⟐ 開発ツール/2026-03-30上級

Firebase Genkit × Gemini API 本番運用ノート — 個人開発アプリで動かして気づいた設計と落とし穴

Firebase Genkit と Gemini API を個人開発アプリのレビュー要約バックエンドで 1 ヶ月動かした運用ノート。Flow / Tool の設計、Cloud Functions と Cloud Run の使い分け、コストとレイテンシの実測値、公式にない 7 つの落とし穴をまとめました。

Firebase Genkit² Gemini API²⁰⁷ RAG¹⁵ Cloud Functions Cloud Run⁵ エージェント¹⁵ 本番環境⁶ AI開発⁸

✦ プレミアム記事

Firebase Genkit を、自分が長年運営している個人開発アプリ群のバックエンドに組み込み始めたのは 2026 年に入ってからでした。最初に動かしたのは、レビュー本文を要約してダッシュボードに流す小さな Flow です。これだけのことで、それまで Cloud Functions に書いていた「Gemini を叩く → トークン制限を見ながら結果を整形 → ロギングして DB に保存」という 80 行ほどのコードが、Genkit の defineFlow ひとつで完結してしまい、しばらく茫然としていました。

個人開発でバックエンドを触るとき、判断の軸はだいたい 2 つに絞られます。ユーザーを何秒待たせるか、そして月末の請求がいくらになるか。広告収益で固定費を回している構成では、この 2 つはどちらも直接的に効いてきます。

ですから Genkit を評価するときも、機能の豊富さより先に「この 2 つの数字がどう動くか」だけを見ていました。以下は、そのレビュー要約 Flow を 1 ヶ月本番で回しながら取った記録です。Flow の設計、Tool の組み立て、RAG、デプロイ、セキュリティといった基本パターンに加えて、公式ドキュメントには書かれていない「実際にハマったところ」と、コスト・レイテンシの実測値も載せています。

ひとつ先に断っておきます。実測を取ったのは 2026 年 4 月です。その後モデルのラインナップが入れ替わり、同じ「Flash」という名前でも単価が変わりました。数字をそのまま持ち回ると足をすくわれるので、後半に「実測値をモデル世代の入れ替わりから守る」という節を置いてあります。

Firebase Genkit とは：概念と利点

Firebase Genkit は、AI アプリケーション開発を加速するための統合フレームワークです。従来の LLM 統合では、PromptTemplate、Chain、Agent といった概念が分散していましたが、Genkit は Flow という統一された抽象化により、これらを効率的に管理します。

Genkit の中核概念

Flow: 入力と出力が型安全に定義された AI 処理のユニット。JavaScript/TypeScript での記述により、ランタイム型チェックと IDE サポートが得られます。Flow は以下の特性を持ちます。

ストリーミング対応: LLM の出力をリアルタイムで配信でき、エンドユーザーの UX 向上に直結
トレーシング: 自動的にすべての API 呼び出しと中間結果が記録され、本番デバッグが容易
再利用可能: 複数の Flow から同じ子 Flow を呼び出し、DRY 原則を遵守

Tool: Flow から呼び出されるアクション。API 呼び出し、データベースアクセス、外部システム連携など。Gemini は Tool calling により、自律的に必要な Tool を選択・実行できます。

Prompt: テンプレート化された入力の定義。変数の注入、System Prompt の設定、Few-shot 例の埋め込みなど。

Embedder と Retriever: RAG（Retrieval Augmented Generation）実装の基盤。Embedder はテキストをベクトル化し、Retriever は類似度検索により関連ドキュメントを取得します。

セットアップ：Gemini 2.5 Pro/Flash との統合

Genkit をプロジェクトに導入するまでの手順を説明します。

# Node.js 18+ が必要
npm init -y
npm install firebase-genkit @genkit-ai/gemini

初期化スクリプト:

// genkit.ts
import { genkit } from 'genkit';
import { googleAI } from '@genkit-ai/googleai';
 
// モデル ID は 1 箇所に閉じ込め、環境変数で差し替えられるようにしておく
export const MODELS = {
  pro:   googleAI.model(process.env.GEMINI_PRO_MODEL   ?? 'gemini-2.5-pro'),
  flash: googleAI.model(process.env.GEMINI_FLASH_MODEL ?? 'gemini-2.5-flash'),
} as const;
 
const ai = genkit({
  plugins: [googleAI({ apiKey: process.env.GEMINI_API_KEY })],
  model: MODELS.pro,  // デフォルトモデル
});
 
export default ai;

モデル ID を 1 箇所に閉じ込める

最初は、プラグインがエクスポートしているモデル定数をそのまま各 Flow に import していました。動きはしますが、モデルを差し替えるときに Flow の数だけ import 文を書き換えることになります。Flow が 20 本を超えたあたりから、実装の時間より「この Flow だけ古いモデルのままではないか」を確認する時間のほうが長くなりました。

いまは上のように MODELS という 1 つのオブジェクトに閉じ込め、実際の ID は環境変数から入れています。ステージングだけ新しいモデルに向ける、といった切り替えがコード変更なしで済みます。あとで触れるコストの再計算をするときも、「どの Flow がどの ID を使っていたか」が 1 ファイルを見れば分かります。

以降のコード例はすべて、この MODELS を import している前提で書いています。

環境構成のポイント:

API キーは環境変数で管理します。本番環境では Secret Manager を使用し、ローカル開発では .env.local に記載します。API キーのプレースホルダーは YOUR_GEMINI_API_KEY とします。

// 複数環境への対応
const apiKey = process.env.GEMINI_API_KEY || process.env.LOCAL_API_KEY;
if (!apiKey) {
  throw new Error('GEMINI_API_KEY not found');
}

Pro 側は推論の深さ、Flash 側はレイテンシと単価、というのが基本的な分かれ目です。

ただし、この関係は世代をまたぐと綺麗に保たれません。後半で数字を並べますが、3.x 系の Flash は 2.5 系の Flash より単価が高く設定されています。「Flash と名前が付いていれば安い」という前提でコードを書いていると、モデルを上げた翌月の請求で驚くことになります。モデル名は性能の目印であって、価格の目印ではないと考えておくのが安全です。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦個人開発アプリのレビュー要約バックエンドを Firebase Genkit + Gemini 2.5 Flash で 1 ヶ月動かした、コスト・レイテンシ・p95 の実測値

