تطبيق واحد يتصل بـ GPT وClaude وGemini في آن واحد: ستة أنواع من مشكلات التوافق التي يجب معالجتها عند تبديل النموذج

ملاحظة المؤلف: ينبغي أن تعالج التطبيقات متعددة النماذج اختلافات استدعاء الأدوات، وحالة الاستدلال، والإخراج المتدفق، والبيانات المهيكلة، والتخزين المؤقت، وذلك عبر تنسيق رسائل موحد، وطبقة محول للمزوّد، وسجل لقدرات النماذج.

يستطيع GPT وClaude وGemini إتمام استدعاءات النص العادية، كما يوفّر Claude وGemini مداخل رسمية متوافقة مع OpenAI SDK. وعند تبديل النموذج في تطبيق بمستوى الإنتاج، يلزم حل 6 فئات من مشكلات التوافق: أدوار الرسائل والتعليمات النظامية، وبروتوكول استدعاء الأدوات، ومعاملات الاستدلال وحالة التفكير، وأحداث التدفق، والإخراج المهيكل والوسائط المتعددة، وحساب تكلفة التخزين المؤقت ومعالجة الأخطاء. استبدال Model ID وحده يكفي لتشغيل سؤال وجواب بسيط، أما استدعاء الأدوات على عدة دورات، واستعادة التدفق بعد انقطاعه، وحساب التكلفة، فتحتاج إلى معالجة منفصلة. والخيار الهندسي الأكثر أمانًا هو «واجهة أعمال موحدة + طبقة محول المزوّد (Provider Adapter) + سجل قدرات النماذج». وبهذه الطريقة يمكن إدارة تبديل النماذج كخاصية منتج قابلة للصيانة.

في ما يلي، نقارن أولاً الاختلافات البنيوية بين واجهات API الأصلية للشركات الثلاث، ونوضح السيناريوهات التي يمكن أن تغطيها الواجهات المتوافقة مع OpenAI. ثم نحلل واحدًا تلو الآخر الأعطال الواقعية التي قد تنجم عن فئات التوافق الست، ونقدّم معمارية تكامل من ست طبقات وكود استدعاء موحد قابل للتشغيل. وأخيرًا نسرد ستة اختبارات توافق قبل الإطلاق، ونشرح كيف تُقسّم المهام بين بوابة API موحدة وتكييف القدرات الأصلية.

للتعرف: مسرد مصطلحات توافق API متعدد النماذج

1 توافق API متعدد النماذج: لماذا لا يكفي تغيير مُعرّف النموذج (Model ID) وحده عند تبديل النماذج

تتيح المزوّدات الثلاثة جميعًا تحديد النموذج عبر حقل model واحد، لكن طريقة تنظيم جسم الطلب، وكائن الاستجابة، وحالة السياق تختلف من واحد لآخر. في الأسئلة والأجوبة العادية تتركّز الفروقات في أسماء الحقول، فتبقى تكلفة التكيّف منخفضة. أما تطبيقات الوكيل (Agent) فتعتمد على استدعاء الأدوات وحالة الاستدلال وأحداث البث المباشر، وعندها تتحوّل الفروقات مباشرة إلى أعطال في بيئة الإنتاج.

1.1 مقارنة بين واجهات API الأصلية لدى GPT وClaude وGemini

يصف الجدول التالي واجهات API الأصلية فقط، ولا يتناول أي طبقة توافق أو نقطة نهاية عبر بوابة.

من الجدول أعلاه نلاحظ أن المزوّدات الثلاثة ينقسمون إلى مسارين مختلفين في مسألة “من يحفظ السياق”. يدعم OpenAI وGemini استمرارية السياق من جهة الخادم، بينما يعيد تطبيقك سجل الرسائل بنفسه في Claude Messages. وإذا كان تصميم تخزين الجلسات في تطبيقك مبنيًا على إحدى الطريقتين فقط، فسيحدث فقدان للسياق أو إرسال مكرر عند الانتقال إلى مزوّد آخر.

1.2 إلى أي مدى يمكن لواجهة متوافقة مع OpenAI أن تحل المشكلات؟

توفّر كل من Claude وGemini مدخلًا متوافقًا مع OpenAI SDK. نقطة النهاية الرسمية المتوافقة في Gemini هي generativelanguage.googleapis.com/v1beta/openai/، وعند استخدام عميل OpenAI يكفي تعديل base_url ومفتاح API وقيمة model. أما وثائق التوافق الخاصة بـ Claude فتحدد نطاق الدعم بشكل صريح، وفيما يلي القيود المعروفة حتى 2026-11-13:

• يُتجاهل معامل strict في تعريفات الأدوات، وبالتالي تصبح القيود الصارمة على معاملات الأدوات بلا فاعلية.
• لا يدعم Prompt Caching (التخزين المؤقت للموجهات).
• لا يدعم المدخلات من نوع audio أو file.
• تُرفع رسائل system وdeveloper إلى المقدمة وتُدمج معًا.
• تختلف الحقول المتعلقة بـ thinking عن واجهة API الأصلية.

