Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
808 lines (548 loc) · 61.6 KB

TROUBLESHOOTING.md

File metadata and controls

808 lines (548 loc) · 61.6 KB
Raw

Troubleshooting (Azərbaycan dili)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 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

İstifadəçilər üçün: Sürətli həllər axtarırsınız? Aşağıdakı Qısa arayışa baxın.

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 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 üçün ümumi problemlər və həllər.

Qısa İstinad

OmniRoute ilə yenicə tanış olursunuz? Buradan başlayın — bunlar problemlərin 90%-ni həll edir:

Bunu görürəm Mənası Nə etməli
"Qoşulmaq mümkün deyil" OmniRoute işləmir omniroute əmrini icra edin və ya docker restart omniroute istifadə edin
"Yanlış API açarı" Açarınız yanlışdır və ya vaxtı bitib Açarı provayderin saytından yenidən köçürün
"Sorğu tezliyi limiti aşılıb" Həddindən çox sorğu göndərirsiniz 1 dəqiqə gözləyin və ya avtomatik alternativ üçün model: "auto" istifadə edin
"Kvota aşılıb" Pulsuz/ödənişli kvotanızı bitirmisiniz Daha çox provayder qoşun və ya pulsuz provayderlərdən (Kiro, Pollinations) istifadə edin
"Yavaş cavablar" Provayder məşğuldur və ya uzaqda yerləşir model: "auto/fast" istifadə edin və ya daha sürətli provayder (Groq, Cerebras) qoşun
"Yanlış provayder istifadə edildi" auto başqa provayder seçib Bu normaldır! auto ən yaxşısını seçir. model: "openai/gpt-4o" ilə konkret provayderi məcburi seçin
"502 Bad Gateway" Provayder işləmir Gözləyib yenidən cəhd edin və ya provayderi dəyişmək üçün model: "auto" istifadə edin
"401 Unauthorized" Giriş məlumatlarınız yanlışdır API açarınızı yoxlayın və ya OAuth ilə yenidən autentifikasiya olun
"omniroute tanınmır" Windows PATH-də qlobal node modulları yoxdur npm qlobal prefiksinizi Windows PATH-ə əlavə edin. Onu npm config get prefix ilə tapın.
"429 Too Many Requests" Sorğu tezliyi məhdudlaşdırılıb 1 dəqiqə gözləyin və ya daha çox provayder qoşun

Hələ də problem həll olunmayıb? Aşağıdakı ətraflı problemlərin aradan qaldırılması bölməsinə baxın və ya Discord üzərindən soruşun.

Problemlərin Ətraflı Aradan Qaldırılması

Pulsuz Provayderlərdə Sorğu Tezliyinin Məhdudlaşdırılması (429 / 400 / 401)

Əlamət: Pulsuz/autentifikasiya tələb etməyən provayderlərlə (opencode, auggie və s.) model: "auto" istifadə edərkən cavab əvəzinə vaxtaşırı HTTP 429, 400 və ya 401 xətası alırsınız. Bir neçə saniyə sonra eyni sorğunu təkrar göndərdikdə sorğular uğurla yerinə yetirilir, lakin avtomatlaşdırma (cron tapşırıqları, agentlər, skriptlər) ilk xətada dayanır.

