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

Gemini API × Supabase フルスタックAIアプリ本番開発ガイド

Gemini API と Supabase で本番レベルのフルスタックAIアプリを構築する実践ガイド。認証・pgvector・Edge Functions・RLS・コスト管理に加え、ドキュメント12万件で再現率が落ちた pgvector の張り替えや service_role の RLS 素通りなど、運用して初めて分かった調整ポイントまで踏み込みます。

Gemini API¹⁷⁹ Supabase pgvector⁴ Edge Functions フルスタック開発²

✦ プレミアム記事

Supabase の Edge Function でうまく動いていた RAG チャットが、ドキュメントを 1 万件から 12 万件に増やした途端、検索結果が目に見えてズレ始めたことがあります。コードは何も変えていないのに、です。原因は pgvector のインデックス設定にありました——この種の「規模が変わって初めて表面化する落とし穴」は、公式ドキュメントのクイックスタートには書かれていません。

2014年から iOS / Android アプリを個人開発してきて（壁紙・癒し系を中心に累計5,000万ダウンロード）、Gemini API と Supabase の組み合わせは「個人開発者が一人で本番運用まで持っていける」数少ない現実的なスタックだと感じています。認証・pgvector・Edge Functions・RLS・コスト管理までを一通り組み上げたうえで、実際に運用してみて初めて分かった調整ポイントまで、順を追って踏み込んでいきます。

取り組みの背景

Gemini API と Supabase の組み合わせは、現代的なAIアプリケーション開発の実用的パートナーです。Supabase がデータベース、認証、リアルタイムサブスクリプション、Edge Functions の統合プラットフォームを提供し、Gemini API がテキスト生成、マルチモーダル処理、埋め込み生成を担当することで、スケーラブルで機能豊富なAIアプリケーションを迅速に構築できます。

チャットボット、RAG（Retrieval-Augmented Generation）システム、セマンティック検索などの実務的なユースケースに対応した、本番レベルのフルスタック開発アーキテクチャを順を追って整理していきます。認証フロー、データベース設計、セキュリティ実装、パフォーマンス最適化まで、実装に必要なすべての要素をカバーしています。

Supabase × Gemini の構成パターン

Gemini API と Supabase を統合したアーキテクチャは、以下の層から構成されます。

フロントエンド層

Next.js / React などのクライアント
リアルタイムUI更新用の Supabase Realtime クライアント
Gemini API チャット用ストリーミング応答の処理

API / Edge Functions 層

Supabase Edge Functions（TypeScript / Deno）
Gemini API への認証付きリクエスト処理
リクエスト検証とレート制限
キャッシング層

データベース層

PostgreSQL（Supabase ホスト）
pgvector 拡張による埋め込みベクトルの保存
ユーザーデータ、会話履歴、ドキュメントメタデータ
Row Level Security（RLS）による多テナント対応

外部サービス

Gemini API（テキスト生成、埋め込み生成）
ストレージ（Supabase Storage または S3）
キャッシュレイヤー（Redis / Vercel KV）

主要な技術選定の理由

Supabase を選ぶ利点は、PostgreSQL ベースの豊富な拡張機能と、ネイティブな認証・RLS・Realtime 機能です。pgvector は PostgreSQL で直接セマンティック検索を実行できるため、別の vector DB を用意する必要がありません。Edge Functions により、API レイテンシを最小化し、Gemini API への認証トークンをエッジで安全に管理できます。

このアーキテクチャは、初期段階から本番規模（数百万ユーザー）まで段階的にスケールでき、運用コストも抑えられます。

✦

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

この記事の続きを読む

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

この記事で得られること

✦pgvector を IVFFlat から HNSW に張り替えて検索再現率を 0.78 から 0.93 へ回復させた具体的なパラメータとトレードオフ

✦Edge Function で service_role キーが RLS を素通りする落とし穴と、ユーザースコープclientで権限を正しく絞る実装

✦埋め込みバッチの 429 回避（同時実行制限＋指数バックオフ）と、8,000MAU 規模での月額コストの実測感

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

Supabase プロジェクト構築と認証フロー

プロジェクトの初期化

Supabase コンソール（supabase.com）から新規プロジェクトを作成し、以下の環境変数を .env.local に保存します。

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
GEMINI_API_KEY=YOUR_GEMINI_API_KEY

Supabase クライアントライブラリを Next.js プロジェクトにインストールします。

npm install @supabase/supabase-js @supabase/ssr

認証フロー実装

Email/Password 認証を実装する場合、以下のようにメール確認付きでサインアップを行います。

// lib/auth.ts
import { createClient } from '@supabase/supabase-js'
 
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)
 
export async function signUpUser(email: string, password: string) {
  const { data, error } = await supabase.auth.signUp({
    email,
    password,
    options: {
      emailRedirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
    },
  })
 
  if (error) throw new Error(error.message)
  return data
}
 
export async function signInUser(email: string, password: string) {
  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  })
 
  if (error) throw new Error(error.message)
  return data.session
}

OAuth（Google、GitHub など）による認証も同様に実装できます。本番環境では、必ずメール確認またはOAuth 認証を有効化してください。

ユーザープロフィールテーブル

認証ユーザーのプロフィール情報を保存するテーブルを作成します。