تناسب الواجهة المتوافقة ثلاث حالات: الدردشة العادية، والتوليد في جولة واحدة، والمقارنة السريعة لجودة إجابات النماذج المختلفة. أما ترحيل الوكلاء (Agents) المعقدين فيشمل معاملات أدوات صارمة، وتخزينًا مؤقتًا، ومدخلات ملفات، وحالة استدلال متعددة الجولات؛ وهذه القدرات تتطلب العودة إلى واجهة API الأصلية، أو التحقق منها بندًا بندًا قبل الإطلاق. وهناك معيار عملي للحكم: إذا كانت الوظيفة التي يعتمد عليها التطبيق تظهر فقط في الوثائق الأصلية، فسجّلها في سجل القدرات وسلّمها إلى محوّل مخصص يتولى التعامل معها.

2 ست فئات من مشكلات التوافق الأكثر شيوعًا عند التبديل بين نماذج GPT وClaude وGemini

2.1 التعامل مع توافق أدوار الرسائل وتعليمات النظام

يميّز OpenAI بين أدوار مثل developer وsystem. أما تعليمات system في Claude فتقع خارج مصفوفة الرسائل. ويستخدم Gemini الحقل system_instruction، وله أيضًا قواعد بنيوية خاصة بمحتوى المستخدم ومحتوى النموذج. والثلاثة جميعًا يعبّرون عن “أولوية التعليمات + تاريخ متعدد الأدوار”، لكن موضع الحقل الذي يحملها يختلف من واحد لآخر.

كثيرًا ما ينشأ الخلل من الدمج الكسول: أن تُجمع تعليمات النظام ورسائل التاريخ ونتائج الأدوات في سلسلة نصية واحدة، ثم تُمرَّر إلى النموذج كمدخل من المستخدم. هذا الأسلوب يعمل، لكن أولوية التعليمات تُضعَف، وقد يعتبر النموذج مخرجات الأدوات في التاريخ متطلبًا جديدًا من المستخدم. والطريقة الصحيحة هي الاحتفاظ بدلالة الأدوار داخل التطبيق، وترك طبقة التكيّف (adapter) تتولى تعيينها إلى حقول كل مزوّد. ومن الأمور التي يجب الانتباه إليها أيضًا أن طبقة توافق Claude تدمج system مع developer، لذا فإن تصاميم الموجهات التي تعتمد على فصل الطبقتين تحتاج إلى تجربة فعلية للتحقق من النتيجة.

2.2 بروتوكولات استدعاء الأدوات والتوافق في معالجة معرّفات الاستدعاء

تدعم الشركات الثلاث استدعاء الدوال (Function Calling)، وتتخذ سلسلة الاستدعاء الشكل التالي:

تحتاج طبقة الأدوات إلى حفظ ستّ معلومات بشكل كامل: معرّف الاستدعاء، واسم الدالة، وJSON المعاملات، وعلاقة الاستدعاء المتوازي، ونتيجة التنفيذ، وما إذا كان النموذج يطلب مواصلة الاستدلال. والاستدعاء المتوازي هو أكثر النقاط عرضةً للأخطاء. فعندما يُطلق النموذج عدة طلبات أدوات دفعةً واحدة، ثم يعيد التطبيق إرسال نتيجة واحدة فقط، أو تُقرن النتائج بمعرّفات خاطئة، فإن الطلب في الجولة التالية سيرفع خطأ في المعاملات، أو يواصل النموذج الإجابة بناءً على بيانات خاطئة.

من المستحسن أن تتحقق طبقة الأدوات الموحّدة من المعاملات باستخدام JSON Schema أولاً، ثم تنفّذ العملية الخارجية الفعلية بعد اجتياز التحقق. فالمعاملات التي يولّدها النموذج ليست صالحة دائمًا، والتحقق المسبق يمكن أن يعترض الأخطاء قبل “استدعاء النظام الخارجي”.

2.3 التوافق في التعامل مع أوضاع التفكير وحالة السياق

أسماء معاملات الاستدلال ومعانيها ليست متكافئة بين الشركات الثلاث:

• OpenAI: تستخدم معاملات مثل reasoning.effort. لا يقبل GPT-6 Astra و GPT-6.1 Sol القيمة reasoning.effort=none، كما أن استدعاء الأدوات في هذين النموذجين يتطلب استخدام Responses API.
• Claude: تعتمد النماذج الحديثة أساسًا على Adaptive Thinking، إلى جانب إعدادات التفكير مثل effort. بعض النماذج الجديدة لم تعد تدعم وضع التفكير اليدوي القديم القائم على budget_tokens الثابت.
• Gemini: تستخدم النماذج المختلفة thinking level أو budget، وتختلف إمكانية إيقاف الاستدلال والمستويات المتاحة من نموذج لآخر. كما تختلف قواعد تعيين المعاملات بين واجهة API الأصلية ومدخل التوافق مع OpenAI.

عند تصميم ثلاث درجات لقوة الاستدلال في واجهة المنتج (“سريع، قياسي، معمّق”)، فإن أسماء الدرجات تعبّر عن نية المنتج. ويحتاج المحوّل إلى تحويلها إلى المعاملات التي يدعمها كل نموذج فعليًا، كما أن الموارد الحسابية التي تحصل عليها الشركات الثلاث عند الدرجة نفسها ليست متساوية. إضافة إلى ذلك، قد لا يتطابق ملخص التفكير الذي يراه المستخدم مع عدد رموز التفكير التي تُحتسب فعليًا، لذا يجب أن تعتمد إحصائيات التكلفة على حقول الاستخدام التي تعيدها الواجهة.

