1778 字
9 分鐘

Gemini API Tool Retrieval 怎麼用?工具一多就吃 token,defer_loading 什麼時候真的省

驗證於

本文目錄

agent 接了三、四個 MCP server,再加上自己寫的幾十個 function,每次請求都要把全部工具的參數 schema 送給模型。實際上一個任務通常只用到兩三個工具,其他幾萬個 token 每次都白付,工具一多,模型挑錯工具的機率也跟著變高。

Google 在 2026 年 11 月 19 日替 Gemini API 推出 Tool Retrieval,目前是預覽版,只能在 Interactions API 用。做法是先只讓模型看到工具的名稱和簡短描述,需要哪個再載入它的完整 schema,整個過程在同一次 API 呼叫裡完成,不另外收費。Google 官方公告

開法:加一個 tool_search,在長尾工具設 defer_loading#

在 tools 陣列加上 {"type": "tool_search"},再替想延後載入的工具設 defer_loading: true。mcp_server 也可以設,那個 server 提供的所有工具都會改成需要時才載入。以下片段來自官方 Tool retrieval 文件,加上中文註解,沒有實際送出請求:

from google import genai
# Tool Retrieval 是預覽功能,要指定 v1beta
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{"type": "tool_search"}, # 每個請求只能有一個
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another.",
"defer_loading": True, # 先只送名稱和描述
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"to": {"type": "string"},
},
"required": ["amount", "to"],
},
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": True, # 整個 MCP server 的工具都延後載入
},
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Check the temperature in London and convert 100 USD to EUR.",
tools=tools,
)

有三個設定細節:

  • generateContent 不支援,要用 client.interactions.create。
  • 延後載入的工具還是要附完整 parameters。 沒載入的 schema 不計費;只給名稱的話,模型搜到後拿回空的 schema,沒辦法呼叫。
  • 描述很長的工具可以加 short_description,延後載入時模型只看這一行摘要。這個欄位只能搭配 defer_loading: true,單獨設會回 400。

最常用的幾個工具建議維持一般載入,只把長尾工具延後,官方也是這樣建議。

回應裡會多兩個 step#

模型需要工具時,會先發出 tool_search_call,API 回傳 tool_search_result(裡面是載入的 schema),接著才是一般的 function_call。這兩個 step 會出現在 interaction.steps 裡,不用自己處理,但很適合拿來除錯:看模型搜了哪些名稱,就知道工具命名或描述是不是不夠清楚。

MCP server 的工具會由 API 直接執行,回應裡會看到 mcp_server_tool_call 和 mcp_server_tool_result;自己的 function 則和平常一樣,執行後回傳 function_result。官方特別提醒,function_call 要從 steps 裡找,回應的 status 不一定是 requires_action。

什麼時候省、什麼時候反而更貴#

Tool Retrieval 不另外收費,但多了三種輸入 token:

  1. 延後工具清單:每個工具一行名稱加摘要,官方早期測試約每個工具 26 個 token。
  2. 固定的搜尋說明:開了 tool_search 的每個請求都會加上一小段。
  3. 每次搜尋多跑一輪模型:搜到工具後,API 會帶著完整上下文和新載入的 schema 再呼叫一次模型,這段記在 usage.total_tool_use_tokens,以輸入價計費。等於每搜一次,就差不多再付一次整段 prompt 的錢(快取命中的部分除外)。

官方文件用整數做了兩個示意情境(不含輸出和快取),下表另外用 Gemini 4 Hydrogen Standard 付費層每百萬輸入 token $1.50 換算金額,價格引自 Gemini API 定價表:

情境全部工具直接載入用 Tool Retrieval
200 個工具、每個 400 token,對話 2,000 token164,000 token(約 $0.246)約 23,650 token(約 $0.035)
10 個工具、每個 400 token,對話 30,000 token68,000 token(約 $0.102)約 92,830 token(約 $0.139)

第二種情況反而貴了三成多:工具少,省下的 schema 不多,上下文又長,每次搜尋都要把 3 萬 token 重送一遍。官方的選擇表也寫得很直接,工具少於約 20 個、而且固定不變,就照舊全部載入;工具庫大、每次只用少數幾個,才是 Tool Retrieval 划算的情況。

還有一個跟快取有關的細節:延後載入後 prompt 變短,如果原本是靠一大堆 schema 才超過模型的最低快取長度,改完可能就吃不到隱式快取了。上線前用自己的流量比較 total_input_tokens、total_tool_use_tokens 和 total_cached_tokens 三個欄位,會比套用官方範例估得準。

常見的 400 錯誤#

錯誤訊息(節錄)原因處理
tool_search tool must be specified when using defer_loading.有工具設了 defer_loading,但請求裡沒有 tool_search加上 {"type": "tool_search"}
When defer_loading is set on a FunctionDeclaration...後續請求漏送 tool_search,或只宣告了 client-side 的 tool_search每個請求都送完整 tools 陣列
deferred loading is not supported for this model模型不支援換成支援清單上的模型
Server side tool call context must be circulated...自己管理對話紀錄(store=False)時,沒把 tool_search_call、tool_search_result 送回去兩個 step 原封不動送回,signature 也要保留
Tool call part is missing thought_signature.送回的 step 被拿掉 signature照收到的原樣送回

Server side tool call context must be circulated 有兩個容易困惑的地方:它出現在送回 function_result 的第二個請求,第一個請求是成功的;而且就算 step 都有送回,只要 system instructions 或其他工具的輸出裡直接提到某個延後工具的名稱,模型可能跳過搜尋直接呼叫,對話就接不下去。官方建議,會被點名的工具不要延後載入。

另外,用 previous_interaction_id 串接多輪對話時,API 會幫忙保存搜尋 step,但不會保存工具宣告。每一輪都要重送同一份 tools,漏送的話,模型只記得之前用過的工具。

支援哪些模型#

官方公告寫的是 Gemini 3.6 以後的模型,包含所有 Gemini 4 模型。不過 11 月 20 日查到的文件支援清單只列了四個:gemini-4-hydrogen、gemini-4-argon、gemini-3.8-flash、gemini-3.6-flash,不支援的模型設 defer_loading 會回 400。用 Gemini 4 Neon 或 Carbon 的流程,先送一個小請求確認,再決定要不要開。Hydrogen 的換模比較方式可以參考 Gemini 4 Hydrogen 從 Flash 換過來的驗收方法。

自己有工具索引的話,用 client-side retrieval#

如果工具清單要依使用者權限過濾,或已經有自己的 embedding 索引,可以把 tool_search 設成 "execution": "client",並給它 name、description 和參數 schema。模型會像呼叫一般 function 一樣呼叫它,由程式自己搜,再把符合的工具宣告放進 function_result 回傳。

這個模式的工具不用事先宣告,使用者中途連上新的整合時也能加進來;代價是每次搜尋多一趟來回,對延遲敏感的服務還是用 server-side。兩種模式不能在同一個請求裡混用。

工具很多的 agent,延後載入之前也值得先盤點一次哪些工具真的需要,接 MCP 前先做能力盤點整理了判斷方式。盤點後還是有幾十個以上的工具,再挑一條實際流量開 Tool Retrieval,對照開啟前後的 usage 欄位,確定有省再擴大。

參考資料:

Introducing Tool Retrieval in the Gemini API

Tool retrieval - Gemini API 文件

Gemini API 定價

Gemini API Tool Retrieval 怎麼用?工具一多就吃 token,defer_loading 什麼時候真的省
https://laplusda.com/posts/gemini-api-tool-retrieval-defer-loading/
作者
Zero
發佈於
2026-11-20
許可協議
CC BY-NC-SA 4.0