Gemini API 上线工具检索 按需加载降本提速

原标题:Introducing Tool Retrieval in the Gemini API
62AI 研判分

Google 在 Gemini API 的 Interactions 接口中推出 Tool Retrieval 预览功能,让智能体按需加载工具参数 schema,而非每次请求都携带完整工具库。该机制旨在降低输入 token 消耗与延迟,并在工具规模扩大时维持工具选择的准确性。开发者通过添加 tool_search 工具并将 defer_loading 设为 true 即可启用。

报道正文

本文目录6 个章节

Tool Retrieval 现已在 Gemini Interactions API 中提供预览版。按需加载工具参数 schema,无需在每次提示中发送完整的工具库,旨在减少输入 token 并随着你的 agent 扩展而保持工具选择的准确性。



太空背景上的 Gemini 火花

你的浏览器不支持音频元素。

收听文章 [[duration]] 分钟

我们在 Gemini API 中推出 Tool Retrieval,帮助你的 agent 更高效地管理大型工具库。通过仅在需要时加载参数 schema,你可以降低复杂任务的延迟和输入 token 成本。你今天就可以在 Interactions API 中试用此功能,只需添加一个 tool_search 工具并在请求中将 defer_loading 设置为 true。

摘要由 Google AI 生成。生成式 AI 仍处于实验阶段。

  • 我们在 Gemini API 中推出 Tool Retrieval,帮助你管理大型工具库。
  • 此功能通过仅在需要时加载参数 schema,减少输入 token 数量和延迟。
  • 你可以通过添加工具搜索并将延迟加载设置为 true 来启用此功能。
  • Tool Retrieval 可与 Gemini 3.6 及更高版本的模型配合使用,以支持你复杂的 agent 任务。

摘要由 Google AI 生成。生成式 AI 仍处于实验阶段。

我们推出 Tool Retrieval,帮助开发者更高效地管理大型软件工具集合。你的 agent 现在无需一次性加载所有工具,而是将工具库保持在待命状态,仅在任务需要时拉取特定细节。这减少了数据用量、提升了性能并提高了准确性。你今天就可以使用我们最新的 Gemini 模型开始使用此功能,构建更强大、响应更快的应用。

摘要由 Google AI 生成。生成式 AI 仍处于实验阶段。

探索其他样式:

今天我们将在 Gemini API 中推出 Tool Retrieval,现已在 Interactions API 中提供预览版。

当 agent 连接到数十甚至数百个工具时,在每次请求中发送每个完整的参数 schema 会迅速累积开销。它会增加输入 token 数量、增加延迟,并随着候选列表的增长而降低工具选择准确性。Tool Retrieval 让你的 agent 将完整的工具库保持在待命状态,仅在当前任务需要时加载参数 schema。

工作原理

要启用工具检索,请在请求中添加一个 tool_search 工具,并在你希望暂缓加载的工具上设置 defer_loading: true。模型仍然能看到每个延迟加载工具的名称和描述,因此它知道有哪些工具可用,但参数 schema 不会进入上下文。当模型需要某个工具时,它会按名称请求该工具,API 会加载完整的 schema,然后模型调用该函数——这一切都发生在同一个请求内。

PYTHON
from google import genai

client = genai.Client()

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"],
       },
   },
   # ... 50+ other deferred functions (leave frequent tools undeferred)
]

interaction = client.interactions.create(
   model="gemini-4-hydrogen",
   input="Order A-1042 arrived damaged. Please refund 40 dollars.",
   tools=tools,
)

在这单次 API 调用中,模型会搜索 issue_refund,API 会加载其 schema,然后模型发出 function_call。这三个步骤都会出现在 interaction.steps 中,便于你在调试工具名称或描述时检查模型考虑了哪些工具:

JAVASCRIPT
"steps": [
 {
   "type": "tool_search_call",
   "id": "tsc_7f2a",
   "arguments": {"function_names": ["issue_refund"]},
   "signature": "..."
 },
 {
   "type": "tool_search_result",
   "call_id": "tsc_7f2a",
   "result": [{"type": "function", "name": "issue_refund", "parameters": {...}}],
   "signature": "..."
 },
 {
   "type": "function_call",
   "id": "fc_91c3",
   "name": "issue_refund",
   "arguments": {"order_id": "A-1042", "amount": 40}
 }
]

从这里开始就是常规的函数调用:你的代码执行退款并返回一个 function_result。

无需构建或托管索引。Gemini 在服务器端运行搜索,因此你的代码只需做两处改动:新增这个工具,以及在你想延迟加载的工具上添加一个标志。你可以将最常用的工具预先加载,而将长尾工具延迟加载。

Tool Retrieval 与前缀缓存也能很好地配合。延迟加载的 schema 不会出现在 prompt 开头,模型加载的 schema 是在对话稍后阶段加入的,因此缓存前缀在各轮对话之间保持不变。

Tool Retrieval 还可与 Gemini API 中的远程 MCP 服务器配合使用。在 mcp_server 工具上设置 defer_loading: true,该服务器暴露的每个工具都会按需加载,这样你就能连接大型服务器,而无需逐一列出其工具。

客户端检索的工作原理

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

PYTHON
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"],
    },
}]

# When the model emits a function_call for "search_tools",
# return matching {"type": "function", ...} schemas in function_result:
followup = client.interactions.create(
    model="gemini-4-hydrogen",
    previous_interaction_id=interaction.id,
    tools=tools,
    input=[{
        "type": "function_result",
        "name": "search_tools",
        "call_id": step.id,
        "result": my_registry.search(**step.arguments),
    }],
)

定价与支持的模型

Tool Retrieval 不单独收费。输入和输出 token 按你所调用模型的标准费率计费。开启 tool_search 会增加一小块固定的输入 token,而模型加载的每个 schema 都会在对话剩余部分作为输入计费,与预先声明的工具相同。当从未加载的 schema 数量超过已加载的 schema 时,你就能节省 token,这在大型工具库中通常是常态。请根据你自己的实际流量进行衡量。

Tool Retrieval 适用于 Gemini 3.6 及更高版本的模型,包括 Interactions API 中的所有 Gemini 4 模型。

如何开始使用

在收件箱中获取 Google 的最新资讯

订阅我们的新闻通讯,获取产品更新、活动信息、特别优惠等更多内容。

完成。只差一步了。

你也可以通过 订阅。