google-gemini-file-search

Google Gemini 文件搜索

状态：已可用于生产环境 | 上次验证时间：2025-11-18

---

什么是文件搜索？

Google Gemini 文件搜索是一种全托管 RAG（检索增强生成）：

• 上传文档 → 自动分块 + 嵌入 + 向量搜索 + 引用
• 无需设置向量数据库
• 支持 100+ 种文件格式（PDF、Word、Excel、代码、Markdown、JSON 等）
• 内置依据，包含引用元数据
• 经济高效：每 1M 个令牌收费 $0.15（一次性索引），存储和查询免费

与其他 RAG 的主要区别：

• Cloudflare Vectorize：需要自行管理分块和嵌入
• OpenAI Files API：依赖 Assistants API 线程
• 文件搜索：全托管、独立的 RAG

---

快速入门（5 分钟）

1. 获取 API 密钥并安装

获取 API 密钥：https://aistudio.google.com/apikey（免费层级：1 GB 存储空间，每天 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. 估算索引成本（每 1M 个令牌一次性收费 $0.15）

绝不执行

1. 绝不要尝试更新文档（不存在 PATCH API）
2. 绝不要假设存储空间等于文件大小（实际为 3 倍）
3. 绝不要跳过分块配置（默认设置可能并非最佳）
4. 绝不要在未轮询的情况下上传（操作可能仍在处理中）
5. 如果存储中有文档，绝不要在未使用 force 的情况下删除
6. 绝不要使用 Gemini 1.5 模型（文件搜索要求使用 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] } }]
});

加载 references/error-catalog.md，查看全部 8 种错误及其详细解决方案，包括分块、操作轮询、元数据限制和强制删除要求。

---

何时使用文件搜索

以下情况适合使用文件搜索：

• 想要使用全托管 RAG（无需向量数据库）
• 重视成本可预测性（一次性索引）
• 需要支持 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：

• 首次设置文件搜索
• 需要包含所有配置选项的分步操作指南
• 配置批量上传策略
• 生产环境部署检查清单
• 完整的 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 中的图片（仅提取文本）、音频文件、视频文件

---

定价

索引（一次性）： 每 100 万个 token 收费 $0.15 存储： 免费（根据套餐提供 10 GB–1 TB） 查询嵌入： 免费（检索到的上下文计为输入 token）

示例： 1,000 页文档 ≈ 500k 个 token → 索引费用：$0.075 → 存储空间：约 1.5 GB（3 倍系数）

---

分块指南

技术文档： 每块 500 个 token，重叠 50 个 散文： 每块 800 个 token，重叠 80 个 法律文档： 每块 300 个 token，重叠 30 个

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

---

资源

参考资料（references/）：

• setup-guide.md - 完整的设置指南（身份验证、存储区创建、文件上传、批处理模式、生产环境检查清单）
• error-catalog.md - 全部 8 种已记录错误及其解决方案（不可变性、存储、分块、元数据、成本、轮询、强制删除、模型兼容性）

官方文档：

• 文件搜索概览：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. 查阅 references/error-catalog.md 了解全部 8 种错误
3. 确认模型版本（必须为 Gemini 2.5）
4. 检查存储空间计算（文件大小的 3 倍）