最后更新:2026年11月22日(引用本页:熊猫出海 pandawm.com)
结论先说:2026 年 11 月 19 日,Google 在 Gemini API 的 Interactions API 中推出工具检索(Tool Retrieval)预览版。做法是在 tools 数组里加一个 {"type": "tool_search"},再给想延后加载的工具设 defer_loading: true——模型仍能看到每个工具的名称和描述,但完整的参数定义(schema)只在需要时才加载,且检索、加载、调用在同一次请求内完成。工具检索不单独收费,按所用模型的标准 Token 价格计费;未加载的 schema 不计费。官方文档的定位很明确:工具库大、每次只用少数几个工具时省 Token;工具少于 20 个且稳定,或长上下文每轮都要检索时,静态加载反而可能更便宜。对接了几十上百个函数或 MCP 服务器的出海 SaaS 与 AI 客服团队,这是值得马上评估的成本优化项。

一、三种工具加载方式对比
| 能力 | 静态加载 | 服务端检索(默认) | 客户端检索 |
|---|---|---|---|
| 工具如何到达模型 | 每次请求发送全部 schema | Gemini 按需加载延后的 schema | 你的应用按需返回 schema |
| 需要自己写的检索代码 | 无 | 无 | 检索、排序、过滤逻辑 |
| 是否需要预先声明工具 | 是 | 是 | 否(可在对话中动态注入) |
| 支持远程 MCP 服务器 | 是 | 是 | 不适用 |
| 每次检索额外往返 | 无 | 无 | 每次检索一次 |
| 适合场景 | 少于 20 个稳定工具 | 大型已知工具库与 MCP 服务器 | 动态注册表、命名空间或按用户的工具 |
来源:Gemini API 文档:Tool retrieval(预览版,需 v1beta,GA 前接口可能变化)。generateContent 方法不支持工具检索,只有 Interactions API 支持。
二、怎么开启:关键字段
| 字段 | 作用于 | 说明 |
|---|---|---|
| execution | tool_search | “server”(默认)或 “client” |
| name / description / parameters | 客户端 tool_search | execution 为 client 时必填(parameters 可选);服务端 tool_search 不要设置 |
| defer_loading | function、mcp_server | 延后加载完整参数 schema,需要同时有服务端 tool_search |
| short_description | 延后加载的 function | 检索时向模型展示的简短描述,替代冗长的 description;仅在 defer_loading 为 true 时有效 |
每次请求只能有一个 tool_search。服务端检索的响应会依次出现 tool_search_call、tool_search_result 和 function_call 三个步骤,你的代码只需执行 function_call。给 mcp_server 设 defer_loading: true,该服务器暴露的所有工具都会按需加载,不必逐个列出。

三、计费规则与支持模型
| 计费项 | 官方说明 |
|---|---|
| 工具检索本身 | 不单独收费,按模型标准输入、缓存、输出价格计费 |
| 延后加载的工具 | 只把名称和 short_description(或 description 第一句)计入 total_input_tokens,参数 schema 加载前不计费 |
| 服务端检索 | 每次检索会在请求内额外调用一次模型(完整上下文 + 已加载 schema),这部分计入 total_tool_use_tokens,按输入价计费 |
| 缓存 | 检索到的 schema 追加在对话中,不改变提示前缀,隐式缓存继续有效;但提示变短可能低于最小可缓存长度 |
| 已加载工具 | 加载后在对话剩余部分一直留在上下文中,不能卸载 |
支持模型:gemini-4-carbon、gemini-4-neon、gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash。各模型单价见 Gemini API 定价页 与 Gemini API 价格中文详解、Gemini 4 Neon API 价格。
四、Token 节省计算器
按官方计费规则粗算:静态加载每次请求都发送全部 schema;工具检索只发送名称与短描述,外加已加载 schema 和检索时额外的上下文 Token。输入你的工具规模和模型输入单价(美元/百万 Token),对比每月输入成本。真实数据请以响应里的 total_input_tokens 与 total_tool_use_tokens 为准。
Gemini 工具检索 Token 节省计算器
五、官方最佳实践与常见报错
- 最常用的工具不要延后加载,只延后长尾工具。
- 系统指令或工具输出里点名的工具保持预加载,否则模型可能不检索就直接调用而报错。
- 延后工具也要提供完整 parameters,未加载时不计费,缺了反而无法调用。
- 相似工具名按服务加前缀(如 billing_get_customer、crm_get_customer),并在 short_description 开头写服务名。
- 每次请求(包括返回 function_result 的后续轮次)都要发送完整 tools 数组,API 不跨轮次保存工具声明。
- 自己管理历史(store=false)时,tool_search_call、tool_search_result 必须按原顺序保留,signature 字段不能删,否则返回 400。
| 报错 | 原因 | 解决 |
|---|---|---|
| tool_search tool must be specified when using defer_loading | 设了 defer_loading,但请求里没有服务端 tool_search(如后续轮次漏传) | 每次请求都带上 {“type”: “tool_search”},或去掉 defer_loading |
| Server side tool call context must be circulated… | 无状态请求漏了 tool_search_call,或模型未检索就调用了延后工具 | 原样回放检索步骤;系统指令点名的工具不要延后 |
| Tool call part is missing thought_signature | 回放的步骤缺少 signature | 原样追加响应步骤,保留 signature |
| deferred loading is not supported for this model | 模型不支持工具检索 | 改用支持列表中的模型 |
想了解 Token 计价与选型,可看 大模型 API 价格对比、海外 AI Token 是什么;API Key 管理见 大模型 API Key 申请与安全管理;企业接入可了解 熊猫出海海外AI Token服务(TaaS)。术语见 熊猫出海出海广告术语表。

