Firebase-Plug-in

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

  • Firestore Vector Store: Verwenden Sie Firestore für die Indexierung und den Abruf mit Vektoreinbettungen.
  • Cloud Functions: Hier können Sie Abläufe als HTTPS-ausgelöste Funktionen bereitstellen.
  • Firebase Authentication: Implementieren Sie Autorisierungsrichtlinien.
  • Telemetrie: Telemetriedaten in die Operations Suite von Google Cloud exportieren und spezielle Ansichten in der Firebase Console aufrufen

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. In 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 Functions bereitstellen, führen Sie ein Upgrade Ihres Firebase-Projekts auf den Blaze-Tarif durch.
  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, die 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

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.

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. Ausführlichere Informationen 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-basierte Vektorabfragen 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. Standardwert ist 10.

  • where: (Record<string, any>)
    Weitere 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 zu wechseln.

Firestore mit Einbettungen füllen

Verwenden Sie einen Einbettungsgenerator zusammen mit dem Admin SDK, um Ihre Firestore-Sammlung zu füllen. Das Skript zum Aufnehmen von Menüs von 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 Befehl gcloud 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 und dem verwendeten Einbettungsmodell ab.

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

Weitere Informationen

Abläufe als Cloud Functions bereitstellen

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 Sie können sie mit den Cloud Functions-Client-SDKs aufrufen.

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 Authentication

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 Authentifizierungsrichtlinie definieren möchten, geben Sie für firebaseAuth() eine Callback-Funktion an, die DecodedIdToken als einzigen Parameter hat. In dieser Funktion wird das Nutzertoken geprüft und ein Fehler ausgegeben, wenn der Nutzer eines der von dir festgelegten Kriterien nicht erfüllt.

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