Firebase 外掛程式

Firebase 外掛程式提供多種 Firebase 服務整合功能：

  • 使用 Cloud Firestore 向量儲存空間的索引器和擷取器
  • 使用 Cloud Firestore 追蹤儲存空間
  • 使用 Cloud Functions 部署工作流程
  • Firebase 驗證使用者的授權政策
  • 將遙測資料匯出至 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 函式、Cloud Run 等) 執行流程，GCLOUD_PROJECT 會自動設為該環境的專案 ID。

    如果您設定 GCLOUD_PROJECT，可以省略設定參數： firebase()

憑證

如要提供 Firebase 憑證，您也必須設定 Google Cloud 應用程式預設憑證。如要指定憑證，請按照下列步驟操作：

  • 如果您是從 Google Cloud 環境 (Cloud Functions、Cloud Run 等) 執行流程，系統會自動設定這項屬性。

  • 適用於其他環境：

    1. 為 Firebase 專案產生服務帳戶憑證，並下載 JSON 金鑰檔案。您可以在 Firebase 主控台的「Service account」頁面中執行這項操作。
    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 向量搜尋功能的相關資訊。如要進一步瞭解如何使用 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 會擲回錯誤，並提供正確的指令來建立索引。

瞭解詳情

  • 如要進一步瞭解 Genkit 中的索引器和擷取器，請參閱「檢索增強生成」頁面。
  • 如要進一步瞭解向量搜尋功能，請參閱 Cloud Firestore 說明文件中的「使用向量嵌入搜尋」。

Cloud Functions

外掛程式提供 onFlow() 建構函式，可建立由 Cloud Functions for Firebase HTTPS 觸發函式支援的流程。這些函式符合 Firebase 的可呼叫函式介面，您可以使用 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 函式的 HttpsOptions 物件：

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

如要定義驗證政策，請為 firebaseAuth() 提供回呼函式，該函式會將 DecodedIdToken 做為唯一參數。在這個函式中，檢查使用者權杖，如果使用者未符合您要要求的任何條件，就會擲回錯誤。

如要進一步瞭解這個主題，請參閱「授權和完整性」。