Genkit com o Cloud Functions para 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 implantar o 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 ).

    2. Instale a CLI do Firebase.

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

    Fazer upgrade do projeto para o plano Blaze, que é necessário para implantar o Cloud 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. Siga uma destas etapas a seguir, dependendo do provedor de modelos escolhido:

    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 à API Gemini usando o Google AI Studio.

    3. Armazene a chave de API no Cloud Secret Manager:

      firebase functions:secrets:set GOOGLE_GENAI_API_KEY
      

      Essa etapa é importante para evitar o vazamento acidental da chave de API que concede acesso a um serviço potencialmente limitado.

      Consulte Armazenar e acessar informações de configuração confidenciais. para mais informações sobre como gerenciar secrets.

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

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

      Em seguida, na definição do fluxo, declare que a função do Cloud precisa acesso a este valor de secret:

      export const menuSuggestionFlow = onFlow(
        {
          name: "menuSuggestionFlow",
          // ...
          httpsOptions: {
            secrets: [googleAIapiKey],  // Add this line.
          },
        },
        async (subject) => {
          // ...
        }
      );
      

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

    Gemini (Vertex AI)

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

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

    O único secret que você precisa configurar para este tutorial é para o provedor de modelo, mas em geral, você precisa fazer algo semelhante para cada serviço que seu fluxo usa.

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

    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 essa vai fazer para este tutorial.

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

    1. Disponibilizar as credenciais da API localmente. Siga um destes procedimentos: dependendo do provedor de modelo escolhido:

      Gemini (IA do Google)

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

      export GOOGLE_GENAI_API_KEY=<your API key>
      

      Gemini (Vertex AI)

      Defina algumas variáveis de ambiente adicionais e use o Ferramenta gcloud para configurar Application Default Credentials:

      export GCLOUD_PROJECT=<your project ID>
      export GCLOUD_LOCATION=us-central1
      gcloud auth application-default login
      
    2. Inicie a interface:

      cd $PROJECT_ROOT/functions
      genkit start
      
    3. 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. Mas você não poderá acessar o endpoint implantado com curl ou semelhante, devido à política de autorização. Vá para a próxima seção para aprender a proteger acessar o fluxo.

Teste o fluxo implantado

É fundamental que cada fluxo implantado defina uma política de autorização. Sem Primeiro, seus fluxos de IA generativa potencialmente caros seriam invocáveis pelo ninguém.

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 usuários do seu app com endereços de e-mail verificados. No lado do cliente, você precisa defina o cabeçalho Authorization: Bearer como um token de ID do Firebase que satisfaça a sua política. Os SDKs do cliente do Cloud Functions fornecem função chamável e métodos que automatizam isso.

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

  1. Na Configurações do projeto do console do Firebase, adicione um novo app da Web, selecione a opção para também configure o Hosting.

  2. Na Autenticação do console do Firebase, ative o provedor do Google, que você usará neste exemplo.

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

    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 requer que você faça login com uma Conta do Google. Depois disso, você pode iniciar solicitações de endpoint da Web.

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 "Inspect" e alterne a opção "Dev/Prod" interruptor. Quando alternado para "prod" ele carrega traces do Firestore.