Əsas səbəb: Üç müstəqil nasazlıq rejimi üst-üstə düşür:

  1. Provayderin sorğu tezliyi limiti (429): Pulsuz səviyyələr müəyyən zaman intervalı üçün kvota tətbiq edə bilər. Paralel çağırışların ani artımı bu kvotanı tükədir, buna görə də interval sıfırlanana qədər növbəti sorğu rədd edilir.
  2. Birbaşa ötürmədə nasaz model (400/401): auto/* hovuzlarına opencode provayderinin kataloqda qeydiyyatdan keçmiş, lakin aktiv giriş məlumatları olmayan birbaşa ötürmə modelləri daxil ola bilər (məsələn, oc/north-mini-code-free → 401). Avtomatik marşrutlaşdırıcı onlardan birini sınayır, uğursuz olur və alternativə keçid işə düşməzdən əvvəl xəta ötürülür.
  3. Paralelliyin gücləndirilməsi (yük altında 429): Bir neçə agent/cron sessiyası eyni anda auto-ya müraciət etdikdə ümumi sorğu tezliyi pulsuz provayderlərin qəbul edə biləcəyi həddi aşır, buna görə də qanuni çağırışlar sui-istifadə kimi işarələnir.

Təsdiqlənmiş həll (icma tərəfindən bildirilib, 2026-08-10): rotasiya, paralellik və alternativə keçidin pulsuz səviyyədəki qeyri-sabitliyi xəta ilə dayanmaq əvəzinə kompensasiya etməsi üçün üç mühit dəyişənini tənzimləyin:

export OMNIROUTE_ROTATE_ON_400=true           # 400/401 zamanı başqa modelə/provayderə keçin (nasaz birbaşa ötürmə modellərini ötürür)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # ağır sorğular üçün açıq qəbul həddi (standart olaraq təyin edilməyib: sorğu sayı limiti yoxdur, aşağıdakı qeydə baxın)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # dərhal təkrar sınana bilən 503 xətası əvəzinə ağır sorğu tutumu üçün daha uzun, məhdud gözləmə

Bunları OmniRoute prosesinin mühitində (demonda, məsələn, LaunchAgent plist vasitəsilə və ya systemctl edit ilə) təyin edin, sonra OmniRoute-u yenidən başladın. Rotasiya bayrağı ən yüksək təsirə malik tək parametrdir: o, hovuzdakı işlək provayderdə şəffaf şəkildə yenidən cəhd etməklə sərt xətanı aradan qaldırır.

Qeyd: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT eyni anda neçə ağır — uzun kontekstli — sorğunun işləyəcəyini məhdudlaşdırır; bu hədd provayderin sorğu tezliyi məhdudlaşdırıcısı deyil, qəbul keçididir. #503-fanout yeniləməsi: bu dəyişən artıq standart olaraq təyin edilmir (indi yalnız yuxarıdakı kimi açıq şəkildə konfiqurasiya edildikdə tətbiq olunur) — bunun əvəzinə ağır sorğuların qəbulu hostun real yaddaş həddinə əsasən özünü miqyaslandıran, avtomatik hesablanan bayt büdcəsi (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) ilə idarə olunur; buna görə də yeni quraşdırmada bu dəyişən ümumiyyətlə təyin edilmədən daha az 503 chat_admission_busy rəddi müşahidə edilməlidir. Onu burada açıq şəkildə təyin etmək yenə də sənədləşdirildiyi kimi işləyir. Bayt büdcəsinin açıq şəkildə dəyişdirilməsi 8 MiB–2 GiB aralığı ilə məhdudlaşdırılır. 413 body_exceeds_budget keçici xəta deyil: həmin bayt büdcəsini artırın, OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES dəyərini azaldın və ya prosesin yaddaş həddini artırın. inflight_bytes_budget səbəbindən yükün azaldılması müvəqqəti resurs çəkişməsidir və yenidən sınana bilər. Hər provayder üzrə sorğu tezliyinin məhdudlaşdırılması (open-sse/services/rateLimitManager.ts) ayrıca olaraq RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH və RATE_LIMIT_AUTO_ENABLE ilə idarə olunur — .env.example faylına baxın.

İşlədiyini necə yoxlamaq olar: agentinizi/cron tapşırığınızı qısa fasilə ilə iki dəfə işə salın və hər ikisinin uğurla tamamlandığını təsdiqləyin. Düzəlişdən əvvəl ikinci icra adətən 429/401 xətası verir. Düzəlişdən sonra xətalar (əgər varsa) şəffaf şəkildə yenidən sınanır və çağırış tamamlanır. Həmçinin curl /monitoring/health əmrini icra edib provayder bağlantılarındakı rateLimitedUntil sahəsini və təsirə məruz qalan provayderlər üçün circuitBreakers.providerBreakers[].state dəyərini izləyə bilərsiniz — vəziyyət CLOSED, DEGRADED, OPEN və ya HALF_OPEN dəyərlərindən biridir (src/shared/utils/circuitBreaker.ts faylına baxın) və uğursuzluğa davam edən provayder, sıfırlama pəncərəsi sınaq sorğusunun keçməsinə imkan verməzdən (HALF_OPEN) əvvəl CLOSED → DEGRADED → OPEN keçidini edəcək.

Hələ də 429 görürsünüzsə: həmin provayder üçün aktiv hesab həqiqətən öz kvotasını tükədib (sadəcə sorğu tezliyi limiti deyil). OmniRoute idarəetmə panelində → Providers → Accounts bölməsindən eyni provayder üçün ikinci hesab əlavə edin və ya başqa pulsuz provayderi (məsələn, routeway, auggie) qoşun. Rotasiya yalnız müvəqqəti sorğu tezliyi/400/401 xətalarında kömək edir; kvotanın tam tükənməsi ikinci etimadnamə və ya fərqli provayder tələb edir.

Görüntü modellərində (auto/vision, bazaarlink/*) 403 görürsünüzsə: qoşulmuş hesabın görüntü imkanlarını əhatə edən ödənişli planı yoxdur və ya API açarının icazələri kifayət etmir. Provayderin idarəetmə panelində açarın əhatə dairəsinə görüntü/multimodal imkanlarının daxil olduğunu yoxlayın və ya ödənişli tarifli hesab qoşaraq onu görüntü üçün hədəf kimi saxlayın.

npm install Xəbərdarlıqları (ERESOLVE / peer / deprecated)

npm install -g omniroute əmrini işlətdikdə npm warn ERESOLVE, peer-asılılıq bildirişləri və deprecated mesajları kimi çoxlu xəbərdarlıq görə bilərsiniz. Bunlar gözləniləndir və zərərsizdir. Çıxışda added <N> packages görürsünüzsə, quraşdırma uğurla tamamlanıb.

Peer-asılılıqların həlli ilə bağlı xəbərdarlıqları gizlətmək üçün OmniRoute-un dəstəklədiyi quraşdırma formasından istifadə edin:

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps yalnız ERESOLVE və peer-asılılıq bildirişlərini gizlədir. Köhnəlmə bildirişləri görünməyə davam edir, çünki onlar tranzitiv üçüncü tərəf paketlərindən gəlir; bu bildirişlər quraşdırmanın uğursuz olduğunu göstərmir.

Xəbərdarlıqlar OmniRoute-un nəzarət etmədiyi üçüncü tərəf paketlərindəki köhnəlmiş peer-asılılıq diapazonlarından qaynaqlanır:

  1. marked-terminal paketi marked >=1 <16 tələb edir, lakin marked@18 tapılıb — praktikada problemsiz işləyir; yuxarı səviyyəli peer diapazonu sadəcə köhnəlib.
  2. deprecated prebuild-install@7.1.3 — tranzitiv yerli binar fayl endirmə köməkçisidir. O, sabitlənmiş wreq-js nəqliyyat bağlamasını quraşdırmaq üçün istifadə edilmir və veb-kuki provayderinin nəqliyyat quraşdırmasının uğursuz olduğunu göstərmir.

Heç bir tədbir tələb olunmur — yuxarı səviyyəli paketləri fork etmədən xəbərdarlıqları tamamilə susdurmaq mümkün deyil.

Gemini Web və Playwright Chromium

Gemini Web sorğusu Playwright Chromium-un quraşdırılmadığını bildirən mesajla 503 qaytarırsa, npm paketi mövcuddur, lakin brauzerin binar faylı yoxdur. Playwright brauzer endirmələrini qəsdən npm paketinin quraşdırılmasından ayrı saxlayır, buna görə də brauzer quraşdırılanadək bu cavab gözləniləndir.

Qlobal npm quraşdırması üçün Chromium-u OmniRoute paketinin kataloqundan quraşdırın ki, brauzer keşi eyni Playwright quraşdırmasına aid olsun:

cd "$(npm root -g)/omniroute"
npx playwright install chromium

Quraşdırmadan sonra OmniRoute-u yenidən başladın, sonra Gemini Web sorğusunu təkrar edin. OmniRoute-u Docker təsvirindən işlədirsinizsə, Chromium və onun asılılıqlarını ehtiva edən -web təsvirindən (və ya runner-web yığma hədəfindən) istifadə edin; əsas təsvir bunları ehtiva etmir.

Sürətli Həllər

Problem Həll
İlk giriş işləmir .env faylında INITIAL_PASSWORD təyin edin (sərt kodlaşdırılmış standart dəyər yoxdur)
İdarəetmə paneli yanlış portda açılır PORT=20128 və NEXT_PUBLIC_BASE_URL=http://localhost:20128 təyin edin
Diskə heç bir jurnal yazılmır APP_LOG_TO_FILE=true təyin edin və çağırış jurnalının qeydə alınmasının aktiv olduğunu yoxlayın
EACCES: icazə rədd edildi ~/.omniroute yolunu əvəz etmək üçün DATA_DIR=/path/to/writable/dir təyin edin
Marşrutlaşdırma strategiyası yadda saxlanmır Ən son v3.x buraxılışına yeniləyin (parametrlərin saxlanması üçün Zod sxemi düzəlişi əvvəlki versiyalarda təqdim edilib)
Giriş zamanı çökmə / boş səhifə Node.js versiyasını yoxlayın — aşağıdakı Node.js Uyğunluğu bölməsinə baxın
dlopen / slice is not valid mach-o file (macOS) cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute əmrini işlədin — aşağıdakı macOS yerli modulunun yenidən yığılması bölməsinə baxın
Proksidə "fetch failed" Proksi konfiqurasiyasının düzgün səviyyədə təyin edildiyinə əmin olun — aşağıdakı Proksi Problemləri bölməsinə baxın
Docker curl: (56) Recv failure: Connection reset by peer Docker port bağlamanız IPv6 üzərinə yönələ bilər. IPv4-ü məcburi etmək üçün -p 127.0.0.1:20128:20128 istifadə edin və ya curl -4 ilə sınaqdan keçirin. Aşağıdakı Docker IPv6 bölməsinə baxın
Antivirus README.md faylını karantinə alır Yanlış müsbət nəticədir — aşağıdakı Antivirusun yanlış müsbət nəticələri bölməsinə baxın
Kaspersky Masaüstü tətbiqini troyan kimi işarələyir İmzalanmamış quraşdırıcıya görə davranış əsaslı yanlış müsbət nəticədir — aşağıdakı Antivirusun yanlış müsbət nəticələri bölməsinə baxın

Antivirusun yanlış müsbət nəticələri

Avast/AVG README.md faylını MD:HttpRequest-inf[Susp] kimi karantinə alır

Bu, yanlış müsbət nəticədir. Heç bir yoluxma yoxdur və heç bir tədbir tələb olunmur.

Avast və AVG çoxlu HTTP sorğusuna bənzəyən keçidlər olan adi mətn/Markdown fayllarını işarələyən evristik analizdən istifadə edir. OmniRoute-un README.md faylı npm paketinə daxildir (package.json → files siyahısında göstərilir), buna görə qlobal quraşdırma zamanı node_modules/omniroute/README.md ünvanına yerləşdirilir — və orada təxminən 15 http://localhost:20128/... nümunəsi (MCP HTTP/SSE son nöqtələri, A2A .well-known URL-i və curl fraqmentləri) var. Keçidlərin bu sıxlığı evristikanın işə düşməsi üçün kifayətdir.

Əgər bu, yalnız yaxın vaxtlarda başlayıbsa: faylın mahiyyəti dəyişməyib. README-də son nöqtələr cədvəli genişləndirilib (MCP HTTP + SSE + A2A əlavə edilib) və daha çox curl nümunəsi əlavə olunub; nəticədə hədd aşılıb.

Bu fayl heç bir icra edilə bilən məzmunu olmayan passiv sənəddir. Onu təhlükəsiz şəkildə karantindən bərpa edə bilərsiniz.

Nə etməli:

  1. Bildirişləri dayandırın — quraşdırma qovluğunu antivirusunuzda istisnalara əlavə edin (Avast: Settings → Exceptions); qlobal node_modules yolunu və/və ya OmniRoute məlumat qovluğunu (~/.omniroute/) əlavə edin.
  2. Yanlış müsbət nəticə barədə məlumat verin — https://www.avast.com/false-positive-file-form.php, karantinə alınmış README.md faylını əlavə edin. Bu, hər kəsə kömək edən həll yoludur, çünki problem təchizatçının evristikasının mətn faylına həddindən artıq reaksiya verməsidir.

Niyə bunu öz tərəfimizdə "düzəltmirik": bütün nümunələr http://localhost istifadə edir və öz-özünə imzalanmış sertifikatların yaratdığı çətinliklər olmadan localhost üçün https istifadə etmək mümkün deyil. Bir təchizatçının evristikasından yayınmaq üçün sənədləri təhrif etmək skaner xətasını razı salmaq naminə bütün oxuculara zərər verərdi.

Kaspersky Desktop tətbiqini PDM:Trojan.Win32.Generic kimi işarələyir

Bu, davranış evristikasından qaynaqlanan yanlış müsbət nəticədir. Heç bir yoluxma yoxdur. Kaspersky-nin PDM: prefiksi hökmün məlum zərərli proqramla uyğunlaşdırma əsasında deyil, Proactive Defense Module (System Watcher) tərəfindən, quraşdırıcının nə etdiyinə əsasən verildiyini bildirir. Bu modul işə düşdükdə Kaspersky bütün quraşdırmanı "geri qaytarır" — artıq yazılmış faylları silir — buna görə tətbiq sonda xarab olur və ya yoxa çıxır.

İşarələdiyi fayllar masaüstü tətbiqi ilə paketlənən, bəyan edilmiş açıq mənbəli asılılıqların standart hissələridir, məsələn:

  • resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js və workerProcessEntry.js — tətbiqdaxili provayder girişində və brauzer əsaslı söhbətdə istifadə olunan brauzer avtomatlaşdırma kitabxanası Playwright.
  • resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — veb-kuki provayderlərində brauzer barmaq izi ilə HTTP üçün istifadə olunan sabitlənmiş wreq-js yerli bağlaması (<arch> — x64 və ya arm64).

Niyə işə düşür: Windows quraşdırıcısı hələ kod imzası ilə imzalanmayıb, buna görə imzasız NSIS quraşdırıcısının reputasiyası sıfırdır və davranış evristikaları maksimum aqressivliklə işləyir. Paketlənmiş yerli DLL və %LOCALAPPDATA%\Programs\OmniRoute altında yazılan yüzlərlə .js faylı (Next.js müstəqil yığmasından heş suffiksli paket qovluqları daxil olmaqla) ilə birlikdə bu, evristikanın işə düşməsi üçün kifayətdir. Kod imzalama planlaşdırılır; tətbiq edilənədək yeni buraxılışlarda bu hal təkrarlana bilər.

Nə etməli:

  1. Əvvəlcə endirmənizi yoxlayın (faylın dəyişdirilmiş olması ehtimalını aradan qaldırır). Hər buraxılışda sha512 sahəsi (base64) OmniRoute.Setup.<version>.exe quraşdırıcısını əhatə edən latest.yml yayımlanır. PowerShell-də quraşdırıcının olduğu qovluqdan: 
    $b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
  [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.<version>.exe"))
[Convert]::ToBase64String($b)
    Çıxış latest.yml → sha512 ilə uyğun gəlməlidir. Uyğun gəlmirsə, faylı silin və yalnız GitHub buraxılışları səhifəsindən yenidən endirin.
  2. Bərpa edin + istisna əlavə edin — geri qaytarılmış elementləri karantindən bərpa edin və %LOCALAPPDATA%\Programs\OmniRoute üçün istisna əlavə edin (Kaspersky → Settings → Threats and Exclusions), sonra yenidən quraşdırın.
  3. Yanlış müsbət nəticə barədə məlumat verin — https://opentip.kaspersky.com/. İstifadəçilər tərəfindən göndərilən yanlış müsbət nəticə hesabatları icazə siyahısına əlavə edilməni həqiqətən sürətləndirir.

Node.js Uyğunluğu

Giriş səhifəsi çökür və ya "Module self-registration" xətası göstərir

Səbəb: OmniRoute-un təsdiqlənmiş təhlükəsiz icra mühiti üçün minimum tələbindən kənar Node.js versiyasından istifadə edirsiniz. Ən çox rast gəlinən hal OmniRoute-un tələb etdiyi təhlükəsizlik yeniləmələri səviyyəsindən aşağı olan köhnə Node 22 və ya 24 yamaq versiyasının işlədilməsidir.

Əlamətlər:

  • Giriş səhifəsi boş ekran və ya server xətası göstərir
  • Konsolda Error: Module did not self-register və ya buna bənzər yerli bağlama xətaları göstərilir
  • İcra mühiti dəstəklənən təhlükəsizlik siyasətinə uyğun olmadıqda giriş səhifəsində Node versiyanızı göstərən narıncı xəbərdarlıq banneri görünür

Həll:

  1. Dəstəklənən Node.js LTS buraxılışını quraşdırın (tövsiyə olunur: Node.js 24.x): 
    nvm install 24
nvm use 24
  2. Versiyanızı yoxlayın: node --version 24.x LTS xəttində v24.0.0 və ya daha yeni versiya göstərməlidir
  3. OmniRoute-u yenidən quraşdırın: npm install -g omniroute
  4. Yenidən başladın: omniroute

Dəstəklənən təhlükəsiz versiyalar: >=22.22.2 <23 və ya >=24.0.0 <27. Node.js 24.x LTS (Krypton) və Node.js 26 tam dəstəklənir.

npm v11+: better-sqlite3 quraşdırılmayıb (Modul tapılmır)

Səbəb: npm v11 (Node.js 24+ ilə birlikdə təqdim olunur) standart olaraq əlavə asılılıqlar üçün quraşdırma skriptlərini bloklayır. better-sqlite3 optionalDependencies bölməsində göstərildiyindən və yerli kompilyasiya (node-gyp rebuild) tələb etdiyindən, npm onu səssizcə ötürür.

Əlamətlər:

  • Server işə salınarkən Cannot find module 'better-sqlite3' xətası ilə çökür
  • ls node_modules/better-sqlite3 əmri "No such file or directory" göstərir
  • npm ls better-sqlite3 əmri (empty) göstərir

Həll:

  1. Quraşdırma skriptlərini təsdiqləyin və yenidən quraşdırın: 
    npm approve-scripts better-sqlite3
npm install
  2. Yaxud əvvəlcədən yığılmış versiyanı əl ilə quraşdırın: 
    npm pack better-sqlite3@13.0.1
tar -xzf better-sqlite3-*.tgz -C node_modules
mv node_modules/package node_modules/better-sqlite3
rm better-sqlite3-*.tgz
  3. İşlədiyini yoxlayın: node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS: dlopen / "slice is not valid mach-o file"

Səbəb: Qlobal npm install -g omniroute quraşdırmasından sonra paketin daxilindəki better-sqlite3 yerli binar faylı lokal olaraq işləyən mühitdən fərqli arxitektura və ya Node.js ABI üçün kompilyasiya edilmiş ola bilər. Əvvəlcədən yığılmış binar fayl mühitinizə uyğun gəlmədikdə bu hal macOS-da (həm Apple Silicon, həm də Intel sistemlərində) tez-tez baş verir.

Əlamətlər:

  • Server işə salındıqdan dərhal sonra dlopen xətası ilə dayanır
  • Xətada slice is not valid mach-o file ifadəsi var
  • Tam nümunə:
dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

Həll — lokal mühitiniz üçün yenidən yığın (Node.js versiyasını aşağı salmaq tələb olunmur):

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

Qeyd: Bu əməliyyat yerli bağlamanı lokal Node.js versiyanıza və CPU arxitekturanıza uyğun şəkildə yenidən kompilyasiya edərək binar uyğunsuzluğunu aradan qaldırır. Rəsmi olaraq dəstəklənən icra mühiti diapazonu >=22.22.2 <23 və ya >=24.0.0 <27-dir (src/shared/utils/nodeRuntimeSupport.ts faylındakı SUPPORTED_NODE_RANGE, package.json faylındakı engines sahəsinə uyğunlaşdırılıb). Node.js 24.x LTS (Krypton) və Node.js 26, better-sqlite3 v12.x ilə tam dəstəklənir.

Proksi Problemləri

Provayder yoxlaması "fetch failed" xətası göstərir

Səbəb: API açarının yoxlama son nöqtəsi (POST /api/providers/validate) əvvəllər proksi konfiqurasiyasından yan keçirdi və bu, proksi marşrutlaşdırması tələb edən mühitlərdə xətalara səbəb olurdu.

Həll (v3.5.5+): Bu problem artıq aradan qaldırılıb. Provayder yoxlaması runWithProxyContext vasitəsilə yönləndirilir və provayder səviyyəli və qlobal proksi parametrlərini avtomatik nəzərə alır.

Token sağlamlıq yoxlaması "fetch failed" xətası ilə uğursuz olur

Səbəb: Arxa planda OAuth tokeninin yenilənməsi hər bağlantı üçün proksi konfiqurasiyasını müəyyən etmirdi.

Həll (v3.5.5+): Token sağlamlıq yoxlaması planlaşdırıcısı artıq yeniləməyə cəhd etməzdən əvvəl hər bağlantı üçün proksi konfiqurasiyasını müəyyən edir. v3.5.5+ versiyasına yeniləyin.

SOCKS5 proksisi "invalid onRequestStart method" xətası qaytarır

Səbəb: Node.js 22-də undici@8 dispatcher-i Node-un daxili fetch() reallaşdırması ilə uyğun deyil.

Həll (v3.5.5+): OmniRoute artıq proksi dispatcher-i aktiv olduqda undici-nin öz fetch() funksiyasından istifadə edir və beləliklə ardıcıl davranışı təmin edir. v3.5.5+ versiyasına yeniləyin.

WSL altında MITM proksisi: Windows hostundakı masaüstü tətbiqləri ələ keçirilmir

Səbəb: MITM proksisi və onun CA sertifikatı OmniRoute-un işlədiyi mühitə quraşdırılır. WSL altında həmin mühit Linux qonaq sistemi olduğu halda, AI masaüstü tətbiqləri (Kiro, Trae, Copilot, Zed, …) Windows hostunda işləyir. Host tətbiqləri qonaq sisteminin sertifikat anbarına etibar etmir və qonaq sisteminin sistem proksisi vasitəsilə yönləndirilmir, buna görə də masaüstü trafikin ələ keçirilməsi burada işə düşmür.

Tövsiyə: OmniRoute-u ələ keçirmək istədiyiniz masaüstü tətbiqləri ilə eyni əməliyyat sistemində birbaşa işə salın (Windows tətbiqləri üçün Windows; eyni qayda macOS/Linux üçün də keçərlidir). Host tətbiqlərini hədəfləyərkən OmniRoute-u WSL daxilində saxlamaq üçün yaradılmış CA sertifikatına Windows hostunda əl ilə etibar etmək və hər bir host tətbiqinin şəbəkə/proksi parametrlərini WSL proksi son nöqtəsinə yönəltmək lazımdır — bu, dəstəklənməyən və etibarsız bir quraşdırmadır.

Provayder Problemləri

"Language model did not provide messages"

Səbəb: Provayder kvotası tükənib.

Həll:

  1. İdarəetmə panelindəki kvota izləyicisini yoxlayın
  2. Ehtiyat səviyyələri olan kombinasiyadan istifadə edin
  3. Daha ucuz/pulsuz səviyyəyə keçin

Sorğu Tezliyinin Məhdudlaşdırılması

Səbəb: Abunəlik kvotası tükənib.

Həll:

  • Ehtiyat keçid əlavə edin: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
  • Ucuz ehtiyat variant kimi GLM/MiniMax istifadə edin

OAuth Tokeninin Müddəti Bitib

OmniRoute tokenləri avtomatik yeniləyir. Problemlər davam edərsə:

  1. İdarəetmə paneli → Provayder → Yenidən qoşulun
  2. Provayder bağlantısını silin və yenidən əlavə edin

Kiro-da çoxsaylı hesablar: ikinci hesab birincini etibarsız edir

Səbəb: Kiro-nun arxa sistemi hər OIDC müştəri qeydiyyatı üçün yalnız bir aktiv sessiyaya icazə verir. İki hesab eyni qeydiyyatdan keçmiş müştərini paylaşdıqda (v3.8.0-dan əvvəl idxal edilmiş bağlantılar), bir hesabın tokeninin yenilənməsi digərinin yeniləmə tokenini etibarsız edir.

Həll (v3.8.0+): Təsirlənmiş bağlantıları yenidən idxal edin. v3.8.0-dan başlayaraq Tokeni İdxal Et, Google/GitHub sosial girişi və ya Avtomatik İdxal vasitəsilə yaradılan hər yeni Kiro bağlantısı avtomatik olaraq öz ayrıca OIDC müştərisini qeydiyyatdan keçirir. Buna görə də bağlantı tam təcrid olunur və bir hesabın yenilənməsi digər hesabların heç birinə təsir etmir.

v3.8.0-dan əvvəl idxal edilmiş bağlantıların hər bağlantı üçün ayrıca müştəri qeydiyyatı yoxdur. Həmin bağlantılar ortaq sosial autentifikasiya yeniləmə son nöqtəsindən istifadə etməyə davam edir. Təcrid olunmanı təmin etmək üçün köhnə bağlantını İdarəetmə paneli → Provayderlər bölməsindən silin və onu üç idxal axınından hər hansı biri vasitəsilə yenidən əlavə edin.

Tam təfərrüatlar və iki Kiro hesabını paralel əlavə etmək üçün addım-addım təlimatlar üçün docs/guides/KIRO_SETUP.md sənədinə baxın.

Bulud Problemləri

Bulud Sinxronizasiya Xətaları

  1. BASE_URL dəyərinin işləyən instansiyanıza yönəldiyini yoxlayın (məsələn, http://localhost:20128)
  2. CLOUD_URL dəyərinin bulud son nöqtənizə yönəldiyini yoxlayın (məsələn, https://omniroute.dev)
  3. NEXT_PUBLIC_* dəyərlərini server tərəfdəki dəyərlərlə uyğun saxlayın

Buludda stream=false 500 Xətası Qaytarır

Əlamət: Axınsız çağırışlar üçün bulud son nöqtəsində Unexpected token 'd'... xətası.

Səbəb: Müştəri JSON gözlədiyi halda yuxarı axın SSE faydalı yükü qaytarır.

Müvəqqəti həll: Buluda birbaşa çağırışlar üçün stream=true istifadə edin. Lokal icra mühiti SSE→JSON ehtiyat mexanizmini ehtiva edir.

Bulud Qoşulduğunu Göstərir, Lakin "Etibarsız API açarı" Xətası Verir

  1. Lokal idarəetmə panelindən (/api/keys) yeni açar yaradın
  2. Bulud sinxronizasiyasını başladın: Buludu Aktivləşdir → İndi Sinxronizasiya Et
  3. Köhnə və ya sinxronizasiya edilməmiş açarlar buludda hələ də 401 qaytara bilər

Docker Problemləri

Docker IPv6 / Bağlantının Sıfırlanması

Əlamətlər: curl http://localhost:20128/v1/models əmri curl: (56) Recv failure: Connection reset by peer qaytarır. İdarəetmə paneli və autentifikasiya tələb etməyən son nöqtələr işləyir, lakin autentifikasiya tələb edən son nöqtələr uğursuz olur — bu, autentifikasiya problemi kimi görünsə də, əslində belə deyil.

Səbəb: docker run -p 20128:20128 portu həm 0.0.0.0 (IPv4), həm də :: (IPv6) üzərində yayımlayır, lakin konteyner daxilindəki proses yalnız IPv4 üzərindən dinləyir. localhost ünvanının əvvəlcə ::1 olaraq həll edildiyi hostlarda bağlantı arxasında dinləyici olmayan yayımlanmış IPv6 portuna düşür → bağlantı sıfırlanır.

Həll:

  1. Sürətli diaqnostika: curl -4 http://localhost:20128/v1/models əmrini icra edin. -4 ilə işləyib onsuz uğursuz olursa, IPv6 bağlama uyğunsuzluğu mövcuddur.
  2. Daimi həll: docker run əmrinizdə -p 127.0.0.1:20128:20128 istifadə edərək açıq şəkildə IPv4 ünvanına bağlayın: 
    docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
    Bu, IPv4 bağlamasını məcbur edir və həmçinin proksinin hostun bütün interfeyslərində əlçatan olmasının qarşısını alır.

CLI Aləti Quraşdırılmayıb Kimi Göstərilir

  1. İcra mühiti sahələrini yoxlayın: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
  2. Portativ rejim üçün: runner-cli obraz hədəfindən istifadə edin (CLI-lər daxildir)
  3. Host qoşma rejimi üçün: CLI_EXTRA_PATHS təyin edin və hostun bin kataloqunu yalnız oxuma rejimində qoşun
  4. Əgər installed=true və runnable=false olarsa: binar fayl tapılıb, lakin sağlamlıq yoxlamasından keçməyib

İcra Mühitinin Sürətli Yoxlanması

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

Xərc Problemləri

Yüksək Xərclər

  1. İdarəetmə Paneli → İstifadə bölməsində istifadə statistikasını yoxlayın
  2. Əsas modeli GLM/MiniMax ilə dəyişin
  3. Kritik olmayan tapşırıqlar üçün pulsuz səviyyədən (Qoder, Kiro) istifadə edin
  4. Hər API açarı üçün xərc büdcələri təyin edin: İdarəetmə Paneli → API Açarları → Büdcə

Sazlama

Jurnal Fayllarını Aktivləşdirin

.env faylınızda APP_LOG_TO_FILE=true təyin edin. Tətbiq jurnalları logs/ altında yazılır. Çağırış jurnalı emal xətti parametrlərdə aktivləşdirildikdə sorğu artefaktları ${DATA_DIR}/call_logs/ altında saxlanılır. Emal xətti üzrə qeydəalma aktiv olduqda, axın fraqmentlərinin faydalı yüklərini buraxmaq üçün CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false təyin edin və ya artefakt limitini KB ilə dəyişmək üçün CALL_LOG_PIPELINE_MAX_SIZE_KB dəyərini tənzimləyin.

Provayderin Vəziyyətini Yoxlayın

# Vəziyyət idarəetmə paneli
http://localhost:20128/dashboard/health

# API vəziyyət yoxlaması
curl http://localhost:20128/api/monitoring/health

İcra Mühiti Yaddaşı

  • Əsas vəziyyət: ${DATA_DIR}/storage.sqlite (provayderlər, kombinasiyalar, ləqəblər, açarlar, parametrlər)
  • İstifadə: storage.sqlite daxilindəki SQLite cədvəlləri (usage_history, call_logs, proxy_logs) + istəyə bağlı ${DATA_DIR}/call_logs/
  • Tətbiq jurnalları: <repo>/logs/... (APP_LOG_TO_FILE=true olduqda)
  • Çağırış jurnalı artefaktları: çağırış jurnalı emal xətti aktivləşdirildikdə ${DATA_DIR}/call_logs/YYYY-MM-DD/...

Sorğu Jurnalları səhifəsindəki Tarixçəni Təmizlə əməliyyatı call_logs, köhnə request_detail_logs və lokal ${DATA_DIR}/call_logs/ artefakt kataloqunu təmizləyir.

Dövrə Qırıcı Problemləri

Provayder OPEN vəziyyətində ilişib qalıb

Provayderin dövrə qırıcısı OPEN vəziyyətində olduqda, soyuma müddəti bitənədək sorğular bloklanır.

Həll:

  1. İdarəetmə paneli → Parametrlər → Dayanıqlılıq bölməsinə keçin
  2. Təsirə məruz qalan provayderin dövrə qırıcı kartını yoxlayın
  3. Bütün dövrə qırıcıları təmizləmək üçün Hamısını sıfırla düyməsinə klikləyin və ya soyuma müddətinin bitməsini gözləyin
  4. Sıfırlamadan əvvəl provayderin həqiqətən əlçatan olduğunu yoxlayın

Provayder dövrə qırıcını davamlı işə salır

Provayder dəfələrlə OPEN vəziyyətinə keçirsə:

  1. Xəta modelini görmək üçün İdarəetmə paneli → Sağlamlıq → Provayderin sağlamlığı bölməsini yoxlayın
  2. Parametrlər → Dayanıqlılıq → Provayder profilləri bölməsinə keçərək xəta həddini artırın
  3. Provayderin API limitlərini dəyişib-dəyişmədiyini və ya təkrar autentifikasiya tələb edib-etmədiyini yoxlayın
  4. Gecikmə telemetriyasını nəzərdən keçirin — yüksək gecikmə vaxt aşımına əsaslanan xətalara səbəb ola bilər

Audio Transkripsiyası Problemləri

"Dəstəklənməyən model" xətası

  • İlk seqmenti giriş məlumatlarına sahib olduğunuz provayder olan model identifikatorundan istifadə edin (openai/whisper-1, openrouter/deepgram/nova-3). Təkcə deepgram/nova-3 istifadə etmək yerli Deepgram açarı tələb edir.
  • Provayderin İdarəetmə paneli → Provayderlər bölməsində qoşulduğunu yoxlayın

Transkripsiya boş nəticə qaytarır və ya uğursuz olur

  • Dəstəklənən audio formatlarını yoxlayın: mp3, wav, m4a, flac, ogg, webm
  • Fayl ölçüsünün provayder limitləri daxilində olduğunu yoxlayın (adətən < 25MB)
  • Provayder kartında API açarının etibarlılığını yoxlayın

Tərcüməçi Sazlamalarının Yoxlanması

Format tərcüməsi problemlərini sazlamaq üçün İdarəetmə paneli → Tərcüməçi bölməsindən istifadə edin:

Rejim Nə Zaman İstifadə Etməli
Sınaq meydançası Giriş/çıxış formatlarını yan-yana müqayisə edin — necə tərcümə olunduğunu görmək üçün uğursuz sorğunu yapışdırın
Söhbət testeri Canlı mesajlar göndərin və başlıqlar daxil olmaqla tam sorğu/cavab yükünü yoxlayın
Test stendi Hansı tərcümələrin pozulduğunu tapmaq üçün format kombinasiyaları üzrə paket testlərini başladın
Canlı monitor Fasilələrlə baş verən tərcümə problemlərini aşkarlamaq üçün real vaxt sorğu axınını izləyin

Ümumi format problemləri

  • Düşünmə teqləri görünmür — Hədəf provayderin düşünmə funksiyasını dəstəkləyib-dəstəkləmədiyini və düşünmə büdcəsi parametrini yoxlayın
  • Alət çağırışları itir — Bəzi format tərcümələri dəstəklənməyən sahələri silə bilər; Sınaq meydançası rejimində yoxlayın
  • Sistem təlimatı yoxdur — Claude və Gemini sistem təlimatlarını fərqli şəkildə emal edir; tərcümə çıxışını yoxlayın
  • SDK obyekt əvəzinə xam sətir qaytarır — v1.x versiyasında həll edilib; cavab təmizləyicisi OpenAI SDK Pydantic yoxlama xətalarına səbəb olan qeyri-standart sahələri (x_groq, usage_breakdown və s.) silir. Bunu hələ də v3.x+ versiyasında görürsünüzsə, problem bildirişi yaradın.
  • GLM/ERNIE system rolunu rədd edir — v1.x versiyasında həll edilib; rol normallaşdırıcısı uyğunsuz modellər üçün sistem mesajlarını avtomatik olaraq istifadəçi mesajları ilə birləşdirir. Bunu hələ də v3.x+ versiyasında görürsünüzsə, problem bildirişi yaradın.
  • developer rolu tanınmır — v1.x versiyasında həll edilib; OpenAI olmayan provayderlər üçün avtomatik olaraq system roluna çevrilir. Bunu hələ də v3.x+ versiyasında görürsünüzsə, problem bildirişi yaradın.
  • json_schema Gemini ilə işləmir — v1.x versiyasında həll edilib; response_format artıq Gemini-nin responseMimeType + responseSchema formatına çevrilir. Bunu hələ də v3.x+ versiyasında görürsünüzsə, problem bildirişi yaradın.

Dayanıqlılıq Parametrləri

Avtomatik sürət məhdudlaşdırması işə düşmür

  • Avtomatik sürət məhdudlaşdırması yalnız API açarı provayderlərinə tətbiq olunur (OAuth/abunəliyə deyil)
  • Settings → Resilience → Provider Profiles bölməsində avtomatik sürət məhdudlaşdırmasının aktiv olduğunu yoxlayın
  • Provayderin 429 status kodları və ya Retry-After başlıqları qaytarıb-qaytarmadığını yoxlayın

Eksponensial geri çəkilmənin tənzimlənməsi

Provayder profilləri bu parametrləri dəstəkləyir:

  • Baza gecikməsi — İlk uğursuzluqdan sonrakı ilkin gözləmə müddəti (standart: 1s)
  • Maksimum gecikmə — Maksimum gözləmə müddəti həddi (standart: 30s)
  • Vuruq — Hər ardıcıl uğursuzluqda gecikmənin nə qədər artırılacağı (standart: 2x)

Sorğu selinin qarşısının alınması

Çoxlu paralel sorğu sürəti məhdudlaşdırılmış provayderə yönəldikdə, OmniRoute sorğuları ardıcıl emal etmək və zəncirvari uğursuzluqların qarşısını almaq üçün mutex + avtomatik sürət məhdudlaşdırmasından istifadə edir. Bu, API açarı provayderləri üçün avtomatikdir.

Söhbət sorğuları 503 / chat_admission_busy xətası ilə uğursuz olur

Əlamətlər:

  • Söhbət tamamlamaları son nöqtəsi xəta kodu chat_admission_busy olan, yenidən sınana bilən 503 cavabı qaytarır.
  • Cavaba Retry-After daxildir. #12135-dən etibarən dəyər müşahidə olunan yüklənmə əsasında müəyyən edilir — sorğunun artıq gözlədiyi OMNIROUTE_CHAT_ADMISSION_QUEUE_MS intervalından və cari ağır yük icarələrinin saxlanıldığı müddətdən daha böyük olanı seçilir — tam saniyəyə yuxarı yuvarlaqlaşdırılır və maksimum 60 ilə məhdudlaşdırılır. Boş şlüzdə tarixi minimumlar saxlanılır: bayt əsaslı yolda 2 saniyə, struktur əsaslı yolda 1 saniyə (buraya həmçinin reason: "structure_limit" daxildir).
  • Bu, başqa bir ağır söhbət və ya uzunmüddətli axın cavabı hələ icra olunarkən baş verə bilər.

Bayt əsaslı cavab gövdəsi belədir:

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

Struktur əsaslı cavab eyni növ və koddan, həmçinin Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. mesajından və reason: "structure_limit" dəyərindən istifadə edir. Standart hədlərdə sorğuda ən azı 200 mesaj, ən azı 64 alət və ya ən azı 32,000 təxmini token olduqda, yaxud məhdudlaşdırılmış struktur qiymətləndirməsi 10,000 ziyarət edilmiş qovşaq və ya 12 dərinlik hədlərini tükətdikdə sorğu struktur baxımından ağır hesab olunur.

Səbəb: Bu, yuxarı axın provayderinin uğursuzluğu deyil, OmniRoute daxilində məqsədli yük azaldılmasıdır. Hər proses böyük sorğu gövdəsini yaddaşda saxlamazdan və təhlil etməzdən əvvəl məhdud ağır yük tutumunu rezerv etmək üçün prosesə lokal qoruyucudan istifadə edir. Ağır yük icarəsi SSE cavabının bütün ömrü boyu saxlanılır.

#503-fanout: bu düzəlişdən əvvəl qoruyucu, host yaddaşından asılı olmayaraq paralelliyi sabit sorğu SAYI ilə (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, standart 1) məhdudlaşdırırdı; buna görə kodlaşdırma agentlərinin şaxələnməsi (çoxsaylı alt agentlər/CLI-lər, adətən > 256 KB olan gövdələr) effektiv paralelliyi təxminən 1-ə endirir və tamamilə normal yük altında 503 xətalarına səbəb olurdu. Qoruyucu indi özünü avtomatik tənzimləyir: o, prosesin real yaddaş həddinə əsasən ölçüləndirilən, avtomatik hesablanmış qəbul BAYT büdcəsi (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) ilə idarə olunur və həmçinin canlı resurs təzyiqi siqnalını nəzərə alır — beləliklə, yalnız host həqiqətən yaddaş təzyiqi altında olduqda yükü azaldır, sadəcə eyni anda birdən çox ağır sorğunun gəlməsinə görə deyil. Köhnə say həddi (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT) hələ də nəzərə alınır, lakin yalnız onu açıq şəkildə təyin etdikdə.

Tutum məşğul olduqda, ağır sorğu yenidən sınana bilən 503 cavabını verməzdən əvvəl yerin boşalması üçün maksimum OMNIROUTE_CHAT_ADMISSION_QUEUE_MS (standart 2000, 0 gözləməni deaktiv edir) müddətində gözləyir. Məhdud gözləmə ona görə mövcuddur ki, ağır alt sorğuları paralel şaxələndirən agent tipli müştərilər (OpenCode, Claude Code, Cursor) dərhal rədd cavabları alaraq bütün yenidən sınaq büdcəsini tükətmək və tapşırığın ortasında dayanmaq əvəzinə sorğu partlayışını ardıcıl emal etsinlər. Cari ağır yük icarələrinin doluluğu, müəyyən edilmiş bayt büdcəsi və canlı təzyiqin şiddəti GET /api/monitoring/health → chatAdmission bölməsində (inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled) göstərilir — hər hansı env var dəyişəninə toxunmazdan əvvəl bunları yoxlayın. Settings → Resilience → Request Queue → Concurrent Requests bunu idarə etmir; həmin parametr ayrıca provayder sorğu növbəsi mexanizmini idarə edir.

Həll:

  1. Əvvəlcə yenidən sınayın. Müştərilər sorğunu dərhal təkrarlamaq əvəzinə Retry-After göstərişinə əməl etməli və geri çəkilmədən istifadə etməlidir.
  2. Hər hansı tənzimləmə etməzdən əvvəl /api/monitoring/health → chatAdmission bölməsini yoxlayın. countCapEnabled: false və kifayət qədər böyük maxInflightBytes avtomatik hesablanmış büdcənin artıq öz işini gördüyünü bildirir; high/critical dəyərində pressureSeverity isə hostda həqiqətən yaddaş çatışmazlığı olduğunu göstərir — bunu qəbul env var dəyişəni ilə düzəltmək mümkün deyil, daha çox RAM və ya daha kiçik iş yükü tələb olunur.
  3. Yalnız /api/monitoring/health avtomatik hesablanmış büdcənin hostunuz üçün həqiqətən çox kiçik olduğunu göstərərsə (bu nadirdir — o, artıq konteynerdən fiziki serverədək miqyaslanır), köhnə sorğu sayı həddinə qayıtmaq əvəzinə onu birbaşa OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES ilə dəyişdirin.

Qəbul parametrlərinin mötəbər təsviri üçün mühit dəyişənləri arayışına baxın.

Əlavə RAG / LLM xəta taksonomiyası (16 problem)

Bəzi OmniRoute istifadəçiləri şlüzü RAG və ya agent steklərinin qarşısında yerləşdirirlər. Belə konfiqurasiyalarda qəribə bir nümunəyə tez-tez rast gəlinir: OmniRoute sağlam görünür (provayderlər işləyir, marşrutlaşdırma profilləri qaydasındadır, sürət limiti xəbərdarlıqları yoxdur), lakin yekun cavab yenə də səhv olur.

Praktikada bu insidentlər adətən şlüzün özündən deyil, sonrakı RAG konveyerindən qaynaqlanır.

Bu xətaları təsvir etmək üçün ortaq terminologiyadan istifadə etmək istəyirsinizsə, təkrarlanan on altı RAG / LLM xəta nümunəsini müəyyən edən, MIT lisenziyalı xarici mətn resursu olan WFGY ProblemMap-dən istifadə edə bilərsiniz. Ümumi səviyyədə o, aşağıdakıları əhatə edir:

  • axtarış yayınması və pozulmuş kontekst sərhədləri
  • boş və ya köhnəlmiş indekslər və vektor anbarları
  • embedding və semantika uyğunsuzluğu
  • prompt yığımı və kontekst pəncərəsi problemləri
  • məntiqin çökməsi və həddindən artıq əminliklə verilən cavablar
  • uzun zəncir və agent koordinasiyası xətaları
  • çoxagentli yaddaş və rol yayınması
  • yerləşdirmə və ilkin işəsalma ardıcıllığı problemləri

İdeya sadədir:

  1. Səhv cavabı araşdırarkən aşağıdakıları qeydə alın:
    • istifadəçi tapşırığı və sorğusu
    • OmniRoute-dakı marşrut və ya provayder kombinasiyası
    • sonrakı mərhələdə istifadə olunan hər hansı RAG konteksti (əldə edilmiş sənədlər, alət çağırışları və s.)
  2. İnsidenti bir və ya iki WFGY ProblemMap nömrəsi ilə (No.1 … No.16) əlaqələndirin.
  3. Nömrəni öz idarəetmə panelinizdə, əməliyyat təlimatınızda və ya insident izləyicinizdə OmniRoute jurnallarının yanında saxlayın.
  4. RAG stekinizi, axtarış komponentinizi və ya marşrutlaşdırma strategiyanızı dəyişdirməli olub-olmadığını müəyyən etmək üçün müvafiq WFGY səhifəsindən istifadə edin.

Tam mətn və konkret reseptlər burada yerləşir (MIT lisenziyası, yalnız mətn):

WFGY ProblemMap README

OmniRoute arxasında RAG və ya agent konveyerləri işlətmirsinizsə, bu bölməni nəzərə almaya bilərsiniz.

v3.8.0 Məlum problemlər

v3.8.0 buraxılışına xas problemlər və onların cari müvəqqəti həlləri. Düzəliş sonrakı yamaq versiyasında təqdim olunarsa, müvafiq qeyd yenilənəcək və ya silinəcək.

Devin CLI autentifikasiya xətaları

Əlamətlər:

  • Devin əsaslı alətləri çağırarkən "Devin CLI tapılmadı" və ya "autentifikasiya uğursuz oldu" xətası
  • CLI icra mühiti yoxlaması installed=false bildirir

Səbəblər:

  • CLI_DEVIN_BIN mövcud olmayan yola işarə edir
  • Devin CLI hostda quraşdırılmayıb

Həll:

  1. Platformanız üçün Devin CLI-ni quraşdırın
  2. .env faylında CLI_DEVIN_BIN=/usr/local/bin/devin (və ya faktiki yolu) təyin edin
  3. OmniRoute-u yenidən başladın və İdarəetmə paneli → CLI Alətləri bölməsindən təkrar sınaqdan keçirin

Modelin soyuma rejimində ilişib qalması (əl ilə sıfırlama)

Əlamətlər:

  • Bitmə vaxtı keçdikdən sonra belə model soyuma rejimində göstərilməyə davam edir
  • Vaxt nişanının keçmişdə olmasına baxmayaraq, kombinasiya marşrutlaşdırması zamanı sorğular hələ də modeli ötürür

Əl ilə sıfırlama:

  • İdarəetmə paneli: Parametrlər → Model Soyuma Rejimləri → təsirə məruz qalan kartda Yenidən aktivləşdir düyməsinə klikləyin
  • API: idarəetmə autentifikasiyası başlıqları ilə DELETE /api/resilience/model-cooldowns

Command Code provayderinə qoşulma 403 xətası ilə uğursuz olur

Əlamətlər:

  • Command Code provayderi ilə bağlantını sınaqdan keçirərkən 403 xətası
  • Provayder kartı yeni əlavə edildikdən sonra "icazəsiz" göstərir

Səbəb: OAuth prosesi tamamlanmayıb (geri çağırış qəbul edilməyib və ya token yadda saxlanılmayıb).

Həll:

  • OAuth prosesini yenidən başlatmaq üçün CLI-dən omniroute providers əmrini icra edin və ya
  • İdarəetmə paneli → Provayderlər → Command Code → Yenidən qoşul vasitəsilə OAuth prosesini təkrar başladın

ModelScope aqressiv 429 soyuma müddətləri qaytarır

Əlamətlər:

  • Kiçik sorğu sıçrayışından sonra ModelScope-da çox qısa və ya dərhal başlayan soyuma müddətləri
  • Kombinasiya marşrutlaşdırması ModelScope-u gözləniləndən daha tez ötürür

Səbəb: ModelScope provayderə xas Retry-After başlıqları göndərir. v3.8.0 bu başlıqlar üçün xüsusi emal mexanizmi ilə təqdim olunur, buna görə də daha köhnə versiyalar onları ümumi sürət limiti göstərişləri kimi səhv şərh edir.

Həll:

  • v3.8.0 və ya daha yeni versiyada olduğunuzdan əmin olun
  • Parametrlər → Dayanıqlılıq bölməsində useUpstream429BreakerHints keçidinin aktiv olduğunu yoxlayın

İstehsal mühitində OMNIROUTE_WS_BRIDGE_SECRET yoxdur

Əlamətlər:

  • Uzaq istehsal hostunda işləyərkən hər Codex/Responses WebSocket körpü sorğusunda 401 xətası
  • WebSocket körpüsünün əlaqə razılaşması qoşulmadan dərhal sonra bağlanır

Səbəb: İstehsal mühitində OMNIROUTE_WS_BRIDGE_SECRET mühit dəyişəni yoxdur.

Həll:

  1. Təsadüfi sirr yaradın: openssl rand -hex 32
  2. İstehsal serverinin mühitində (və körpü ilə əlaqə saxlayan hər bir klientdə) OMNIROUTE_WS_BRIDGE_SECRET=<random-secret> təyin edin
  3. OmniRoute-u yenidən başladın

Responses API: fon rejimi sinxron rejimə endirilib

Əlamətlər:

  • Jurnala xəbərdarlıq yazılır: background mode degraded to synchronous
  • background: true sorğusu fon tapşırığı deskriptoru əvəzinə normal sinxron cavab qaytarır

Səbəb: v3.8.0 xəbərdarlıq yaradaraq Responses API-də background: true parametrini qəsdən sinxron icraya endirir. Tam asinxron fon icrası gələcəkdə təqdim ediləcək funksiyadır.

Həll:

  • Klienti background olmadan çağırış etmək üçün uyğunlaşdırın və ya
  • Tam asinxron fon rejimini təqdim edən sonrakı buraxılışı gözləyin (dəyişikliklər jurnalını izləyin)

Yavaş Başlama / Hazırlıq Taymautu

CLI ⚠ Server did not respond within 60s mesajını göstərirsə, lakin server əslində işləyirsə, hazırlıq yoxlaması üçün ayrılmış vaxt mühitinizə görə çox qısadır.

Bu, adətən Windows-da (antivirus, fayl sistemi izləyiciləri) və ya başlanğıcda ağır iş yükü olan konteynerlərdə baş verir.

Həll — ayrılmış vaxtı artırın:

# Mühit dəyişəni vasitəsilə (sonrakı başladılmalarda da qüvvədə qalır):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3 dəqiqə
omniroute serve

# CLI bayrağı vasitəsilə (birdəfəlik):
omniroute serve --ready-timeout 180000

Standart dəyər 60 000 ms-dir (60 s). Xəbərdarlıq yalnız məlumat xarakterlidir; server arxa planda başlamağa davam edir və yüklənmə tamamlandıqdan sonra əlçatan olacaq.

OMNIROUTE_READY_TIMEOUT_MS haqqında tam təfərrüatlar üçün docs/reference/ENVIRONMENT.md sənədinə baxın.

Hələ də ilişib qalmısınız?