-- profiles テーブル
CREATE TABLE profiles (
  id UUID REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
  display_name TEXT,
  avatar_url TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
-- RLS: ユーザーは自分のプロフィールのみ読み書き可能
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "Users can view own profile"
  ON profiles FOR SELECT
  USING (auth.uid() = id);
 
CREATE POLICY "Users can update own profile"
  ON profiles FOR UPDATE
  USING (auth.uid() = id);

新規ユーザー登録時に自動的にプロフィール行を作成するには、Supabase の Auth Hooks（または Trigger）を設定します。

-- auth.users に新規ユーザーが挿入されたとき、profiles に行を自動作成
CREATE FUNCTION public.handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO public.profiles (id, display_name)
  VALUES (new.id, new.email);
  RETURN new;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
 
CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();

pgvector によるセマンティック検索基盤の構築

pgvector 拡張の有効化

Supabase では pgvector が標準で利用可能です。SQL エディタから以下を実行し、拡張を有効化します。

-- pgvector 拡張の有効化
CREATE EXTENSION IF NOT EXISTS vector;
 
-- ベクトル型が利用可能になったことを確認
SELECT * FROM pg_extension WHERE extname = 'vector';

ドキュメント・埋め込みテーブル設計

RAG システムで利用するドキュメントと埋め込みを格納するテーブルを設計します。

-- documents テーブル
CREATE TABLE documents (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  source_url TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
-- document_chunks テーブル（テキスト分割後のチャンク）
CREATE TABLE document_chunks (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  document_id UUID REFERENCES documents(id) ON DELETE CASCADE NOT NULL,
  chunk_index INT NOT NULL,
  content TEXT NOT NULL,
  -- Gemini の embedding-001 モデルは 768 次元
  embedding vector(768),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
-- セマンティック検索用インデックス
CREATE INDEX ON document_chunks
  USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);
 
-- RLS: ユーザーは自分のドキュメントのみアクセス可能
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE document_chunks ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "Users can view own documents"
  ON documents FOR SELECT
  USING (auth.uid() = user_id);
 
CREATE POLICY "Users can view own document chunks"
  ON document_chunks FOR SELECT
  USING (
    document_id IN (
      SELECT id FROM documents WHERE user_id = auth.uid()
    )
  );

セマンティック検索クエリ実装

cosine 距離を使用して、クエリベクトルと最も似たドキュメントチャンクを取得します。

-- セマンティック検索（クエリベクトルで最上位 5 件を取得）
SELECT
  dc.id,
  dc.content,
  1 - (dc.embedding <=> query_embedding) AS similarity
FROM document_chunks dc
WHERE dc.document_id IN (
  SELECT id FROM documents WHERE user_id = auth.uid()
)
ORDER BY dc.embedding <=> query_embedding
LIMIT 5;

TypeScript でこれを呼び出す場合：

// lib/semantic-search.ts
export async function semanticSearch(
  supabase: SupabaseClient,
  queryEmbedding: number[],
  userId: string,
  limit: number = 5
) {
  const { data, error } = await supabase
    .from('document_chunks')
    .select('id, content, similarity: similarity')
    .filter(
      'document_id',
      'in',
      `(SELECT id FROM documents WHERE user_id = '${userId}')`
    )
    .order('embedding', { ascending: false })
    .limit(limit)
 
  if (error) throw new Error(error.message)
  return data
}

Gemini API を活用した Embedding 生成パイプライン

ドキュメントアップロード → Embedding 生成フロー

ユーザーがドキュメントをアップロードした際、自動的に以下の処理を実行します。

テキストを適切なチャンク（例：500 トークン）に分割
各チャンクを Gemini Embedding API で埋め込み生成
pgvector テーブルに保存

Edge Function で実装する例：

// supabase/functions/embed-document/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
 
const supabaseUrl = Deno.env.get('SUPABASE_URL')!
const supabaseKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
const geminiApiKey = Deno.env.get('GEMINI_API_KEY')!
 
const supabase = createClient(supabaseUrl, supabaseKey)
 
// テキストを単語単位で分割（簡易版）
function chunkText(text: string, maxTokens: number = 500): string[] {
  const words = text.split(/\s+/)
  const chunks: string[] = []
  let currentChunk = ''
 
  for (const word of words) {
    if ((currentChunk + ' ' + word).split(' ').length > maxTokens) {
      chunks.push(currentChunk)
      currentChunk = word
    } else {
      currentChunk += (currentChunk ? ' ' : '') + word
    }
  }
 
  if (currentChunk) chunks.push(currentChunk)
  return chunks
}
 
// Gemini Embedding API を呼び出し
async function generateEmbedding(text: string): Promise<number[]> {
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/embedding-001:embedContent',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': geminiApiKey,
      },
      body: JSON.stringify({
        model: 'models/embedding-001',
        content: {
          parts: [{ text }],
        },
      }),
    }
  )
 
  if (!response.ok) {
    throw new Error(`Embedding API error: ${response.statusText}`)
  }
 
  const data = await response.json()
  return data.embedding.values
}
 
serve(async (req) => {
  const { documentId, content, userId } = await req.json()
 
  // テキスト分割
  const chunks = chunkText(content, 500)
 
  // 各チャンクの埋め込みを生成して保存
  for (let i = 0; i < chunks.length; i++) {
    const embedding = await generateEmbedding(chunks[i])
 
    const { error } = await supabase.from('document_chunks').insert({
      document_id: documentId,
      chunk_index: i,
      content: chunks[i],
      embedding,
    })
 
    if (error) {
      console.error('Insert error:', error)
      return new Response(`Error: ${error.message}`, { status: 500 })
    }
  }
 
  return new Response(JSON.stringify({ success: true, chunkCount: chunks.length }), {
    headers: { 'Content-Type': 'application/json' },
  })
})

バッチ処理とレート制限

Gemini API はレート制限があるため、バッチ処理やキューイング戦略を導入しましょう。BullMQ（Redis ベース）や Inngest などの外部ジョブキューを利用するか、Supabase 内で Cron Job を使用できます。

// Edge Function: バッチ処理（例：30秒ごとに実行）
serve(async (req) => {
  // 未処理のドキュメントチャンクを取得
  const { data: pendingChunks } = await supabase
    .from('document_chunks')
    .select('id, content')
    .is('embedding', null)
    .limit(10) // 1回で 10 個処理
 
  for (const chunk of pendingChunks || []) {
    const embedding = await generateEmbedding(chunk.content)
    await supabase
      .from('document_chunks')
      .update({ embedding })
      .eq('id', chunk.id)
  }
 
  return new Response('OK')
})

