Richiamare i flussi Genkit dalla tua app

Cloud Functions for Firebase ha un metodo onCallGenkit che ti consente di creare una funzione richiamabile con un'azione Genkit (un flusso). Queste funzioni possono essere chiamate con genkit/beta/client o un Cloud Functions for Firebase Client SDK, che aggiunge automaticamente le informazioni di autenticazione.

Prima di iniziare

  • Dovresti avere familiarità con il concetto di flussi Genkit e con il modo in cui scriverli. Le istruzioni riportate in questa pagina presuppongono che tu abbia già definito alcuni flussi di cui vuoi eseguire il deployment.
  • È utile, ma non obbligatorio, aver utilizzato Cloud Functions for Firebase in precedenza.

Configura un progetto Firebase

  1. Crea un nuovo progetto Firebase utilizzando la console Firebase o scegline uno esistente.

  2. Esegui l'upgrade del progetto al piano tariffario Blaze con pagamento a consumo, necessario per il deployment in produzione di Cloud Functions.

  3. Installa l'interfaccia a riga di comando Firebase.

  4. Accedi all'interfaccia a riga di comando Firebase:

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

  5. Crea una nuova directory del progetto:

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

  6. Inizializza un progetto Firebase nella directory:

    cd $PROJECT_ROOT
firebase init functions

Il resto di questa pagina presuppone che tu abbia scelto di scrivere le tue funzioni in JavaScript.

Aggrega il flusso in onCallGenkit

Dopo aver configurato un progetto Firebase e inizializzato Cloud Functions al suo interno, puoi copiare o scrivere definizioni dei flussi nella directory functions del progetto. Ecco un esempio di flusso che lo dimostra:

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;
},
);

Per eseguire il deployment di un flusso come questo, inseriscilo in onCallGenkit, disponibile in firebase-functions/https. Questo metodo helper ha tutte le funzionalità delle funzioni richiamabili e supporta automaticamente sia le risposte in streaming che quelle JSON.

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

Rendi disponibili le credenziali API per i flussi di cui è stato eseguito il deployment

Una volta eseguiti il deployment, i flussi devono essere autenticati con i servizi remoti su cui si basano. Come minimo, la maggior parte dei flussi richiede le credenziali per accedere al servizio API del modello che utilizza.

Per questo esempio, esegui una delle seguenti operazioni, a seconda del provider del modello che hai scelto:

Gemini (Google AI)

  1. Genera una chiave API per Gemini Developer API utilizzando Google AI Studio.

  2. Archivia la chiave API in Google Cloud Secret Manager:

    firebase functions:secrets:set GOOGLE_GENAI_API_KEY

    Questo passaggio è importante per evitare la fuga accidentale della chiave API, che concede l'accesso a un servizio potenzialmente a consumo.

    Per saperne di più sulla gestione dei secret, consulta Archivia e accedi alle informazioni di configurazione sensibili.

  3. Modifica src/index.js e aggiungi quanto segue dopo le importazioni esistenti:

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

    Poi, nella definizione della funzione richiamabile, dichiara che la funzione deve accedere a questo valore secret:

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

Ora, quando esegui il deployment di questa funzione, la chiave API verrà archiviata in Google Cloud Secret Manager e sarà disponibile nell'ambiente Cloud Functions.

Gemini (Vertex AI)

  1. Nella console Google Cloud, abilita l'API Vertex AI per il tuo progetto Firebase.

  2. Nella pagina IAM, assicurati che al service account Compute predefinito sia concesso il ruolo Vertex AI User.

L'unico secret che devi configurare per questo tutorial è quello per il provider del modello, ma in generale devi fare qualcosa di simile per ogni servizio utilizzato dal tuo flusso.

(Facoltativo) Aggiungi l'applicazione di Firebase App Check

Firebase App Check utilizza l'attestazione nativa per verificare che la nostra API venga chiamata solo dalla tua applicazione. Il metodo onCallGenkit supporta l'applicazione di App Check in modo dichiarativo.

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);

Configura la condivisione di risorse multiorigine (CORS)

Utilizza l'opzione cors per controllare quali origini possono accedere alla tua funzione.

Per impostazione predefinita, le funzioni richiamabili hanno la configurazione CORS per consentire le richieste da tutte le origini. Per consentire alcune richieste multiorigine, ma non tutte, passa un elenco di domini o espressioni regolari specifici che devono essere consentiti. Ad esempio:

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

Esempio completo

Dopo aver apportato tutte le modifiche descritte in questa guida, il flusso di cui è possibile eseguire il deployment sarà simile al seguente esempio:

const {onCallGenkit} = require("firebase-functions/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,
);

Esegui il deployment dei flussi su Firebase

Dopo aver definito i flussi utilizzando onCallGenkit, puoi eseguirne il deployment come faresti con altre funzioni:

cd $PROJECT_ROOT
firebase deploy --only functions