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

Neste guia, descrevemos como começar a usar a 2ª geração do Cloud Functions com a Configuração remota do lado do servidor para fazer chamadas do lado do servidor para a API Vertex AI Gemini.

Neste tutorial, você vai adicionar a Configuração remota a uma função semelhante ao chatbot que usa o modelo do Gemini para responder às perguntas dos usuários. A Configuração remota vai gerenciar as entradas da API Gemini (incluindo um comando anexado às consultas recebidas do usuário), e você pode atualizar essas entradas sob demanda no Console do Firebase. Você também vai usar o Pacote de emuladores locais do Firebase para testar e depurar a função e, depois de verificar se ela funciona, vai implantar e e testá-las no 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 do Google Cloud selecionando o nome do seu projeto do 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, além da CLI do Firebase para implantá-las no ambiente de execução do Cloud Functions.

  1. Instale o Node.js e o npm.

    Para instalar o Node.js e o 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 do Cloud Functions com a Configuração remota e Vertex AI:

  1. Ative as APIs recomendadas da Vertex AI no console do 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 do SDK Admin e salve a chave.
  4. Crie a função.
  5. Crie um modelo da Configuração remota específico do servidor.
  6. Implante a função e teste-a no Pacote de emuladores locais do Firebase.
  7. Implante a função no Google Cloud.

Etapa 1: ativar as APIs recomendadas da 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 da Vertex AI como resultado.
  3. Selecione Vertex AI. O painel da 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, você vai precisar adicionar ou vincular uma conta do Cloud Billing. Depois de ativar uma conta de faturamento, volte para a 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 o Cloud Functions para 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 o SDK Admin e os pacotes da 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 do SDK Admin e salvar a chave

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

  1. No console do Google Cloud, abra a página IAM & Admin e localize a conta de serviço do SDK Admin (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 Leitor da Configuração remota.
  4. Clique em Adicionar outro papel e selecione Desenvolvedor da AI Platform.
  5. Clique em Adicionar outro papel e selecione Usuário da 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 do SDK Admin 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 SDK Admin 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 a API Gemini da Vertex AI, configura parâmetros padrão usando a Configuração remota, busca os parâmetros e processos mais recentes da Configuração remota, processa a entrada do usuário e transmite uma resposta de volta para ele.

  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. a Configuração remota e o SDK da Vertex AI e inicialize o app colando o seguinte código no arquivo:

    const { onRequest } = require("firebase-functions/v2/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 vai usar se não for possível se conectar a ela o servidor da Configuração remota. Essa solução configura textModel, generationConfig, safetySettings, textPrompt e location como parâmetros da Configuração remota que correspondem aos parâmetros da Configuração remota que você vai configurar mais adiante 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ê pode ou não acessar a API Gemini da Vertex AI. Neste exemplo, um parâmetro chamado vertex_enabled. Essa configuração pode ser útil ao testar a função. Nos snippets de código abaixo, esse valor é definido como false, que será ignorado usando a Vertex AI enquanto você testa a implantação da função básica. Definir isso como true vai invocar a API Gemini da Vertex AI.

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

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-preview-0514",
  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. Crie a função e configure a Configuração remota 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 a 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 da Configuração remota específico do servidor

Em seguida, crie um modelo da Configuração remota do lado do servidor e defina os parâmetros e valores para usar na função. Para criar um modelo da Configuração remota específico do servidor:

  1. Abra o console do Firebase e, no menu de navegação, abra Executar e selecione Configuração remota.

  2. Selecione Servidor no seletor Cliente/servidor na parte de cima da página da Configuração remota.

    • Se esta é a primeira vez que você usa a Configuração remota ou modelos de servidor, clique em Criar configuração. O painel Criar seu primeiro parâmetro do lado do servidor será exibido.
    • Caso não esteja usando modelos de servidor da Configuração remota pela primeira vez, clique em Adicionar parâmetro.

  3. Defina os seguintes parâmetros da Configuração remota:

    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-1.5-pro-preview-0514
    prompt Comando para preceder à 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 da 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 da 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 e testar a função no Pacote de emuladores locais do Firebase

Agora está tudo pronto para implantar e testar a função localmente com o Pacote de emuladores locais do Firebase.

  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 SDK Admin 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 porque is_vertex_enabled está configurado no seu modelo de servidor da Configuração remota, ele acessa o Gemini usando a API Gemini da Vertex AI 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 da Configuração remota no console do 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.

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

Como a conta de serviço do SDK Admin tem todos os papéis e permissões para executar a função e interagir com o Configuração remota e a API Gemini da Vertex AI, 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 SDK Admin.

  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, acesse Identidade temporária de conta de serviço na documentação do Google Cloud.

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

  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 no 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 alterações no modelo de servidor da Configuração remota, publicar essas mudanças e testar diferentes opções.

Próximas etapas