Gemini API Tool Retrieval:100 个工具库怎么省 token

谷歌在 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 延迟、工具选择准确率。工具库规模在十几个以内时它可有可无,过了五十个这个功能基本就该默认打开。

相关阅读

全部文章归档与模型专题