Newshot

Gemini API 推出工具检索功能

AI summary

通过工具检索,你的智能体可以访问数百种工具,同时消耗更少的 token。该功能现已在 Gemini API 中开放预览。

Translation(model translation, not the source's own text)
太空背景上的 Gemini 火花
太空背景上的 Gemini 火花

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

当一个 agent 连接到几十甚至上百个工具时,每次请求都发送完整的参数 schema 会迅速累积开销。这会推高输入 token 数量、增加延迟,而且随着候选列表变长,工具选择准确率也会下降。Tool Retrieval 让你的 agent 把完整工具库保持在待命状态,只在当前任务需要时才加载参数 schema。

工作原理

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


        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 中,便于在调试工具名称或描述时检查模型考虑了哪些工具:


        "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 也能与 prefix caching 良好配合。延迟加载的 schema 不会出现在提示词开头,而模型加载的 schema 会在对话中较晚的位置加入,因此缓存的 prefix 在不同轮次之间保持不变。

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

客户端检索的工作原理

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

文章标题:在 Gemini API 中引入工具检索

正文:


        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),
    }],
)
      

定价与支持的模型如何运作

工具检索不单独收费。输入和输出 token 按你所调用模型的标准费率计费。开启 tool_search 会增加一小段固定的输入 token,模型加载的每个 schema 在对话余下部分都会作为输入计费,与预先声明的工具相同。当你从未加载的 schema 多于已加载的 schema 时,就能节省 token,这在大型工具库中通常是常见情况。请针对你自己的流量进行衡量。

工具检索在 Interactions API 中适用于 Gemini 3.6 及之后的模型,包括所有 Gemini 4 模型。

如何开始

  • 阅读文档 — 包含示例的完整设置指南
  • 比较 Gemini 模型 — 为你的用例找到最合适的模型
  • 加入 Discord 上的讨论 — 与团队分享反馈

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

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

完成。只差一步。

请查看你的收件箱以确认订阅。

你也可以通过 订阅。

你的信息将按照 Google 的隐私政策使用。你可以随时退订。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Google AI 官方
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