// tier: helix-primary · order 13
LLMProvider betalicense: TBD
Source
واجهة واحدة، 43 مزودًا — مع قواطع دوائر، وإعادة المحاولة، ومراقبة الصحة مدمجة.
LLMProvider هو وحدة Go عامة وقابلة لإعادة الاستخدام تحدد واجهة LLMProvider الموحدة بالإضافة إلى أنماط المرونة الإنتاجية المحيطة بها — قاطع الدائرة، ومراقبة الصحة، وإعادة المحاولة مع التراجع التدريجي، والتحميل الكسول — وتوفر 43 تنفيذًا ملموسًا للمزودين خلف عقد واحد، مع محول عام متوافق مع OpenAI ونموذج اكتشاف نماذج صادق دون أي حلول احتياطية مشفرة مسبقًا.
وحدة Go قابلة لإعادة الاستخدام تعرض واجهة LLMProvider الواحدة (Complete، CompleteStream، HealthCheck، GetCapabilities، ValidateConfig) بالإضافة إلى بدائيات تحمل الأخطاء — قاطع الدائرة، ومراقب الصحة، وإعادة المحاولة مع تراجع تدريجي مضاف إليه تذبذب زمني، والتحميل الكسول — عبر 43 محولًا للمزودين ومحول عام متوافق مع OpenAI. آمنة للخيوط.
LLMProvider هي طبقة التجريد التي يحتاجها كل خدمة مستهلكة لـ LLM لكنها نادرًا ما تُبنى بشكل جيد — تلك البنية التحتية غير الجذابة التي تفصل بين العرض التوضيحي والنظام الذي ينجو من مواجهة حركة المرور الحقيقية. فهي تحدد واجهة واحدة مدركة للقدرات — Complete، CompleteStream، HealthCheck، GetCapabilities، ValidateConfig — بحيث يستهدف كود التطبيق عقدًا واحدًا بالضبط بغض النظر عن أي من الـ 43 خلفية يجيب على الاستدعاء، ثم توفر التعزيزات التشغيلية التي تحول مكالمات المزودين الهشة إلى شيء يمكنك تشغيله في الإنتاج دون حبس أنفاسك. قاطع الدائرة ثلاثي الحالات (مغلق → مفتوح → نصف مفتوح) يغلف أي مزود بشكل شفاف — *بما في ذلك قناته البثية*، حيث يُحسب الدفق الفارغ بشكل صحيح كفشل — بحيث يمكن لخلفية واحدة سيئة السلوك أن تفتح القاطع وتمنع انهيار الخدمة بأكملها؛ ويدير CircuitBreakerManager المركزي كل القواطع دفعة واحدة. مراقب الصحة القابل للتكوين يتابع المزودين باستمرار عبر حالات الصحة/التدهور/الخلل/المجهول بناءً على فحوصات العتبات والفترات، بحيث يُلاحظ التدهور بدلاً من اكتشافه عند حدوث انقطاع. منطق إعادة المحاولة يضيف التراجع الأسي مع التذبذب الزمني في الأعلى، متخذًا قرارات مدركة للحالة — إعادة المحاولة للأخطاء التي تستحق إعادة المحاولة (429، 5xx، أعطال الشبكة العابرة)، دون إهدار الدورات على أخطاء 4xx أو سياق ملغى — مع تأخير محدد بحيث لا يمكن لعاصفة التراجع أن تخرج عن السيطرة. ونمط التحميل الكسول يؤجل بناء كل مزود حتى استخدامه الفعلي الأول — وهو خيار تصميم متعمد يجعل تسجيل جميع المزودين الـ 43 مجانيًا بشكل أساسي.
توفر الوحدة 43 حزمة مزود ملموسة بالإضافة إلى محول generic متوافق مع OpenAI ينفذ الواجهة الكاملة ضد *أي* نقطة نهاية /v1/chat/completions — مصادقة Bearer، وبث SSE مع معالجة صحيحة لـ [DONE] — بحيث يصبح المزود الذي ليس لديه حزمة مخصصة مواطنًا من الدرجة الأولى بمجرد توجيه المحول إلى URL الخاص به. تُحل بيانات الاعتماد في مكان واحد بالضبط (apikeys، باستخدام اصطلاح صارم ApiKey_<Provider>)، مما يغلق فئة الأخطاء الكاملة التي تقول "المفتاح المشفر يجتاز مجموعة الاختبارات، لكن المفتاح الحقيقي لم يُربط أبدًا، ويتعطل المنتج في الإنتاج" من مصدرها. اكتشاف النماذج متعمد وصارم في صدقه: فهو يستعلم واجهات برمجة التطبيقات للمزودين الفعليين خلف ذاكرة تخزين مؤقتة ذات مدة حياة، و— وفقًا للحوكمة — تم حذف طبقة الحل الاحتياطي المشفرة مسبقًا بالكامل. عندما يفشل الاكتشاف الفعلي، لا تُرجع LLMProvider *أي شيء* بدلاً من كتالوج قديم، بحيث لا يُعطى المتصل مطلقًا معرّف نموذج يبدو صالحًا ثم لا يمكن استدعاؤه. كل جزء من هذا البناء آمن للخيوط للاستخدام المتزامن.
المحتوى
تفشل المكالمات البسيطة لـ LLM في بيئة الإنتاج — حيث تفرض مقدمو الخدمة قيودًا على المعدلات، أو تتدهور الخدمة، أو تتوقف تمامًا، وقد يتسبب مزود واحد سيئ في إسقاط الخدمة بأكملها. تتغير فهارس النماذج، وتقدم القوائم المشفرة مسبقًا معرفات لم تعد صالحة. تجمع LLMProvider بين الواجهة ومرونة الأداء والاكتشاف الصادق بحيث يرث كل مستهلك القدرة على التحمل والموثوقية تلقائيًا دون جهد إضافي.
تختزل عملية "دمج مزود LLM" إلى خطوة واحدة فقط — إما تنفيذ واجهة واحدة، أو توجيه المحول العام إلى نقطة نهاية — ثم تغلف هذا المزود تلقائيًا وشفافًا في قواطع الدوائر ومراقبة الصحة وإعادة المحاولة مع تأخير متذبذب. تتوقف المرونة عن كونها شيئًا يعيد كل فريق اختراعه (بشكل سيئ، وتحت ضغط المواعيد النهائية، بعد أول انقطاع) لتصبح السلوك الافتراضي للمكتبة عبر جميع مزودي الخدمة البالغ عددهم ٤٣ مزودًا. تُكتب هندسة الموثوقية مرة واحدة، وتُختبر بدقة، ويرثها الجميع مجانًا بمجرد استيرادها.
- واجهة واحدة تدرك القدرات — دمج الاستكمال والبث ومراقبة الصحة والتحقق من القدرات والتكوين في عقد واحد تلتزم به جميع الخلفيات بنفس الطريقة.
- التغليف الشفاف لقواطع الدوائر — بما في ذلك البث. يحمي القاطع قناة
CompleteStream، وليس مجرد طلب/استجابة فحسب، ويعامل البث الفارغ على أنه الفشل الحقيقي الذي يمثله — مع إشعارات المستمعين الآمنة من التعطل وخارج القفل. - ٤٣ حزمة مزودات + محول عام متوافق مع OpenAI — تبقى الحزم المخصصة خفيفة، وأي بائع غير مدرج يتحدث
/v1/chat/completionsيعمل على الفور بمجرد توجيه المحول إليه. - سلطة اعتماد واحدة (
apikeys) — مكان واحد فقط يقرأ متغيرات البيئةApiKey_<Provider>، مما يلغي بشكل هيكلي عدم التطابق بين "الاختبارات الناجحة والمنتج المعطل" بدلًا من مجرد التحذير منه. - اكتشاف صادق للنماذج (دون احتياطي مشفر) — واجهات برمجة التطبيقات الحية للمزودين خلف ذاكرة تخزين مؤقتة ذات مدة صلاحية؛ عند الفشل، تُرجع
nil، ولا تقدم أبدًا فهرسًا قديمًا أو مُختلقًا يمنح معرفات غير قابلة للاستدعاء. - التهيئة الكسولة باستخدام
sync.Once— يُؤجل البناء إلى أول استخدام، لذا فإن تسجيل جميع المزودات البالغ عددها ٤٣ مزودًا لا يكلف شيئًا تقريبًا حتى يتم استدعاء أحدها فعليًا. - مكدس تحدي متعدد اللغات ومقاوم للخداع — أداة تشغيل حقيقية تختبر سلوك قواطع الدوائر والصحة وإعادة المحاولة عبر خمس لغات، محكومة باختبار الطفرات المزدوج (يجب أن يخرج الكود غير المتحور بصفر؛ ويجب أن يفرض الطفر المحقون الخروج برقم ٩٩)، لذا فإن المجموعة الناجحة تعني سلوكًا يعمل بشكل مؤكد.
- فشل المزودات المتتالي. يجب ألا يسحب مزود واحد غير مستقر خدمة بأكملها معه. تم حل هذه المشكلة باستخدام قاطع دوائر ثلاثي الحالات (مغلق → مفتوح → نصف مفتوح) يغلف أي مزود *وبثه* بشكل شفاف، ويفتح عند الفشل المستمر، ويتحقق من التعافي في الحالة نصف المفتوحة، ويتم تنسيقه مركزيًا بواسطة
CircuitBreakerManager. - الأخطاء العابرة وحدود المعدلات. تم حلها باستخدام تأخير أسي حساس للحالة مع تذبذب —
min(InitialDelay·Multiplier^(n-1), MaxDelay) ± jitter— بحيث تنتشر محاولات إعادة المحاولة بدلًا من التزامن في قطيع مدوٍ. يعيد المحاولة بالضبط لما يجب إعادة المحاولة له (٤٢٩، ٥٠٠، ٥٠٢، ٥٠٣، ٥٠٤، وأخطاء الشبكة)، ويرفض إهدار المحاولات على سياق ملغى أو أي خطأ من فئة ٤xx آخر. - التوسع مع العديد من المزودات المسجلة وغير المستخدمة. مع تسجيل ٤٣ مزودًا ولكن استخدام عدد قليل منها فقط في أي خدمة معينة، فإن البناء المتسرع سيكون هدرًا خالصًا. تم حل هذه المشكلة بالتهيئة الكسولة المحروسة بواسطة
sync.Once، بحيث لا تدفع المزودات التي تستدعيها فعليًا سوى تكلفة إعدادها. - منح معرفات نماذج غير صالحة. تم حل هذه المشكلة بحذف طبقة الاحتياطي المكتشفة مسبقًا بالكامل (وفقًا لـ CONST-036) وعدم إرجاع أي شيء عند فشل الاكتشاف المباشر — بالإضافة إلى نسخة دفاعية عند الإرجاع بحيث لا يتمكن المتصل من تعديل ذاكرة التخزين المؤقت أو التنافس مع قارئ آخر. تُفرض الصدق هيكليًا، وليس بالاتفاق.
- البث وصحة التزامن. يتمثل نمط الفشل الخفي في حدوث تعطل بين قفل القاطع واستدعاءات المستمعين. تم حل هذه المشكلة بالتقاط لقطات من المستمعين وإخطارهم خارج القفل ضمن مهلة زمنية مدتها ٥ ثوانٍ، وفك القفل قبل الإخطار عند إعادة الضبط — مع بناء كل مكون للاستخدام المتزامن واختباره بواسطة مجموعة
-race.
المحتوى
- Go (1.25.3) — تم اختياره لقدرته المتميزة على التوازي، والثنائيات الثابتة، ومكتبته القياسية القوية؛ حيث يحمل الوحدة، والواجهة، وكل أدوات المرونة، وجميع المحولات البالغ عددها ٤٣.
net/http(مكتبة قياسية) — بروتوكول HTTP خالٍ من التبعيات عن قصد: يدعم عملاء المزودين لكل مزود، والمحول المتوافق مع OpenAI، واستدعاءات الاكتشاف المباشرة، فلا توجد طبقة نقل خارجية تحتاج إلى تدقيق أو تصحيح.- logrus — تسجيل منظم ومدرك للمستويات حيث يحتاج المشغلون إلى وضوح الرؤية: داخل تحولات حالة قاطع الدائرة ومسار الاكتشاف.
- testify — يدير مجموعة الاختبارات، والأهم من ذلك، تثبيت الفروع المتحولة الذي يجعل نجاح التشغيل ذا معنى حقيقي.
- yaml.v3 — يحلل حزم التدويل والإعدادات بتنسيق يبقى قابلاً للتحرير البشري.
digital.vasic.models— الأنواع المشتركةLLMRequest/LLMResponse/ProviderCapabilities، محفوظة في مكان واحد بحيث يتحدث كل محول بنفس المفردات (تبعية تشغيل موثقة).- حزم داخلية —
circuit،health،retry،apikeys،discovery،providers/(٤٣ بائعًا +generic)، وi18n: سطح المرونة والتكامل مقسم إلى وحدات صغيرة قابلة للاختبار بشكل مستقل بدلاً من كونه كتلة واحدة ضخمة. .env+~/api_keys.sh(اتفاقيةApiKey_<Provider>) — مصدر واحد لا لبس فيه للحقيقة المتعلقة بالمصادقة، بحيث يتم توصيل المفاتيح بنفس الطريقة في الاختبارات وفي الإنتاج.- مجموعة أوامر Makefile للاختبار المتزامن (
-race -p 1) + مشغل التحدي — العمود الفقري لمكافحة الخداع: يكتشف كاشف السباق صحة التوازي، بينما يضرب مشغل التحدي السلوك الحقيقي عبر الفوضى، وهجمات الحرمان من الخدمة، والتوسع، والضغط، واكتشاف الخدمات المباشرة، وسيناريوهات عدم التعليق.
- الحالة: تجريبية. وحدة قابلة لإعادة الاستخدام ومستقلة؛ مستودع GitHub عام.
- الرخصة: لم تُحدد بعد. غير متسقة — يشير
doc.goإلى رخصة MIT بينما يوجد ملف LICENSE بنمط رخصة Apache-2.0 — تحقق قبل النشر. - LLMsVerifier هو المصدر الرئيسي الموثوق به لكاتالوج النماذج القياسي. يبدو ملف البيان
helix-deps.yamlقديمًا (يعلنdeps: []بينما تذكر الوثائق وجود تبعية لـdigital.vasic.models)؛ "المستوى الثاني (models.dev)" في الاكتشاف مخطط له كعنصر نائب، وليس نشطًا بعد.
مستوى الأولوية: Helix-رئيسي (مجموعة LLM للبنية التحتية — وحدة قابلة لإعادة الاستخدام ومستقلة). يأتي في المرتبة التالية بعد HelixTrack.