TodayAI

GuidesRAG

用 Gemini File Search 做托管文档检索

创建 File Search store、上传文档、等待索引，再在 Interactions 中启用 file_search 做 RAG 问答。

基于 Google AI for Developers 整理 · 官方资料 ↗

自己做 RAG 通常要切块、嵌入、建索引、写检索，再把命中片段塞进 prompt。Gemini File Search 把导入、切块、索引和检索托管在 API 一侧；你负责建 store、上传文件，并在 Interactions 里声明 file_search。

这篇只走官方 Interactions API 路径：创建带 gemini-embedding-2 的 File Search store，上传文档并轮询处理完成，再用 gemini-3.6-flash 提问，最后从 annotations 确认引用。

Gemini File Search 把哪些工作托管了

官方说明：File Search 会 import、chunk、index 你的数据，再根据 prompt 做快速检索；检索结果作为上下文交给模型，生成更贴文档的回答。

它还支持多模态：文本嵌入可用 gemini-embedding-001，图像/多模态嵌入用 gemini-embedding-2。官方同时注明：当前不支持 audio / video 格式。

对你来说，主路径是：创建 File Search store → 上传并等待索引 → 在 interactions.create 的 tools 里启用 file_search → 读回答与引用。

创建 File Search Store

Store 是文档嵌入的容器。官方示例创建时指定 embedding_model 为 models/gemini-embedding-2。需要环境变量中的 Gemini API Key，并安装 google-genai。

安装官方 Python SDK

bash
pip install -U google-genai
python
from google import genai
import time

client = genai.Client()

file_search_store = client.file_search_stores.create(
    config={
        "display_name": "your-fileSearchStore-name",
        "embedding_model": "models/gemini-embedding-2",
    }
)
print(file_search_store.name)

打印出的 name 后面上传和查询都会用到。官方还说明：经 File API 上传的原始文件约 48 小时后删除，但导入 File Search store 的数据会一直保留，直到你手动删除。

上传文档并等待处理

用 upload_to_file_search_store 把本地文件导入 store。它返回长时间运行的 operation，需要轮询直到 done。

python
operation = client.file_search_stores.upload_to_file_search_store(
    file="sample.txt",
    file_search_store_name=file_search_store.name,
    config={"display_name": "display-file-name"},
)

while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

print("indexed")

索引未完成就提问，检索往往空空如也。先确认 operation.done，再用文档里明确出现过的问题去问。

用 Interactions 查询

在 tools 里声明 type 为 file_search，并传入 file_search_store_names。官方示例模型为 gemini-3.6-flash。

python
interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Can you tell me about [insert question]",
    tools=[{
        "type": "file_search",
        "file_search_store_names": [file_search_store.name],
    }],
)

检索与 grounding 发生在服务端；你不需要自己先搜一段文字再拼进 prompt。接下来要做的是核对回答是否真的用了文件。

怎么确认模型使用了文件

遍历 interaction.steps，找到 type 为 model_output 的步骤，打印文本；若有 annotations，检查 type 为 file_citation 的项，并查看 file_name 与 source。

python
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "file_citation":
                            print(f"  - {annotation.file_name}: {annotation.source}")
  • file_search_stores.create 返回了 store name
  • upload 的 operation.done 为 true
  • 提问后得到与文档相关的回答
  • annotations 中出现 file_citation（有引用时）

和自己管理 Embeddings 有什么区别

File Search 把切块、嵌入、索引、语义检索托管在 Gemini API。你主要管理 store、上传与查询时的 tool 声明。

若你要精细控制切块策略、自建向量库、或检索必须完全跑在自有基础设施上，应改看 Embeddings 文档，自己管向量与检索，而不是指望 File Search 暴露整条索引链路。

创建 store 时选 embedding_model 也有产品含义：gemini-embedding-2 面向图像/多模态；默认文本路径可用 gemini-embedding-001。按官方说明，当前仍不支持把 audio / video 当 File Search 文档。

最容易踩的坑

operation 一直不完成

继续按官方示例轮询 client.operations.get；检查文件格式是否受支持，以及 API 配额。

答案完全不接地、没有 file_citation

确认 file_search_store_names 正确、索引已完成，并换一个文档内明确出现过的问题再试。

想上传音视频

官方明确：Audio and video formats are not currently supported。

把 File Search 当成自建向量库的替代调试面

它不暴露你自己维护的 chunk/embedding 流水线。需要那一层控制时，改走 Embeddings + 自建检索。

官方资料

Google AI for Developers

File Search ↗