google-gemini-file-search

Google Gemini File Search

ステータス：本番環境対応済み | 最終確認日：2025-11-18

---

File Search とは？

Google Gemini File Search はフルマネージド型の RAG（検索拡張生成）です。

• ドキュメントをアップロード → 自動チャンク化＋埋め込み＋ベクトル検索＋引用
• ベクトルデータベースのセットアップは不要
• 100 種類以上のファイル形式に対応（PDF、Word、Excel、コード、Markdown、JSON など）
• 引用メタデータ付きの組み込みグラウンディング
• コスト効率に優れています：100 万トークンあたり 0.15 ドル（インデックス作成時に一度のみ）、ストレージとクエリは無料

他の RAG との主な違い：

• Cloudflare Vectorize：チャンク化と埋め込みを自分で管理
• OpenAI Files API：Assistants API のスレッドに紐付けられる
• File Search：フルマネージド型のスタンドアロン RAG

---

クイックスタート（5 分）

1. API キーを取得してインストール

API キーを取得します：https://aistudio.google.com/apikey（無料枠：ストレージ 1 GB、1 日あたり 1,500 リクエスト）

bun add @google/genai

バージョン： 0.21.0+ | Node.js： 18+

2. 基本的な例

import { GoogleGenerativeAI } from '@google/genai';
import fs from 'fs';

const ai = new GoogleGenerativeAI(process.env.GOOGLE_AI_API_KEY);

// Create store
const fileStore = await ai.fileSearchStores.create({
  config: { displayName: 'my-knowledge-base' }
});

// Upload document
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('./manual.pdf'),
  config: {
    displayName: 'Installation Manual',
    chunkingConfig: {
      whiteSpaceConfig: {
        maxTokensPerChunk: 500,
        maxOverlapTokens: 50
      }
    }
  }
});

// Poll until done
while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  operation = await ai.operations.get({ name: operation.name });
}

// Query documents
const model = ai.getGenerativeModel({
  model: 'gemini-2.5-pro',  // Only 2.5 Pro/Flash supported
  tools: [{
    fileSearchTool: {
      fileSearchStores: [fileStore.name]
    }
  }]
});

const result = await model.generateContent('How do I install the product?');
console.log(result.response.text());

// Get citations
const grounding = result.response.candidates[0].groundingMetadata;
if (grounding) {
  console.log('Sources:', grounding.groundingChunks);
}

バッチアップロード、エラー処理、本番環境向けチェックリストを含む詳しい手順については、references/setup-guide.md を読み込んでください。

---

重要なルール

必ず行うこと

1. 更新時は削除して再アップロードする（ドキュメントは変更不可です）
2. ストレージ容量をファイルサイズの 3 倍で見積もる（埋め込み＋メタデータで約 3 倍になります）
3. チャンク化を設定する（技術文書は 500 トークン、文章は 800 トークン）
4. done: true になるまで（タイムアウトを設定して）オペレーションをポーリングする
5. ドキュメントを含むストアを削除する際は、force: true を使用する
6. Gemini 2.5 モデルのみを使用する（2.5-pro または 2.5-flash）
7. ドキュメントごとにメタデータを20 フィールド未満にする
8. インデックス作成コストを見積もる（100 万トークンあたり 0.15 ドル、一度のみ）

絶対に行わないこと

1. ドキュメントを更新しようとしない（PATCH API はありません）
2. ストレージ容量がファイルサイズと同じだと思い込まない（3 倍になります）
3. チャンク化の設定を省略しない（デフォルト設定が最適とは限りません）
4. ポーリングせずにアップロードしない（オペレーションがまだ処理中の場合があります）
5. ドキュメントを含むストアを、force を指定せずに削除しない
6. Gemini 1.5 モデルを使用しない（File Search には 2.5 が必要です）
7. メタデータを20 フィールド以上にしない（上限です）
8. コストを見積もらずに大きなファイルをアップロードしない

---

防止できる主なエラー 3 件

エラー 1：ドキュメントを変更できない

問題： 既存のドキュメントを更新しようとしている

解決策： 削除して再アップロードする

// Find and delete old version
const docs = await ai.fileSearchStores.documents.list({
  parent: fileStore.name
});
const oldDoc = docs.documents.find(d => d.displayName === 'manual.pdf');
if (oldDoc) {
  await ai.fileSearchStores.documents.delete({
    name: oldDoc.name,
    force: true
  });
}

// Upload new version
await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('manual-v2.pdf'),
  config: { displayName: 'manual.pdf' }
});

エラー 2：ストレージクォータ超過

問題： ストレージ容量の計算が間違っている（3 倍の係数）

解決策： アップロード前に見積もる

const fileSize = fs.statSync('data.pdf').size;
const estimatedStorage = fileSize * 3;  // Embeddings + metadata

if (estimatedStorage > 1e9) {
  console.warn('⚠️ May exceed free tier 1 GB limit');
}

エラー 3：モデルの互換性

問題： モデルのバージョンが間違っている

解決策： Gemini 2.5 のみを使用する

// ✅ CORRECT
const model = ai.getGenerativeModel({
  model: 'gemini-2.5-pro',  // or gemini-2.5-flash
  tools: [{ fileSearchTool: { fileSearchStores: [storeName] } }]
});

// ❌ WRONG
const model = ai.getGenerativeModel({
  model: 'gemini-1.5-pro',  // Not supported!
  tools: [{ fileSearchTool: { fileSearchStores: [storeName] } }]
});