الحالة المشفّرة في استدعاء الأدوات متعددة الدورات هي من أكثر النقاط التي يغفل عنها الوكيل طويل المدى:

• قد تحتاج عناصر reasoning في OpenAI Responses واستدعاءات الأدوات إلى الاستمرار في الانتقال مع السجل.
• قد تحتوي كتل thinking / redacted_thinking في Claude على حالة مشفّرة، ويجب الحفاظ على بنيتها الأصلية عند إرسالها مرة أخرى بعد تنفيذ الأدوات.
• يتطلب الوضع stateless في Gemini Interactions الحفاظ على كتل thought والتوقيعات كما هي؛ وعند استخدام الوضع stateful، يمكن للخادم الحفاظ على جزء من الحالة.

حفظ النص الظاهر في نافذة الدردشة وحده لا يكفي لاستعادة تاريخ استدلال النموذج بشكل كامل. الخلل النموذجي هو: أن يخطئ الوكيل فجأة بعد الدورة الثالثة لاستدعاء الأدوات، أو أن يبدأ في تكرار خطوات أُنجزت بالفعل. والسبب عادةً هو فقدان كتلة التوقيع في إحدى الدورات الوسيطة.

2.4 توحيد أحداث البث المباشر (Streaming)

تختلف أنواع أحداث البث المباشر وترتيبها وإشارات انتهائها بين الشركات الثلاث. فقد يُخرج OpenAI Responses أحداثًا مثل response.output_text.delta، وزيادات استدعاء الأدوات، وحدث اكتمال response. أما تدفق Claude Messages فيستخدم أحداثًا مثل message_start وcontent_block_delta وmessage_delta. بينما تعتمد واجهة Gemini الأصلية على بنيتها الخاصة للإخراج والخطوات.

إذا كانت الواجهة الأمامية تحلّل أحداث المزوّد الخام مباشرة، فسيتعين تعديل كود الواجهة الأمامية في كل مرة تُدمج فيها نموذجًا جديدًا. لذلك يُنصح بتحويل الأحداث في الخادم الخلفي إلى بروتوكول أحداث داخلي موحّد:

هناك ثلاث نقاط أعطال شائعة في معالجة البث. الأولى: تصل أجزاء معاملات عدة استدعاءات أدوات متبادلة، فتؤدي عملية التجميع حسب ترتيب الوصول إلى خلط المعاملات فيما بينها. الثانية: يُقطع نص JSON في أي موضع حرف، ومحاولة تحليله عند استلام نصفه تؤدي إلى throwing an exception. الثالثة: ينقطع الاتصال في منتصف الطريق دون استلام حدث الاكتمال، فتبقى الواجهة عالقة على حالة “جارٍ التوليد”. لذا يجب أن تعالج طبقة التحويل هذه الحالات الثلاث صراحةً.

2.5 الإخراج المنظم عبر JSON Schema وفروق قدرات الوسائط المتعددة

يوفّر المزوّدون الثلاثة جميعًا قدرات الإخراج المنظم، لكنهم يختلفون في خصائص JSON Schema المدعومة، والوضع الصارم، وطريقة الدمج مع استدعاء الأدوات. ويفصل Claude رسميًا بين آليتين: «JSON outputs» التي تقيّد بنية الإجابة النهائية، و«Strict tool use» التي تقيّد بنية معاملات استدعاء الأدوات. وعند استخدام بعض النماذج للتنسيق الصارم، قد تظهر أيضًا تكلفة إضافية لتجميع المخطط أو تخزينه مؤقتًا.

من الناحية الهندسية، يُنصح بأن يحتفظ التطبيق بنسخته القياسية الخاصة من JSON Schema، وأن يسجّل في سجل القدرات خصائص JSON Schema التي يدعمها كل نموذج. وللخصائص غير المدعومة، ينفّذ المهايئ تحويلاً تخفيضيًا. ومهما ادّعى النموذج من صرامة، يجب على جانب التطبيق أن يتحقق مرة أخرى بنفسه، وإذا فشل التحقق ينتقل إلى إعادة محاولة منضبطة أو مسار للإبلاغ عن الخطأ.

وينطبق الأمر نفسه على الوسائط المتعددة. فعبارة «دعم إدخال الصور» تصف فئة القدرة فقط، أما التفاصيل فتتطلب مقارنة النقاط التالية: أنواع الملفات المقبولة وأحجامها وعدد الصور، وقدرات الفيديو والصوت، وطريقة رفع الملفات، والحد الأقصى لنافذة السياق الطويلة ونطاقها الفعلي المتاح، والحد الأقصى لرموز الإخراج، وإمكانية دمج استدعاء الأدوات مع المدخلات متعددة الوسائط. وعدم دعم طبقة التوافق مع Claude لمدخلات audio وfile يمثّل قيدًا ملموسًا يجب تدوينه في السجل.

2.6 الفروق بين النماذج في التخزين المؤقت والفوترة ومعالجة الأخطاء

تختلف آليات التخزين المؤقت للموجهات بين الشركات الثلاث اختلافًا واضحًا:

