Плагин 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, который содержит ключ вашей учетной записи службы, или вы можете установить переменную среды GCLOUD_SERVICE_ACCOUNT_CREDS для содержимого файла JSON.

Телеметрия

Плагин напрямую зависит от плагина Google Cloud и, следовательно, имеет возможности для экспорта телеметрии в пакет операций Google Cloud. Чтобы включить экспорт телеметрии, установите для enableTracingAndMetrics значение true и добавьте раздел телеметрии в конфигурацию Genkit: 

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

configureGenkit({
  plugins: [firebase()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'firebase',
    logger: 'firebase',
  },
});

Обратитесь к документации плагина Google Cloud для получения информации обо всех параметрах конфигурации и необходимых API, которые необходимо включить в проекте.

Использование

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

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

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

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

Использование GCLOUD_SERVICE_ACCOUNT_CREDS и Firestore

Если вы используете учетные данные сервисной учетной записи, передавая учетные данные непосредственно через GCLOUD_SERVICE_ACCOUNT_CREDS , а также используете Firestore в качестве векторного хранилища, вам нужно будет передать учетные данные непосредственно экземпляру 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);
}

Ретриверы

Плагин 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 используемый для настройки вашей облачной функции: 

    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 в качестве единственного параметра. В этой функции проверяется токен пользователя и выдается ошибка, если пользователь не соответствует ни одному из требуемых критериев.

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