Firebase 插件

Firebase 插件提供了多种与 Firebase 服务的集成：

  • 使用 Cloud Firestore 矢量存储空间的索引创建器和检索器
  • 使用 Cloud Firestore 存储轨迹
  • 使用 Cloud Functions 部署流程
  • Firebase Authentication 用户的授权政策
  • 将遥测数据导出到 Google Cloud 的运维套件

安装

npm i --save @genkit-ai/firebase

前提条件

  • 所有 Firebase 产品都需要 Firebase 项目。您可以使用 Firebase 控制台创建新项目，也可以在现有 Google Cloud 项目中启用 Firebase。
  • 此外，如果您想将流程部署到 Cloud Functions 函数，则必须将项目升级为采用随用随付 Blaze 方案。
  • 如果您想在本地运行用于导出遥测数据的代码，则需要安装 Google Cloud CLI 工具。

配置

项目 ID

如需使用此插件，请在初始化 Genkit 时指定该插件：

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

const ai = genkit({
  plugins: [firebase({ projectId: "your-firebase-project" })],
});

该插件要求您指定 Firebase 项目 ID。您可以通过以下任一方式指定 Firebase 项目 ID：

  • 在 firebase() 配置对象中设置 projectId。

  • 设置 GCLOUD_PROJECT 环境变量。如果您要从 Google Cloud 环境（Cloud Functions、Cloud Run 等）运行 flow，GCLOUD_PROJECT 会自动设置为该环境的项目 ID。

    如果您设置了 GCLOUD_PROJECT，则可以省略配置参数：firebase()

凭据

如需提供 Firebase 凭据，您还需要设置 Google Cloud 应用默认凭据。如需指定凭据，请按照以下所述操作：

  • 如果您要从 Google Cloud 环境（Cloud Functions、Cloud Run 等）运行 flow，系统会自动设置。

  • 对于其他环境：

    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();

如需了解所有配置选项以及需要在项目中启用的必要 API，请参阅 Google Cloud 插件文档。

用法

此插件提供了多种与 Firebase 服务的集成，您可以将这些集成组合使用，也可以单独使用。

Cloud Firestore 矢量存储

您可以将 Cloud Firestore 用作 RAG 索引和检索的矢量存储空间。

本部分包含与 firebase 插件和 Cloud Firestore 的矢量搜索功能相关的信息。 如需详细了解如何使用 Genkit 实现 RAG，请参阅检索增强生成页面。

使用 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 字段进行编制索引才能正常运行。如需创建索引，请执行以下操作：

  • 运行 Firestore 文档中创建单字段向量索引部分中所述的 gcloud 命令。

    该命令如下所示：

    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 将抛出一个错误，并附上用于创建索引的正确命令。

了解详情

Cloud Functions

该插件提供了 onFlow() 构造函数，用于创建由 Cloud Functions for Firebase HTTPS 触发的函数支持的流程。这些函数符合 Firebase 的 Callable 函数接口，您可以使用 Cloud Functions 客户端 SDK 调用它们。

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：用于配置 Cloud Functions 函数的 HttpsOptions 对象：

    export const exampleFlow = onFlow(
  ai,
  {
    name: "exampleFlow",
    httpsOptions: {
      cors: true,
    },
    // ...
  },
  async (prompt) => {
    // ...
  }
);

  • enforceAppCheck：如果为 true，则拒绝缺少或无效的 App Check 令牌的请求。

  • consumeAppCheckToken：如果为 true，则在验证 App Check 令牌后将其失效。

    请参阅重放攻击防范。

Firebase Auth

此插件提供了一个辅助函数，用于围绕 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 作为其唯一参数的回调函数。在此函数中，检查用户令牌，如果用户未满足您要要求的任何条件，则抛出错误。

如需详细了解此主题，请参阅授权和完整性。