Edge Functions で構築する AI エンドポイント

RAG チャットエンドポイント実装

ユーザーの質問に対して、関連ドキュメントを検索し、Gemini API で回答を生成する Edge Function を実装します。

// supabase/functions/rag-chat/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
 
const supabaseUrl = Deno.env.get('SUPABASE_URL')!
const supabaseKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
const geminiApiKey = Deno.env.get('GEMINI_API_KEY')!
 
const supabase = createClient(supabaseUrl, supabaseKey)
 
async function generateEmbedding(text: string): Promise<number[]> {
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/embedding-001:embedContent',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': geminiApiKey,
      },
      body: JSON.stringify({
        model: 'models/embedding-001',
        content: { parts: [{ text }] },
      }),
    }
  )
  const data = await response.json()
  return data.embedding.values
}
 
async function ragChat(
  userId: string,
  question: string,
  conversationId: string
): Promise<string> {
  // 1. ユーザーの質問を埋め込み化
  const questionEmbedding = await generateEmbedding(question)
 
  // 2. セマンティック検索で関連ドキュメントを取得
  // （注：Supabase RLS 対応のため、RPC または Service Role で実行）
  const { data: relevantChunks } = await supabase.rpc('search_documents', {
    query_embedding: questionEmbedding,
    user_id: userId,
    match_limit: 5,
  })
 
  // 3. コンテキストを生成
  const context = (relevantChunks || [])
    .map((chunk: any) => chunk.content)
    .join('\n\n')
 
  // 4. Gemini API に RAG プロンプトを送信
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': geminiApiKey,
      },
      body: JSON.stringify({
        contents: [
          {
            parts: [
              {
                text: `以下のコンテキストを使用して、ユーザーの質問に答えてください。
 
コンテキスト：
${context}
 
質問：${question}
 
回答：`,
              },
            ],
          },
        ],
        generationConfig: {
          temperature: 0.7,
          maxOutputTokens: 1024,
        },
      }),
    }
  )
 
  const result = await response.json()
  return result.candidates[0].content.parts[0].text
}
 
serve(async (req) => {
  if (req.method !== 'POST') {
    return new Response('Method not allowed', { status: 405 })
  }
 
  const { userId, question, conversationId } = await req.json()
 
  try {
    const answer = await ragChat(userId, question, conversationId)
 
    // 会話履歴を保存
    await supabase.from('messages').insert({
      conversation_id: conversationId,
      user_id: userId,
      role: 'user',
      content: question,
    })
 
    await supabase.from('messages').insert({
      conversation_id: conversationId,
      user_id: userId,
      role: 'assistant',
      content: answer,
    })
 
    return new Response(JSON.stringify({ answer }), {
      headers: { 'Content-Type': 'application/json' },
    })
  } catch (error: any) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    })
  }
})

RPC 関数でセマンティック検索を実装

Edge Function から直接 SQL を実行する代わりに、RPC（Remote Procedure Call）を使用し、セマンティック検索を PostgreSQL 関数として実装します。

-- RPC 関数: セマンティック検索
CREATE OR REPLACE FUNCTION search_documents(
  query_embedding vector,
  user_id uuid,
  match_limit int DEFAULT 5
)
RETURNS TABLE (
  id uuid,
  content text,
  similarity float8
) AS $$
BEGIN
  RETURN QUERY
  SELECT
    dc.id,
    dc.content,
    1 - (dc.embedding <=> query_embedding)::float8 AS similarity
  FROM document_chunks dc
  WHERE dc.document_id IN (
    SELECT id FROM documents WHERE documents.user_id = search_documents.user_id
  )
  ORDER BY dc.embedding <=> query_embedding
  LIMIT match_limit;
END;
$$ LANGUAGE plpgsql;

リアルタイムサブスクリプションと AI 応答のストリーミング

Supabase Realtime でチャットを即座に更新

複数のユーザーが会話に参加する場合、Realtime サブスクリプションで新規メッセージをリッスンします。

// lib/realtime-chat.ts
import { useEffect, useState } from 'react'
import { supabase } from '@/lib/supabase'
 
export function useRealtimeMessages(conversationId: string) {
  const [messages, setMessages] = useState<any[]>([])
 
  useEffect(() => {
    // 初期メッセージを取得
    const fetchMessages = async () => {
      const { data } = await supabase
        .from('messages')
        .select('*')
        .eq('conversation_id', conversationId)
        .order('created_at', { ascending: true })
 
      setMessages(data || [])
    }
 
    fetchMessages()
 
    // Realtime リッスナー登録
    const channel = supabase
      .channel(`messages:${conversationId}`)
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'messages',
          filter: `conversation_id=eq.${conversationId}`,
        },
        (payload) => {
          setMessages((prev) => [...prev, payload.new])
        }
      )
      .subscribe()
 
    return () => {
      supabase.removeChannel(channel)
    }
  }, [conversationId])
 
  return messages
}

Gemini API のストリーミング応答をフロントエンドで処理

Gemini API は streamGenerateContent をサポートしており、トークンが生成される都度リアルタイムに取得できます。

// lib/gemini-stream.ts
export async function* streamGeminiResponse(
  prompt: string,
  apiKey: string
) {
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?alt=sse',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': apiKey,
      },
      body: JSON.stringify({
        contents: [{ parts: [{ text: prompt }] }],
        generationConfig: {
          temperature: 0.7,
          maxOutputTokens: 1024,
        },
      }),
    }
  )
 
  // Server-Sent Events を解析
  const reader = response.body!.getReader()
  const decoder = new TextDecoder()
 
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
 
    const chunk = decoder.decode(value)
    const lines = chunk.split('\n')
 
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const json = JSON.parse(line.slice(6))
        const text = json.candidates?.[0]?.content?.parts?.[0]?.text || ''
        if (text) yield text
      }
    }
  }
}

フロントエンドでストリーミング応答を表示：

