能省,但有条件。 按 Google 官方文档给出的两组假设性算例,在 200 个工具、2,000 Token 基础上下文的场景中,Gemini Tool Retrieval 的输入 Token 从 164,000 降到 23,650,约减少 85.6%。在 10 个工具、30,000 Token 基础上下文的场景中,输入 Token 从 68,000 升到 92,830,约增加 36.5%。是否划算,取决于一个问题:省掉的完整工具 Schema,能否覆盖服务端搜索额外产生的上下文开销。
您读完此文能了解到什么?
- Tool Retrieval 省的是哪一部分 Token,又新增了哪一部分 Token。
- 官方 200 工具算例与 10 工具算例的完整前提和逐项拆解。
- 基于官方参数推导的盈亏临界公式,以及“工具数达到多少才值得启用”的判断方法。
- 如何用
interaction.usage字段和缓存规则核算一次 Agent 任务的真实成本。
索引:先用概念表和影响速览帮你统一术语、判断自己属于哪类读者。“客观事实”部分交代 Google 公布的机制、计费规则与两组算例原文口径。“分析判断”部分给出按官方参数推导的临界点、三种“省”的区别、单任务账单公式和启用决策表。

Gemini Tool Retrieval 成本分析 To Know:概念解释
| 概念 | 简要解释 |
|---|---|
| 输入 Token | 送入模型处理的文本、历史上下文和工具声明等内容的计量单位 |
| 工具 Schema | 模型生成函数调用时依据的完整参数定义,算例中每个约 400 Token |
| 延迟工具列表 | 设置 defer_loading: true 后,模型最初只看到的工具名称和简述,官方早期测试中每项约 26 Token |
| 基础上下文 B | 算例中每次模型调用原本就要处理的历史与任务信息 |
| 搜索后推理 | 服务端检索到工具后,带着现有上下文和新增 Schema 再执行的一次模型调用 |
total_tool_use_tokens |
同一请求内,由服务端工具和搜索引发的额外模型调用输入量 |
total_cached_tokens |
输入用量中由缓存处理、按缓存费率计费的部分 |
| 盈亏临界点 | 同一组假设下,静态加载与按需加载输入开销相等的边界 |
| 单个成功任务成本 | 完成一个业务目标所花费的各轮模型调用和工具费用之和 |
Gemini Tool Retrieval 影响速览
- 接入大型工具库的 Agent 开发者:工具多、单次任务只用少数几个时,有机会显著降低重复输入的 Schema 成本。这是官方 200 工具算例对应的场景。
- 工具集较小、上下文较长的应用开发者:每次服务端搜索都要额外跑一次模型推理并重新处理长上下文,启用后可能更贵。官方 10 工具算例就是反例。
- 负责成本核算的工程或 FinOps 人员:只看首次请求的
total_input_tokens会低估成本,必须把total_tool_use_tokens、缓存命中和输出 Token 一起计入。 - 维护企业工具注册表的平台团队:客户端检索模式可以结合自有权限过滤和动态工具,但每次搜索会多一次 API 往返,成本口径需要单独评估。
客观事实:Gemini Tool Retrieval 发布与计费机制
Gemini Tool Retrieval 是什么、何时发布
2026 年 11 月 19 日,Google 在官方博客宣布在 Gemini Interactions API 中开放 Tool Retrieval 预览功能。该功能处于 Preview 阶段,需要使用 v1beta API 版本,旧的 generateContent 方法不支持。服务端模式的启用方式是在 tools 中加入 {"type": "tool_search"},并对希望延迟加载的 function 或 mcp_server 设置 defer_loading: true。
开发文档截至 2026 年 11 月 20 日明确列出的兼容模型 ID 有四个:gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash。公告中“Gemini 3.6 及更新模型”的说法更宽泛,但未列入文档的型号需要自行验证,对不支持的模型设置 defer_loading 会返回 HTTP 400。
需要强调一个容易误读的点:服务端模式下,开发者每次请求仍要提交完整的 tools 数组,包括延迟工具的完整参数,即使使用 previous_interaction_id 也一样。Tool Retrieval 改变的是完整 Schema 进入模型上下文的时机,而不是请求体里不再发送这些定义。
静态加载与 Gemini Tool Retrieval 的成本从哪里来
静态加载时,每次模型调用都要读取全部工具的完整 Schema,即使本轮只用到一个退款函数。Tool Retrieval 用一份简短的工具列表替代这些完整定义,模型需要时发起 tool_search_call,服务端返回含完整 Schema 的 tool_search_result,模型再据此生成 function_call。
Google 明确表示 Tool Retrieval 没有独立的功能费,但以下内容仍按所选模型费率计费:
- 所有延迟工具的简短列表项。
- 开启
tool_search后增加的固定搜索指令。 - 每次服务端检索引发的额外模型推理,它会重新处理完整上下文和新加载的 Schema。
- 被加载工具的完整 Schema,以及它们在后续轮次中的持续占用(当前文档未提供卸载机制)。
- 正常的输出、Thinking 和工具执行结果相关 Token。

