Firebase-Plug-in

Das Firebase-Plug-in bietet Integrationen mit Firebase-Diensten, sodass Sie intelligente und skalierbare KI-Anwendungen erstellen können. Besondere Merkmale:

  • Firestore Vector Store: Verwenden Sie Firestore für die Indexierung und Abfrage mit Vektoreinbettungen.
  • Telemetrie: Telemetriedaten in die Operations Suite von Google Cloud exportieren, die die Firebase Genkit-Monitoring-Konsole unterstützt.

Installation

Installieren Sie das Firebase-Plug-in mit npm:

npm install @genkit-ai/firebase

Vorbereitung

Firebase-Projekt einrichten

  1. Für alle Firebase-Produkte ist ein Firebase-Projekt erforderlich. Mit der Firebase Console können Sie ein neues Projekt erstellen oder Firebase in einem vorhandenen Google Cloud-Projekt aktivieren.
  2. Wenn Sie Workflows mit Cloud-Funktionen bereitstellen, aktualisieren Sie Ihr Firebase-Projekt auf den Blaze-Tarif.
  3. Wenn Sie Code lokal ausführen möchten, der Telemetry-Daten exportiert, muss das Tool Google Cloud CLI installiert sein.

Firebase Admin SDK-Initialisierung

Sie müssen das Firebase Admin SDK in Ihrer Anwendung initialisieren. Das Plug-in übernimmt das nicht automatisch.

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

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

Sie müssen die Firebase-Projekt-ID angeben. Sie haben folgende Möglichkeiten, Ihre Firebase-Projekt-ID anzugeben:

  • Legen Sie projectId im Konfigurationsobjekt initializeApp() wie im Snippet oben gezeigt fest.

  • Legen Sie die Umgebungsvariable GCLOUD_PROJECT fest. Wenn Sie Ihren Ablauf in einer Google Cloud-Umgebung (z. B. Cloud Functions oder Cloud Run) ausführen, wird GCLOUD_PROJECT automatisch auf die Projekt-ID der Umgebung festgelegt.

    Wenn Sie GCLOUD_PROJECT festlegen, können Sie den Konfigurationsparameter in initializeApp() weglassen.

Anmeldedaten

Wenn Sie Firebase-Anmeldedaten angeben möchten, müssen Sie auch die Standardanmeldedaten für Google Cloud-Anwendungen einrichten. So geben Sie Ihre Anmeldedaten an:

  • Wenn Sie Ihren Ablauf in einer Google Cloud-Umgebung (z. B. Cloud Functions oder Cloud Run) ausführen, wird dies automatisch festgelegt.

  • Für andere Umgebungen:

    1. Generieren Sie Anmeldedaten für Ihr Dienstkonto für Ihr Firebase-Projekt und laden Sie die JSON-Schlüsseldatei herunter. Sie können dies auf der Seite Dienstkonto in der Firebase Console tun.
    2. Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Dateipfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält, oder legen Sie die Umgebungsvariable GCLOUD_SERVICE_ACCOUNT_CREDS auf den Inhalt der JSON-Datei fest.

Funktionen und Verwendung

Telemetrie

Firebase Genkit Monitoring wird von der Cloud Operations Suite von Google unterstützt. Dazu müssen telematische APIs für Ihr Projekt aktiviert sein. Weitere Informationen finden Sie in der Google Cloud-Plug-in-Dokumentation.

Gewähren Sie dem „Standard-Compute-Dienstkonto“ in der Google Cloud IAM-Konsole die folgenden Rollen:

  • Monitoring-Messwert-Autor (roles/monitoring.metricWriter)
  • Cloud Trace-Agent (roles/cloudtrace.agent)
  • Logautor (roles/logging.logWriter)

So aktivieren Sie den Telemetrieexport:enableFirebaseTelemetry()

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

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

Dieses Plug-in teilt Konfigurationsoptionen mit dem Google Cloud-Plug-in.

