Invocar fluxos do Genkit no seu app

O Cloud Functions para Firebase tem um método onCallGenkit que permite criar uma função que pode ser chamada com uma ação do Genkit (um fluxo). Essas funções podem ser chamadas com genkit/beta/client ou os SDKs do cliente do Cloud Functions, que adicionam automaticamente informações de autenticação.

Antes de começar

  • Você precisa conhecer o conceito de fluxos do Genkit e como programá-los. As instruções nesta página pressupõem que você já definiu alguns fluxos que quer implantar.
  • Isso é útil, mas não obrigatório, se você já usou o Cloud Functions para Firebase.

Configurar um projeto do Firebase

  1. Crie um novo projeto do Firebase usando o console do Firebase ou escolha um projeto atual.

  2. Faça upgrade do projeto para o plano Blaze, que é necessário para a implantação de produção do Cloud Functions.

  3. Instale a CLI do Firebase.

  4. 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

  5. Crie um novo diretório do projeto:

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

  6. Inicialize um novo projeto do Firebase no diretório:

    cd $PROJECT_ROOT
firebase init functions

O restante desta página pressupõe que você escolheu escrever suas funções em JavaScript.

Envolver o fluxo em onCallGenkit

Depois de configurar um projeto do Firebase com o Cloud Functions, é possível copiar ou gravar definições de fluxo no diretório functions do projeto. Confira um exemplo de fluxo para demonstrar isso:

const ai = genkit({
  plugins: [googleAI()],
  model: gemini15Flash,
});

const jokeTeller = ai.defineFlow({
  name: "jokeTeller",
  inputSchema: z.string().nullable(),
  outputSchema: z.string(),
  streamSchema: z.string(),
}, async (jokeType = "knock-knock", {sendChunk}) => {
  const prompt = `Tell me a ${jokeType} joke.`;

  // Call the `generateStream()` method to
  // receive the `stream` async iterable.
  const {stream, response: aiResponse} = ai.generateStream(prompt);

  // Send new words of the generative AI response
  // to the client as they are generated.
  for await (const chunk of stream) {
    sendChunk(chunk.text);
  }

  // Return the full generative AI response
  // to clients that may not support streaming.
  return (await aiResponse).text;
},
);
index.js

Para implantar um fluxo como esse, envolva-o com onCallGenkit, disponível em firebase-functions/https. Esse método auxiliar tem todos os recursos de funções chamáveis e oferece suporte automático a respostas de streaming e JSON.

const {onCallGenkit} = require("firebase-functions/v2/https");
exports.tellJoke = onCallGenkit({
  // Bind the Gemini API key secret parameter to the function.
  secrets: [apiKey],
},
// Pass in the genkit flow.
jokeTeller,
);
index.js

Disponibilizar credenciais da API para fluxos implantados

Depois de implantados, os fluxos precisam de uma maneira de se autenticar com todos os serviços remotos em que eles dependem. No mínimo, a maioria dos fluxos precisa de credenciais para acessar o serviço de API de modelo que eles usam.

Para este exemplo, siga um destes procedimentos, dependendo do provedor de modelos escolhido:

Gemini (IA do Google)

  1. Garanta que a IA do Google disponíveis na sua região.

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

  3. Armazene sua 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 medido.

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

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

    const {defineSecret} = require("firebase-functions/params");
// Store the Gemini API key in Cloud Secret Manager.
const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");
    index.js

    Em seguida, na definição da função que pode ser chamada, declare que a função precisa ter acesso a esse valor secreto:

    // Bind the Gemini API key secret parameter to the function.
secrets: [apiKey],
    index.js

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

Gemini (Vertex AI)

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

  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.

(Opcional) Adicionar a aplicação obrigatória do App Check

O Firebase App Check usa atestados nativos para verificar se a API está sendo chamada apenas pelo seu aplicativo. O onCallGenkit oferece suporte à aplicação obrigatória do App Check de forma declarativa.

export const generatePoem = onCallGenkit({
  enforceAppCheck: true,
  // Optional. Makes App Check tokens only usable once. This adds extra security
  // at the expense of slowing down your app to generate a token for every API
  // call
  consumeAppCheckToken: true,
}, generatePoemFlow);

Configurar CORS (Compartilhamento de recursos entre origens)

Use a opção cors para controlar quais origens podem acessar a função.

Por padrão, as funções chamáveis têm o CORS configurado para permitir solicitações de todas as origens. Para permitir algumas solicitações de origem cruzada, mas não todas, transmita uma lista de domínios específicos ou expressões regulares que precisam ser permitidas. Por exemplo:

export const tellJoke = onCallGenkit({
  cors: 'mydomain.com',
}, jokeTeller);

Exemplo completo

Depois de fazer todas as mudanças descritas acima, o fluxo de implantação vai ficar parecido com este exemplo:

const {onCallGenkit} = require("firebase-functions/v2/https");
const {defineSecret} = require("firebase-functions/params");

// Dependencies for Genkit.
const {gemini15Flash, googleAI} = require("@genkit-ai/googleai");
const {genkit, z} = require("genkit");

// Store the Gemini API key in Cloud Secret Manager.
const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");

const ai = genkit({
  plugins: [googleAI()],
  model: gemini15Flash,
});

const jokeTeller = ai.defineFlow({
  name: "jokeTeller",
  inputSchema: z.string().nullable(),
  outputSchema: z.string(),
  streamSchema: z.string(),
}, async (jokeType = "knock-knock", {sendChunk}) => {
  const prompt = `Tell me a ${jokeType} joke.`;

  // Call the `generateStream()` method to
  // receive the `stream` async iterable.
  const {stream, response: aiResponse} = ai.generateStream(prompt);

  // Send new words of the generative AI response
  // to the client as they are generated.
  for await (const chunk of stream) {
    sendChunk(chunk.text);
  }

  // Return the full generative AI response
  // to clients that may not support streaming.
  return (await aiResponse).text;
},
);

exports.tellJoke = onCallGenkit({
  // Bind the Gemini API key secret parameter to the function.
  secrets: [apiKey],
},
// Pass in the genkit flow.
jokeTeller,
);
index.js

Implantar fluxos no Firebase

Depois de definir os fluxos usando onCallGenkit, você pode implantá-los como faria com outras funções:

cd $PROJECT_ROOT
firebase deploy --only functions