Implementa flujos con Cloud Functions para Firebase

Cloud Functions para Firebase tiene un método onCallGenkit que te permite crear rápidamente una función que se pueda llamar con una acción de Genkit (p.ej., un flujo). Se puede llamar a estas funciones con genkit/beta/client o el SDK de cliente de Functions, que agrega automáticamente información de autenticación.

Antes de comenzar

• Debes conocer el concepto de flujos de Genkit y cómo escribirlos. En las instrucciones de esta página, se da por sentado que ya tienes algunos flujos definidos que deseas implementar.
• Sería útil, pero no es obligatorio, que ya hayas usado Cloud Functions para Firebase.

1. Configura un proyecto de Firebase:

Si aún no tienes un proyecto de Firebase con Cloud Functions de TypeScript configurado, sigue estos pasos:

1. Crea un proyecto de Firebase nuevo con la consola de Firebase o elige uno existente.

2. Actualiza el proyecto al plan Blaze, que es obligatorio para implementar Cloud Functions.

3. Instala Firebase CLI.

4. Accede con Firebase CLI:

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

5. Crea un directorio de proyecto nuevo:

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

6. Inicializa un proyecto de Firebase en el directorio:

   cd $PROJECT_ROOT
   firebase init genkit

   En el resto de esta página, se supone que decidiste escribir tus funciones en TypeScript, pero también puedes implementar tus flujos de Genkit si usas JavaScript.

2. Une el flujo en onCallGenkit

Después de configurar un proyecto de Firebase con Cloud Functions, puedes copiar o escribir definiciones de flujo en el directorio functions/src del proyecto y exportarlas en index.ts.

Para que tus flujos se puedan implementar, debes unirlos en onCallGenkit. Este método tiene todas las funciones de onCall normal. Admite automáticamente las respuestas de transmisión y JSON.

Supongamos que tienes el siguiente flujo:

const generatePoemFlow = ai.defineFlow(
  {
    name: "generatePoem",
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (subject: string) => {
    const { text } = await ai.generate(`Compose a poem about ${subject}.`);
    return text;
  }
);

Puedes exponer este flujo como una función que se puede llamar con onCallGenkit:

import { onCallGenkit } from 'firebase-functions/https';

export generatePoem = onCallGenkit(generatePoemFlow);

Define una política de autorización

Todos los flujos implementados, ya sea en Firebase o no, deben tener una política de autorización. Sin una, cualquier persona puede invocar tus flujos de IA generativa potencialmente costosos. Para definir una política de autorización, usa el parámetro authPolicy de onCallGenkit:

export const generatePoem = onCallGenkit({
  authPolicy: (auth) => auth?.token?.email_verified,
}, generatePoemFlow);

En este ejemplo, se usa una función manual como política de autenticación. Además, la biblioteca de HTTPS exporta los asistentes signedIn() y hasClaim(). Este es el mismo código con una de esas ayudas:

import { hasClaim } from 'firebase-functions/https';

export const generatePoem = onCallGenkit({
  authPolicy: hasClaim('email_verified'),
}, generatePoemFlow);

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 necesitan, 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.

Agrega la aplicación forzosa de la Verificación de aplicaciones

La Verificación de aplicaciones de Firebase usa un mecanismo de certificación integrado para verificar que solo tu aplicaciónllame a la API. onCallGenkit admite la aplicación forzosa de la Verificación de aplicaciones 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);

Cómo establecer una política de CORS

De forma predeterminada, las funciones que admiten llamadas permiten que cualquier dominio llame a tu función. Si deseas personalizar los dominios que pueden hacer esto, usa la opción cors. Con la autenticación adecuada (en especial, la Verificación de apps), a menudo no es necesario usar CORS.

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

Ejemplo completo

Después de realizar todos los cambios descritos anteriormente, tu flujo implementable se verá como en el siguiente ejemplo:

import { genkit } from 'genkit';
import { onCallGenkit, hasClaim } from 'firebase-functions/https';
import { defineSecret } from 'firebase-functions/params';

const apiKey = defineSecret("GOOGLE_GENAI_API_KEY");

