يتطلب دمج Gemini Tool Retrieval إنجاز ثلاثة أمور. أولاً، أضف {"type": "tool_search"} إلى مصفوفة tools، واضبط defer_loading: True على الدوال منخفضة الاستخدام في تطبيقك. ثانياً، أرسل الطلب إلى Interactions API بإصدار v1beta، ثم استخرج function_call من interaction.steps. ثالثاً، نفّذ الدالة محلياً، وأنشئ function_result اعتماداً على call_id، ثم أعد إرساله مع مصفوفة tools كاملة. لا حاجة في كل ذلك إلى كتابة أداة بحث عن الأدوات بنفسك؛ إذ يتولى الخادم استرجاع الأدوات وتحميل مخطط المعاملات (Schema).
من الضروري التوضيح منذ البداية: لا يغيّر Tool Retrieval سوى «توقيت دخول تعريفات معاملات الأدوات إلى سياق النموذج»، بينما يبقى تنفيذ الدوال مسؤولية المطور. كما أنه لا يضمن تخفيض التكلفة بالضرورة؛ ففي الحالات التي تكون فيها الأدوات قليلة والسياق طويلاً قد يرتفع استهلاك الـ Tokens على العكس.
ماذا ستتعلم بعد قراءة هذا المقال؟
- ما النماذج التي يدعمها Gemini Tool Retrieval، وأي إصدار من SDK يلزم، ولماذا يجب تحديد
v1betaصراحةً - مثال Python كامل بأسماء متغيرات متسقة: أداتان مؤجلتان للمخزون والطلبات، من الاسترجاع حتى الإجابة النهائية
- من يتولى معالجة كل من
tool_search_callوtool_search_resultوfunction_callوfunction_resultعلى حدة - الفرق بين مسارات التوسع الثلاثة: التحميل المؤجل عبر MCP عن بُعد، والاسترجاع من جانب العميل، وبناء Tool Registry خاص
- طرق التشخيص المركّز للأخطاء الشائعة مثل HTTP 400، وكيف تحدد ما إذا كان الأمر مجدياً اقتصادياً قبل التفعيل
دليل المحتوى: يبدأ المقال بجدول To Know يشرح الحقول الجوهرية، ثم توضح «لمحة سريعة عن التأثير» ما تعنيه هذه الميزة التجريبية لكل فئة من المستخدمين. ويعرض قسم «الحقائق الموضوعية» خطوات الدمج بالترتيب: تجهيز البيئة، تعريف الأدوات، مراقبة خطوة الاسترجاع، إعادة إرسال نتيجة الدالة، ثم التوسع إلى MCP والاسترجاع من جهة العميل، مع تجميع استكشاف الأخطاء في نهاية هذا القسم. أما قسم «التحليل والحكم» فيناقش، مستنداً إلى مثالين حسابيين افتراضيين قدمتهما Google، الحالات التي تناسب Tool Retrieval والحالات التي لا تناسبها.

