Usar a Configuração remota do lado do servidor com o Cloud Functions e a Vertex AI

Este guia descreve como começar a usar a 2ª geração Cloud Functions com Remote Config do lado do servidor para fazer chamadas para o Vertex AI Gemini API.

Neste tutorial, você vai adicionar Remote Config a uma função semelhante a um chatbot que usa um modelo Gemini para responder às perguntas dos usuários. A Remote Config vai gerenciar as entradas da Gemini API (incluindo um comando anexado às consultas recebidas do usuário), e você pode atualizar essas entradas sob demanda no console Firebase. Você também vai usar o Firebase Local Emulator Suite para testar e depurar a função e, depois de verificar se ela funciona, você vai implantar e testá-lo em Google Cloud.

Pré-requisitos

Neste guia, pressupomos que você já sabe usar o JavaScript para desenvolver aplicativos.

Configurar um projeto do Firebase

Se você ainda não tiver um projeto do Firebase:

  1. Faça login no console do Firebase.

  2. Clique em Criar projeto e use uma das seguintes opções:

    • Opção 1: crie um novo projeto do Firebase (que vai ser um projeto do Google Cloud automaticamente) ao inserir um novo nome na primeira etapa do fluxo de trabalho "Criar projeto".
    • Opção 2: "Adicionar o Firebase" a um projeto Google Cloud existente selecionando o nome do projeto Google Cloud no menu suspenso da primeira etapa do fluxo de trabalho "Criar projeto".

  3. Quando solicitado, você não vai precisar configurar o Google Analytics para usar essa solução.

  4. Continue seguindo as instruções na tela para criar o projeto.

Se você já tiver um projeto do Firebase:

Prossiga para Configurar o ambiente de desenvolvimento.

Configurar seu ambiente de desenvolvimento

Você vai precisar de um ambiente do Node.js para criar funções e da CLI Firebase para implantar funções no ambiente de execução do Cloud Functions.

  1. Instale o Node.js e o npm.

    Para instalar o Node.js e npm, recomendamos o uso do Gerenciador de versões de nós:

  2. Instale a CLI do Firebase usando seu método preferido. Por exemplo, para instalar a CLI usando npm, execute este comando:

    npm install -g firebase-tools@latest

    Essa ação instala o comando firebase, disponível globalmente. Se o comando falhar, talvez seja necessário alterar as permissões do NPM.

    Para atualizar para a versão mais recente, de firebase-tools execute novamente o mesmo comando.

  3. Instale firebase-functions e firebase-admin e use --save para salvar no package.json:

    npm install firebase-functions@latest firebase-admin@latest --save

Agora está tudo pronto para prosseguir para a implementação da solução.

Implementação

Siga estas etapas para criar, testar e implantar a 2ª geração Cloud Functions com Remote Config e Vertex AI:

  1. Ative as APIs recomendadas da Vertex AI no console Google Cloud.
  2. Inicialize seu projeto e instale as dependências do Node.
  3. Configure as permissões do IAM para sua conta de serviço Admin SDK e salve a chave.
  4. Crie a função.
  5. Crie um modelo de Remote Config específico do servidor.
  6. Implante sua função e teste-a no Firebase Local Emulator Suite.
  7. Implante a função no Google Cloud.

Etapa 1: ativar as APIs recomendadas do Vertex AI no console do Google Cloud

  1. Abra o console do Google Cloud e, quando solicitado, selecione o projeto.
  2. No campo Pesquisar na parte de cima do console, digite Vertex AI e aguarde a exibição de Vertex AI como resultado.
  3. Selecione Vertex AI. O painel Vertex AI será exibido.

  4. Selecione Ativar todas as APIs recomendadas.

    A ativação da API pode levar alguns instantes para ser concluída. Mantenha a página ativa e aberta até que a ativação seja concluída.

  5. Se o faturamento não estiver ativado, vamos pedir para você adicionar ou vincular um Cloud Billing. Depois de ativar uma conta de faturamento, volte para Vertex AI e verifique se todas as APIs recomendadas estão ativadas.

Etapa 2: inicializar o projeto e instalar dependências do nó

  1. Abra um terminal no computador e acesse o diretório em que você planeja criar a função.

  2. Faça login no Firebase:

    firebase login

  3. Execute o seguinte comando para inicializar Cloud Functions for Firebase:

    firebase init functions

  4. Selecione Usar um projeto existente e especifique o ID do projeto.

  5. Quando for necessário selecionar a linguagem a ser usada, escolha JavaScript e pressione Enter.

  6. Para todas as outras opções, selecione os padrões.

    Um diretório functions será criado no diretório atual. Nele, você encontra um arquivo index.js que vai usar para criar sua função, um diretório node_modules que contém as dependências da sua função e um arquivo package.json que contém as dependências do pacote.

  7. Adicione os pacotes Admin SDK e Vertex AI executando os comandos a seguir, usando --save para garantir que fique salvo no seu arquivo package.json:

    cd functions