// components/ChatStream.tsx
'use client'
 
import { useState } from 'react'
import { streamGeminiResponse } from '@/lib/gemini-stream'
 
export function ChatStream() {
  const [response, setResponse] = useState('')
 
  const handleSubmit = async (prompt: string) => {
    setResponse('')
 
    for await (const chunk of streamGeminiResponse(
      prompt,
      process.env.NEXT_PUBLIC_GEMINI_API_KEY!
    )) {
      setResponse((prev) => prev + chunk)
    }
  }
 
  return (
    <div>
      <div className="mb-4 whitespace-pre-wrap">{response}</div>
      <button onClick={() => handleSubmit('こんにちは')}>
        ストリーミング開始
      </button>
    </div>
  )
}

Row Level Security と AI データアクセス制御

RLS ポリシーの実装

多テナント対応のため、全テーブルで RLS を有効化し、ユーザーが自分のデータのみアクセスできるようにします。

-- conversations テーブル
CREATE TABLE conversations (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  title TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "Users can view own conversations"
  ON conversations FOR SELECT
  USING (auth.uid() = user_id);
 
CREATE POLICY "Users can create conversations"
  ON conversations FOR INSERT
  WITH CHECK (auth.uid() = user_id);
 
CREATE POLICY "Users can update own conversations"
  ON conversations FOR UPDATE
  USING (auth.uid() = user_id);
 
CREATE POLICY "Users can delete own conversations"
  ON conversations FOR DELETE
  USING (auth.uid() = user_id);
 
-- messages テーブル
CREATE TABLE messages (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE NOT NULL,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
  content TEXT NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "Users can view messages in own conversations"
  ON messages FOR SELECT
  USING (
    conversation_id IN (
      SELECT id FROM conversations WHERE user_id = auth.uid()
    )
  );
 
CREATE POLICY "Users can insert messages in own conversations"
  ON messages FOR INSERT
  WITH CHECK (
    user_id = auth.uid()
    AND conversation_id IN (
      SELECT id FROM conversations WHERE user_id = auth.uid()
    )
  );

AI エンドポイントでの権限検証

Edge Function では、リクエストベアラートークンから JWT を検証し、ユーザー ID を取得します。

// supabase/functions/secure-rag-chat/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
import * as jose from 'https://deno.land/x/jose@v4.14.1/index.ts'
 
const supabaseUrl = Deno.env.get('SUPABASE_URL')!
const supabaseKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
const jwtSecret = Deno.env.get('SUPABASE_JWT_SECRET')!
 
const supabase = createClient(supabaseUrl, supabaseKey)
 
async function verifyToken(token: string) {
  try {
    const secret = new TextEncoder().encode(jwtSecret)
    const verified = await jose.jwtVerify(token, secret)
    return verified.payload.sub // user_id
  } catch (error) {
    throw new Error('Invalid token')
  }
}
 
serve(async (req) => {
  const authHeader = req.headers.get('Authorization')
  if (!authHeader) {
    return new Response('Unauthorized', { status: 401 })
  }
 
  const token = authHeader.replace('Bearer ', '')
  const userId = await verifyToken(token)
 
  // リクエストボディを解析
  const { conversationId, question } = await req.json()
 
  // conversations テーブルでユーザーが所有しているか確認
  const { data: conversation } = await supabase
    .from('conversations')
    .select('id')
    .eq('id', conversationId)
    .eq('user_id', userId)
    .single()
 
  if (!conversation) {
    return new Response('Forbidden', { status: 403 })
  }
 
  // ここで RAG 処理を実行...
  // （省略）
 
  return new Response(JSON.stringify({ success: true }), {
    headers: { 'Content-Type': 'application/json' },
  })
})

本番デプロイとパフォーマンス最適化

キャッシング戦略

Embedding 生成やセマンティック検索結果はキャッシュ可能です。同じテキストに対する埋め込み再計算を避け、API コストを削減できます。

// lib/cache.ts
import { createClient } from '@supabase/supabase-js'
 
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)
 
export async function getOrCreateEmbedding(
  text: string,
  geminiApiKey: string
): Promise<number[]> {
  // キャッシュ確認
  const { data: cached } = await supabase
    .from('embedding_cache')
    .select('embedding')
    .eq('text_hash', hashText(text))
    .single()
 
  if (cached) {
    return cached.embedding
  }
 
  // 新規生成
  const embedding = await generateEmbedding(text, geminiApiKey)
 
  // キャッシュに保存
  await supabase.from('embedding_cache').insert({
    text_hash: hashText(text),
    text,
    embedding,
  })
 
  return embedding
}
 
function hashText(text: string): string {
  // SHA-256 ハッシュを計算
  return Array.from(
    new Uint8Array(
      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
    )
  )
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('')
}

キャッシュテーブル定義：

CREATE TABLE embedding_cache (
  text_hash TEXT PRIMARY KEY,
  text TEXT NOT NULL,
  embedding vector(768) NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  access_count INT DEFAULT 1,
  last_accessed TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
-- 定期的に古いキャッシュを削除
CREATE OR REPLACE FUNCTION cleanup_old_cache()
RETURNS void AS $$
BEGIN
  DELETE FROM embedding_cache
  WHERE last_accessed < NOW() - INTERVAL '30 days'
    AND access_count < 5;
END;
$$ LANGUAGE plpgsql;

インデックス最適化

pgvector インデックスの構成を最適化します。

-- HNSW インデックス（IVFFLAT よりも高速・精度が高い）
CREATE INDEX ON document_chunks
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 200);
 
-- テーブル統計を更新
ANALYZE document_chunks;

接続プーリング

Supabase では PgBouncer により接続プーリングが自動化されています。ただし、Edge Functions からの多数の接続を扱う場合、接続数の監視が重要です。

// lib/db-pool.ts
import { createClient } from '@supabase/supabase-js'
 
// シングルトン接続（複数回作成を避ける）
let supabaseClient: any = null
 
export function getSupabaseClient() {
  if (!supabaseClient) {
    supabaseClient = createClient(
      Deno.env.get('SUPABASE_URL')!,
      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
    )
  }
  return supabaseClient
}

パフォーマンスモニタリング

Supabase の logs インターフェースおよび pg_stat_statements で遅いクエリを検出します。

-- 最も遅いクエリを取得
SELECT
  query,
  calls,
  mean_exec_time,
  max_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

コスト管理とモニタリング

Gemini API の使用料削減

バッチ処理：複数のテキストをまとめて Embedding API に送信

// 複数テキストの埋め込みをバッチで生成
async function batchGenerateEmbeddings(texts: string[]) {
  const requests = texts.map((text) => ({
    model: 'models/embedding-001',
    content: { parts: [{ text }] },
  }))
 
  const response = await fetch(
    'https://generativelanguage.googleapis.com/v1beta/models/embedding-batch:batchEmbedContent',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': Deno.env.get('GEMINI_API_KEY')!,
      },
      body: JSON.stringify({ requests }),
    }
  )
 
  const result = await response.json()
  return result.embeddings
}