مفاهيم أساسية حول استرداد الأدوات في Gemini (To Know)
| المفهوم | شرح موجز |
|---|---|
| google-genai | اسم حزمة SDK الرسمية من Google للغة Python، ويتم استيرادها عبر from google import genai |
| v1beta | إصدار واجهة المعاينة، ويجب استخدامه مع استرداد الأدوات، وقد حُدِّد صراحةً عند تهيئة العميل في هذا المقال |
| Interactions API | واجهة من Google موجهة لسير عمل الوكيل، وتدعم المحادثات ذات الحالة وخطوات التنفيذ القابلة للملاحظة |
tool_search |
نوع أداة خاص يعلن تفعيل استرداد الأدوات، بحد أقصى أداة واحدة لكل طلب |
defer_loading |
يؤخر إدخال التعريف الكامل لمعاملات دالة محددة أو خادم MCP إلى سياق النموذج |
short_description |
وصف موجز للدالة المؤجلة يراه النموذج في البداية، ولا يمكن استخدامه إلا مع الدوال المؤجلة |
tool_search_call |
خطوة بحث يبدأها النموذج ضمن عملية الاسترداد على الخادم |
tool_search_result |
خطوة يعيد فيها الخادم المخطط الكامل للأداة المطابقة |
function_call |
طلب من النموذج لكود المطور بتنفيذ دالة معينة مع تمرير المعاملات |
function_result |
نوع الإدخال الذي يستخدمه التطبيق لإعادة نتيجة تنفيذ الدالة إلى النموذج |
call_id |
معرف يربط نتيجة تنفيذ الدالة بـ function_call.id الأصلي |
previous_interaction_id |
معرف يتيح للطلبات اللاحقة متابعة سجل التفاعل المحفوظ على الخادم |
signature |
حقل توقيع يجب إرجاعه كما هو مع الخطوة الأصلية عند إعادة تشغيل الخطوات التاريخية في جلسة عديمة الحالة |
نظرة سريعة على تأثيرات Gemini Tool Retrieval
| الفئة | التأثير الفعلي |
|---|---|
| مطورو الوكلاء (Agent) | يمكن للوكلاء الذين يملكون أدوات كثيرة تحميل الأدوات ذات الاستخدام النادر بشكل مؤجل، دون الحاجة إلى بناء استرجاع متجهات خاص بهم، لكن عليهم التحول إلى Interactions API |
| الفرق التي تستخدم generateContent بالفعل | الطريقة القديمة لا تدعم Tool Retrieval، لذا تحتاج إلى ترحيل الواجهة وتحليل بنية الاستجابة |
| جهات دمج MCP | يمكن ضبط defer_loading على مستوى mcp_server بالكامل، دون الحاجة إلى إعلان كل أداة على حدة |
| مسئولو التكاليف | لا توجد رسوم منفصلة للميزة، لكن كل عملية بحث على جانب الخادم تولّد استدعاءات نموذج إضافية خاضعة للفوترة، ما يستدعي مراقبة total_tool_use_tokens |
| المشاريع ذات المكتبات الصغيرة للأدوات | قد لا تكون السيناريوهات التي تضم عشرة أدوات أو أكثر مع سياق طويل مجزية، وقد يكون التحميل الثابت أكثر اقتصادًا |
حقائق موضوعية عن Gemini Tool Retrieval: معلومات الإصدار وإجراءات التكامل
حالة إصدار Gemini Tool Retrieval والنماذج المدعومة
في 19 نوفمبر 2026 (بتوقيت بكين، في الساعات الأولى من صباح 20 نوفمبر)، نشرت Google مقالًا على مدونتها الرسمية بعنوان «Introducing Tool Retrieval in the Gemini API»، وأعلنت فيه عن طرح Tool Retrieval للاختبار في Interactions API. كاتبا المقال هما Lucia Loher، مديرة منتج Gemini API، وNora Kassner، عالمة أبحاث في Google DeepMind. الميزة حاليًا في حالة Preview، وقد تخضع الواجهة للتعديل قبل الإصدار الرسمي.
كانت صياغة الإعلان عامة إلى حد ما: «Gemini 3.6 والنماذج الأحدث، بما في ذلك جميع نماذج Gemini 4». غير أن وثائق المطوّرين، حتى 20 نوفمبر 2026، كانت تذكر بوضوح أربعة معرّفات نماذج فقط: gemini-4-hydrogen وgemini-4-argon وgemini-3.8-flash وgemini-3.6-flash. عند التكامل، يجب الاعتماد على قائمة الوثائق. وإذا عيّنت defer_loading لنموذج غير مدعوم، فسيعيد الطلب HTTP 400 مباشرة.
التحضير لتكامل Gemini Tool Retrieval: SDK وv1beta
أصدرت مكتبة Google Python SDK الرسمية googleapis/python-genai الإصدار v3.6.0 في 18 نوفمبر 2026، وأضافت مخططات عامة مرتبطة بـ Tool Retrieval وبنتائج الدوال. أمر التثبيت كما يلي:
pip install -U "google-genai>=3.6.0"
export GEMINI_API_KEY="your-key" # لا تضع المفتاح الحقيقي في الشيفرة
هناك عقبة شائعة تتعلق برقم الإصدار. منذ v3.0.0، يستخدم عميل Gemini Developer API الإصدار v1 افتراضيًا، فيما يتطلب Tool Retrieval الإصدار v1beta، لذا يجب تحديده صراحةً عند التهيئة:
from google import genai
client = genai.Client(
http_options={"api_version": "v1beta"}
)
يقرأ SDK بيانات الاعتماد من متغير البيئة GEMINI_API_KEY. وإذا كنت تستخدم REST، فنقطة النهاية المقابلة هي POST https://generativelanguage.googleapis.com/v1beta/interactions، ورأس المصادقة هو x-goog-api-key.
الخطوة الأولى: تعريف أدوات Gemini باستخدام tool_search وdefer_loading
لا يحتوي سيناريو العرض التوضيحي إلا على أداتين خاصتين بالأعمال: get_inventory للاستعلام عن مخزون المنتجات، وget_order_status للاستعلام عن حالة الطلب، وقد تم ضبطهما على التحميل المؤجل. ودور كل حقل في مصفوفة tools كما يلي:
{"type": "tool_search"}: يفعّل البحث من جانب الخادم، وتكون قيمةexecutionالافتراضيةserver. وإذا ضبطتdefer_loadingدونtool_search، فسيظهر الخطأdefer_loading requires tool_search.defer_loading: True: لا تدخلparametersالكاملة في السياق الأولي، ولا يرى النموذج في البداية سوى الاسم والوصف القصير.short_description: الوصف القصير في القائمة الأولية. وإذا لم يُملأ، تُؤخذ الجملة الأولى منdescription. ويُعد ملؤه في دالة غير مؤجلة أمرًا غير صالح.parameters: يجب مع ذلك إرسالها كاملة. ما يُؤجَّل هو توقيت دخول المخطط (Schema) إلى سياق النموذج؛ فلا يزال الخادم بحاجة إلى الحصول على التعريف الكامل.
ما الأدوات المناسبة للتأجيل؟ توصي Google باستخدام مزيج منهما: تُبقي الأدوات كثيرة الاستخدام قيد التحميل المباشر، وتُحمّل الأدوات المتخصصة منخفضة الاستخدام وطويلة الذيل تحميلًا مؤجلًا. كذلك، لا تضبط الأدوات التي تُذكر بالاسم صراحةً في تعليمات النظام على أنها مؤجلة؛ وإلا فقد يتخطى النموذج البحث ويستدعيها مباشرة، ما يؤدي إلى خطأ بسبب غياب سياق التحميل. ويُفضّل إضافة مساحة أسماء أعمال إلى الأدوات المتشابهة في الاسم، مثل التمييز بين billing_get_customer وcrm_get_customer، بدلًا من تسمية الجميع get_customer.
الخطوة الثانية: إرسال الطلب ومراقبة خطوات استرجاع أدوات Gemini
فيما يلي رمز العرض التوضيحي الكامل. المخزون «12 قطعة» وحالة الطلب demo_pending كلاهما بيانات محاكاة محلية، ولن يتم الاستعلام عن أي نظام حقيقي. لتشغيل الرمز تحتاج إلى مفتاح Gemini API صالح وإلى صلاحية الوصول إلى النموذج.
import json
from google import genai
MODEL = "gemini-4-hydrogen"
client = genai.Client(
http_options={"api_version": "v1beta"}
)
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "get_inventory",
"description": "Retrieve the available inventory for a product SKU.",
"short_description": "Check product inventory by SKU.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"sku": {"type": "string"}},
"required": ["sku"]
}
},
{
"type": "function",
"name": "get_order_status",
"description": "Retrieve the status of a customer order.",
"short_description": "Check an order's current status.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]
}
}
]
def execute_demo_tool(name, arguments):
"""دالة أعمال محاكاة محلية، لا تستعلم عن مخزون أو طلبات حقيقية."""
if name == "get_inventory":
return {"sku": arguments["sku"], "available": 12, "data_source": "local_demo"}
if name == "get_order_status":
return {"order_id": arguments["order_id"], "status": "demo_pending", "data_source": "local_demo"}
raise ValueError(f"Unknown tool: {name}")
# الطلب الأول: يكتشف النموذج الأدوات اللازمة ويختارها
interaction = client.interactions.create(
model=MODEL,
input="查询商品 SKU-42 的可用库存。",
tools=tools
)
print("执行步骤:")
for step in interaction.steps:
print(step.type, getattr(step, "name", ""))
عادةً ما تظهر interaction.steps المطبوعة بالترتيب التالي. يحدد النموذج الترتيب الدقيق ونتائج الاسترجاع، وقد يحدث أكثر من بحث في الجولة الواحدة.
tool_search_call: يكتشف النموذج أنه لا يملك أدوات محملة مناسبة، فيبدأ بحثًا من جانب الخادم.tool_search_result: يعيد API مخطط المعاملات الكامل الخاص بـget_inventoryالمطابق.function_call: بعد قراءة Schema، ينشئ النموذج استدعاءً مثلget_inventory(sku="SKU-42").
الخطوات الثلاث تحدث ضمن طلب API خارجي واحد، ولا يحتاج التطبيق إلى كتابة باحث إضافي أو إرسال طلب استرجاع آخر. يكفي في الخطوتين الأولين المراقبة والتسجيل، ولا تكرر البحث محليًا. لكن «الطلب الواحد» لا يعني «تنفيذ استنتاج واحد فقط»: فكل بحث من جانب الخادم يفعّل استدعاء نموذج إضافيًا، ويُحتسب هذا الجزء من الرموز كالمعتاد. وهناك نقطة أخرى يجب الانتباه إليها عند التصحيح: لا تنظر إلى interaction.status وحده. فحتى إذا لم تكن الحالة requires_action، قد تحتوي steps على function_call بانتظار التنفيذ.

