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 など）からフローを実行している場合、GCLOUD_PROJECT は環境のプロジェクト ID に自動的に設定されます。

    GCLOUD_PROJECT を設定した場合は、構成パラメータ firebase() を省略できます。

認証情報

Firebase 認証情報を指定するには、Google Cloud アプリケーションのデフォルト認証情報も設定する必要があります。認証情報を指定するには:

  • Google Cloud 環境（Cloud Functions、Cloud Run など）からフローを実行している場合は、自動的に設定されます。

  • その他の環境の場合:

    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 の呼び出し可能関数インターフェースに準拠しており、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 を唯一のパラメータとして受け取るコールバック関数を指定します。この関数では、ユーザー トークンを調べ、ユーザーが必須の条件を満たしていない場合はエラーをスローします。

このトピックの詳細については、認可と完全性をご覧ください。