Плагин Firebase

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

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

Установка

npm i --save @genkit-ai/firebase

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

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

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

Идентификатор проекта

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

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

const ai = genkit({
  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. Чтобы включить экспорт телеметрии, вызовите enableFirebaseTelemetry() :

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

enableFirebaseTelemetry();

Обратитесь к документации плагина 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)
});

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

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

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

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

Индексирование и внедрение

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

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

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

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

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

• См. страницу генерации с расширенным поиском для общего обсуждения индексаторов и ретриверов в Genkit.
• Дополнительную информацию о функции векторного поиска см. в разделе «Поиск с векторными вложениями» в документации Cloud Firestore.

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

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

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

firebase deploy --only functions

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

• httpsOptions : объект HttpsOptions , используемый для настройки вашей облачной функции:

  export const exampleFlow = onFlow(
    ai,
    {
      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(
  ai,
  {
    name: "exampleFlow",
    authPolicy: firebaseAuth((user) => {
      if (!user.email_verified) throw new Error("Requires verification!");
    }),
  },
  async (prompt) => {
    // ...
  }
);

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

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