✦公式ドキュメントに書かれていない 7 つの落とし穴（Cold Start 35〜45秒・concurrency=1 デフォルト・runFlow 入れ子計上・Secret Manager 課金・Flow 名衝突・トレース PII・streamCallback バックプレッシャー）

✦Cloud Functions と Cloud Run の使い分けマトリクスと、モデル世代が入れ替わったあとに実測コストを読み直すための計算スクリプト

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

Core Concepts：Flow、Tool、Prompt の実装

Flow の設計パターン

Flow は AI 処理の最小単位です。簡単な例から複雑な例まで段階的に解説します。

シンプルな Text-to-Text Flow:

import { defineFlow, runFlow } from 'genkit';
import { MODELS } from './genkit';
 
export const summarizeArticle = defineFlow(
  {
    name: 'summarizeArticle',
    inputSchema: z.object({
      text: z.string(),
      maxLength: z.number().default(200)
    }),
    outputSchema: z.string()
  },
  async (input) => {
    const result = await ai.generate({
      model: MODELS.pro,
      prompt: `以下のテキストを${input.maxLength}文字以内で要約してください：\n\n${input.text}`,
      config: {
        temperature: 0.3,
        maxOutputTokens: 500
      }
    });
    return result.text();
  }
);
 
// 実行
const summary = await runFlow(summarizeArticle, {
  text: '長いテキスト...',
  maxLength: 200
});

ストリーミング対応 Flow:

export const streamingSummarize = defineFlow(
  {
    name: 'streamingSummarize',
    inputSchema: z.object({ text: z.string() }),
    outputSchema: z.string(),
    streamSchema: z.string()  // ストリーミング出力型
  },
  async (input, streamCallback) => {
    const stream = await ai.generate({
      model: MODELS.pro,
      prompt: `要約してください: ${input.text}`,
      streaming: true
    });
 
    let fullResponse = '';
    for await (const chunk of stream) {
      fullResponse += chunk.text();
      streamCallback(chunk.text());  // クライアントへリアルタイム配信
    }
    return fullResponse;
  }
);

Tool の定義と Gemini による自動呼び出し

Tool は JSON Schema で定義され、Gemini が自動的に選択・実行します。

import { defineTool } from 'firebase-genkit';
 
const getWeather = defineTool(
  {
    name: 'getWeather',
    description: '指定された都市の天気を取得',
    inputSchema: z.object({
      city: z.string().describe('都市名')
    }),
    outputSchema: z.object({
      temperature: z.number(),
      condition: z.string()
    })
  },
  async (input) => {
    // 実装: 外部 API を呼び出し
    const response = await fetch(`https://weather-api.example.com?city=${input.city}`);
    return response.json();
  }
);
 
const getFlightInfo = defineTool(
  {
    name: 'getFlightInfo',
    description: '飛行機の運航情報を取得',
    inputSchema: z.object({
      departure: z.string(),
      arrival: z.string(),
      date: z.string().describe('YYYY-MM-DD 形式')
    }),
    outputSchema: z.object({
      flights: z.array(z.object({
        flightNumber: z.string(),
        departure: z.string(),
        arrival: z.string()
      }))
    })
  },
  async (input) => {
    const response = await fetch(
      `https://flight-api.example.com/search?from=${input.departure}&to=${input.arrival}&date=${input.date}`
    );
    return response.json();
  }
);

Tool を Flow に統合:

export const tripPlannerAgent = defineFlow(
  {
    name: 'tripPlanner',
    inputSchema: z.object({
      destination: z.string(),
      departureDate: z.string()
    }),
    outputSchema: z.string()
  },
  async (input) => {
    const result = await ai.generate({
      model: MODELS.pro,
      tools: [getWeather, getFlightInfo],
      prompt: `${input.destination} への旅行プランを立ててください。出発日は ${input.departureDate} です。天気と飛行機の情報を参考にしてください。`,
      maxIterations: 5  // Tool 呼び出しの最大回数
    });
    return result.text();
  }
);

RAG 実装：Embedder と Retriever の統合

検索拡張生成（RAG）は、大規模なナレッジベースから関連ドキュメントを取得し、LLM の入力に含める手法です。Genkit でこれを実装します。

Embedder の選択と設定

import { defineEmbedder } from 'firebase-genkit';
import { embedding001 } from '@genkit-ai/gemini';
 
// Gemini 組み込みの Embedder を使用
const embedder = embedding001;
 
// カスタム Embedder の定義も可能
const customEmbedder = defineEmbedder(
  {
    name: 'customEmbedder',
    configSchema: z.object({ model: z.string() })
  },
  async (input, config) => {
    const response = await fetch('https://embedding-api.example.com', {
      method: 'POST',
      body: JSON.stringify({ texts: input, model: config.model })
    });
    const data = await response.json();
    return data.embeddings;
  }
);

Vector Store の統合

Genkit は複数の Vector Store をサポート。ここでは Pinecone を例に:

import { pineconeRetrieverRef } from '@genkit-ai/pinecone';
import { Pinecone } from '@pinecone-database/pinecone';
 
const pc = new Pinecone({
  apiKey: process.env.PINECONE_API_KEY
});
 
const index = pc.index(process.env.PINECONE_INDEX);
 
const retriever = defineRetriever(
  {
    name: 'documentRetriever',
    configSchema: z.object({ topK: z.number().default(5) })
  },
  async (input, config) => {
    // テキストをベクトル化
    const embedding = await embedder.embed(input);
 
    // Pinecone で類似度検索
    const results = await index.query({
      vector: embedding,
      topK: config.topK,
      includeMetadata: true
    });
 
    // 検索結果をドキュメント形式で返す
    return results.matches.map(match => ({
      content: match.metadata.text,
      metadata: match.metadata,
      score: match.score
    }));
  }
);

RAG Flow の実装