チャンク化、オペレーションのポーリング、メタデータの上限、強制削除の要件を含む 8 件すべてのエラーと詳細な解決策については、references/error-catalog.md を読み込んでください。

---

File Search を使用する場面

File Search を使用する場面：

• フルマネージド型の RAG を利用したい場合（ベクトル DB 不要）
• コストの予測しやすさが重要な場合（インデックス作成は一度のみ）
• 100 種類以上のファイル形式に対応する必要がある場合
• 引用が重要な場合（グラウンディング機能を内蔵）
• シンプルなデプロイを優先する場合
• ドキュメントの変更頻度が比較的低い場合

代替手段を使用する場面：

Cloudflare Vectorize - グローバルなエッジ性能、カスタム埋め込み、R2 のリアルタイム更新
OpenAI Files API - Assistants API、会話型スレッド、非常に大規模なコレクション（10,000 件以上）

---

一般的なパターン

パターン 1：カスタマーサポートのナレッジベース

// Upload support docs with metadata
await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('troubleshooting.pdf'),
  config: {
    displayName: 'Troubleshooting Guide',
    customMetadata: {
      doc_type: 'support',
      category: 'troubleshooting',
      language: 'en'
    }
  }
});

パターン 2：ドキュメントの一括アップロード

const files = ['doc1.pdf', 'doc2.md', 'doc3.docx'];
const uploadPromises = files.map(file =>
  ai.fileSearchStores.uploadToFileSearchStore({
    name: fileStore.name,
    file: fs.createReadStream(file),
    config: { displayName: file }
  })
);
const operations = await Promise.all(uploadPromises);

// Poll all operations
for (const op of operations) {
  let operation = op;
  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 1000));
    operation = await ai.operations.get({ name: operation.name });
  }
  console.log('✅', operation.response.displayName);
}

パターン 3：ドキュメントの更新フロー

// 1. List existing documents
const docs = await ai.fileSearchStores.documents.list({
  parent: fileStore.name
});

// 2. Delete old version
const oldDoc = docs.documents.find(d => d.displayName === 'manual.pdf');
if (oldDoc) {
  await ai.fileSearchStores.documents.delete({
    name: oldDoc.name,
    force: true
  });
}

// 3. Upload new version
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('manual-v2.pdf'),
  config: {
    displayName: 'manual.pdf',
    customMetadata: {
      version: '2.0',
      updated_at: new Date().toISOString()
    }
  }
});

// 4. Poll until done
while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  operation = await ai.operations.get({ name: operation.name });
}

コードドキュメント検索や社内ナレッジベースを含む追加パターンについては、references/setup-guide.md を読み込んでください。

---

参照ドキュメントを読み込む場面

references/setup-guide.md を読み込む場面：

• File Search を初めてセットアップする場合
• すべての設定オプションを含む段階的な手順が必要な場合
• バッチアップロードの方法を設定する場合
• 本番環境へのデプロイ用チェックリストが必要な場合
• API の初期化パターンをすべて確認する場合

次の場合は references/error-catalog.md を読み込んでください：

• よくある8つのエラーのいずれかが発生した場合
• コード例を含む詳細なエラー解決策が必要な場合
• 予防チェックリストが必要な場合
• アップロード／クエリに関する問題をトラブルシューティングする場合
• チャンク化、メタデータ、コスト計算に関する問題を理解する場合

---

対応ファイル形式

100種類以上の形式に対応：

• ドキュメント：PDF、Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）
• テキスト：Markdown（.md）、プレーンテキスト（.txt）、JSON、CSV
• コード：Python、JavaScript、TypeScript、Java、C++、Go、Rustなど

非対応： PDF内の画像（テキスト抽出のみ対応）、音声ファイル、動画ファイル

---

料金

インデックス作成（1回限り）： 100万トークンあたり $0.15 ストレージ： 無料（プランに応じて10 GB～1 TB） クエリの埋め込み： 無料（取得したコンテキストは入力トークンとしてカウントされます）

例： 1,000ページのドキュメント ≈ 500kトークン → インデックス作成コスト：$0.075 → ストレージ：約1.5 GB（3倍の係数）

---

チャンク化のガイドライン

技術文書： 1チャンクあたり500トークン、オーバーラップ50 散文： 1チャンクあたり800トークン、オーバーラップ80 法律文書： 1チャンクあたり300トークン、オーバーラップ30

chunkingConfig: {
  whiteSpaceConfig: {
    maxTokensPerChunk: 500,  // Smaller = more precise
    maxOverlapTokens: 50     // 10% overlap recommended
  }
}

---

リソース

リファレンス（references/）：

• setup-guide.md - セットアップ手順の完全ガイド（認証、ストアの作成、ファイルのアップロード、バッチパターン、本番環境チェックリスト）
• error-catalog.md - 解決策付きで記載された8つすべてのエラー（変更不可性、ストレージ、チャンク化、メタデータ、コスト、ポーリング、強制削除、モデル互換性）

公式ドキュメント：

• File Search の概要：https://ai.google.dev/api/file-search
• API リファレンス：https://ai.google.dev/api/file-search/documents
• ブログ記事：https://blog.google/technology/developers/file-search-gemini-api/

---

質問や問題がありますか？

1. セットアップ全体については references/setup-guide.md を確認してください
2. 8つすべてのエラーについては references/error-catalog.md を確認してください
3. モデルのバージョンを確認してください（Gemini 2.5 である必要があります）
4. ストレージの計算を確認してください（ファイルサイズの3倍）