Wtyczka Firebase

Wtyczka Firebase zapewnia integrację z usługami Firebase, dzięki czemu możesz tworzyć inteligentne i skalowalne aplikacje AI. Najważniejsze funkcje:

  • Firestore Vector Store: używaj Firestore do indeksowania i wyszukiwania za pomocą wektorów dystrybucyjnych.
  • Telemetria: eksportuj dane telemetryczne do pakietu operacyjnego Google Cloud, który obsługuje konsolę monitorowania Firebase Genkit.

Instalacja

Zainstaluj wtyczkę Firebase za pomocą npm:

npm install @genkit-ai/firebase

Wymagania wstępne

Konfigurowanie projektu Firebase

  1. Wszystkie usługi Firebase wymagają projektu Firebase. W konsoli Firebase możesz utworzyć nowy projekt lub włączyć Firebase w dotychczasowym projekcie Google Cloud.
  2. Jeśli wdrażasz przepływy za pomocą funkcji Cloud Functions, uaktualnij projekt Firebase do abonamentu Blaze.
  3. Jeśli chcesz uruchomić lokalnie kod, który eksportuje dane telemetryczne, musisz mieć zainstalowane narzędzie Google Cloud CLI.

Inicjowanie pakietu Firebase Admin SDK

W aplikacji musisz zainicjować pakiet SDK Firebase Admin. Wtyczka nie obsługuje tego automatycznie.

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

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

Aby korzystać z wtyczki, musisz podać identyfikator projektu Firebase. Identyfikator projektu Firebase możesz podać na jeden z tych sposobów:

  • W obiekcie konfiguracji initializeApp() ustaw wartość projectId, jak pokazano w powyższym fragmencie kodu.

  • Ustaw zmienną środowiskową GCLOUD_PROJECT. Jeśli uruchamiasz przepływ z środowiska Google Cloud (Cloud Functions, Cloud Run itp.), zmienna GCLOUD_PROJECT jest automatycznie ustawiana na identyfikator projektu tego środowiska.

    Jeśli ustawisz GCLOUD_PROJECT, możesz pominąć parametr konfiguracji w pliku initializeApp().

Dane logowania

Aby podać dane logowania Firebase, musisz też skonfigurować domyślne dane logowania do aplikacji Google Cloud. Aby określić swoje dane uwierzytelniające:

  • Jeśli uruchamiasz przepływ z środowiska Google Cloud (Cloud Functions, Cloud Run itp.), ta wartość jest ustawiana automatycznie.

  • W innych środowiskach:

    1. Wygeneruj dane logowania do konta usługi dla swojego projektu Firebase i pobierz plik klucza JSON. Możesz to zrobić na stronie Konto usługi w konsoli Firebase.
    2. Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę pliku JSON zawierającego klucz konta usługi lub ustaw zmienną środowiskową GCLOUD_SERVICE_ACCOUNT_CREDS na zawartość pliku JSON.

Funkcje i użytkowanie

Dane telemetryczne

Genkit Monitoring w Firebase korzysta z pakietu operacyjnego Google Cloud. Wymaga to włączenia interfejsów API związanych z telemetrią w Twoim projekcie. Więcej informacji znajdziesz w dokumentacji wtyczki Google Cloud.

Przypisz te role do „domyślnego konta usługi obliczeniowej” w konsoli Google Cloud IAM:

  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  • Cloud Trace Agent (roles/cloudtrace.agent)
  • Zapisujący logi (roles/logging.logWriter)

Aby włączyć wywołanie eksportowania danych telemetrycznych: enableFirebaseTelemetry()

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

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

Ta wtyczka udostępnia opcje konfiguracji wtyczce Google Cloud.

Cloud Firestore możesz używać jako magazynu wektorów do indeksowania i wyszukiwania w ramach RAG.

Ta sekcja zawiera informacje dotyczące wtyczki firebase i funkcji wyszukiwania wektorów w Cloud Firestore. Więcej informacji o wdrażaniu RAG za pomocą Genkit znajdziesz na stronie Generowanie rozszerzone przez wyszukiwanie w zapisanych informacjach.

Korzystanie z GCLOUD_SERVICE_ACCOUNT_CREDS i Firestore

Jeśli używasz danych logowania konta usługi, przekazując je bezpośrednio za pomocą funkcji GCLOUD_SERVICE_ACCOUNT_CREDS, i używasz Firestore jako wektorowego magazynu danych, musisz przekazać dane logowania bezpośrednio do instancji Firestore podczas inicjalizacji. W przeciwnym razie singleton może zostać zainicjowany za pomocą domyślnych danych logowania aplikacji w zależności od kolejności inicjowania wtyczki.

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

Definiowanie funkcji pobierania Firestore

Użyj funkcji defineFirestoreRetriever(), aby utworzyć funkcję pobierania zapytań opartych na wektorach 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'
});

Pobieranie dokumentów

Aby pobrać dokumenty za pomocą zdefiniowanego retrievera, przekaż instancję retrievera i opcje zapytania do 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
  },
});

Dostępne opcje odzyskiwania

Do pola options w elementach ai.retrieve można przekazać te opcje:

  • limit: (liczba)określa maksymalną liczbę dokumentów do pobrania. Wartość domyślna to 10.

  • where: (Record<string, any>) Dodaj dodatkowe filtry na podstawie pól Firestore. Przykład:

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

  • collection: (ciąg) Zastąpić domyślną kolekcję określoną w konfiguracji retrievera.

  • Jest to przydatne podczas wysyłania zapytań do podkolekcji lub dynamicznego przełączania się między

  • kolekcje.

Wypełnianie Firestore za pomocą elementów wbudowanych

Aby wypełnić kolekcję Firestore, użyj generatora umieszczania i pakietu Admin SDK. Na przykład skrypt przetwarzania menu z strony Generowanie z użyciem rozszerzonego wyszukiwania można dostosować do Firehose w ten sposób:

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 korzysta z indeksu, aby zapewniać szybkie i wydajne wykonywanie zapytań dotyczących kolekcji. (Pamiętaj, że „indeks” odnosi się tutaj do indeksów baz danych, a nie do abstrakcji indeksatora i pobierania Genkit).

W poprzednim przykładzie pole embedding musi być zindeksowane, aby działać. Aby utworzyć indeks:

  • Uruchom polecenie gcloud opisane w sekcji Tworzenie indeksu wektorowego pojedynczego pola w dokumentacji Firestore.

    Polecenie wygląda tak:

    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

    Prawidłowa konfiguracja indeksowania zależy jednak od zapytań, które wysyłasz, i używanego modelu umieszczania.

  • Możesz też wywołać funkcję ai.retrieve(), a Firestore zwróci błąd z prawidłowym poleceniem do utworzenia indeksu.

Więcej informacji

Wdrażanie przepływów jako funkcji Cloud Functions

Aby wdrożyć przepływ za pomocą Cloud Functions, użyj wbudowanego w bibliotekę Firebase Functions obsługi genkit. Metoda onCallGenkit umożliwia tworzenie funkcji wywoływalnej z poziomu przepływu. Obsługuje automatycznie strumieniowanie i żądania JSON. Do ich wywoływania możesz użyć pakietów SDK klienta Cloud Functions.

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

Wdróż przepływ za pomocą wiersza poleceń Firebase:

firebase deploy --only functions