// سطح: helix-primary · سفارش 13
LLMProvider betaاجازهنامه: TBD
منبع
یک رابط، ۴۳ ارائهدهنده — با مدارشکن، تلاش مجدد و سلامت یکپارچه.
LLMProvider یک ماژول Go عمومی و قابل استفاده مجدد است که یک رابط یکپارچه LLMProvider به همراه الگوهای تابآوری عملیاتی — مدارشکن، پایش سلامت، تلاش مجدد با تأخیر تصاعدی، بارگذاری تنبل — تعریف میکند و ۴۳ پیادهسازی ارائهدهنده مشخص را پشت این قرارداد واحد ارائه میدهد، به همراه یک آداپتور عمومی سازگار با OpenAI و کشف مدل بدون جایگزینی سختکد شده.
یک ماژول Go قابل استفاده مجدد که یک رابط LLMProvider (Complete، CompleteStream، HealthCheck، GetCapabilities، ValidateConfig) به همراه مکانیزمهای تحمل خطا — مدارشکن، پایشگر سلامت، تلاش مجدد با تأخیر تصادفی، مقداردهی اولیه تنبل — روی ۴۳ آداپتور ارائهدهنده و یک آداپتور عمومی سازگار با OpenAI ارائه میدهد. این ماژول نخنسبت است.
LLMProvider همان لایه انتزاعی است که هر سرویس مصرفکننده LLM به آن نیاز دارد، اما تقریباً هیچکس آن را به درستی پیادهسازی نمیکند — همان لولهکشی ناخوشایند که یک دمو را از سیستمی که در برابر ترافیک واقعی دوام میآورد، متمایز میسازد. این ماژول یک رابط واحد با قابلیتهای مشخص — Complete، CompleteStream، HealthCheck، GetCapabilities، ValidateConfig — تعریف میکند تا کد برنامه تنها به یک قرارداد واحد وابسته باشد، فارغ از اینکه کدام یک از ۴۳ بکاند پاسخگوی درخواست باشد. سپس، مکانیزمهای مقاومسازی عملیاتی را ارائه میدهد که تماسهای شکننده با ارائهدهندگان را به چیزی تبدیل میکند که میتوان بدون نگرانی در محیط عملیاتی اجرا کرد.
یک مدارشکن سهحالته (بسته → باز → نیمهباز) به صورت شفاف هر ارائهدهندهای — *از جمله کانال استریم آن* — را در بر میگیرد، جایی که یک استریم خالی به درستی به عنوان شکست در نظر گرفته میشود. بدین ترتیب، یک بکاند ناپایدار میتواند مدار را باز کند و از سقوط کل سرویس جلوگیری نماید؛ یک CircuitBreakerManager مرکزی تمام مدارشکنها را به صورت همزمان رصد میکند.
یک پایشگر سلامت قابل تنظیم، ارائهدهندگان را به طور مداوم در حالتهای سالم، تخریبشده، ناسالم یا ناشناخته بر اساس آستانهها و بازههای زمانی بررسی میکند تا تخریب به جای کشف در زمان قطعی، پیش از وقوع شناسایی شود.
منطق تلاش مجدد، تأخیر تصاعدی را با تأخیر تصادفی ترکیب میکند و تصمیمات هوشمندانهای بر اساس وضعیت اتخاذ مینماید — خطاهای قابل تلاش مجدد (۴۲۹، ۵xx، خطاهای گذرا شبکه) دوباره امتحان میشوند، اما برای خطاهای ۴xx یا زمینه لغو شده، چرخهای تلف نمیشود. تأخیرها نیز محدود میشوند تا طوفان تلاش مجدد رخ ندهد.
الگوی مقداردهی اولیه تنبل، ساخت هر ارائهدهنده را تا اولین استفاده واقعی به تعویق میاندازد — انتخابی آگاهانه که ثبت تمام ۴۳ ارائهدهنده را عملاً بدون هزینه نگه میدارد.
این ماژول ۴۳ بسته ارائهدهنده مشخص به همراه یک آداپتور generic سازگار با OpenAI ارائه میدهد که رابط کامل را برای *هر* نقطه پایانی /v1/chat/completions پیادهسازی میکند — احراز هویت Bearer، استریم SSE با مدیریت صحیح [DONE] — به طوری که ارائهدهندهای بدون بسته اختصاصی، به محض اشاره آداپتور به URL آن، به عنوان یک شهروند درجه یک در نظر گرفته میشود.
اعتبارنامهها تنها در یک مکان (apikeys، با استفاده از قرارداد سختگیرانه ApiKey_<Provider>) حل میشوند و بدین ترتیب کل دستهای از باگها که در آن «کلید سختکد شده تستها را پاس میکند، اما کلید واقعی هرگز متصل نشده و محصول در محیط عملیاتی از کار میافتد» از مبدأ مسدود میشود.
کشف مدلها به طور عمدی و تقریباً لجوجانه صادقانه انجام میشود: این ماژول با استفاده از یک حافظه نهان TTL، APIهای ارائهدهندگان زنده را پرسوجو میکند و — مطابق با سیاستهای حاکمیتی — لایه جایگزین سختکد شده قدیمی به کلی حذف شده است. هنگامی که کشف زنده با شکست مواجه میشود، LLMProvider *هیچ چیز* بر نمیگرداند تا فراخواننده هرگز شناسه مدلی را دریافت نکند که ظاهراً معتبر است اما قابل فراخوانی نیست. تمام این اجزا برای استفاده همزمان طراحی شده و نخنسبت هستند.
محتوا
فراخوانیهای سادهٔ LLM در محیط عملیاتی شکست میخورند — ارائهدهندگان محدودیت نرخ اعمال میکنند، کیفیت خدمات را کاهش میدهند یا از دسترس خارج میشوند، و یک بکاند معیوب میتواند کل سرویس را با خود به زمین بزند. کاتالوگ مدلها تغییر میکند و فهرستهای سختکد شده شناسههایی را در اختیار تماسگیرندگان قرار میدهند که دیگر کار نمیکنند. LLMProvider واسط، الگوهای تابآوری و کشف صادقانه را متمرکز میکند تا هر مصرفکنندهای بهطور خودکار تحمل خطا و صداقت را به ارث ببرد.
این ابزار «ادغام یک ارائهدهندهٔ LLM» را به یک حرکت واحد تقلیل میدهد — کافی است یک واسط پیادهسازی کنید یا فقط آداپتور عمومی را به یک نقطهٔ پایانی نشانه بگیرید — و سپس آن ارائهدهنده را بهطور خودکار و شفاف در مدارشکن، پایش سلامت و تلاش مجدد با تأخیر تصادفیشده میپیچد. تابآوری دیگر چیزی نیست که هر تیمی آن را از نو اختراع کند (بد، تحت فشار ضربالعجل، پس از اولین قطعی)، بلکه به رفتار پیشفرض کتابخانه در همهٔ ۴۳ بکاند تبدیل میشود. مهندسی قابلیت اطمینان یک بار نوشته میشود، به دقت آزمایش میشود و بهطور رایگان در اختیار هر کسی قرار میگیرد که آن را وارد کند.
- یک واسط آگاه به قابلیتها — تکمیل، جریانسازی، سلامت، قابلیتها و اعتبارسنجی تنظیمات در یک قرارداد واحد ادغام شدهاند که هر بکاندی بهطور یکسان به آن پایبند است.
- پیچیدن مدارشکن بهصورت شفاف — از جمله جریانها. مدارشکن نهتنها از کانال
CompleteStreamبلکه از کل جریان محافظت میکند و یک جریان خالی را بهعنوان شکست واقعی تلقی میکند — با اطلاعرسانی به شنوندگان بهصورت بدون بنبست و خارج از قفل. - ۴۳ بستهٔ ارائهدهنده + یک آداپتور سازگار با OpenAI — بستههای اختصاصی سبک باقی میمانند و هر فروشندهٔ فهرستنشدهای که از
/v1/chat/completionsپشتیبانی کند، بهمحض اینکه آداپتور را به سمت آن نشانه بگیرید، کار خواهد کرد. - مرجع واحد اعتبارنامه (
apikeys) — دقیقاً یک مکان متغیرهای محیطیApiKey_<Provider>را میخواند و بهجای هشدار دربارهٔ ناسازگاری «آزمایشهای سبز، محصول معیوب»، آن را بهطور ساختاری حذف میکند. - کشف صادقانهٔ مدل (بدون جایگزین سختکد شده) — APIهای ارائهدهندگان زنده پشت یک حافظهٔ پنهان با عمر محدود؛ در صورت شکست،
nilبرمیگرداند و هرگز کاتالوگی منسوخ یا ساختگی ارائه نمیدهد که شناسههای غیرقابلفراخوانی توزیع کند. - آغاز تنبل با
sync.Once— ساخت در اولین استفاده به تعویق میافتد، بنابراین ثبت همهٔ ۴۳ ارائهدهنده تقریباً هیچ هزینهای ندارد تا زمانی که واقعاً یکی از آنها فراخوانی شود. - پشتهٔ چالش ضد بلوف و چندمنطقهای — یک اجراگر واقعی که رفتار مدارشکن، سلامت و تلاش مجدد را در پنج منطقه آزمایش میکند و با آزمایش جهش جفتشده کنترل میشود (کد بدون جهش باید با خروجی ۰ پایان یابد؛ یک جهش تزریقشده باید خروجی ۹۹ را مجبور کند)، بنابراین یک مجموعه آزمایش موفق بهطور قطعی به معنای رفتار کارآمد است.
- شکستهای آبشاری ارائهدهندگان. یک بکاند ناپایدار نباید کل سرویس را با خود به زمین بزند. این مشکل با یک مدارشکن سهحالته (بسته → باز → نیمهباز) حل شد که بهطور شفاف هر ارائهدهندهای — از جمله جریان آن — را میپیچد، در صورت شکست مداوم باز میشود، در حالت نیمهباز برای بازیابی کاوش میکند و توسط یک
CircuitBreakerManagerمرکزی هماهنگ میشود. - خطاهای گذرا و محدودیت نرخ. با تلاش مجدد نمایی آگاه به وضعیت بهعلاوهٔ تأخیر تصادفی حل شد —
min(InitialDelay·Multiplier^(n-1), MaxDelay) ± jitter— تا تلاشهای مجدد بهجای همگامسازی در یک گلهٔ شلوغ، پخش شوند. این مکانیزم دقیقاً آنچه را که باید دوباره تلاش کند (خطاهای ۴۲۹، ۵۰۰، ۵۰۲، ۵۰۳، ۵۰۴ و خطاهای شبکه) دوباره امتحان میکند و از تلاش برای یک زمینهٔ لغوشده یا هر خطای ۴xx دیگر خودداری میکند. - مقیاسبندی برای ارائهدهندگان ثبتشده اما بلااستفاده. با ثبت ۴۳ ارائهدهنده که تنها تعداد کمی از آنها در هر سرویس زنده هستند، ساخت مشتاقانه صرفاً اتلاف منابع خواهد بود. این مشکل با آغاز تنبل محافظتشده توسط
sync.Onceحل شد، بنابراین تنها ارائهدهندگانی که واقعاً فراخوانی میشوند هزینهٔ راهاندازی خود را پرداخت میکنند. - توزیع شناسههای مدل نامعتبر. با حذف کامل لایهٔ جایگزین کشف سختکد شده (بر اساس CONST-036) و برگرداندن هیچچیز در صورت شکست کشف زنده حل شد — بهعلاوه یک کپی تدافعی هنگام برگشت تا تماسگیرنده نتواند حافظهٔ پنهان را تغییر دهد یا با خوانندهٔ دیگری تداخل کند. صداقت بهطور ساختاری اعمال میشود، نه بر اساس قرارداد.
- جریانسازی + صحت همزمانی. حالت شکست ظریف، بنبست بین قفل مدارشکن و تماسهای بازگشتی شنوندگان آن است. این مشکل با عکسبرداری لحظهای از شنوندگان و اطلاعرسانی به آنها خارج از قفل و تحت یک مهلت ۵ ثانیهای حل شد، و همچنین با باز کردن قفل پیش از اطلاعرسانی در زمان بازنشانی — بهعلاوهٔ اینکه همهٔ مؤلفهها برای استفادهٔ همزمان ساخته شده و توسط مجموعه آزمایش
-raceتثبیت شدهاند.
محتوا
- Go (نسخهٔ ۱٫۲۵٫۳) — انتخابشده بهخاطر همزمانی درجهیک، باینریهای ایستا و کتابخانهٔ استاندارد قدرتمند؛ شامل ماژول، رابط، همهٔ عناصر تابآوری و هر ۴۳ آداپتور است.
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) + اجراکنندهٔ چالش — ستون فقرات ضدفریب: آشکارساز همزمانی درستی همزمانی را اثبات میکند و اجراکنندهٔ چالش رفتار واقعی را تحت هرجومرج، حملات DDoS، مقیاسبندی، فشار، کشف زنده و سناریوهای بدون تعلیق آزمایش میکند.
- وضعیت: بتا. یک ماژول قابل استفادهٔ مجدد و جداشده؛ مخزن GitHub عمومی است.
- مجوز: نامشخص. ناسازگاری وجود دارد —
doc.goمجوز MIT را اعلام میکند در حالی که فایل LICENSE به سبک Apache-2.0 است — پیش از انتشار، تأیید کنید. - LLMsVerifier منبع واحد بالادستی برای کاتالوگ مدلهای معتبر است. مانیفست
helix-deps.yamlقدیمی بهنظر میرسد (وابستگیها راdeps: []اعلام کرده در حالی که مستندات وابستگی بهdigital.vasic.modelsرا ذکر میکنند)؛ «طبقهٔ ۲ (models.dev)» در بخش کشف، یک طرح اولیه برنامهریزیشده است و فعال نیست.
طبقهٔ اولویت: Helix-اصلی (خوشهٔ LLM-زیرساخت — ماژول قابل استفادهٔ مجدد و جداشده). پس از HelixTrack قرار دارد.