Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
Resilience Guide (فارسی)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
OmniRoute سه سازوکار تابآوری متمایز اما مرتبط دارد. هرکدام دامنه و هدف متفاوتی دارند. هنگام اشکالزدایی رفتار مسیریابی، آنها را از یکدیگر تفکیک کنید.
1. قطعکننده مدار ارائهدهنده
دامنه: کل ارائهدهنده (برای مثال، glm، openai، anthropic).
هدف: توقف ارسال ترافیک به ارائهدهندهای که بهطور مکرر در سطح بالادستی/سرویس دچار خطا میشود.
پیادهسازی:
- کلاس اصلی:
src/shared/utils/circuitBreaker.ts - اتصال:
src/sse/handlers/chatHelpers.ts،src/sse/handlers/chat.ts - API وضعیت:
GET /api/monitoring/health - API بازنشانی:
POST /api/resilience/reset - پوششدهندهها:
open-sse/services/accountFallback.ts - جدول پایگاه داده:
domain_circuit_breakers
حالتها:
CLOSED— ترافیک عادی مجاز استDEGRADED— ترافیک همچنان مجاز است، اما افزایش خطاهای ارائهدهنده ردیابی میشود؛ پس از موفقیتهای کافی، یک آزمون اتصال معتبر، یا سپریشدن طولانیترین زمان نگهداریOPENبرای نوع آخرین خطا (مقدارcooldownByKindمربوط به آن، و در غیر این صورتresetTimeout، ضربدرmaxBackoffMultiplier، با حداقل یک دوره خنکسازی) بدون وقوع خطای جدید، بهCLOSEDبازمیگرددOPEN— ارائهدهنده موقتاً مسدود است؛ مسیریابی ترکیبی از آن صرفنظر میکندHALF_OPEN— مهلت بازنشانی سپری شده است؛ درخواست آزمایشی مجاز است
مقادیر پیشفرض قابل پیکربندی (open-sse/config/constants.ts، در داشبورد ← تنظیمات ← تابآوری در دسترس هستند):
| کلاس | ورود به حالت افت پس از | بازشدن پس از | مهلت بازنشانی |
|---|---|---|---|
| OAuth | 5 خطا | 8 خطا | 60s |
| API-key | 7 خطا | 12 خطا | 30s |
| محلی | محاسبهشده | 2 خطا | 15s |
degradationThreshold زمان ورود ارائهدهنده به حالت DEGRADED را کنترل میکند؛ failureThreshold زمان بازشدن مدار و صرفنظرکردن از ارائهدهنده را کنترل میکند. پروفایلهای ارائهدهنده محلی هنوز در صفحه تنظیمات تابآوری نمایش داده نمیشوند.
کدهای فعالسازی: فقط وضعیتهای سطح ارائهدهنده [408, 500, 502, 503, 504]. برای خطاهای سطح حساب (اغلب 401/403/429 — این موارد به خنکسازی یا قفلشدن تعلق دارند) مدار را فعال نکنید.
بازیابی تنبل: وقتی OPEN منقضی میشود، getStatus()، canExecute() و getRetryAfterMs() حالت را به HALF_OPEN بهروزرسانی میکنند. همین خواندنها (و خطای بعدی) یک حالت DEGRADED منقضیشده را به CLOSED بازمیگردانند. نیازی به تایمر پسزمینه نیست.
خنکسازی سراسری و اختیاری ارائهدهنده (دروازه پنجره)
لایه چهارم و اختیاری (PROVIDER_COOLDOWN_ENABLED، بهطور پیشفرض خاموش) حافظهای
بیندرخواستی از ارائهدهندگان خطادار را در
open-sse/services/providerCooldownTracker.ts نگه میدارد که هنگام تعیین اهداف ترکیبی
بررسی میشود تا درخواستهای ترکیبی متوالی، ارائهدهندهای را که بهتازگی
دچار خطا شده است، دوباره پیمایش نکنند. ورودیهای سطح ارائهدهنده از دروازه پنجره PROVIDER_PROFILES پیروی میکنند:
| پروفایل | فعالشدن پس از (providerFailureThreshold) |
در بازه (providerFailureWindowMs) |
خنکشدن بهمدت (providerCooldownMs) |
|---|---|---|---|
| OAuth | 10 |
15min |
5min |
| API key | 15 |
30min |
10min |
در مقادیر پایینتر از آستانه، ارائهدهنده در حال خنکشدن در نظر گرفته نمیشود؛ یک موفقیت،
پنجره را پاک میکند. در عوض، ورودیهای سطح اتصال (provider:connectionId)
پسروی نمایی minRetryCooldownMs → maxRetryCooldownMs را حفظ میکنند. بازنویسیها:
OMNIROUTE_PROVIDER_BREAKER_{OAUTH,API_KEY}_{FAILURE_THRESHOLD,FAILURE_WINDOW_MS,COOLDOWN_MS}.
محافظ رگرسیون: tests/unit/provider-cooldown-window-gate.test.ts.
2. وقفهٔ اتصال
دامنه: یک اتصال/حساب/کلید ارائهدهنده.
هدف: نادیدهگرفتن یک کلید معیوب، درحالیکه سایر اتصالهای همان ارائهدهنده همچنان به سرویسدهی ادامه میدهند.
پیادهسازی:
- علامتگذاری بهعنوان دردسترسنبودن:
src/sse/services/auth.ts::markAccountUnavailable() - انتخاب:
getProviderCredentials*در همان فایل - محاسبهٔ وقفه:
open-sse/services/accountFallback.ts::checkFallbackError() - تنظیمات:
src/lib/resilience/settings.ts
فیلدهای هر اتصال:
rateLimitedUntil— برچسب زمانی انقضای وقفهtestStatus: "unavailable"lastError،lastErrorType،errorCodebackoffLevel— شمارندهٔ عقبنشینی نمایی
وقفههای پیشفرض:
- پایهٔ OAuth: 5s
- پایهٔ کلید API: 3s
- 429 کلید API: هدرهای بالادستی
Retry-After/بازنشانی یا متن قابلتجزیهٔ بازنشانی را ترجیح میدهد - عقبنشینی:
baseCooldownMs * 2 ** failureIndex
محافظ ضد ازدحام ناگهانی: از طولانیشدن بیشازحد وقفه یا افزایش دوگانهٔ backoffLevel بر اثر شکستهای همزمان جلوگیری میکند.
خطاهای 429 مربوط به محدودیت همزمانی، از نردبان عقبنشینی بالا نمیروند. یک 429 که بدنهٔ آن از محدودیت همزمانی خبر میدهد ("too many concurrent requests"، "concurrency limit"، "parallel request limit"، عبارت GLM یعنی 并发数过高) به این معناست که حساب سالم اما مشغول است.
checkFallbackError() دلیل concurrency_limited را برمیگرداند: بلافاصله به اتصال بعدی تغییر مسیر دهید، این اتصال را برای مدت ثابت CONCURRENCY_LIMIT_COOLDOWN_MS (1s) یا مدت پیشنهادی بالادست در وقفه قرار دهید، backoffLevel را بدون تغییر نگه دارید و skipProviderBreaker را تنظیم کنید.
بدنهای که صراحتاً به سهمیه اشاره دارد همچنان اولویت دارد؛ بنابراین بدنهای که با الگوی سهمیه نیز تطابق داشته باشد، همچنان بهعنوان سهمیه تشخیص داده میشود. تشخیص: looksLikeConcurrencyLimit() در src/shared/utils/classify429.ts؛ حکم: open-sse/services/accountFallback/concurrencyLimit429.ts. تابع classify429() (یعنی FailureKind قطعکننده) بدون تغییر باقی میماند و همچنان این بدنهها را rate_limit تشخیص میدهد.
توقف محتوای جریان، حساب را وارد وقفه نمیکند. هنگامی که ناظر توقف محتوا
(open-sse/utils/streamHandler.ts) از جریانی که در زمان مقرر هیچ خروجی مدلی ارسال نکرده است
صرفنظر میکند، markAccountUnavailable() خطا را برای اتصال ثبت میکند، اما هیچ
وقفهای تنظیم نمیکند: توقف به همان درخواست تعلق دارد و اغلب ناشی از یک نوبت استدلال طولانی است که هنوز خروجیای ندارد. اپراتورها میتوانند با resilienceSettings.streamStallCooldown.enabled
دوباره این رفتار را فعال کنند (مقدار پیشفرض false است).
فریمهای استدلال، بودجهٔ توقف محتوا را از نو آغاز میکنند. یک مدل استدلالی ممکن است پیش از نخستین توکن قابلمشاهدهٔ خود
چندین دقیقه فکر کند: Claude فریمهای thinking_delta را بهصورت جریانی ارسال میکند که
متن تفکرشان ممکن است خالی باشد، و Responses API اقلام استدلال را یکی پس از
دیگری بهصورت جریانی ارسال میکند. isReasoningProgressFrame() (open-sse/utils/streamReadiness.ts) این
فریمها را تشخیص میدهد و ناظر بهجای لغو نوبت، با دریافت هرکدام بودجهٔ خود را از نو آغاز میکند.
این فریمها همچنان خروجی مدل محسوب نمیشوند؛ بنابراین نوبتی که تنها با استدلال پایان یابد همچنان
خالی گزارش میشود، و نوبتی که استدلال را متوقف کند و فقط ضربانهای حیات بفرستد، همچنان
ناظر را فعال میکند.
فریمهای دودویی reasoningContentEvent متعلق به Kiro که امضای غیرخالی دارند، این
فعالیت استدلالی را در سراسر اجراکننده بهصورت یک دلتای خالی reasoning_content حفظ میکنند. امضا
ارسال نمیشود. فراداده، فریمهای ناقص و امضاهای خالی، بودجهٔ
محتوا را از نو آغاز نمیکنند؛ مهلت مستقل جریان فعال و لغو از سوی کلاینت همچنان
اعمال میشوند (open-sse/executors/kiro/reasoning.ts).
حالتهای نهایی (وقفه نیستند):
banned— توسط تشخیص کلیدواژهٔ ممنوعیت/مسدودشدن حساب تنظیم میشود (به BAN_DETECTION مراجعه کنید)، و همچنین پس از سه رد متوالی هر درخواست از سوی بالادست (request_rejected، برای مثال OAuth مربوط به Anthropic با خطای 403 و پیام "Request not allowed" —open-sse/services/requestRejectedStreak.ts)؛ یک رد منفرد فقط اتصال را وارد وقفه میکندexpired(پس از تعداد محدودی تلاش مجدد به حالت نهایی منتقل میشود —EXPIRED_RETRY_MAX = 3همراه با عقبنشینی نمایی — تا خطاهای گذرای OAuth بتوانند پیش از غیرفعالشدن دائمی حساب، خودبهخود برطرف شوند)credits_exhausted
این حالتها تا زمانی که اطلاعات اعتبارسنجی تغییر کند یا اپراتوری آنها را بازنشانی کند، پایدار میمانند. حالتهای نهایی را با وضعیت وقفهٔ گذرا بازنویسی نکنید.
بازیابی تنبل: هنگامی که زمان rateLimitedUntil گذشته باشد، اتصال دوباره واجد شرایط میشود. پس از استفادهٔ موفق، clearAccountError() تمام فیلدهای خطا را پاک میکند.
دیوار مصرف OAuth مربوط به Claude: مسیر کماولویتتر + بازنشانی محدودیت نشست
دامنه: یک اتصال اشتراک Claude (OAuth). هر دو قابلیت بهصورت جداگانه برای هر
اتصال قابلفعالسازی هستند (ویرایش اتصال ← بخش Claude ← گزینههای lowPriorityMode / autoLimitReset در
providerSpecificData که هر دو بهطور پیشفرض خاموشاند) و معادل فرمانهای /low-priority و
/limit-reset در Claude Code هستند (قرارداد ارتباطی ثبتشده از Claude Code 2.1.263).
پیادهسازی:
- ماشین حالت + طبقهبندی پاسخ:
open-sse/services/claudeLowPriority.ts - کلاینت وضعیت/درخواست بازنشانی:
open-sse/services/claudeLimitReset.ts - قلاب اجراکننده (تزریق هدر + تلاش مجدد با همان حساب):
open-sse/executors/base.ts::execute() - ماندگارسازی فعالسازی اختیاری:
src/lib/providers/requestDefaults.ts::normalizeProviderSpecificData()
محرک: دیوار مصرف 5 ساعته — یک 429 که هدرهای آن شامل
anthropic-ratelimit-unified-status: rejected باشد و، هنگامی که حساب واجد شرایط است،
anthropic-ratelimit-unified-slow-offer: treatment را نیز داشته باشد. پیش از نخستین خطای 429 مربوط به دیوار،
چیزی ارسال نمیشود؛ یک 429 ناگهانی بدون هدرهای یکپارچه، مسیر عادی وقفه را طی میکند.
مسیر کماولویتتر (lowPriorityMode):
- در 429 دیوار محدودیت، اجراکننده پیشنهاد را میپذیرد و بلافاصله همان
حساب را با
anthropic-usage-limit: slowدوباره امتحان میکند؛ مسیر تا زمانanthropic-ratelimit-unified-resetاعلامشده (+60 ثانیه مهلت) فعال میماند و تمام درخواستها در آن بازه این هدر را حمل میکنند. 429 رهگیریشده هرگز بهhandleChatCoreنمیرسد، بنابراین اتصال در وضعیت cooldown قرار نمیگیرد و با اتصال دیگری جایگزین نمیشود. anthropic-ratelimit-unified-slow-statusدر پاسخهای بعدی:active/not_neededمسیر را حفظ میکنند؛slot_busy(429) یا یک529بهاندازهanthropic-ratelimit-unified-slow-retry-afterسرور منتظر میمانند (پیشفرض 20 ثانیه، محدودشده به 5–600 ثانیه، با نوسان تصادفی ±30٪) و دوباره تلاش میکنند؛ این فرایند بهanthropic-ratelimit-unified-slow-max-waitمحدود است (پیشفرض 20 دقیقه، محدودشده به 1 دقیقه–6 ساعت) — پس از آن مسیر پایان مییابد و یک دوره توقف 10 دقیقهای، پذیرش مجدد را مسدود میکند. زمان انتظار همچنین به زمان باقیمانده از مهلت شروع upstream خود درخواست (resolveFetchStartTimeout، بهطور پیشفرض 10 دقیقه) منهای حاشیه 5 ثانیه محدود میشود: بدون این محدودیت، حداکثر زمان انتظار پیشفرض 20 دقیقهای از عمر درخواست بیشتر میشد و sleep در میانه انتظار لغو میگردید و بهجای پایان ملایمmax_wait+ دوره توقف، یکTimeoutErrorنمایان میشد.weekly_limit/budget_exhausted/off/ineligible، جابهجایی پنجره 5 ساعته، یاineligible+anthropic-ratelimit-unified-overage-in-use: true(که آن را در هر وضعیتی باextra_usageپایان میدهد، زیرا مازاد مصرف پولی اکنون دیوار محدودیت را پوشش میدهد) مسیر را پایان میدهند؛ سپس پاسخ وارد مسیر عادی cooldown میشود.budget_exhaustedتا زمان بازنشانی بودجه اعلامشده (≤ 8 روز) به خاطر سپرده میشود.- بررسی دیوار محدودیت پس از تلاشهای مجدد درونتلاش اجراکننده که بر اثر 400 انجام میشوند (ویرایش context، محدودسازی thinking/effort، یادگیری خودکار پارامتر) اجرا میشود، بنابراین یک 429 دیوار محدودیت که فقط در یکی از آن تلاشهای مجدد ظاهر شود، همچنان رهگیری میشود و به مسیر cooldown نمیرسد.
- وضعیت برای هر اتصال در حافظه نگهداری میشود (راهاندازی مجدد، برای پذیرش دوباره یک 429 دیوار محدودیت اضافی هزینه دارد).
بازنشانی محدودیت نشست (autoLimitReset، هنگامی که هر دو روشن باشند پیش از مسیر امتحان میشود):
GET https://api.anthropic.com/api/oauth/usage?at_wall=1&skip_spend=1← بلوکjuniper_tide؛ وقتیarm: "reset"وavailable: trueباشند،POST https://api.anthropic.com/api/organizations/{orgUUID}/reset_rate_limitsبا{ "program": "juniper_tide" }(شناسه UUID سازمان ازproviderSpecificData.organizationUUID، با fallback راهاندازی اولیه).result: reset|not_limited← درخواست با سرعت کامل دوباره امتحان میشود (بدون هدر slow).already_used/not_offeredمقدارnext_available_atرا به خاطر میسپارند (پیشفرض یک هفته)؛ هر شکست باعث عقبنشینی 15 دقیقهای میشود. بازنشانی هفتهای یکبار است و همچنان جزو محدودیت هفتگی محسوب میشود.
محافظهای رگرسیون: tests/unit/claude-low-priority-mode.test.ts،
tests/unit/claude-limit-reset.test.ts، tests/unit/claude-low-priority-executor.test.ts.
وابستگی نشست (#7274)
دامنه: یک نشست کلاینت (هدر X-Session-Id / x-codex-session-id / x-omniroute-session) برای هر ارائهدهنده به یک اتصال سنجاق میشود.
هدف: نگهداشتن یک عامل چندمرحلهای (Claude Code، aider، عاملهای سفارشی) روی همان حساب در میان درخواستها، با کاهش از دست رفتن context میان حسابها و 429های مکرر شروع سرد در ارائهدهندگانی که وضعیت نشست بهازای هر حساب دارند.
پیادهسازی:
- تعیین TTL:
src/sse/services/sessionAffinityPin.ts::resolveSessionAffinityTtlMs() - انتخاب/ایجاد سنجاق:
src/sse/services/sessionAffinityPin.ts::selectSessionAffinityConnection() - استخراج هدر (عمومی، برای هر ارائهدهنده):
src/sse/services/auth.ts::extractSessionAffinityKey() - جدول سنجاق ماندگار:
sessionAccountAffinity(src/lib/db/sessionAccountAffinity.ts) - تنظیم:
sessionAffinityTtlMs(TTL سراسری برحسب میلیثانیه،0آن را غیرفعال میکند) —src/lib/db/settings.ts. نام آن توسط migration به نام124_generic_session_affinity_ttl.sqlازcodexSessionAffinityTtlMsمختص Codex تغییر یافته است؛ این migration هر TTL از پیش پیکربندیشده Codex را بهعنوان مقدار پیشفرض جدید منتقل میکند.
پیش از #7274، تابع resolveSessionAffinityTtlMs() برای هر ارائهدهندهای بهجز codex فوراً مقدار 0 را برمیگرداند، بنابراین تنظیم TTL (و هدرهای نشست) در هیچ جای دیگری اثری نداشتند، هرچند سازوکار سنجاقکردن و استخراج هدر از قبل مستقل از ارائهدهنده بودند. این اصلاح، آن بازگشت زودهنگام را حذف کرد؛ اکنون پس از تنظیم سراسری TTL روی مقداری بیشتر از 0، این مقدار بهطور یکسان برای همه ارائهدهندگان اعمال میشود.
سه هدر وابستگی نشست هرگز به upstream ارسال نمیشوند — اجراکنندهها بهجای عبور دادن هدرهای کلاینت، هدرهای upstream خود را از ابتدا میسازند؛ بنابراین این مقدار صرفاً یک شناسه همبستگی داخلی باقی میماند.
اجارههای انحصاری اتصال برای نشست مدیریتشده
دامنه: یک کلاینت/نشست HTTP مدیریتشده فعال، مالک یک اتصال واجد شرایط OmniRoute است.
هدف: فراهمکردن مالکیت انحصاری و ماندگار اتصال برای کلاینتهایی که در میان درخواستها به یک مرز سخت مسیریابی نیاز دارند. این با وابستگی نشست تفاوت دارد، زیرا وابستگی نشست یک ترجیح نرم برای تداوم است: یک اجاره انحصاری، وضعیت چرخهعمر را در SQLite ماندگار میکند، یکتایی سراسری مالک فعال و اتصال فعال را به اجرا درمیآورد و یک نسل منقضی را پیش از ارسال به ارائهدهنده رد میکند.
این قابلیت برای هر کلید API بهصورت اختیاری فعال میشود. یک کلید مدیریتشده باید scope مربوط به
lease:exclusive و یک فهرست صریح و غیرخالی allowedConnections داشته باشد. هر کلاینت HTTP میتواند
از endpoint چرخهعمر استفاده کند؛ هیچ نام کلاینت، user-agent، ارائهدهنده، روش OAuth یا مدلی لازم نیست.
اجاره مالک یک اتصال است، نه یک مدل؛ بنابراین تغییر مدل، تا زمانی که اتصال طبق شرایط عادی واجد صلاحیت
باقی بماند، binding را حفظ میکند. قواعد عادی مدل، سهمیه، سلامت، cooldown و allowlist همچنان
تعیینکننده هستند و ممکن است همان نسل را به اتصال آزاد و واجد شرایط دیگری منتقل کنند.
چرخهٔ حیات از POST /api/v1/session-leases با کنشهای JSON شامل acquire، renew و release استفاده میکند.
درخواستهای استنتاج مدیریتشده، مقدار مات X-OmniRoute-Lease-Owner و مقدار دقیق
X-OmniRoute-Lease-Generation را ارائه میکنند. مالک از vlo_ و سپس 43 نویسهٔ base64url تشکیل میشود؛ فقط
هش SHA-256 آن ذخیره میشود. هر حصار نهایی ارسال، شناسهٔ کلید API احراز هویتشده و
شناسهٔ اتصال فعال را نیز مقید میکند. سرآیندهای کنترل اجاره از گزارشها، تصویرهای لحظهای ذخیرهشدهٔ درخواست و
سرآیندهای اجراکنندهٔ بالادستی حذف میشوند.
اگر مسیریابی عادی دارای کاندیداهای مدیریتشدهٔ واجد شرایط باشد، اما هر کاندیدای آزاد توسط یک
اجارهٔ فعال خارجی اشغال شده باشد، OmniRoute وضعیت HTTP 429، کد lease-capacity-unavailable،
حالت waiting-for-capacity و یک Retry-After محدودشده و مبتنی بر نزدیکترین زمان انقضای مرتبط را برمیگرداند.
خالیبودن عادی مجموعهٔ واجد شرایط، رقابت بر سر اجاره محسوب نمیشود و معناشناسی خطای مسیریابی موجود خود را حفظ میکند.
سازوکارهای مرتبط همچنان مجزا باقی میمانند:
- اشغال نشست OAuth، توزیع نرم و محلیِ فرایند برای حسابهای OAuth است.
- سمافورهای حساب، مجوزهای همزمانی درخواست را اعطا میکنند و با تکمیل درخواست پایان مییابند.
- اجارههای انحصاری نشست مدیریتشده، مالکیت پایدار چرخهٔ حیات با حصار نسلی هستند.
3. قفل مدل
دامنه: سهتایی ارائهدهنده + اتصال + مدل.
دامنه کلید بر اساس وضعیت: وضعیتِ ناموفق تعیین میکند که قفل در کدام کلید نوشته شود
(resolveLockoutScope() در open-sse/services/accountFallback/exactModelLock.ts):
429/403/402— نشانه سهمیه یا مجوز دسترسی — خانواده سهمیه را قفل میکند: برای codex، کل دامنهcodex/spark(تمام مدلهایgpt-5*آن اتصال) و برای سایر ارائهدهندگان،getQuotaScopedModelForProvider().404مدل اصلی را قفل میکند (getModelLockKey()دامنهnot_foundرا محدود میکند).- هر وضعیت دیگری — خطاهای انتقال/سرور
5xxو پاسخ502ساختهشده توسط خود OmniRoute در اعتبارسنجی کیفیت — فقط سهتایی دقیق ارائهدهنده/اتصال/مدل را قفل میکند. یک جریان معیوب در یک مدل، شاهدی بر وضعیت سهمیه حساب نیست؛ پیش از این قاعده، یک پاسخ خالی درcodex/gpt-5.6-lunaتمام مدلهایgpt-5*آن اتصال را برای ۲ تا ۳۰ دقیقه (بهصورت تصاعدی) از مسیریابی حذف میکرد، درحالیکه سهمیه آن دستنخورده بود. - گزینه صریح
scopeاز سوی فراخواننده همیشه اولویت دارد (Antigravity مقدار"exact"را ارسال میکند).
هدف: جلوگیری از غیرفعالشدن کل اتصال هنگامی که فقط یک مدل در دسترس نیست یا با محدودیت سهمیه مواجه شده است.
مثالها:
- ارائهدهندگان دارای سهمیه بهازای هر مدل که 429 برمیگردانند
- ارائهدهندگان محلی که برای یک مدل موجودنیست 404 برمیگردانند
- خطاهای مجوز مختص ارائهدهنده برای حالت/مدل (برای مثال، حالتهای Grok)
پیادهسازی: open-sse/services/accountFallback.ts — lockModel()، clearModelLock()، getAllModelLockouts().
داشبورد دورههای انتظار مدل (v3.8.0)
رابط کاربری: تنظیمات ← دورههای انتظار مدل (src/app/(dashboard)/dashboard/settings/components/ModelCooldownsCard.tsx)
قفلهای فعال را همراه با این موارد فهرست میکند: ارائهدهنده، اتصال، مدل، دلیل، expiresAt. اپراتورها میتوانند یک مدل را بهصورت دستی از طریق کارت دوباره فعال کنند.
REST API:
GET /api/resilience/model-cooldowns— فهرستکردن قفلهای فعالDELETE /api/resilience/model-cooldowns— فعالسازی مجدد دستی. بدنه:{provider, connection, model}. احراز هویت: مدیریت.
مدیر دوره انتظار
رابط کاربری: نظارت ← مدیر دوره انتظار (src/app/(dashboard)/dashboard/resilience/cooldowns/).
یک صفحه برای تمام اتصالهایی که به دلیلی موقت از مسیریابی خارج شدهاند، بهجای
بازکردن صفحه هر ارائهدهنده. این صفحه دورههای انتظار اتصال، قفلهای مدل و وضعیتهای
نهایی را فهرست میکند؛ آنها را بهازای هر اتصال، برای یک مجموعه انتخابشده، یا برای تمام اتصالهای یک ارائهدهنده
پاک میکند؛ و پرکاربردترین قواعد دوره انتظار را ویرایش میکند: streamStallCooldown.enabled و دوره انتظار پایه
connectionCooldown برای OAuth / کلید API و حداکثر گامهای عقبنشینی (ذخیرهشده از طریق
PATCH /api/resilience). وضعیتهای نهایی (banned، expired، credits_exhausted)
فهرست میشوند، اما هرگز در اینجا پاک نمیشوند.
REST API (src/lib/resilience/cooldownManager.ts، احراز هویت: مدیریت):
GET /api/resilience/cooldowns[?provider=]— اتصالها همراه با وضعیت، زمان باقیمانده دوره انتظار، سطح عقبنشینی، نوع آخرین خطا و قفلهای مدل (بدون اطلاعات اعتبارنامه)POST /api/resilience/cooldowns— بدنه{connectionIds: string[]}یا{all: true, provider?}؛ مقدار{cleared, unchanged, skippedTerminal, lockoutsCleared}را برمیگرداند
رابط کاربری تنظیمات قفل + بازیابی با کاهش بر اثر موفقیت (v3.8.23)
قفل مدل از یک رفتار همیشهفعال و کدنویسیشده به قابلیتی کاملاً قابلپیکربندی و اختیاری تبدیل شد که کارت تنظیمات و مسیر بازیابی خودترمیمشونده مخصوص خود را دارد.
کارت تنظیمات: تنظیمات ← قفل مدل
(src/app/(dashboard)/dashboard/settings/components/ModelLockoutCard.tsx).
این کارت از ModelCooldownsCard فقطخواندنی بالا (که صرفاً قفلهای فعال را
فهرست میکند) متمایز است — کارت جدید پارامترها را پیکربندی میکند. مقادیر پیشفرض
در DEFAULT_MODEL_LOCKOUT_SETTINGS
(src/lib/resilience/modelLockoutSettings.ts) قرار دارند:
| تنظیمات | پیشفرض | معنا |
|---|---|---|
enabled |
false |
کلید اصلی — قفل مدل بهطور پیشفرض خاموش است. |
errorCodes |
[403, 404, 429, 502, 503, 504] |
وضعیتهای بالادستی که بهعنوان خطای در دامنه مدل محسوب میشوند. |
baseCooldownMs |
120_000 (۱۲۰ ثانیه) |
مدت اولیه قفل برای نخستین خطا. |
maxCooldownMs |
1_800_000 (۳۰ دقیقه) |
سقف دوره انتظار افزایشیافته. |
maxBackoffSteps |
10 |
حداکثر گامهای افزایش عقبنشینی نمایی. |
useExponentialBackoff |
true |
اینکه آیا خطاهای تکراری دوره انتظار را بهصورت نمایی افزایش دهند. |
تنظیمات از طریق مخزن معمول تنظیمات ماندگار میشوند و با طرحواره تنظیمات
تابآوری اعتبارسنجی میشوند؛ کارت مقادیر baseCooldownMs/maxCooldownMs
(با شرط maxCooldownMs ≥ baseCooldownMs) و maxBackoffSteps را در محدوده مجاز نگه میدارد.
بازیابی با کاهش بر اثر موفقیت: بازیابی صرفاً بر انقضای زمانسنج متکی نیست. یک پاسخ
سالم تعداد خطاهای مدل را کاهش میدهد تا مدلی که در میانه بازه بازیابی شده است،
پیش از موعد زمانسنج دیگر با افزایش دوره انتظار مواجه نشود (و قفل آن پاک شود). در یک
هدف ترکیبی موفق، open-sse/services/combo.ts تابع decayModelFailureCount()
(open-sse/services/accountFallback.ts) را فراخوانی میکند که مقدار ذخیرهشده
failureCount را نصف میکند (Math.floor(failureCount / 2))؛ وقتی این مقدار به 0
برسد، ورودی قفل بهطور کامل حذف میشود. تابع متناظر recordModelLockoutFailure()
در صورت وقوع خطاها در بازه افزایش، شمارش را افزایش میدهد (و دوره انتظار را تشدید میکند).
این کاهش بر اثر موفقیت، علاوه بر انقضای عادی زمانسنج است —
هرکدام از این مسیرها میتواند مدل را دوباره فعال کند.
وضعیت: قفلها در حافظه نگهداری میشوند (Mapهای مختص هر فرایند از
ModelLockoutEntry با کلید provider:connectionId:model و قفلهای دارای دامنه دقیق با کلید
provider:connectionId:exact:model) و در
DB ماندگار نمیشوند — با راهاندازی مجدد از بین میروند. تنظیمات ماندگار هستند؛ وضعیت
قفل فعال موقتی است.
۴. کنترل همزمانی Quota-Share (v3.8.36)
حسابهای اشتراکی (GLM، MiniMax و غیره) اغلب فقط حدود ۱ تا ۳ درخواست همزمان را
میپذیرند؛ عبور از این مقدار باعث خطاهای 429 و دورههای انتظار میشود. این مسئله در
ترکیبهای quota-share (qtSd/…) شدیدتر است، زیرا چند کلید API یک حساب بالادستی
را بهاشتراک میگذارند. سه لایه از سرازیر شدن درخواستها به یک حساب مشترک جلوگیری میکنند.
سقف همزمانی هر اتصال (max_concurrent)
هر اتصال ارائهدهنده میتواند یک سقف max_concurrent تعریف کند
(provider_connections.max_concurrent که در پنجره اتصال / API / DB تنظیم میشود).
برای نداشتن محدودیت، آن را خالی بگذارید. این همان تنظیم واحدی است که لایه سریالسازی
زیر را کنترل میکند — آن را برابر با همزمانی واقعی حساب قرار دهید (برای مثال، GLM حدود ۱ و MiniMax حدود ۲).
سقفهای همزمانی هر مدل (modelConcurrency)
یک اتصال همچنین میتواند در نگاشت rateLimitOverrides خود، سقفهای دقیق همزمانی
برای هر مدل تعریف کند:
{
"rateLimitOverrides": {
"maxConcurrent": 4,
"modelConcurrency": { "glm-5": 1, "glm-4.7": 3 }
}
}
آن را در پنجره اتصال (بازنویسی محدودیت نرخ → سقفهای همزمانی
هر مدل، یک model=cap در هر خط) یا از طریق
PATCH /api/providers/[id] با همان ساختار JSON تنظیم کنید. معناشناسی کلیدها:
- سراسری برای اتصال در برابر مختص مدل:
maxConcurrentهمچنان سقف مشترک و سراسری اتصال است. هنگامی که هر دو اعمال شوند، هر دو دروازه بهصورت اتمیک در همان دروازه مرکب اخذ میشوند (global → provider → account → model)؛ رفتار مؤثر تابع محدودیت سختگیرانهترِ قابلاعمال است. - تطبیق دقیق کلید مدل: کلید، رشته مدل ارسالشده به اجراکننده پس از
رفع مسیریابی است — معمولاً شناسه ساده مدل بالادستی
(
glm-5)، نه نام مستعار سمت کلاینت بهشکلprovider/model؛ (zai/glm-5باglm-5مطابقت ندارد). مقادیر باید اعداد صحیح مثبت باشند که سقف درخواستهای همزمان را مشخص میکنند. - صفبندی محلی، بدون کشف خودکار: درخواستهای مازاد با استفاده از
معناشناسی موجود صف/مهلت زمانی، بهصورت محلی در صف قرار میگیرند
(خطاهای پذیرش نوعدار
SEMAPHORE_TIMEOUT/SEMAPHORE_QUEUE_FULL). OmniRoute سیاست بالادستی را کشف یا استنباط نمیکند — فقط سقفهایی را دقیقاً اعمال میکند که اپراتور پیکربندی کرده است. اشباع شدن دروازه یک مدل هرگز ارائهدهنده را غیرفعال نمیکند و هیچگاه باعث قفل دائمی مدل نمیشود؛ رفتار بالادستی مربوط به 429/دوره انتظار/مسیر جایگزین همچنان پشتوانه مدیریت خطا باقی میماند. - دامنه هر اتصال و هر پردازه: سقفها برای هر اتصال پایگاه داده جداگانهاند و در حافظه نگهداری میشوند؛ بنابراین دو اتصال که از یک کلید API بالادستی یکسان استفاده میکنند، با یکدیگر هماهنگ نمیشوند.
- پیکربندینشده یعنی بدون تغییر: حذف نگاشت (یا خالی گذاشتن فیلد داشبورد) هیچ دروازه مدلی اضافه نمیکند. نمونه پیکربندی، بدون ادعای وجود محدودیتی همگانی برای ارائهدهنده:
glm-5=1
glm-4.7=3
سریالسازی درخواستهای Quota-share
هنگامی که یک ارسال quota-share، اتصالی را هدف قرار دهد که یک
max_concurrent مثبت تعریف کرده است، درخواستهای همزمان به آن حساب
از طریق یک سمافور مختص اتصال (کلید qsconn:<connectionId>) سریالسازی
میشوند: درخواستهای مازاد بهجای سرازیر شدن به حساب، در صف منتظر میمانند.
این سازوکار fail-open است — در صورت اشباع صف یا پایان مهلت زمانی، پردازش
بدون اسلات ادامه پیدا میکند تا هیچ درخواست قابلارسالی رد نشود.
آن را در تنظیمات → تابآوری → همزمانی هر اتصال در Quota-share
(resilienceSettings.quotaShareConcurrencyLimit.enabled، بهطور پیشفرض
فعال) تغییر دهید. بدون سقف max_concurrent، رفتار بدون تغییر باقی میماند.
دروازه مسیریابی quota-share (
selectQuotaShareTarget، DRR + P2C) خود از نوع fail-open است و فقط اولویت اتصالی را که به سقف رسیده کاهش میدهد — با استخری تکاتصالی نمیتواند محدودیت سخت اعمال کند؛ بنابراین این سمافور است که عملاً جریان انبوه درخواستها را مهار میکند.
تلاش مجدد آگاه از دوره انتظار برای ترکیبها
برای هر راهبرد ترکیبی (در صورت فعال بودن)، درخواستی که ممکن است یک خطای 429
را برای یک دوره انتظار گذرای کوتاه تثبیت کند، بهجای بازگرداندن 429 تا پایان آن
منتظر میماند و دوباره ارسال میشود — این رفتار پنجرههای TPM/RPM در کلاس
Gemini (حدود ۶۰ ثانیه retry-after) را در ترکیبهای چندمدلی پوشش میدهد؛ برای
مثال، زمانی که هر دو هدف یک ترکیب دومدلی به محدودیت نرخ مختص مدل برخورد کنند.
این رفتار با comboCooldownWait (enabled، maxWaitMs، maxAttempts،
budgetMs) در تنظیمات → تابآوری محدود میشود. این سازوکار هرگز برای
quota_exhausted (قفلشده تا نیمهشب) یا دلایل احراز هویت/یافتنشدن منتظر نمیماند.
#16319 · comboCooldownWait · pre-dispatch (attempts = 0)
all targets skipped + transient model lockout:
enabled ∧ 0 < waitMs ≤ maxWaitMs ∧ attempt < maxAttempts ∧ budgetLeftMs ≥ waitMs
→ wait → re-dispatch
wait = false → HTTP 429 rate_limit_error
retry_after / reset_at ← earliest transient lock expiry
quota_exhausted / auth_error / not_found / not_found_local:
no transient hint → HTTP 503 ALL_TARGETS_SKIPPED
5. کنترل پذیرش صف درخواست (v3.8.49 · مسئله #6593)
محدوده: صف محلی محدودسازی نرخ بهازای هر ارائهدهنده+اتصال (open-sse/services/rateLimitManager.ts،
با پشتوانه Bottleneck)، یک لایه پایینتر از سه سازوکار بالا.
maxWaitMs زمان انتظار در صف را محدود میکند؛ executionMaxWaitMs اجرای درخواست را محدود میکند.
این دو عمداً از هم جدا هستند و هیچیک بر دیگری اثر نمیگذارد.
resilienceSettings.requestQueue.maxWaitMs همان بودجه انتظار در صف است:
مدت انتظار برای یک جای خالی نزد ارائهدهنده و سپس ماندن در وضعیت QUEUED را
پوشش میدهد و تایمر آن درست در لحظهای پاک میشود که کار وضعیت QUEUED را ترک
کرده و اجرا را آغاز میکند (rateLimitManager.ts، wrappedFn). درخواستی که از
این مدت فراتر رود هرگز به سرویس بالادستی نمیرسد. مقدار پیشفرض 30000ms است که
توسط DEFAULT_REQUEST_QUEUE_MAX_WAIT_MS در
src/lib/resilience/settings.ts تأمین و توسط
tests/unit/ratelimit-admission-control-6593.test.ts تثبیت شده است؛ بنابراین
تغییر آن باعث شکست آن آزمون میشود، نه اینکه این بند بیسروصدا منسوخ باقی بماند.
resilienceSettings.requestQueue.executionMaxWaitMs مقداری است که Bottleneck
بهعنوان expiration کار دریافت میکند و تایمر آن فقط پس از اعزام آغاز میشود.
این مقدار یک محافظ نهایی برای اجراکنندههایی است که زمانپایان بالادستی مختص
خود را ندارند، و اگر زمانپایان آغاز واکشی خود اجراکننده طولانیتر باشد، تا آن
مقدار افزایش مییابد تا نتواند یک پاسخ سالمِ در حال پردازش را قطع کند. مقدار
پیشفرض 600000ms (10 دقیقه) است.
وارد کردن بودجه صف در expiration همان چیزی بود که پیشتر دروازههای
غیرافزایشی را در میانه اجرا از کار میانداخت — آنها بهطور موجه چند دقیقه پیش
از ارسال نخستین بایتها اجرا میشوند — و به همین دلیل است که انقضا با code: "RATE_LIMIT_EXECUTION_TIMEOUT" (HTTP 504) ارائه میشود، درحالیکه بودجه صف کد
زمانپایان صف را حمل میکند. هرکدام را از طریق
RATE_LIMIT_MAX_WAIT_MS / RATE_LIMIT_EXECUTION_MAX_WAIT_MS (متغیر محیطی) یا
داشبورد (تنظیمات ← تابآوری) بازنویسی کنید. هر دو هنگام نرمالسازی به بازه
1ms–24h محدود میشوند.
اولویت، برای هر دو: متغیر محیطی فقط مقدار پیشفرض را تأمین میکند. مقداری
که در resilienceSettings.requestQueue ماندگار شده باشد (از طریق داشبورد /
وصله API و ذخیرهشده در key_value) بر آن اولویت دارد، و
rateLimitOverrides.maxWaitMs / .executionMaxWaitMs مختص هر اتصال نیز بر آن
اولویت دارد. بنابراین تنظیم متغیر محیطی در استقراری که از قبل یک مقدار ماندگار
دارد، هیچ تغییری ایجاد نمیکند — در عوض، تنظیم ماندگار را پاک یا بهروزرسانی
کنید.
مدت حضور در صف توسط maxWaitMs محدود میشود؛ maxQueueDepth در ادامه مشخص
میکند چند فراخواننده میتوانند همزمان در صف باشند.
تلاشهای مجدد اعلامشده در بدنه: تنظیم آهنگ در برابر قفلشدن. بدنه یک پاسخ
429 میتواند زمان انتظار خودش را مشخص کند (RetryInfo.retryDelay در Gemini یا
متن «تلاش مجدد پس از N ثانیه») که updateFromResponseBody آن را میخواند.
انتظاری که در maxWaitMs اتصال بگنجد، برای تنظیم آهنگ است: محدودکننده مخزن خود
را برای آن مدت خالی میکند و فراخوانیهای در صف، هنگام پر شدن دوباره آن اعزام
میشوند. انتظاری طولانیتر از maxWaitMs چیزی نیست که صف بتواند تا پایان آن
منتظر بماند — Gemini برای سهمیه روزانه تمامشده با
retryDelay: "86399s" پاسخ میدهد. Retry-After بازپخششده در پاسخ 429
بازسازیشده (#16528) از قبل باعث میشود موتور جایگزین، مدل را برای آن بازه قفل
کند؛ اما مکث دادن محدودکننده برای همان بازه همچنان باعث میشود هر فراخوانیای
که زودتر به کلید برسد (برای مثال پس از بازنشانی تابآوری)، بهاندازه کل
maxWaitMs متوقف شود. وقتی چنین انتظاری از جزئیات نوعدار Google
RetryInfo (با منشأ google_rpc_retry_info) ناشی شود و محدودکننده کلید از قبل
به مدل محدود شده باشد (getLimiterKey را ببینید)، پاسخ 429 بهجای آن، در همان
اتصال به قفلشدن مدل تبدیل میشود (lockModelForLongBodyRetry در
open-sse/services/rateLimitManager/bodyRetryPause.ts، با سقف 24h) و
محدودکننده بدون مکث باقی میماند. انتخاب حساب با استفاده از isModelLocked()
از آن قفل عبور نمیکند؛ دروازه پیش از اعزام ترکیبی نیز برای مقصدهای متصل به آن
اتصال همین رفتار را دارد. در antigravity که محدودکننده آن بهازای هر خانواده
سهمیه تعریف میشود، قفل مانند دیگر قفلهای سهمیه آن روی همان مدل دقیق اعمال
میشود. اگر نام مستعاری به آن مدل نگاشت شده باشد، نامی که کارخواه درخواست کرده
نیز قفل میشود، زیرا آن بررسیها از نام درخواستشده استفاده میکنند؛ قفل دقیق
است (lockExactModel)، بنابراین نام مستعاری که از یک خانواده سهمیه antigravity
یا یک محدوده codex عبور کند، هرگز خودش را قفل نمیکند. یک راهنمای متنی، یک
retryDelay بدون نوع، یا محدودکنندهای که در کل اتصال مشترک است، مکث را حفظ
میکند. وقتی محدودکنندهای که مسیر 429 بهتازگی بازسازی کرده واقعاً مکث کند،
فراخوانندهای که زمان باقیماندهاش در صف پیش از پایان مکث تمام شود، بلافاصله
با کد زمانپایان صف رد میشود (checkLimiterPause)، نه اینکه تا پایان آن زمان
منتظر بماند؛ زمان پایان ثبتشده به لحظه پیش از ساختهشدن محدودکننده متصل است،
یعنی جایی که Bottleneck ساعت تازهسازی خود را آغاز میکند، و هر تغییر بعدی در
مخزن آن را فراموش میکند. این رفتار توسط
tests/unit/rate-limit-long-body-retry-lockout.test.ts و
tests/unit/rate-limit-body-retry-pause.test.ts پوشش داده شده است.
maxQueueDepth — سقف پذیرش اختیاری (جدید). resilienceSettings.requestQueue.maxQueueDepth
تعداد درخواستهایی را که میتوانند همزمان برای یک ارائهدهنده+اتصال در صف
باشند (و هنوز اعزام نشدهاند) محدود میکند. وقتی صف از قبل
maxQueueDepth درخواست داشته باشد، درخواست جدید با یک خطای نوعدار
code: "RATE_LIMIT_QUEUE_FULL"، پیش از آنکه اصلاً به limiter.schedule()
برسد، سریعاً رد میشود — بنابراین رد کردن کمهزینه است و پیش از هرگونه کار
پاییندستیِ فشردهسازی اعلان / ترجمه برای آن درخواست رخ میدهد. مقدار پیشفرض
0 = غیرفعال است و رفتار موجودِ صف نامحدود را حفظ میکند؛ بازه مجاز 0–100000
است. از طریق RATE_LIMIT_MAX_QUEUE_DEPTH (متغیر محیطی) یا
resilienceSettings.requestQueue.maxQueueDepth (وصله داشبورد/API) بازنویسی
کنید.
خود بررسی پذیرش یک تابع خالص است
(open-sse/services/rateLimitManager/admission.ts::checkQueueAdmission) تا
بدون یک محدودکننده واقعی Bottleneck نیز واحدآزماییپذیر باشد.
RFCای که #6593 را باز کرد، یک پرچم
bypassCompressionOnRateLimitنیز پیشنهاد داده بود. خط لولهٔopen-sse/services/compression/در این مخزن فشردهسازی prompt/context روی درخواست خروجی LLM است (chatCore.ts، حوالی بلوکresolveCompressionSettings/selectCompressionStrategy)، نه فشردهسازی پاسخ HTTP روی بدنههای 429 تولیدشده — هیچ مسیر کد متناظری برای یک پرچم bypass واقعی وجود ندارد. همچنین، آن مرحلهٔ فشردهسازی prompt در حال حاضر در خط لولهٔ درخواست پیش ازwithRateLimit()اجرا میشود؛ بنابراین، تغییر ترتیب برای رد کردن آن هنگام رد درخواست بهدلیل پر بودن صف، تغییری جداگانه و بزرگتر از محدودهٔ این مسئله است؛ این تغییر عمداً در اینجا پیادهسازی نشده و بهعنوان کاری آتی باقی مانده است، مشروط بر اینکه صرفهجویی CPU ارزش ریسک تغییر ترتیب را داشته باشد.
شبکهٔ ایمنی فعالسازی خودکار محدودیت نرخ و محافظت از اتصال (rateLimitProtection)
شبکهٔ ایمنی فعالسازی خودکار (resilienceSettings.requestQueue.autoEnableApiKeyProviders، پیشفرض true):
بهطور پیشفرض، OmniRoute محافظت صف محدودیت نرخ را بهصورت خودکار برای تمام اتصالهای فعال ارائهدهندگان مبتنی بر کلید API (getProviderCategory(provider) === "apikey") فعال میکند. این کار تضمین میکند که درخواستهای ورودی به کلیدهای API بالادستیِ حساس به نرخ، بهجای هجوم ناگهانی و ایجاد خطاهای 429 در بالادست، از طریق Bottleneck در صف قرار گرفته و مهار شوند. شبکهٔ ایمنی را میتوان از طریق متغیر محیطی RATE_LIMIT_AUTO_ENABLE بازنویسی کرد (false/0/off آن را غیرفعال میکند و true/1/on آن را اجباراً فعال میکند). این متغیر بر تنظیم ذخیرهشدهٔ داشبورد (Settings → Resilience / PATCH /api/resilience) اولویت دارد.
معنای rateLimitProtection برای هر اتصال:
محافظت محدودیت نرخ برای هر اتصال از طریق فیلد بولی rateLimitProtection روی اتصالهای ارائهدهنده پیگیری میشود (که در SQLite با نام rate_limit_protection ذخیره میشود):
- فعالسازی صریح (
rateLimitProtection === true): محافظت محدودیت نرخ، صرفنظر از دستهٔ ارائهدهنده یا فعال بودن شبکهٔ ایمنی فعالسازی خودکار، صراحتاً برای این اتصال فعال است. - غیرفعالسازی صریح (
rateLimitProtection === false): محافظت صریح را غیرفعال میکند، اما یک اتصال فعالِ مبتنی بر کلید API را از شبکهٔ ایمنی فعالسازی خودکار سراسری مستثنا نمیکند. درreconcileEnabledConnections(open-sse/services/rateLimitManager.ts)، مقادیرfalseوundefinedمعادلاند: فقطrateLimitProtection === trueبهعنوان بازنویسی صریح در نظر گرفته میشود. اگرrateLimitProtectionبرابر باfalseباشد (یا تنظیم نشده باشد)، یک اتصال فعالِ مبتنی بر کلید API همچنان با شرط فعالسازی خودکار مطابقت دارد و تحت محافظت محدودیت نرخ باقی میماند. - نبود امکان انصراف برای هر اتصال: در حال حاضر، اپراتور نمیتواند مشخص کند که «این اتصال فعالِ منفردِ مبتنی بر کلید API باید بدون محافظت صف محدودیت نرخ اجرا شود»، درحالیکه فعالسازی خودکار برای سایر اتصالها فعال باقی بماند. برای اجرای کامل اتصالهای مبتنی بر کلید API بدون صفهای محدودیت نرخ، شبکهٔ ایمنی باید بهصورت سراسری غیرفعال شود (
RATE_LIMIT_AUTO_ENABLE=falseیاresilienceSettings.requestQueue.autoEnableApiKeyProviders = false).
مسیرهای نوشتن پشتیبانیشده:
POST /api/rate-limits: مسیر نوشتن مدیریتی پشتیبانیشده برای تغییر وضعیتrateLimitProtectionیک اتصال ({ connectionId: string, enabled: boolean }). فراخوانی آن باenabled: trueمحافظت صریح را فعال میکند؛ فراخوانی آن باenabled: falseمحافظت صریح را حذف میکند (هرچند اگر فعالسازی خودکار روشن باشد، اتصالهای فعالِ مبتنی بر کلید API همچنان تحت پوشش شبکهٔ ایمنی سراسری باقی میمانند).PUT /api/providers/[id]: عمداًrateLimitProtectionرا نمیپذیرد یا تغییر نمیدهد (#11278). بهروزرسانی فرادادهٔ اتصال ارائهدهنده از طریقPUT /api/providers/[id]هرگز وضعیت ذخیرهشدهٔ محافظت محدودیت نرخ را تغییر نخواهد داد.
6. ناظر توان عملیاتی جریان کند (#9709)
محافظ اختیاری resilienceSettings.streamRecovery.throughputWatchdog یک بالادست را تشخیص میدهد که همچنان قطعهها را ارسال میکند، اما خروجی دستیار را با نرخی کمتر از نرخ پیکربندیشدهٔ خروجی مفید تولید میکند. این محافظ عمداً از مهلت عدم فعالیت متمایز است: ضربانهای حیات و فرادادهها هیچیک از تایمرها را بازنشانی نمیکنند و بهعنوان پیشرفت محسوب نمیشوند. همچنین با مهلت قطعی تلاش (#9153) متفاوت است؛ مهلتی که صرفنظر از کیفیت خروجی، همچنان سقف ایمنی مطلق باقی میماند.
ناظر پیش از آنکه بتواند عملیات را متوقف کند، به یک دورهٔ آمادهسازی و پس از آن یک پنجرهٔ لغزان کامل نیاز دارد. این ناظر دلتاهای متنی را از رویدادهای خروجی Chat Completions و Responses API میشمارد (بهعنوان یک تقریب محافظهکارانه بر مبنای بایت UTF-8)، رویدادهای صرفاً شامل میزان مصرف و رویدادهای خالی را نادیده میگیرد و تا زمانی که رویدادهای فراخوانی ابزار یا استدلال در جریاناند، ارزیابی را معلق میکند. این قابلیت بهطور پیشفرض غیرفعال است و میتوان آن را با STREAM_THROUGHPUT_WATCHDOG_ENABLED=true فعال کرد؛ پنجره، دورهٔ آمادهسازی، حداقل نرخ و حداقل خروجی قابلاندازهگیری، توسط لایهٔ عادی نرمالسازی تنظیمات تابآوری محدود میشوند.
هنگامی که این قابلیت فعال باشد، توقف ناشی از ناظر فقط بر تلاش فعال بالادست اعمال میشود. پیش از ارسال هر بایتی که برای کلاینت قابلمشاهده باشد، مسیر موجود بازیابی زودهنگام در همان حساب ممکن است تلاش را دوباره باز کند. پس از commit، جریان هرگز کورکورانه بازپخش نمیشود؛ فقط قرارداد امن و موجود ادامهٔ میانجریانی میتواند یک پسوند را به جریان متصل کند. نهاییسازی همچنان فقط یکبار انجام میشود، بنابراین حسابداری میزان مصرف و آزادسازی semaphore تکرار نمیشوند.
7. بازبیان وضعیت بالادست (خطاهای سهمیه با وضعیت نادرست)
دامنه: یک درگاه بالادست که اتمام موقت سهمیه را با وضعیت HTTP نادرست گزارش میکند.
هدف: اصلاح یک وضعیت گمراهکننده پیش از طبقهبندی، تا مصرفکنندگان پاییندست (موتور fallback، تجمیع combo و پاسخ ارائهشده به کلاینت) ماهیت واقعی و قابلتلاشمجدد خطا را مشاهده کنند.
برخی درگاهها اتمام موقت سهمیه را با یک وضعیت HTTP غیرقابلتلاشمجدد اعلام میکنند. agentrouter.org بهجای وضعیت استاندارد 429، وضعیت 403 (و گاهی 400) را با یک بدنهٔ چینی (用户额度不足 / 额度不足) برمیگرداند. کلاینتهایی مانند Claude Code، وضعیت 403 را دائمی در نظر میگیرند و نشست را متوقف میکنند؛ همچنین بدون اصلاح، موتور fallback آن را بهجای یک رویداد سهمیه، بهصورت AUTH_ERROR طبقهبندی میکند.
پیادهسازی:
- رجیستری + تطبیقدهنده:
open-sse/config/upstreamStatusRestatement.ts— فهرستی از قواعد مختص هر ارائهدهنده ({id, fromStatuses, toStatus, textMarkers, excludeMarkers, defaultRetryAfterMs}) که از طریقapplyStatusRestatement()تطبیق داده میشوند. - محل فراخوانی: بلوک
providerFailure:درopen-sse/handlers/chatCore.ts(حدود خط 3654)، بلافاصله پس از آنکهparseUpstreamError()یک پاسخ بالادست با وضعیت HTTP خطا (!providerResponse.ok) را تجزیه میکند و پیش از اجرای هرگونه طبقهبندی، تا همهٔ مصرفکنندگان پاییندست وضعیت اصلاحشده را مشاهده کنند. خطاهای تعبیهشده درون یک جریان SSE با وضعیت200، مسیر مجزا و دیرتری را برای تجزیهٔ جریان طی میکنند و در حال حاضر تحت پوشش این hook نیستند — این یک محدودیت شناختهشده است که هنوز برای وضعیت نادرست agentrouter لازم نیست (زیرا آن وضعیت بهصورت یک وضعیت HTTP خطا ظاهر میشود). - واجد شرایط بودن برای تلاش مجدد: وضعیت
429درRETRY_AFTER_ELIGIBLE_STATUSES(open-sse/services/combo/unavailableRetryGate.ts) قرار دارد؛ بنابراین یک خطای بازبیانشده، بهجای آنکه بهشکل یک403بیاثر ظاهر شود، دارای یک پنجرهٔ واقعی تلاش مجدد است. - مقدار مصنوعی
60sبرایdefaultRetryAfterMs(upstreamStatusRestatement.ts) فقط چیزی است که پاسخ بازبیانشده به کلاینت اعلام میکند؛ این مقدار، مدت cooldown/lockout داخلی خود اتصال نیست — آن مدت بهطور جداگانه توسط سازوکاری تعیین میشود که عملاً خطای بازبیانشده را مدیریت میکند (افزایش تدریجی زمان انتظار در Connection Cooldown، §2، با مقدار پایهٔ3sبرای ارائهدهندگان مبتنی بر API-key؛ یا Model Lockout، §3، برای ارائهدهندگان سهمیهٔ مختص مدل مانند agentrouter). روتر ممکن است از نظر داخلی زودتر از پنجرهٔ 60s اعلامشده به کلاینت، واجد شرایط تلاش مجدد شود — این حاشیهٔ اطمینان عمدی است، نه یک باگ.
خطاهای دائمی (无权访问模型 در agentrouter — عدم دسترسی به این مدل) هرگز بازبیان نمیشوند: excludeMarkers حتی در صورت تطبیق textMarkers نیز قاعده را وتو میکند؛ بنابراین خطا وضعیت اصلی خود را حفظ میکند و هیچ چیزی آن را تا ابد مجدداً امتحان نمیکند. قاعدهٔ متناظر طبقهبندی ارائهدهنده
(agentrouter-model-access-denied در open-sse/config/providerErrorRules.ts:
reason: "auth_error"، scope: "model"، با cooldown پایهٔ اعلامشدهٔ 6h) توسط checkFallbackError (open-sse/services/accountFallback.ts)
پیش از بازگشت زودهنگام عمومی FORBIDDEN برای دستهٔ apikey بررسی میشود و تحت کنترل honorsRuleLockScope(provider) قرار دارد (#10334 — در حال حاضر از طریق allowlist با نام HONORS_RULE_LOCK_SCOPE_PROVIDERS در providerErrorRules.ts، منحصراً برای agentrouter فعال است). cooldown اعلامشدهٔ 6h این قاعده بهصورت fallbackResult.baseCooldownMs منتقل میشود، اما همچنان وارد مسیر ازپیشموجود lockout سهمیهٔ مختص مدل (lockModelIfPerModelQuota() /
recordModelLockoutFailure()، که بهجز منبع cooldown توسط #10334 تغییری نکرده است) میشود: مانند تمام lockoutهای دیگر مدل، مقدار آن تا mlSettings.maxCooldownMs تنظیمشده توسط اپراتور (مقدار پیشفرض 1_800_000ms / 30min) کاهش مییابد و دلیل lockout ذخیرهشده همان مقدار سختکدشدهٔ ازپیشموجود "forbidden" باقی میماند، نه مقدار "auth_error" این قاعده — فقط مدت cooldown بهصورت سرتاسری رعایت میشود، نه رشتهٔ دلیل. خود اتصال فعال باقی میماند؛ مدلهای همسطح روی همان اتصال تحت تأثیر قرار نمیگیرند.
خطاهای بازبیانشدهٔ سهمیه (额度不足) در محیط production با یک قانون provider تطبیق پیدا میکنند
(agentrouter-user-quota-exhausted: reason: "quota_exhausted"، scope: "connection"، بدون cooldown اعلامشدهٔ مختص به خود — مقدار پیشفرض scaled
backoff در persistence layer اعمال میشود). از #10334 به بعد، scope در
ProviderErrorRuleMatch بهصورت end-to-end مصرف میشود، اما فقط برای providerهای
موجود در allowlist با نام HONORS_RULE_LOCK_SCOPE_PROVIDERS (providerErrorRules.ts —
در حال حاضر فقط "agentrouter"، با کنترل از طریق honorsRuleLockScope()). برای همهٔ
providerهای دیگر، scope دقیقاً مانند قبل از #10334 صرفاً جنبهٔ اطلاعرسانی دارد.
checkFallbackError دامنهٔ قانون تطبیقیافته را بهصورت
fallbackResult.ruleScope ارائه میکند؛ isAgentrouterConnectionQuotaScope()
(src/sse/services/auth.ts) guard مشترکی است که تأیید میکند یک
ruleScope واقعاً برای درنظرگرفتن بهعنوان سیگنالی سراسری در سطح connection و
خودبازیاب ایمن است (scope برابر با "connection"، reason برابر با
quota_exhausted، هرگز permanent نیست و هرگز creditsExhausted نیست — دفاعی
در برابر قانونی احتمالی در آینده که scope برابر با "connection" را با یک وضعیت
دائمی account جفت کند). دو مصرفکننده آن را فراخوانی میکنند:
- Persistence (
markAccountUnavailable()،src/sse/services/auth.ts): بهجای افتادن در شاخهٔ lockout بهازای هر model برای passthrough-provider (مقدارpassthroughModelsبرای agentrouter برابر باtrueاست → تابعhasPerModelQuota()مقدارtrueرا برمیگرداند)، یک cooldown موقت connection اعمال میکند —testStatus: "unavailable"بههمراهrateLimitedUntil، و هرگز یک وضعیت پایانی (credits_exhausted/banned/expired) اعمال نمیشود — تا connection پس از پایان cooldown خودبهخود بازیابی شود، نه اینکه به reset دستی credential نیاز داشته باشد. این کار برای connectionهایی باdisableCooling: trueانجام نمیشود (#2997): آن opt-out در عوض به lockout بهازای هر model منتقل میشود (یک موازنهٔ مستندشده — comment کد در بالای این شاخه را ببینید). - مسیریابی combo در همان request (
applyComboTargetExhaustion()،open-sse/services/combo/targetExhaustion.ts): همان guard، connection را در Set درونحافظهایexhaustedConnectionsبا کلید${provider}:${connectionId}علامتگذاری میکند. این کار فقط target باقیماندهای در همان request را رد میکند که خودش از قبل دقیقاً همانconnectionIdرا در object مربوط به target خود داشته باشد (getExhaustedTargetSkipReason()،open-sse/services/combo/comboPredicates.ts، شرطif (provider && connectionId)پیش از lookup درexhaustedConnections) — یک combo سادهٔ model-list که در آن targetهای همسطح هیچconnectionIdتثبیتشدهای از خود ندارند و یکی از آنها فقط در هر dispatch از header با نامX-OmniRoute-Selected-Connection-Idدر response resolve میشود، هرگز با آن کلید تطبیق پیدا نمیکند. برای این حالت رایج، محافظت واقعی در برابر استفادهٔ مجدد یک leg باقیمانده از accountای که همین حالا exhaust شده، این Set نیست — بلکه persistence layer بالا است (اکنونrateLimitedUntilمربوط به connection در آینده قرار دارد) که با جلوگیری همین guard از ثبتtransientRateLimitedProvidersبرای failure ترکیب میشود (بخش «طراحی دومرحلهای» و comment کد در شاخهٔisAgentrouterConnectionQuotaScopeدرtargetExhaustion.tsرا ببینید): با علامتگذارینشدن آن Set، مجوز اجباریallowRateLimitedConnectionدرcombo.ts(open-sse/services/combo.ts:1005-1013،:2734-2738) برای legهای باقیماندهٔ provider فعال نمیشود؛ بنابراین filter مربوط بهrateLimitedUntilدر انتخاب credential (src/sse/services/auth.ts:1238) بهطور معمول رعایت میشود و یک leg باقیمانده یا یک connection متفاوت و همچنان واجد شرایط agentrouter را انتخاب میکند، یا با نبود credential قابلاستفاده شکست میخورد — و بهاجبار دوباره به connectionای که این شاخه همین حالا وارد cooldown کرده است بازنمیگردد.
طراحی دومرحلهای: بازبیان status، سپس classification
بازبیان status (upstreamStatusRestatement.ts) و قوانین classification مربوط به
provider (open-sse/config/providerErrorRules.ts،
providerRuleRegistry) registryهای جداگانهای هستند که هر دو بر اساس provider id
و text markerها کلیدگذاری میشوند، اما در محلهای متفاوت اجرا میشوند و اهداف متفاوتی
دارند: restatement در ابتدای chatCore.ts، HTTP status را بازنویسی میکند؛
قوانین classification درون checkFallbackError()
(open-sse/services/accountFallback.ts)، reason مربوط به fallback و scope
قفل (model / provider / connection) را انتخاب میکنند.
قوانین classification فقط برای providerهایی که در allowlist با نام
FULL_TEXT_RULE_PROVIDERS در providerErrorRules.ts فهرست شدهاند، متن کامل
error را میبینند (که برای تطبیق markerهای body مانند 额度不足 لازم است) — در
حال حاضر فقط "agentrouter". برای هر provider دیگر در catalog داخلی،
checkFallbackError فقط error ساختاریافته ({code, type}) را به
getProviderErrorRuleMatch میدهد؛ این داده برای قوانین مبتنی بر
header/status/code کافی است، اما markerهای متنی body را نمیبیند.
helper با نام resolveRuleMatchBody() این انتخاب را انجام میدهد: متن کامل error
برای providerهای موجود در allowlist و error ساختاریافته برای سایر موارد. افزودن یک
provider داخلی به FULL_TEXT_RULE_PROVIDERS یک opt-in صریح بهازای هر provider
است — این سازوکار وجود دارد تا مسیر پیشفرض برای هر provider خارج از فهرست،
بایتبهبایت بدون تغییر باقی بماند.
scope یک قانون (model / provider / connection) یک opt-in جداگانه از
FULL_TEXT_RULE_PROVIDERS است: checkFallbackError فقط آن را بهصورت
fallbackResult.ruleScope ارائه میکند و مصرفکنندگان downstream تنها برای
providerهای موجود در allowlist با نام HONORS_RULE_LOCK_SCOPE_PROVIDERS در همان
فایل، آن را چیزی بیش از یک label اطلاعرسانی در نظر میگیرند (gated via honorsRuleLockScope() — در حال حاضر فقط "agentrouter"). برای آگاهی از اینکه
یک تطبیق با scope: "connection" پس از قرارگرفتن provider در آن allowlist عملاً
چه میکند، بخش «خطاهای بازبیانشدهٔ سهمیه» در بالا را ببینید.
#11104 — قوانین اعلامشده توسط اپراتور هر دو allowlist را دور میزنند. یک اپراتور میتواند
در زمان اجرا از طریق settings.providerErrorRules
(open-sse/config/providerErrorRules.ts::setOperatorProviderErrorRules)
و بدون ویرایش این فایل، یک قانون مختص هر provider تعریف کند. مشروطکردن یک قانون اپراتور به
FULL_TEXT_RULE_PROVIDERS/HONORS_RULE_LOCK_SCOPE_PROVIDERS — allowlistهایی
که برای محافظت از رفتار پیشفرض قوانین کاتالوگ داخلی در نظر گرفته شدهاند —
مکانیسم تنظیمات را برای همه providerها بهجز مواردی که از قبل در آنجا
فهرست شدهاند، بلااستفاده میکند؛ زیرا تعریف قانون، خود بهمنزلهٔ opt-in صریح
اپراتور است. resolveRuleMatchBody() و honorsRuleLockScope() هر دو ابتدا
hasOperatorRuleForProvider() را بررسی میکنند: providerای که دارای قانون اپراتور است،
متن خام خطا را دریافت میکند و scope تعریفشدهٔ آن رعایت میشود، صرفنظر از
اینکه در یکی از allowlistها نیز وجود داشته باشد یا نه.
شکاف شناختهشده — برای HTTP 400 هرگز به providerRuleRegistry مراجعه نمیشود.
شاخهٔ BAD_REQUEST در checkFallbackError وضعیت 400 را بهطور کامل
از طریق آرایههای الگوی خودش (MODEL_ACCESS_DENIED_PATTERNS،
CONTEXT_OVERFLOW_PATTERNS و موارد دیگر در accountFallback.ts) طبقهبندی میکند و پیش از
رسیدن به شاخهٔ configuredRule/getProviderErrorRuleMatch در بالای آن بازمیگردد.
یک قانون کاتالوگ داخلی (یا قانون اپراتور) با status: 400 از نظر نحوی
معتبر است، اما هرگز اجرا نخواهد شد. در حال حاضر هیچ قانون موجودی 400 را هدف قرار نمیدهد،
بنابراین چیزی در محیط production تحت تأثیر نیست — اما یک قانون 400 در آینده ابتدا نیازمند
تغییر این شاخه است؛ تغییری که از افزودن یک قانون گستردهتر است (زیرا 400 را برای همهٔ
providerهایی که از قبل به رفتار آرایههای الگو متکی هستند دوباره طبقهبندی میکند)
و خارج از محدودهٔ افزودن یک قانون برای یک provider منفرد است.
افزودن یک gateway جدید که سهمیه را نادرست گزارش میکند
- یک آرایهٔ قانون در
statusRestatementRegistry(open-sse/config/upstreamStatusRestatement.ts) ثبت کنید.textMarkersرا مختص provider نگه دارید؛ هرگز از عبارتهای عمومی انگلیسی که باCREDITS_EXHAUSTED_SIGNALS(open-sse/services/accountFallback.ts) تداخل دارند، دوباره استفاده نکنید. - در صورت نیاز، قوانین طبقهبندی را در
open-sse/config/providerErrorRules.ts(providerRuleRegistry) ثبت کنید تا محدودهٔ قفل درست انتخاب شود (connectionبرای سهمیهٔ سراسری حساب وmodelبرای خطاهای مختص هر مدل). این مرحله در production فقط برای providerهایی اثر میگذارد که قوانینشان به متن کامل خطا نیاز دارد (نشانگرهای body): شناسهٔ provider را در همان فایل بهFULL_TEXT_RULE_PROVIDERSاضافه کنید — در غیر این صورتcheckFallbackErrorفقط خطای ساختیافتهٔ{code, type}را به قانون تحویل میدهد و یک قانون مبتنی بر متن body هرگز با ترافیک واقعی مطابقت نخواهد داشت. قوانینی که صرفاً بر اساسstatus/headersمطابقت مییابند (مانند قوانین Opencode یا Minimax) به این opt-in نیاز ندارند. جدا از این، اگر قانونscope: "connection"را تعریف میکند و هدف، یک cooldown واقعی در سراسر connection بههمراه ردکردن combo در همان درخواست است (نه صرفاً یک برچسب اطلاعرسانی)، شناسهٔ provider را در همان فایل بهHONORS_RULE_LOCK_SCOPE_PROVIDERSاضافه کنید — این همان چیزی است که مصرف به سبکisAgentrouterConnectionQuotaScope()را درmarkAccountUnavailable()(src/sse/services/auth.ts) وapplyComboTargetExhaustion()(open-sse/services/combo/targetExhaustion.ts) کنترل میکند؛ بدون آن،scopeهمچنان از طریقfallbackResult.ruleScopeجریان مییابد، اما هیچچیز بر اساس آن عمل نمیکند. - تستهای واحدی مشابه
tests/unit/upstream-status-restatement.test.tsوtests/unit/agentrouter-error-rules.test.tsاضافه کنید (از جمله guardهای not-permanent / not-creditsExhausted و — اگر provider به allowlist نیاز دارد — تستی که تأیید کندresolveRuleMatchBody()فقط برای همان provider متن کامل را بازمیگرداند).
هیچ تغییری در chatCore.ts، classifyError یا combo لازم نیست.
قفل مبتنی بر باکت خروجی (#10880)
providerهای موجود در EGRESS_BUCKETED_LOCK_PROVIDERS (خانوادهٔ opencode) بهعنوان
upstream مبتنی بر باکت IP در نظر گرفته میشوند (سطح رایگان opencode بر اساس IP باکتبندی
میشود، نه بر اساس حساب — به #9611 مراجعه کنید): وضعیت 429 که بهصورت quota_exhausted
یا rate_limit_exceeded طبقهبندی شده باشد، برای هر connection از خانوادهٔ موجود در
allowlist که آخرین IP خروجی شناختهشدهٔ آن با IP connection ناموفق مطابقت دارد، cooldown
اعمال میکند؛ این کار پیش از آن انجام میشود که rotation بتواند آنها را امتحان کند
— و از N-1 فراخوانی upstream با شکست تضمینشده جلوگیری میکند (همان الگوی
#10460/#10525). rate_limit_exceeded عمداً گنجانده شده است: در مسیر
markAccountUnavailable قوانین مختص opencode هرگز مطابقت پیدا نمیکنند (هیچ header/bodyای
به checkFallbackError تحویل داده نمیشود و opencode در FULL_TEXT_RULE_PROVIDERS
نیست)، بنابراین یک 429 که body آن حاوی متن سهمیهٔ اشتراک ("monthly usage limit
reached") باشد، پیش از آنکه قانون status_429 اصلاً بررسی شود، توسط fallback متن سهمیه
(buildSubscriptionQuotaFallback، accountFallback.ts؛ cooldown یکساعته) بهصورت
quota_exhausted طبقهبندی میشود — درحالیکه یک 429 فاقد متن سهمیه (محدودسازی نرخ ساده)
از طریق قانون status_429 بهصورت rate_limit_exceeded طبقهبندی میشود و همچنان
برای خانوادهٔ IP cooldown اعمال میکند. برای یک provider موجود در allowlist، محدودیت نرخ
مبتنی بر IP همان سیگنال سهمیهٔ تمامشده است. محدودیتهای واقعی:
- حداکثر تلاش: قفل، آخرین
egress_ipشناختهشدهٔ اتصال را ازproxy_logsپیدا میکند (بازهٔ 24h، همگام، بدون کش). در صورت سرد بودن کش (IP خروجی هرگز بررسی نشده باشد) یا نبود هیچ ردیفی → اتصال ناموفق همچنان توسط این شاخه وارد دورهٔ انتظار میشود (مانند وضعیت فعلی ثبت میشود)، فقط هیچ اتصال همخانوادهای قفل نمیشود. - هرگز نهایی نیست: دورهٔ انتظار یک پنجرهٔ سهمیهای تمدیدشونده است
(
testStatus: "unavailable")، و هیچگاه از یک سیگنال در سطح IP، وضعیت دائمی استنتاج نمیشود. اتصالهایdisableCoolingاین شاخه را کاملاً نادیده میگیرند. - ریزدانگی قفل برای خانوادهٔ موجود در فهرست مجاز تغییر میکند: این یک تغییر
دامنه است، نه صرفاً یک بهینهسازی برای اتصالهای همخانواده. opencode یک ارائهدهندهٔ
passthroughModelsاست، بنابراین پیش از این شاخه، خطای 429 باعث قفلشدن در سطح هر MODEL میشد؛ اکنون باعث ورود اتصال به دورهٔ انتظار میشود — حتی برای اپراتوری که تنها یک اتصال و هیچ اتصال همخانوادهای ندارد. این همان ریزدانگیای است که جدول قوانین opencode از قبل صحیح اعلام کرده است (scope: "connection",providerErrorRules.ts)؛ اما تاکنون هرگز رعایت نشده، زیرا opencode درHONORS_RULE_LOCK_SCOPE_PROVIDERSنیست. این شاخه دورهٔ انتظار اتصال ناموفق +backoffLevelآن را مستقیماً مینویسد، مشابه شاخهٔ agentrouter با دامنهٔ اتصال، و سپس بازمیگردد — بلوک در سطح مدل و مسیر عمومی پایینتر هرگز اجرا نمیشوند. - شامل Combo: مانند شاخهٔ agentrouter، این دامنه عمداً تنزل
persistUnavailableState/isComboرا که یک فراخوانندهٔ combo برای خطای 429 اعمال میکند نادیده میگیرد. قفلشدن در سطح مدل شکل ضعیفتری از این دامنه نیست، بلکه واحد اشتباهی است: هیچ چیزی دربارهٔ IP با سهمیهٔ تمامشده بیان نمیکند، بنابراین چرخش combo به ازای هر اتصال همخانواده همچنان یک فراخوانی با شکست قطعی را هدر میدهد. - ایمنی اتصالهای همخانواده: اتصال همخانوادهای که از قبل در وضعیت نهایی (banned/credits_exhausted) قرار دارد یا هماکنون دورهٔ انتظار طولانیتری دارد، هرگز بازنویسی نمیشود.
- فهرست مجاز انحصاری: گسترش
EGRESS_BUCKETED_LOCK_PROVIDERSیک تصمیم صریح مالک است؛ نه سیمکشی عمومی (الگوی #10334/#10419). کوئری اتصالهای همخانواده بهجای تکرار همان فهرست مجاز بهصورت یک لیترال SQL، همان فهرست را bind میکند؛ بنابراین گسترش آن همچنان تغییری یکخطی باقی میماند. - چرخش IP خروجی، در هر دو جهت: پنجرهٔ جستوجو (24h) بسیار بزرگتر از TTL کش IP خروجی (5 min) است، بنابراین «آخرین IP شناختهشده» تاریخچه است، نه وضعیت فعلی. اگر پراکسی یک اتصال درون این پنجره چرخیده باشد، قفل ممکن است یک IP واقعاً مشترک را از دست بدهد (IP ثبتشده، IP جدید و دارای سهمیه است) — و بهطور متقارن ممکن است اتصال همخانوادهای را وارد دورهٔ انتظار کند که از آن زمان از IP دارای سهمیهٔ تمامشده فاصله گرفته است. حالت دوم بهاندازهٔ یک پنجرهٔ دورهٔ انتظار برای آن اتصال همخانواده هزینه دارد؛ هر دو بهعنوان محدودیتهای حداکثر تلاشِ یک جستوجوی مبتنی بر تاریخچه پذیرفته شدهاند.
- هزینه: دو پیمایش محدودشده روی
proxy_logs(فیلترشده بر اساس پنجره از طریقidx_pl_timestamp)، فقط با بسامد خطای 429. بدون ایندکس جدید (migration 134، اصل YAGNI). روی یک کپی با اندازهٔ متوسط از پایگاه دادهٔ ترافیک واقعی اندازهگیری شده است؛ یک نمونهٔ پرترافیک بهتناسب، ردیفهای بیشتری را در همان پنجره نگه میدارد.
سایر قابلیتهای تابآوری
- ۲۰ راهبرد مسیریابی (اولویت، وزندار، نوبتی، انتقال زمینه، ابتدا پُرکردن، p2c، تصادفی، کماستفادهترین، بهینهسازیشده برای هزینه، آگاه از بازنشانی، پنجره بازنشانی، ظرفیت مازاد، وزندهیشده بر اساس سهمیه، کاملاً تصادفی، خودکار، lkgp، بهینهسازیشده برای زمینه، بهینهسازیشده برای کش، ادغام، خط لوله) — به AUTO-COMBO.md مراجعه کنید.
- مسیریابی آگاه از بازنشانی (v3.8.0) — اتصالها را بر اساس زمان بازنشانی سهمیه اولویتبندی میکند.
- تنزل حالت پسزمینه —
background: trueدر Responses API همراه با هشدار به حالت همگام تنزل داده میشود. - تشخیص پویای محدودیت ابزارها — هنگام رسیدن به محدودیت تعداد ابزار، ارائهدهندگان را بهتدریج کنار میگذارد.
- مسیر جایگزین اضطراری — توسط
OMNIROUTE_EMERGENCY_FALLBACKکنترل میشود؛ اپراتورها میتوانند بدون راهاندازی مجدد، آن را از صفحه Feature Flags بازنویسی کنند.
اشکالزدایی
- پاسخ ترکیب وزندار
503 all_targets_cooling_downاست (Retry-Afterتنظیم شده وdiagnostics.excludedهمهٔ هدفها را با یکی از دلایلmodel_lockout/circuit_open/provider_cooldown/unavailableفهرست میکند) ← استخر پیکربندی و متصل شده است، اما هر هدف صرفاً بهدلیل یک زمانسنج تابآوری کنار گذاشته شده است؛ هشدار[COMBO] Weighted selection: every target excluded before dispatch — …دلایل و ثانیههای باقیمانده را مشخص میکند. خطای404 no_executable_targetsاز همان ترکیب به این معناست که هیچ زمانسنج تابآوریای دخیل نبوده است (چیزی برای اجرا وجود ندارد، یا بررسی دسترسپذیری برای همهٔ حسابها ناموفق بوده است). این منطق درopen-sse/services/combo/pinRecovery.tsو بر پایهٔ موارد کنارگذاری جمعآوریشده درtargetResolution.tsساخته شده است. - همهٔ کلیدهای یک ارائهدهنده نادیده گرفته میشوند ← هم وضعیت قطعکنندهٔ مدار و هم
rateLimitedUntil/testStatusهر اتصال را بررسی کنید. - ارائهدهنده پس از بازهٔ بازنشانی بهطور دائمی کنار گذاشته میشود ← کد بهجای
getStatus()/canExecute()مستقیماًstateخام را میخواند. - یک کلید ناموفق است، اما بقیه باید کار کنند ← وقفهٔ اتصال را به قطعکنندهٔ مدار ترجیح دهید.
- فقط یک مدل ناموفق است ← قفل مدل را به وقفهٔ اتصال ترجیح دهید.
- وضعیت باید خودکار بازیابی شود، اما نمیشود ← وجود مهر زمانی در آینده و مسیر خواندنی را بررسی کنید که وضعیت منقضیشده را تازهسازی میکند. وضعیتهای دائمی به تغییرات دستی نیاز دارند.
اثرانگشت TLS و پنهانکاری
پنهانکاری مختص ارائهدهنده (JA3/JA4، CCH، مبهمسازی) بهصورت جداگانه مستند شده است — docs/security/STEALTH_GUIDE.md را ببینید (در git؛ در /docs کامپایل نشده است).
آزمایش تابآوری (فاز ۸ · بلوک C)
فراتر از تستهای واحد منطق تابآوری، سه تست، زمان اجرا را تحت شرایط واقعی فشار/خرابی بررسی میکنند (همگی یکپارچهسازی/شبانه — هیچکدام PRها را مسدود نمیکنند):
| تست | کارکرد | اجرا |
|---|---|---|
| آشوب | یک گره بالادستی جعلی، تأخیر/بازنشانی/مهلتپایانیافته/503 واقعی تزریق میکند؛ تأیید میکند که قطعکننده مدار باز میشود/بازیابی میشود و checkFallbackError خطای 503 را بهعنوان بازگشت قابلبازیابی طبقهبندی میکند. |
RUN_CHAOS_INT=1 npm run test:chaos |
| رشد هیپ | حدود ۵۰۰ جریان بهازای هر createSSEStream تحت --expose-gc؛ اگر هیپ فراتر از سقف رشد کند، ناموفق میشود (محافظ OOM شماره 3069). |
npm run test:heap |
| آزمون ماندگاری k6 | بار مداوم روی /api/monitoring/health؛ آستانههای p95/خطا. |
k6 run tests/load/k6-soak.js (شبانه) |
هماهنگسازی توسط .github/workflows/nightly-resilience.yml انجام میشود (cron + dispatch). در
test:integration پیشفرض، تستهای آشوب و هیپ خودکار رد میشوند (بدون RUN_CHAOS_INT/--expose-gc).
همچنین ببینید
- راهنمای معماری — معماری سیستم و جزئیات داخلی
- راهنمای کاربر — ارائهدهندگان، ترکیبها و یکپارچهسازی CLI
- موتور ترکیب خودکار — امتیازدهی ۱۶ عاملی و بستههای حالت