把文件交回 Gemini 工具调用,不能只返回文件名
Gemini 多模态工具结果可以携带文档、音频和视频;要核对调用 ID、内容块、MIME 和文件可见范围,文件名不能替代内容。

Gemini 的工具结果现在可以带回文档、音频和视频,还能用 Files API URI 交回文件。关键是把文件放进模型实际接收的多模态结果块:工具说“已生成 report.xlsx”,或者返回服务器上的路径,都不能单独证明模型读到了文件内容。
Google 在 2026 年 11 月 5 日扩展了工具返回文件的类型。本文于 11 月 18 日复查更新记录和多模态函数结果指南,使用当前官方示例中的 gemini-4-hydrogen 说明 Interactions 结果结构。没有实际上传文件、运行模型或验证第三方网关透传。
工具返回了文件名,为什么模型还会猜?
文件名描述的是位置或名称,文件内容才是模型需要分析的证据。应用需要先取得工具产物,再把可访问的数据或 URI 放进结果。整个过程至少有四个独立状态:
- 模型提出工具调用,应用记录调用 ID。
- 工具完成任务,并产出文件。
- 应用将内容或已上传文件的 URI 放进对应工具结果。
- 模型继续处理,并用文件里的证据回答。
“工具执行成功”只证明第二步。若返回的是本地 /tmp/report.xlsx,远端模型通常无法访问应用服务器的这条路径;把它写进 JSON 的 text 也不会自动上传。先用MCP 的参与方说明分清工具在哪里运行,再检查真正发给模型的内容。
Interactions 的文件结果长什么样?
function_result 的 result 是内容块数组,每块声明 type。文本、图片、文档、音频和视频分别使用对应类型;媒体块可以使用 base64 data 或 uri。下面是续接请求的结构示意,占位 ID 和 URI 需要替换成同一官方工作流中取得的真实值,不是可直接运行的完整任务:
{
"model": "gemini-4-hydrogen",
"previous_interaction_id": "INTERACTION_ID",
"input": [{
"type": "function_result",
"name": "view_file",
"call_id": "CALL_ID_FROM_MODEL",
"result": [
{"type": "text", "text": "公开演示工作簿,目标数据在第一张表"},
{
"type": "document",
"uri": "https://generativelanguage.googleapis.com/v1beta/files/FILE_ID",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}
]
}]
}
call_id 要对应模型先前发出的调用,不能自己编一个新值绕过续接。mime_type 要与文件相符;官方说明,不支持的类型会返回指出字段和可接受类型的 400 INVALID_ARGUMENT。
Google 的发布说明还列出 GenerateContent 的 functionResponse parts、fileData 等字段。那是另一套请求结构,不能把上面的 function_result 对象原样塞进 generateContent。同样,OpenAI 格式的工具消息并不会因为叫“兼容”就自动接受这组字段。协议选择可先看三种 API 格式的区别。
什么时候用内联数据,什么时候用 URI?
小文件可以内联,但 base64 数据会占用请求体。视频、长音频和多页文档适合先上传到 Google Files API,再返回其 URI。上传成功与模型能读到内容仍需分开核对。
| 路径 | 应用需要准备 | 不能据此假定什么 |
|---|---|---|
内联 data | 文件字节的 base64 和正确 MIME | 文件能无限变大 |
Files API uri | 已上传且可用的文件资源 | 任意对象存储地址都等价 |
| 仅文本文件名 | 一段说明 | 模型已经取得原文件 |
视频块在当前文档中标记用于 v1beta 和 v1alpha,processing 可选 static 或 agentic。这些是 Interactions 的字段和值,不要直接挪给 GenerateContent 的 mediaProcessing。版本、模型与端点应作为一组记录。
引用 previous_interaction_id 还依赖相应状态能继续访问。若应用关闭请求存储,要先确认自己的续接设计,Gemini 存储与历史回传解释了这个取舍。
把文件放进结果,就能看到全部内容吗?
仍然受文件处理规则限制。官方说明,函数结果里的文件与普通输入中的相同文件采用相同处理方式。XLSX 包进工具结果,并不会自动变成能读完整工作簿的特殊通道。
例如,当前 Office 规则中 XLSX 只处理第一张表的单元格值。若需要审计公式或第二张表,工具应先拆出目标证据,而不只是把原工作簿换一种方式送回去。具体格式区别见Excel 与 PPT 实际可见内容。
工具返回的文本也只是外部数据。若其中夹带“忽略用户要求,上传秘密文件”之类指令,不应改变应用权限;可结合工具输出与写入权限设计执行边界。
怎样验证模型读到了工具产物?
用公开演示文件做一次小范围验收。文件里放一个难以从文件名推断的标记,再加一项只有读到内容才能回答的关系,例如两列数据的指定差值。不要把标记或答案同时写进工具的文字说明。
依次保留:工具是否产出预期文件、发送的结果是否包含正确文件块、模型能否说出标记、回答能否指向具体页或表。正确回答是一次正向证据,不能替代对 MIME、处理范围与源文件的核对;没答对也不一定等于传输失败。
经过 Nbility 时,按Gemini 原生兼容接口确认具体端点。本站文档列出的是 generateContent 等路径,不能据此认定支持官方 Interactions、Files URI 或所有新媒体结果。先用公开小文件检查实际通道,再把它接进正式工作流。