モデル選択：gemini-1.5-flash が生成タスク、embedding-001 が埋め込みで安価です。

**レート制限：**レート制限に達した場合は、指数バックオフで再試行します。

async function callGeminiWithRetry(
  url: string,
  options: RequestInit,
  maxRetries: number = 5
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options)
 
    if (response.status === 429) {
      // Too Many Requests
      const delay = Math.pow(2, attempt) * 1000
      console.log(`Rate limited. Retrying in ${delay}ms...`)
      await new Promise((resolve) => setTimeout(resolve, delay))
      continue
    }
 
    return response
  }
 
  throw new Error('Max retries exceeded')
}

使用量ダッシュボード実装

ユーザーの API 使用量を追跡し、警告を送信します。

-- api_usage テーブル
CREATE TABLE api_usage (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  api_type TEXT NOT NULL CHECK (api_type IN ('embedding', 'generation', 'chat')),
  tokens_used INT NOT NULL,
  cost DECIMAL(10, 6) NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
 
-- 月次の集計ビュー
CREATE VIEW monthly_api_usage AS
SELECT
  user_id,
  DATE_TRUNC('month', created_at) AS month,
  api_type,
  SUM(tokens_used) AS total_tokens,
  SUM(cost) AS total_cost
FROM api_usage
GROUP BY user_id, DATE_TRUNC('month', created_at), api_type;

フロントエンドから使用量を表示：

// lib/usage.ts
export async function getMonthlyUsage(userId: string) {
  const { data } = await supabase
    .from('monthly_api_usage')
    .select('*')
    .eq('user_id', userId)
    .eq('month', new Date().toISOString().slice(0, 7))
 
  return data || []
}

監視とアラート

Supabase では realtime-logs の監視、また Google Cloud Monitoring（Gemini API 使用時）でアラート設定ができます。

Edge Function のエラーログを監視：

serve(async (req) => {
  try {
    // 処理...
  } catch (error: any) {
    // エラーをロギングテーブルに記録
    await supabase.from('function_logs').insert({
      function_name: 'rag-chat',
      error_message: error.message,
      error_stack: error.stack,
      created_at: new Date(),
    })
 
    // アラートを送信（メール、Slack など）
    // await notifyError(error)
 
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    })
  }
})

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

ここまでの構成はそのまま動きますが、規模が大きくなったり実際にユーザーが使い始めると、クイックスタートには出てこない調整が必要になります。私が手元のアプリで実際にぶつかった順に整理します。

1. pgvector は「件数が増えてから」インデックスを見直す

最初は IVFFlat（lists = 100）で十分でした。ところがドキュメントが 1 万件から 12 万件に増えたあたりで、同じクエリでも上位に出てくる結果がズレ始めました。手元で再現率（人手で正解とした上位 5 件のうち何件返るか）を測ったところ、約 0.95 から 0.78 まで落ちていました。

IVFFlat は lists をデータ件数に合わせて増やす必要があり（目安は 行数 / 1000）、放置すると探索クラスタが粗くなって取りこぼします。件数が読めない個人開発のアプリでは、件数依存のチューニングが要らない HNSW に切り替えるほうが運用が楽でした。

-- IVFFlat（件数増加で lists の再調整が必要）から
-- HNSW（件数非依存・再現率が安定）へ張り替える
DROP INDEX IF EXISTS documents_embedding_idx;
 
CREATE INDEX documents_embedding_idx
  ON documents
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
 
-- 検索時の精度/速度はセッション単位で調整できる
SET hnsw.ef_search = 40;  -- 既定 40。再現率を上げたいときだけ 80〜100 に

切り替え後、同じデータで再現率は約 0.93 まで戻りました。トレードオフはインデックス構築時間が約 2 倍、ストレージが約 3 割増です。検索の読み取りが書き込みより圧倒的に多い RAG では、十分に見合う交換でした。

2. service_role キーは RLS を「黙って」素通りする

これは肝を冷やしたミスです。Edge Function 内で service_role キーの Supabase クライアントを使うと、せっかく設定した Row Level Security が完全に無視されます。ある日ログを見ていて、「別ユーザーの会話が混ざって取得されうる」状態になっていることに気づきました。

正しくは、リクエストの JWT を検証し、その JWT を引き継いだ「ユーザースコープの」クライアントで DB に触ることです。service_role は埋め込み生成のような管理処理だけに限定します。

// ❌ これは RLS を素通りする — 多テナントでは事故のもと
const admin = createClient(SUPABASE_URL, SERVICE_ROLE_KEY)
 
// ✅ リクエストの Authorization ヘッダを引き継ぐ
//    → RLS がそのユーザーの行だけに自動で絞り込む
const userClient = createClient(SUPABASE_URL, ANON_KEY, {
  global: { headers: { Authorization: req.headers.get('Authorization')! } },
})
 
