能省,但有條件。 按 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 文檔中心