mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-02 21:32:10 +03:00

Files

zenobit bfa9cd15b7 Add Czech language + Fix VM_DEPLOYMENT_GUIDE.md English source

Author: zenobit <zenobit@disroot.org>

2026-03-19 16:02:28 +01:00

13 KiB

Raw Blame History

Odstraňování problémů

Běžné problémy a řešení pro OmniRoute.

Rychlé opravy

Problém	Řešení
První přihlášení nefunguje	Nastavit `INITIAL_PASSWORD` v `.env` (bez pevně zakódovaného výchozího nastavení)
Dashboard se otevírá na nesprávném portu	Nastavte `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128`
Žádné protokoly požadavků v sekci `logs/`	Nastavte `ENABLE_REQUEST_LOGS=true`
PŘÍSTUP: povolení zamítnuto	Nastavením `DATA_DIR=/path/to/writable/dir` přepíšete `~/.omniroute`
Strategie směrování se neukládá	Aktualizace na v1.4.11+ (oprava schématu Zod pro perzistenci nastavení)

Problémy s poskytovateli

"Jazykový model neposkytoval zprávy"

Příčina: Vyčerpání kvóty poskytovatele.

Opravit:

Zkontrolujte sledovač kvót na řídicím panelu
Použijte kombinaci se záložními úrovněmi
Přepnout na levnější/bezplatnou úroveň

Omezení rychlosti

Příčina: Vyčerpání kvóty předplatného.

Opravit:

Přidat záložní variantu: cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking
Použijte GLM/MiniMax jako levnou zálohu

Platnost tokenu OAuth vypršela

OmniRoute automaticky obnovuje tokeny. Pokud problémy přetrvávají:

Ovládací panel → Poskytovatel → Znovu připojit
Odstranění a opětovné přidání připojení poskytovatele

Problémy s cloudem

Chyby synchronizace s cloudem

