跳到主内容

Gemini API 上线工具检索:工具 schema 按需加载,不再全塞进 prompt

谷歌 2026-11-19 在 Interactions API 预览上线 Tool Retrieval:tool_search 加 defer_loading,模型只看到工具名与描述、用到才加载参数 schema,官方称不单独收费。

2026-11-20 · Google 官方博客(2026-11-19,一手实取) / AI Studio 文档(tool-retrieval)

发布 2026-11-20核实 2026-11-20

要点

  • 2026-11-19,谷歌在 Gemini API 的 Interactions API 里预览上线 Tool Retrieval(工具检索),作者署名 Lucia Loher(Gemini API 产品经理)与 Nora Kassner(Google DeepMind 研究科学家)。
  • 机制:请求里加一个 tool_search 工具,对要延迟的工具打 defer_loading: true;模型仍能看到工具名与描述,但参数 schema 不进上下文,用到时才由服务端加载。
  • 官方给出的动机是三条同时恶化:输入 token 膨胀、延迟上升、候选工具变多后选择准确率下降。
  • 适用范围:Gemini 3.6 及更高版本,含全部 Gemini 4 模型,仅在 Interactions API 中;状态 Preview。
  • 不单独收费。tool_search 占一小段固定输入 token,被加载的 schema 按输入 token 计费直至该对话结束。
  • 官方没有给任何 token 节省百分比,也没有给工具数量上限,只给了判断条件与「用自己的流量实测」的建议。

它省的是「从来没被用到的那些工具」

问题本身很好理解:Agent 接的工具越多,每轮请求里要带的 schema 就越多。一个工具几十到几百 token,五十个工具就是几千 token——而一次任务往往只用到其中两三个。

Tool Retrieval 的做法是把「有哪些工具」和「工具长什么样」拆开:

信息以前现在(defer_loading: true)
工具名在上下文里在上下文里
工具描述在上下文里在上下文里
参数 schema在上下文里用到时才加载
谁负责检索—服务端(默认)或你的客户端

关键点在于模型仍然知道有哪些工具。它靠名称与描述决定要不要用,而不是靠完整的 JSON Schema。这一步省下来的正好是上下文里最占地方的那块。

服务端检索怎么跑:一次请求内三步

打开 tool_search 之后,一次请求里会出现三个步骤,官方说可以直接在 interaction.steps 里看到:

1. tool_search_call     ← arguments: {"function_names": ["issue_refund"]}
2. tool_search_result   ← [{"type": "function", "name": "issue_refund", "parameters": {...}}]
3. function_call        ← name: "issue_refund", arguments: {"order_id": "A-1042", "amount": 40}

之后就是你熟悉的 function calling:你的代码执行退款、把 function_result 交回去。检索与调用在同一次请求里完成,不是两次往返。

请求侧的最小改法是这样(官方 Python 示例的骨架,gemini-4-hydrogen 为原文所用模型):

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "issue_refund",
        "description": "Refund an order to the original payment method.",
        "defer_loading": True,      # 关键:这个工具的 schema 延迟加载
        "parameters": {...},
    },
    # … 另外几十个同样 defer 的工具;常用的几个不要 defer
]
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Order A-1042 arrived damaged. Please refund 40 dollars.",
    tools=tools,
)

官方给的建议很实在:把最常用的工具前置加载,只延迟长尾。全都 defer 会让每次请求都多一次检索。

客户端检索与远程 MCP:两个附加能力

客户端检索。 如果你的工具注册表本来就在自己手里(按用户权限过滤、已有 embedding 索引),可以声明 "execution": "client" 并自己实现 search_tools。代价是每次检索多一次往返;收益是工具不必预先声明——用户中途接入某个集成时,新工具可以当场暴露出来。

远程 MCP 服务器。 对 mcp_server 工具打 defer_loading: true,这台服务器暴露的全部工具都按需加载。这条对「连一个大服务器」的场景最实用,不必把它的工具逐个列出来。

什么时候真的省钱:一个必须自己算的不等式

官方没给百分比,只给了一句可执行的判断:没被加载的 schema 总量 > 被加载的 schema 总量时才省钱。

把它写成算式,成本差大致是:

省下的 = Σ(始终没被加载的工具 schema) − tool_search 固定开销 − Σ(被加载工具的 schema)

