Firebase プラグイン

Firebase プラグインは Firebase サービスと統合されており、インテリジェントでスケーラブルな AI アプリケーションを構築できます。主な特長は以下のとおりです。

  • Firestore ベクトルストア: Firestore を使用して、ベクトル エンベディングによるインデックス登録と取得を行います。
  • Cloud Functions: フローを HTTPS トリガー関数としてデプロイします。
  • Firebase Authentication: 認可ポリシーを実装します。
  • テレメトリー: テレメトリーを Google Cloud のオペレーション スイートにエクスポートし、Firebase コンソールで専用のビューを表示する

インストール

npm を使用して Firebase プラグインをインストールします。

npm install @genkit-ai/firebase

前提条件

Firebase プロジェクトの設定

  1. すべての Firebase プロダクトで Firebase プロジェクトが必要です。新しいプロジェクトを作成するか、既存の Google Cloud プロジェクトで Firebase を有効にするには、Firebase コンソールを使用します。
  2. Cloud Functions を使用してフローをデプロイする場合は、Firebase プロジェクトを Blaze プランにアップグレードします。
  3. テレメトリーをエクスポートするコードをローカルで実行する場合は、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 Functions、Cloud Run など）からフローを実行している場合、GCLOUD_PROJECT は環境のプロジェクト ID に自動的に設定されます。

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

認証情報

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 プラグインのドキュメントをご覧ください。

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: （文字列）
    retriever 構成で指定されたデフォルト コレクションをオーバーライドします。これは、サブコレクションをクエリする場合や、コレクションを動的に切り替える場合に便利です。

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

このプラグインには、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) => {
    // ...
  }
);

認証ポリシーを定義するには、DecodedIdToken を唯一のパラメータとして受け取るコールバック関数を firebaseAuth() に指定します。この関数でユーザー トークンを調べ、ユーザーが必須の条件を満たしていない場合はエラーをスローします。

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