• OpenAI: تدعم نماذج GPT-5.6 والنماذج اللاحقة التخزين المؤقت الضمني ونقاط توقف التخزين المؤقت الصريحة، ومدة الصلاحية (TTL) لها نوعان: 30 دقيقة و12 ساعة.
• Claude: يُحدَّد التخزين المؤقت التلقائي أو الصريح عبر cache_control، ويدعم وضعين: 5 دقائق وساعة واحدة؛ لكن هذه القدرة غير مدعومة في طبقة التوافق مع OpenAI.
• Gemini: توفر النماذج الجديدة تخزينًا مؤقتًا ضمنيًا تلقائيًا، وبعض الـ API والنماذج تدعم إنشاء كائنات تخزين مؤقت صراحةً.

بعد تبديل النموذج، لا يمكن عادةً إعادة استخدام التخزين المؤقت الخاص بالمزود الأصلي. وعند التحول من Claude إلى Gemini في منتصف الجلسة، تُحسب الطلب الأول على أساس الإدخال الكامل. وإذا كان تقدير التكلفة يفترض افتراضيًا أن «التخزين المؤقت يصيب دائمًا»، فكلما زادت وتيرة تبديل الاستراتيجية، زاد انحراف الفاتورة.

كما أن أسعار الوحدة القياسية لكل مزود تختلف اختلافًا واضحًا. الأسعار الرسمية القياسية حتى 2026-11-13 هي كما يلي (دولار أمريكي / مليون Token):

هذا الجدول يوضح فروق الفوترة فقط، فقدرات كل نموذج وظروف استخدامه مختلفة، ولا يمكن تحويل ارتفاع السعر أو انخفاضه مباشرةً إلى مقارنة أداء. ولا يشمل الجدول أيضًا تكاليف كتابة التخزين المؤقت واستدعاء الأدوات ومستويات الخدمة والزيادات التي يفرضها أطراف ثالثون.

💰 توصية لحساب التكاليف: تحتاج فواتير التطبيقات متعددة النماذج إلى تسجيل مفصّل حسب «الإدخال العادي، كتابة التخزين المؤقت، إصابة التخزين المؤقت، التفكير والإخراج، تكاليف الأدوات، رسوم السياق الطويل». وعند استدعاء عدة نماذج بشكل موحد عبر APIYI apiyi.com، يمكنك رؤية استهلاك كل نموذج في مكان واحد، ما يسهّل ربط استراتيجية التوجيه بالتكلفة الفعلية.

أما من ناحية معالجة الأخطاء، فإن معدل الطلبات ومعدل الـ Token والحصص والمهلات الزمنية وصيغ الأخطاء تختلف بين الثلاثة. وينبغي للتطبيق أن يبني تصنيفًا موحدًا للأخطاء: فشل المصادقة، النموذج غير مدعوم، معلمات غير صالحة، طلب كبير جدًا أو تجاوز السياق، تحديد المعدل 429، خطأ من الخادم، انقطاع الشبكة، انقطاع تدفق الاستجابة، فشل استدعاء الأدوات.

كما يجب أن يراعي الرجوع إلى نموذج بديل ما إذا كانت المهمة ذات آثار جانبية. فإذا انتهت مهلة النموذج الرئيسي بعد تنفيذ الأداة، ثم تحوّل النظام تلقائيًا إلى النموذج البديل وأعاد تشغيل المهمة بأكملها، فقد تُنفَّذ عمليات مثل الدفع أو إرسال البريد أو تعديل الملفات مرتين. والحل هو إضافة مفتاح幂等ية إلى الأدوات ذات الآثار الجانبية، بحيث يستأنف الرجوع من «الخطوات التي لم تُنفَّذ بعد» فقط.

3 كيف ينبغي تصميم بنية متوافقة مع واجهات API متعددة النماذج؟

الهيكل الموصى به من ست طبقات كما يلي:

1. واجهة الأعمال: يسأل المستخدم، ويرفع المواد، ويختار النموذج والمهمة.
2. تنسيق طلب موحّد: استخدام بنية موحدة لتمثيل سجل الرسائل، والمرفقات، وقائمة الأدوات، ومتطلبات الإخراج المهيكل، وشدة الاستدلال، ومعرّف المهمة.
3. توجيه النماذج: اختيار GPT أو Claude أو Gemini بناءً على السعر، والقدرات، وزمن الاستجابة، والتوافر، وقواعد العمل.
4. محول المزود (Provider Adapter): تحويل الطلب القياسي إلى التنسيق الأصلي لكل مزود، ثم إعادة تعيين النتيجة العائدة إلى التنسيق الداخلي.
5. تنفيذ الأدوات وإدارة الحالة: الحفاظ على معرّفات الاستدعاء، وسجلات التنفيذ، وسياق المحادثة، وحالة الاستدلال لدى المزود، والتخزين المؤقت، والتعافي من الفشل.
6. السجلات وحساب التكلفة: تسجيل النموذج، وعدد التوكنات (Tokens)، والتكلفة الفعلية، وزمن الاستجابة، والتخزين المؤقت، والأخطاء، واستدعاءات الأدوات في كل طلب.

3.1 إنشاء تنسيق موحّد للرسائل والأدوات