الخطوة الثالثة: تنفيذ الدالة وإرجاع function_result
تتولى Tool Retrieval فقط العثور على الأدوات وتجهيز المعاملات، بينما تظل دوال الأعمال الفعلية من مسؤولية التطبيق، وهذا الجزء يستخدم آلية Function Calling القياسية. أكمل على الكود أعلاه كما يلي:
# تنفيذ استدعاءات دوال الأعمال الفعلية فقط، وعدم تنفيذ tool_search_call على جانب التطبيق
function_results = []
for step in interaction.steps:
if step.type != "function_call":
continue
result = execute_demo_tool(step.name, step.arguments)
function_results.append({
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}]
})
# إعادة نتائج الدوال المحلية إلى Gemini
if function_results:
followup = client.interactions.create(
model=MODEL,
previous_interaction_id=interaction.id,
tools=tools,
input=function_results
)
print("最终回答:", followup.output_text)
else:
print("当前回答:", interaction.output_text)
هناك ثلاث نقاط يجب الانتباه إليها في هذا الكود. أولاً، يجب أن تؤخذ قيمة call_id من step.id الخاص بـ function_call الأصلي. وعندما توجد عدة استدعاءات في الجولة الواحدة، يعتمد النموذج عليها لمطابقة كل نتيجة مع استدعائها. ثانيًا، يجعل previous_interaction_id=interaction.id الخادم يواصل سجل التفاعل المحفوظ، بما في ذلك الأدوات التي سبق استرجاعها. ثالثًا، يجب تمرير مصفوفة tools كاملة في الجولة الثانية أيضًا. تحتفظ API بسجل الخطوات، لكنها لا تحتفظ بتعريفات الأدوات؛ لذا يجب إعادة إرسال tool_search وجميع الأدوات المؤجلة وغير المؤجلة وإعدادات MCP في كل جولة.
يعرض هذا المثال حلقة استدعاء دالة واحدة فقط، ولا يتضمن منسّقًا عامًا للتعامل مع Agent على مدى جولات متعددة. إذا كان في followup استدعاء function_call آخر، فتابع المعالجة بالطريقة نفسها.
🎯 نصيحة تقنية: تعتمد Tool Retrieval نفسها على Interactions API الرسمية من Google بإصدار
v1beta. إذا كنت تريد أولاً تشغيل دوال الأعمال باستخدام Function Calling القياسي، ومقارنة أداء النماذج المختلفة في اختيار الأدوات وملء المعاملات، فيمكنك استخدام نفس مفتاح API في APIYI apiyi.com للتبديل بين نماذج مثل Gemini وClaude وGPT لإجراء اختبارات أساسية.
توسعة: MCP البعيد واسترجاع العملاء في Gemini
يمكن لخادم MCP البعيد أن يضبط التحميل المؤجل على مستوى الخادم، بحيث تُحمَّل الأدوات التي يكشفها عند الطلب:
mcp_tools = [
{"type": "tool_search"},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": True
}
]
بخلاف الدوال المخصصة، تتولى API تنفيذ أدوات MCP البعيدة، وما يظهر في steps هو mcp_server_tool_call وmcp_server_tool_result، ولا يحتاج التطبيق إلى إعادة إرسال النتائج. ولا تذكر الوثائق الرسمية حاليًا “الحد الأقصى لعدد الأدوات القابلة للتأجيل”.
إذا كانت المؤسسة تمتلك بالفعل سجل أدوات خاصًا بها، أو استرجاعًا متجهيًا، أو تصفية صلاحيات على مستوى المستخدم، فيمكنها الانتقال إلى الاسترجاع من جانب العميل: ضبط "execution": "client"، وتقديم name وdescription وparameters كاملة. في هذه الحالة تكون نتيجة الجولة الأولى عبارة عن function_call عادي إلى search_tool_registry. وبعد أن يقوم التطبيق بالاسترجاع، يُرجع في function_result.result مصفوفة كاملة من كائنات تعريف الأدوات، دون تسلسلها إلى سلسلة JSON واحدة. ولا يستخدم نمط العميل defer_loading، ولا يجوز الخلط بين النمطين في الطلب نفسه.

