Richiamare i flussi Genkit dalla tua app

Cloud Functions for Firebase ha un metodo onCallGenkit che consente di creare una funzione chiamabile 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 conoscere il concetto di Genkit flussi e come 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, se hai già utilizzato Cloud Functions for Firebase prima.

Configurare un progetto Firebase

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

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

  3. Installa l'Firebase CLI.

    Cloud Shell

  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 di 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 funzioni in JavaScript.

Eseguire il wrapping del flusso in onCallGenkit

Dopo aver configurato un progetto Firebase e inizializzato Cloud Functions in esso, puoi copiare o scrivere definizioni di flusso nella functions directory del progetto. Ecco un esempio di flusso per dimostrarlo:

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, esegui il wrapping con onCallGenkit, disponibile in firebase-functions/https. Questo metodo helper ha tutte le funzionalità delle funzioni chiamabili e supporta automaticamente sia le risposte di 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,
);

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

Una volta di cui è stato eseguito il deployment, i flussi devono essere in grado di autenticarsi con tutti i servizi remoti da cui dipendono. Come minimo, la maggior parte dei flussi ha bisogno di credenziali per accedere al servizio API del modello che utilizza.

Per questo esempio, esegui una delle seguenti operazioni, a seconda del provider di modelli 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 di esporre accidentalmente la chiave API, che concede l'accesso a un servizio potenzialmente misurato.

    Per ulteriori informazioni sulla gestione dei secret, consulta Archiviare e accedere 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");

    Quindi, nella definizione della funzione chiamabile, 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 dall'ambiente Cloud Functions.

Gemini (Vertex AI)

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

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

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

(Facoltativo) Aggiungere l'applicazione forzata 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'App Check applicazione forzata 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);

Configurare CORS (Cross-Origin Resource Sharing)

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

Per impostazione predefinita, le funzioni chiamabili hanno CORS configurato per consentire le richieste da tutte le origini. Per consentire alcune richieste cross-origin, ma non tutte, passa un elenco di domini specifici o espressioni regolari 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 all'esempio seguente:

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

Eseguire il deployment dei flussi in Firebase

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

cd $PROJECT_ROOT
firebase deploy --only functions