المبدأ الجوهري للتنسيق الموحّد هو تقسيم السجل إلى طبقتين من التخزين. الطبقة الأولى هي السجل القياسي العام، وتشمل رسائل المستخدم، والإجابة النهائية للنموذج، وطلبات الأدوات، ونتائج الأدوات، وهو سجل يستطيع أي مزوّد قراءته وفهمه. أما الطبقة الثانية فهي الحالة الخاصة بكل مزوّد، مثل عناصر reasoning وتوقيع thinking وكتل thought، وتُخزَّن معزولة حسب المزوّد، ولا تُعاد كما هي إلا عند إرسال الطلب إلى المزوّد نفسه.

from dataclasses import dataclass, field
from typing import Any, Literal

@dataclass
class ToolCall:
    call_id: str              # معرّف استدعاء موحّد، والمهايئ مسؤول عن الربط المتبادل مع معرّف المزوّد
    name: str
    arguments: dict[str, Any]
    result: Any = None
    idempotency_key: str = "" # يجب تعيينه للأدوات ذات الآثار الجانبية

@dataclass
class Message:
    role: Literal["system", "developer", "user", "assistant", "tool"]
    content: list[dict]                      # كتل متعددة الوسائط مثل النصوص والصور
    tool_calls: list[ToolCall] = field(default_factory=list)
    # حالة خاصة بالمزوّد: المفتاح هو اسم المزوّد، والقيمة هي التوقيع / كتلة reasoning المحفوظة كما هي
    vendor_state: dict[str, Any] = field(default_factory=dict)

عند تبديل النموذج، يقرأ المهايئ الحقول القياسية ليبني طلبًا جديدًا. أما الأجزاء الموجودة داخل vendor_state والتي تنتمي إلى مزوّدين آخرين فلا تُرسَل، بينما تُعاد الأجزاء التي تنتمي إلى المزوّد الهدف كما هي دون تغيير.

3.2 التكيّف مع واجهات API الأصلية عبر محوّل المزوّد (Provider Adapter)

يتحمّل كل محوّل ثلاث مسؤوليات:

• تحويل المدخلات: تعيين الأدوار (مثل نقل system إلى حقل مستقل خاص بـ Claude)، وتحويل تعريفات الأدوات، وتخفيض مستوى الـ Schema، وتعيين مستويات الاستدلال.
• تحويل المخرجات: تحويل الاستجابة الأصلية وأحداث البث إلى الأحداث الداخلية الموضحة في القسم 2.4، وتعيين معرّفات استدعاء الأدوات إلى معرّفات موحّدة.
• معالجة الحالة: استخراج حالات المزوّد وحفظها، مثل التوقيعات وعناصر الاستدلال (reasoning items)، ثم تحديد ما إذا كان سيتم استخدام الاستمرار من جانب الخادم (previous_response_id، previous_interaction_id) أم إعادة إرسال التاريخ بالكامل.

يمكن للسؤال والجواب العادي أن يسلك مسار المحوّل العام المتوافق مع صيغة OpenAI. أما الحالات التي تتطلب معاملات أدوات صارمة، أو التحكم في التخزين المؤقت، أو حالة تفكير مشفّرة، فتحتاج إلى تنفيذ محوّل أصلي منفصل لكلٍّ منها. بهذه الطريقة نحافظ على راحة المدخل الموحّد، ونمنح القدرات المتقدمة موقعًا واضحًا تُنفَّذ فيه.

3.3 استخدام سجل القدرات لتحديد الميزات المتاحة

يسجّل سجل القدرات ما هو مدعوم فعليًا بوحدة “النموذج + نقطة الوصول”، وقد يقابل النموذج الواحد سجلين مختلفين: أحدهما عند استخدامه عبر API الأصلية والآخر عبر طبقة التوافق. فيما يلي مثال على البنية، أما القيم الفعلية فيجب أن تعتمد على الوثائق الرسمية ونتائج اختباراتك الخاصة:

gpt-6.1-sol@responses:
  tools: true
  tool_api: responses          # استدعاء الأدوات يتطلب استخدام Responses API
  reasoning_effort: [low, medium, high]   # لا يقبل none
  vendor_state: reasoning_items
claude-sonnet@openai-compat:
  tools: true
  strict_tools: false          # طبقة التوافق تتجاهل strict
  prompt_caching: false
  file_input: false
  merges_system_developer: true
gemini-flash@interactions:
  tools: true
  builtin_tools: [google_search, url_context, code_execution]
  vendor_state: thought_signatures

تستعلم طبقة التوجيه (routing) من السجل قبل اختيار النموذج. فإذا كان الطلب يحمل ملفًا، تُستبعد السجلات التي تحمل file_input: false؛ وإذا كان الطلب يحتاج معاملات أدوات صارمة، فلا تُختار إلا السجلات التي تحمل strict_tools: true. ويمكن لواجهة المنتج أيضًا أن تخفي الخيارات غير المدعومة في النموذج الحالي بناءً على ذلك، فتقلّ بذلك حالات ارتكاب المستخدم لأخطاء.

4 الاختبار والمراقبة قبل إطلاق توافق واجهات API متعددة النماذج

4.1 ستة اختبارات توافق: من الأسئلة البسيطة إلى سلسلة الأدوات متعددة الجولات

نفّذ الاختبارات الستة التالية بالترتيب من الأقل تعقيدًا إلى الأعلى:

1. الأسئلة والأجوبة العادية: أرسل الموجه نفسه إلى ثلاثة نماذج، وتحقق من أن محتوى الإجابة وإحصاءات الرموز (Token) سليمة.
2. الإخراج المتدفق: تأكد من وصول الإخراج باستمرار، ومن استقبال إشارة النهاية الصحيحة.
3. استدعاء الأدوات: يستدعي النموذج أداة استعلام عن الطقس أو استعلام عن البيانات، وينفّذها التطبيق ثم يعيد النتيجة.
4. حلقة الأدوات المتعددة: استدعاء الأدوات لأكثر من جولتين متتاليتين، مع التحقق من اكتمال السجل ومعرّفات الاستدعاء.
5. JSON المنظم: الإخراج وفق المخطط (Schema) نفسه، والتحقق من البنية باستخدام مدقق على جانب التطبيق.
6. تبديل النموذج: تبديل جلسة العمل نفسها بين GPT وClaude وGemini، مع التحقق من سلامة السياق وسجل الأدوات والإجابة النهائية.

البندان 4 و6 هما الأقدر على كشف مشكلات حالة الاستدلال، ويُفضّل إدراجهما في عملية التكامل المستمر. أعد تشغيلهما كل مرة تُرقّي فيها إصدار النموذج أو تغيّر نقطة الوصول.

4.2 إنشاء مراقبة موحدة للتكلفة والاستقرار

سجّل في كل طلب على الأقل الحقول التالية: النموذج ونقطة الوصول، ومعدل نجاح الطلبات، ونوع الاستثناء (حسب تصنيف القسم 2.6)، وزمن وصول أول حرف وإجمالي زمن المهمة، والرموز مفصّلة (الإدخال، وكتابة الذاكرة المؤقتة، وإصابة الذاكرة المؤقتة، والتفكير، والإخراج)، وعدد استدعاءات الأدوات وعدد مرات فشلها، وعدد مرات إعادة المحاولة والتراجع.

عند تقييم النموذج، انظر إلى إجمالي زمن المهمة الكاملة وإجمالي تكلفتها؛ فبيانات الطلب الواحد قيمتها المرجعية محدودة. النموذج الرخيص في سعر الوحدة، إذا كان معدل خطأ معاملات الأدوات فيه مرتفعًا ويحتاج إلى عدة جولات من إعادة المحاولة، فقد تكون تكلفته الإجمالية أعلى في الواقع.

5 دور بوابة API الموحدة في توافق واجهات API للنماذج المتعددة

5.1 تكاليف الربط والصيانة

استخدام ثلاثة نماذج في الوقت نفسه يعني ثلاث مجموعات من الحسابات، وثلاث مجموعات من المفاتيح، وثلاث منظومات للفوترة، وثلاث مجموعات من إعدادات SDK. بوابة API الموحدة تجمع كل هذا في مدخل واحد: إدارة مركزية لربط النماذج والبيانات الاعتمادية، وتقليل صيانة الإعدادات لدى كل مزوّد، وإمكانية اختيار النموذج والتبديل بينه على مستوى طبقة الإعداد، ورؤية موحدة للاستخدام والتكلفة. وبالنسبة للفرق التي تقارن أداء النماذج باستمرار، تصبح عتبة تجربة نموذج جديد أقل ارتفاعًا.

5.2 موقع APIYI: تقسيم العمل بين المدخل الموحد والتوافق مع القدرات الأصلية

APIYI منصة تجميع لواجهات API لنماذج الذكاء الاصطناعي الكبيرة؛ بمفتاح API واحد يمكنك استدعاء النماذج الشائعة مثل OpenAI وClaude وGemini عبر واجهة متوافقة مع OpenAI، مع فوترة حسب الاستخدام. وهي مناسبة لتأدية دور «المدخل الموحد للاستدعاء» في المعمارية: الأسئلة والأجوبة العادية، والإخراج التدفقي، ومقارنة النماذج، وتوجيه النماذج المتعددة، كلها قابلة للربط مباشرة.

أن يكون المدخل الموحد متطابقًا تمامًا مع القدرات الأصلية للمزوّد هما متطلبان تقنيان مختلفان. فعند ربط نموذج معيّن، لا يزال عليك أن تتحقق بندًا بندًا في سجل القدرات من نطاق دعم استدعاء الأدوات، وحالة التفكير، والوسائط المتعددة، والتخزين المؤقت، والمخرجات المهيكلة. أما المسارات التي تعتمد على قدرات أصلية مثل Responses API وcache_control والتوقيعات المشفرة، فيجب التأكد من أن نقطة النهاية المقابلة متاحة فعلًا قبل الإطلاق، أو حفظ محوّل أصلي مخصّص لها.

بدء سريع مع توافق API متعدد النماذج

مثال مبسّط: مقارنة ثلاثة نماذج بنفس الموجه

يستدعي الكود التالي ثلاثة نماذج بالتتابع عبر عميل OpenAI SDK نفسه، وهو ما يقابل البند الأول في القسم 4.1.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # واجهة APIYI الموحدة
)

# معرّفات النماذج حسب قائمة النماذج على المنصة
MODELS = ["你的GPT模型ID", "你的Claude模型ID", "你的Gemini模型ID"]

for model in MODELS:
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "用一句话解释什么是幂等"}],
    )
    print(model, "→", resp.choices[0].message.content)
    print("usage:", resp.usage)

import json
import openai
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # واجهة APIYI الموحدة
)