Ověřte, zda BASE_URL odkazuje na vaši spuštěnou instanci (např. http://localhost:20128 )
Ověřte, zda CLOUD_URL odkazuje na váš cloudový koncový bod (např. https://omniroute.dev ).
Udržujte hodnoty NEXT_PUBLIC_* zarovnané s hodnotami na straně serveru.

Cloud `stream=false` Vrací 500

Příznak: Unexpected token 'd'... na cloudovém koncovém bodu pro nestreamovaná volání.

Příčina: Upstream vrací datovou část SSE, zatímco klient očekává JSON.

Řešení: Pro přímá volání z cloudu použijte stream=true . Lokální běhové prostředí zahrnuje záložní SSE→JSON.

Cloud hlásí připojení, ale „neplatný klíč API“.

Vytvořte nový klíč z lokálního dashboardu ( /api/keys )
Spuštění synchronizace s cloudem: Povolit cloud → Synchronizovat nyní
Staré/nesynchronizované klíče mohou v cloudu stále vracet 401

Problémy s Dockerem

Nástroj CLI se zobrazuje jako nenainstalovaný

Zkontrolujte běhová pole: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
Pro přenosný režim: použijte cílový soubor image runner-cli (dodávané CLI)
Pro režim připojení hostitele: nastavte CLI_EXTRA_PATHS a připojte adresář hostitele bin jako pouze pro čtení.
Pokud installed=true a runnable=false : binární soubor byl nalezen, ale kontrola stavu selhala.

Rychlé ověření za běhu

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}'

Problémy s náklady

Vysoké náklady

Zkontrolujte statistiky využití v sekci Nástěnka → Využití
Přepnout primární model na GLM/MiniMax
Pro nekritické úlohy použijte bezplatnou úroveň (Gemini CLI, iFlow).
Nastavení rozpočtů nákladů pro každý klíč API: Dashboard → API klíče → Rozpočet

Ladění

Povolit protokoly požadavků

V souboru .env nastavte ENABLE_REQUEST_LOGS=true . Protokoly se zobrazují v adresáři logs/ .

Zkontrolujte stav poskytovatele

# Health dashboard
http://localhost:20128/dashboard/health

# API health check
curl http://localhost:20128/api/monitoring/health

Runtimové úložiště

Hlavní stav: ${DATA_DIR}/storage.sqlite (poskytovatelé, kombinace, aliasy, klíče, nastavení)
Použití: SQLite tabulky v storage.sqlite ( usage_history , call_logs , proxy_logs ) + volitelné ${DATA_DIR}/log.txt a ${DATA_DIR}/call_logs/
Záznamy požadavků: <repo>/logs/... (pokud ENABLE_REQUEST_LOGS=true )

Problémy s jističi

Poskytovatel uvízl ve stavu OPEN (OTEVŘENO)

Pokud je jistič poskytovatele VYPNUTÝ, požadavky jsou blokovány, dokud neuplyne doba ochlazování.

Opravit:

Přejděte do nabídky Ovládací panel → Nastavení → Odolnost
Zkontrolujte kartu jističe u dotčeného poskytovatele
Kliknutím na Obnovit vše vynulujete všechny jističe nebo počkejte, až vyprší doba zpoždění.
Před resetováním ověřte, zda je poskytovatel skutečně dostupný.

Poskytovatel neustále vypíná jistič

Pokud poskytovatel opakovaně přechází do stavu OTEVŘENO:

Zkontrolujte v části Dashboard → Stav → Stav poskytovatele vzorec selhání.
Přejděte do Nastavení → Odolnost → Profily poskytovatelů a zvyšte prahovou hodnotu selhání.
Zkontrolujte, zda poskytovatel změnil limity API nebo vyžaduje opětovné ověření.
Zkontrolujte telemetrii latence – vysoká latence může způsobit selhání z důvodu časového limitu.

Problémy s přepisem zvuku

Chyba „Nepodporovaný model“

Ujistěte se, že používáte správný prefix: deepgram/nova-3 nebo assemblyai/best
Ověřte, zda je poskytovatel připojen v nabídce Dashboard → Poskytovatelé.

Přepis vrací prázdný výsledek nebo selže

Zkontrolujte podporované zvukové formáty: mp3 , wav , m4a , flac , ogg , webm
Ověřte, zda je velikost souboru v rámci limitů poskytovatele (obvykle < 25 MB)
Zkontrolujte platnost klíče API poskytovatele v kartě poskytovatele

Ladění překladače

Pro ladění problémů s překladem formátu použijte Dashboard → Translator :

Režim	Kdy použít
Dětské hřiště	Porovnejte vstupní/výstupní formáty vedle sebe – vložte neúspěšný požadavek a podívejte se, jak se přeloží
Tester chatu	Odesílejte živé zprávy a kontrolujte kompletní datovou část požadavků/odpovědí včetně záhlaví
Zkušební stolice	Spusťte dávkové testy napříč kombinacemi formátů a zjistěte, které překlady jsou poškozené.
Živý monitor	Sledujte tok požadavků v reálném čase a zachyťte občasné problémy s překladem

Běžné problémy s formátováním

Štítky myšlení se nezobrazují – Zkontrolujte, zda cílový poskytovatel podporuje myšlení a nastavení rozpočtu myšlení.
Volání nástrojů se vynechávají – Některé překlady formátů mohou odstranit nepodporovaná pole; ověřte v režimu Playground.
Chybí systémová výzva – Claude a Gemini zpracovávají systémové výzvy odlišně; zkontrolujte překlad výstupu
SDK vrací nezpracovaný řetězec místo objektu – Opraveno ve verzi 1.1.0: sanitizér odpovědí nyní odstraňuje nestandardní pole ( x_groq , usage_breakdown atd.), která způsobují selhání validace OpenAI SDK v Pydantic.
GLM/ERNIE odmítá system roli — Opraveno ve verzi 1.1.0: normalizátor rolí automaticky slučoval systémové zprávy s uživatelskými zprávami pro nekompatibilní modely.
role developer nebyla rozpoznána – Opraveno ve verzi 1.1.0: automaticky převedeno na system pro poskytovatele, kteří nepoužívají OpenAI
json_schema nefunguje s Gemini — Opraveno ve verzi 1.1.0: response_format se nyní převádí na responseMimeType + responseSchema z Gemini.

Nastavení odolnosti

Automatické omezení rychlosti se nespouští

Automatické omezení rychlosti se vztahuje pouze na poskytovatele klíčů API (ne na OAuth/předplatné)
Ověřte Nastavení → Odolnost → Profily poskytovatelů mají povoleno automatické omezení rychlosti
Zkontrolujte, zda poskytovatel vrací stavové kódy 429 nebo hlavičky Retry-After

Ladění exponenciálního poklesu

Profily poskytovatelů podporují tato nastavení:

Základní zpoždění — Počáteční doba čekání po prvním selhání (výchozí: 1 s)
Max. zpoždění — Maximální doba čekání (výchozí: 30 s)
Násobitel — O kolik se má zvýšit zpoždění za každou po sobě jdoucí chybu (výchozí: 2x)

Stádo proti hromům

Když se na poskytovatele s omezenou rychlostí odesílá mnoho souběžných požadavků, OmniRoute použije mutex + automatické omezení rychlosti k serializaci požadavků a zabránění kaskádovým selháním. Toto je automatické pro poskytovatele klíčů API.

Volitelná taxonomie selhání RAG / LLM (16 problémů)

Někteří uživatelé OmniRoute umisťují bránu před RAG nebo agent stacky. V těchto nastaveních je běžné vidět zvláštní vzorec: OmniRoute vypadá v pořádku (poskytovatelé aktivní, profily směrování v pořádku, žádná upozornění na limity rychlosti), ale konečná odpověď je stále nesprávná.

V praxi tyto incidenty obvykle pocházejí z následného RAG kanálu, nikoli ze samotné brány.

Pokud chcete sdílenou slovní zásobu pro popis těchto selhání, můžete použít WFGY ProblemMap, externí textový zdroj s licencí MIT, který definuje šestnáct opakujících se vzorců selhání RAG / LLM. Na obecné úrovni zahrnuje:

drift vyhledávání a narušené hranice kontextu
prázdné nebo zastaralé indexy a vektorové úložiště
vkládání versus sémantický nesoulad
problémy s assembly promptu a kontextovým oknem
logický kolaps a přehnaně sebevědomé odpovědi
selhání dlouhého řetězce a koordinace agentů
paměť více agentů a posun rolí
problémy s nasazením a objednáváním bootstrapů

Myšlenka je jednoduchá:

Při vyšetřování špatné odpovědi zaznamenejte:
- úkol a požadavek uživatele
- Kombinace trasy nebo poskytovatele v OmniRoute
- jakýkoli kontext RAG použitý v následných fázích (načtené dokumenty, volání nástrojů atd.)
Namapujte incident na jedno nebo dvě čísla z WFGY ProblemMap ( No.1 … No.16 ).
Uložte číslo do vlastního řídicího panelu, runbooku nebo sledovače incidentů vedle protokolů OmniRoute.
Pro rozhodnutí, zda je potřeba změnit RAG stack, retriever nebo směrovací strategii, použijte odpovídající stránku WFGY.

Plný text a konkrétní recepty naleznete zde (licence MIT, pouze text):

Soubor README pro mapu problémů WFGY

Tuto část můžete ignorovat, pokud za OmniRoute nespouštěte RAG ani agenty.

Stále v koncích?

Problémy s GitHubem : github.com/diegosouzapw/OmniRoute/issues
Architektura : Viz docs/ARCHITECTURE.md pro interní podrobnosti
Referenční informace k API : Všechny koncové body naleznete v docs/API_REFERENCE.md
Panel stavu : Zkontrolujte Panel stavu, kde najdete stav systému v reálném čase.
Překladač : Použijte Dashboard → Překladač k ladění problémů s formátem

13 KiB Raw Blame History Unescape Escape

Odstraňování problémů

Rychlé opravy

Problémy s poskytovateli

"Jazykový model neposkytoval zprávy"

Omezení rychlosti

Platnost tokenu OAuth vypršela

Problémy s cloudem

Chyby synchronizace s cloudem

Cloud stream=false Vrací 500

Cloud hlásí připojení, ale „neplatný klíč API“.

Problémy s Dockerem

Nástroj CLI se zobrazuje jako nenainstalovaný

Rychlé ověření za běhu

Problémy s náklady

Vysoké náklady

Ladění

Povolit protokoly požadavků

Zkontrolujte stav poskytovatele

Runtimové úložiště

Problémy s jističi

Poskytovatel uvízl ve stavu OPEN (OTEVŘENO)

Poskytovatel neustále vypíná jistič

Problémy s přepisem zvuku

Chyba „Nepodporovaný model“

Přepis vrací prázdný výsledek nebo selže

Ladění překladače

Běžné problémy s formátováním

Nastavení odolnosti

Automatické omezení rychlosti se nespouští

Ladění exponenciálního poklesu

Stádo proti hromům

Volitelná taxonomie selhání RAG / LLM (16 problémů)

Stále v koncích?

13 KiB

Raw Blame History

Cloud `stream=false` Vrací 500