export const ragQA = defineFlow(
  {
    name: 'ragQA',
    inputSchema: z.object({
      question: z.string()
    }),
    outputSchema: z.string()
  },
  async (input) => {
    // Step 1: 関連ドキュメントを検索
    const documents = await retriever.retrieve(input.question, { topK: 3 });
 
    // Step 2: コンテキストを構築
    const context = documents
      .map(doc => doc.content)
      .join('\n---\n');
 
    // Step 3: Gemini で生成
    const result = await ai.generate({
      model: MODELS.pro,
      prompt: `以下のコンテキストを参考に、質問に答えてください。
 
コンテキスト:
${context}
 
質問: ${input.question}`,
      config: {
        temperature: 0.5,
        maxOutputTokens: 1000
      }
    });
 
    return result.text();
  }
);

Agentic パターン：エージェントの段階的な進化

AI エージェントの複雑性は、順序立てた以下のパターンで進化します。

パターン 1：Sequential（順序固定）

複数の Flow を決まった順序で実行。エージェントの考慮度が最も低いものの、予測可能性が高いです。

export const sequentialWorkflow = defineFlow(
  {
    name: 'sequentialWorkflow',
    inputSchema: z.object({ topic: z.string() }),
    outputSchema: z.string()
  },
  async (input) => {
    // Step 1: リサーチ
    const research = await runFlow(researchTopic, { topic: input.topic });
 
    // Step 2: 構成化
    const structure = await runFlow(outlineContent, { research });
 
    // Step 3: 執筆
    const article = await runFlow(writeArticle, { outline: structure });
 
    return article;
  }
);

パターン 2：Tool Calling（自動選択）

Tool calling により、Gemini が自動的に必要な Tool を選択します。

export const autonomousAgent = defineFlow(
  {
    name: 'autonomousAgent',
    inputSchema: z.object({ request: z.string() }),
    outputSchema: z.string()
  },
  async (input) => {
    const result = await ai.generate({
      model: MODELS.pro,
      tools: [
        getWeather,
        getFlightInfo,
        getHotelAvailability,
        makeReservation
      ],
      prompt: `ユーザーのリクエスト: ${input.request}\n\n必要な Tool を呼び出して対応してください。`,
      maxIterations: 10,
      config: {
        temperature: 0.7
      }
    });
 
    return result.text();
  }
);

パターン 3：Iterative Refinement（反復改善）

LLM の出力を評価し、品質が不足していれば改善指示を与えて再実行。

export const refinementAgent = defineFlow(
  {
    name: 'refinementAgent',
    inputSchema: z.object({ topic: z.string() }),
    outputSchema: z.string()
  },
  async (input) => {
    let content = '';
    let quality = 0;
    let iterations = 0;
    const maxIterations = 3;
 
    while (quality < 0.8 && iterations < maxIterations) {
      // コンテンツ生成
      content = await ai.generate({
        model: MODELS.pro,
        prompt: `${input.topic} について詳しく説明してください。`
      }).then(r => r.text());
 
      // 品質評価
      const evaluation = await ai.generate({
        model: MODELS.pro,
        prompt: `以下のテキストを 0 から 1 の品質スコアで評価してください: ${content}`,
        responseSchema: z.object({ score: z.number().min(0).max(1) })
      });
 
      quality = evaluation.score;
 
      if (quality < 0.8) {
        const feedback = await ai.generate({
          model: MODELS.pro,
          prompt: `品質スコア ${quality} の以下のテキストを改善してください: ${content}`
        }).then(r => r.text());
        content = feedback;
      }
 
      iterations++;
    }
 
    return content;
  }
);

パターン 4：Autonomous（自律的実行）

Genkit の Agentic Flow では、LLM が複数回にわたって思考し、Tool を呼び出し、結果を評価して次のアクションを決定します。

export const fullyAutonomousAgent = defineFlow(
  {
    name: 'fullyAutonomousAgent',
    inputSchema: z.object({
      goal: z.string(),
      maxSteps: z.number().default(10)
    }),
    outputSchema: z.string()
  },
  async (input) => {
    const conversationHistory = [];
 
    for (let step = 0; step < input.maxSteps; step++) {
      // 現在のゴール状況を LLM に評価させる
      const nextAction = await ai.generate({
        model: MODELS.pro,
        tools: [
          searchDatabase,
          callAPI,
          executeCode,
          delegateSubgoal
        ],
        prompt: `
目標: ${input.goal}
 
これまでの進捗:
${conversationHistory.map(h => `- ${h}`).join('\n')}
 
次に何をすべきか判断してください。必要に応じて Tool を呼び出してください。
ゴール達成時は "GOAL_ACHIEVED" を出力してください。
`,
        maxIterations: 1
      });
 
      conversationHistory.push(nextAction.text());
 
      if (nextAction.text().includes('GOAL_ACHIEVED')) {
        break;
      }
    }
 
    // 最終結果をまとめる
    const finalSummary = await ai.generate({
      model: MODELS.pro,
      prompt: `以下のプロセスの結果をまとめてください:\n${conversationHistory.join('\n')}`
    }).then(r => r.text());
 
    return finalSummary;
  }
);

MCP（Model Context Protocol）との統合

MCP は、LLM がローカルツール（ファイルシステム、データベース、IDE など）にアクセスするための標準プロトコルです。Genkit は MCP サーバーを Tool として統合できます。

import { defineModel } from '@genkit-ai/mcp';
 
const mcpTool = defineModel(
  {
    name: 'mcpFilesystem',
    description: 'ファイルシステムへのアクセス（MCP 経由）'
  },
  async (input) => {
    const mcpClient = new MCPClient({
      host: 'localhost',
      port: 3000
    });
 
    const response = await mcpClient.call(input.toolName, input.params);
    return response;
  }
);
 
// Flow に統合
export const codeAnalysisAgent = defineFlow(
  {
    name: 'codeAnalysis',
    inputSchema: z.object({ filePath: z.string() }),
    outputSchema: z.string()
  },
  async (input) => {
    const result = await ai.generate({
      model: MODELS.pro,
      tools: [mcpTool],
      prompt: `ファイル ${input.filePath} のコードを分析してください。`
    });
 
    return result.text();
  }
);

