Wtyczka Firebase

Wtyczka Firebase zapewnia integrację z usługami Firebase, co umożliwia tworzenie inteligentnych i skalowalne aplikacji AI. Najważniejsze funkcje:

  • Firestore Vector Store: używaj Firestore do indeksowania i wyszukiwania za pomocą wektorów dystrybucyjnych.
  • Cloud Functions: wdróż przepływy jako funkcje aktywowane przez HTTPS.
  • Uwierzytelnianie Firebase: wdrożenie zasad autoryzacji.
  • Telemetria: eksportuj dane telemetryczne do pakietu operacyjnego Google Cloud i wyświetl widoki specjalistyczne w konsoli Firebase.

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ą 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 otoczenia Google Cloud (np. Cloud Functions czy Cloud Run), 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

Ten wtyczka jest bezpośrednio zależna od wtyczki Google Cloud, dlatego zawiera postanowienia umożliwiające eksportowanie danych telemetrycznych do pakietu operacyjnego Google Cloud. Aby włączyć wywołanie eksportowania danych telemetrycznych: enableFirebaseTelemetry()

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

enableFirebaseTelemetry();

Informacje o wszystkich opcjach konfiguracji i wymaganych interfejsach API, które należy włączyć w projekcie, znajdziesz w dokumentacji wtyczki Google Cloud.

Cloud Firestore możesz używać jako magazynu wektorów do indeksowania i wyszukiwania 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 generowania rozszerzonego 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 magazynu wektorów, 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 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 w przypadku wysyłania zapytań do podzbiorów lub dynamicznego przełączania się między zbiorami.

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 generowania wzbogaconego o wyszukiwanie można dostosować do Firestore 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,
    });
    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 indektów, aby umożliwiać 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 będziesz wysyłać, 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

Wtyczka udostępnia konstruktor onFlow(), który tworzy przepływ obsługiwany przez funkcję w Cloud Functions dla Firebase aktywowaną przez HTTPS. Te funkcje są zgodne z interfejsem wywoływalnych funkcji Firebase i można je wywoływać za pomocą pakietów SDK klienta Cloud Functions.

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

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

firebase deploy --only functions

Funkcja onFlow() ma opcje niedostępne w funkcji defineFlow():

  • httpsOptions: obiekt HttpsOptions służący do konfigurowania funkcji w Cloud Functions:

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

  • enforceAppCheck: gdy true, odrzucaj żądania, w których brakuje tokenów Sprawdzania aplikacji lub są one nieprawidłowe.

  • consumeAppCheckToken: gdy true, unieważnij token Sprawdzania aplikacji po jego zweryfikowaniu.

    Zobacz Ochrona przed odtwarzaniem.

Uwierzytelnianie Firebase

Ten wtyczka zawiera funkcję pomocniczą do tworzenia zasad autoryzacji w Uwierzytelnianiu Firebase:

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) => {
    // ...
  }
);

Aby zdefiniować zasady uwierzytelniania, podaj w funkcji firebaseAuth() funkcję wywołania zwrotnego, która ma DecodedIdToken jako jedyny parametr. W ramach tej funkcji sprawdzaj token użytkownika i wyrzucaj błąd, jeśli użytkownik nie spełnia któregokolwiek z wymaganych kryteriów.

Więcej informacji na ten temat znajdziesz w artykule Autoryzacja i nienaruszalność danych.