Firebase 插件

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

• 使用 Cloud Firestore 矢量存储区的索引器和检索器
• 使用 Cloud Firestore 跟踪存储情况
• 使用 Cloud Functions 进行流部署
• Firebase Authentication 用户的授权政策

安装

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 项目 ID。您可以通过以下任一方式指定 Firebase 项目 ID：

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

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

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

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

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

• 对于其他环境：

  1. 为您的 Firebase 项目生成服务帐号凭据，并下载 JSON 密钥文件。您可以在 Firebase 控制台的服务帐号页面上执行此操作。
  2. 将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务帐号密钥的 JSON 文件的文件路径。

用量

此插件提供多种 Firebase 服务集成，您既可以单独使用这些服务，也可以单独使用这些服务。

Cloud Firestore 矢量存储

您可以使用 Cloud Firestore 作为 RAG 索引和检索的矢量存储区。

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

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

• 运行 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
  

  但是，正确的索引配置取决于您将进行的查询和使用的嵌入模型。

• 或者，您也可以调用 retrieve()，Firestore 将抛出一个错误并显示正确的命令来创建索引。

了解详情

• 请参阅检索增强生成页面，了解 Genkit 中索引器和检索器的一般讨论。
• 如需详细了解矢量搜索功能，请参阅 Cloud 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

Cloud Functions

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

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：用于配置 Cloud Functions 函数的 HttpsOptions 对象： js export const exampleFlow = onFlow( { name: "exampleFlow", httpsOptions: { cors: true, }, // ... }, async (prompt) => { // ... } );

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

• consumeAppCheckToken：当 true 时，在验证 App Check 令牌后使其失效。

  请参阅重放攻击防范。

Firebase Auth

此插件提供了一个辅助函数，用于创建与 Firebase 身份验证相关的授权政策：

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 作为其唯一参数。在此函数中，检查用户令牌，如果用户不符合您要求的任何条件，则抛出错误。

有关此主题的更全面的讨论，请参阅授权和完整性。