Implantar fluxos usando o Cloud Run

É possível implantar fluxos do Genkit como endpoints HTTPS usando o Cloud Run. O Cloud Run tem várias opções de implantação, incluindo a implantação baseada em contêineres. Esta página explica como implantar seus fluxos diretamente do código.

Antes de começar

• Instale o Google Cloud CLI.
• Você precisa conhecer o conceito de fluxos do Genkit e saber como programá-los. Nesta página, presumimos que você já tenha fluxos que quer implantar.
• Seria útil, mas não obrigatório, se você já tiver usado o Google Cloud e o Cloud Run antes.

1. Configure um projeto do Google Cloud

Se você ainda não tiver um projeto do Google Cloud configurado, siga estas etapas:

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

2. Vincule o projeto a uma conta de faturamento, o que é obrigatório para o Cloud Run.

3. Configure a Google Cloud CLI para usar seu projeto:

   gcloud init

2. Preparar seu projeto Node para implantação

Para que seus fluxos possam ser implantados, você precisa fazer algumas pequenas alterações no código do projeto:

Adicionar scripts de início e build ao package.json

Ao implantar um projeto Node.js no Cloud Run, as ferramentas de implantação esperam que seu projeto tenha um script start e, opcionalmente, um script build. Para um projeto típico do TypeScript, os seguintes scripts geralmente são adequados:

"scripts": {
  "start": "node lib/index.js",
  "build": "tsc"
},

Adicionar código para configurar e iniciar o servidor de fluxo

No arquivo executado pelo script start, adicione uma chamada para startFlowServer. Esse método inicia um servidor Express configurado para exibir seus fluxos como endpoints da Web.

Ao fazer a chamada, especifique os fluxos que você quer veicular:

ai.startFlowServer({
  flows: [menuSuggestionFlow],
});

Também há alguns parâmetros opcionais que você pode especificar:

• port: a porta de rede a ser detectada. Se não for especificado, o servidor vai detectar na porta definida na variável de ambiente PORT. Se PORT não estiver definido, o padrão será 3400.
• cors: a política CORS do servidor de fluxo. Se você vai acessar esses endpoints em um aplicativo da Web, provavelmente vai precisar especificar isso.
• pathPrefix: um prefixo de caminho opcional para adicionar antes dos endpoints do fluxo.
• jsonParserOptions: opções a serem transmitidas ao analisador de corpo de JSON do Express.

Opcional: definir uma política de autorização

Todos os fluxos implantados precisam exigir algum tipo de autorização. Caso contrário, seus fluxos de IA generativa potencialmente caros poderão ser invocados por qualquer pessoa.

Ao implantar seus fluxos com o Cloud Run, você tem duas opções de autorização:

• Autorização baseada no Cloud IAM: use as ferramentas de gerenciamento de acesso nativo do Google Cloud para restringir o acesso aos seus endpoints. Consulte Autenticação nos documentos do Cloud Run para saber como fornecer essas credenciais.

• Política de autorização definida no código: use o recurso de política de autorização dos fluxos do Genkit para verificar informações de autorização usando um código personalizado. Isso geralmente é, mas não necessariamente, uma autorização baseada em token.

Se você quiser definir uma política de autorização no código, use o parâmetro authPolicy na definição do fluxo:

const myFlow = ai.defineFlow(
  {
    name: "myFlow",
    authPolicy: (auth, input) => {
      if (!auth) {
        throw new Error("Authorization required.");
      }
      // Custom checks go here...
    },
  },
  async () => {
    // ...
  }
);

O parâmetro auth da política de autorização vem da propriedade auth do objeto de solicitação. Normalmente, essa propriedade é definida usando o middleware Express. Consulte Autorização e integridade.

Disponibilizar credenciais da API para fluxos implantados

Depois de implantados, os fluxos precisam de uma forma de autenticação com os serviços remotos em que eles dependem. A maioria dos fluxos precisa, no mínimo, 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:

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.

3. Implantar fluxos no Cloud Run

Depois de preparar seu projeto para implantação, você pode implantá-lo usando a ferramenta gcloud.

gcloud run deploy --update-secrets=GOOGLE_GENAI_API_KEY=<your-secret-name>:latest

gcloud run deploy

A ferramenta de implantação vai solicitar todas as informações necessárias.

Quando for perguntado se você quer permitir invocações não autenticadas:

• Responda Y se você não estiver usando o IAM e tiver definido uma política de autorização no código.
• Responda N para configurar seu serviço para exigir credenciais do IAM.

Opcional: testar o fluxo implantado

Depois que a implantação terminar, a ferramenta imprimirá o URL de serviço. É possível testar isso com curl:

curl -X POST https://<service-url>/menuSuggestionFlow \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" -d '{"data": "banana"}'