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.
  • Dane telemetryczne: eksportuj dane telemetryczne do pakietu usług Google Cloud Operations, 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 1 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ę do pliku JSON zawierającego klucz konta usługi. Możesz też ustawić zmienną środowiskową GCLOUD_SERVICE_ACCOUNT_CREDS na zawartość pliku JSON.

Funkcje i użytkowanie

Dane telemetryczne

Wtyczka Firebase zapewnia implementację telemetrii do wysyłania danych, ścieżek i dzienników do Firebase Genkit Monitoring.

Aby rozpocząć, zapoznaj się z przewodnikiem po rozpoczęciu, w którym znajdziesz instrukcje instalacji i konfiguracji.

Aby uwierzytelniać się w Google Cloud, zapoznaj się z przewodnikiem dotyczącym uwierzytelniania i autoryzacji.

Opcje konfiguracji znajdziesz w przewodniku po konfiguracji zaawansowanej.

Szczegółowe informacje o tym, które dane, ślady i logi Genkit są zbierane, znajdziesz w artykule Zbieranie danych telemetrycznych.

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 taki 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