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 o Cloud Functions de segunda geração 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ê adicionará a Configuração remota a uma função semelhante a um chatbot que usa o modelo do Gemini para responder às perguntas dos usuários. A Configuração remota gerenciará as entradas da API Gemini (incluindo um prompt que será anexado a consultas de usuários recebidas) e poderá atualizar essas entradas sob demanda no Console do Firebase. Você também usará o Pacote de emuladores locais do Firebase para testar e depurar a função e, depois de verificar se ela funciona, fará a implantação e o teste no Google Cloud.

Pré-requisitos

Este guia pressupõe que você esteja familiarizado com o uso do 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: criar um novo projeto do Firebase (e o projeto subjacente do Google Cloud automaticamente) inserindo um novo nome de projeto na primeira etapa do fluxo de trabalho "Criar projeto".
    • Opção 2: selecione o nome do projeto do Google Cloud no menu suspenso na primeira etapa do fluxo de trabalho "Criar projeto" para adicionar o Firebase a um projeto atual do Google Cloud.

  3. Quando solicitado, você não precisa 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 o 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 Node Version Manager.

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

    npm install -g firebase-tools@latest

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

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

  3. Instale firebase-functions e firebase-admin e use --save para salvá-los no package.json:

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

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

Implementação

Siga estas etapas para criar, testar e implantar o Cloud Functions de 2a geração com a Configuração remota e a Vertex AI:

  1. Ativar 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 e teste a função 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 seu projeto.
  2. No campo Pesquisar na parte de cima do console, digite Vertex AI e aguarde até que Vertex AI apareça como resultado.
  3. Selecione Vertex AI. O painel da Vertex AI é 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ê precisará adicionar ou vincular uma conta do Cloud Billing. Depois de ativar uma conta de faturamento, volte ao painel da 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 navegue até 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 solicitado a 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. Dentro dele, você encontrará um arquivo index.js que será usado para criar sua função, um diretório node_modules que contém as dependências da 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 abaixo e usando --save para garantir que ele seja salvo no arquivo package.json:

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

O arquivo functions/package.json agora terá a seguinte aparência, 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. Além disso, verifique se a versão do mecanismo do nó corresponde à versão instalada do Node.js e à versão que você executa no Google Cloud. Por exemplo, se a estrofe engines em package.json estiver configurada como Node versão 18 e você estiver usando o Node.js 20, atualize o arquivo para usar 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ê 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 e administrador 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 é exibida.
  3. Clique em Adicionar outro papel e selecione Leitor da Configuração remota.
  4. Clique em Adicionar outro papel e selecione Desenvolvedor do 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. Clique em 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ê 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 SDK Admin e a API Vertex AI Gemini, configura parâmetros padrão usando a Configuração remota, busca os parâmetros mais recentes desse recurso, processa a entrada do usuário e transmite uma resposta de volta para o 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 atual, adicione o SDK Admin, a Configuração remota e o SDK da Vertex AI. Em seguida, 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 sua função vai usar se não conseguir se conectar ao servidor da Configuração remota. Esta solução configura textModel, generationConfig, safetySettings, textPrompt e location como parâmetros da Configuração remota que correspondem aos parâmetros dela que serão definidos 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ê acessa ou não a API Vertex AI Gemini (neste exemplo, um parâmetro chamado vertex_enabled). Essa configuração pode ser útil ao testar sua função. Nos snippets de código a seguir, esse valor é definido como false, que vai pular o uso da Vertex AI enquanto você testa a implantação básica da função. Definir como true vai invocar a API Vertex AI Gemini.

    // 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 sua 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, expanda Executar e selecione Configuração remota.

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

    • Se esta for 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.
    • Se esta não for a primeira vez que você usa modelos de servidor da Configuração remota, 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 para usar no seu código, consulte Versões e ciclos de vida de modelo ou Nomes de modelos disponíveis.     		String gemini-1.5-pro-preview-0514
    prompt Prompt 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 a serem enviados 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 a Vertex AI. Booleano true

  4. Quando terminar de adicionar parâmetros, verifique novamente se eles estão corretos e se os tipos de dados estão corretos. Em seguida, 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 permissões do IAM para a conta de serviço do SDK Admin e salvar a chave. Em seguida, no diretório pai do diretório functions, implante sua 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 volte à página de registros do emulador do Firebase ou ao console e verifique se há erros ou avisos.

  5. Tente enviar algumas entradas do usuário observando que, como is_vertex_enabled está configurado no modelo de servidor da Configuração remota, isso precisa acessar o Gemini pela API Vertex AI Gemini 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, você estará 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 se a política da organização não as restringir. Durante o teste 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 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 necessários para executar a função e interagir com a Configuração remota e a API Vertex AI Gemini, use-a para executar a função. Para fazer isso, você precisa criar tokens para a conta a partir da sua conta de usuário.

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

  1. No console do Google Cloud, ative a API IAM Service Account Credentials.
  2. Atribua o papel Criador de token da conta de serviço à conta de usuário: no Console do Google Cloud, abra IAM e administrador > IAM, selecione sua conta de usuário e 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 Representação 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 Gatilho > Editar e expanda Configurações de ambiente de execução, build, conexões e segurança.

  6. Na guia Ambiente de execução, altere a conta de serviço de 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 a partir da linha de comando, você precisará se autenticar no serviço Cloud Functions e conseguir um token de autenticação válido.

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

  1. Se ela ainda não estiver instalada no computador, instale a CLI gcloud conforme descrito em Instalar a CLI gcloud.

  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, publicá-las e testar opções diferentes.

Próximas etapas