TellWorldAI 世界档案
问档案English

首页›实践›实践

实践

Gemini API 工具检索:让模型按需加载工具定义

Gemini API 工具检索:让模型按需加载工具定义,比较服务端和客户端两种模式,并避开多轮对话和无状态会话里的常见 400 报错。

如果你的应用接了几十个函数工具,每次请求都要把它们全部塞进上下文,这篇适合你。读完你能分清服务端检索和客户端检索该用哪个,知道怎么把工具标成延迟加载,并能避开多轮对话和无状态会话里最容易碰到的 400 报错。

工具检索解决什么问题

工具检索(tool retrieval)让 Gemini 在对话过程中搜索并加载工具的 schema,而不是每次请求都收到全部工具定义[1]。工具少时这没有必要。工具多时就不一样了:几十个函数声明每次请求都会占掉好几万 token,而且候选工具越多,模型选对工具的准确率就越低[1]。工具检索让每次真正进入上下文的工具保持在很小的范围内[1]。

需要注意的是,它目前处于预览阶段,要求使用 v1beta API 版本,正式发布前接口可能还会调整[1]。它只在 Interactions API 上可用,generateContent 不支持[1]。

先判断用哪种方式

这里有三种选择。静态加载是把每个工具的 schema 每次都发出去,适合少于 20 个左右的稳定工具。服务端检索适合工具很多但固定的场景。客户端检索适合自己维护的工具注册表、按命名空间划分的工具,或者每个用户各自拥有不同工具集的情况[1]。

两种检索的区别在于谁来做搜索。服务端检索是默认方式,Gemini 在你声明的工具里搜索,并自己加载匹配的 schema;客户端检索则由你的应用负责搜索,再把匹配的 schema 返回给模型[1]。如果应用对延迟敏感,优先选服务端检索,因为它的搜索在一次 API 调用内完成;每次客户端搜索都要在模型和你的应用之间多走一个来回[1]。

服务端检索怎么用

打开它要做两件事:在 tools 数组里加上 {"type": "tool_search"},然后把你想暂时藏起来的 function 工具标上 defer_loading: true。如果是远程 MCP 服务,可以在 mcp_server 工具上设置它,这样该服务暴露的所有工具都会延迟加载[1]。

模型一开始只能看到每个延迟工具的名字和描述,看不到参数 schema。它需要某个工具时,会先发出 tool_search_call,API 解析出 schema 后返回 tool_search_result,接着模型才发出真正的 function_call。这些步骤都在同一次 API 调用里完成,你只需要执行最后的 function_call,然后把 function_result 按常规送回去[1]。

如果工具是远程 MCP 服务提供的,API 会直接在远端执行它,并在同一个响应里返回 mcp_server_tool_call 和 mcp_server_tool_result。你自己的函数仍然以 function_call 结尾,需要你来执行[1]。判断是否要执行,要看 steps 里有没有 function_call,不要只看 status。即使返回了 function_call,status 也不一定是 requires_action[1]。

如果一个延迟工具的描述写得很长,可以加上 short_description,让模型在检索时只看这段简短摘要。它只能和 defer_loading: true 一起用[1]:

{
  "type": "function",
  "name": "convert_currency",
  "description": "Convert an amount between currencies using live mid-market rates, with optional rounding and historical date lookup.",
  "short_description": "Convert an amount between currencies.",
  "defer_loading": true,
  "parameters": { ... }
}

客户端检索怎么用

客户端检索把搜索交还给你的应用。你要声明一个 execution 为 client 的 tool_search 工具,并给它一个名字、一段描述和自己的参数 schema。描述是必须的,因为模型靠它判断什么时候该去搜索[1]。

模型调用这个工具时,就像调用普通函数一样。你的应用执行自己的检索逻辑,然后把匹配到的完整函数声明放进 function_result.result 里返回,模型再调用这些新工具。这些工具不必出现在最初的 tools 数组里,所以用户中途接入新服务时,可以动态加入工具[1]。同一个请求里只能声明一个 tool_search 工具,服务端和客户端的不能同时存在[1]。

多轮对话:每次都要重发完整的 tools

即使使用 previous_interaction_id 串联多轮对话,API 也不会把上一轮的工具声明带过来。每次请求都要重新发送完整的 tools 数组,包括 tool_search、所有延迟工具(包括延迟的 mcp_server),以及所有不延迟的工具[1]。

如果后面的请求漏掉了某些工具,模型只知道前几轮已经调用过的那些工具,往往会继续用它们,还可能去调用这一轮已经没有声明的函数[1]。下面的例子展示了第二轮如何带回函数结果,同时重发第一轮的 tools:

# Turn 1 used tools=tools and returned a function_call step.
fc_step = next(s for s in interaction.steps if s.type == "function_call")

followup = client.interactions.create(
    model="gemini-4-hydrogen",
    previous_interaction_id=interaction.id,
    tools=tools,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": '{"amount": 92.4, "currency": "EUR"}'}],
        }
    ],
)
  print(followup.output_text)

无状态会话要原样回传检索步骤

如果你自己保存会话历史(设置 store=false,每次把完整历史放进 input),就必须把每个 tool_search_call 和 tool_search_result 步骤原样传回去,包括 signature 字段[1]。tool_search_result 里装着已经加载的 schema,缺了它,模型就会失去之前加载过的工具[1]。不要编辑、重排或重新格式化这些步骤,并且要保持它们在 function_call 之前的位置[1]。

如果历史里缺了这些步骤,API 会返回 400 错误,错误信息大意是:使用延迟加载的函数时,服务端的工具调用上下文必须回传[1]。这个错误通常出现在第二次调用时,而不是第一次。第一次检索成功,第二次发送 function_result 时才失败[1]。

常见报错

除了上面的上下文错误,还有几类 400 错误值得提前避开[1]:

  • defer_loading 没有和服务端 tool_search 一起用。
  • short_description 出现在没有设置 defer_loading: true 的函数上。
  • 客户端 tool_search 缺少 name 或 description。
  • 服务端 tool_search 设置了 name、description 或 parameters。
  • 同一个请求里同时声明了服务端和客户端的 tool_search。

费用

工具检索本身没有单独的收费,所有 token 都按所调用模型的标准输入、缓存和输出价格计费[1]。被延迟的工具在输入里只占一行,也就是名字和简短描述;参数 schema 在模型真正加载之前不计费。早期测试中,每个延迟工具大约占 26 个 token[1]。

需要留意的是,每次服务端搜索都会在同一个请求里多发一次模型调用,这次调用的完整上下文和新加载的 schema 都要计费,按输入价格算[1]。所以工具检索是否省钱,要看你自己的真实流量来测。

最佳实践

  • 常用的工具保持加载,只把长尾的专用工具延迟。
  • 系统指令或其他工具的输出里提到名字的工具,不要延迟,否则下一次请求会因上下文错误失败[1]。
  • 每个延迟工具都要带完整的 parameters。只有名字和简短描述的工具,搜索后返回的是空 schema,模型无法调用[1]。
  • 相似的服务要给函数加前缀,例如 billing_get_customer 和 crm_get_customer,并在 short_description 开头点明服务名[1]。
  • 在系统指令里告诉模型什么时候去搜索工具。

下一步

开始前先确认你使用的模型支持延迟加载,并在 Interactions API 上测试。预览功能变化较快,模型支持范围和价格以官方页面为准[1]。

来源

  1. 1
    Tool retrievalGemini API docs

引用本页: Gemini API 工具检索:让模型按需加载工具定义. TellWorld, https://www.tellworld.net/zh/practice/practice-gemini-tool-retrieval. 更新于 2026-11-20

相关动态