npm install firebase-admin@latest @google-cloud/vertexai --save

O arquivo functions/package.json ficará como o exemplo a seguir, com as versões mais recentes especificadas:

  {
    "name": "functions",
    "description": "Cloud Functions for Firebase",
    "scripts": {
      "serve": "firebase emulators:start --only functions",
      "shell": "firebase functions:shell",
      "start": "npm run shell",
      "deploy": "firebase deploy --only functions",
      "logs": "firebase functions:log"
    },
    "engines": {
      "node": "20"
    },
    "main": "index.js",
    "dependencies": {
      "@google-cloud/vertexai": "^1.1.0",
      "firebase-admin": "^12.1.0",
      "firebase-functions": "^5.0.0"
    },
    "devDependencies": {
      "firebase-functions-test": "^3.1.0"
    },
    "private": true
  }

Se estiver usando o ESLint, você verá uma estrofe que o inclui. Verifique também se a versão do mecanismo do nó corresponde à versão instalada do Node.js e à versão que será executada no Google Cloud. Por exemplo, se a estrofe engines em package.json está configurada como Node versão 18 e se você estiver usando o Node.js 20, atualize o arquivo para usar a versão 20:

  "engines": {
    "node": "20"
  },

Etapa 3: configurar as permissões do IAM para a conta de serviço Admin SDK e salvar a chave

Nesta solução, você vai usar a conta de serviço Admin SDK do Firebase para executar sua função.

  1. No console do Google Cloud, abra o IAM e página "Administrador" e localize a conta de serviço Admin SDK (chamada firebase-adminsdk).
  2. Selecione a conta e clique em Editar principal. A página de acesso para editar será exibida.
  3. Clique em Adicionar outro papel e selecione Remote Config Leitor.
  4. Clique em Adicionar outro papel e selecione Desenvolvedor da AI Platform.
  5. Clique em Adicionar outro papel e selecione Usuário Vertex AI.
  6. Clique em Adicionar outro papel e selecione Invocador do Cloud Run.
  7. Clique em Salvar.

Em seguida, exporte as credenciais da conta de serviço Admin SDK e salve-as na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. No console do Google Cloud, abra a página Credenciais.
  2. Clique na conta de serviço do Admin SDK para abrir a página Detalhes.
  3. Clique em Chaves.
  4. Selecione Adicionar chave > Criar nova chave.
  5. Verifique se JSON está selecionado como o Tipo de chave e clique em Criar.
  6. Faça o download da chave em um local seguro no seu computador.

  7. No seu terminal, exporte a chave como uma variável de ambiente:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Etapa 4: criar a função

Nesta etapa, você vai criar uma função que processa a entrada do usuário e gera respostas com tecnologia de IA. Você vai combinar vários snippets de código para criar uma função abrangente que inicializa o Admin SDK e Vertex AI Gemini API, configura parâmetros padrão usando Remote Config, busca os parâmetros Remote Config mais recentes, processos entrada do usuário e transmite uma resposta de volta ao usuário.

  1. Na base de código, abra functions/index.js em um editor de texto ou ambiente de desenvolvimento integrado.

  2. Exclua o conteúdo e adicione o SDK Admin SDK, Remote Config e Vertex AI e inicialize o app colando o seguinte código no arquivo:

    const { onRequest } = require("firebase-functions/https");
const logger = require("firebase-functions/logger");

const { initializeApp } = require("firebase-admin/app");
const { VertexAI } = require('@google-cloud/vertexai');
const { getRemoteConfig } = require("firebase-admin/remote-config");

// Set and check environment variables.
const project = process.env.GCLOUD_PROJECT;

// Initialize Firebase.
const app = initializeApp();
    index.js

  3. Configure os valores padrão que a função usará se não for possível se conectar a ela no servidor Remote Config. Esta solução configura textModel, generationConfig, safetySettings, textPrompt e location como parâmetros Remote Config que correspondem a parâmetros Remote Config que serão configurados posteriormente neste guia. Para mais informações sobre esses parâmetros, consulte Cliente Node.js da Vertex AI

    Também é possível configurar um parâmetro para controlar se você acessa ou não o Vertex AI Gemini API. Neste exemplo, um parâmetro chamado vertex_enabled). Essa configuração pode ser útil ao testar sua função. Nos snippets de código abaixo, esse valor é definido como false, que será ignorado usando Vertex AI enquanto você testa a implantação da função básica. Definindo como true vai invocar a Vertex AI Gemini API.

    // Define default (fallback) parameter values for Remote Config.
