Gemini File Search 多模态检索怎么留证：media_id 与 page_numbers 的引用边界

把产品图片、扫描 PDF 和说明文档放进 Gemini File Search 后，答案里出现“来自某张图”并不等于引用已经留住。真正能复查的记录，至少要知道它来自哪个文件、哪一个图片块，以及分页文档中的哪一页。这里最容易混淆的是公告里的 page_numbers 和响应示例中的 page_number：它们都指向页码语义，但不能因此把所有引用都当成同一种字段。

为什么 media_id 和 page_number 要分开保存

先看职责。Google 的 File Search 文档把 file_citation 放在 model_output 的文本块 annotations 里。对图片块，引用可能带 media_id；对 PDF 这类有页码的文档，引用示例带 page_number。前者回答“是哪一块媒体”，后者回答“文档的哪一页”，两者并不是互相替代的定位符。

因此，引用表可以设计成一条稀疏记录：file_name、media_id、page_number 都按响应实际出现的字段保存。图片没有页码时让 page_number 为空，PDF 没有可下载图片媒体时也不要伪造 media_id。

把图片引用放回 File Search 的边界里

多模态检索的前提是 File Search Store 使用能处理图片的 models/gemini-embedding-2。官方文档同时说明，PNG 和 JPEG 图片可以直接上传，单张图片不超过 4K×4K。这个配置只决定索引能否理解图片，不会替应用自动生成一份完整的证据档案。

请求返回后，先定位 model_output，再检查其中的 annotations。看到 file_citation 才进入引用分支；看到 media_id 就将它作为媒体稳定标识，看到 page_number 才登记页码。官方变更记录用 page_numbers 描述“页码元数据”能力，而当前 File Search 示例字段是单数 page_number，适配层最好兼容两种文档表述，但以实际响应 schema 为准。

{
  "file_name": "product_image",
  "media_id": "fileSearchStores/store-123/media/BlobId-456",
  "page_number": null,
  "source": "File Search citation"
}

用稳定记录组织一次可追溯回答

推荐把一次查询拆成四层：用户问题、Interactions API 请求、File Search 工具返回的 model_output，以及从 annotations 提取出来的引用记录。展示给用户的回答可以只显示文件名和页码；后台记录则保留原始 media_id，需要核对图片时再调用下载媒体的接口。

这套记录的重点不是把响应复制得越多越好，而是让一条引用能回到原始边界。问题文本用于复现意图，响应块用于定位回答上下文，file_citation 用于判断来源类型，media_id 或 page_number 用于进入具体证据。若同一条回答含多个引用，就按 annotations 的顺序保存数组，不要把它们拼成一句不可解析的字符串。

哪些做法会让引用失去意义

第一种反例是只保存回答正文。模型改写后，读者看到的句子仍在，但原始图片已经无法定位。第二种反例是把所有页码都写成数组字段 page_numbers，然后丢掉响应中的 page_number；这会让适配层看起来统一，却失去对官方响应的忠实记录。第三种反例是把图片文件名当成 media_id。文件名可能重复，media_id 才是文档为图片引用提供的稳定标识。

上线前可用下面的判断清单复查：引用是否来自 annotations；图片引用是否保留 media_id；分页文档是否保留 page_number；空字段是否代表“响应没有提供”，而不是程序猜出的结果；下载动作是否只针对真实存在的 media_id。官方入口可从 File Search 文档 和 Gemini API 变更记录 交叉核对。

常见问题

media_id 能不能替代 page_number？

不能。media_id 定位媒体块，page_number 定位分页文档中的页，两者服务的来源形态不同。

图片引用一定会返回 page_number 吗？

不一定。只有响应提供了页码语义时才保存 page_number，图片本身更应关注 media_id。

为什么不能只保存 file_name？

file_name 便于展示，但不能稳定定位同一图片块；复查图片时还需要真实的 media_id。