谷歌在 11 月 19 日给 Gemini API 上线了一项叫 Tool Retrieval 的预览功能,解决的是智能体接了几十个甚至上百个工具之后越来越贵、越来越慢、越来越容易选错工具的问题。一句话结论:只要你的工具库超过十几个,Tool Retrieval 就能把没被调用的那部分 schema 从上下文里摘掉,省下的输入 token 直接体现在账单和延迟上。
这件事的触发点很朴素。智能体每发一次请求,都要把它认识的所有工具的完整参数结构拼进提示词里。一个工具的参数 schema 平均几百到上千 token,五十个工具就是几万 token。这些 token 每一轮对话都要重付一遍,还得跟真正的任务指令抢模型的注意力。结果就是工具选错率上升,首 token 延迟变长,成本还线性膨胀。
Tool Retrieval 的做法是把 schema 从上下文里搬出去,但把工具的名字和描述留在里面。模型看到的是一张目录,需要哪一项就点名要,API 再把那一项的完整参数结构加载进来。整个查找、加载、调用都发生在同一次 API 请求内部,你的代码不需要多发一轮。
tool_search 加 defer_loading 就是全部的接入改动
接入方式非常轻。请求里加一个 tool_search 工具,然后在想延后加载的工具上设置 defer_loading: true。
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"],
},
},
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Order A-1042 arrived damaged. Please refund 40 dollars.",
tools=tools,
)
这里的关键语义是,被标记为 defer_loading 的工具,模型仍然看得见名字和描述,所以它知道有这个工具存在,但看不见参数结构。于是模型发出一个按名字检索的请求,API 把 schema 补上,模型随即输出函数调用,三步连续完成,客户端全程感知不到中间的加载过程。
调试的时候可以在 interaction.steps 里看到完整轨迹,一共三种 step 类型。
| step 类型 | 作用 | 关键字段 |
|---|---|---|
| tool_search_call | 模型点名要检索哪些工具 | arguments.function_names |
| tool_search_result | API 回填被检索到的完整 schema | call_id、result |
| function_call | 模型基于刚加载的 schema 发起调用 | name、arguments |
这三个 step 全部出现在同一次请求的返回里,所以工具描述写得好不好、工具名起得清不清楚,可以直接对着日志排查,不需要靠猜。检索是谷歌服务端做的,你不需要自己建索引、自己托管向量库,也不需要把工具注册表搬上云。
服务端检索和客户端检索,差别在一次往返
如果你本来就维护着自己的工具注册表、向量索引,或者需要按用户权限过滤工具,官方给了另一条路:把 tool_search 声明成 "execution": "client",然后自己定义查询参数。
tools = [{
"type": "tool_search",
"execution": "client",
"name": "search_tools",
"description": "Search the internal tool registry for functions.",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
}]
模型发出 function_call 调 search_tools 时,你的应用自己跑这个查找,把命中的 schema 通过 function_result 回传,再用 previous_interaction_id 接着上一次交互继续。代价是多一次网络往返,收益是工具不必提前声明,用户中途接入一个新集成时也能在对话进行中暴露出来。
| 方案 | 检索在哪跑 | 额外往返 | 适合谁 |
|---|---|---|---|
| 全量 schema 内联 | 不检索 | 0 | 工具不超过十个的简单场景 |
| Tool Retrieval 服务端 | 谷歌服务端 | 0 | 工具多但都是自家标准工具 |
| Tool Retrieval 客户端 | 你的应用 | 1 | 有自建注册表、向量索引或权限过滤需求 |
三条路的差别,本质上是一次往返换一次控制权。工具数量少的时候内联最省事,工具上百个的时候服务端检索是最省心的折中,只有当权限或个性化检索无法外包时才值得自己扛那次往返。
计费方式:没有新费用,省的是没加载的那部分
Tool Retrieval 本身不单独收费,输入输出 token 按你调用模型的常规价计费。开销有两处变化:开启 tool_search 会增加一小块固定的输入 token,而模型实际加载的每一个 schema 从加载那一刻起按普通输入 token 计费,一直算到本轮对话结束。
所以省钱的逻辑很直白。没被加载的 schema 数量多于被加载的 schema 数量时才划算,而这在大型工具库里是常态。谷歌自己的措辞也是让你拿自己的流量实测,而不是给一个通用倍数。
| 模型 | 输入 / 百万 token | 输出 / 百万 token | 备注 |
|---|---|---|---|
| Gemini 4 Hydrogen | 1.50 美元 | 7.50 美元 | 1M 上下文窗口内统一计价 |
| Gemini 4 Carbon | 2.00 美元 | 10.00 美元 | 推广价至 11 月 30 日 |
| Gemini 4 Neon | 3.00 美元 | 15.00 美元 | 四档思考级别,1M 上下文 |
拿 Gemini 4 Hydrogen 的输入价 1.50 美元每百万 token 做个粗算。假设你的工具库有 60 个工具、平均每个 schema 800 token,一次对话内联全部工具就是约 4.8 万 token,按这个价折算单次请求约 0.072 美元。而真实业务里一次任务平均只用到 2 到 3 个工具,也就是 2400 token 的 schema 加上加载时固定增加的那一小块。即便把「没加载」的部分算保守,这个差距也足以让账单曲线明显变平。
和 prefix caching、MCP 的配合方式
Tool Retrieval 与前缀缓存是天然互补的。被延后的 schema 不会出现在提示词开头,加载进来的 schema 追加在对话后段,所以从第一轮到最后一轮,被缓存的前缀保持不变。这对多轮对话尤其重要,否则每轮都变化的工具描述会把整个缓存前缀冲掉。
和远程 MCP 服务器也能一起用。给 mcp_server 工具设置 defer_loading: true,这个服务器暴露的所有工具就都变成按需加载,你不需要再逐个列出工具清单。这对那种挂着几十个工具的 MCP 服务器是很实用的简化。
支持范围上,Tool Retrieval 需要 Gemini 3.6 及更新的模型,包含全部 Gemini 4 系列模型,接口走的是 Interactions API。文档还提到 Gemini 4 Neon 在 Interactions API 里可直接使用,上一篇讲 Gemini 4 Neon 定价的稿子里提到过它的 3 美元每百万 token 输入价和四档思考级别,可以对读。
什么场景值得开,什么场景不值得
值得开的信号很明确。工具数量上去了(超过十几个)、单次任务的输入 token 里工具 schema 占比很高、工具选择准确率随工具增多而下降、或者你在为输入 token 的单价发愁,这四条命中任意一条都该试。
不值得开的场景也存在。工具只有五六个的时候,内联的全部成本本来就低于加载动作本身的复杂度收益。交互流程对延迟极其敏感、而工具库又小的时候,多次加载带来的请求内开销可能不划算。如果你的应用已经在用 Ollama 做函数调用,那套 schema 治理经验在 Gemini 侧同样适用,只是入口换了地方。
还有一个容易被忽略的细节:Tool Retrieval 走的是 Interactions API 而不是老的 generateContent。用老的接口做函数调用的项目要迁移调用方式,这部分改造成本要算进账。站内关于 FastMCP 改名后 MCP 服务怎么起 的实测写过 MCP 侧的部署细节,工具数量一多,MCP 服务器那侧的加载压力也会同步上来。
常见问题
Tool Retrieval 会让模型看不见工具吗?
不会。模型始终能看到每个被延后工具的名字和描述,只是不带参数结构。所以它依然知道有哪些工具可用,能决定去检索哪一个,只是检索前看不到具体参数长什么样。
开启后要怎么确认真的省了 token?
看返回里的 interaction.steps,里面每一条 tool_search_result 对应一个被实际加载的 schema,把它和工具库总数相减就知道有多少 schema 被留在了上下文之外。
这个功能现在稳定吗?
目前是预览状态,需要用 Gemini 3.6 或更新的模型,并通过 Interactions API 调用。谷歌没有给单独的收费项,也没有说明它何时转正式版,正式投产前建议先在自己流量上做一轮成本对照。
小结
Tool Retrieval 把「工具太多」这个智能体工程里最贵的问题,换成了一个显式开关。改动集中在请求体两处字段,收益却同时落在三个维度:输入 token 账单、首 token 延迟、工具选择准确率。工具库规模在十几个以内时它可有可无,过了五十个这个功能基本就该默认打开。
相关阅读
- Gemini 4 Neon 怎么选:3 美元每百万 token 与 AA 61 分
- Gemini Decisions API 上线:1000 题单次判定与 0.1 美元定价
- Ollama 函数调用怎么配:七个不报错的坑
- FastMCP 改名后 MCP 服务怎么起:pip 装 2.3 实测
- Codex 沙箱怎么配:3 个平台的权限模型与 3128 端口
延伸阅读
- 腾讯元宝桌宠上线PC端:24小时陪伴、拖拽文件自动摘要1 月前
- 谷歌 Gemini 测试中自主入侵 3 家公司:首次确认 AI 突破测试环境,安全红线告急2 月前
- Qwen-UI-Agent 发布:阿里通义 GUI 智能体基座模型,100+ 真机 150+ 应用训练超越 GPT、Claude、Gemini2 月前
- 4个Gemini 4 Argon智能体27小时通关《我的世界》1 月前
继续读
往下这几篇值得接着看:
想快速查定义?对应的词条在这里:
- Gemini 4词条 · AI 自学笔记
