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

本頁面由 Cloud Translation API 翻譯而成。

Firebase 外掛程式

Firebase 外掛程式提供 Firebase 服務整合功能，方便您建構智慧且可擴充的 AI 應用程式。主要功能包括：

Firestore 向量儲存空間：使用 Firestore 為向量嵌入項目建立索引和擷取。
遙測資料：將遙測資料匯出至支援 Firebase Genkit 監控控制台的 Google Cloud 作業套件。

安裝

使用 npm 安裝 Firebase 外掛程式：

npm install @genkit-ai/firebase

事前準備

設定 Firebase 專案

所有 Firebase 產品都需要 Firebase 專案。您可以使用 Firebase 控制台建立新專案，或在現有 Google Cloud 專案中啟用 Firebase。
如果您要部署含有 Cloud 函式的流程，請將 Firebase 專案升級為 Blaze 方案。
如果您想在本機執行匯出遙測資料的程式碼，請務必安裝 Google Cloud CLI 工具。

Firebase Admin SDK 初始化

您必須在應用程式中初始化 Firebase Admin SDK。外掛程式不會自動處理這項作業。

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

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

外掛程式要求您指定 Firebase 專案 ID。您可以使用下列任一方式指定 Firebase 專案 ID：

如上方程式碼片段所示，請在 initializeApp() 設定物件中設定 projectId。
設定 GCLOUD_PROJECT 環境變數。如果您透過 Google Cloud 環境 (Cloud 函式、Cloud Run 等) 執行流程，GCLOUD_PROJECT 會自動設為該環境的專案 ID。

如果您設定 GCLOUD_PROJECT，可以省略 initializeApp() 中的設定參數。

憑證

如要提供 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 檔案的內容。

功能與用途

遙測

Firebase Genkit Monitoring 由 Google Cloud 作業套件提供技術支援。這需要為專案啟用遙測相關 API。詳情請參閱 Google Cloud 外掛程式說明文件。

在 Google Cloud IAM 控制台，將下列角色授予「預設的運算服務帳戶」：

Monitoring 指標寫入者 (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 向量搜尋功能的相關資訊。如要進一步瞭解如何使用 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);
}

定義 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
  },
});

可用的擷取選項

下列選項可傳遞至 ai.retrieve 中的 options 欄位：

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 欄位必須建立索引才能運作。如要建立索引，請按照下列步驟操作：

執行 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

如要使用 Cloud Functions 部署流程，請使用 Firebase 函式程式庫內建的 Genkit 支援功能。onCallGenkit 方法可讓您從資料流建立可呼叫的函式。這項功能會自動支援串流和 JSON 要求。您可以使用 Cloud Functions 用戶端 SDK 呼叫這些模型。

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