Richiamare i flussi Genkit dalla tua app

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

Prima di iniziare

  • Devi avere familiarità con il concetto di flussi di Genkit e sapere 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.

Configura un progetto Firebase

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

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

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

  4. Accedi con la CLI di 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.

Inserisci il flusso in onCallGenkit

Dopo aver configurato un progetto Firebase con Cloud Functions, puoi copiare o scrivere definizioni di flusso nella directory functions del progetto. Ecco un flusso di esempio 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;
},
);
index.js

Per eseguire il deployment di un flusso come questo, racchiudilo 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 sia quelle JSON.

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

Rendere disponibili le credenziali API ai flussi di lavoro di cui è stato eseguito il deployment

Una volta implementati, i flussi devono essere autenticati con tutti i servizi remoti da cui dipendono. 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 fornitore del modello che hai scelto:

Gemini (Google AI)

  1. Assicurati che Google AI sia disponibile nella tua regione.

  2. Genera una chiave API per l'API Gemini utilizzando Google AI Studio.

  3. Archivia la chiave API in Cloud Secret Manager:

    firebase functions:secrets:set GOOGLE_GENAI_API_KEY

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

    Per ulteriori informazioni sulla gestione dei secret, consulta Archivia e accedi a informazioni di configurazione sensibili.

  4. 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");
    index.js

    Poi, 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],
    index.js

Ora, quando esegui il deployment di questa funzione, la chiave API viene archiviata in Cloud Secret Manager ed è disponibile dall'ambiente Cloud Functions.

Gemini (Vertex AI)

  1. Nella console 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 Utente Vertex AI.

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

(Facoltativo) Aggiungere l'applicazione forzata di App Check

Firebase App Check utilizza l'attestazione nativa per verificare che la tua API venga chiamata solo dalla tua applicazione. 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);

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 multiorigine, 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 sopra, il flusso implementabile sarà simile al seguente esempio:

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

Esegui 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