# سجل القدرات: القيم مجرد أمثلة هيكلية، حافظ عليها وفق الوثائق الرسمية ونتائج الاختبار الفعلي
CAPABILITIES = {
    "gpt":    {"model": "معرّف نموذج GPT الخاص بك",    "tools_via": "responses"},  # استدعاء الأدوات يجب أن يمر عبر محوّل Responses
    "claude": {"model": "معرّف نموذج Claude الخاص بك", "tools_via": "chat"},
    "gemini": {"model": "معرّف نموذج Gemini الخاص بك", "tools_via": "chat"},
}

def classify_error(e: Exception) -> str:
    """تصنيف موحّد للأخطاء يحدد ما إذا كان يمكن إعادة المحاولة"""
    if isinstance(e, openai.AuthenticationError):
        return "auth_failed"
    if isinstance(e, openai.NotFoundError):
        return "model_not_supported"
    if isinstance(e, openai.RateLimitError):
        return "rate_limited"          # يمكن إعادة المحاولة مع تراجع زمني
    if isinstance(e, openai.BadRequestError):
        return "invalid_request"       # خطأ في المعاملات أو تجاوز السياق، لا تُعد المحاولة بشكل أعمى
    if isinstance(e, openai.APIConnectionError):
        return "network_error"
    if isinstance(e, openai.InternalServerError):
        return "server_error"
    return "unknown"

def stream_chat(provider: str, messages: list, tools: list | None = None):
    """تحويل تدفّق بصيغة متوافقة مع OpenAI إلى أحداث داخلية موحّدة"""
    cap = CAPABILITIES[provider]
    if tools and cap["tools_via"] != "chat":
        raise NotImplementedError(f"{provider} 的工具调用请交给原生适配器处理")

    kwargs = {
        "model": cap["model"],
        "messages": messages,
        "stream": True,
        "stream_options": {"include_usage": True},
    }
    if tools:
        kwargs["tools"] = tools

    calls: dict[int, dict] = {}   # دمج أجزاء معاملات استدعاءات الأدوات المتوازية حسب index
    finished = False
    try:
        for chunk in client.chat.completions.create(**kwargs):
            if not chunk.choices:
                if chunk.usage:
                    yield {"type": "usage", "data": chunk.usage.model_dump()}
                continue
            choice = chunk.choices[0]
            delta = choice.delta
            if delta.content:
                yield {"type": "text_delta", "data": delta.content}
            for tc in delta.tool_calls or []:
                slot = calls.setdefault(tc.index, {"id": None, "name": "", "args": ""})
                if tc.id:
                    slot["id"] = tc.id
                if tc.function and tc.function.name:
                    slot["name"] = tc.function.name
                    yield {"type": "tool_call_start", "data": {"id": slot["id"], "name": slot["name"]}}
                if tc.function and tc.function.arguments:
                    slot["args"] += tc.function.arguments
                    yield {"type": "tool_call_args", "data": {"index": tc.index}}
            if choice.finish_reason:
                finished = True
                yield {"type": "completed", "data": {
                    "finish_reason": choice.finish_reason,
                    "tool_calls": list(calls.values()),
                }}
    except Exception as e:
        yield {"type": "error", "data": classify_error(e)}
        return
    if not finished:
        yield {"type": "error", "data": "stream_interrupted"}  # انقطاع التدفّق في منتصفه

EXECUTED_KEYS: set[str] = set()   # في بيئة الإنتاج استبدله بتخزين دائم

def run_tool(call: dict, schema: dict, func, idempotency_key: str | None = None):
    """تحقّق من المعاملات أولاً، ثم نفّذ بشكل عيدي"""
    try:
        args = json.loads(call["args"])   # لا تُحلّل إلا بعد اكتمال تجميع الأجزاء
        validate(instance=args, schema=schema)
    except (json.JSONDecodeError, ValidationError) as e:
        return {"error": f"invalid_arguments: {e}"}
    if idempotency_key:
        if idempotency_key in EXECUTED_KEYS:
            return {"skipped": "already_executed"}
        EXECUTED_KEYS.add(idempotency_key)
    return func(**args)

# مثال على الاستخدام
for event in stream_chat("claude", [{"role": "user", "content": "介绍一下流式输出"}]):
    print(event)

🚀 بدء سريع: سجّل عبر APIYI على apiyi.com للحصول على رصيد اختبار مجاني، ثم استخدم الشيفرة أعلاه لإكمال أول اختبارين في القسم 4.1 باستخدام مفتاح API نفسه. أما الاختبارات المتعلقة باستدعاء الأدوات والاستدلال متعدد الجولات، فتحقق منها لكل نموذج على حدة بالاستعانة بسجل القدرات.

الأسئلة الشائعة FAQ

النقاط الأساسية لتوافق API متعدد النماذج Key Takeaways

