Wtyczka Firebase umożliwia integrację z usługami Firebase na kilka sposobów:
- Indeksatory i moduły pobierania danych korzystające z magazynu wektorów Cloud Firestore
- Śledź miejsce na dane za pomocą Cloud Firestore
- Wdrażanie przepływu za pomocą Cloud Functions
- Zasady autoryzacji dla użytkowników Uwierzytelniania Firebase
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 istniejącym projekcie Google Cloud, korzystając z konsoli Firebase.
- Ponadto, jeśli chcesz wdrożyć przepływy w Cloud Functions, musisz przenieść swój projekt na abonament Blaze z płatnością według wykorzystania.
Konfiguracja
Identyfikator projektu
Aby używać tej wtyczki, określ ją, gdy wywołujesz configureGenkit()
:
import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";
configureGenkit({
plugins: [firebase({projectId: "your-firebase-project"})],
});
Wtyczka wymaga podania identyfikatora projektu Firebase. Identyfikator projektu Firebase możesz określić na jeden z tych sposobów:
Ustaw
projectId
w obiekcie konfiguracjifirebase()
.Ustaw zmienną środowiskową
GCLOUD_PROJECT
. Jeśli uruchamiasz przepływ ze środowiska Google Cloud (Cloud Functions, Cloud Run itp.), wartośćGCLOUD_PROJECT
jest automatycznie ustawiona na identyfikator projektu tego środowiska.Jeśli ustawisz
GCLOUD_PROJECT
, możesz pominąć parametr konfiguracji:firebase()
Aby podać dane logowania do Firebase, musisz też skonfigurować domyślne dane logowania do aplikacji Google Cloud. Aby podać dane logowania:
Jeśli uruchamiasz przepływ ze środowiska Google Cloud (Cloud Functions, Cloud Run itp.), ustawienie to jest ustawiane automatycznie.
W przypadku innych środowisk:
- Wygeneruj dane logowania do konta usługi dla projektu Firebase i pobierz plik klucza JSON. Możesz to zrobić na stronie Konto usługi w konsoli Firebase.
- Ustaw zmienną środowiskową
GOOGLE_APPLICATION_CREDENTIALS
na ścieżkę pliku JSON zawierającego klucz konta usługi.
Dane telemetryczne
Wtyczka jest bezpośrednio zależna od wtyczki Google Cloud i dlatego ma funkcje umożliwiające eksport danych telemetrycznych do pakietu operacyjnego Google Cloud. Aby włączyć eksportowanie danych telemetrycznych, ustaw enableTracingAndMetrics
na true
i dodaj sekcję telemetrii do konfiguracji Genkit:
import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";
configureGenkit({
plugins: [firebase()],
enableTracingAndMetrics: true,
telemetry: {
instrumentation: 'firebase',
logger: 'firebase',
},
});
Informacje o wszystkich opcjach konfiguracji i interfejsach API, które musisz włączyć w projekcie, znajdziesz w dokumentacji wtyczki Google Cloud.
Wykorzystanie
Zapewnia ona kilka integracji z usługami Firebase, których można używać razem lub osobno.
Magazyn wektorów Cloud Firestore
Cloud Firestore może być używany jako magazyn wektorowy na potrzeby indeksowania i pobierania RAG.
Ta sekcja zawiera informacje dotyczące wtyczki firebase
i funkcji wyszukiwania wektorowego w Cloud Firestore.
Na stronie generowania rozszerzonego przez wyszukiwanie znajdziesz bardziej szczegółowe omówienie wdrażania RAG za pomocą Genkit.
Wtyczka firebase
zapewnia wygodną funkcję definiowania źródeł 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ć, przekaż go do funkcji retrieve()
:
const docs = await 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ąp kolekcję domyślną, aby wyszukać np. wyszukiwanie w kolekcji podrzędnej.
Aby wypełnić kolekcję Firestore, użyj generatora umieszczania oraz pakietu Admin SDK. Na przykład skrypt przetwarzania menu ze strony Generowanie rozszerzonego przez wyszukiwanie może zostać dostosowany do Firestore w następujący sposób:
import { configureGenkit } from "@genkit-ai/core";
import { embed } from "@genkit-ai/ai/embedder";
import { defineFlow, run } from "@genkit-ai/flow";
import { textEmbeddingGecko, vertexAI } 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 * as z from "zod";
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: textEmbeddingGecko,
};
configureGenkit({
plugins: [vertexAI({ location: "us-central1" })],
enableTracingAndMetrics: false,
});
const app = initializeApp({ credential: applicationDefault() });
const firestore = getFirestore(app);
export const indexMenu = defineFlow(
{
name: "indexMenu",
inputSchema: z.string().describe("PDF file path"),
outputSchema: z.void(),
},
async (filePath: string) => {
filePath = path.resolve(filePath);
// Read the PDF.
const pdfTxt = await run("extract-text", () =>
extractTextFromPdf(filePath)
);
// Divide the PDF text into segments.
const chunks = await run("chunk-it", async () => chunk(pdfTxt));
// Add chunks to the index.
await run("index-chunks", async () => indexToFirestore(chunks));
}
);
async function indexToFirestore(data: string[]) {
for (const text of data) {
const embedding = await 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 zależy od indeksów, aby umożliwić szybkie i sprawne wykonywanie zapytań dotyczących kolekcji. (Zwróć uwagę, że słowo „index” odnosi się w tym miejscu do indeksów baz danych, a nie do abstrakcyjnych indeksów i mechanizmów zbierających dane z Genkita).
Poprzedni przykład wymaga zindeksowania pola embedding
. Aby utworzyć indeks:
Uruchom polecenie
gcloud
opisane w sekcji Tworzenie indeksu wektorów z jednym polem w dokumentach 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 wykonywanych zapytań i używanego modelu umieszczania.
Możesz też wywołać metodę
retrieve()
, a Firestore zgłosi błąd z prawidłowym poleceniem utworzenia indeksu.
Więcej informacji
- Na stronie Generowanie rozszerzonego przez wyszukiwanie znajdziesz ogólne informacje o indekserach i mechanizmach pobierania w Genkit.
- Więcej informacji o funkcji wyszukiwania wektorowego znajdziesz w dokumentacji Cloud Firestore na temat wyszukiwania z wektorami dystrybucyjnymi.
Miejsce na dane logu w Cloud Firestore
W Cloud Firestore możesz przechowywać logi czasu:
import {firebase} from "@genkit-ai/firebase";
configureGenkit({
plugins: [firebase()],
traceStore: "firebase",
enableTracingAndMetrics: true,
});
Domyślnie wtyczka przechowuje logi czasu w kolekcji o nazwie genkit-traces
w domyślnej bazie danych projektu. Aby zmienić któreś z tych ustawień:
firebase({
traceStore: {
collection: "your-collection";
databaseId: "your-db";
}
})
Jeśli korzystasz z pamięci śledzenia bazującej na Firestore, włącz wartość TTL dla dokumentów śledzenia: https://firebase.google.com/docs/firestore/ttl
Cloud Functions
Wtyczka udostępnia konstruktor onFlow()
, który tworzy przepływ wspierany przez funkcję wyzwalaną przez HTTPS w Cloud Functions dla Firebase. Funkcje te są zgodne z wywoływanym interfejsem funkcji Firebase i możesz je wywoływać za pomocą pakietów SDK klienta Cloud Functions.
import {firebase} from "@genkit-ai/firebase";
import {onFlow, noAuth} from "@genkit-ai/firebase/functions";
configureGenkit({
plugins: [firebase()],
});
export const exampleFlow = onFlow(
{
name: "exampleFlow",
authPolicy: noAuth(), // WARNING: noAuth() creates an open endpoint!
},
async (prompt) => {
// Flow logic goes here.
return response;
}
);
Wdróż przepływ za pomocą interfejsu wiersza poleceń Firebase:
firebase deploy --only functions
Niektóre opcje funkcji onFlow()
są niedostępne w defineFlow()
:
httpsOptions
: obiektHttpsOptions
używany do konfigurowania funkcji w Cloud Functions:js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );
enforceAppCheck
: gdytrue
odrzuca żądania z brakującymi lub nieprawidłowymi tokenami Sprawdzania aplikacji.consumeAppCheckToken
: gdytrue
, unieważni token Sprawdzania aplikacji po jego zweryfikowaniu.
Uwierzytelnianie Firebase
Udostępnia ona funkcję pomocniczą do tworzenia zasad autoryzacji związanych z Uwierzytelnianiem Firebase:
import {firebaseAuth} from "@genkit-ai/firebase/auth";
export const exampleFlow = onFlow(
{
name: "exampleFlow",
authPolicy: firebaseAuth((user) => {
if (!user.email_verified) throw new Error("Requires verification!");
}),
},
async (prompt) => {
// ...
}
);
Aby zdefiniować zasadę uwierzytelniania, podaj w firebaseAuth()
funkcję wywołania zwrotnego, która jako jedyny parametr przyjmuje DecodedIdToken
. W tej funkcji sprawdza się token użytkownika. Jeśli użytkownik nie spełni któregokolwiek z wymagań, zgłasza błąd.
Więcej informacji na ten temat znajdziesz w artykule Autoryzacja i integralność.