Gemini API 推出工具检索功能

💡 原文英文,约800词,阅读约需3分钟。
📝

内容提要

Gemini API 预览版推出工具检索功能:代理可保留完整工具库,仅在需要时加载参数架构,避免每次请求发送全部架构,从而减少输入 token、降低延迟并提升工具选择准确率。启用方式为添加 tool_search 工具并设置 defer_loading: true,支持远程 MCP 服务器及客户端检索,无额外收费,适用于 Gemini 3.6 及以后模型。

🔎

延伸解读

工具检索如何减少 token 与延迟

当代理连接数十甚至上百个工具时,每次请求都发送全部参数架构会快速增加输入 token 并拖慢响应。工具检索让模型仍能看到每个延迟加载工具的名称和描述,但参数架构不进入上下文,仅在模型按名称请求时才加载。这样既保留了工具库的完整性,又避免了无关架构的传输开销,尤其适合工具数量多但单次任务只用到少数工具的场景。

与前缀缓存的协同效应

工具检索与前缀缓存配合良好:延迟加载的架构不放在提示开头,模型后续加载的架构则追加在对话较后位置,因此缓存的提示前缀在各轮之间保持不变。这意味着启用工具检索不会破坏已有的缓存收益,反而可能因为前缀更稳定而提升缓存命中率。对于多轮对话的代理应用,这一点值得在评估时纳入考量。

客户端检索的取舍

如果开发者维护自己的工具注册表、嵌入索引或按用户权限过滤,可将 tool_search 设为客户端执行并自定义搜索参数。代价是每次搜索多一次往返,因为查找由应用完成。好处是工具无需预先声明,甚至能在对话中途用户连接新集成时动态暴露新工具。选择服务端还是客户端检索,取决于是否已有现成的注册表与权限体系。

计费方式与适用判断

工具检索本身不单独收费,输入输出按所调用模型的标准费率计费。启用 tool_search 会增加一小块固定输入 token,每个被加载的架构在后续对话中按输入计费,与预先声明工具相同。只有当未加载的架构多于已加载的架构时才能省 token,这对大型工具库通常是常态。文章建议用自己的流量实测,而非直接假设收益。

❓

Q&A

Gemini API 的工具检索功能是什么?它解决什么问题?

工具检索是 Gemini API 预览版推出的一项功能,允许代理保留完整工具库,但仅在需要时加载参数架构。它解决了当代理连接大量工具时,每次请求都发送所有完整参数架构导致输入 token 增加、延迟升高以及工具选择准确率下降的问题。

如何在 Gemini API 中启用工具检索?

在请求中添加一个 tool_search 工具,并在希望延迟加载的工具上设置 defer_loading: true。模型仍能看到每个延迟工具的名称和描述,但参数架构不会放入上下文。当模型需要某个工具时,会按名称请求,API 加载完整架构,模型再调用函数,所有这些都在同一个请求内完成。

工具检索如何与远程 MCP 服务器配合使用?

在 mcp_server 工具上设置 defer_loading: true,该服务器暴露的所有工具都会按需加载,这样你可以连接大型服务器而无需逐一列出其工具。

客户端检索模式如何工作?需要额外做什么?

如果你维护自己的工具注册表、嵌入索引或按用户权限过滤,可以声明 tool_search 并设置 "execution": "client",定义搜索参数。客户端检索每次搜索会增加一次往返,因为你的应用执行查找。工具无需预先声明,因此你还可以在对话中用户连接集成时暴露新工具。

工具检索是否额外收费?支持哪些模型?

工具检索没有单独收费。输入和输出 token 按所调用模型的标准费率计费。启用 tool_search 会增加一小块固定的输入 token,模型加载的每个架构在对话剩余部分按输入计费,与预先声明的工具相同。当未加载的架构多于已加载的架构时(大型工具库的常见情况),可以节省 token。该功能适用于 Gemini 3.6 及之后模型,包括所有 Gemini 4 模型,在 Interactions API 中可用。

工具检索如何影响前缀缓存?

工具检索与前缀缓存配合良好。延迟加载的架构不会出现在提示开头,模型加载的架构在对话后期添加,因此缓存的 prefix 在各轮之间保持不变。

🏷️

标签

➡️

继续阅读