Skip to content

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

95.0 KB
Raw Blame

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 سه سازوکار تابآوری متمایز اما مرتبط دارد. هرکدام دامنه و هدف متفاوتی دارند. هنگام اشکالزدایی رفتار مسیریابی، آنها را از یکدیگر تفکیک کنید.

مدل سهلایه تابآوری

منبع: diagrams/resilience-3layers.mmd

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، errorCode
  • backoffLevel — شمارندهٔ عقبنشینی نمایی

وقفههای پیشفرض:

  • پایهٔ 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 جدید که سهمیه را نادرست گزارش میکند

  1. یک آرایهٔ قانون در statusRestatementRegistry (open-sse/config/upstreamStatusRestatement.ts) ثبت کنید. textMarkers را مختص provider نگه دارید؛ هرگز از عبارتهای عمومی انگلیسی که با CREDITS_EXHAUSTED_SIGNALS (open-sse/services/accountFallback.ts) تداخل دارند، دوباره استفاده نکنید.
  2. در صورت نیاز، قوانین طبقهبندی را در 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 جریان مییابد، اما هیچچیز بر اساس آن عمل نمیکند.
  3. تستهای واحدی مشابه 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).


همچنین ببینید