google-gemini-file-search

用途

Google Gemini File Search 是一套全托管的 RAG（检索增强生成）系统。用户上传文档后，可用自然语言进行查询，系统自动完成分块、嵌入、语义搜索并给出引用来源。支持 100 多种文件格式，包括 PDF、Word、Excel 和代码文件。

本技能（Skill）提供完整的 @google/genai File Search API 配置方法、常见错误预防策略、分块最佳实践、成本优化建议，以及 Cloudflare Workers 与 Next.js 集成模板。

主要能力

全托管 RAG：自动分块、嵌入、语义检索与引用。
支持 100 多种文件格式上传。
提供 8 类已记录错误的预防策略（资料中另提及共预防 12 类常见错误）。
分块最佳实践，用于优化检索质量。
成本优化指导（索引 $0.15/1M tokens，存储约为输入文件的 3 倍）。
Cloudflare Workers + Next.js 集成模板。

使用方式

前置条件

Google AI API 密钥：在 https://aistudio.google.com/apikey 创建。
- 免费层限制：所有文件搜索存储合计 1 GB 存储；每天 1,500 次请求；每分钟 100 万 tokens。
- 付费层定价：索引 $0.15 / 1M 输入 tokens（一次性）；存储免费（Tier 1：10 GB，Tier 2：100 GB，Tier 3：1 TB）；查询时嵌入免费（检索到的上下文计入输入 tokens）。
Node.js 环境：最低 Node.js 18+（推荐 v20+）。
安装 @google/genai SDK：
```
npm install @google/genai
# 或
pnpm add @google/genai
# 或
yarn add @google/genai
```
当前稳定版本 1.30.0+（可用 npm view @google/genai version 验证）。 ⚠️ 重要：File Search API 需要 @google/genai v1.29.0 或更高版本。更早版本不支持 File Search。该 API 于 v1.29.0（2025 年 11 月 5 日）加入。

TypeScript 配置（可选但推荐）：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  }
}

常见错误与预防

本技能预防 12 类常见错误，资料中详细记录了其中 8 类：

错误 1：文档不可变性 症状：Error: Documents cannot be modified after indexing。原因：文档索引后不可修改，没有 PATCH 或 UPDATE 操作。预防：使用删除后重新上传的模式进行更新。

错误 2：存储配额超限 症状：Error: Quota exceeded. Expected 1GB limit, but 3.2GB used. 原因：存储计算包含输入文件 + 嵌入 + 元数据，总存储约为输入大小的 3 倍。预防：上传前按 3 倍系数估算存储。

错误 3：分块配置不当 症状：检索质量差、结果不相关或上下文在句子中间被截断。原因：默认分块可能不适合内容类型。预防：按内容类型配置分块。分块指南：

技术文档/代码：500 tokens/块，重叠 50。
散文/文章：800 tokens/块，重叠 80。
法律/合同：300 tokens/块，重叠 30（高精度）。

错误 4：元数据超限 症状：Error: Maximum 20 custom metadata key-value pairs allowed。原因：每个文档最多 20 个元数据字段。预防：设计紧凑的元数据模式，使用层级键或 JSON 字符串。

错误 5：索引成本意外 症状：上传 10 GB 文档后收到 $375 的意外账单。原因：索引成本为一次性，但按输入 token 计算（$0.15/1M tokens）。预防：索引前估算成本。成本示例：

1 GB 文本 ≈ 250M tokens = $37.50 索引费。
100 MB PDF ≈ 25M tokens = $3.75 索引费。
10 MB 代码 ≈ 2.5M tokens = $0.38 索引费。

错误 6：未轮询操作状态 症状：上传后立即查询无结果，或索引不完整。原因：文件上传为异步处理，必须轮询操作直到 done: true。预防：始终轮询操作状态，并设置超时与回退方案。

错误 7：忘记强制删除 症状：Error: Cannot delete store with documents. Set force=true. 原因：含文档的存储需要 force: true 才能删除（防止误删）。预防：删除非空存储时始终使用 force: true。

错误 8：使用不支持的模型 症状：Error: File Search is only supported for Gemini 3 Pro and Flash models。原因：File Search 需要 Gemini 3 Pro 或 Gemini 3 Flash，不支持 Gemini 2.x 和 1.5 模型。预防：始终使用 Gemini 3 模型。

资料中另记录以下错误：

错误 9：Blob 来源的 displayName 未保留（v1.34.0+ 已修复） 症状：groundingChunks[0].title === null。原因：在 v1.34.0 之前的 @google/genai 版本中，以 Blob 对象（非文件路径）上传文件时，SDK 会丢弃 displayName 和 customMetadata 配置字段。预防：升级到 v1.34.0+；v1.33.0 及更早版本可使用可续传上传（resumable upload）作为变通方案。

错误 10：JSON 响应模式下忽略 grounding 元数据 症状：即使配置了 fileSearch 工具，response.candidates[0].groundingMetadata === undefined。原因：使用 responseMimeType: 'application/json' 进行结构化输出时，API 会忽略 fileSearch 工具且不返回 grounding 元数据，即使使用 Gemini 3 模型。预防：采用两步法——先获取带 grounding 的文本响应，再在提示中转换为结构化格式。

错误 11：Google Search 与 File Search 工具互斥 症状：Error: "Search as a tool and file search tool are not supported together"，状态 INVALID_ARGUMENT。原因：Gemini API 不允许在同一请求中同时使用 googleSearch 和 fileSearch 工具。预防：使用独立的专用代理，根据查询类型编排。

错误 12：Batch API 缺少响应元数据（社区来源） 症状：使用 metadata 字段时无法将批量响应与请求关联。原因：使用 Batch API 且 InlinedRequest 包含 metadata 字段时，对应的 InlinedResponse 不返回该 metadata。

适用场景

构建文档问答系统。
需要自动分块、嵌入、语义检索与引用的 RAG 应用。
处理多种格式文档（PDF、Word、Excel、代码）的检索场景。
在 Cloudflare Workers 或 Next.js 中集成文件搜索能力。

限制

文档索引后不可修改，更新需删除后重新上传。
存储约为输入大小的 3 倍，免费层合计 1 GB。
每个文档最多 20 个自定义元数据键值对。
仅支持 Gemini 3 Pro 和 Gemini 3 Flash 模型。
googleSearch 与 fileSearch 工具不能在同一请求中使用。
使用 JSON 响应模式时会丢失 grounding 元数据。
上传为异步处理，需轮询操作状态。
删除非空存储需 force: true。
索引按输入 token 计费（$0.15/1M tokens，一次性）。