Plugin Firebase

Il plug-in Firebase fornisce integrazioni con i servizi Firebase, consentendoti di creare applicazioni di IA intelligenti e scalabili. Alcuni esempi delle principali funzionalità:

  • Firestore Vector Store: utilizza Firestore per l'indicizzazione e il recupero con incorporamenti vettoriali.
  • Cloud Functions: esegui il deployment dei flussi come funzioni attivate da HTTPS.
  • Firebase Authentication: implementa i criteri di autorizzazione.
  • Telemetria: esporta la telemetria nella suite operativa di Google Cloud e visualizza viste specializzate nella console Firebase

Installazione

Installa il plug-in Firebase con npm:

npm install @genkit-ai/firebase

Prerequisiti

Configurazione del progetto Firebase

  1. Tutti i prodotti Firebase richiedono un progetto Firebase. Puoi creare un nuovo progetto o attivare Firebase in un progetto Google Cloud esistente utilizzando la console Firebase.
  2. Se esegui il deployment dei flussi con Cloud Functions, esegui l'upgrade del progetto Firebase al piano Blaze.
  3. Se vuoi eseguire localmente il codice che esporta la telemetria, devi installare lo strumento Google Cloud CLI.

Inizializzazione dell'SDK Firebase Admin

Devi inizializzare l'SDK Firebase Admin nella tua applicazione. Questa operazione non viene gestita automaticamente dal plug-in.

import { initializeApp } from 'firebase-admin/app';

initializeApp({
  projectId: 'your-project-id',
});

Il plug-in richiede di specificare l'ID progetto Firebase. Puoi specificare l'ID progetto Firebase in uno dei seguenti modi:

  • Imposta projectId nell'oggetto di configurazione initializeApp() come mostrato nello snippet precedente.

  • Imposta la variabile di ambiente GCLOUD_PROJECT. Se esegui il flusso da un ambiente Google Cloud (Cloud Functions, Cloud Run e così via), GCLOUD_PROJECT viene impostato automaticamente sull'ID progetto dell'ambiente.

    Se imposti GCLOUD_PROJECT, puoi omettere il parametro di configurazione in initializeApp().

Credenziali

Per fornire le credenziali di Firebase, devi anche configurare le credenziali predefinite dell'applicazione Google Cloud. Per specificare le credenziali:

  • Se esegui il flusso da un ambiente Google Cloud (Cloud Functions, Cloud Run e così via), questo valore viene impostato automaticamente.

  • Per altri ambienti:

    1. Genera le credenziali dell'account di servizio per il tuo progetto Firebase e scarica il file della chiave JSON. Puoi farlo nella pagina Account di servizio della Console di Firebase.
    2. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio oppure imposta la variabile di ambiente GCLOUD_SERVICE_ACCOUNT_CREDS sui contenuti del file JSON.

Funzionalità e utilizzo

Telemetria

Il plug-in ha una dipendenza diretta dal plug-in Google Cloud e, di conseguenza, dispone di disposizioni per abilitare l'esportazione della telemetria nella suite operativa di Google Cloud. Per attivare l'esportazione della telemetria, chiama enableFirebaseTelemetry():

import { enableFirebaseTelemetry } from '@genkit-ai/firebase';

enableFirebaseTelemetry();

Fai riferimento alla documentazione del plug-in Google Cloud per tutte le opzioni di configurazione e le API necessarie da attivare nel progetto.

Puoi utilizzare Cloud Firestore come spazio vettoriale per l'indicizzazione e il recupero dei raggruppamenti.

Questa sezione contiene informazioni specifiche sul plug-in firebase e sulla funzionalità di ricerca vettoriale di Cloud Firestore. Per una discussione più dettagliata sull'implementazione della RAG utilizzando Genkit, consulta la pagina Retrieval-Augmented Generation.

Utilizzo di GCLOUD_SERVICE_ACCOUNT_CREDS e Firestore

