إذا أردت بناء تطبيق ذكاء اصطناعي واحد يعمل مع GPT وClaude وGemini وDeepSeek وGrok، فاستخدم واجهة API موحّدة للمسار المشترك للطلبات واحتفِظ بسياسة التوجيه داخل تطبيقك. CometAPI توفّر عنوان Base URL متوافقًا مع OpenAI وفهرس نماذج مشتركًا، بحيث يمكن لخدمة Python استدعاء معرّفات نماذج مختلفة عبر عميل واحد. لا يزال رمزك هو من يقرّر أي نموذج يعمل، وأي أدوات مسموح بها، ومتى يكون الرجوع الآمن مناسبًا.
يبني هذا الدليل وكيلاً لـ Grok 4.7 يمكنه طلب أداتين تجاريتين للقراءة فقط، ورفض الأدوات غير المعروفة والوسائط (Arguments) المشوّهة قبل التنفيذ، والتبديل إلى نموذج آخر مختبَر تعاقديًا فقط بعد حالات فشل عابرة محدّدة. الهدف ليس نظامًا مستقلاً سحريًا، بل حلقة صغيرة قابلة للفحص يمكن اختبارها وتشغيلها في الإنتاج.
ما الذي ستقوم ببنائه
يتكوّن الوكيل من خمسة أجزاء صريحة:
- عميل CometAPI واحد. يستخدم OpenAI Python SDK عنوان Base URL الخاص بـ CometAPI كما يظهر في الإعداد أدناه.
- Grok 4.7 بوصفه النموذج الأساسي. معرّف النموذج الحالي في CometAPI هو
grok-4.7. - سجل أدوات (Tool registry). قد يقترح النموذج استدعاء دالة، لكن رمز التطبيق وحده يمكنه تنفيذ دالة موجودة على قائمة السماح.
- حلقة وكيل محدودة. تتوقّف الحلقة بعد عدد ثابت من أدوار النموذج بدلاً من التشغيل إلى ما لا نهاية.
- سياسة رجوع مرتّبة. تُجرَّب معرّفات نماذج متوافقة من GPT أو Claude أو Gemini أو DeepSeek فقط بعد فشل مؤقّت قابل لإعادة المحاولة من جانب النموذج/الواجهة.
يدعم Grok 4.7 استدعاء الدوال، وتوثّق CometAPI حاليًا مساري /v1/chat/completions و/v1/responses للنموذج. يستخدم هذا الدليل Chat Completions لأن tools المتوافقة مع OpenAI واستدعاءات الأدوات من المساعد ورسائل نتائج الأدوات المطابقة من نوع tool تُطابِق مباشرة حلقة Python مدمجة وقابلة للفحص. توافق النقل لا يثبت التكافؤ الوظيفي الكامل بين جميع النماذج، لذا يجب أن يجتاز كل رجوع مُهيّأ نفس اختبارات العقد قبل دخوله الإنتاج.
حالة الاستدلال في وكلاء Grok 4.7 متعدّدي الأدوار
يقبل Grok 4.7 مستويات جهد استدلال low وmedium وhigh وxhigh، والقيمة الافتراضية هي high. على واجهة Responses الخاصة بـ xAI، تتضمن كل استجابة من Grok 4.7 الحقل reasoning.encrypted_content؛ ينبغي للحلقة متعددة الأدوار المُدارة من جهة العميل إعادة تمرير عناصر الاستدلال المرتجعة دون تغيير في الطلب التالي. كما يمكن للحلقات الطويلة استخدام ضغط السياق: احتفِظ بعنصر الضغط المرتجع كحالة معتمة وألحِق الأدوار الجديدة بعده. ونظرًا لكون هذه الحقول حالةً مخصّصة لمزود الخدمة، تحقّق من أن المسار المختار عبر CometAPI يُعيدها طرفًا لطرف قبل جعلها اعتمادًا إنتاجيًا.
بنية الوكيل: النموذج يقترح، وتطبيقك يقرّر
تدفّق استدعاء الأدوات الآمن بسيط:
User request → model response → validate tool call → execute allowlisted tool → append tool result → model response
لا يتلقى النموذج بيانات اعتماد قاعدة البيانات ولا ينفّذ Python مباشرة. بل ينتج طلبًا منظّمًا مثل "استدعِ get_order_status مع معرّف الطلب هذا". يراجع تطبيقك اسم الأداة، ويحلّل الوسائط، ويطبّق التفويض وقواعد العمل، ويشغّل الدالة، ثم يعيد نتيجة مسلسلة (Serialized).
هذا الفصل أهم من اختيار النموذج. يجب أن يرث نموذج الرجوع نفس حدود الأدوات — لا حدودًا أوسع — وأن تُعامَل نتائج الأدوات كبيانات غير موثوقة عندما تحتوي على محتوى خارجي.
كيفية بناء وكيل Grok 4.7 باستخدام Python
الخطوة 1: ضبط OpenAI Python SDK ليتّصل عبر CometAPI
ثبّت OpenAI SDK:
pip install openai
اضبط الإعداد عبر متغيّرات البيئة:
export COMETAPI_KEY="your-cometapi-key"
export PRIMARY_MODEL="grok-4.7"
export FALLBACK_MODEL_1="your-compatible-gpt-model-id"
export FALLBACK_MODEL_2="your-compatible-claude-model-id"
export FALLBACK_MODEL_3="your-compatible-gemini-model-id"
export FALLBACK_MODEL_4="your-compatible-deepseek-model-id"
يستخدم هذا الدليل Chat Completions لأن استدعاءات الأدوات الصريحة من المساعد ورسائل نتائج الأدوات المطابقة تجعل تدفّق التحكم سهل الفحص ضمن مثال Python مدمج. للحلقات الأطول ذات الحالة، قيّم استخدام Responses API كما ذُكر أعلاه. كذلك، لا تنسخ معرّفات نماذج قديمة من منشور مدونة إلى الإنتاج: اجلب فهرس GET /api/models العام الخاص بـ CometAPI أثناء النشر أو بدء التشغيل، ثم أكّد القدرات والتسعير في دليل النماذج.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
timeout=30.0,
)
المهلة الصريحة وتعطيل إعادة المحاولة في SDK مقصودان. سيقوم التطبيق بتصنيف حالات الفشل وتقرير ما إذا كان يجب تكرار الطلب أو الانتقال إلى نموذج آخر. عمليات إعادة المحاولة الخفية تجعل زمن الاستجابة، والآثار الجانبية المكررة، وسلوك الرجوع أصعب فهمًا.
الخطوة 2: ابدأ بأدوات ضيّقة للقراءة فقط
ابدأ بأدوات تقرأ البيانات بدلًا من تغييرها. التعريفات التالية تسمح للوكيل بالتحقّق من طلب والاطّلاع على المخزون. التنفيذ يعيد بيانات تجريبية؛ استبدله باستدعاءات مصادقة لخدماتك الخاصة.
import json
TOOLS = [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Read the current status of one order.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": False,
},
},
},
{
"type": "function",
"function": {
"name": "check_inventory",
"description": "Read available inventory for one SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {"type": "string"}
},
"required": ["sku"],
"additionalProperties": False,
},
},
},
]
def get_order_status(order_id: str) -> dict:
# Replace this demo with an authenticated, read-only service call.
return {"order_id": order_id, "status": "in_transit"}
def check_inventory(sku: str) -> dict:
# Replace this demo with an authenticated, read-only service call.
return {"sku": sku, "available_units": 12}
TOOL_REGISTRY = {
"get_order_status": get_order_status,
"check_inventory": check_inventory,
}
يحسّن مخطط JSON شكل الطلب، لكنه ليس تفويضًا. تحقّق من أطوال الوسائط وصيغها، وأكّد أن المستخدم الحالي مخوَّل للوصول إلى الطلب أو رمز الصنف المطلوب، وحدّد حجم نتيجة كل أداة قبل إعادتها إلى النموذج.
الخطوة 3: أضِف سياسة رجوع ضيّقة متعددة النماذج
يجب أن يعالج الرجوع حالات فشل المسار المؤقتة، لا أن يخفي الطلبات المكسورة. يوصي دليل الرجوع الرسمي لـ CometAPI بالانتقال إلى المسار التالي المُهيّأ لأخطاء الاتصال، والمهلات، وHTTP 408، وHTTP 429، واستجابات 5xx المؤقتة. ينبغي أن تفشل بيانات الاعتماد غير الصحيحة، والمعاملات غير المدعومة، والطلبات غير الصحيحة فورًا.
from openai import APIConnectionError, APIStatusError, APITimeoutError
def configured_models() -> list[str]:
names = [
os.getenv("PRIMARY_MODEL", "grok-4.7"),
os.getenv("FALLBACK_MODEL_1"),
os.getenv("FALLBACK_MODEL_2"),
os.getenv("FALLBACK_MODEL_3"),
os.getenv("FALLBACK_MODEL_4"),
]
return [name for name in names if name]
def is_retryable(error: Exception) -> bool:
if isinstance(error, (APIConnectionError, APITimeoutError)):
return True
if isinstance(error, APIStatusError):
return error.status_code in {408, 429} or error.status_code >= 500
return False
def complete_with_fallback(messages: list[dict], tools: list[dict]):
models = configured_models()
last_error = None
for index, model in enumerate(models):
try:
response = client.chat.completions.create(
model=model,
messages=messages,
tools=tools,
tool_choice="auto",
)
return response, model
except Exception as error:
last_error = error
final_route = index == len(models) - 1
if final_route or not is_retryable(error):
raise
raise RuntimeError("No configured model completed the request") from last_error
قائمة النماذج هي إعداد، لا تصنيف جودة. اختر بدائل تدعم الأدوار الرسائليّة نفسها، ومخطط الأدوات المطلوب، وطريقة الإدخال، ومتطلبات السياق، وسلوك الاستجابة اللازمة لهذا الوكيل. سجّل المسار المحدّد وسبب كل انتقال.
الخطوة 4: شغّل حلقة وكيل Grok 4.7 المحدودة
ترسل الحلقة أدناه المحادثة، وتنفّذ أي استدعاءات أدوات مسموح بها، وتُلحِق النتائج مع tool_call_id المطابق، وتطلب من النموذج المختار إتمام الإجابة.
def execute_tool_call(tool_call) -> str:
name = tool_call.function.name
if name not in TOOL_REGISTRY:
return json.dumps({"error": f"Tool not allowed: {name}"})
try:
arguments = json.loads(tool_call.function.arguments)
result = TOOL_REGISTRY[name](**arguments)
return json.dumps(result)
except (json.JSONDecodeError, TypeError, ValueError) as error:
return json.dumps({"error": f"Invalid tool arguments: {error}"})
def run_agent(user_text: str, max_turns: int = 4) -> dict:
messages = [
{
"role": "system",
"content": (
"You are a support agent. Use tools only when needed. "
"Never invent order or inventory data."
),
},
{"role": "user", "content": user_text},
]
route_log = []
for turn in range(max_turns):
response, model = complete_with_fallback(messages, TOOLS)
route_log.append({"turn": turn + 1, "model": model})
assistant = response.choices[0].message
messages.append(assistant.model_dump(exclude_none=True))
if not assistant.tool_calls:
return {
"answer": assistant.content,
"routes": route_log,
"usage": response.usage.model_dump() if response.usage else None,
}
for tool_call in assistant.tool_calls:
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": execute_tool_call(tool_call),
}
)
raise RuntimeError("Agent stopped after reaching max_turns")
result = run_agent("Where is order A-104, and is SKU BLUE-42 in stock?")
print(result["answer"])
print(result["routes"])
يدعم الرمز عدة استدعاءات أدوات في استجابة نموذج واحدة لأنه يُلحِق نتيجة لكل استدعاء مُرجع. إذا كانت الأداة تغيّر الحالة — إرسال بريد إلكتروني، أو تقديم طلب، أو إصدار ردّ — فأضِف مفتاحًا لعدم التكرار (Idempotency) وخطوة تأكيد بشرية. لا تعِد تشغيل دور الوكيل بالكامل بشكل أعمى بعد مهلة إذا كان من الممكن أن يكون قد حدث تأثير جانبي بالفعل.
كيف تتوافق GPT وClaude وGemini وDeepSeek مع التطبيق نفسه
يمكن لـ CometAPI تقليل التكرار في طبقة الاتصال: حساب واحد، وBase URL متوافق مع OpenAI للمسار المشترك، ومعرّف نموذج تُحدده شيفرة التطبيق. هذا يجعل GPT وClaude وGemini وDeepSeek وGrok مرشّحين خلف واجهة داخلية واحدة.
لكن ذلك لا يجعل النماذج قابلة للاستبدال. قبل إضافة رجوع، تحقّق من:
- أن معرّف النموذج الحالي مُعاد من فهرس CometAPI؛
- أن المسار يدعم مخطط الأدوات والأدوار الرسائلية المطلوبة؛
- أن وسائط استدعاء الأدوات وسلوك الاستدعاءات المتعددة تطابق عقد الوكيل؛
- أن نافذة السياق وطرائق الإدخال تلائم الطلب؛
- أن الاستجابة يمكن التحقّق منها قبل أن تصل إلى المستخدم؛
- أن الكمون والتكلفة يبقيان ضمن ميزانية المنتج.
قد تتطلب ميزات مزوّد الخدمة الأصلية نقطة نهاية أصلية أو مُكيّف (Adapter) منفصلًا. احتفِظ بهذه الاستثناءات صريحةً بدل محاولة تمرير كل قدرة عبر الواجهة المشتركة.
الرجوع متعدد النماذج في Grok 4.7 ليس نظامًا متعدد الوكلاء
تختار سلسلة الرجوع متعدد النماذج نموذجًا آخر عند فشل المسار. أما النظام متعدد الوكلاء فيُسند مسؤوليات مختلفة إلى وكلاء منفصلين — مثل المخطّط، والباحث، والمراجع. النمطان يحلان مشاكل مختلفة.
إذا مدّدت هذا الوكيل إلى سير عمل متعدد الوكلاء، فأعطِ كل عامل دورًا ضيقًا، وقائمة أدوات مسموحًا بها منفصلة، وميزانية محدودة، وتسليمًا منظّمًا. لا تسمح لكل وكيل باستدعاء كل أداة أو بتمرير نص غير محدود. ابدأ بوكيل واحد إلى أن تُثبت بيانات التقييم أن فصل الأدوار يحسّن النتيجة.
حواجز حماية إنتاجية لوكيل Grok 4.7
التحقّق قبل تنفيذ الأداة
راجِع أسماء الأدوات، ومخططات الوسائط، وملكية المستأجر (Tenant)، وأذونات المستخدم، وحدود المعدّل في رمز التطبيق. اعتبر أوصاف الأدوات إرشادًا للنموذج، لا ضوابط أمنية.
افصل أدوات القراءة عن أدوات الكتابة
يمكن غالبًا تشغيل أدوات القراءة تلقائيًا بعد التفويض. ينبغي أن تتطلب أدوات الكتابة تحقّقات أقوى، وعدم تكرار، وتأكيدًا للإجراءات ذات الأثر.
حدِّ كل حلقة
اضبط حدًا أقصى لأدوار النموذج، واستدعاءات الأدوات، والوقت الإجمالي، وحجم المطلب، وميزانية الرموز. أعِد خطأً مضبوطًا أو مسار تصعيد عندما يتم بلوغ حد.
سجّل مسار القرارات
سجّل المهمة المطلوبة، وإصدار السياسة، ومعرّف النموذج المختار، وسبب الرجوع، واسم الأداة، وزمن تنفيذ الأداة، ونتيجة التحقّق، واستخدام الرموز، والحالة النهائية. لا تسجّل أسرارًا أو محتوى عملاء غير ضروري.
استخدم اختبارات عقد، لا افتراضات
شغّل نفس مجموعات الاختبار ضد كل نموذج مُهيّأ. حدّ أدنى مفيد يشمل إجابة عادية، واستدعاء أداة واحد، واستدعاءات أدوات متعددة، ووسائط مشوّهة، وأداة غير معروفة، ومهلة أداة، ورمز 429 من النموذج الأساسي، ومفتاح API غير صالح يجب ألّا يسبّب الرجوع.
قائمة تحقق للنشر
- اجلب معرّفات النماذج الحالية وتحقق من مسار Grok 4.7 قبل النشر.
- احتفِظ بمفتاح CometAPI في مدير أسرار، وليس في الشيفرة المصدرية أو المطالبات.
- ابدأ بأدوات قراءة فقط ومخططات JSON صريحة.
- طبّق المصادقة وتفويض المستأجر قبل كل استدعاء أداة.
- اسمح بالرجوع فقط للأخطاء العابرة المصنّفة.
- اختبر كل رجوع وفق عقد استدعاء الأدوات نفسه.
- أضِف عدم التكرار والتأكيد قبل تفعيل أدوات الكتابة.
- اضبط حدود الحلقة والكمون والسياق والتكلفة.
- قِس نجاح المهمة، وليس توفر API فقط.
لماذا تبني هذا الوكيل عبر CometAPI؟
تكون CometAPI مفيدة هنا لأن التكامل المشترك يبقى صغيرًا. يشير OpenAI Python SDK إلى Base URL واحد، ويتم اختيار Grok 4.7 عبر معرّف النموذج، ويمكن وضع نماذج متوافقة من مزوّدين آخرين خلف سياسة مسار مملوكة للتطبيق نفسه.
هذا يمنح الفريق مساحة لتقييم GPT وClaude وGemini وDeepSeek دون نثر شيفرات اتصال خاصة بالمزودين عبر المنتج. كما يحافظ على حدود مهمة: توفّر CometAPI الوصول، بينما يمتلك تطبيقك فحوصات القدرات، وتنفيذ الأدوات، وسياسة الرجوع، والتقييم، والسلوك المواجه للمستخدم.
راجِع صفحة نموذج Grok 4.7 الحالية، واضبط العميل من الدليل السريع لـ CometAPI، واجلب معرّفات النماذج الحالية قبل اختيار بدائل إنتاجية.
الأسئلة الشائعة
أي API ينبغي أن أستخدمه لتطبيق يعمل مع GPT وClaude وGemini وDeepSeek؟
للمسار المشترك للدردشة واستدعاء الأدوات، يمكن لواجهة API موحّدة متوافقة مع OpenAI مثل CometAPI أن تقلّل جهد التكامل. احتفِظ باختيار النموذج وسياسة الرجوع داخل تطبيقك، واستخدم المكيّفات الأصلية للمزوّد عندما لا تتوافق ميزة مطلوبة مع العقد المشترك.
هل يمكن لـ Grok 4.7 استدعاء دوال Python مباشرة؟
يمكن لـ Grok 4.7 إرجاع طلبات استدعاء دوال منظّمة. يقوم تطبيق Python لديك بتحليل الطلب، والتحقّق منه، وتنفيذ دالة موجودة على قائمة السماح، ثم إرسال النتيجة إلى النموذج. النموذج نفسه لا ينفّذ Python محليًا.
هل يجب أن يفعّل كل خطأ الانتقال إلى نموذج مختلف؟
لا. استخدم الرجوع لأخطاء اتصال محدّدة، والمهلات، و408، و429، واستجابات 5xx المؤقتة. يجب إصلاح الطلبات غير الصالحة، وإخفاقات المصادقة، والمعاملات غير المدعومة بدل إرسالها إلى نموذج آخر.
هل يمكنني استخدام مخطط أدوات واحد مع كل نموذج؟
فقط بعد الاختبار. فالمسار المشترك لا يضمن تطابق سلوك الأدوات، أو جودة الوسائط، أو سلوك الاستدعاءات المتوازية، أو فرض المخطط. أضِف نموذجًا إلى السلسلة فقط بعد أن يجتاز اختبارات عقد الوكيل.
هل نظام الرجوع متعدد النماذج هو نفسه نظامًا متعدد الوكلاء؟
لا. يغيّر الرجوع النموذج المستخدم للطلب بعد فشل المسار. أمّا البنية متعددة الوكلاء فتسند مهام مختلفة إلى وكلاء منفصلين. ابنِهما كطبقتين منفصلتين مع اختبارات وضوابط مستقلة.