Wtyczka Firebase

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 usługi Uwierzytelnianie 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łącz Firebase w dotychczasowym projekcie Google Cloud za pomocą Konsola Firebase.
  • Ponadto, jeśli chcesz wdrożyć przepływy w Cloud Functions, musisz przenieś projekt na wyższy abonament na abonament Blaze z płatnościami 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. Możesz określić identyfikatora projektu Firebase na jeden z tych sposobów:

  • Ustaw projectId w obiekcie konfiguracji firebase().

  • Ustaw zmienną środowiskową GCLOUD_PROJECT. Jeśli pracujesz nad przepływem ze środowiska Google Cloud (Cloud Functions, Cloud Run itp.), Pole GCLOUD_PROJECT jest automatycznie ustawiane na identyfikator projektu środowiska.

    Jeśli ustawisz GCLOUD_PROJECT, możesz pominąć parametr konfiguracji: firebase()

Dane logowania

Aby podać dane logowania do Firebase, musisz też skonfigurować Google Cloud Domyślne dane logowania aplikacji. Aby podać dane logowania:

  • Jeśli uruchamiasz przepływ ze środowiska Google Cloud (Cloud Functions, Cloud Run itd.), to ustawienie jest ustawiane automatycznie.

  • W przypadku innych środowisk:

    1. Wygeneruj dane logowania do konta usługi dla projektu Firebase oraz pobierz plik klucza JSON. Możesz to zrobić na Konto usługi w konsoli Firebase.
    2. Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na plik ścieżki pliku JSON zawierającego klucz konta usługi. Możesz też ustawić zmienną środowiskową GCLOUD_SERVICE_ACCOUNT_CREDS na zawartość pliku JSON.

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, co pozwala stosowane 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 na temat wtyczki firebase i usługi Cloud Funkcja wyszukiwania wektorowego Firestore. Bardziej szczegółowe informacje znajdziesz na stronie Generowanie rozszerzonego przez wyszukiwanie. na temat wdrażania RAG za pomocą Genkit.

Korzystanie z GCLOUD_SERVICE_ACCOUNT_CREDS i Firestore

Jeśli korzystasz z danych logowania konta usługi, przekazując je bezpośrednio przez GCLOUD_SERVICE_ACCOUNT_CREDS, oraz używasz Firestore jako magazynu wektorów, podczas inicjowania musisz przekazać dane uwierzytelniające bezpośrednio do instancji Firestore. W zależności od kolejności inicjowania wtyczki dane logowania mogą zostać zainicjowane bezpośrednio do instancji Firestore.

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 zapewnia udogodnienie w zakresie definiowania Firestore retrievery, 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 podzbioru.

Indeksowanie i umieszczanie

Aby zapełnić kolekcję Firestore, użyj generatora wektorów dystrybucyjnych oraz Admin SDK. Na przykład skrypt przetwarzania menu ze strony Stronę generowania rozszerzonego przez wyszukiwanie można dostosować dla 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 efektywne wykonywanie zapytań kolekcji. (Zwróć uwagę, że określenie „indeks” odnosi się w tym miejscu do indeksów baz danych, a nie do abstrakcje indeksujące i retrievera Genkit).

Poprzedni przykład wymaga indeksowania pola embedding w naszej pracy. Aby utworzyć indeks:

  • Uruchom polecenie gcloud opisane w Utwórz indeks wektorów w jednym polu dokumentu 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ń, a używany przez Ciebie model umieszczania.

  • Możesz też wywołać funkcję retrieve(), a Firestore zwróci błąd z poprawnego polecenia, aby utworzyć indeks.

Więcej informacji

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 ślady w kolekcji o nazwie genkit-traces w domyślnej bazy 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 oparty na Funkcja w Cloud Functions dla Firebase aktywowana przez HTTPS. Funkcje te spełniają do usługi Firebase wywoływanego interfejsu funkcji i możesz użyć funkcji Pakiety SDK klienta Cloud Functions aby do nich zadzwonić.

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: HttpsOptions który jest używany do konfigurowania funkcji w Cloud Functions:

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

  • enforceAppCheck: gdy true, odrzuca prośby z brakującymi lub nieprawidłowymi sprawdzeniem aplikacji. tokeny.

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

    Zobacz Zabezpieczenie przed ponownym odtworzeniem.

Uwierzytelnianie Firebase

Ta wtyczka zapewnia funkcję pomocniczą do tworzenia zasad autoryzacji dotyczących Uwierzytelnianie 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 trwa DecodedIdToken. . W tej funkcji przejrzyj token użytkownika i wyślij zgłoszenie występuje wtedy, gdy użytkownik nie spełnia któregokolwiek z wymagań.

Więcej informacji znajdziesz w artykule Autoryzacja i integralność. w tym temacie.