Firebase-Plug-in

Das Firebase-Plug-in bietet mehrere Integrationen mit Firebase-Diensten:

  • Indexierungs- und Abruftools, die den Cloud Firestore-Vektorspeicher verwenden
  • Trace-Speicher mit Cloud Firestore
  • Ablauf mit Cloud Functions bereitstellen
  • Autorisierungsrichtlinien für Firebase Authentication-Nutzer
  • Telemetrieexport in die Operations Suite von Google Cloud

Installation

npm i --save @genkit-ai/firebase

Vorbereitung

  • 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.
  • Wenn Sie Workflows in Cloud Functions bereitstellen möchten, müssen Sie Ihr Projekt auf den Blaze-Tarif (Pay-as-you-go) umstellen.
  • Wenn Sie Code lokal ausführen möchten, der Telemetry-Daten exportiert, muss das Tool Google Cloud CLI installiert sein.

Konfiguration

Projekt-ID

Wenn Sie dieses Plug-in verwenden möchten, geben Sie es an, wenn Sie Genkit initialisieren:

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

const ai = genkit({
  plugins: [firebase({ projectId: "your-firebase-project" })],
});

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

  • Legen Sie projectId im Konfigurationsobjekt firebase() 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 weglassen: firebase()

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 das Dienstkonto Ihres Firebase-Projekts 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.

Telemetrie

Das Plug-in ist direkt vom Google Cloud-Plug-in abhängig und bietet daher die Möglichkeit, den Telemetrieexport in die Google Cloud Operations Suite zu aktivieren. So aktivieren Sie den Telemetrieexport:enableFirebaseTelemetry()

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

enableFirebaseTelemetry();

In der Dokumentation zum Google Cloud-Plug-in finden Sie alle Konfigurationsoptionen und die erforderlichen APIs, die im Projekt aktiviert werden müssen.

Nutzung

Dieses Plug-in bietet mehrere Integrationen mit Firebase-Diensten, die Sie gemeinsam oder einzeln verwenden können.

Cloud Firestore-Vektorspeicher

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

Retriever

Das firebase-Plug-in bietet eine praktische Funktion zum Definieren von Firestore-Abrufmethoden, defineFirestoreRetriever():

import {defineFirestoreRetriever} from "@genkit-ai/firebase";
import {retrieve} from "@genkit-ai/ai/retriever";

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

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

const yourRetrieverRef = defineFirestoreRetriever({
  name: "yourRetriever",
  firestore: getFirestore(app),
  collection: "yourCollection",
  contentField: "yourDataChunks",
  vectorField: "embedding",
  embedder: textEmbeddingGecko, // Import from '@genkit-ai/googleai' or '@genkit-ai/vertexai'
  distanceMeasure: "COSINE", // "EUCLIDEAN", "DOT_PRODUCT", or "COSINE" (default)
});

Um sie zu verwenden, übergeben Sie sie an die Funktion ai.retrieve():

const docs = await ai.retrieve({
  retriever: yourRetrieverRef,
  query: "look for something",
  options: { limit: 5 },
});

Folgende Abrufoptionen sind verfügbar:

  • limit: Gibt die Anzahl der übereinstimmenden Ergebnisse an, die zurückgegeben werden sollen.
  • where: Zusätzlich zur Vektorsuche können Sie Feld/Wert-Paare angeben, die übereinstimmen sollen (z.B. {category: 'food'}).
  • collection: Standardsammlung überschreiben, um z.B. nach einer untergeordneten Sammlung zu suchen.

Indexierung und Einbetten

Verwende einen Einbettungsgenerator zusammen mit dem Admin SDK, um deine Firestore-Sammlung zu füllen. Das Skript zum Einlesen von Menüs auf der Seite Erweiterte Generierung durch Abruf könnte 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,
    });
    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 Abfragen ab, die Sie stellen, und vom verwendeten Einbettungsmodell.

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

Weitere Informationen

Cloud Functions

Das Plug-in bietet den Konstruktor onFlow(), mit dem ein Ablauf erstellt wird, der von einer HTTPS-ausgelösten Cloud Functions for Firebase-Funktion unterstützt wird. Diese Funktionen entsprechen der aufrufbaren Funktionsoberfläche von Firebase und können mit den Cloud Functions-Client-SDKs aufgerufen werden.

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

Binden Sie den Ablauf mit der Firebase CLI ein:

firebase deploy --only functions

Die Funktion onFlow() bietet einige Optionen, die in defineFlow() nicht vorhanden sind:

  • httpsOptions: Ein HttpsOptions-Objekt, mit dem Ihre Cloud-Funktion konfiguriert wird:

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

  • enforceAppCheck: Wenn true, werden Anfragen mit fehlenden oder ungültigen App Check-Tokens abgelehnt.

  • consumeAppCheckToken: Wenn true, heben Sie das App Check-Token nach der Überprüfung auf.

    Weitere Informationen finden Sie unter Replay-Schutz.

Firebase Auth

Dieses Plug-in bietet eine Hilfsfunktion zum Erstellen von Autorisierungsrichtlinien für 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) => {
    // ...
  }
);

Wenn Sie eine Autorisierungsrichtlinie definieren möchten, geben Sie für firebaseAuth() eine Callback-Funktion an, die DecodedIdToken als einzigen Parameter annimmt. In dieser Funktion wird das Nutzertoken geprüft und ein Fehler ausgegeben, wenn der Nutzer keines der von dir festgelegten Kriterien erfüllt.

Weitere Informationen zu diesem Thema finden Sie unter Autorisierung und Integrität.