Genkit com o Cloud Functions do Firebase

O Firebase Genkit inclui um plug-in que ajuda a implantar seus fluxos no Firebase Cloud Functions. Esta página, como exemplo, orienta você no processo de implantação do fluxo de amostra padrão no Firebase.

Implantar um fluxo como uma função do Cloud

  1. Instale as ferramentas necessárias:

    1. Verifique se você está usando o Node.js versão 20 ou mais recente (execute node --version para verificar).

    2. Instale a CLI do Firebase.

  2. Crie um novo projeto do Firebase usando o Console do Firebase ou escolha um projeto existente.

    Faça upgrade do projeto para o plano Blaze, que é necessário para implantar o Cloud Functions.

  3. Faça login com a CLI do Firebase:

    firebase login
firebase login --reauth # alternative, if necessary
firebase login --no-localhost # if running in a remote shell

  4. Crie um novo diretório do projeto:

    export PROJECT_ROOT=~/tmp/genkit-firebase-project1
mkdir -p $PROJECT_ROOT

  5. Inicialize um projeto do Firebase com o Genkit na pasta:

    cd $PROJECT_ROOT
firebase init genkit
    • Selecione o projeto que você criou anteriormente.
    • Selecione o provedor do modelo que você quer usar.

    Aceite os padrões das outras solicitações. A ferramenta genkit criará alguns arquivos de origem de amostra para você começar a desenvolver seus próprios fluxos de IA. No entanto, no restante deste tutorial, você apenas implantará o fluxo de amostra.

  6. Disponibilize as credenciais da API para sua função do Cloud. Dependendo do provedor de modelo escolhido, siga um destes procedimentos:

    Gemini (IA do Google)

    1. Verifique se a IA do Google está disponível na sua região.

    2. Gere uma chave de API para a API Gemini usando o Google AI Studio.

    3. Defina a variável de ambiente GOOGLE_GENAI_API_KEY como sua chave:

      export GOOGLE_GENAI_API_KEY=<your API key>

    4. Edite src/index.ts e adicione o seguinte após as importações atuais:

    import {defineSecret} from "firebase-functions/params";
defineSecret("GOOGLE_GENAI_API_KEY");

    Agora, quando você implantar essa função, sua chave de API será armazenada no Cloud Secret Manager e disponível no ambiente do Cloud Functions.

    Gemini (Vertex AI)

    1. No console do Cloud, ative a API Vertex AI para seu projeto do Firebase.

    2. Na página IAM, confira se a conta de serviço padrão do Compute recebeu o papel Usuário da Vertex AI.

    3. Opcional: se você quiser executar o fluxo localmente, como na próxima etapa, defina mais algumas variáveis de ambiente e use a ferramenta gcloud para configurar o Application Default Credentials:

      export GCLOUD_PROJECT=<your project ID>
export GCLOUD_LOCATION=us-central1
gcloud auth application-default login

    A única chave secreta que você precisa configurar neste tutorial é para o provedor de modelos, mas, em geral, é necessário fazer algo semelhante para cada serviço usado pelo fluxo.

  7. Se você acessar o fluxo de um app da Web (o que será feito na próxima seção), defina uma política de CORS no parâmetro httpsOptions:

    export const menuSuggestionFlow = onFlow(
  {
    name: "menuSuggestionFlow",
    // ...
    httpsOptions: {cors: true}, // Add this line.
  },
  async (subject) => {
    // ...
  }
);

    É provável que você queira uma política mais restritiva para apps de produção, mas isso é suficiente para este tutorial.

  8. Opcional: teste o fluxo na interface do desenvolvedor:

    1. Inicie a interface:

      cd $PROJECT_ROOT/functions
