Genkit for Node.js 1.0 is now available and production-ready! Learn more

Эта страница переведена с помощью Cloud Translation API.

Плагин Firebase

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

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

Установка

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

npm install @genkit-ai/firebase

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

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

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

Инициализация Firebase Admin SDK

Вы должны инициализировать 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.

Особенности и использование

Телеметрия

Firebase Genkit Monitoring работает на базе облачного операционного пакета Google. Для этого необходимо, чтобы в вашем проекте были включены API, связанные с телеметрией. Для получения более подробной информации обратитесь к документации плагина Google Cloud .

Предоставьте следующие роли «учетной записи вычислительной службы по умолчанию» в консоли Google Cloud IAM :

Модуль записи метрик мониторинга (roles/monitoring.metricWriter)
Агент Cloud Trace (roles/cloudtrace.agent)
Модуль записи журналов (roles/logging.logWriter)

Чтобы включить экспорт телеметрии, вызовите enableFirebaseTelemetry() :

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

enableFirebaseTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
});

Этот плагин использует те же параметры конфигурации, что и плагин Google Cloud .

Векторный поиск 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);
}

Определение ретривера 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 : (Record<string, Any>) Добавьте дополнительные фильтры на основе полей 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,
    }))[0].embedding;
    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.

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

Чтобы развернуть поток с помощью Cloud Functions, используйте встроенную поддержку genkit библиотеки Firebase Functions. Метод onCallGenkit позволяет создавать вызываемую функцию из потока. Он автоматически поддерживает потоковую передачу и запросы JSON. Для их вызова можно использовать клиентские SDK Cloud Functions .

import { onCallGenkit } from 'firebase-functions/https';
import { defineSecret } from 'firebase-functions/params';

export const exampleFlow = ai.defineFlow({
  name: "exampleFlow",
}, async (prompt) => {
    // Flow logic goes here.

    return response;
  }
);

// WARNING: This has no authentication or app check protections.
// See github.com/firebase/genkit/blob/main/docs/auth.md for more information.
export const example = onCallGenkit({ secrets: [apiKey] }, exampleFlow);

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

firebase deploy --only functions