Gemini Tool Retrieval 官方算例:200 个工具与 10 个工具
两组算例均来自 Google Tool Retrieval 文档,属于官方标注的假设性计算,不是生产环境 Benchmark,并且都忽略了输出 Token 和缓存收益。统一口径是:每个完整 Schema 400 Token、每个延迟工具简述约 26 Token、搜索指令 150 Token、一次任务含 2 次外部请求、第一次请求中完成 1 次服务端搜索、共加载 2 个工具。
| 计算项 | 200 工具,B=2,000 | 10 工具,B=30,000 |
|---|---|---|
| 静态加载:2 ×(B + N × 400) | 164,000 | 68,000 |
| 请求 1 初始输入(B + N × 26 + 150) | 7,350 | 30,410 |
| 请求 1 搜索后推理(再加 2 个 Schema) | 8,150 | 31,210 |
| 请求 2 输入 | 8,150 | 31,210 |
| Tool Retrieval 合计 | 23,650 | 92,830 |
| 变化量 | -140,350 | +24,830 |
| 变化幅度(按官方数字二次计算) | 约 -85.6% | 约 +36.5% |
200 工具场景之所以节省明显,是因为静态方案每次都要背着 80,000 Token 的工具定义,而基础上下文只有 2,000,搜索多跑一次推理的代价很小。10 工具场景正好相反:工具定义总共才 4,000 Token,可省的空间有限,而搜索后推理要把 30,000 Token 的长上下文再处理一遍,新增开销直接压过了节省。
Gemini Tool Retrieval 的 Usage 字段、价格与缓存规则
Google 在 interaction.usage 中提供了分析 Tool Retrieval 成本所需的字段:
| 字段 | 含义 | 成本分析中的作用 |
|---|---|---|
total_input_tokens |
请求内首次模型调用的输入 | 只能反映“初始上下文变短了多少” |
total_tool_use_tokens |
服务端工具和搜索引发的额外模型调用输入 | 搜索成本的主要来源,最容易被忽略 |
total_cached_tokens |
已包含在输入中、由缓存处理的部分 | 按缓存费率计,不能再重复相加 |
total_output_tokens |
模型生成的输出 | 按输出费率计 |
total_thought_tokens |
推理过程产生的 Token | 按所选模型的输出费率计 |
价格方面,Google 定价页的 Standard 标准价格中,Gemini 4 Hydrogen 输入为每百万 Token $1.50、输出(含 Thinking)为 $7.50,缓存输入为 $0.075。若只用这一输入单价对官方算例做算术换算,200 工具场景约为 $0.246 对 $0.0355,10 工具场景约为 $0.102 对 $0.139。这只是把假设性 Token 数乘以官方费率,不是任何真实账单。
缓存规则有两条门槛需要分开理解。第一,Interactions API 只支持隐式缓存,截至 2026 年 11 月 20 日,Gemini 4 系列、Gemini 3.8 Flash 和 Gemini 3.6 Flash 的隐式缓存最低输入规模均为 4,096 Token。第二,在 Gemini 4 的多轮对话和 Agent Loop 中,新请求需新增至少 2,050 Token,系统才会缓存完整的上一请求;不足时,上一请求末尾的 2,050 Token 会按标准输入价重新计费,模型输出、Thinking 和函数结果都计入这个新增量。
截至资料核查日,Google 没有公布 Tool Retrieval 在真实任务集上的 Token 节省比例、延迟改善幅度或工具选择准确率提升,也未见可充分核验的独立开发者生产实测。
分析判断:Gemini Tool Retrieval 什么时候真的省 Token
Gemini Tool Retrieval 的盈亏临界点:工具数达到多少才值得启用
以下为按官方算例参数推导的扩展示例,不是 Google 发布的通用阈值。设 N 为工具总数、B 为基础上下文,沿用 S=400、D=26、H=150、K=2 和“两次请求、一次搜索”的口径:
- 静态加载:T_static = 2 ×(B + 400N)
- 按需加载:T_retrieval = 3 ×(B + 26N + 150)+ 2 × 2 × 400
这个公式可以完整复现官方两组结果。令 T_retrieval < T_static,整理得到 722N > B + 2050,即 N > (B + 2050) / 722。这里的 2050 来自 3 × 150 + 1600,只是代数结果,与缓存文档中 Gemini 4 多轮缓存的 2,050 Token 新增量条件毫无关系,切勿混用。
| 基础上下文 B | 工具数 N | 静态加载 | Tool Retrieval | 变化 | 幅度 | 数据属性 |
|---|---|---|---|---|---|---|
| 2,000 | 200 | 164,000 | 23,650 | -140,350 | -85.6% | 官方算例 |
| 30,000 | 10 | 68,000 | 92,830 | +24,830 | +36.5% | 官方算例 |
| 30,000 | 44 | 95,200 | 95,482 | +282 | +0.3% | 扩展推导 |
| 30,000 | 45 | 96,000 | 95,560 | -440 | -0.5% | 扩展推导 |
| 30,000 | 50 | 100,000 | 95,950 | -4,050 | -4.1% | 扩展推导 |
| 30,000 | 100 | 140,000 | 99,850 | -40,150 | -28.7% | 扩展推导 |
在 B=30,000 时,临界值为 N > 44.39,也就是从第 45 个工具开始按需加载才略占优势,而且在临界点附近节省几乎可以忽略。同一公式下,若 B=2,000,临界值约为 5.6,即 6 个工具就能翻转。由此可见,基础上下文越长,越需要更大的工具库来摊薄搜索时重新处理上下文的成本。