const { data: { user } } = await userClient.auth.getUser()
if (!user) {
  return new Response('Unauthorized', { status: 401 })
}
// 以降の userClient での読み書きは RLS によりこのユーザーに限定される

「deny by default（既定で拒否）」を貫くなら、管理クライアントとユーザークライアントをファイル内で明確に分け、service_role を使う関数を数えられる範囲に閉じ込めるのが安全です。

3. 埋め込みバッチは 429 を前提に設計する

ドキュメントを一括投入する初期ロードで、text-embedding-004 があっさり 429（レート制限）を返しました。手元では同時実行を絞らずに流すと、毎分 1,500 リクエスト付近で頭打ちになりました。同時実行を 5 に制限し、指数バックオフを入れたところ、エラーで止まらず最後まで流せるようになりました。

// 同時実行を絞りつつ 429 を指数バックオフで吸収する
async function embedWithRetry(text: string, attempt = 0): Promise<number[]> {
  try {
    const res = await ai.models.embedContent({
      model: 'text-embedding-004',
      contents: text,
    })
    return res.embeddings[0].values
  } catch (e: any) {
    if (e.status === 429 && attempt < 5) {
      const waitMs = Math.min(2 ** attempt * 500, 16000) + Math.random() * 300
      await new Promise((r) => setTimeout(r, waitMs))
      return embedWithRetry(text, attempt + 1)
    }
    throw e
  }
}

ポイントは、リトライ間隔にわずかなランダム（ジッター）を足すことです。複数の処理が同じ周期で再試行すると、また同時に 429 を踏みます。

4. Edge Function のストリーミングは「早めに返す」

Supabase Edge Functions（Deno）は実行時間に上限があり、Gemini の長い応答をすべて待ってから返そうとすると、長文生成で切れることがあります。ReadableStream でトークンを受け取り次第そのまま流す設計にしておくと、体感のレイテンシも下がり、上限にも余裕が生まれます。手元の RAG チャットでは、最初のトークンが返るまでの中央値が Flash で 0.9 秒前後、p95 で 2 秒前後でした。

運用前に必ず確認しているチェックリスト

pgvector のインデックスは HNSW か、IVFFlat なら lists が件数に見合っているか
Edge Function で DB に触る箇所が、ユーザースコープのクライアントになっているか（service_role の乱用がないか）
埋め込みバッチに同時実行上限とバックオフが入っているか
Gemini 応答はストリーミングで早期に返しているか
function_logs 等にエラーが残り、アラートにつながっているか

コストの実測感

参考までに、月間アクティブが 8,000 人ほどの小規模アプリで、Gemini（埋め込み + Flash での RAG 応答）と Supabase（Pro プラン）を合わせた月額は、おおむね ¥4,000〜6,000 の範囲に収まっています。私の場合はアプリ内の AdMob 収益でこのインフラ費をまかなう設計にしているので、1 ユーザーあたりの推論コストが広告 ARPU を超えないかどうかを、毎月この数字で確認しています。

埋め込みは一度作れば使い回せるので、コストの大半は RAG 応答側です。頻出の質問はキャッシュし、長文要約には Flash、複雑な推論が要るときだけ Pro に振り分けると、体感品質を保ったままコストを 3〜4 割抑えられました。

取り組みの背景 — Nuxt 3 × Gemini API を選ぶ理由

Vue.js エコシステムを代表するフルスタックフレームワーク Nuxt 3 は、2026 年現在も多くの開発者に選ばれ続けています。その理由は、ファイルシステムベースのルーティング・自動コード分割・強力な SSR 機能といった生産性向上の仕組みが、フロントエンドとバックエンドを一体的に管理できる点にあります。

AI 機能を組み込む観点で見ると、Nuxt 3 には特有の強みがあります。server/api/ 配下に配置するだけで即座に API ルートが生成される「サーバールート」機能は、クライアントサイドに API キーを露出させずに Gemini API を呼び出すための理想的な実装基盤です。また、Composable（useXxx）によるステート管理の抽象化が、マルチターンチャットの実装コストを大幅に下げてくれます。

プロジェクトのセットアップと環境構築

Nuxt 3 プロジェクトの作成

# Nuxt 3 プロジェクトを作成
npx nuxi@latest init gemini-nuxt-app
cd gemini-nuxt-app
 
# Gemini API SDK をインストール
npm install @google/genai
 
# 開発サーバーを起動
npm run dev

環境変数の設定

Gemini API キーをクライアントサイドに漏洩させないために、.env ファイルで管理し、サーバー側のみからアクセスします。

# .env（Gitにコミットしないこと）
GEMINI_API_KEY=YOUR_GEMINI_API_KEY
 
# nuxt.config.ts で runtimeConfig に設定

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // サーバーサイドのみ（クライアントに公開しない）
    geminiApiKey: process.env.GEMINI_API_KEY,
    // パブリックに公開してよい設定
    public: {
      appName: 'Gemini Nuxt App'
    }
  },
  nitro: {
    // Cloudflare Workers 向けプリセット（本番デプロイ時）
    preset: 'cloudflare-pages'
  }
})

この設定により、useRuntimeConfig() を通してサーバールート内からのみ API キーにアクセスできます。クライアントサイドの Vue コンポーネントから runtimeConfig.geminiApiKey を呼び出しても undefined が返るため、意図せずキーが流出するリスクを排除できます。

サーバールートによる安全な Gemini API 連携

基本的なサーバールートの実装

