Gemini工具参数改为按需加载,上百个工具接入只多一个标志
工具少的时候,把每个工具的完整参数定义都放进对话,问题不大。挂到几十上百个,做法开始拖累:每次请求重发全量 schema,输入 token 累积,延迟上升;候选列表越长,模型选错工具的概率越高。
Google 的解法是把工具清单拆成两层:名字和描述先给模型,参数 schema 按需加载。Tool Retrieval 现在在 Gemini Interactions API 中以预览版提供。
模型看到名字,看不到参数
模型仍然看得到每个被延迟工具的 name 和 description,所以知道有哪些工具可用;参数 schema 不进上下文。schema 定义工具接受哪些字段、哪个必填、类型是什么。
模型需要某个工具时按名字请求,API 把完整 schema 加载进来,模型再发出函数调用。
搜索、加载、调用都在同一个请求内完成,也写进 interaction.steps。开发者可以回看模型当时考虑了哪些工具。工具名或描述写得含糊时,这点尤其有用。
接入改动很小:请求里加一个 tool_search 工具,在想要延迟的工具上设 defer_loading: true。
没有索引要建,也没有索引要托管。搜索跑在 Gemini 服务端,代码层面只多一个新工具和一个标志。
最常用的工具可以保持前置加载,长尾的延迟。这个分层判断留给开发者自己;公告没有给出门槛建议。工具很少的小库是否还值得开,文中没有说法。
Tool Retrieval 和 prefix caching 能配合。延迟的 schema 不占 prompt 开头,模型加载的 schema 在对话靠后的位置加进来。缓存前缀在各轮之间保持不变。
远程 MCP 服务器也适用:在 mcp_server 工具上设 defer_loading: true,该服务器暴露的所有工具都按需加载。接一个大型服务器,不必把工具逐条列出来。
如果团队自己维护工具注册表、嵌入索引或按权限做过滤,可以把 tool_search 的 execution 声明为 client,并定义搜索参数。代价是每次搜索多一次往返,因为查找在应用侧跑。换来的是工具不必预先声明——对话中途接入一个集成时,新工具可以当场暴露。
账怎么算
Tool Retrieval 本身不单独收费。输入和输出 token 按所调模型的标准费率结算。
开启 tool_search 会增加一小块固定输入 token。模型加载的每个 schema 在后续对话中按输入计费,和前置声明的工具一样。
省不省,取决于没被加载的 schema 是否多于被加载的。大工具库里,这通常是常态。
可用范围是 Gemini 3.6 及之后的模型,包括所有 Gemini 4 模型,限 Interactions API。
公告由 Lucia Loher(Gemini API 产品经理)和 Nora Kassner(Google DeepMind 研究科学家)署名,文末给出文档、模型对比页和 Discord 讨论区三个入口。
公告没填的空白还有几处。预览版有没有配额或使用限制,没提。客户端检索每次搜索会多一次往返,这对实际体验影响多大,没有数据。prefix caching 和 Tool Retrieval 并用时,缓存命中率能提升多少,也没给数。
关键事实
- Tool Retrieval 现已在 Gemini Interactions API 中提供预览版。
- 当 agent 连接数十甚至数百个工具时,每次请求都发送完整参数 schema 会快速累积输入 token、增加延迟,并随着候选列表增长而降低工具选择准确率。
- 启用 Tool Retrieval 需要在请求中添加 tool_search 工具,并在想要延迟加载的工具上设置 defer_loading: true。
- 模型仍然能看到所有延迟工具的 name 和 description,因此知道有哪些工具可用,但参数 schema 不进入上下文。
- 当模型需要某个工具时,它按名称请求,API 加载完整 schema,模型调用函数,全部发生在同一个请求内。
- 无需构建或托管索引,Gemini 在服务端运行搜索,代码只需新增 tool 和 defer_loading 标志。
- 可以将最常用的工具保持前置加载,而将长尾工具延迟加载。
- Tool Retrieval 与 prefix caching 兼容:延迟的 schema 不进入 prompt 开头,模型加载的 schema 在对话后期加入,因此缓存前缀在各轮之间保持不变。