如果你的应用接了几十个函数工具,每次请求都要把它们全部塞进上下文,这篇适合你。读完你能分清服务端检索和客户端检索该用哪个,知道怎么把工具标成延迟加载,并能避开多轮对话和无状态会话里最容易碰到的 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]。
来源
- 1Tool retrievalGemini API docs
引用本页: Gemini API 工具检索:让模型按需加载工具定义. TellWorld, https://www.tellworld.net/zh/practice/practice-gemini-tool-retrieval. 更新于 2026-11-20