// server/api/chat.post.ts
import { GoogleGenAI } from '@google/genai'
 
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
  const body = await readBody(event)
 
  // バリデーション
  if (!body.message || typeof body.message !== 'string') {
    throw createError({ statusCode: 400, message: 'message is required' })
  }
  if (body.message.length > 4000) {
    throw createError({ statusCode: 400, message: 'message too long' })
  }
 
  const genai = new GoogleGenAI({ apiKey: config.geminiApiKey })
 
  try {
    const response = await genai.models.generateContent({
      model: 'gemini-2.5-flash',
      contents: body.message,
      config: {
        maxOutputTokens: 2048,
        temperature: 0.7
      }
    })
    return {
      text: response.text,
      usageMetadata: response.usageMetadata
    }
  } catch (error: any) {
    // Gemini API エラーの適切な変換
    if (error.status === 429) {
      throw createError({
        statusCode: 429,
        message: 'Rate limit exceeded. Please try again later.'
      })
    }
    throw createError({ statusCode: 500, message: 'AI generation failed' })
  }
})

クライアントサイドからの呼び出し

<!-- components/ChatInput.vue -->
<script setup lang="ts">
const message = ref('')
const response = ref('')
const loading = ref(false)
 
async function sendMessage() {
  if (!message.value.trim() || loading.value) return
  loading.value = true
  response.value = ''
 
  try {
    const data = await $fetch('/api/chat', {
      method: 'POST',
      body: { message: message.value }
    })
    response.value = data.text
  } catch (error: any) {
    response.value = `エラー: ${error.data?.message || '不明なエラー'}`
  } finally {
    loading.value = false
  }
}
</script>
 
<template>
  <div class="chat-container">
    <div class="response-area" v-if="response">{{ response }}</div>
    <div class="input-area">
      <textarea v-model="message" placeholder="メッセージを入力..." />
      <button @click="sendMessage" :disabled="loading">
        {{ loading ? '生成中...' : '送信' }}
      </button>
    </div>
  </div>
</template>

ストリーミングレスポンスの実装（SSE）

AI アプリのユーザー体験を大きく左右するのが「ストリーミング」です。レスポンス全文が生成されてから表示するのではなく、生成されたトークンをリアルタイムに表示することで、体感速度が劇的に改善されます。

サーバールートのストリーミング対応

// server/api/chat-stream.post.ts
import { GoogleGenAI } from '@google/genai'
 
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
  const body = await readBody(event)
 
  // SSE ヘッダーを設定
  setHeader(event, 'Content-Type', 'text/event-stream')
  setHeader(event, 'Cache-Control', 'no-cache')
  setHeader(event, 'Connection', 'keep-alive')
  setHeader(event, 'X-Accel-Buffering', 'no') // nginx バッファリング無効化
 
  const genai = new GoogleGenAI({ apiKey: config.geminiApiKey })
 
  // Nuxt の sendStream でストリームを返す
  return sendStream(event, async (stream) => {
    try {
      const result = await genai.models.generateContentStream({
        model: 'gemini-2.5-flash',
        contents: body.message,
        config: { maxOutputTokens: 2048 }
      })
 
      for await (const chunk of result) {
        const text = chunk.text
        if (text) {
          // SSE フォーマット: "data: ...\n\n"
          stream.write(`data: ${JSON.stringify({ text })}\n\n`)
        }
      }
      // 完了シグナル
      stream.write(`data: ${JSON.stringify({ done: true })}\n\n`)
    } catch (error) {
      stream.write(`data: ${JSON.stringify({ error: 'Generation failed' })}\n\n`)
    } finally {
      stream.end()
    }
  })
})

クライアントサイドの EventSource 受信

<!-- composables/useGeminiStream.ts -->
<script setup lang="ts">
export function useGeminiStream() {
  const streamText = ref('')
  const isStreaming = ref(false)
 
  async function startStream(message: string) {
    isStreaming.value = true
    streamText.value = ''
 
    // fetch を使って POST + ReadableStream でストリーム受信
    const response = await fetch('/api/chat-stream', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message })
    })
 
    const reader = response.body!.getReader()
    const decoder = new TextDecoder()
    let buffer = ''
 
    while (true) {
      const { value, done } = await reader.read()
      if (done) break
 
      buffer += decoder.decode(value, { stream: true })
      const lines = buffer.split('\n')
      buffer = lines.pop() || ''
 
      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = JSON.parse(line.slice(6))
          if (data.done) {
            isStreaming.value = false
          } else if (data.text) {
            streamText.value += data.text
          }
        }
      }
    }
  }
 
  return { streamText, isStreaming, startStream }
}
</script>

マルチターンチャットと状態管理

Gemini API のマルチターンチャットを Nuxt 3 で実装する際、チャット履歴の管理が重要になります。Pinia ストアと組み合わせることで、クリーンなアーキテクチャを実現できます。

// stores/chat.ts
import { defineStore } from 'pinia'
 
interface Message {
  role: 'user' | 'model'
  content: string
  timestamp: number
}
 
export const useChatStore = defineStore('chat', () => {
  const messages = ref<Message[]>([])
  const sessionId = ref(crypto.randomUUID())
 
  function addMessage(role: Message['role'], content: string) {
    messages.value.push({
      role,
      content,
      timestamp: Date.now()
    })
  }
 
  function clearChat() {
    messages.value = []
    sessionId.value = crypto.randomUUID()
  }
 
  // API に送る履歴形式に変換
  const apiHistory = computed(() =>
    messages.value.map(m => ({
      role: m.role,
      parts: [{ text: m.content }]
    }))
  )
 
  return { messages, sessionId, addMessage, clearChat, apiHistory }
})

// server/api/chat-multi.post.ts
import { GoogleGenAI } from '@google/genai'
 
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
  const body = await readBody(event)
  const { message, history = [] } = body
 
  const genai = new GoogleGenAI({ apiKey: config.geminiApiKey })
  const model = genai.models
 
  // 会話履歴を含めてコンテキストを構築
  const contents = [
    ...history,
    { role: 'user', parts: [{ text: message }] }
  ]
 
  const response = await model.generateContent({
    model: 'gemini-2.5-flash',
    contents,
    config: {
      systemInstruction: 'あなたは親切で丁寧なアシスタントです。日本語で回答してください。',
      maxOutputTokens: 2048
    }
  })
 
  return { text: response.text }
})