由此得出三条工程结论:

  1. 工具越多、单次用得越少,收益越大。 五十个工具跑一个只用两三个的任务,是最佳场景。
  2. 工具少且几乎全用,别开。 固定开销会吃掉收益,甚至倒挂。
  3. 同一会话里反复用同一批工具,收益会衰减。 因为加载过的 schema 在这个对话里一直计费——它只推迟了成本,没有抹掉成本。真正被抹掉的是「整场对话都没被碰过的工具」。

这也解释了为什么官方只说「省 token」不说「省多少」:这个数字完全取决于你的工具库形状,换成别人的 benchmark 没有参考价值。

三个要留意的地方

第一,检索不是语义检索(至少官方没说)。 原文描述是「模型按名称请求工具」、服务端运行、无需自建索引;没有出现 semantic search 或向量检索的表述。别按「它会做语义匹配」来设计工具命名——工具名与描述写得好不好,直接决定检索能不能命中。官方也提示可以用 interaction.steps 反查模型考虑了哪些工具,来调名称与描述。

第二,没有工具数量上限的官方口径。 原文只说「几十甚至上百个」,示例注释里出现「50+」。没有公布硬上限,别把示例当规格。

第三,它是 Preview。 接口形状(tool_search / defer_loading / execution: client)都还可能变。要上生产,先把这段封装成一层薄适配,别让字段名渗到业务代码里。

AI 之家 观点

这条新闻的价值不在「又省了 token」,而在于它承认了 2026 年 Agent 工程的主要矛盾已经从「模型够不够强」变成了「上下文怎么分配」。

过去一年大家解决工具过多靠三种土办法:手工分组(把工具切成几个子 Agent)、在系统提示里写路由规则、或者干脆只接十几个工具。这三种都在拿「能力」换「上下文」。Tool Retrieval 换了个方向——把 schema 从「常驻」改成「按需」,本质上是给工具调用加了一层分页。

对做工具平台的团队,这里有一个容易被忽略的连带影响:工具描述第一次变成了有直接经济价值的资产。以前描述写得含糊,最多让模型选错工具;现在描述还是检索的唯一依据——写得含糊的工具,连被加载的机会都没有。所以下一步该做的不是调参,而是把每个工具的 description 当成产品文案来写:一句话说清「什么时候用我」,而不是「我是什么」。

至于要不要现在接:工具数量过了三十个、且单次任务只用少数几个的团队,值得用一周流量做 A/B;工具不到十个的,先别动——固定开销换不来收益,还会多一层调试面。

相关阅读

来源

本卡片由 AI 之家 编辑部根据 Google 官方博客整理,非厂商付费内容。官方未公布 token 节省比例与工具数量上限,文中相关判断均为基于其公开表述的推断,已注明。

常见问题

Tool Retrieval 到底改了哪一步?

改的是「工具怎么进上下文」。以前每个工具的完整参数 schema 都要放进请求;现在可以对工具打 defer_loading: true,模型只看到名称与描述,需要用时在同一次请求内向服务端请求 schema(tool_search_call),拿到后再发 function_call。加载路径在服务端,你不用建索引、也不用托管向量库。

哪些模型能用?

官方原文是 Gemini 3.6 及更高版本、包含所有 Gemini 4 模型,且只在 Interactions API 里可用。状态是 Preview,官方示例用的模型名是 gemini-4-hydrogen。

能省多少 token?

官方没给数字,只给了判断条件:『没被加载的 schema 总量大于被加载的』才省,工具库越大越容易成立。也就是说,工具只有十几个、每题都要用大半的时候,反而可能因为 tool_search 那一段固定开销而略微变贵。必须以自己的流量实测,官方原话是 measure it against your own traffic。

怎么计费?

没有单独收费。tool_search 本身会占一小段固定输入 token,被加载的 schema 从加载那一刻起按输入 token 计费、持续到该对话结束,和你一开始就把工具全放进去的计费方式一样。省的钱来自「永远没被加载的那部分」。

会破坏前缀缓存吗?

官方说不会,而且这是设计时特意照顾的点:延迟的 schema 不放在 prompt 开头,加载的 schema 追加在对话靠后的位置,所以前缀在轮次之间保持不变。对长会话来说这条比省 token 更重要。

相关对比