الدالة نفسها، الواجهة الأمامية تحتاج إلى استدعاء أربعة نماذج: GPT-4o مسؤول عن الاحتياط، وDeepSeek يشغّل الاستدلال الرئيسي، وQwen يعالج النصوص الصينية الطويلة، وDoubao يتولى صياغات خدمة العملاء. أربع مجموعات SDK، وأربعة أنظمة مصادقة، وأربع وثائق. في الأسبوع الأول من الإطلاق، استهلكت محاذاة هذه الاختلافات وحدها يومَي عمل لشخصين.
هذا ليس مبالغة. لقد أحصينا: بعد دمج أربع شركات نماذج، تضخم الجزء المتعلق باستدعاء النماذج في كود الأعمال بنحو ثلاثة أضعاف. كل مرة تُبدّل فيها نموذجًا، عليك تعديل طريقة الاستدعاء ومنطق التحليل ومعالجة الأخطاء. والأمر الأكثر إزعاجًا هو أنه في كل مرة تُحدّث فيها الشركة المزوّدة الـ SDK، عليك إعادة الاختبار بالكامل. هذه المقالة تنظّم بشكل كامل الحفر التي وقعنا فيها والحل النهائي للبوابة الذي اعتمدناه، آملين أن تساعد الفرق التي لا تزال تصارع بين النماذج المتعددة.
أولًا: المصادقة — أربعة أنظمة، وأربع طرق كتابة
المصادقة هي أول ما اصطدمنا به. عائلة OpenAI تعتمد Bearer Token، ويكفي وضع Authorization: Bearer sk-xxx في ترويسة الطلب. أما Qwen فتتطلب توقيع AccessKey، وفي كل طلب يجب حساب HMAC باستخدام AK/SK، مع تجميع الطابع الزمني والسلسلة العشوائية. وDoubao يستخدم AK/SK مع طابع زمني، لكن خوارزمية التوقيع تختلف عن Qwen. وDeepSeek رغم توافقه مع صيغة OpenAI، فإن له base_url خاصًا به وربطًا خاصًا لأسماء النماذج، وطريقة التهيئة لا تتطابق تمامًا مع الـ SDK الرسمي.
النتيجة أن الكود مليء بـ if-else في كل مكان. كل مزوّد له نسخة client، وكل نسخة لها مجموعة إعدادات. وإدارة المفاتيح أكثر إزعاجًا — مفاتيح المزوّدين الأربعة مخزّنة في أربعة أماكن، وعند التدوير يجب التعديل في أربعة مواضع، وإذا فاتك واحد تحدث حادثة في الإنتاج.
لاحقًا وحّدنا الأمر في طبقة الدمج: نكشف للخارج مفتاح API واحدًا فقط، ونقوم داخليًا بترجمة البروتوكول. الطريقة تحديدًا هي أن طبقة الدمج تحتفظ بجدول توجيه للمزوّدين، وكل مزوّد يقابله محوّل مصادقة خاص به. جانب الأعمال يحصل على مفتاح واحد فقط، ويصل الطلب إلى طبقة الدمج، التي تجد المزوّد المقابل حسب اسم النموذج، وتُكمل التوقيع وإعادة التوجيه عبر المحوّل.
لاحقًا وحّدنا base_url إلى token8341 وجرّبناه، فمفتاح واحد يكفي لاستدعاء GPT-4o وClaude وGemini وDeepSeek وQwen وERNIE وDoubao، متوافقًا مع OpenAI SDK، ويكفي تغيير سطر واحد من base_url للتبديل. الأعمال القذرة للمصادقة أصبحت محجوبة خارج طبقة الدمج، ونظف كود الأعمال كثيرًا. وتحوّل تدوير المفاتيح إلى عملية في موضع واحد، فانخفضت تكلفة التشغيل والصيانة بدرجة كاملة.
ثانيًا: تقسيم بث SSE — أربع صيغ، وعرض واحد
تقسيم بث SSE هو الحفرة الثانية، وهو أخفى من المصادقة. في chunk الخاص بـ GPT-4o قد يكون delta.content مساويًا null، خصوصًا في أول chunk وآخر chunk، وإذا لم تتحقق الواجهة الأمامية من الفراغ قبل العرض، سيظهر undefined للحظة. وDeepSeek يضع usage في آخر chunk، كما أن بنية حقل usage لديه لا تطابق OpenAI تمامًا. وأنواع أحداث Qwen أكثر تفصيلًا، فهناك add وfinish وerror وغيرها من أنواع الأحداث، وبنية payload لكل حدث مختلفة. وعلامة النهاية في Doubao مختلفة أيضًا، إذ يستخدم حقل finish_reason خاصًا لتمييز نهاية البث.
الواجهة الأمامية تستقبل أربع صيغ، فيتشقق منطق العرض مباشرة. كان حلنا الأول هو التكيّف في الواجهة الأمامية، فكتبنا أربع دوال تحليل، لكن كل مرة نضيف نموذجًا كان علينا تعديل الواجهة الأمامية. لاحقًا غيّرنا إلى التطبيع في طبقة البوابة: التوحيد إلى بنية chunk الخاصة بـ OpenAI، وتصفية delta الفارغ مباشرة، واستخراج usage وتجميعه بشكل منفصل. القاعدة تحديدًا هي — تحويل استجابات البث من جميع المزوّدين إلى صيغة data: {"choices":[{"delta":{"content":"..."}}]}، وتوحيد النهاية بعلامة data: [DONE]، وإرجاع usage في آخر chunk بصيغة OpenAI.
الواجهة الأمامية تعرف صيغة واحدة فقط، ولا تحتاج لمعرفة من المتصل في الخلفية. هذا التغيير خفّض الكود المتعلق بالنماذج في الواجهة الأمامية من أكثر من 400 سطر إلى نحو 80 سطرًا، وعند إضافة نموذج جديد لا تحتاج الواجهة الأمامية لأي تعديل.
ثالثًا: رموز الأخطاء — أخطاء مخبأة داخل HTTP 200
درجة فوضى رموز الأخطاء تجاوزت التوقعات. نفس تحديد المعدل: OpenAI يُرجع 429 مع rate_limit_exceeded، وQwen يُرجع خطأ أعمال يحمل حقل code، وDoubao يحشر الخطأ ببساطة داخل body استجابة HTTP 200 — رمز الحالة 200، لكن داخل body يوجد حقل error. وDeepSeek في معظم الأوقات متوافق مع OpenAI، لكنه يعيد أحيانًا بنى أخطاء مخصصة.
المراقبة والتنبيه لا يمكن توحيدهما إطلاقًا. لا يمكنك كتابة قاعدة تقول "نبّه عند 429"، لأن بعض المزوّدين لا يُرجعون 429 عند تحديد المعدل. ولا يمكنك الاعتماد على رمز حالة HTTP فقط، لأن 200 من Doubao قد يكون خطأ.
أنشأنا في طبقة الدمج جدول ربط، يجمع رموز أخطاء المزوّدين في نظام أخطاء داخلي واحد: تحديد المعدل، انتهاء المهلة، فشل المصادقة، مراجعة المحتوى، الخدمة غير متاحة. منطق الربط تحديدًا هو — النظر أولًا إلى رمز حالة HTTP، ثم إلى error code داخل body، والحكم بالجمع بينهما. مثلًا إذا أرجع Doubao 200 لكن داخل body يوجد error، يُربط حسب error code؛ وإذا أرجع Qwen 400 مع business code، يُربط حسب code. قواعد التنبيه تُكتب مرة واحدة فقط، وعند التشخيص يُنظر إلى رمز الخطأ الأصلي.
حافظنا على هذا الجدول بنحو أكثر من 60 قاعدة، تغطي سيناريوهات الأخطاء الشائعة للمزوّدين الأربعة. بعد الإطلاق ارتفعت دقة التنبيه من نحو 60% إلى أكثر من 95%، واختفت الإنذارات الكاذبة تقريبًا.
رابعًا: إحصاء الاستخدام — أربعة أرقام لا تتطابق
اختلاف معايير إحصاء الاستخدام هو الأكثر سهولة في التغاضي عنه، لكنه سينكشف حتمًا عند التسوية المالية. عدّ token في GPT-4o يشمل system prompt، وtoken المخزّن المؤقت في DeepSeek يُسعّر منفصلًا، وQwen يحسب الإدخال والإخراج بشكل منفصل، ووحدة الفوترة في Doubao مختلفة أيضًا. عند التسوية المالية لا تتطابق الأرقام الأربعة، فلا يمكن حساب التكلفة الفعلية لكل نموذج إطلاقًا.
حل التجميع هو تسجيل model وinput_tokens وoutput_tokens وcache_hit لكل طلب في طبقة البوابة، وحفظها في قاعدة البيانات وفق معيار فوترة موحّد بالـ token. الطريقة تحديدًا هي — تسجّل البوابة وقت بداية الطلب ونهايته عند إعادة التوجيه، وتستخرج حقل usage من كل مزوّد من الاستجابة، وتحوّله إلى صيغة موحّدة. وبالنسبة للمزوّدين ذوي وحدات الفوترة المختلفة، يُجرى تحويل واحد في طبقة البوابة، بحيث تُحوّل جميعها إلى تكلفة لكل token.
بهذا، بصرف النظر عمّن هو المتصل في الأسفل، يمكن تسوية التكلفة في الجدول نفسه. لاحقًا بنينا أيضًا لوحة تكاليف على هذا الجدول، يمكن تفكيكها حسب النموذج وحسب خط الأعمال وحسب اليوم. في إحدى المرات اكتشفنا أن تكلفة خط أعمال معين ارتفعت فجأة بنسبة 40%، وتبيّن بعد الفحص أن استراتيجية التوجيه كانت تدفع كمية كبيرة من الطلبات إلى GPT-4o، وبعد تعديل التوجيه انخفضت التكلفة فورًا. لولا تجميع الاستخدام الموحّد، لما كان يمكن اكتشاف هذا النوع من المشاكل إطلاقًا.
خامسًا: البنية الرباعية لبوابة النماذج
أي الطبقات يجب أن تتحملها بوابة النماذج؟ تقسيمي هو أربع طبقات.
الطبقة الأولى: ترجمة البروتوكول. توحيد صيغ الطلب والاستجابة لكل مزوّد في واجهة متوافقة مع OpenAI. هذه الطبقة هي الوحيدة التي يتعامل معها كود الأعمال مباشرة، وهي مسؤولة عن ترجمة الطلبات بصيغة OpenAI القياسية إلى صيغ كل مزوّد، ثم ترجمة الاستجابات مرة أخرى.
الطبقة الثانية: التوجيه. اختيار النموذج حسب نوع المهمة، مثل النصوص الصينية الطويلة إلى Qwen، والكود إلى DeepSeek، والاحتياط إلى GPT-4o. يمكن جعل استراتيجية التوجيه قابلة للتكوين، وتدعم أبعادًا متعددة مثل نوع المهمة والأولوية والتكلفة. أضفنا أيضًا منطق التخفيض — إذا انتهت مهلة النموذج الرئيسي أو حُدّد معدله، يُنتقل تلقائيًا إلى نموذج الاحتياط.
الطبقة الثالثة: تجميع الاستخدام. فوترة وحصص موحّدة. استهلاك token لكل طلب وإصابة التخزين المؤقت ووقت الاستجابة تُسجّل في هذه الطبقة، وتُوفّر واجهة استعلام استخدام موحّدة للخارج.
الطبقة الرابعة: القابلية للمراقبة. السجلات وتتبع المسار وجمع رموز الأخطاء. كل طلب له trace_id، ويمكن تتبعه عبر السلسلة الكاملة من المدخل إلى المخرج. رموز الأخطاء تُربط بشكل موحّد في هذه الطبقة، وقواعد التنبيه تُكوّن في هذه الطبقة فقط.
كود الأعمال يستدعي واجهة الطبقة الأولى فقط، والطبقات الثلاث التالية شفافة بالنسبة له. فائدة ذلك هي — تبديل النموذج لا يتطلب تعديل كود الأعمال، وإضافة نموذج لا تتطلب تعديل كود الأعمال، وتعديل استراتيجية التوجيه لا يتطلب تعديل كود الأعمال. فريق الأعمال يحتاج فقط للاهتمام بـ"أريد استدعاء نموذج", والباقي يُترك للبوابة.
سادسًا: تنبيهات لتجنب الحفر
لا تستورد SDK الخاص بكل مزوّد مباشرة في كود الأعمال. بمجرد أن تُحدّث الشركة المزوّدة الواجهة أو أن تحتاج لتبديل النموذج، ستكون مساحة التعديل واسعة جدًا. رأينا فرقًا تستدعي SDK مباشرة في كود الأعمال، وعند تبديل النموذج لاحقًا عدّلت أكثر من 30 ملفًا، واختبرت أسبوعًا كاملًا قبل الإطلاق.
يومان إضافيان في طبقة الدمج يوفّران أسبوعين لاحقًا. نسبة العائد على الاستثمار هذه مُثبتة فعليًا عندنا — بعد إطلاق البوابة، إضافة نموذج جديد تحتاج فقط إلى إضافة محوّل في طبقة البوابة، وكود الأعمال بلا تعديل، ويمكن إتمام الدمج والاختبار في نصف يوم.
نصيحتان صغيرتان إضافيتان: الأولى أن تبدأ تجميع الاستخدام مبكرًا، ولا تنتظر حتى التسوية المالية لتكتشف أن الحساب غير ممكن؛ والثانية أن جدول ربط رموز الأخطاء يجب صيانته باستمرار، وأول شيء عند دمج مزوّد جديد هو استكمال ربط رموز الأخطاء.
المؤلف: صن هاوَران
تاريخ النشر: 9 نوفمبر 2026