デプロイ：Cloud Functions と Cloud Run

Cloud Functions へのデプロイ

Cloud Functions は小規模で短時間の Flow に最適です。

// functions/src/index.ts
import * as functions from 'firebase-functions';
import { runFlow } from 'firebase-genkit';
import { summarizeArticle } from './flows';
 
export const summarize = functions.https.onCall(async (data, context) => {
  // 認証チェック
  if (!context.auth) {
    throw new functions.https.HttpsError(
      'unauthenticated',
      'Authentication required'
    );
  }
 
  try {
    const result = await runFlow(summarizeArticle, {
      text: data.text,
      maxLength: data.maxLength || 200
    });
 
    return { success: true, summary: result };
  } catch (error) {
    throw new functions.https.HttpsError('internal', error.message);
  }
});

デプロイコマンド:

firebase deploy --only functions:summarize

Cold Start 対策:

// 事前ウォームアップエンドポイント
export const warmUp = functions.pubsub
  .schedule('every 5 minutes')
  .onRun(async () => {
    await ai.generate({
      model: MODELS.pro,
      prompt: 'Warm-up request'
    });
  });

Cloud Run へのデプロイ

複雑な Flow やストリーミング対応が必要な場合は Cloud Run を使用します。

// Dockerfile
FROM node:18-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only production
COPY . .
EXPOSE 8080
CMD ["node", "server.js"]

// server.ts - Express サーバー
import express from 'express';
import { runFlow } from 'firebase-genkit';
import { tripPlannerAgent } from './flows';
 
const app = express();
app.use(express.json());
 
// ストリーミング対応
app.post('/plan-trip', async (req, res) => {
  const { destination, departureDate } = req.body;
 
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
 
  try {
    const stream = await runFlow(
      tripPlannerAgent,
      { destination, departureDate },
      { streamCallback: (chunk) => {
        res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
      }}
    );
 
    res.write(`data: ${JSON.stringify({ result: stream })}\n\n`);
    res.end();
  } catch (error) {
    res.write(`data: ${JSON.stringify({ error: error.message })}\n\n`);
    res.end();
  }
});
 
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

デプロイコマンド:

gcloud run deploy genkit-agent \
  --source . \
  --platform managed \
  --region us-central1 \
  --set-env-vars GEMINI_API_KEY=YOUR_GEMINI_API_KEY

セキュリティ：認証・認可・秘密情報管理

認可ポリシーの設定

import * as functions from 'firebase-functions';
import * as admin from 'firebase-admin';
 
export const protectedFlow = functions.https.onCall(async (data, context) => {
  // ユーザー認証の確認
  if (!context.auth) {
    throw new functions.https.HttpsError('unauthenticated', 'User must be logged in');
  }
 
  // Firestore でユーザーロールを確認
  const userDoc = await admin.firestore()
    .collection('users')
    .doc(context.auth.uid)
    .get();
 
  if (!userDoc.data()?.isPremium) {
    throw new functions.https.HttpsError(
      'permission-denied',
      'Premium subscription required'
    );
  }
 
  // Flow 実行
  return await runFlow(expensiveFlow, data);
});

Secret Manager の統合

import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
 
const client = new SecretManagerServiceClient();
 
async function getSecret(secretId: string): Promise<string> {
  const projectId = process.env.GCP_PROJECT_ID;
  const name = `projects/${projectId}/secrets/${secretId}/versions/latest`;
 
  const [version] = await client.accessSecretVersion({ name });
  return version.payload.data.toString('utf8');
}
 
// Flow で使用
const apiKey = await getSecret('gemini-api-key');
const ai = genkit({
  plugins: [googleAI({ apiKey })]
});

App Check による API 保護

import * as appCheck from 'firebase-functions/v2/https';
 
export const protectedAgent = appCheck.onCall(
  { region: 'us-central1' },
  async (request) => {
    // App Check トークンは自動検証済み
    return await runFlow(secureFlow, request.data);
  }
);

パフォーマンス最適化

第 2 世代 Cloud Functions の並行実行

# firebase.json
{
  "functions": {
    "runtime": "nodejs18",
    "concurrency": 100  // デフォルト 100 から増加
  }
}

export const parallelAgent = functions.https.onCall(async (data) => {
  // 複数の Flow を並行実行
  const [result1, result2, result3] = await Promise.all([
    runFlow(flowA, data),
    runFlow(flowB, data),
    runFlow(flowC, data)
  ]);
 
  return { result1, result2, result3 };
});

Flow のグループ化

// 同じメモリ設定での複数 Flow をグループ化
export const aiOperations = functions
  .runWith({
    memory: '2GB',
    timeoutSeconds: 300
  })
  .https.onCall(async (data, context) => {
    const flowName = data.flowName;
 
    switch (flowName) {
      case 'summarize':
        return await runFlow(summarizeArticle, data.params);
      case 'translate':
        return await runFlow(translateContent, data.params);
      case 'generate':
        return await runFlow(generateContent, data.params);
      default:
        throw new Error('Unknown flow');
    }
  });

キャッシング戦略

import * as admin from 'firebase-admin';
 
const cache = admin.firestore();
 
export const cachedRAGFlow = defineFlow(
  {
    name: 'cachedRAGFlow',
    inputSchema: z.object({ question: z.string() })
  },
  async (input) => {
    const cacheKey = Buffer.from(input.question).toString('base64');
 
    // キャッシュをチェック
    const cached = await cache.collection('rag_cache').doc(cacheKey).get();
    if (cached.exists) {
      return cached.data().answer;
    }
 
    // キャッシュミス時は実行
    const result = await runFlow(ragQA, input);
 
    // 結果をキャッシュ
    await cache.collection('rag_cache').doc(cacheKey).set({
      answer: result,
      timestamp: admin.firestore.FieldValue.serverTimestamp(),
      ttl: 86400  // 24 時間
    });
 
    return result;
  }
);

本番監視と可観測性

Genkit のトレーシング機能

Genkit はすべての API 呼び出しを自動的に記録します。

import { getLogger } from 'firebase-functions/logger';
 