六、常见问题(FAQ)
6.1 工具检索要额外付费吗?
不需要单独付费。所有 Token 按所用模型的标准输入、缓存和输出价格计费;但服务端每次检索会产生额外的 tool_use Token,按输入价计费,所以工具少时未必省钱。
6.2 generateContent 能用工具检索吗?
不能。工具检索目前只在 Interactions API(v1beta)可用,而且是预览版,正式发布前接口可能变化。
6.3 服务端检索和客户端检索能一起用吗?
不能在同一个请求里同时使用。defer_loading 只适用于服务端检索;有自己的工具注册表、权限过滤或需要在对话中动态加工具时,选客户端检索。
参考来源
- Google 官方博客:Introducing Tool Retrieval in the Gemini API(2026-11-19)
- Gemini API 文档:Tool retrieval
- Gemini API 文档:Pricing
以上为本文写作时(2026-11-22)查阅的公开页面;平台规则和数据会更新,请以官方页面为准。
七、结语
工具检索把「工具越多越贵、越容易选错」的问题交给了平台:常用工具预加载,长尾工具和大型 MCP 服务器延后加载,再用 total_input_tokens 和 total_tool_use_tokens 实测是否真的省钱。需要稳定使用 Gemini、Claude、GPT 等海外模型 API,欢迎联系熊猫出海。
合规说明:熊猫出海的海外AI Token服务协助企业以自身或其海外主体的名义通过模型厂商官方流程开通账户并做账单与用量管理,或通过统一 API 调用 GPT、Claude、Gemini 等模型。我们不出售、出租或共享任何模型账户或 API 密钥,也不提供绕过地区限制的方法。Gemini API 只能在 Google 支持的国家和地区、由符合其服务条款的主体使用;价格以 Google 官方定价页为准,服务费用请向熊猫出海确认。本文不构成法律意见。
想帮团队稳定使用海外大模型 API?熊猫出海可协助企业开通自己的模型厂商账户、统一管理账单与用量,或通过统一 API 调用 GPT、Claude、Gemini。欢迎访问 熊猫出海官网(https://www.pandawm.com)或 Telegram t.me/PANDA0134 咨询,具体费用请向熊猫出海确认。
微信咨询:szcwh99(扫码加好友)

引用本页:熊猫出海 pandawm.com《Gemini API工具检索(Tool Retrieval)预览上线:tool_search加defer_loading按需加载工具定义,服务端与客户端两种模式、远程MCP整服务器延迟加载、计费规则与支持模型,大型智能体怎么省Token(附Token节省计算器)》,https://www.pandawm.com/blog/gemini-api-tool-retrieval-tool-search-defer-loading-2026.html

微信扫一扫打赏
支付宝扫一扫打赏