图注:前两行数据为 Google 官方算例,其余为同口径推导。真实任务中的搜索次数和加载数量会改变曲线,建议用自己的业务请求复测,可以通过 API易 apiyi.com 统一接口快速拉起多个模型的静态加载基线做对照。
现实任务很少严格符合这组假设,以下变量会移动临界点:
- 搜索次数:每多一次服务端搜索,就多一次接近“B + 工具列表 + 已加载 Schema”规模的模型输入,长上下文场景下相当于每次再付一遍 B。
- 实际加载数量 K:加载的工具越多,节省越少;已加载 Schema 无法卸载,长会话中会持续累积。
- 单个 Schema 大小 S:参数复杂、描述冗长的工具,按需加载收益更大;Schema 很短时收益会被列表项和搜索指令吃掉。
- 会话轮数:静态方案每轮都要重复全部 Schema,轮数越多、且不再触发新搜索时,按需加载的优势越明显。
输入 Token 减少、总计费下降、响应更快:Gemini Tool Retrieval 的三种“省”
这三件事经常被混为一谈,但它们并不等价。输入 Token 减少最直观,但如果只看 total_input_tokens,会漏掉记在 total_tool_use_tokens 里的搜索后推理,从而高估节省幅度。
总计费下降还取决于缓存和单价。按需加载让初始提示变短,如果原本是靠大量 Schema 才越过 4,096 Token 的隐式缓存门槛,启用后反而可能失去缓存。函数调用与结果回传的短循环若新增内容不足 2,050 Token,Gemini 4 也拿不到完整的上一请求缓存。也就是说,Token 少了,单价结构却可能变差。
响应更快目前没有任何官方或独立数据支撑。服务端搜索不增加客户端往返,但请求内部确实多跑了模型推理;客户端检索则每次搜索多一次 API 往返。延迟究竟变快还是变慢,只能靠自己的端到端测试回答。
如何计算一次 Gemini Tool Retrieval Agent 任务的真实账单
依据官方 Usage 语义,在标准计费、缓存 Token 已包含于输入、无其他按次收费工具的前提下,单个请求可估算为:
USD ≈ [ (I + U − C) × P_in + C × P_cache + (O + T) × P_out ] / 1,000,000
其中 I、U、C、O、T 依次对应上表五个字段。一个 Agent 任务往往跨多个请求,需要把每个请求的 Usage 汇总后再计算,最终用“总成本 ÷ 成功完成的任务数”得到单个成功任务成本。
在开启 Tool Retrieval 之前,先测出静态加载基线是最稳妥的做法。下面用 OpenAI 兼容接口跑一次静态 Function Calling,记录基线 Usage:
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # API易 统一接口,用于跑静态加载基线
)
resp = client.chat.completions.create(
model="gemini-3.8-flash", # 模型名以平台模型列表为准
messages=[{"role": "user", "content": "Refund 40 USD for order A-1042."}],
tools=[{"type": "function", "function": {"name": "issue_refund",
"parameters": {"type": "object", "properties": {
"order_id": {"type": "string"}, "amount": {"type": "number"}},
"required": ["order_id", "amount"]}}}]
)
print(resp.usage) # 记录静态全量加载时的输入与输出 Token
需要说明的是,Tool Retrieval 本身依赖 Google Interactions API 的 v1beta 版本。上面的示例只用于获取静态加载对照数据,按需加载一侧请使用支持 Interactions API 的调用方式,再把两边的 Usage 放进同一个成本公式比较。
查看完整实现代码:盈亏临界推算 + Usage 账单估算
import openai
# ---------- 1. 按官方算例口径做理论推算(扩展示例,非官方阈值) ----------
def static_tokens(B: int, N: int, S: int = 400) -> int:
return 2 * (B + N * S)
def retrieval_tokens(B: int, N: int, D: int = 26, H: int = 150,
K: int = 2, S: int = 400) -> int:
return 3 * (B + N * D + H) + 2 * K * S
def breakeven_tools(B: int) -> float:
return (B + 2050) / 722 # 仅在 S=400、D=26、H=150、K=2 时成立
for B, N in [(2000, 200), (30000, 10), (30000, 45), (30000, 100)]:
s, r = static_tokens(B, N), retrieval_tokens(B, N)
print(f"B={B:>6} N={N:>3} static={s:>7} retrieval={r:>7} "
f"change={(r - s) / s:+.1%}")
print("B=30000 临界工具数:", round(breakeven_tools(30000), 2))
# ---------- 2. 按 Usage 字段估算单请求费用(美元) ----------
def request_cost(I, U, C, O, T, p_in, p_cache, p_out) -> float:
"""I/U/C/O/T 对应 total_input / tool_use / cached / output / thought tokens"""
return ((I + U - C) * p_in + C * p_cache + (O + T) * p_out) / 1_000_000
# 示例:Gemini 4 Hydrogen 标准价 1.50 / 0.075 / 7.50(每百万 Token)
print(request_cost(I=7350, U=8150, C=0, O=200, T=0,
p_in=1.50, p_cache=0.075, p_out=7.50))
# ---------- 3. 静态加载基线(OpenAI 兼容接口) ----------
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1"
)
def run_static_baseline(prompt: str, tools: list, model: str = "gemini-3.8-flash"):
resp = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}],
tools=tools
)
return resp.usage # 汇总多轮任务时,逐请求累加
🚀 快速开始:建议先在 API易 apiyi.com 用一个 Key 跑通静态加载基线,把真实业务任务集的 Token 与完成率记录下来,再决定是否把 Agent 迁移到按需加载,避免凭官方示意数字直接改架构。
Gemini Tool Retrieval 启用决策:你的工具库是否具备条件
综合官方工程建议与上面的推导,可以按下表做初步判断,最终仍以真实任务的单个成功任务成本和完成率为准:
| 工作负载特征 | 建议策略 | 理由 |
|---|---|---|
| 少于约 20 个稳定工具,多数每轮都用 | 继续静态加载 | 官方建议;可省 Schema 少,搜索开销占比高 |
| 工具少但基础上下文很长 | 静态加载,或仅延迟少数大 Schema 工具 | 每次搜索都会重新处理长上下文,10 工具算例即反例 |
| 几十到上百个工具,单次只用少数几个 | 优先评估服务端检索 | 大型长尾工具库是官方 200 工具算例对应场景 |
| 高频工具 + 大量低频专业工具混合 | 高频直接加载,低频 defer_loading |
官方推荐的混合用法,避免简单任务也先搜索 |
| 多租户、动态工具、需按用户权限过滤 | 评估客户端检索 | 可接入自建注册表,但每次搜索多一次往返 |
| 系统指令经常点名的工具 | 保持直接加载 | 官方提醒点名的延迟工具可能被绕过搜索直接调用而出错 |
💡 选择建议:同一批任务分别跑静态与按需两套方案,保持模型、工具库、上下文长度和缓存条件一致。通过 API易 apiyi.com 可以在统一接口下切换不同 Gemini 及其他主流模型做基线对照,便于把成本差异归因到工具加载策略本身。
还有几个工程细节会直接影响账单:store=false 自行管理历史时必须原样保留 tool_search_call、tool_search_result 及其 signature,否则后续请求可能报 HTTP 400;不能为了缩小请求体而省略延迟工具的 parameters;调试时要检查 interaction.steps 中的 function_call,不能只看 interaction.status。这些问题一旦触发重试,重复请求的 Token 同样会计入成本。
说到底,Tool Retrieval 是一个以“少数工具被频繁使用、多数工具长期闲置”为前提的成本工具。官方两组方向相反的算例已经把边界讲清楚:工具库越大、上下文越短、搜索越少,越可能省;反之则可能多花。真正该优化的不是首次请求的 Token 数,而是每个成功任务的总账。
正如清人陈澹然在《寤言·迁都建藩议》中所写:“不谋全局者,不足谋一域。”
参考资料
- Google 官方公告:Introducing Tool Retrieval in the Gemini API(2026-11-19)
- 链接:
blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval
- 链接:
- Google Tool Retrieval 技术文档:配置、计费、官方算例与限制
- 链接:
aistudio.google.com/docs/tool-retrieval
- 链接:
- Google Context caching 文档:隐式缓存门槛与 Gemini 4 多轮缓存规则
- 链接:
aistudio.google.com/docs/caching
- 链接:
- Google Gemini Developer API 定价:模型输入、输出与缓存费率
- 链接:
aistudio.google.com/docs/pricing
- 链接:
作者: APIYI 技术团队
技术交流: 如需对比 Gemini 等多模型在 Agent 场景下的 Token 成本,欢迎访问 API易 apiyi.com 获取测试额度,更多接入说明见 docs.apiyi.com 文档中心