export const monitoredFlow = defineFlow(
  {
    name: 'monitoredFlow',
    inputSchema: z.object({ text: z.string() })
  },
  async (input, context) => {
    const logger = getLogger();
 
    logger.info('Flow started', { input });
 
    const result = await ai.generate({
      model: MODELS.pro,
      prompt: input.text,
      config: {
        temperature: 0.5
      }
    });
 
    logger.info('Flow completed', {
      tokens: result.usage,
      executionTime: context.executionTime
    });
 
    return result.text();
  }
);

Cloud Logging への統合

import * as logging from '@google-cloud/logging';
 
const log = logging.log('genkit-operations');
 
export const loggingFlow = defineFlow(
  {
    name: 'loggingFlow',
    inputSchema: z.object({ data: z.any() })
  },
  async (input) => {
    const metadata = {
      severity: 'INFO',
      sourceLocation: {
        file: 'flows.ts',
        line: 123
      }
    };
 
    log.write(log.entry(metadata, { input }));
 
    const result = await runFlow(ragQA, input);
 
    log.write(log.entry(metadata, { result }));
 
    return result;
  }
);

コスト最適化戦略

モデル選択の指標

用途	推奨モデル	理由
要約・分類	Gemini 2.5 Flash	高速で低コスト
コンテンツ生成	Gemini 2.5 Pro	品質と速度のバランス
複雑な推論	Gemini 2.5 Pro	深い思考が必要

export const costOptimizedFlow = defineFlow(
  {
    name: 'costOptimized',
    inputSchema: z.object({
      task: z.enum(['summarize', 'generate', 'reason']),
      text: z.string()
    })
  },
  async (input) => {
    const model = input.task === 'summarize'
      ? MODELS.flash
      : input.task === 'generate'
      ? MODELS.pro
      : MODELS.pro;
 
    return await ai.generate({
      model,
      prompt: input.text
    }).then(r => r.text());
  }
);

バッチ処理による API 呼び出しの削減

export const batchFlow = defineFlow(
  {
    name: 'batchFlow',
    inputSchema: z.object({
      items: z.array(z.string())
    })
  },
  async (input) => {
    // 複数アイテムを 1 つのプロンプトで処理
    const batchPrompt = `以下の ${input.items.length} 個のテキストをまとめて処理してください:\n${input.items.map((item, i) => `${i + 1}. ${item}`).join('\n')}`;
 
    return await ai.generate({
      model: MODELS.pro,
      prompt: batchPrompt
    }).then(r => r.text());
  }
);

実践例：AI カスタマーサポートシステムの構築

顧客からの問い合わせに自動対応するシステムを実装します。

// カスタマーサポート エージェント
const fetchTicket = defineTool(
  {
    name: 'fetchTicket',
    description: 'チケット ID からサポートチケット情報を取得',
    inputSchema: z.object({ ticketId: z.string() }),
    outputSchema: z.object({
      id: z.string(),
      customer: z.string(),
      issue: z.string(),
      status: z.string()
    })
  },
  async (input) => {
    const ticket = await fetch(
      `https://support-api.example.com/tickets/${input.ticketId}`
    ).then(r => r.json());
    return ticket;
  }
);
 
const updateTicket = defineTool(
  {
    name: 'updateTicket',
    description: 'チケットステータスと応答メッセージを更新',
    inputSchema: z.object({
      ticketId: z.string(),
      status: z.string(),
      response: z.string()
    }),
    outputSchema: z.object({ success: z.boolean() })
  },
  async (input) => {
    const response = await fetch(
      `https://support-api.example.com/tickets/${input.ticketId}`,
      {
        method: 'PATCH',
        body: JSON.stringify({
          status: input.status,
          agentResponse: input.response
        })
      }
    );
    return { success: response.ok };
  }
);
 
export const customerSupportAgent = defineFlow(
  {
    name: 'customerSupport',
    inputSchema: z.object({ ticketId: z.string() }),
    outputSchema: z.string()
  },
  async (input) => {
    // チケット情報を取得
    const ticket = await runFlow(fetchTicketFlow, { ticketId: input.ticketId });
 
    // AI が自動対応を生成
    const response = await ai.generate({
      model: MODELS.pro,
      tools: [updateTicket],
      prompt: `
顧客サポートチケット:
ID: ${ticket.id}
顧客: ${ticket.customer}
問題: ${ticket.issue}
現在のステータス: ${ticket.status}
 
適切な対応メッセージを生成し、チケットを更新してください。
解決可能な場合は "resolved" に、さらに情報が必要な場合は "awaiting-info" に設定してください。
`,
      maxIterations: 3
    });
 
    return response.text();
  }
);

公式ドキュメントには書かれていない、本番運用で気づいた 7 つのインサイト

ここからは、私自身が個人開発のバックエンドに Firebase Genkit を入れて、1 ヶ月ほど動かしてみて遭遇した「公式には書かれていないハマりどころ」を 7 つにまとめます。順番は重要度ではなく、踏みやすさの順です。

1. Cold Start は Gemini 初回呼び出し込みで 35〜45 秒に伸びる

Cloud Functions Gen2 + Genkit + Gemini 2.5 Pro の組み合わせで、Cold Start から最初のレスポンスまで実測 35〜45 秒かかりました。内訳はだいたい、コンテナ起動 8〜12 秒、Genkit 初期化（genkit({...}) の googleAI プラグイン解決）4〜6 秒、Gemini 2.5 Pro の最初の generate 呼び出し 20〜25 秒、です。

Pro を Flash に変えるとレスポンス部分が 8〜12 秒まで落ちますが、Cold Start 全体は 20〜28 秒残ります。私は AdMob から入る広告収益で運用しているアプリにつき、ユーザーから見える機能には Gemini を直接当てず、バックグラウンドのバッチ要約と、サーバー側の minInstances を 1 にした Cloud Run コンテナでの常時受け待ちに分けるようにしました。

# firebase.json — Cold Start 軽減のためメモリ増 + min-instances 維持
{
  "functions": {
    "runtime": "nodejs18",
    "memory": "1GiB",
    "concurrency": 80,
    "minInstances": 1
  }
}

