Gemini API Tool Retrieval: tool_search, defer_loading और बिलिंग
Gemini Interactions API (v1beta) में प्रीव्यू के रूप में उपलब्ध Tool Retrieval को tool_search और defer_loading के साथ सक्षम करें। सर्वर-साइड और क्लाइंट-साइड मोड की तुलना करें, Google ब्लॉग के दावों के मुकाबले चार दस्तावेजी मॉडल जांचें, रिमोट MCP और स्टेटलेस रीप्ले संभालें, सामान्य त्रुटियां हल करें और टोकन बिलिंग व इम्प्लिसिट प्रीफिक्स कैशिंग का आकलन करें।
विषय-सूची

Gemini Interactions API (v1beta) में Tool Retrieval अब प्रीव्यू में उपलब्ध है, जिससे एजेंट tool_search और defer_loading के ज़रिए ज़रूरत पड़ने पर ही टूल पैरामीटर स्कीमा लोड कर सकते हैं। यह उन डेवलपर्स के लिए उपयोगी है जो दर्जनों कस्टम फ़ंक्शन या रिमोट MCP सर्वर को Gemini से जोड़ते हैं, और यह सुविधा केवल Interactions API पर उपलब्ध है (generateContent पर नहीं)। 2026-11-20 को सत्यापित स्थिति के अनुसार इसे आज़माने के लिए, चार दस्तावेजी मॉडलों (gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, या gemini-3.6-flash) में से किसी एक के साथ v1beta/interactions को कॉल करें, {"type": "tool_search"} जोड़ें, और अपने मुख्य सेट के बाहर के टूल पर defer_loading: true सेट करें।
पहले सही API मार्ग चुनें
Google ने 19 नवंबर 2026 को Google ब्लॉग पर Tool Retrieval की घोषणा की और AI Studio Tool retrieval दस्तावेज़ में सेटअप निर्देश प्रकाशित किए। चूंकि यह सुविधा Interactions API प्रीव्यू (v1beta) तक सीमित है, इसलिए आपका मौजूदा एंडपॉइंट तय करता है कि आप इसे तुरंत अपना सकते हैं या नहीं।
| मार्ग | खाता और क्षेत्र | बिलिंग इकाई | Tool Retrieval समर्थन | कब चुनें |
|---|---|---|---|---|
आधिकारिक Gemini Interactions API (v1beta) | किसी समर्थित क्षेत्र में Google AI Studio API कुंजी; gemini-4-argon के लिए Paid Tier आवश्यक | प्रति 1M इनपुट, कैश्ड और आउटपुट टोकन (gemini-4-hydrogen, gemini-3.8-flash, gemini-3.6-flash पर Standard Free Tier उपलब्ध) | प्रीव्यू में समर्थित (tool_search, defer_loading, रिमोट mcp_server) | आपके पास बड़ी टूल लाइब्रेरी है और आप सीधे v1beta/interactions कॉल कर सकते हैं |
आधिकारिक Gemini generateContent API | वही Google AI Studio खाता और समर्थित क्षेत्र | प्रति 1M इनपुट, कैश्ड और आउटपुट टोकन | समर्थित नहीं | आपके पास ~20 से कम स्थिर टूल हैं, समर्थित Gemini 3 या 2.5 मॉडल पर एक्सप्लिसिट कैशिंग चाहिए, या अभी माइग्रेट नहीं कर सकते |
| पे-एज़-यू-गो API गेटवे (जैसे BetterToken) | अपना पंजीकृत BetterToken खाता और कंसोल में बनाई गई API कुंजी | प्रत्येक मॉडल की वर्तमान बिलिंग इकाई के अनुसार पे-एज़-यू-गो बैलेंस से शुल्क | Interactions API दस्तावेजित नहीं है; Tool Retrieval समर्थन असत्यापित है | आप कई मॉडलों के लिए दस्तावेजित नेटिव Gemini generateContent या OpenAI-कम्पैटिबल Chat Completions एंडपॉइंट पर ही बने रहते हैं (BetterToken दस्तावेज़ में प्रति-मॉडल टूल समर्थन जांचें) |
यदि आप Interactions API पर जाने के बजाय मानक Gemini generateContent या OpenAI-कम्पैटिबल Chat Completions पर बने रहते हैं, तो आप दस्तावेजित एंडपॉइंट, मॉडल ID और प्रति-मॉडल टूल समर्थन के लिए BetterToken का Gemini API संदर्भ देखें।
समर्थित मॉडल और Gemini 4 का 400 त्रुटि व्यवहार
19 नवंबर 2026 के Google घोषणा ब्लॉग में कहा गया है कि Tool Retrieval, Gemini 3.6 और उसके बाद के मॉडलों के साथ काम करता है, जिनमें सभी Gemini 4 मॉडल शामिल हैं, और यह नवीनतम Gemini मॉडल पृष्ठ का लिंक देता है। उस पृष्ठ पर चार Gemini 4 मॉडल सूचीबद्ध हैं: gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, और gemini-4-argon।
हालांकि, 2026-11-20 को सत्यापित स्थिति के अनुसार आधिकारिक Tool retrieval समर्थित मॉडल सूची में केवल चार मॉडल ID शामिल हैं:
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
2026-11-20 को सत्यापित स्थिति के अनुसार Tool Retrieval दस्तावेज़ पृष्ठ पर gemini-4-carbon और gemini-4-neon सूचीबद्ध नहीं हैं। किसी असमर्थित मॉडल को defer_loading भेजने पर HTTP 400 त्रुटि के साथ deferred loading is not supported for this model संदेश मिलता है।
अपना एकीकरण gemini-4-hydrogen से शुरू करें, जिसे Google ने पूरे Tool Retrieval उदाहरणों में उपयोग किया है; यदि आप Flash मॉडलों से स्विच कर रहे हैं तो हमारी Gemini 4 Hydrogen मूल्य निर्धारण और माइग्रेशन गाइड देखें। यदि आपका वर्कफ़्लो gemini-4-carbon पर निर्भर है, तो defer_loading सक्षम करने से पहले v1beta पर वास्तविक व्यवहार की जांच करें, या स्टैटिक टूल लोडिंग बनाए रखते हुए Gemini 4 Carbon API मूल्य निर्धारण और माइग्रेशन पढ़ें।
सर्वर-साइड बनाम क्लाइंट-साइड रिट्रीवल
Interactions API दो परस्पर अनन्य रिट्रीवल मोड का समर्थन करता है: सर्वर-साइड रिट्रीवल (डिफ़ॉल्ट) और क्लाइंट-साइड रिट्रीवल (execution: "client")। दोनों ही शुरुआती प्रॉम्प्ट से स्कीमा को बाहर रखते हैं, लेकिन लेटेंसी, सेटअप और टूल पंजीकरण में अलग-अलग हैं।
| पहलू | स्टैटिक टूल लोडिंग | सर्वर-साइड रिट्रीवल | क्लाइंट-साइड रिट्रीवल |
|---|---|---|---|
| मॉडल तक स्कीमा कैसे पहुंचते हैं | सभी शुरू में भेजे जाते हैं | Gemini मांग पर स्थगित स्कीमा लोड करता है | आपका ऐप function_result में स्कीमा लौटाता है |
| लिखने योग्य रिट्रीवल कोड | कोई नहीं | कोई नहीं | कस्टम खोज, रैंकिंग और फ़िल्टरिंग |
| टूल शुरू में घोषित किए जाते हैं | हां | हां | नहीं |
| रिमोट MCP समर्थन | हां | हां (mcp_server पर defer_loading: true) | लागू नहीं |
| अतिरिक्त नेटवर्क राउंड ट्रिप | कोई नहीं | कोई नहीं (एक ही API कॉल में चलता है) | प्रति खोज एक राउंड ट्रिप |
| सबसे उपयुक्त उपयोग | ~20 से कम स्थिर टूल | बड़ी लेकिन निश्चित टूल लाइब्रेरी या कई MCP सर्वर | निजी रजिस्ट्री, प्रति-उपयोगकर्ता अनुमतियां, सत्र के बीच जुड़ने वाले डायनेमिक टूल |
आप प्रति अनुरोध केवल एक tool_search प्रविष्टि घोषित कर सकते हैं। एक ही अनुरोध में सर्वर-साइड और क्लाइंट-साइड tool_search प्रविष्टियां मिलाने पर Cannot specify both client-side and server-side tool_search tools. त्रुटि मिलती है।
सर्वर-साइड रिट्रीवल और रिमोट MCP सेटअप करें
सर्वर-साइड रिट्रीवल के लिए v1beta API संस्करण आवश्यक है। यद्यपि Google के ब्लॉग पोस्ट के स्निपेट में api_version छोड़ा गया है, आधिकारिक Tool retrieval गाइड बताती है कि प्रीव्यू Tool Retrieval को v1beta की आवश्यकता है: Python में genai.Client(http_options={"api_version": "v1beta"}) और JavaScript में new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }) से क्लाइंट शुरू करें।
Bash में, अपनी Gemini API कुंजी को टर्मिनल पर प्रिंट किए बिना लोड करें, फिर https://generativelanguage.googleapis.com/v1beta/interactions पर POST अनुरोध भेजें। नीचे दिया गया उदाहरण एक स्थगित स्थानीय फ़ंक्शन (convert_currency) को Google के दस्तावेजी डेमो मौसम MCP सर्वर (https://gemini-api-demos.uc.r.appspot.com/mcp) के साथ जोड़ता है:
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-hydrogen",
"input": "Check the temperature in London and convert 100 USD to EUR.",
"tools": [
{"type": "tool_search"},
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another using live mid-market rates.",
"short_description": "Convert an amount between currencies.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"from": {"type": "string"},
"to": {"type": "string"}
},
"required": ["amount", "from", "to"]
}
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": true
}
]
}'
tools ऐरे बनाते समय चार नियमों का पालन करें:
- सर्वर-साइड
tool_searchऑब्जेक्ट परname,description, औरparametersसेट न करें। - प्रत्येक स्थगित
functionपर पूराparametersस्कीमा भेजें। जब तक मॉडल किसी स्थगित टूल को पहली बार लोड नहीं करता, उसके पैरामीटर स्कीमा का शुल्क नहीं लगता, और बिना पैरामीटर भेजा गया टूल खोज के बाद खाली स्कीमा के साथ लौटता है जिसे मॉडल कॉल नहीं कर सकता। - संक्षिप्त स्थगित सूची में लंबे
descriptionको बदलने के लिए वैकल्पिकshort_descriptionका उपयोग केवलdefer_loading: trueके साथ ही करें। - रिमोट MCP सर्वर के लिए केवल Streamable HTTP एंडपॉइंट ही जोड़ें (SSE सर्वर समर्थित नहीं हैं) और
-के बिनाsnake_caseसर्वर नाम उपयोग करें, जैसा कि Remote MCP में दस्तावेजित है। यदि आपका रिमोट सर्वर हैंडशेक या स्कीमा सत्यापन में विफल होता है, तो हमारी MCP सर्वर एकीकरण समस्या निवारण गाइड देखें।
सर्वर-साइड प्रतिक्रिया की पुष्टि करें
सफल सर्वर-साइड रिट्रीवल प्रतिक्रिया उसी API कॉल में steps के भीतर tool_search_call और tool_search_result चरण लौटाती है, जिसके बाद वास्तविक टूल कॉल आता है। डेमो सर्वर पर get_weather जैसे रिमोट MCP टूल के लिए, API रिमोट कॉल भी चलाता है और उसी प्रतिक्रिया में mcp_server_tool_call व mcp_server_tool_result चरण लौटाता है।
अपने स्थानीय फ़ंक्शनों के लिए सीधे steps के भीतर function_call आइटम देखें। केवल status == "requires_action" पर निर्भर न रहें, क्योंकि Google बताता है कि function_call चरण मौजूद होने पर भी status हमेशा requires_action नहीं होता। फ़ंक्शन को स्थानीय रूप से चलाएं और अगले टर्न में function_result भेजें।
क्लाइंट-साइड रिट्रीवल सेटअप करें
जब आपकी टूल सूची उपयोगकर्ता अनुमतियों, आंतरिक नेमस्पेस, या सत्र शुरू होने के बाद जुड़ने वाले एकीकरणों पर निर्भर करती है, तो execution: "client" का उपयोग करें। क्लाइंट-साइड tool_search परिभाषा में name और description दोनों आवश्यक हैं (किसी को भी छोड़ने पर 400 त्रुटि आती है), और अनुरोध में किसी भी टूल पर defer_loading सेट नहीं किया जाना चाहिए।
नीचे दिया गया Python स्निपेट एक न्यूनतम प्रोटोकॉल उदाहरण है जो लाइव रजिस्ट्री क्वेरी करने के बजाय एक निश्चित घोषणा लौटाता है। जब स्क्रिप्ट followup.steps से {"user_id": 123} के साथ get_billing_history के लिए function_call चरण प्रिंट करे, तो पुष्टि हो जाती है कि राउंड ट्रिप काम कर रहा है:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{
"type": "tool_search",
"execution": "client",
"name": "search_tool_registry",
"description": "Search internal tool namespaces such as billing and support when needed.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"namespace": {"type": "string"},
},
"required": ["query"],
},
}
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Look up the billing history for user 123.",
tools=tools,
)
for step in interaction.steps:
if step.type == "function_call" and step.name == "search_tool_registry":
# Minimal protocol example: replace with your own registry or permission filter.
matches = [
{
"type": "function",
"name": "get_billing_history",
"description": "Retrieve billing history for a given user.",
"parameters": {
"type": "object",
"properties": {"user_id": {"type": "integer"}},
"required": ["user_id"],
},
}
]
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[
{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": matches,
}
],
)
for next_step in followup.steps:
if next_step.type == "function_call":
print(next_step.name, next_step.arguments)
पूर्ण फ़ंक्शन घोषणाओं को function_result.result ऐरे के भीतर JSON ऑब्जेक्ट के रूप में ही लौटाएं, उन्हें सीरियलाइज़ की गई JSON स्ट्रिंग के रूप में न भेजें, और खोज function_call से मेल खाता name तथा call_id शामिल करें। यदि आपकी क्लाइंट-साइड खोज में कोई मिलान नहीं मिलता है, तो एक संक्षिप्त टेक्स्ट परिणाम लौटाएं जिसमें लिखा हो कि कुछ नहीं मिला और मॉडल क्या खोज सकता है, ताकि वह अपनी क्वेरी सुधार सके।
मल्टी-टर्न स्टेट, स्टेटलेस रीप्ले और सामान्य त्रुटियां
पहले टर्न के बाद अधिकांश एकीकरण विफलताएं तीन प्रीव्यू सीमाओं के कारण होती हैं:
- हर अनुरोध में पूरा
toolsऐरे दोबारा भेजें। जब आपprevious_interaction_idदेते हैं तो Interactions API चरण इतिहास सहेजता है, लेकिन अनुरोधों के बीच टूल घोषणाएं सहेजकर नहीं रखता। अगले टर्न में टूल छोड़ने पर मॉडल अघोषित टूल चूक सकता है या सर्वर-साइड मोड में आंतरिकretriever:कॉल उत्पन्न कर सकता है। - लोड किए गए टूल अनलोड नहीं हो सकते, और सर्वर-साइड मिस पर टेक्स्ट मिलता है। एक बार मॉडल किसी टूल को लोड कर ले, तो उसका स्कीमा शेष संवाद तक संदर्भ में रहता है। यदि सर्वर-साइड क्वेरी किसी स्थगित टूल से मेल नहीं खाती, तो API संरचनात्मक रिट्रीवल त्रुटि के बजाय सामान्य टेक्स्ट प्रतिक्रिया देता है, इसलिए मिस पहचानने के लिए
tool_search_resultपर निर्भर न रहें। store=falseहोने पर चरण और सिग्नेचर हूबहू वापस भेजें। प्रत्येक स्टेटलेस अनुवर्ती अनुरोध मेंinputके भीतर पूरा चरण इतिहास भेजें, और अनुरोध के शीर्ष स्तर पर पूराtoolsऐरे दोबारा भेजें। प्रतिक्रिया के हर चरण (tool_search_call,tool_search_result,thought, औरfunction_call) को उसके मूल क्रम में और बिना बदलेsignatureके साथ जोड़ें, और उसके बाद नयाfunction_resultभेजें। केवलfunction_resultभेजने से रिट्रीवल संदर्भ खो जाता है और400त्रुटि आती है। ऐसे SDK संस्करण का उपयोग करें जोtool_search_callऔरtool_search_resultको पहचानता हो, क्योंकि पुराने SDK इन्हें अज्ञात चरण मानकर इनके फ़ील्ड हटा देते हैं। सिस्टम निर्देशों या टूल आउटपुट में नामित किसी भी टूल को स्थगित न रखें, अन्यथा मॉडल बिना खोजे उसे कॉल कर सकता है औरfunction_resultपर विफल हो सकता है।
Google असमर्थित मॉडलों, defer_loading के साथ सर्वर-साइड tool_search न होने, defer_loading: true के बिना short_description देने, क्लाइंट-साइड name या description छोड़ने, स्टेटलेस चरण न लौटाने और signature हटने पर HTTP 400 प्रतिक्रियाएं दस्तावेजित करता है। प्रत्येक दस्तावेजी त्रुटि संदेश को उसके कारण और समाधान से मिलाने के लिए नीचे दी गई तालिका देखें:
| दस्तावेजी त्रुटि संदेश | कारण | समाधान |
|---|---|---|
deferred loading is not supported for this model | समर्थित सूची से बाहर के मॉडल पर defer_loading भेजा गया | gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, या gemini-3.6-flash पर स्विच करें |
tool_search tool must be specified when using defer_loading. | किसी function या mcp_server टूल पर defer_loading: true सेट है, लेकिन अनुरोध में कोई tool_search टूल नहीं है | {"type": "tool_search"} जोड़ें या defer_loading हटाएं |
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request. | किसी फ़ंक्शन पर defer_loading: true सेट है लेकिन सर्वर-साइड tool_search नहीं है (जैसे केवल execution: "client" घोषित है या अगले अनुरोध में tool_search छूट गया) | क्लाइंट-साइड मोड में defer_loading हटाएं, या {"type": "tool_search"} सहित पूरा tools ऐरे दोबारा भेजें |
Cannot specify both client-side and server-side tool_search tools. | अनुरोध में सर्वर-साइड और क्लाइंट-साइड दोनों tool_search शामिल हैं | प्रति अनुरोध ठीक एक ही tool_search प्रविष्टि घोषित करें |
ToolSearch name must not be specified when execution mode is SERVER_SIDE. | सर्वर-साइड tool_search पर name सेट किया गया (description और parameters के लिए भी यही त्रुटि आती है) | वह फ़ील्ड हटाएं; यदि execution: "client" पर जा रहे हैं, तो name और description दोनों दें और सभी टूल से defer_loading हटाएं |
short_description can only be set if defer_loading is true | defer_loading: true के बिना फ़ंक्शन पर short_description सेट किया गया | defer_loading: true जोड़ें या short_description हटाएं |
Server side tool call context must be circulated when using deferred loading functions. | स्टेटलेस अनुरोध के इतिहास में स्थगित टूल का function_result है, लेकिन उसे लोड करने वाले tool_search_call और tool_search_result चरण नहीं हैं | हर tool_search_call और tool_search_result चरण को signature सहित बिना बदले वापस भेजें |
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (भले ही सभी चरण वापस भेजे गए हों) | मॉडल ने ऐसा स्थगित फ़ंक्शन कॉल किया जिसे किसी tool_search ने लोड नहीं किया, आमतौर पर इसलिए कि उसका नाम सिस्टम निर्देशों या किसी अन्य टूल के आउटपुट में था | नाम से उल्लेखित टूल को स्थगित न रखें |
Tool call part is missing thought_signature. / Tool response part is missing thought_signature. | स्टेटलेस अनुरोध में tool_search_call (कॉल भाग) या tool_search_result (प्रतिक्रिया भाग) चरण को उसके signature फ़ील्ड के बिना वापस भेजा गया | दोनों रिट्रीवल चरणों को उनके signature मानों के साथ बिना बदले वापस भेजें |
बिलिंग फ़ील्ड, प्रीफिक्स कैशिंग और लागत का संतुलन
Tool Retrieval के लिए कोई अलग सुविधा शुल्क नहीं है। हर टोकन का बिल Gemini API मूल्य निर्धारण पृष्ठ की मानक इनपुट, कैश्ड और आउटपुट दरों पर लगता है। 2026-11-20 को सत्यापित दरों के अनुसार, Paid Tier पर gemini-4-hydrogen का शुल्क प्रति 1M इनपुट टोकन $1.50, प्रति 1M कैश्ड इनपुट टोकन $0.075, और प्रति 1M आउटपुट टोकन (थिंकिंग टोकन सहित) $7.50 है। gemini-4-hydrogen, gemini-3.8-flash, और gemini-3.6-flash के लिए Standard Free Tier उपलब्ध है, जबकि gemini-4-argon केवल Paid Tier पर 30 नवंबर 2026 तक प्रति 1M टोकन $2.00 इनपुट, $0.10 कैश्ड और $10.00 आउटपुट पर उपलब्ध है, जो 1 दिसंबर 2026 से बढ़कर $4.00 / $0.20 / $20.00 हो जाएगा।
टोकन संख्या जांचने के लिए प्रत्येक इंटरैक्शन प्रतिक्रिया में पांच usage फ़ील्ड देखें:
total_input_tokens: अनुरोध में पहली मॉडल कॉल का प्रॉम्प्ट, जिसमें आपका इनपुट, संवाद इतिहास, सिस्टम निर्देश, अस्थगित टूल स्कीमा, छोटा निश्चितtool_searchनिर्देश ब्लॉक, और स्थगित टूल की एक-पंक्ति प्रविष्टियां (nameके साथshort_descriptionयाdescriptionका पहला वाक्य; Google के प्रारंभिक परीक्षण में प्रति स्थगित टूल लगभग 26 टोकन) शामिल हैं।total_tool_use_tokens: सर्वर-साइड टूल चलने के बाद उसी अनुरोध में API द्वारा की जाने वाली अतिरिक्त मॉडल कॉलों के प्रॉम्प्ट, जिनमें प्रत्येक सर्वर-साइड टूल खोज शामिल है। प्रत्येक कॉल पूरा संदर्भ और नए लोड हुए स्कीमा फिर से भेजती है और इस पर इनपुट दर से शुल्क लगता है; एक ही टर्न में कई खोजें अतिरिक्त पास जोड़ती हैं।total_cached_tokens: प्रॉम्प्ट का वह भाग जो इम्प्लिसिट कैश से पूरा हुआ, जिस पर इनपुट दर के बजाय कैश्ड दर से शुल्क लगता है।total_output_tokens: उत्पन्न प्रतिक्रिया टोकन, जिन पर आउटपुट दर लागू होती है।total_thought_tokens: उत्पन्न थिंकिंग टोकन, जिन पर आउटपुट दर लागू होती है।
प्रीफिक्स कैशिंग सीमा की सावधानी
Context caching के अनुसार, Interactions API केवल इम्प्लिसिट कैशिंग का समर्थन करता है; Interactions API या Gemini 4 मॉडलों पर एक्सप्लिसिट कैशिंग उपलब्ध नहीं है। चूंकि प्राप्त किए गए स्कीमा प्रॉम्प्ट की शुरुआत में नहीं बल्कि वहां जोड़े जाते हैं जहां मॉडल उन्हें लोड करता है, इसलिए आपके सिस्टम निर्देश, टूल सूची और पिछले टर्न हर अनुरोध में अपरिवर्तित प्रीफिक्स बने रहते हैं। जब यह प्रीफिक्स मॉडल के न्यूनतम कैश योग्य आकार को पार कर जाता है, तो संवाद के बाद के अनुरोध, जिनमें प्रत्येक सर्वर-साइड खोज की अतिरिक्त मॉडल कॉल शामिल है, इम्प्लिसिट कैश से पूरे हो सकते हैं और total_cached_tokens में दिखते हैं।
हालांकि, 2026-11-20 को सत्यापित स्थिति के अनुसार सभी चार समर्थित Tool Retrieval मॉडलों को इम्प्लिसिट कैशिंग के लिए न्यूनतम 4,096 इनपुट टोकन की आवश्यकता होती है। यदि आपका प्रॉम्प्ट केवल पूर्ण टूल स्कीमा के कारण 4,096 टोकन से ऊपर था, तो उन टूल को स्थगित करने पर अनुरोध न्यूनतम कैश योग्य आकार से नीचे जा सकता है। Gemini 4 मॉडलों पर मल्टी-टर्न और एजेंट लूप में, Gemini पिछले पूरे अनुरोध को तभी कैश करता है जब नया अनुरोध कम से कम 2,050 टोकन जोड़ता है (मॉडल आउटपुट, थिंकिंग और फ़ंक्शन परिणाम सभी इसमें गिने जाते हैं); इससे छोटे जुड़ाव पर Gemini पिछले अनुरोध के अंतिम 2,050 टोकन को मानक इनपुट दर पर फिर से प्रोसेस करता है।
Tool Retrieval कब टोकन बचाता है और कब महंगा पड़ता है
Google के दस्तावेज़ दो अनुरोधों का एक उदाहरणात्मक अनुमान देते हैं (पूर्णांक संख्याएं, आउटपुट टोकन और कैशिंग को छोड़कर), जहां मॉडल 400 टोकन वाले दो टूल लोड करके अनुरोध 1 की प्रतिक्रिया में function_call लौटाता है, और फिर आपका ऐप अनुरोध 2 में function_result भेजता है:
| उदाहरणात्मक परिदृश्य (Google दस्तावेज़ अनुमान) | स्टैटिक लोडिंग (इनपुट टोकन) | Tool Retrieval (इनपुट + टूल-यूज़ टोकन) | शुद्ध परिणाम |
|---|---|---|---|
| 200 टूल (प्रत्येक 400 टोकन), 2,000-टोकन संदर्भ | 2 × (2,000 + 80,000) = 164,000 | अनुरोध 1: 7,350 + खोज पास 8,150; अनुरोध 2: 8,150 = ~23,650 | इनपुट-साइड टोकन में ~86% की बचत |
| 10 टूल (प्रत्येक 400 टोकन), 30,000-टोकन संदर्भ | 2 × (30,000 + 4,000) = 68,000 | अनुरोध 1: 30,410 + खोज पास 31,210; अनुरोध 2: 31,210 = ~92,830 | इनपुट-साइड टोकन ~37% अधिक |
टूल स्थगित करना तब फ़ायदेमंद होता है जब आपकी लाइब्रेरी बड़ी हो और अधिकांश टर्न केवल कुछ ही टूल उपयोग करते हों। छोटे टूलसेट या ऐसे लंबे संवाद में जहां लगभग हर टर्न पर खोज होती है, अतिरिक्त सर्वर-साइड खोज पास (total_tool_use_tokens) बचत से अधिक महंगा पड़ सकता है। सबसे अधिक उपयोग होने वाले टूल शुरू से लोड रखें, कम उपयोग होने वाले टूल स्थगित करें, और व्यापक रोलआउट से पहले अपने वास्तविक ट्रैफ़िक पर वास्तविक बिल के साथ total_input_tokens, total_tool_use_tokens, और total_cached_tokens मापें।