Plugin Firebase

Il plug-in Firebase fornisce integrazioni con i servizi Firebase, in modo da poter 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.
  • Telemetria: esporta la telemetria nella suite operativa Google Cloud che alimenta la console di monitoraggio Firebase Genkit.

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

Firebase Genkit Monitoring è basato sulla suite operativa Google Cloud. Per farlo, è necessario attivare le API relative alla telemetria per il tuo progetto. Per ulteriori dettagli, consulta la documentazione del plug-in Google Cloud.

Concedi i ruoli seguenti al "service account Compute predefinito" all'interno della console IAM di Google Cloud:

  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  • Agente Cloud Trace (roles/cloudtrace.agent)
  • Logs Writer (roles/logging.logWriter)

Per attivare l'esportazione della telemetria, chiama enableFirebaseTelemetry():

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

enableFirebaseTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
});

Questo plug-in condivide le opzioni di configurazione con il plug-in Google Cloud.

Puoi utilizzare Cloud Firestore come un vettore per l'indicizzazione e il recupero dei raggruppamenti.

Questa sezione contiene informazioni specifiche sul plug-in firebase e sulla funzionalità di ricerca di vettori 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 vettore di memorizzazione, devi passare le credenziali direttamente all'istanza Firestore durante l'inizializzazione, altrimenti l'oggetto singleton 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.

  • Questo è utile per eseguire query sulle sottocollezioni o passare dinamicamente da una all'altra

  • raccolte.

Compilare Firestore con gli incorporamenti

Per compilare la raccolta Firestore, utilizza un generatore di embedding insieme all'SDK Admin. Ad esempio, lo script di importazione del menu della pagina Genesi basata sul recupero 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,
    }))[0].embedding;
    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 astrattive di indicizzazione e recupero 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 di vettori 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 effettui 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

Per eseguire il deployment di un flusso con Cloud Functions, utilizza il supporto integrato della libreria Firebase Functions per genkit. Il metodo onCallGenkit consente di creare una funzione richiamabile da un flusso. Supporta automaticamente le richieste JSON e in streaming. Puoi utilizzare gli SDK client di Cloud Functions per chiamarle.

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

export const exampleFlow = ai.defineFlow({
  name: "exampleFlow",
}, async (prompt) => {
    // Flow logic goes here.

    return response;
  }
);

// WARNING: This has no authentication or app check protections.
// See github.com/firebase/genkit/blob/main/docs/auth.md for more information.
export const example = onCallGenkit({ secrets: [apiKey] }, exampleFlow);

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

firebase deploy --only functions