minInstances: 1 を入れておくと、Cloud Functions Gen2 で時間あたり数十円ですが Cold Start のロングテールがほぼ消えました。広告クリック単価の高い時間帯にユーザーを待たせると AdMob の eCPM にも響くため、結果的に元は取れています。

2. concurrency のデフォルトが Gen2 でも 1 のままになりやすい

Cloud Functions Gen2 のドキュメントには concurrency 上限が 1000 と書かれていますが、firebase deploy でデフォルト設定のままだと、コンテナの concurrency が 1 のまま動いていることが何度かありました。Gemini を呼び出す関数は I/O 待ちが大半なので、concurrency=1 のままだと急に来た 10 件のリクエストで 10 個のコンテナが起動し、起動分のコストと Cold Start のロングテールを全部踏みます。

私は最低でも concurrency: 50、Flash 中心の関数は 80 を入れるようにしました。Pro を使う関数だけメモリ消費が大きいので、concurrency: 30 程度に下げてバランスを取っています。

3. `runFlow` の入れ子はトレースが「親 Flow にも子 Flow にも」二重計上される

Genkit のトレース機能は便利ですが、runFlow(parentFlow, ...) の中で runFlow(childFlow, ...) を呼ぶと、Cloud Logging のトレースエクスポートで親 Flow と子 Flow の両方にトークン使用量が重複して載ります。月末に集計したとき、Cloud Billing の Gemini 課金額より Genkit トレース集計のほうが 1.8 倍ほど多くなって面食らいました。

対処は単純で、コスト集計は「Cloud Billing の generativelanguage.googleapis.com だけを真と扱う」ことに割り切ること。Genkit トレースはあくまでデバッグ用と位置付け、ダッシュボードには出さないようにしました。

4. Secret Manager の `accessSecretVersion` 呼び出しに 1 リクエスト課金が乗る

accessSecretVersion は 10,000 リクエストあたり $0.03 と安いものの、Cloud Functions の Cold Start で毎回叩くと地味に積もります。Gemini API キーは関数のグローバルスコープで一度だけ取得し、その後はモジュール変数にキャッシュするのが正解でした。

let cachedApiKey: string | null = null;
async function getCachedSecret(name: string): Promise<string> {
  if (cachedApiKey) return cachedApiKey;
  const [version] = await secretManager.accessSecretVersion({ name });
  cachedApiKey = version.payload.data.toString("utf8");
  return cachedApiKey;
}

Cold Start の度に取り直されるため、Warm な間はキャッシュされ、Cold が来たら再取得されるという挙動になります。

5. Flow 名は文字列で完全一致：リネームすると Cloud Logging の絞り込みが死ぬ

defineFlow({ name: 'summarizeArticle', ... }) の name は Cloud Logging のラベルに直接出ます。私はリファクタで summarizeArticleV2 にリネームしたところ、それまでの監視ダッシュボードと Slack アラートが全部 V1 で絞り込まれていて、3 日ほど気づきませんでした。

リネームするときは、必ず旧名と新名の両方を含むワイルドカードクエリ（name=~"summarizeArticle.*"）に書き換えてから移行することをお勧めします。

6. トレースに PII が混ざる：本番投入前に redactor を必ず噛ませる

Genkit の自動トレースは、Flow に渡された入力をそのまま Cloud Logging に書き出します。レビュー要約 Flow に流していたユーザー本文には、ごく稀にメールアドレスや電話番号が紛れ込んでいて、本番投入してから気づきました。

defineFlow の前段にレダクタを挟むのが安全です。私の場合はざっくり「メールアドレス・電話番号・クレジットカード番号らしき桁数の数列」を [REDACTED] に置換する簡易関数を Flow の入口に挟んでいます。

const REDACT_PATTERNS = [
  /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}/g,
  /0\d{1,3}-?\d{2,4}-?\d{3,4}/g,
  /\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}/g,
];
function redact(text: string): string {
  return REDACT_PATTERNS.reduce(
    (acc, pat) => acc.replace(pat, "[REDACTED]"),
    text
  );
}

ユーザーが投稿したテキストを Gemini に渡す系のアプリでは、これを入口で噛ませないと、Cloud Logging の保管期間 30 日の間ずっと PII が露出し続けることになります。

7. `streamCallback` は同期的に呼ばれる：重い処理を入れるとバックプレッシャーで詰まる

ストリーミング Flow の streamCallback は、Gemini から chunk が届くたびに同期的に呼ばれます。ここに DB 書き込みや別 API への通知を素朴に入れると、その処理時間ぶん Gemini のストリーム受信が止まり、全体のレスポンスが体感で 2〜3 倍遅くなりました。

streamCallback の中では、queue.push(chunk) のような軽い操作だけにとどめ、重い処理は別ワーカーや setImmediate で逃がすのが鉄則です。

const bufferQueue: string[] = [];
let flushTimer: NodeJS.Timeout | null = null;
 
const streamCallback = (chunk: string) => {
  bufferQueue.push(chunk);
  if (!flushTimer) {
    flushTimer = setImmediate(() => {
      const batch = bufferQueue.splice(0);
      // ここで DB 書き込み等の重い処理
      persistChunks(batch);
      flushTimer = null;
    });
  }
};

個人開発アプリで Genkit を運用してみたコスト・レイテンシ実測値

ここからは、実際に 1 ヶ月動かしてみて取れた数値を共有します。対象は私の壁紙系アプリのうち 1 本に組み込んだ「ユーザーレビュー要約 Flow」で、月間およそ 12,000 件のレビューが入ってきます。

モデル別コスト・レイテンシ実測（2026 年 4 月実測）

モデル	1 リクエストあたり平均トークン	平均レイテンシ	p95 レイテンシ	1 リクエストあたりコスト	月間総コスト（12,000件）
Gemini 2.5 Pro	入力 1,800 / 出力 250	4.2 秒	11.8 秒	$0.018	約 $216
Gemini 2.5 Flash	入力 1,800 / 出力 250	1.1 秒	3.4 秒	$0.0014	約 $17
Gemini 2.0 Flash	入力 1,800 / 出力 250	0.9 秒	2.7 秒	$0.0009	約 $11