const defaultConfig = {

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-002",
  generation_config: [{
    "stopSequences": [], "temperature": 0.7,
    "maxOutputTokens": 64, "topP": 0.1, "topK": 20
  }],
  prompt: "I'm a developer who wants to learn about Firebase and you are a \
    helpful assistant who knows everything there is to know about Firebase!",
  safety_settings: [{
    "category":
      "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT",
    "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE"
  }],
  location: 'us-central1',

  // Disable Vertex AI Gemini API access for testing.
  vertex_enabled: false
};
    index.js

  4. Criar a função e configurar Remote Config do lado do servidor:

    // Export the function.
exports.generateWithVertex = onRequest(async (request, response) => {

  try {

    // Set up Remote Config.
    const rc = getRemoteConfig(app);

    // Get the Remote Config template and assign default values.
    const template = await rc.getServerTemplate({
      defaultConfig: defaultConfig
    });

    // Add the template evaluation to a constant.
    const config = template.evaluate();

    // Obtain values from Remote Config.
    const textModel = config.getString("model_name") ||
        defaultConfig.model_name;
    const textPrompt = config.getString("prompt") || defaultConfig.prompt;
    const generationConfig = config.getString("generation_config") ||
        defaultConfig.generation_config;
    const safetySettings = config.getString("safety_settings") ||
        defaultConfig.safety_settings;
    const location = config.getString("location") ||
        defaultConfig.location;
    const vertexEnabled = config.getBoolean("is_vertex_enabled") ||
        defaultConfig.vertex_enabled;
    index.js

  5. Configure Vertex AI e adicione a lógica de chat e resposta:

      // Allow user input.
  const userInput = request.query.prompt || '';

  // Instantiate Vertex AI.
    const vertex_ai = new VertexAI({ project: project, location: location });
    const generativeModel = vertex_ai.getGenerativeModel({
      model: textModel,
      safety_settings: safetySettings,
      generation_config: generationConfig,
    });

    // Combine prompt from Remote Config with optional user input.
    const chatInput = textPrompt + " " + userInput;

    if (!chatInput) {
      return res.status(400).send('Missing text prompt');
    }
    // If vertexEnabled isn't true, do not send queries to Vertex AI.
    if (vertexEnabled !== true) {
      response.status(200).send({
        message: "Vertex AI call skipped. Vertex is not enabled."
      });
      return;
    }

    logger.log("\nRunning with model ", textModel, ", prompt: ", textPrompt,
      ", generationConfig: ", generationConfig, ", safetySettings: ",
      safetySettings, " in ", location, "\n");

    const result = await generativeModel.generateContentStream(chatInput); 
    response.writeHead(200, { 'Content-Type': 'text/plain' });

    for await (const item of result.stream) {
      const chunk = item.candidates[0].content.parts[0].text;
      logger.log("Received chunk:", chunk);
      response.write(chunk);
    }

    response.end();

  } catch (error) {
    logger.error(error);
    response.status(500).send('Internal server error');
  }
});
    index.js

  6. Salve e feche o arquivo.

Etapa 5: criar um modelo Remote Config específico do servidor

Em seguida, crie um modelo Remote Config do lado do servidor e configure os parâmetros e valores para usar na função. Para criar um modelo Remote Config específico de servidor:

  1. Abra o console Firebase e, no menu de navegação, abra Run e selecione Remote Config.

  2. Selecione Servidor no seletor Cliente/Servidor na parte de cima da Remote Config.

    • Se esta é a primeira vez que você usa Remote Config ou modelos de servidor, clique em Criar configuração. O painel Criar seu primeiro parâmetro do lado do servidor será exibido.
    • Se esta não for a primeira vez que você usa modelos de servidor Remote Config, clique em Adicionar parâmetro.

  3. Defina os seguintes parâmetros Remote Config:

    Nome do parâmetro Descrição Tipo Valor padrão
    model_name Nome do modelo
    Para acessar listas atualizadas de nomes de modelos e usar no seu código, acesse Versões e ciclos de vida do modelo ou Nomes de modelos disponíveis.     		String gemini-2.0-flash
    prompt Comando para adição ao início da consulta do usuário. String I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
    generation_config Parâmetros para enviar ao modelo. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Configurações de segurança para Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Local para executar o serviço e o modelo Vertex AI. String us-central1
    is_vertex_enabled Parâmetro opcional que controla se as consultas são enviadas para Vertex AI. Booleano true

  4. Quando terminar de adicionar parâmetros, verifique seus parâmetros e se os tipos de dados estão corretos e clique em Publicar alterações.