const generatePoemFlow = ai.defineFlow({
  name: "generatePoem",
  inputSchema: z.string(),
  outputSchema: z.string(),
}, async (subject: string) => {
  const { text } = await ai.generate(`Compose a poem about ${subject}.`);
  return text;
});

export const generateFlow = onCallGenkit({
  secrets: [apiKey],
  authPolicy: hasClaim("email_verified"),
  enforceAppCheck: true,
}, generatePoemFlow);

3. Implementa flujos en Firebase

Después de definir los flujos con onCallGenkit, puedes implementarlos de la misma manera que implementarías otras funciones de Cloud Functions:

cd $PROJECT_ROOT
firebase deploy --only functions

Ya implementaste el flujo como una función de Cloud Functions. Sin embargo, no puedes acceder a tu extremo implementado con curl o un servicio similar debido a la política de autorización del flujo. En la siguiente sección, se explica cómo acceder de forma segura al flujo.

Opcional: Prueba el flujo implementado

Para probar el extremo de tu flujo, puedes implementar la siguiente app web de ejemplo mínima:

1. En la sección Configuración del proyecto de Firebase console, agrega una app web nueva y selecciona la opción para configurar también Hosting.

2. En la sección Authentication de Firebase console, habilita el proveedor Google, que se usa en este ejemplo.

3. En el directorio de tu proyecto, configura Firebase Hosting, donde implementarás la app de ejemplo:

   cd $PROJECT_ROOT
   firebase init hosting

   Acepta los valores predeterminados para todas las indicaciones.

4. Reemplaza public/index.html por lo siguiente:

   <!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="generatePoem">Compose a poem on this subject</button>
         <p id="generatedPoem"></p>
       </div>
       <script type="module">
         import { initializeApp } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-app.js";
         import {
           getAuth,
           onAuthStateChanged,
           GoogleAuthProvider,
           signInWithPopup,
         } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-auth.js";
         import {
           getFunctions,
           httpsCallable,
         } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-functions.js";
   
         const firebaseConfig = await fetch("/__/firebase/init.json");
         initializeApp(await firebaseConfig.json());
   
         async function generatePoem() {
           const poemFlow = httpsCallable(getFunctions(), "generatePoem");
           const subject = document.querySelector("#subject").value;
           const response = await poemFlow(subject);
           document.querySelector("#generatedPoem").innerText = response.data;
         }
   
         function signIn() {
           signInWithPopup(getAuth(), new GoogleAuthProvider());
         }
   
         document.querySelector("#signinBtn").addEventListener("click", signIn);
         document
           .querySelector("#generatePoem")
           .addEventListener("click", generatePoem);
   
         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. Implementa la app web y la Cloud Function:

   cd $PROJECT_ROOT
   firebase deploy

Para abrir la app web, visita la URL que imprime el comando deploy. La app requiere que accedas con una Cuenta de Google. Luego, puedes iniciar solicitudes de extremos.

Opcional: Ejecuta flujos en la IU para desarrolladores

Puedes ejecutar flujos definidos con onCallGenkit en la IU para desarrolladores, de la misma manera que ejecutas flujos definidos con defineFlow, por lo que no es necesario cambiar entre los dos entre la implementación y el desarrollo.

cd $PROJECT_ROOT/functions
npx genkit start -- npx tsx --watch src/index.ts

o

cd $PROJECT_ROOT/functions
npm run genkit:start

Ahora puedes navegar a la URL que imprimió el comando genkit start para acceder a ella.

Opcional: Desarrolla con Firebase Local Emulator Suite

Firebase ofrece un conjunto de emuladores para el desarrollo local, que puedes usar con Genkit.

Para usar la IU para desarrolladores de Genkit con Firebase Emulator Suite, inicia los emuladores de Firebase de la siguiente manera:

npx genkit start -- firebase emulators:start --inspect-functions

Este comando ejecuta tu código en el emulador y ejecuta el framework de Genkit en modo de desarrollo. Esto inicia y expone la API de reflexión de Genkit (pero no la IU para desarrolladores).

Para ver los seguimientos de Firestore en la IU de Dev, puedes navegar a la pestaña Inspect y activar o desactivar el interruptor Dev/Prod. Cuando se activa prod, carga trazas de Firestore.