レビュー要約のように「定型的な日本語の整形」がメインのタスクでは、2.5 Flash で十分な品質が出ました。コストは Pro 比で約 12.7 分の 1、レイテンシも 4 倍速くなります。私は最終的に Flash に寄せて、月額 $17 程度で運用しています。

Cold Start を含む全体レイテンシ（Cloud Functions Gen2）

状態	Pro	Flash
Warm（直前に呼ばれた直後）	4.2 秒	1.1 秒
Cool（5 分以上経過）	28 秒	20 秒
Cold（初回起動）	42 秒	24 秒
Cold + minInstances=1	5.0 秒	1.4 秒

minInstances: 1 を入れたときの追加コストは、私の構成で月額およそ $4 でした。レビュー要約は非同期処理なので付けていませんが、ユーザーから直接呼ばれるエンドポイント（例：FAQ 検索 Bot）には付けています。

キャッシュヒット率による実コスト圧縮

// Firestore キャッシュを噛ませた後の実測（同じレビュー本文が来た場合のみヒット）
const CACHE_HIT_RATE = 0.18;  // 約 18%
const ORIGINAL_COST_PER_MONTH = 17;  // Flash で月 $17
const EFFECTIVE_COST = ORIGINAL_COST_PER_MONTH * (1 - CACHE_HIT_RATE);
// → 約 $14/月（さらに 3 ドル削減）

レビュー要約のように同じ文章が再投稿されることが少ない用途では、キャッシュヒット率は 20% を切る程度でした。FAQ Bot のように「同じ質問が繰り返し来る」用途だと、私の実測ではヒット率が 50〜65% まで上がり、$17 → $7 程度まで落ちます。

実測値をモデル世代の入れ替わりから守る

上の表を取ったのは 2026 年 4 月です。その後 Flash 系のラインナップが入れ替わったため、この表をそのまま「Flash なら月 $17」と読むと外れます。

2.5 Flash で測ったときの実効単価は 1 リクエストあたり $0.0014、月 12,000 件で約 $17 でした。一方 2026 年 7 月時点で公開されている 3.6 Flash の単価は、100 万トークンあたり入力 $1.50・出力 $7.50 です。同じトークン数を流したときの計算はこうなります。

項目	月間トークン数	単価（100 万トークンあたり）	月額
入力（1,800 × 12,000 件）	21.6M	$1.50	$32.40
出力（250 × 12,000 件）	3.0M	$7.50	$22.50
合計	—	—	約 $54.9

同じワークロード、同じトークン数、モデル名に入っている単語も同じ「Flash」です。それで月額が $17 から $55 に上がります。3 倍以上の差です。

3.6 Flash は 3.5 Flash に比べて出力トークンがおよそ 17% 少なくなると案内されています。それを織り込んで出力を 250 → 208 トークンで見積もっても、出力側は $18.7、合計で約 $51 にしかなりません。消費量の改善は確かに効きますが、単価の差を埋めるほどではない、というのが計算して出た結論でした。

ここで候補に上がるのが 3.5 Flash-Lite で、入力は 100 万トークンあたり $0.3 とされています。レビュー要約のような「定型的な日本語の整形」は、判断の難しさより処理量のほうが支配的なタスクです。世代を上げること自体が目的でないなら、素直に Lite 系に降りるほうが筋が良いと考えています。

トークン数は実測、単価は変数として持つ

この件で学んだのは、実測して意味があるのはトークン数と p95 レイテンシまでで、金額はいつでも再計算できる形にしておく、ということでした。金額をドキュメントに直接書き込むと、モデルが変わった瞬間にすべてが古くなります。しかも古くなったことが誰にも見えません。

そこで、計測結果は「1 リクエストあたりのトークン数」で保存し、単価は別ファイルから読むようにしました。

// pricing.ts — 単価だけを分離して置く。公式の価格ページを見て更新する
export const PRICE_PER_1M = {
  "gemini-2.5-flash":      { input: 0.30, output: 2.50 },
  "gemini-3.6-flash":      { input: 1.50, output: 7.50 },
  "gemini-3.5-flash-lite": { input: 0.30, output: null },  // 出力単価は未確認
} as const;
 
type Measured = {
  inputTokens: number;      // 1 リクエストあたりの実測値
  outputTokens: number;
  requestsPerMonth: number;
};
 
export function monthlyCost(modelId: keyof typeof PRICE_PER_1M, m: Measured): number {
  const p = PRICE_PER_1M[modelId];
  if (p.output === null) {
    // 未確認の単価をゼロ扱いで通すと、見積もりが静かに小さく出る
    throw new Error(`output price for ${modelId} is unverified`);
  }
  const inputM  = (m.inputTokens  * m.requestsPerMonth) / 1_000_000;
  const outputM = (m.outputTokens * m.requestsPerMonth) / 1_000_000;
  return inputM * p.input + outputM * p.output;
}
 
// 2026-04 に取った実測トークン数を、いまの単価で読み直す
const measured: Measured = { inputTokens: 1800, outputTokens: 250, requestsPerMonth: 12000 };
 
monthlyCost("gemini-2.5-flash", measured);  // → 約 $14.0
monthlyCost("gemini-3.6-flash", measured);  // → 約 $54.9

gemini-2.5-flash の計算結果 $14.0 は、実測の $17 とずれます。この差はリトライと失敗分です。理論値はあくまで成功した呼び出しだけを数えるので、レート制限で弾かれて再送した分、スキーマ検証に落ちて投げ直した分は乗ってきません。私の場合はこの差がおよそ 2 割で、以降は理論値に 1.2 を掛けたものを予算の目安にしています。

output: null を握りつぶさずに例外にしているのも意図的です。一度「Lite に寄せれば入力単価は据え置きだから総額も据え置きのはず」と早合点しかけたことがあり、確認していない値は静かに通さないようにしました。

単価は変わります。上の数字も記事化の時点で Gemini API の価格ページを確認して入れたものですので、お読みになる時点でご自身で最新の値を確かめてください。

広告収益で固定費を回すアプリで、Genkit をどこに置くか