Etapa 6: implantar a função e testá-la no Firebase Local Emulator Suite

Agora está tudo pronto para implantar e testar a função localmente com o Firebase Local Emulator Suite.

  1. Verifique se você definiu GOOGLE_APPLICATION_CREDENTIALS como uma variável de ambiente conforme descrito na Etapa 3: configurar as permissões do IAM para a conta de serviço do Admin SDK e salvar a chave. Então, no diretório pai do diretório functions, implante a função no emulador do Firebase:

    firebase emulators:start --project PROJECT_ID --only functions

  2. Abra a página de registros do emulador. Isso vai mostrar que a função foi carregada.

  3. Acesse a função executando o seguinte comando, em que PROJECT_ID é o ID do projeto e LOCATION é a região em que você implantou a função (por exemplo, us-central1):

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. Aguarde uma resposta e retorne à página de registros do emulador do Firebase ou ao seu console e verifique se há erros ou avisos.

  5. Tente enviar alguma entrada do usuário, observando que, como is_vertex_enabled está configurado no modelo de servidor Remote Config, ele acessa o modelo Gemini pelo Vertex AI Gemini API e que isso pode gerar cobranças:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. Faça alterações no modelo de servidor Remote Config no console Firebase e acesse novamente a função para observar as alterações.

Etapa 7: implantar a função no Google Cloud

Depois de testar e verificar a função, estará tudo pronto para implantar no Google Cloud e testar a função ativa.

Implantar a função

Implante a função usando a CLI do Firebase:

firebase deploy --only functions

Bloquear o acesso não autenticado à função

Quando as funções são implantadas com o Firebase, as invocações não autenticadas são permitidas por padrão, caso a política da organização não restrinja esse processo. Durante os testes e antes de proteger com o App Check, recomendamos bloquear o acesso não autenticado.

Para bloquear o acesso não autenticado à função:

  1. No console do Google Cloud, abra o Cloud Run:

  2. Clique em generateWithVertex e, em seguida, na guia Segurança.

  3. Ative a Autenticação necessária e clique em Salvar.

Configure sua conta de usuário para usar as credenciais da conta de serviço Admin SDK

Como a conta de serviço Admin SDK tem todos os papéis e permissões necessários para executar a função e interagir com o Remote Config e o Vertex AI Gemini API, use-a para executar a função. Para isso, você precisa criar tokens para a conta usando sua conta de usuário.

As etapas a seguir descrevem como configurar sua conta de usuário e a função para execução com os privilégios da conta de serviço do Admin SDK.

  1. No console do Google Cloud, ative a API Service Account Credentials do IAM.
  2. Atribua o papel de Criador de token da conta de serviço à sua conta de usuário: no console do Google Cloud, abra IAM & Admin > IAM, selecione a conta de usuário e, em seguida, clique em Editar principal > Adicionar outro papel.

  3. Selecione Criador de token de conta de serviço e clique em Salvar.

    Para informações mais detalhadas sobre a representação de uma conta de serviço, consulte Identidade temporária de conta de serviço na documentação do Google Cloud.

  4. Abra a página Cloud Functions do console do Google Cloud e clique na função generateWithVertex na lista generateWithVertex.

  5. Selecione Acionador > Editar e abra Ambiente de execução, build, conexões e configurações de segurança.

  6. Na guia Ambiente de execução, mude a conta de serviço do ambiente de execução para a conta do SDK Admin.

  7. Clique em Próxima e em Implantar.

Configurar a CLI gcloud

Para executar e testar a função com segurança na linha de comando, é necessário se autenticar no serviço do Cloud Functions e conseguir um token de autenticação válido.

Para ativar a geração de tokens, instale e configure a gcloud CLI.

  1. Se ainda não estiver instalada em seu computador, instale a gcloud CLI como descrito em Instalar a gcloud CLI.

  2. Receba credenciais de acesso para sua conta do Google Cloud:

    gcloud auth login

  3. Defina o ID do projeto na gcloud:

    gcloud config set project PROJECT_ID

Testar a função

Agora está tudo pronto para testar a função em Google Cloud. Para testar a função, execute o seguinte comando:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

Tente novamente com dados fornecidos pelo usuário:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
 -H "Authorization: bearer $(gcloud auth print-identity-token)" \
 -H "Content-Type: application/json"

Agora você pode fazer mudanças no seu modelo de servidor do Remote Config, publicar essas mudanças e testar opções diferentes.

Próximas etapas