Wtyczka Firebase

Wtyczka Firebase udostępnia kilka integracji z usługami Firebase:

  • Indeksatory i wyszukiwarki korzystające z magazynu wektorów Cloud Firestore
  • Śledzenie miejsca w chmurze przy użyciu Cloud Firestore
  • Wdrażanie przepływu za pomocą Cloud Functions
  • Zasady autoryzacji dla użytkowników Uwierzytelniania Firebase
  • Eksportowanie danych telemetrycznych do pakietu operacyjnego Google Cloud

Instalacja

npm i --save @genkit-ai/firebase

Wymagania wstępne

  • Wszystkie usługi Firebase wymagają projektu Firebase. Możesz utworzyć nowy projekt lub włączyć Firebase w dotychczasowym projekcie Google Cloud za pomocą konsoli Firebase.
  • Jeśli chcesz wdrażać przepływy w Cloud Functions, musisz ulepszyć swój projekt do abonamentu Blaze opłaty według wykorzystania.
  • Jeśli chcesz uruchomić lokalnie kod, który eksportuje dane telemetryczne, musisz mieć zainstalowane narzędzie Google Cloud CLI.

Konfiguracja

Identyfikator projektu

Aby użyć tej wtyczki, określ ją podczas inicjowania Genkit:

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

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

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

  • Ustaw wartość projectId w obiekcie konfiguracji firebase().

  • 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 parametr GCLOUD_PROJECT, możesz pominąć parametr konfiguracji:firebase()

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 zmienną środowiskową GCLOUD_SERVICE_ACCOUNT_CREDS na zawartość pliku JSON.

Dane telemetryczne

Ten wtyczek jest bezpośrednio zależny od wtyczka Google Cloud, dlatego zawiera opcje 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();

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

Wykorzystanie

Ta wtyczka zapewnia kilka integracji z usługami Firebase, które możesz używać razem lub osobno.

Magazyn wektorów Cloud Firestore

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

Retrievery

Wtyczka firebase udostępnia funkcję ułatwiającą definiowanie funkcji pobierania Firestore, 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)
});

Aby go użyć, prześlij go do funkcji ai.retrieve():

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

Dostępne opcje pobierania:

  • limit: określ liczbę pasujących wyników do zwrócenia.
  • where: pary pole-wartość do dopasowania (np. {category: 'food'}) oprócz wyszukiwania wektorowego.
  • collection: zastąpienie domyślnej kolekcji, aby wyszukać np. podkolekcję.

Indeksowanie i osadzanie

Aby wypełnić kolekcję Firestore, użyj generatora elementów i pakietu Admin SDK. Na przykład skrypt przetwarzania menu z strony generowanie za pomocą rozszerzonego wyszukiwania 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 indeksów, 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 wyszukiwarki Genkit).

W poprzednim przykładzie pole embedding musi być zindeksowane do pracy. 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 od modelu umieszczania, którego używasz.

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

Więcej informacji

Cloud Functions

Wtyczka udostępnia konstruktor onFlow(), który tworzy przepływ obsługiwany przez funkcję Cloud Functions for Firebase aktywowaną przez HTTPS. Te funkcje są zgodne z interfejsem wywoływanych 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 HttpsOptionsużywany do konfigurowania funkcji w Cloud Functions:

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

  • enforceAppCheck: gdy true, odrzucaj żądania z brakiem lub nieprawidłowymi tokenami Sprawdzania aplikacji.

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

    Zobacz Ochrona przed odtwarzaniem.

Uwierzytelnianie Firebase

Ten wtyczka udostępnia funkcję pomocniczą do tworzenia zasad autoryzacji w 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) => {
    // ...
  }
);

Aby zdefiniować zasady uwierzytelniania, podaj funkcji wywołania zwrotnego firebaseAuth() funkcję wywołania zwrotnego, która przyjmuje DecodedIdToken jako jedyny parametr. W tej funkcji sprawdź token użytkownika i wyrzuć 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.