Плагин Firebase

Плагин Firebase обеспечивает несколько интеграций со службами Firebase:

  • Индексаторы и ретриверы с использованием векторного хранилища Cloud Firestore
  • Отслеживание хранилища с помощью Cloud Firestore
  • Развертывание потока с использованием облачных функций
  • Политики авторизации для пользователей аутентификации Firebase

Монтаж

npm i --save @genkit-ai/firebase

Предварительные условия

  • Для всех продуктов Firebase требуется проект Firebase. Вы можете создать новый проект или включить Firebase в существующем проекте Google Cloud с помощью консоли Firebase .
  • Кроме того, если вы хотите развернуть потоки в Cloud Functions, вам необходимо обновить свой проект до плана Blaze с оплатой по мере использования.

Конфигурация

Чтобы использовать этот плагин, укажите его при вызове configureGenkit() :

import {configureGenkit} from "@genkit-ai/core";
import {firebase} from "@genkit-ai/firebase";

configureGenkit({
  plugins: [firebase({projectId: "your-firebase-project"})],
});

Плагин требует, чтобы вы указали идентификатор вашего проекта Firebase. Вы можете указать идентификатор проекта Firebase одним из следующих способов:

  • Установите projectId в объекте конфигурации firebase() .

  • Установите переменную среды GCLOUD_PROJECT . Если вы запускаете поток из среды Google Cloud (Cloud Functions, Cloud Run и т. д.), GCLOUD_PROJECT автоматически устанавливается идентификатор проекта среды.

    Если вы установите GCLOUD_PROJECT , вы можете опустить параметр конфигурации: firebase()

Чтобы предоставить учетные данные Firebase, вам также необходимо настроить учетные данные Google Cloud Application по умолчанию. Чтобы указать свои учетные данные:

  • Если вы запускаете поток из среды Google Cloud (Cloud Functions, Cloud Run и т. д.), это устанавливается автоматически.

  • Для других сред:

    1. Создайте учетные данные сервисной учетной записи для вашего проекта Firebase и загрузите файл ключей JSON. Вы можете сделать это на странице учетной записи службы консоли Firebase.
    2. Задайте для переменной среды GOOGLE_APPLICATION_CREDENTIALS путь к файлу JSON, содержащему ключ вашей учетной записи службы.

Применение

Этот плагин обеспечивает несколько интеграций со службами Firebase, которые вы можете использовать вместе или по отдельности.

Векторный магазин Cloud Firestore

Вы можете использовать Cloud Firestore в качестве векторного хранилища для индексации и поиска RAG.

В этом разделе содержится информация, относящаяся к плагину firebase и функции векторного поиска Cloud Firestore. См. страницу генерации с расширенным поиском для более подробного обсуждения реализации RAG с использованием Genkit.

Плагин firebase предоставляет удобную функцию для определения ретриверов 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)
});

Чтобы использовать его, передайте его функции retrieve() :

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

Доступные варианты извлечения включают в себя:

  • limit : укажите количество совпадающих результатов, которые нужно вернуть.
  • where : пары поле/значение для сопоставления (например {category: 'food'} ) в дополнение к векторному поиску.
  • collection : переопределить коллекцию по умолчанию для поиска, например, поиска по подколлекции.

Чтобы пополнить свою коллекцию Firestore, используйте генератор встраивания вместе с Admin SDK. Например, сценарий приема меню со страницы генерации с расширенным поиском можно адаптировать для Firestore следующим образом:

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 зависит от индексов, обеспечивающих быстрый и эффективный запрос к коллекциям. (Обратите внимание, что «индекс» здесь относится к индексам базы данных, а не к абстракциям индексатора и получателя Genkit.)

Предыдущий пример требует, чтобы поле embedding было проиндексировано для работы. Чтобы создать индекс:

  • Запустите команду gcloud , описанную в разделе «Создание векторного индекса с одним полем» документации Firestore.

    Команда выглядит следующим образом:

    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

    Однако правильная конфигурация индексирования зависит от запросов, которые вы будете выполнять, и используемой модели внедрения.

  • В качестве альтернативы можно вызвать retrieve() , и Firestore выдаст ошибку с правильной командой для создания индекса.

Узнать больше

Хранилище трассировки Cloud Firestore

Вы можете использовать Cloud Firestore для хранения следов:

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

configureGenkit({
  plugins: [firebase()],
  traceStore: "firebase",
  enableTracingAndMetrics: true,
});

По умолчанию плагин сохраняет трассировки в коллекции под названием genkit-traces в базе данных проекта по умолчанию. Чтобы изменить любую настройку:

firebase({
  traceStore: {
    collection: "your-collection";
    databaseId: "your-db";
  }
})

При использовании хранилища трассировки на базе Firestore вам потребуется включить TTL для документов трассировки: https://firebase.google.com/docs/firestore/ttl

Облачные функции

Плагин предоставляет конструктор onFlow() , который создает поток, поддерживаемый функцией Cloud Functions for Firebase, запускаемой HTTPS. Эти функции соответствуют интерфейсу вызываемых функций Firebase, и для их вызова можно использовать клиентские SDK 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;
  }
);

Разверните свой поток с помощью Firebase CLI:

firebase deploy --only functions

Функция onFlow() имеет некоторые параметры, которых нет в defineFlow() :

  • httpsOptions : объект HttpsOptions используемый для настройки вашей облачной функции: js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );

  • enforceAppCheck : если true , отклонять запросы с отсутствующими или недействительными токенами проверки приложений .

  • consumeAppCheckToken : если true , сделать недействительным токен проверки приложения после его проверки.

    См. Защита от повтора .

Аутентификация Firebase

Этот плагин предоставляет вспомогательную функцию для создания политик авторизации вокруг Firebase Auth:

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

Чтобы определить политику аутентификации, предоставьте firebaseAuth() функцию обратного вызова, которая принимает DecodedIdToken в качестве единственного параметра. В этой функции проверяется токен пользователя и выдается ошибка, если пользователь не соответствует ни одному из требуемых критериев.

См. Авторизацию и целостность для более подробного обсуждения этой темы.