Nuxt ミドルウェアでのレート制限と認証

本番環境では、無制限の API 呼び出しを許可するとコストが膨大になります。Nuxt の server/middleware/ を使ってレート制限を実装しましょう。

メモリベースのシンプルなレート制限

// server/middleware/rate-limit.ts
const requestCounts = new Map<string, { count: number; resetAt: number }>()
 
const RATE_LIMIT = {
  maxRequests: 10,   // 1分間の最大リクエスト数
  windowMs: 60_000   // ウィンドウサイズ（1分）
}
 
export default defineEventHandler((event) => {
  // /api/chat* パスのみ適用
  if (!event.path.startsWith('/api/chat')) return
 
  const ip =
    getHeader(event, 'x-forwarded-for')?.split(',')[0].trim() ||
    event.node.req.socket.remoteAddress ||
    'unknown'
 
  const now = Date.now()
  const record = requestCounts.get(ip)
 
  if (!record || now > record.resetAt) {
    // 新しいウィンドウを開始
    requestCounts.set(ip, { count: 1, resetAt: now + RATE_LIMIT.windowMs })
    return
  }
 
  if (record.count >= RATE_LIMIT.maxRequests) {
    const retryAfter = Math.ceil((record.resetAt - now) / 1000)
    setHeader(event, 'Retry-After', String(retryAfter))
    throw createError({
      statusCode: 429,
      message: `レート制限に達しました。${retryAfter}秒後に再試行してください。`
    })
  }
 
  record.count++
})

本番環境ではメモリではなく KV や Redis でカウントを永続化することを推奨します。 Cloudflare Workers 環境では Cloudflare KV を、Vercel 環境では Vercel KV（Redis）を利用してください。

JWT を使った簡易認証

// server/middleware/auth.ts
export default defineEventHandler(async (event) => {
  if (!event.path.startsWith('/api/chat')) return
 
  const authHeader = getHeader(event, 'authorization')
  if (!authHeader?.startsWith('Bearer ')) {
    throw createError({ statusCode: 401, message: 'Unauthorized' })
  }
 
  // 実際の JWT 検証ロジックを実装
  const token = authHeader.slice(7)
  // ... JWT verify ...
})

本番環境へのデプロイ戦略

Cloudflare Pages + Workers（推奨）

Nuxt 3 は Cloudflare Pages への対応が成熟しており、エッジ実行による低レイテンシが期待できます。

# wrangler CLI のインストール
npm install -D wrangler
 
# Cloudflare Pages にデプロイ
npx nuxi build
npx wrangler pages deploy .output/public

# wrangler.toml
name = "gemini-nuxt-app"
compatibility_date = "2026-04-01"
compatibility_flags = ["nodejs_compat"]
 
[vars]
APP_ENV = "production"
 
# Secrets は wrangler secret put で設定
# GEMINI_API_KEY は --secret で管理

# API キーをシークレットとして登録
npx wrangler secret put GEMINI_API_KEY

Vercel へのデプロイ

# Vercel CLI でデプロイ
npm install -g vercel
vercel --prod

// vercel.json
{
  "framework": "nuxtjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".output/public",
  "env": {
    "GEMINI_API_KEY": "@gemini-api-key"
  }
}

Docker を使ったセルフホスト

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.output ./.output
ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

docker build -t gemini-nuxt-app .
docker run -e GEMINI_API_KEY=YOUR_KEY -p 3000:3000 gemini-nuxt-app

エラーハンドリングとコスト最適化

指数バックオフによるリトライ

Gemini API の一時的なエラー（429・503）には、指数バックオフでリトライするのが定石です。エラーハンドリングの実装パターンについては Gemini API エラーハンドリングとリトライパターン完全ガイドも参照してください。

// server/utils/retry.ts
export async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts = 3,
  baseDelay = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (error: any) {
      const isRetryable = error.status === 429 || error.status === 503
      if (!isRetryable || attempt === maxAttempts) throw error
 
      const delay = baseDelay * Math.pow(2, attempt - 1)
      const jitter = Math.random() * 1000
      await new Promise(r => setTimeout(r, delay + jitter))
    }
  }
  throw new Error('Unreachable')
}

コスト最適化の実践テクニック

API コストを最小化するために、以下の設定を組み合わせましょう。詳しくは Gemini API コスト最適化完全ガイドで解説しています。

1. maxOutputTokens の適切な制限

config: {
  maxOutputTokens: 512,    // 短い回答で十分な場合は制限する
  temperature: 0.5         // 創造性が不要な場合は低めに
}

2. Context Caching の活用

// 長いシステムプロンプトや固定コンテキストはキャッシュ
const cachedContent = await genai.caches.create({
  model: 'gemini-2.5-flash',
  contents: [/* 固定コンテキスト */],
  ttl: '3600s'
})

3. Gemini 2.5 Flash の優先使用 大半のユースケースでは gemini-2.5-flash で十分なパフォーマンスが出ます。gemini-2.5-pro は複雑な推論が必要な場合のみ使用することで、コストを 5〜10 倍削減できます。

4. リクエストのキャッシング

// server/api/chat.post.ts 内でのシンプルなキャッシング
const responseCache = new Map<string, string>()
 
// 同一メッセージは API を呼ばずキャッシュから返す
const cacheKey = JSON.stringify({ message: body.message })
if (responseCache.has(cacheKey)) {
  return { text: responseCache.get(cacheKey), cached: true }
}

使用量モニタリング

// server/api/chat.post.ts — 使用量ログ
const response = await genai.models.generateContent(/* ... */)
 
// usageMetadata でトークン使用量を記録
const usage = response.usageMetadata
console.log(`[Usage] prompt=${usage.promptTokenCount} output=${usage.candidatesTokenCount}`)
 
// 本番では CloudWatch / Datadog / Cloudflare Analytics に送信