• تغيير النموذج ≠ تغيير المعرّف: يمكن ترحيل الأسئلة والأجوبة العادية مباشرة، أما مسارات الوكيل (Agent) فتحتاج إلى معالجة 6 أنواع من الاختلافات.
• طبقة التوافق لها حدود: طبقة توافق Claude تتجاهل strict، ولا تدعم التخزين المؤقت ولا إدخال الملفات.
• يجب حفظ التوقيع كما هو: فقدان توقيع thinking / thought هو سبب شائع للأخطاء في سلاسل الأدوات متعددة الجولات.
• توحيد أحداث البث: يُخرج الخادم الخلفي 8 أنواع من الأحداث الداخلية، بينما تتعامل الواجهة الأمامية مع بروتوكول واحد فقط.
• سجل القدرات يقود التوجيه: تُسجَّل الوظائف المدعومة فعليًا بوحدة «النموذج + نقطة النهاية».
• التراجع يجب أن يكون آمن التكرار (idempotent): أضف مفتاح idempotency للأدوات ذات الأثر الجانبي لمنع التنفيذ المتكرر.
• اختبر قبل الإطلاق: استخدم الحصة المجانية من APIYI apiyi.com لتشغيل اختبارات التوافق الستة بنجاح.

الخلاصة

عندما يدمج تطبيق واحد بين GPT وClaude وGemini في الوقت نفسه، يكمن جوهر الأمر في تجميع الفروقات وإدارتها داخل عدد قليل من المكونات:

1. توحيد تنسيق الرسائل والأدوات: يُخزَّن السجل القياسي والحالة الخاصة بكل مزوّد في طبقتين منفصلتين، بحيث لا يضيع السياق عند تبديل النماذج.
2. محوّل المزوّد (Provider Adapter): يتولى تحويل المدخلات والمخرجات ومعالجة الحالة، وفيه تُدمج القدرات المتقدمة الأصلية.
3. سجل القدرات: يسجّل بدقة ما يدعمه كل نموذج وكل نقطة نهاية من أدوات واستدلال ووسائط متعددة وSchema وتخزين مؤقت، وهو الذي يحدد التوجيه وخيارات الواجهة.

وعلى هذا الأساس، تُصان جودة الإطلاق من خلال ستة اختبارات توافق ومراقبة تفصيلية للتكاليف حسب البند. وفي مرحلة الاستدعاء العادي ومقارنة النماذج، يُنصح باستخدام APIYI عبر apiyi.com بمفتاح واحد لإتمام التحقق من عدة نماذج بسرعة، ثم تحديد أي المسارات تحتاج إلى تكييف أصلي بناءً على نتائج الاختبار.

📚 المراجع

1. OpenAI Function Calling: استدعاء الأدوات وcall_id وfunction_call_output
2. الرابط: developers.openai.com/api/docs/guides/function-calling

3. الوصف: الشرح المرجعي الموثوق لبروتوكول استدعاء الأدوات في Responses API

4. دليل ترحيل أحدث نماذج OpenAI: معاملات الاستدلال ومتطلبات الواجهة في سلسلة GPT-6

5. الرابط: developers.openai.com/api/docs/guides/latest-model

6. الوصف: قيود القيم المقبولة في reasoning.effort ومتطلبات Responses API

7. OpenAI Prompt Caching: نقاط توقف التخزين المؤقت وTTL

8. الرابط: developers.openai.com/api/docs/guides/prompt-caching

9. الوصف: آليات التخزين المؤقت الضمني والصريح

10. توافق Claude مع OpenAI SDK: نطاق الدعم والقيود في طبقة التوافق

11. الرابط: platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk

12. الوصف: الفروقات في strict والتخزين المؤقت وإدخال الملفات ودمج system وغيرها

13. Claude Extended Thinking: التفكير التكيفي وتوقيعات التفكير

14. الرابط: platform.claude.com/docs/en/build-with-claude/extended-thinking

15. الوصف: قواعد إعادة إرسال كتل thinking في استدعاءات الأدوات متعددة الجولات

16. المخرجات المنظمة والتخزين المؤقت في Claude: مخرجات JSON، الاستخدام الصارم للأدوات، cache_control

17. الرابط: platform.claude.com/docs/en/build-with-claude/structured-outputs
18. الرابط: platform.claude.com/docs/en/build-with-claude/prompt-caching

19. الوصف: القيود المنظمة وأنماط التخزين المؤقت

20. Gemini Interactions API والتوافق مع OpenAI: الواجهة الجديدة ومدخل التوافق

21. الرابط: ai.google.dev/gemini-api/docs/interactions-overview
22. الرابط: ai.google.dev/gemini-api/docs/openai

23. الوصف: هيكل steps وحالة الجلسة وتعيين المعاملات المتوافقة

24. توقيعات التفكير واستدعاء الأدوات والتخزين المؤقت في Gemini

25. الرابط: ai.google.dev/gemini-api/docs/thought-signatures
26. الرابط: ai.google.dev/gemini-api/docs/function-calling
27. الرابط: ai.google.dev/gemini-api/docs/caching

28. الوصف: الحفاظ على التوقيعات في نمط stateless، وبروتوكول الأدوات، والتخزين المؤقت الصريح

29. صفحات الأسعار الرسمية للشركات الثلاث

30. الرابط: developers.openai.com/api/docs/pricing
31. الرابط: platform.claude.com/docs/en/models/sonnet-5-5/overview
32. الرابط: ai.google.dev/gemini-api/docs/pricing
33. الوصف: مصدر بيانات جدول الأسعار في هذا المقال، تاريخ المراجعة 2026-11-13

المؤلف: فريق APIYI التقني
للتواصل التقني: نرحب بتواصلكم معنا عبر الصفحة الرئيسية لموقع APIYI، ولمزيد من المواد يمكنكم زيارة مركز الوثائق docs.apiyi.com