| البُعد | الاسترجاع من جانب الخادم | الاسترجاع من جانب العميل (Gemini) | سجل أدوات خاص (حل عام) |
|---|---|---|---|
| الجهة المنفذة للاسترجاع | Gemini API | تطبيق المطوّر | تطبيق المطوّر |
| الإعداد الأساسي | tool_search + defer_loading |
tool_search + execution: client |
استدعاء دوال عادي |
| هل يجب تعريف كل الأدوات مسبقًا | نعم | لا | لا |
| رحلات شبكة إضافية | لا يوجد | جولة +1 لكل عملية بحث | جولة +1 لكل عملية بحث |
| إضافة أدوات ديناميكيًا | غير مريحة | مدعومة | مدعومة |
| السيناريو النموذجي | مكتبة أدوات كبيرة وشبه ثابتة | متعدد المستأجرين، سجل خاص | إعادة الاستخدام بين النماذج والتبديل بين المورّدين |
| المنصات المتاحة | Google الرسمية v1beta | Google الرسمية v1beta | واجهات متوافقة مع OpenAI مثل APIYI apiyi.com |
العمود الأخير ليس Gemini Tool Retrieval، بل تنفيذ هندسي قريب من الفكرة: نكشف في البداية دالة بحث واحدة فقط، ثم بعد نجاح الاسترجاع نضيف الـ Schema المقابلة إلى tools. وهو مناسب للفرق التي تحتاج إلى التبديل بين عدة نماذج. وأبسط صياغة له هي:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1" # واجهة APIYI المتوافقة مع OpenAI
)
MODEL = "your-model-name" # راجع قائمة النماذج على المنصة
search_tool = {"type": "function", "function": {
"name": "search_tool_registry",
"description": "Search internal business tools by keyword.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
عرض الاستدعاء الكامل على مرحلتين لسجل أدوات (Tool Registry) من إنشائك الخاص
import json, os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1"
)
MODEL = "your-model-name" # وفقًا لقائمة النماذج المعروضة على المنصة
TOOL_REGISTRY = {
"get_inventory": {"type": "function", "function": {
"name": "get_inventory",
"description": "Retrieve the available inventory for a product SKU.",
"parameters": {"type": "object", "properties": {"sku": {"type": "string"}}, "required": ["sku"]}}},
"get_order_status": {"type": "function", "function": {
"name": "get_order_status",
"description": "Retrieve the status of a customer order.",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]}}},
}
search_tool = {"type": "function", "function": {
"name": "search_tool_registry",
"description": "Search internal business tools (inventory, orders) by keyword.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
def search_registry(query):
q = query.lower()
return [name for name, t in TOOL_REGISTRY.items()
if any(w in t["function"]["description"].lower() for w in q.split())]
def execute_demo_tool(name, args):
if name == "get_inventory":
return {"sku": args["sku"], "available": 12, "data_source": "local_demo"}
if name == "get_order_status":
return {"order_id": args["order_id"], "status": "demo_pending", "data_source": "local_demo"}
raise ValueError(name)
messages = [{"role": "user", "content": "查询商品 SKU-42 的可用库存。"}]
tools = [search_tool]
for _ in range(4): # حد أقصى بسيط لعدد الدورات، لمنع الحلقة اللانهائية
resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
msg = resp.choices[0].message
if not msg.tool_calls:
print("最终回答:", msg.content)
break
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
if call.function.name == "search_tool_registry":
names = search_registry(args["query"])
tools += [TOOL_REGISTRY[n] for n in names if TOOL_REGISTRY[n] not in tools]
content = json.dumps({"loaded_tools": names})
else:
content = json.dumps(execute_demo_tool(call.function.name, args), ensure_ascii=False)
messages.append({"role": "tool", "tool_call_id": call.id, "content": content})
💡 اقتراح للاختيار: جودة الاسترجاع في مسار سجل الأدوات تعتمد على دالة البحث التي تكتبها أنت، ومطابقة الكلمات المفتاحية في المثال مجرد عرض توضيحي. جرّب تبديل النماذج على APIYI apiyi.com وتشغيل المجموعة نفسها من المهام، ثم قارن بين «هل تم العثور على الأداة الصحيحة» و«هل تم ملء المعاملات بشكل صحيح»، لتعرف أي نموذج يناسب مكتبة أدواتك على نحو أفضل.
استكشاف الأخطاء الشائعة في استرداد الأدوات من Gemini
| العَرَض | السبب | المعالجة |
|---|---|---|
defer_loading requires tool_search |
تم الإعلان عن دالة مؤجلة، لكن دون وجود tool_search على الخادم |
أضف {"type": "tool_search"} إلى tools |
short_description غير صالح |
كُتب على دالة غير مؤجلة | استخدمه فقط مع الدوال التي لديها defer_loading=True |
| HTTP 400 unsupported model | النموذج غير موجود في قائمة النماذج المدعومة | استخدم أحد معرّفات النماذج الأربعة المذكورة في الوثائق |
| الطلب لا يعمل أو يعيد خطأ في الإصدار | يستخدم SDK الإصدار v1 افتراضيًا، أو تم استدعاء generateContent |
عيّن api_version="v1beta" صراحةً، واستخدم Interactions API بدلًا منه |
| HTTP 400 في الجولة الثانية | عند store=False تُغفل خطوة الاسترداد أو signature |
أعد إرسال tool_search_call/result وجميع التوقيعات كما هي |
| النموذج يستخدم أدوات قديمة أو الأدوات غير متاحة | الطلبات اللاحقة لا تمرر tools |
أعد إرسال مصفوفة tools كاملة في كل جولة |
| المعاملات فارغة بعد الاسترداد | الأداة المؤجلة أرسلت الاسم والوصف المختصر فقط | يجب إرسال parameters كاملة حتى للأدوات المؤجلة |
| فشل إعداد الاسترداد في جانب العميل | حقول مثل name وdescription مفقودة |
أكمل تعريف دالة البحث في جانب العميل |
يتطلب الوضع عديم الحالة (store=False) شرحًا منفصلًا. في هذه الحالة لا يمكن الاعتماد على previous_interaction_id؛ يجب على التطبيق حفظ مدخلات المستخدم وtool_search_call وtool_search_result وfunction_call وfunction_result وجميع signature بنفسه، ثم إعادة إرسالها كما هي. وإذا حُذف أو عُدّل أي من هذه الخطوات، فقد لا يتمكن الخادم من إعادة بناء سياق الاسترداد. بالإضافة إلى ذلك، عندما لا يجد الخادم أداة مطابقة، قد يعيد نصًا مباشرة بدلًا من خطأ مُهيكل. لذا فإن «عدم إرجاع الطلب لخطأ» لا يعني «نجاح الاسترداد»؛ وعند التحقق ينبغي فحص steps بندًا بندًا للتأكد من ظهور خطوة الاسترداد واستدعاء الدالة المتوقعين.
تحليل وتقييم Gemini Tool Retrieval: متى يستحق التفعيل
الحكم الأول: العائد يتوقف على حجم مكتبة الأدوات وطول السياق، وليس مجرد تفعيل الميزة يعني توفيرًا. قدّم توثيق Google مجموعتين من الأمثلة الحسابية الافتراضية ذات اتجاهين متعاكسين، وأوضح صراحةً أنها ليست اختبارات أداء إنتاجية. المجموعة الأولى: 200 أداة، كل أداة 400 Tokens، سياق أساسي 2,000 Tokens، والطلبات مرتين؛ التحميل الثابت يبلغ نحو 164,000 Tokens، بينما يبلغ Tool Retrieval نحو 23,650 Tokens، أي انخفاض يُقدَّر بنحو 85.6% وفق هذا الحساب. المجموعة الثانية: 10 أدوات، سياق أساسي 30,000 Tokens، التحميل الثابت 68,000 Tokens، لكن Tool Retrieval يبلغ 92,830 Tokens، أي زيادة نحو 36.5%، والسبب أن استدلال البحث الإضافي يعيد معالجة كامل السياق الطويل. توصية Google الهندسية هي: عندما تكون الأدوات المستقرة أقل من نحو 20 أداة، يكفي التحميل الثابت عادةً.

الحكم الثاني: عند تقييم التكلفة يجب النظر إلى total_tool_use_tokens، لا إلى إدخال الجولة الأولى فقط. في الاختبارات الرسمية المبكرة، كان الوصف المختصر لكل أداة مؤجلة يستهلك في المتوسط نحو 26 Tokens، أي ما يقارب 2,600 Tokens لـ 100 أداة، وهذه قيمة تقريبية. وما يستحق المتابعة حقًا هو الاستدعاءات الإضافية للنموذج التي يثيرها البحث، وتراكم الـ Schema المحمّلة خلال الجلسة. التوثيق الحالي لا يوفر آلية لإلغاء تحميل الأدوات التي جرى استرجاعها، وكلما زاد عدد الأدوات المسترجعة في جلسة طويلة تضخّم السياق. كما أن التخزين المؤقت ليس مفيدًا بشكل غير مشروط: فبعد تقصير موجه البداية، قد ينخفض عن الحد الأدنى للتخزين المؤقت الضمني.
الحكم الثالث: أصبح التحميل عند الطلب للأدوات إجماعًا في القطاع، لكن بيانات كل جهة لا تُسقط على الأخرى. أطلقت Anthropic أداة Tool Search Tool في نوفمبر 2025، وأطلقت OpenAI أداة Tool Search في مارس 2026 مع GPT-5.4، وقد نشرت كل منهما بيانات توفير مقاسة وفق شروطها الخاصة. أما Google هذه المرة فقدّمت أمثلة افتراضية فقط. وحتى 20 نوفمبر 2026، لا توجد قياسات إنتاجية مستقلة قابلة للتحقق لـ Gemini Tool Retrieval. لذلك فإن عبارات من قبيل “Gemini يوفر 85% في القياس الفعلي” لا تصمد حاليًا.
نصيحة للمطورين: ابدأ بتصنيف أدوات الـ Agent الحالية حسب تكرار الاستدعاء؛ حمّل الأدوات عالية التكرار مباشرة، وأجّل تحميل الأدوات ذات الاستخدام النادر (long tail)؛ ثم قارن، على نفس مجموعة المهام، التحميل الثابت مع Tool Retrieval من حيث إجمالي Tokens والزمن من البداية إلى النهاية ونسبة اختيار الأداة الصحيحة ودقة المعاملات. الميزة لا تزال في مرحلة المعاينة ولم يُحدد موعد إطلاقها الرسمي، لذا من الأفضل في بيئة الإنتاج الإبقاء على مفتاح للرجوع إلى التحميل الثابت. وفي مرحلة اختيار النموذج، يمكنك أولاً تشغيل خط أساس قياسي لـ Function Calling بتكلفة منخفضة عبر الواجهة الموحدة لـ APIYI apiyi.com، ثم الانتقال إلى v1beta الرسمي للتحقق من صافي عائد Tool Retrieval.
كلما زادت الأدوات، كان لا بد أولاً من التفكير بوضوح في متى تُستخدم كل أداة. وكما ورد في «لون يو·وي لينغ غونغ» (الحوارات): «من أراد إتقان عمله، فعليه أولاً أن يشحذ أدواته.»
📚 المراجع
-
Introducing Tool Retrieval in the Gemini API: إعلان رسمي من Google
- الرابط:
blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval - الوصف: تاريخ النشر، وأهداف التصميم، وMCP، ووضعي الاسترجاع
- الرابط:
-
وثائق Tool retrieval الرسمية: التكوين والقيود والفوترة وأمثلة الحساب
- الرابط:
aistudio.google.com/docs/tool-retrieval - الوصف: الشفرة التطبيقية لهذه المقالة، وقواعد الأخطاء، والإعادة العديمة الحالة، وأمثلة حساب الرموز، وهذه هي المرجع الأساسي
- الرابط:
-
وثائق Function Calling الرسمية: تنفيذ الدوال وإعادة النتائج
- الرابط:
aistudio.google.com/docs/function-calling - الوصف: الاستخدام القياسي لـ
function_resultوcall_id
- الرابط:
-
وثائق Interactions API الرسمية: بنية الواجهة وخطوات التنفيذ
- الرابط:
aistudio.google.com/docs/interactions-overview - الوصف: المحادثة ذات الحالة، و
steps، والفرق بينها وبينgenerateContent
- الرابط:
-
إصدار python-genai v3.6.0 / v3.0.0: سجل إصدارات SDK
- الرابط:
github.com/googleapis/python-genai/releases - الوصف: دعم مخطط Tool Retrieval وتغيرات نسخة API الافتراضية
- الرابط:
المؤلف: فريق APIYI التقني
التبادل التقني: لاختبارات مقارنة Function Calling بين النماذج المتعددة يمكنكم زيارة APIYI على apiyi.com، وللمزيد من مواد التكامل راجع مركز الوثائق docs.apiyi.com
