Gemini API 预览工具按需检索能力
谷歌推出 Gemini API Tool Retrieval 预览,让智能体保留大型工具库,并在需要时才加载相应参数模式。该流程可在一次 Interactions API 请求内完成。
AI 深度解读
接了几十个函数或多个 MCP server 的 AI 应用,可能每次请求都在重复支付工具说明的 token 成本。Google 在 Gemini API 中预览的 Tool Retrieval,想解决的就是这笔开销:先给模型看工具名称和简短描述,需要调用时,再加载完整参数定义。
这篇报道的结论很明确:工具库可以按需加载,但省下多少还没有 Google 的实测数据。对程序员更有价值的,是弄清它减少了什么成本,又新增了什么成本。
工具还没调用,为什么已经花了不少 token
传统工具调用通常会把函数声明随请求一起交给模型。工具一多,参数类型、字段说明、嵌套结构就会占据大量上下文。原文援引 Google 文档称,几十个函数声明,每次请求就可能消耗数万 token。
Tool Retrieval 把工具的「发现」和「参数加载」拆开。模型先看到名称与简短描述,选中工具后,才拿到完整 schema,也就是函数参数的结构定义。
它延迟加载的是工具参数说明,工具执行仍然由对应的执行方完成。
据原文,这项能力目前只在 Interactions API 的 v1beta 中预览。延迟加载的工具数量没有公布明确上限,但这不等于已经证明可以无限扩展。Google 给出的建议是:少于 20 个、变化不大的工具,继续静态加载。
这个边界很实用。只有几个函数的小应用,未必需要再加一层检索;大型工具库才更有机会从中受益。
一次工具检索,应用究竟要处理什么
启用检索,需要在 tools 数组中加入下面这个条目:
{"type": "tool_search"}
关键是这一行只负责启用检索入口;想延迟加载的函数,还要分别设置 defer_loading: true。原文提到,发布示例使用 gemini-4-hydrogen,演示了延迟加载的 issue_refund,注释还提及另外 50+ 个延迟加载函数,但没有附上完整示例代码。
服务端模式下,响应包含三个步骤:
tool_search_call:模型按名称请求工具。tool_search_result:API 返回完整参数定义。function_call:模型生成实际函数调用。
前两步由 API 处理,应用执行 function_call,再返回 function_result。检索、加载参数和生成函数调用,可以在 1 次 API 请求内完成,不增加客户端往返。但业务函数执行及结果返回仍需应用处理。
函数还可以配置可选的 short_description,供检索阶段展示;它只在 defer_loading: true 时有效。既然模型在检索前看不到完整参数,名称和短描述就需要足够清楚,否则工具库虽大,模型也未必能选对。
对于 MCP,在 mcp_server 条目上设置 defer_loading: true,会延迟加载该服务暴露的全部工具。工具仍通过 Gemini API 的 MCP 支持远程执行。
少一次网络往返,不等于少一次模型计算
服务端检索是默认模式。Google 负责搜索,应用无需建立或托管索引。
客户端模式则设置 "execution": "client",由应用查询自己的 embedding 索引、工具注册表或权限过滤器,再通过 function_result.result 返回匹配的函数声明。它允许会话中途加入初始 tools 数组里没有的工具,代价是每次检索增加 1 次往返。
两种模式不能在同一个请求中混用,每个请求也只允许有 1 个 tool_search 条目。
费用上,原文说没有单独的功能收费,但有两项容易漏算:
- 每次服务端搜索都会针对完整上下文触发额外模型调用,其 token 计入
total_tool_use_tokens,按输入价格收费。 - 加载过的 schema 会在后续会话中持续作为输入计费,而且不能卸载。
服务端模式减少的是客户端往返,不能据此推断模型计算免费。
缓存也有条件。延迟加载的 schema 不进入提示前缀,加载后以内联方式追加,隐式缓存仍可生效;但初始提示变短,也可能低于最低可缓存长度。因此,小工具库或每轮都要搜索的场景,静态加载反而可能更便宜。
我的判断
我认同它针对的问题:把大量暂时用不到的参数说明反复塞进上下文,确实有优化空间。服务端托管适合希望减少集成工作的应用;客户端检索适合已有工具注册表、需要自定义筛选逻辑的团队。权限过滤可以参与检索,但业务函数执行时仍应校验权限。
不过,这篇报道解释了机制,没有给出 Gemini 的节省比例、准确率或延迟对照。我们不能据此判断实际收益。
原文列出的 Anthropic 数据是节省 85%,并列出 token 从 77K 降到 8.7K;Opus 4.5 准确率从 79.5% 升到 88.1%。OpenAI 则报告在 250 个 MCP Atlas 任务上节省 47%。这些都是厂商自报,测试条件不同,也不能当作 Gemini 的成绩。报道没有解释 85% 与上述 token 数值的统计口径。
兼容性同样需要单独核对。原文列出的 Gemini 模型为 Gemini 4 Carbon、Neon、Hydrogen、Argon,以及 3.8 Flash、3.6 Flash;Anthropic 为 Claude 5 series、Opus 4.5+、Sonnet 4.5+、Haiku 4.5;OpenAI 为 gpt-5.4 及之后版本。这些是报道提供的范围,不能顺带推断其他 API 或模型也支持。
与静态加载相比,按需检索多了搜索成本,也多了选错、漏选工具的可能。缺少对照数据时,「大型工具库值得试」是合理方向,「一定更便宜、更准确」则没有依据。
能拿来做什么
- 给现有 Node Agent 统计一次工具声明的 token 占用。如果少于 20 个稳定工具,可以先保留静态加载,把实际开销作为后续比较基线。
- 接入大量 MCP 工具时,用同一批任务比较静态加载与服务端检索,记录总费用、响应耗时和工具选择成功率,并单独观察
total_tool_use_tokens。 - 已有工具注册表或权限筛选需求的团队,可以评估客户端模式,同时把每次检索增加的 1 次往返计入延迟预算。
- 优先整理函数名称和
short_description,再测试容易混淆的工具。完整 schema 被延迟后,检索前的短说明就承担了更多选择责任。