Se utilizzi le credenziali dell'account di servizio passandole direttamente tramite GCLOUD_SERVICE_ACCOUNT_CREDS e utilizzi anche Firestore come spazio vettoriale, dovrai passare le credenziali direttamente all'istanza Firestore durante l'inizializzazione, altrimenti l'oggetto singolo potrebbe essere inizializzato con le credenziali predefinite dell'applicazione, a seconda dell'ordine di inizializzazione del plug-in.

import {initializeApp} from "firebase-admin/app";
import {getFirestore} from "firebase-admin/firestore";

const app = initializeApp();
let firestore = getFirestore(app);

if (process.env.GCLOUD_SERVICE_ACCOUNT_CREDS) {
  const serviceAccountCreds = JSON.parse(process.env.GCLOUD_SERVICE_ACCOUNT_CREDS);
  const authOptions = { credentials: serviceAccountCreds };
  firestore.settings(authOptions);
}

Definire un recuperatore Firestore

Utilizza defineFirestoreRetriever() per creare un retriever per le query basate su vettori di Firestore.

import { defineFirestoreRetriever } from '@genkit-ai/firebase';
import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

const app = initializeApp();
const firestore = getFirestore(app);

const retriever = defineFirestoreRetriever(ai, {
  name: 'exampleRetriever',
  firestore,
  collection: 'documents',
  contentField: 'text', // Field containing document content
  vectorField: 'embedding', // Field containing vector embeddings
  embedder: yourEmbedderInstance, // Embedder to generate embeddings
  distanceMeasure: 'COSINE', // Default is 'COSINE'; other options: 'EUCLIDEAN', 'DOT_PRODUCT'
});

Recuperare i documenti

Per recuperare i documenti utilizzando il retriever definito, passa l'istanza del retriever e le opzioni di query a ai.retrieve.

const docs = await ai.retrieve({
  retriever,
  query: 'search query',
  options: {
    limit: 5, // Options: Return up to 5 documents
    where: { category: 'example' }, // Optional: Filter by field-value pairs
    collection: 'alternativeCollection', // Optional: Override default collection
  },
});

Opzioni di recupero disponibili

Le seguenti opzioni possono essere passate al campo options in ai.retrieve:

  • limit: (number)
    Specifica il numero massimo di documenti da recuperare. Il valore predefinito è 10.

  • where: (Record<string, any>)
    Aggiungi filtri aggiuntivi in base ai campi Firestore. Esempio:

    where: { category: 'news', status: 'published' }

  • collection: (stringa)
    Sostituisci la raccolta predefinita specificata nella configurazione del retriever. Questa operazione è utile per eseguire query sulle sottocollezioni o passare dinamicamente da una collezione all'altra.

Compilare Firestore con gli elementi incorporati

Per compilare la raccolta Firestore, utilizza un generatore di embedding insieme all'SDK Admin. Ad esempio, lo script di importazione del menu della pagina Retrieval-Augmented Generation potrebbe essere adattato per Firestore nel seguente modo:

import { genkit } from 'genkit';
import { vertexAI, textEmbedding004 } from "@genkit-ai/vertexai";

import { applicationDefault, initializeApp } from "firebase-admin/app";
import { FieldValue, getFirestore } from "firebase-admin/firestore";

import { chunk } from "llm-chunk";
import pdf from "pdf-parse";

import { readFile } from "fs/promises";
import path from "path";

// Change these values to match your Firestore config/schema
const indexConfig = {
  collection: "menuInfo",
  contentField: "text",
  vectorField: "embedding",
  embedder: textEmbedding004,
};

const ai = genkit({
  plugins: [vertexAI({ location: "us-central1" })],
});

const app = initializeApp({ credential: applicationDefault() });
const firestore = getFirestore(app);

export async function indexMenu(filePath: string) {
  filePath = path.resolve(filePath);

  // Read the PDF.
  const pdfTxt = await extractTextFromPdf(filePath);

  // Divide the PDF text into segments.
  const chunks = await chunk(pdfTxt);

  // Add chunks to the index.
  await indexToFirestore(chunks);
}

