Gemini API File Search（RAG 工具）详解

一、它是什么？原理是什么？

File Search是 Gemini API 内置的、托管式 RAG（检索增强生成） 能力。
你把文件交给它，它会自动完成 导入 → 分块 → 向量化 → 索引。
当用户提问时，它会进行语义检索，把最相关的片段作为上下文输入模型，从而得到更准确且带引用的回答。
目前支持的模型包括 gemini-2.5-pro与gemini-2.5-flash。

⚙️ 基本工作流程

创建一个 File Search Store（索引容器）。
通过 uploadToFileSearchStore 或 importFile 将文档导入；系统自动分块、生成嵌入向量并建立索引。
- 原始文件 48 小时后删除；
- 向量索引数据将长期保存。
在生成内容时启用 tools.fileSearch，模型自动执行检索并返回引用（grounding metadata）。

二、它能做什么？（设计目标与应用场景）

File Search 的设计目标是让开发者无需自建向量库或维护嵌入逻辑。
你只需上传文件，剩下的由 Gemini 自动完成。

🎯 典型使用场景

知识库问答 / 客服助手：基于产品文档、FAQ、手册快速回答问题并给出引用。
内部文档助理：检索会议纪要、内部政策或研究资料，自动生成摘要。
内容与代码搜索：支持 PDF、DOCX、TXT、JSON、源代码等多格式检索。
多源融合：与 Google Search Grounding 联用，实现“内部文档 + 公网信息”并行检索。

💾 限制与存储配额

类型	限制
单文件大小	≤ 100 MB
Store 建议容量	< 20 GB（性能最佳）
项目总容量	Free 1 GB / Tier1 10 GB / Tier2 100 GB / Tier3 1 TB
Files API 原始文件	48 小时有效，单文件 ≤ 2 GB，总量 20 GB
File Search 索引	长期保存，约为原文大小的 3×

三、我能怎么用？（上手指南）

🧩 步骤概览

获取 Gemini API Key（Google AI Studio）。
安装 SDK（Python / JavaScript）。
创建 Store → 导入文件 → 调用模型启用 File Search 工具。

🐍 Python 示例

from google import genai
from google.genai import types
import time
 
client = genai.Client()
 
# 1) 创建 File Search Store
store = client.file_search_stores.create(
    config={'display_name': 'my-kb'}
)
 
# 2) 上传并导入文件
op = client.file_search_stores.upload_to_file_search_store(
    file="handbook.pdf",
    file_search_store_name=store.name,
    config={'display_name': 'handbook.pdf'}
)
while not op.done:
    time.sleep(2)
    op = client.operations.get(op)
 
# 3) 使用 File Search 进行问答
resp = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="用3条要点总结这份手册的安全规范，并给出处。",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                    file_search_store_names=[store.name]
                )
            )
        ]
    )
)
 
print(resp.text())
print(resp.candidates[0].grounding_metadata)

四、进阶用法与最佳实践

功能	说明
🔹 自定义分块	导入时传 `chunking_config` 调整 token 大小与重叠度
🔹 元数据过滤	上传时加 `custom_metadata`，查询时用 `metadata_filter` 筛选
🔹 控制召回数量	使用 `topK` 调节召回片段数量
🔹 展示引用	读取 `grounding_metadata` 渲染来源/证据
🔹 混合检索	同时启用 `fileSearch` 与 `google_search`，结合私有+公网来源
🔹 性能建议	单 Store 控制在 20 GB 内，索引文件小于 100 MB

五、计费说明

项目	计费规则
索引嵌入	按嵌入模型价格（约 $0.15 / 百万 token）
存储	免费
查询嵌入	免费
生成时使用	按上下文 token 常规计费

六、Gemini vs Vertex AI

方案	适合场景
Gemini Developer API	快速构建、个人与小型项目
Vertex AI	企业级部署、VPC 环境、合规治理、监控需求

两者 SDK 均已统一为 Gen AI SDK，迁移无缝。

七、官方文档与资源

🧪 Google AI for Developers 官方文档 🧪 Introducing File Search 博文 🧪 @google/genai SDK 参考 🧪 Files API 限制说明 🧪 Google Search Grounding 组合使用指南

美丽新世界

探索

20251110_Gemini API File Search（RAG 工具）详解