Плагин Firebase

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

  • Магазин векторов Firestore : используйте Firestore для индексации и поиска с векторными вложениями.
  • Облачные функции : развертывание потоков как функций, запускаемых по протоколу HTTPS.
  • Аутентификация Firebase : реализация политик авторизации.
  • Телеметрия : экспортируйте телеметрию в операционный пакет Google Cloud и просматривайте специализированные представления в консоли Firebase.

Установка

Установите плагин Firebase с помощью npm:

npm install @genkit-ai/firebase

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

Настройка проекта Firebase

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

Инициализация SDK администратора Firebase

Вы должны инициализировать Firebase Admin SDK в своем приложении. Плагин не обрабатывает это автоматически. 

import { initializeApp } from 'firebase-admin/app';

initializeApp({
  projectId: 'your-project-id',
});

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

  • Установите projectId в объекте конфигурации initializeApp() как показано в приведенном выше фрагменте.

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

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

Реквизиты для входа

Чтобы предоставить учетные данные 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, которые необходимо включить в проекте.

Вы можете использовать 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);
}

Определение ретривера Firestore

Используйте defineFirestoreRetriever() чтобы создать средство извлечения для векторных запросов Firestore. 

import { defineFirestoreRetriever } from '@genkit-ai/firebase';
import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

const app = initializeApp();
const firestore = getFirestore(app);

const retriever = defineFirestoreRetriever(ai, {
  name: 'exampleRetriever',
  firestore,
  collection: 'documents',
  contentField: 'text', // Field containing document content
  vectorField: 'embedding', // Field containing vector embeddings
  embedder: yourEmbedderInstance, // Embedder to generate embeddings
  distanceMeasure: 'COSINE', // Default is 'COSINE'; other options: 'EUCLIDEAN', 'DOT_PRODUCT'
});

Получить документы

Чтобы получить документы с помощью определенного средства извлечения, передайте экземпляр средства извлечения и параметры запроса в ai.retrieve . 

const docs = await ai.retrieve({
  retriever,
  query: 'search query',
  options: {
    limit: 5, // Options: Return up to 5 documents
    where: { category: 'example' }, // Optional: Filter by field-value pairs
    collection: 'alternativeCollection', // Optional: Override default collection
  },
});

Доступные варианты получения

Следующие параметры могут быть переданы в поле options в ai.retrieve :

  • limit : (число)
    Укажите максимальное количество документов для получения. По умолчанию — 10 .

  • where : (Запись<строка, любая>)
    Добавьте дополнительные фильтры на основе полей Firestore. Пример:

    where: { category: 'news', status: 'published' }

  • collection : (строка)
    Переопределить коллекцию по умолчанию, указанную в конфигурации средства извлечения. Это полезно для запроса подколлекций или динамического переключения между коллекциями.

Заполните Firestore вставками

Чтобы пополнить свою коллекцию 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 выдаст ошибку с правильной командой для создания индекса.

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

Развертывание потоков как облачных функций

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

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