最後に、広告収益で固定費をまかなっているアプリで実際に採用している「Genkit の置き場所」の設計を共有します。この構成では、ユーザー体験を 1 秒でも遅らせると広告 impression あたりの収益（eCPM）に直接響くため、Gemini のような「答えが返るまで数秒待たされる API」をどこに置くかが、そのまま収益に効いてきます。

パターン A：ユーザー操作の主導線には Gemini を入れない

壁紙アプリのトップ画面、検索画面、ダウンロード画面など、ユーザーが秒単位で操作する画面では Gemini を直接呼びません。これらの画面は AdMob のバナー・ネイティブ広告の表示機会が多く、レイテンシが下がると impression 数が増えてしまいます。

Gemini を使うのは、「画像にぴったりな名前をつけてもらう」「ユーザーが集めた壁紙コレクションに対してテーマ別の説明文を生成する」のような、明示的にユーザーが「考えてもらう」ボタンを押したときに限定しています。この場合はローディング表示が許容されるので、Pro でも問題ありません。

パターン B：オフピーク時間帯のバッチで Gemini を回す

新着壁紙のタグ生成、レビュー要約、SEO 用説明文の生成といった「ユーザー操作と非同期で良いもの」は、すべてオフピーク時間帯（私の場合 02:00〜05:00 JST）の Cloud Scheduler バッチで Genkit Flow を走らせています。

// Cloud Scheduler から発火される、ユーザー非接続なバッチ
export const overnightTagGeneration = functions.pubsub
  .schedule("0 3 * * *")
  .timeZone("Asia/Tokyo")
  .onRun(async () => {
    const newWallpapers = await fetchNewWallpapersWithoutTags();
    for (const wallpaper of newWallpapers) {
      await runFlow(tagGenerationFlow, { wallpaperId: wallpaper.id });
    }
  });

この時間帯なら Cold Start が出ても誰も困りませんし、Gemini 側のレート制限にも余裕があります。私はこのパターンで、月間およそ 80,000 件の自動タグ付けを Flash で回しており、コストは月 $25 ほどです。

パターン C：FAQ / サポート用は Flash + 1 秒キャッシュ TTL

サポート FAQ 検索のように、ユーザーが質問を入力して数秒待つことが許容される用途は、Gemini 2.5 Flash に絞り、Firestore に直近 24 時間のキャッシュを置いています。同じ質問が来たらキャッシュから返し、新規質問だけ Flash に投げる構成です。

// FAQ Bot 用：温度を低く、キャッシュ強めに
const faqResponse = await ai.generate({
  model: MODELS.flash,
  prompt: faqPrompt,
  config: {
    temperature: 0.2,  // 個性は不要、安定性重視
    maxOutputTokens: 400,
  }
});

temperature: 0.2 にしているのは、FAQ で「個性的な回答」が出ると逆にサポートのオペレーションコストが上がるためです。私は実体験として、temperature: 0.7 で運用していた時期に「Gemini が独自解釈した使い方案内」がユーザーから問い合わせとして返ってきて、結局人間が修正することになった件が複数あったため、ここは低めに固定しています。

Cloud Functions と Cloud Run の使い分け早見表

用途	推奨	理由
ユーザー操作直結（即時性必要・Gemini を直接呼ぶ）	Cloud Run + minInstances=1 + Flash	Cold Start を吸収しないと UX が崩れる
バッチ処理（オフピーク・大量）	Cloud Functions Gen2 + 適切な concurrency	起動の柔軟さとコスト
ストリーミングが必要	Cloud Run（Cloud Functions は SSE 不向き）	Functions の SSE はタイムアウト 60 秒で詰む
数秒の処理を月数百回	Cloud Functions（最安構成）	起動コストが時間課金より安い
数十秒の処理を月数万回	Cloud Run（concurrency 活用）	1 コンテナで多重処理できる

私の現状の構成は、レビュー要約とタグ生成が Cloud Functions Gen2、サポート FAQ Bot だけ Cloud Run、という分け方です。AdMob 収益が日次でブレるアプリでは、固定費の minInstances は最小限に抑えたほうが精神衛生上も良いと感じています。

全体を振り返ってと次のステップ

Firebase Genkit を個人開発の本番に置いてみて率直に感じているのは、「Gemini を素で叩いていた頃に比べて、運用が単純に静かになった」ということです。Cloud Functions に書き散らしていたトークン制限のコード、エラー時のリトライ、Cloud Logging への構造化ログ出力、これらが Flow / Tool / トレースという 3 つの抽象化に吸収されて、コードレビュー時に追うべき場所が明確になりました。

ただ、この記事で書いてきたように、Cold Start のロングテール、concurrency のデフォルト、Secret Manager の重複呼び出し、トレースの PII 露出、streamCallback のバックプレッシャーといった「公式には書かれていない」ポイントを踏まないと、コストもレイテンシも想定の 2〜3 倍に膨らみます。

うまくいかなかったことも書いておきます。入力の長さでモデルを自動的に振り分ける仕組みを一度入れましたが、これは外しました。長い入力ほど難しい、という前提が実際のレビュー本文には当てはまらず、むしろ短い一文のほうが皮肉や言い回しの解釈でつまずくことが多かったためです。いまは用途（要約か、生成か、推論か）で明示的に選ぶ形に戻しています。自動化できそうに見える判断ほど、根拠になる相関を先に確かめたほうが良かったと感じています。

これから Genkit を入れる方には、まずは「ユーザー操作から外れたバッチ用途」で Flash を回し、コストとレイテンシの実測を取ってみることをお勧めします。私の場合はそこから「常駐させても元が取れる用途」を見極めて、Cloud Run に少しずつ移していきました。

次に踏むと良いステップは、自分の業務やアプリの中から「人間が同じ作業を毎日繰り返している部分」を 1 つ選び、その部分を defineFlow ひとつに置き換えてみることだと考えています。Genkit の良さは、小さく始めても後から段階的に拡張できる設計に表れています。

同じように個人開発のバックエンドに Gemini を組み込もうとしている方の参考になれば幸いです。お読みいただきありがとうございました。