Gemini API 预览工具检索,减少令牌消耗
Gemini API 推出预览版 Tool Retrieval,让 Agent 在接入数百个工具时减少令牌使用。摘录未披露具体接入方式或节省比例。
AI 深度解读
工具库越来越大,Agent 每次请求都携带完整工具定义,成本和选择难度也会跟着涨。Google 这次公布的 Tool Retrieval,把工具的参数定义改成按需加载:先让模型知道有哪些工具,需要调用时再补齐细节。
它已在 Gemini Interactions API 中进入预览。值得关注的不是多了一个搜索接口,而是工具上下文可以分层管理了。不过,原文没有给出延迟、准确率或费用的对照数据,具体收益仍要用自己的请求验证。
模型先看工具目录,需要时再读参数
传统函数调用通常会把工具名称、描述和完整参数结构一起放进上下文。当 Agent 接入几十甚至几百个工具时,即使一次任务只用其中两个,其余工具的参数也会占用输入 token。
Tool Retrieval 将这部分信息拆开。模型仍然能看到所有延迟加载工具的名称和描述,但暂时看不到参数 schema,也就是调用工具时必须遵守的字段、类型和必填规则。
延迟加载的是参数定义,工具名称和描述仍然留在上下文里。
启用方式是在请求中加入 tool_search,再给需要延迟加载的工具设置 defer_loading: true。下面这段代码展示了如何把退款工具放进待加载目录:
from google import genai
client = genai.Client()
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "issue_refund",
"description": "Refund an order to the original payment method.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
"amount": {"type": "number"},
},
"required": ["order_id", "amount"],
},
},
# ... 另外 50 多个延迟加载函数,常用工具保持直接加载
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Order A-1042 arrived damaged. Please refund 40 dollars.",
tools=tools,
)
重点看 defer_loading 所在的位置:开发者仍然提交了退款工具的完整参数定义,只是 API 暂时不把它加载进模型上下文。因此,不能把它理解为客户端连工具定义都不用传。
模型识别出需要 issue_refund 后,会按名称请求工具,API 加载参数定义,再由模型生成函数调用。这些步骤发生在同一次 API 请求内。退款操作仍由应用代码执行,然后回传 function_result;加载工具不会自动替你完成业务操作。
原文建议保留高频工具的直接加载,把低频工具延后。这比一股脑开启延迟加载更符合它的设计目的。
内置检索省接入,自建检索保留控制权
默认方案由 Gemini 在服务端检索,不需要开发者另建或托管索引。调试入口是 interaction.steps,可以查看搜索、加载结果和最终调用:
"steps": [
{
"type": "tool_search_call",
"id": "tsc_7f2a",
"arguments": {"function_names": ["issue_refund"]},
"signature": "..."
},
{
"type": "tool_search_result",
"call_id": "tsc_7f2a",
"result": [{"type": "function", "name": "issue_refund", "parameters": {...}}],
"signature": "..."
},
{
"type": "function_call",
"id": "fc_91c3",
"name": "issue_refund",
"arguments": {"order_id": "A-1042", "amount": 40}
}
]
注意 function_names:这里展示的是模型按工具名称发起请求。若选错工具,可以结合这些步骤检查名称和描述是否容易混淆。这是响应结构节选,包含占位内容,不能当作完整 JavaScript 程序运行。
如果团队已有工具注册表、向量索引,或需要按用户权限筛选工具,也可以给 tool_search 设置 "execution": "client",自行定义搜索参数。原文示例将搜索函数命名为 search_tools,接收必填的 query。
这条路径由应用执行检索,每次搜索增加一轮往返。应用把匹配的 {"type": "function", ...} 定义装进 function_result,再通过 client.interactions.create 提交,并用 previous_interaction_id=interaction.id 关联前一次交互。
它的额外价值是工具不必提前全部声明。用户在对话中连接新集成后,应用可以再暴露相应工具。但权限筛选仍需应用实现,原文没有说检索功能会自动处理授权。
对于远程 MCP 服务,可以直接给 mcp_server 设置 defer_loading: true,让该服务暴露的工具按需加载,无须逐个配置。
省不省钱,要看哪些参数始终没被加载
Tool Retrieval 没有单独收费,但不等于使用它没有开销。
tool_search 会增加一小块固定输入 token。被加载的参数定义,在后续对话中仍按输入 token 计费,和一开始就声明的工具一样。输入、输出 token 都遵循所调用模型的标准价格。
所以,收益主要来自那些始终没有加载的参数定义。如果工具库很大,而单次对话只触及少数工具,就有节省空间;如果大部分工具最终都会用到,节省空间便会收窄,还要考虑检索开销。原文没有给出工具数量的适用阈值。
它也能配合前缀缓存(prefix caching):延迟加载的参数不进入提示词开头,实际需要的定义追加到后续对话,因此缓存前缀可以保持稳定。这是在解释兼容机制,不是给出了缓存命中率提升数据。
按原文说明,支持范围是 Interactions API 中的 Gemini 3.6 及之后模型,包括全部 Gemini 4 模型;代码使用 gemini-4-hydrogen。能力仍处于预览阶段,原文没有展开其他 API 的支持情况。
我的判断
我认可它把工具目录和调用细节分开管理。对于参数复杂、低频工具多的 Agent,完整 schema 常驻上下文确实会携带大量当前任务用不到的信息。
但准确率提升需要打个问号。Google 将降低延迟、减少 token 和改善工具选择准确率作为收益,却没有提供测试集、工具规模、模型配置或对照结果。原文提供的是机制说明和接口示例,没有可用于推算收益的实测数据。
而且,模型仍要阅读工具名称和描述。工具大量重名、职责交叉、描述含糊时,仅延迟加载参数未必能解决选择问题。它也没有消除工具目录随规模增长而占用上下文的问题。
与应用提前筛出一小组工具相比,内置检索减少了自建检索逻辑;客户端检索则适合已有注册表和权限体系的团队,代价是额外往返与维护工作。只有少量工具的应用,继续直接声明通常更容易理解,没必要仅为接入新功能增加流程。
能拿来做什么
- 给现有 AI 编程助手盘点一次工具使用频率,把文件读取等高频工具与低频集成分开,再挑参数定义较大的低频工具试用延迟加载。
- 在 Node 服务接入时,用同一批真实任务比较完整声明与按需加载,记录输入 token、总耗时和工具选择是否正确,再决定是否扩大使用。
- 调试选错工具的问题时,检查
interaction.steps中的搜索名称、返回定义和最终参数,定位问题发生在哪一步,再修改工具描述。 - 如果团队已有按用户授权的工具注册表,可以评估客户端检索,并在返回工具定义之前完成权限筛选;不要把工具检索当成授权机制。