async function indexToFirestore(data: string[]) {
  for (const text of data) {
    const embedding = await ai.embed({
      embedder: indexConfig.embedder,
      content: text,
    });
    await firestore.collection(indexConfig.collection).add({
      [indexConfig.vectorField]: FieldValue.vector(embedding),
      [indexConfig.contentField]: text,
    });
  }
}

async function extractTextFromPdf(filePath: string) {
  const pdfFile = path.resolve(filePath);
  const dataBuffer = await readFile(pdfFile);
  const data = await pdf(dataBuffer);
  return data.text;
}

Firestore si basa sugli indici per fornire query rapide ed efficienti sulle raccolte. Tieni presente che per "indice" qui si intendono gli indici del database e non le astrazioni di indicizzatore e retriever di Genkit.

L'esempio precedente richiede l'indicizzazione del campo embedding per funzionare. Per creare l'indice:

  • Esegui il comando gcloud descritto nella sezione Creare un indice vettoriale a campo singolo della documentazione di Firestore.

    Il comando è il seguente:

    gcloud alpha firestore indexes composite create --project=your-project-id \
  --collection-group=yourCollectionName --query-scope=COLLECTION \
  --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=yourEmbeddingField

    Tuttavia, la configurazione corretta dell'indicizzazione dipende dalle query che effettuerai e dal modello di incorporamento che utilizzi.

  • In alternativa, chiama ai.retrieve() e Firestore restituirà un errore con il comando corretto per creare l'indice.

Scopri di più

Esegui il deployment dei flussi come funzioni Cloud

Il plug-in fornisce il costruttore onFlow(), che crea un flusso basato su una funzione attivata tramite HTTPS di Cloud Functions for Firebase. Queste funzioni sono conformi all'interfaccia della funzione richiamabile di Firebase e puoi utilizzarle con gli SDK client di Cloud Functions.

import { onFlow, noAuth } from "@genkit-ai/firebase/functions";

export const exampleFlow = onFlow(
  ai, // Provide the Genkit instance
  {
    name: "exampleFlow",
    authPolicy: noAuth(), // WARNING: noAuth() creates an open endpoint!
  },
  async (prompt) => {
    // Flow logic goes here.

    return response;
  }
);

Esegui il deployment del flusso utilizzando l'interfaccia a riga di comando di Firebase:

firebase deploy --only functions

La funzione onFlow() ha alcune opzioni non presenti in defineFlow():

  • httpsOptions: un oggetto HttpsOptions utilizzato per configurare la Funzione Cloud:

    export const exampleFlow = onFlow(
  ai,
  {
    name: "exampleFlow",
    httpsOptions: {
      cors: true,
    },
    // ...
  },
  async (prompt) => {
    // ...
  }
);

  • enforceAppCheck: quando true, rifiuta le richieste con token App Check mancanti o non validi.

  • consumeAppCheckToken: quando true, invalida il token App Check dopo averlo verificato.

    Vedi Protezione da replay.

Firebase Authentication

Questo plug-in fornisce una funzione di supporto per creare criteri di autorizzazione per Firebase Auth:

import {firebaseAuth} from "@genkit-ai/firebase/auth";

export const exampleFlow = onFlow(
  ai,
  {
    name: "exampleFlow",
    authPolicy: firebaseAuth((user) => {
      if (!user.email_verified) throw new Error("Requires verification!");
    }),
  },
  async (prompt) => {
    // ...
  }
);

Per definire un criterio di autenticazione, fornisci a firebaseAuth() una funzione di callback che accetta un DecodedIdToken come unico parametro. In questa funzione, esamina il token utente e genera un errore se l'utente non soddisfa uno dei criteri che vuoi richiedere.

Per una discussione più approfondita su questo argomento, consulta Autorizzazione e integrità.