Implementa flujos con Cloud Run

Puedes implementar flujos de Genkit como extremos HTTPS con Cloud Run. Cloud Run tiene varias opciones de implementación, incluida la implementación basada en contenedores. En esta página, se explica cómo implementar tus flujos directamente desde el código.

Antes de comenzar

• Instala Google Cloud CLI.
• Debes conocer el concepto de flujos de Genkit y cómo escribirlos. En esta página, se supone que ya tienes flujos que deseas implementar.
• Sería útil, pero no es obligatorio, que ya hayas usado Google Cloud y Cloud Run.

1. Configura un proyecto de Google Cloud

Si aún no tienes configurado un proyecto de Google Cloud, sigue estos pasos:

1. Crea un proyecto de Google Cloud nuevo usando la consola de Cloud o elige uno existente.

2. Vincula el proyecto a una cuenta de facturación, que es obligatoria para Cloud Run.

3. Configura Google Cloud CLI para usar tu proyecto:

   gcloud init

2. Prepara tu proyecto de Node para la implementación

Para que tus flujos se puedan implementar, deberás realizar algunos cambios pequeños en el código de tu proyecto:

Agrega secuencias de comandos de inicio y compilación a package.json

Cuando implementas un proyecto de Node.js en Cloud Run, las herramientas de implementación esperan que tu proyecto tenga una secuencia de comandos start y, de manera opcional, una secuencia de comandos build. Para un proyecto de TypeScript típico, las siguientes secuencias de comandos suelen ser adecuadas:

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

Agrega código para configurar y, luego, iniciar el servidor de flujo

En el archivo que ejecuta la secuencia de comandos start, agrega una llamada a startFlowServer. Este método iniciará un servidor Express configurado para entregar tus flujos como extremos web.

Cuando realices la llamada, especifica los flujos que deseas publicar:

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

También hay algunos parámetros opcionales que puedes especificar:

• port: Es el puerto de red en el que se escuchará. Si no se especifica, el servidor escucha en el puerto definido en la variable de entorno PORT y, si no se establece PORT, se establece de forma predeterminada en 3400.
• cors: La política de CORS del servidor de flujo. Si accederás a estos extremos desde una aplicación web, es probable que necesites especificar esto.
• pathPrefix: Es un prefijo de ruta opcional que se agrega antes de los extremos de tu flujo.
• jsonParserOptions: Son opciones para pasar al analizador de cuerpo de JSON de Express.

Opcional: Define una política de autorización

Todos los flujos implementados deben requerir algún tipo de autorización. De lo contrario, cualquier persona podría invocar tus flujos de IA generativa potencialmente costosos.

Cuando implementas tus flujos con Cloud Run, tienes dos opciones para la autorización:

• Autorización basada en Cloud IAM: Usa las funciones de administración de acceso nativas de Google Cloud para restringir el acceso a tus extremos. Consulta Autenticación en los documentos de Cloud Run para obtener información sobre cómo proporcionar estas credenciales.

• Política de autorización definida en el código: Usa la función de política de autorización de los flujos de Genkit para verificar la información de autorización con código personalizado. A menudo, esto es una autorización basada en tokens, pero no necesariamente.

Si deseas definir una política de autorización en el código, usa el parámetro authPolicy en la definición del flujo:

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

El parámetro auth de la política de autorización proviene de la propiedad auth del objeto de solicitud. Por lo general, configuras esta propiedad con el middleware de Express. Consulta Integridad y autorización.

Haz que las credenciales de la API estén disponibles para los flujos implementados

Una vez que se implementan, tus flujos necesitan una forma de autenticarse con los servicios remotos en los que se basan. La mayoría de los flujos necesitarán, como mínimo, credenciales para acceder al servicio de la API del modelo que usan.

En este ejemplo, realiza una de las siguientes acciones según el proveedor de modelos que hayas elegido:

El único secreto que debes configurar para este instructivo es para el proveedor del modelo, pero, en general, debes hacer algo similar para cada servicio que tu flujo use.

3. Implementa flujos en Cloud Run

Después de preparar tu proyecto para la implementación, puedes implementarlo con la herramienta gcloud.

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

gcloud run deploy

La herramienta de implementación te solicitará la información que requiera.

Cuando se te pregunte si quieres permitir invocaciones no autenticadas, haz lo siguiente:

• Responde Y si no usas IAM y, en su lugar, definiste una política de autorización en el código.
• Responde N para configurar tu servicio para que requiera credenciales de IAM.

Opcional: Prueba el flujo implementado

Una vez finalizada la implementación, la herramienta imprimirá la URL de servicio. Puedes probar con curl:

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