genkit start

    2. Na interface do desenvolvedor (http://localhost:4000/), execute o fluxo:

      1. Clique em menuSuggestionFlow.

      2. Na guia Inserir JSON, forneça um assunto para o modelo:

        "AI app developers"

      3. Na guia Auth JSON, forneça um objeto de autenticação simulado:

        {
  "uid": 0,
  "email_verified": true
}

      4. Clique em Executar.

  9. Se tudo estiver funcionando como esperado até agora, você poderá implantar o fluxo:

    cd $PROJECT_ROOT
firebase deploy --only functions

Você implantou o fluxo como uma função do Cloud. No entanto, não será possível acessar o endpoint implantado com curl ou semelhante, devido à política de autorização do fluxo. Continue na próxima seção para saber como acessar o fluxo com segurança.

Teste o fluxo implantado

É fundamental que cada fluxo implantado defina uma política de autorização. Sem um, seus fluxos de IA generativa potencialmente caros poderiam ser invocados por qualquer pessoa.

O fluxo de amostra padrão tem uma política de autorização como a seguinte:

firebaseAuth((user) => {
  if (!user.email_verified) {
    throw new Error('Verified email required to run flow');
  }
});

Esta política usa o auxiliar firebaseAuth() para permitir o acesso apenas a usuários registrados do app com endereços de e-mail verificados. No lado do cliente, você precisa definir o cabeçalho Authorization: Bearer como um token de ID do Firebase que satisfaça sua política. Os SDKs do cliente do Cloud Functions fornecem métodos de função chamável que automatizam isso.

Para testar o endpoint de fluxo, implante o seguinte exemplo mínimo de app da Web:

  1. Na seção Configurações do projeto do Console do Firebase, adicione um novo app da Web, selecionando a opção para também configurar o Hosting.

  2. Na seção Autenticação do Console do Firebase, ative o provedor do Google, que você vai usar neste exemplo.

  3. No diretório do projeto, configure o Firebase Hosting, em que você implantará o app de amostra:

    cd $PROJECT_ROOT
firebase init hosting

    Aceite os padrões de todas as solicitações.

  4. Substitua public/index.html pelo seguinte:

    <!doctype html>
<html>
  <head>
    <title>Genkit demo</title>
  </head>
  <body>
    <div id="signin" hidden>
      <button id="signinBtn">Sign in with Google</button>
    </div>
    <div id="callGenkit" hidden>
      Subject: <input type="text" id="subject" />
      <button id="suggestMenuItem">Suggest a menu theme</button>
      <p id="menuItem"></p>
    </div>
    <script type="module">
      import { initializeApp } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-app.js';
      import {
        getAuth,
        onAuthStateChanged,
        GoogleAuthProvider,
        signInWithPopup,
      } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-auth.js';
      import {
        getFunctions,
        httpsCallable,
      } from 'https://www.gstatic.com/firebasejs/10.10.0/firebase-functions.js';

      const firebaseConfig = await fetch('/__/firebase/init.json');
      initializeApp(await firebaseConfig.json());

      async function generateMenuItem() {
        const menuSuggestionFlow = httpsCallable(
          getFunctions(),
          'menuSuggestionFlow'
        );
        const subject = document.querySelector('#subject').value;
        const response = await menuSuggestionFlow(subject);
        document.querySelector('#menuItem').innerText = response.data;
      }

      function signIn() {
        signInWithPopup(getAuth(), new GoogleAuthProvider());
      }

      document
        .querySelector('#signinBtn')
        .addEventListener('click', signIn);
      document
        .querySelector('#suggestMenuItem')
        .addEventListener('click', generateMenuItem);

      const signinEl = document.querySelector('#signin');
      const genkitEl = document.querySelector('#callGenkit');

      onAuthStateChanged(getAuth(), (user) => {
        if (!user) {
          signinEl.hidden = false;
          genkitEl.hidden = true;
        } else {
          signinEl.hidden = true;
          genkitEl.hidden = false;
        }
      });
    </script>
  </body>
</html>

  5. Implante o app da Web e a função do Cloud:

    cd $PROJECT_ROOT
firebase deploy

Abra o app da Web acessando o URL impresso pelo comando deploy. O app exige que você faça login com uma Conta do Google para iniciar solicitações de endpoint.

Como desenvolver usando o Pacote de emuladores locais do Firebase

O Firebase oferece um pacote de emuladores para desenvolvimento local que pode ser usado com o Genkit.

Para usar o Genkit com o Pacote de emuladores do Firebase, inicie os emuladores do Firebase da seguinte maneira:

GENKIT_ENV=dev firebase emulators:start --inspect-functions

Isso vai executar o código no emulador e executar o framework Genkit no modo de desenvolvimento, que inicia e expõe a API Genkit Reflexão (mas não a interface de desenvolvimento).

Em seguida, inicie a interface do desenvolvedor do Genkit com a opção --attach para conectá-la ao código em execução no emulador do Firebase:

genkit start --attach http://localhost:3100 --port 4001

Para ver os traces do Firestore na interface de desenvolvimento, acesse a guia "Inspecionar" e ative a opção "Dev/Prod". Quando a opção for "prod", os rastros do Firestore serão carregados.