Sie können Cloud Firestore als Vektorspeicher für die Indexierung und Abfrage von RAGs verwenden.

Dieser Abschnitt enthält Informationen speziell zum firebase-Plug-in und zur Vektorsuchfunktion von Cloud Firestore. Eine ausführlichere Beschreibung zur Implementierung von RAG mit Genkit finden Sie auf der Seite Retrieval-Augmented Generation.

GCLOUD_SERVICE_ACCOUNT_CREDS und Firestore verwenden

Wenn Sie Anmeldedaten für ein Dienstkonto verwenden, indem Sie sie direkt über GCLOUD_SERVICE_ACCOUNT_CREDS übergeben, und Firestore als Vektorspeicher verwenden, müssen Sie die Anmeldedaten während der Initialisierung direkt an die Firestore-Instanz übergeben. Andernfalls wird das Singleton je nach Reihenfolge der Plugin-Initialisierung möglicherweise mit den Standardanmeldedaten der Anwendung initialisiert.

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

Firestore-Abrufmethode definieren

Verwenden Sie defineFirestoreRetriever(), um einen Retriever für Firestore-vektorbasierte Abfragen zu erstellen.

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

Dokumente abrufen

Wenn Sie Dokumente mit dem definierten Retriever abrufen möchten, übergeben Sie die Retrieverinstanz und die Abfrageoptionen an 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
  },
});

Verfügbare Wiederherstellungsoptionen

Die folgenden Optionen können an das Feld options in ai.retrieve übergeben werden:

  • limit: (Zahl) Gibt die maximale Anzahl der abzurufenden Dokumente an. Der Standardwert ist 10.

  • where: (Record<string, any>) Hier können Sie zusätzliche Filter basierend auf Firestore-Feldern hinzufügen. Beispiel:

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

  • collection: (String) Überschreibt die in der Abrufkonfiguration angegebene Standardsammlung.

  • Das ist nützlich, um Untersammlungen abzufragen oder dynamisch zwischen

  • Sammlungen.

Firestore mit Einbettungen füllen

Verwenden Sie einen Embedding-Generator in Verbindung mit dem Admin SDK, um Ihre Firestore-Sammlung zu füllen. Das Skript zum Einlesen von Menüs von der Seite Mit Abruf erweiterte Generierung kann beispielsweise so für Firestore angepasst werden:

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 verwendet Indexe, um schnelle und effiziente Abfragen in Sammlungen zu ermöglichen. Hinweis: „Index“ bezieht sich hier auf Datenbankindexe und nicht auf die Indexierungs- und Abrufabstraktion von Genkit.

Im vorherigen Beispiel muss das Feld embedding indexiert sein, damit es funktioniert. So erstellen Sie den Index:

  • Führen Sie den gcloud-Befehl aus, der im Abschnitt Einzelfeld-Vektorindex erstellen der Firestore-Dokumentation beschrieben ist.

    Der Befehl sieht folgendermaßen aus:

    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

    Die richtige Indexierungskonfiguration hängt jedoch von den von Ihnen gestellten Abfragen und dem verwendeten Einbettungsmodell ab.

  • Alternativ können Sie ai.retrieve() aufrufen. In diesem Fall gibt Firestore einen Fehler mit dem richtigen Befehl zum Erstellen des Index zurück.

Weitere Informationen

Abläufe als Cloud Functions bereitstellen

Wenn Sie einen Ablauf mit Cloud Functions bereitstellen möchten, verwenden Sie die integrierte Unterstützung für Genkit in der Firebase Functions-Bibliothek. Mit der Methode onCallGenkit können Sie aus einem Ablauf eine aufrufbare Funktion erstellen. Streaming- und JSON-Anfragen werden automatisch unterstützt. Sie können sie mithilfe der Cloud Functions-Client-SDKs aufrufen.

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

Binden Sie den Ablauf mit der Firebase CLI ein:

firebase deploy --only functions