diff --git a/docs/i18n/hu/ARCHITECTURE.md b/docs/i18n/hu/ARCHITECTURE.md new file mode 100644 index 00000000..d1d8154f --- /dev/null +++ b/docs/i18n/hu/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# OmniRoute Architecture + +🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) + +_Utolsó frissítés: 2026-02-18_ + +## Vezetői összefoglaló + +Az OmniRoute egy helyi mesterséges intelligencia-útválasztó átjáró és irányítópult, amely a Next.js-re épül. +Egyetlen OpenAI-kompatibilis végpontot (`/v1/*`) biztosít, és a forgalmat több upstream szolgáltató között irányítja át fordítással, tartalékkal, tokenfrissítéssel és használati követéssel. + +Alapvető képességek: + +- OpenAI-kompatibilis API felület a CLI-hez/eszközökhöz (28 szolgáltató) +- Fordítás kérése/válaszolása a szolgáltatói formátumok között +- Model kombinált tartalék (több modell sorozat) +- Fiókszintű tartalék (szolgáltatónként több fiók) +- OAuth + API-kulcs szolgáltatói kapcsolatkezelés +- Beágyazás generálása a `/v1/embeddings` segítségével (6 szolgáltató, 9 modell) +- Képgenerálás a `/v1/images/generations` segítségével (4 szolgáltató, 9 modell) +- Gondoljon a címkeelemzésre (`...`) az érvelési modellekhez +- Válasz fertőtlenítés a szigorú OpenAI SDK-kompatibilitás érdekében +- Szerepek normalizálása (fejlesztő→rendszer, rendszer→felhasználó) a szolgáltatók közötti kompatibilitás érdekében +- Strukturált kimenet átalakítás (json_schema → Gemini responseSchema) +- Helyi kitartás a szolgáltatók, kulcsok, álnevek, kombinációk, beállítások, árképzés számára +- Használat/költségkövetés és kérések naplózása +- Opcionális felhőszinkronizálás több eszköz/állapot szinkronizáláshoz +- IP engedélyezési/blokkolási lista API hozzáférés-vezérléshez +- Átgondolt költségvetés-kezelés (áthaladó/automatikus/egyéni/adaptív) +- Globális rendszer azonnali befecskendezése +- Munkamenet követés és ujjlenyomat +- Fiókonként továbbfejlesztett díjkorlátozás szolgáltató-specifikus profilokkal +- Megszakító minta a szolgáltatói rugalmasság érdekében +- Mennydörgés elleni állományvédelem mutex zárral +- Aláírás alapú kérés deduplikációs gyorsítótár +- Domain réteg: modell elérhetősége, költségszabályok, tartalék házirend, kizárási szabályzat +- Tartomány állapotának fennmaradása (SQLite átírási gyorsítótár tartalékok, költségvetések, zárolások, megszakítók számára) +- Házirend motor a kérelmek központosított értékeléséhez (zárás → költségvetés → tartalék) +- Telemetria kérése p50/p95/p99 késleltetési összesítéssel +- Korrelációs azonosító (X-Request-Id) a végpontok közötti nyomkövetéshez +- Megfelelőségi naplózás API-kulcsonkénti leiratkozással +- Eval keretrendszer az LLM minőségbiztosításhoz +- Rugalmas UI műszerfal valós idejű megszakító állapottal +- Moduláris OAuth-szolgáltatók (12 egyedi modul a `src/lib/oauth/providers/` alatt) + +Elsődleges futásidejű modell: + +- A `src/app/api/*` alatti Next.js alkalmazásútvonalai irányítópult API-kat és kompatibilitási API-kat is megvalósítanak +- A `src/sse/*` + `open-sse/*` megosztott SSE/routing magja kezeli a szolgáltató végrehajtását, fordítását, adatfolyamát, tartalékát és használatát + +## Hatály és határok + +### Hatáskörben + +- Helyi átjáró futásidejű +- Irányítópult-kezelő API-k +- Szolgáltató hitelesítése és token frissítése +- Fordítás és SSE streaming kérése +- Helyi állapot + használat tartóssága +- Opcionális felhőszinkronizálás + +### A hatályon kívül + +- Felhőszolgáltatás megvalósítása a `NEXT_PUBLIC_CLOUD_URL` mögött +- Szolgáltató SLA/vezérlő síkja a helyi folyamaton kívül +- Maguk a külső CLI binárisok (Claude CLI, Codex CLI stb.) + +## Magas szintű rendszerkontextus + +```mermaid +flowchart LR + subgraph Clients[Developer Clients] + C1[Claude Code] + C2[Codex CLI] + C3[OpenClaw / Droid / Cline / Continue / Roo] + C4[Custom OpenAI-compatible clients] + BROWSER[Browser Dashboard] + end + + subgraph Router[OmniRoute Local Process] + API[V1 Compatibility API\n/v1/*] + DASH[Dashboard + Management API\n/api/*] + CORE[SSE + Translation Core\nopen-sse + src/sse] + DB[(db.json)] + UDB[(usage.json + log.txt)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity] + P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA] + P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible] + end + + subgraph Cloud[Optional Cloud Sync] + CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL] + end + + C1 --> API + C2 --> API + C3 --> API + C4 --> API + BROWSER --> DASH + + API --> CORE + DASH --> DB + CORE --> DB + CORE --> UDB + + CORE --> P1 + CORE --> P2 + CORE --> P3 + + DASH --> CLOUD +``` + +## Alapvető futásidejű összetevők + +## 1) API és útválasztási réteg (Next.js App Routes) + +Fő könyvtárak: + +- `src/app/api/v1/*` és `src/app/api/v1beta/*` a kompatibilitási API-khoz +- `src/app/api/*` a felügyeleti/konfigurációs API-khoz +- Következő átírások a `next.config.mjs` leképezésben `/v1/*` ide: `/api/v1/*` + +Fontos kompatibilitási útvonalak: + +- `src/app/api/v1/chat/completions/route.ts` +- `src/app/api/v1/messages/route.ts` +- `src/app/api/v1/responses/route.ts` +- `src/app/api/v1/models/route.ts` - egyéni modelleket tartalmaz `custom: true` +- `src/app/api/v1/embeddings/route.ts` - beágyazás generálása (6 szolgáltató) +- `src/app/api/v1/images/generations/route.ts` — képgenerálás (4+ szolgáltató, beleértve az Antigravitációt/Nebiust) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` – dedikált szolgáltatónkénti csevegés +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – dedikált szolgáltatónkénti beágyazások +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – szolgáltatónként dedikált képek +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Kezelési tartományok: + +- Hitelesítés/beállítások: `src/app/api/auth/*`, `src/app/api/settings/*` +- Szolgáltatók/kapcsolatok: `src/app/api/providers*` +- Szolgáltató csomópontjai: `src/app/api/provider-nodes*` +- Egyedi modellek: `src/app/api/provider-models` (GET/POST/DELETE) +- Modellkatalógus: `src/app/api/models/catalog` (GET) +- Proxy konfigurációja: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Kulcsok/álnevek/kombók/árazás: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Használat: `src/app/api/usage/*` +- Szinkronizálás/felhő: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI-eszközök segédei: `src/app/api/cli-tools/*` +- IP-szűrő: `src/app/api/settings/ip-filter` (GET/PUT) +- Átgondolt költségvetés: `src/app/api/settings/thinking-budget` (GET/PUT) +- Rendszerprompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Munkamenetek: `src/app/api/sessions` (GET) +- Díjkorlátok: `src/app/api/rate-limits` (GET) +- Rugalmasság: `src/app/api/resilience` (GET/PATCH) – szolgáltatói profilok, megszakító, sebességkorlát állapot +- Rugalmasság visszaállítása: `src/app/api/resilience/reset` (POST) - megszakítók visszaállítása + lehűlés +- Gyorsítótár statisztikái: `src/app/api/cache/stats` (GET/DELETE) +- A modell elérhetősége: `src/app/api/models/availability` (GET/POST) +- Telemetria: `src/app/api/telemetry/summary` (GET) +- Költségkeret: `src/app/api/usage/budget` (GET/POST) +- Tartalékláncok: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Megfelelőségi ellenőrzés: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Irányelvek: `src/app/api/policies` (GET/POST) + +## 2) SSE + Translation Core + +Fő áramlási modulok: + +- Bejegyzés: `src/sse/handlers/chat.ts` +- Alaphangszerelés: `open-sse/handlers/chatCore.ts` +- Szolgáltatói végrehajtási adapterek: `open-sse/executors/*` +- Formátumészlelés/szolgáltató konfigurációja: `open-sse/services/provider.ts` +- Modell elemzés/feloldás: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Fiók tartalék logikája: `open-sse/services/accountFallback.ts` +- Fordítási nyilvántartás: `open-sse/translator/index.ts` +- Adatfolyam átalakítások: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Használat kibontása/normalizálása: `open-sse/utils/usageTracking.ts` +- Think címkeelemző: `open-sse/utils/thinkTagParser.ts` +- Beágyazáskezelő: `open-sse/handlers/embeddings.ts` +- Beágyazási szolgáltató nyilvántartása: `open-sse/config/embeddingRegistry.ts` +- Képgeneráló kezelő: `open-sse/handlers/imageGeneration.ts` +- Képszolgáltató nyilvántartása: `open-sse/config/imageRegistry.ts` +- Válasz fertőtlenítés: `open-sse/handlers/responseSanitizer.ts` +- Szerepkör normalizálása: `open-sse/services/roleNormalizer.ts` + +Szolgáltatások (üzleti logika): + +- Fiókválasztás/pontozás: `open-sse/services/accountSelector.ts` +- Kontextus-életciklus-kezelés: `open-sse/services/contextManager.ts` +- IP-szűrő betartatása: `open-sse/services/ipFilter.ts` +- Munkamenetkövetés: `open-sse/services/sessionManager.ts` +- Deduplikáció kérése: `open-sse/services/signatureCache.ts` +- Rendszerkérdés: `open-sse/services/systemPrompt.ts` +- Gondolkodó költségvetés-kezelés: `open-sse/services/thinkingBudget.ts` +- Helyettesítő karakteres modell-útválasztás: `open-sse/services/wildcardRouter.ts` +- Díjkorlát kezelése: `open-sse/services/rateLimitManager.ts` +- Megszakító: `open-sse/services/circuitBreaker.ts` + +Domain réteg modulok: + +- A modell elérhetősége: `src/lib/domain/modelAvailability.ts` +- Költségszabályok/költségkeretek: `src/lib/domain/costRules.ts` +- Tartalék irányelv: `src/lib/domain/fallbackPolicy.ts` +- Kombinált feloldó: `src/lib/domain/comboResolver.ts` +- Kizárási szabályzat: `src/lib/domain/lockoutPolicy.ts` +- Irányelvmotor: `src/domain/policyEngine.ts` — központi zárolás → költségvetés → tartalék értékelés +- Hibakód-katalógus: `src/lib/domain/errorCodes.ts` +- Kérelem azonosítója: `src/lib/domain/requestId.ts` +- Lekérési időtúllépés: `src/lib/domain/fetchTimeout.ts` +- Telemetria kérése: `src/lib/domain/requestTelemetry.ts` +- Megfelelőség/ellenőrzés: `src/lib/domain/compliance/index.ts` +- Eval futó: `src/lib/domain/evalRunner.ts` +- A tartomány állapotának fennmaradása: `src/lib/db/domainState.ts` — SQLite CRUD tartalék láncokhoz, költségvetésekhez, költségelőzményekhez, zárolási állapothoz, megszakítókhoz + +OAuth-szolgáltató modulok (12 külön fájl a `src/lib/oauth/providers/` alatt): + +- Nyilvántartási index: `src/lib/oauth/providers/index.ts` +- Egyéni szolgáltatók: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, **OMNI_TOKEN_1118**,\_118_TOK `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Vékony burkolat: `src/lib/oauth/providers.ts` - újraexportálás az egyes modulokból + +## 3) Perzisztencia réteg + +Elsődleges állapot DB: + +- `src/lib/localDb.ts` +- fájl: `${DATA_DIR}/db.json` (vagy `$XDG_CONFIG_HOME/omniroute/db.json`, ha be van állítva, különben `~/.omniroute/db.json`) +- entitások: providerConnections, providerNodes, modelAliases, kombók, apiKeys, beállítások, árképzés, **customModels**, **proxyConfig**, **ipFilter**, **thhinkingBudget**, **systemPrompt** + +DB használat: + +- `src/lib/usageDb.ts` +- fájlok: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- ugyanazt az alapkönyvtár-házirendet követi, mint a `localDb` (`DATA_DIR`, majd `XDG_CONFIG_HOME/omniroute`, ha be van állítva) +- fókuszált almodulokra bontva: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` - CRUD műveletek a tartomány állapotához +- Táblázatok (létrehozva: `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, **OMNI_8_EN** +- Átírási gyorsítótár minta: a memórián belüli térképek mérvadóak futás közben; a mutációk szinkronban íródnak az SQLite-ba; állapot visszaáll a DB-ből hidegindításkor + +## 4) Auth + biztonsági felületek + +- Az irányítópult cookie hitelesítése: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- API-kulcs létrehozása/ellenőrzése: `src/shared/utils/apiKey.ts` +- A szolgáltató titkai `providerConnections` bejegyzésben is megmaradtak +- Kimenő proxy támogatása a következőn keresztül: `open-sse/utils/proxyFetch.ts` (env vars) és `open-sse/utils/networkProxy.ts` (szolgáltatónként konfigurálható vagy globális) + +## 5) Cloud Sync + +- Ütemező init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Időszakos feladat: `src/shared/services/cloudSyncScheduler.ts` +- Irányítási útvonal: `src/app/api/sync/cloud/route.ts` + +## Kérelem életciklusa (`/v1/chat/completions`) + +```mermaid +sequenceDiagram + autonumber + participant Client as CLI/SDK Client + participant Route as /api/v1/chat/completions + participant Chat as src/sse/handlers/chat + participant Core as open-sse/handlers/chatCore + participant Model as Model Resolver + participant Auth as Credential Selector + participant Exec as Provider Executor + participant Prov as Upstream Provider + participant Stream as Stream Translator + participant Usage as usageDb + + Client->>Route: POST /v1/chat/completions + Route->>Chat: handleChat(request) + Chat->>Model: parse/resolve model or combo + + alt Combo model + Chat->>Chat: iterate combo models (handleComboChat) + end + + Chat->>Auth: getProviderCredentials(provider) + Auth-->>Chat: active account + tokens/api key + + Chat->>Core: handleChatCore(body, modelInfo, credentials) + Core->>Core: detect source format + Core->>Core: translate request to target format + Core->>Exec: execute(provider, transformedBody) + Exec->>Prov: upstream API call + Prov-->>Exec: SSE/JSON response + Exec-->>Core: response + metadata + + alt 401/403 + Core->>Exec: refreshCredentials() + Exec-->>Core: updated tokens + Core->>Exec: retry request + end + + Core->>Stream: translate/normalize stream to client format + Stream-->>Client: SSE chunks / JSON response + + Stream->>Usage: extract usage + persist history/log +``` + +## Kombinált + fiók tartalék folyamat + +```mermaid +flowchart TD + A[Incoming model string] --> B{Is combo name?} + B -- Yes --> C[Load combo models sequence] + B -- No --> D[Single model path] + + C --> E[Try model N] + E --> F[Resolve provider/model] + D --> F + + F --> G[Select account credentials] + G --> H{Credentials available?} + H -- No --> I[Return provider unavailable] + H -- Yes --> J[Execute request] + + J --> K{Success?} + K -- Yes --> L[Return response] + K -- No --> M{Fallback-eligible error?} + + M -- No --> N[Return error] + M -- Yes --> O[Mark account unavailable cooldown] + O --> P{Another account for provider?} + P -- Yes --> G + P -- No --> Q{In combo with next model?} + Q -- Yes --> E + Q -- No --> R[Return all unavailable] +``` + +A tartalék döntéseket az `open-sse/services/accountFallback.ts` vezérli állapotkódok és hibaüzenet-heurisztika használatával. + +## OAuth beépítési és tokenfrissítési életciklus + +```mermaid +sequenceDiagram + autonumber + participant UI as Dashboard UI + participant OAuth as /api/oauth/[provider]/[action] + participant ProvAuth as Provider Auth Server + participant DB as localDb + participant Test as /api/providers/[id]/test + participant Exec as Provider Executor + + UI->>OAuth: GET authorize or device-code + OAuth->>ProvAuth: create auth/device flow + ProvAuth-->>OAuth: auth URL or device code payload + OAuth-->>UI: flow data + + UI->>OAuth: POST exchange or poll + OAuth->>ProvAuth: token exchange/poll + ProvAuth-->>OAuth: access/refresh tokens + OAuth->>DB: createProviderConnection(oauth data) + OAuth-->>UI: success + connection id + + UI->>Test: POST /api/providers/[id]/test + Test->>Exec: validate credentials / optional refresh + Exec-->>Test: valid or refreshed token info + Test->>DB: update status/tokens/errors + Test-->>UI: validation result +``` + +Az élő forgalom alatti frissítés a `open-sse/handlers/chatCore.ts`-ban történik a `refreshCredentials()` végrehajtón keresztül. + +## Cloud Sync életciklusa (Engedélyezés / Szinkronizálás / Letiltása) + +```mermaid +sequenceDiagram + autonumber + participant UI as Endpoint Page UI + participant Sync as /api/sync/cloud + participant DB as localDb + participant Cloud as External Cloud Sync + participant Claude as ~/.claude/settings.json + + UI->>Sync: POST action=enable + Sync->>DB: set cloudEnabled=true + Sync->>DB: ensure API key exists + Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys) + Cloud-->>Sync: sync result + Sync->>Cloud: GET /{machineId}/v1/verify + Sync-->>UI: enabled + verification status + + UI->>Sync: POST action=sync + Sync->>Cloud: POST /sync/{machineId} + Cloud-->>Sync: remote data + Sync->>DB: update newer local tokens/status + Sync-->>UI: synced + + UI->>Sync: POST action=disable + Sync->>DB: set cloudEnabled=false + Sync->>Cloud: DELETE /sync/{machineId} + Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed) + Sync-->>UI: disabled +``` + +Az időszakos szinkronizálást a `CloudSyncScheduler` váltja ki, ha a felhő engedélyezve van. + +## Adatmodell és tárolási térkép + +```mermaid +erDiagram + SETTINGS ||--o{ PROVIDER_CONNECTION : controls + PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider + PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage + + SETTINGS { + boolean cloudEnabled + number stickyRoundRobinLimit + boolean requireLogin + string password_hash + string fallbackStrategy + json rateLimitDefaults + json providerProfiles + } + + PROVIDER_CONNECTION { + string id + string provider + string authType + string name + number priority + boolean isActive + string apiKey + string accessToken + string refreshToken + string expiresAt + string testStatus + string lastError + string rateLimitedUntil + json providerSpecificData + } + + PROVIDER_NODE { + string id + string type + string name + string prefix + string apiType + string baseUrl + } + + MODEL_ALIAS { + string alias + string targetModel + } + + COMBO { + string id + string name + string[] models + } + + API_KEY { + string id + string name + string key + string machineId + } + + USAGE_ENTRY { + string provider + string model + number prompt_tokens + number completion_tokens + string connectionId + string timestamp + } + + CUSTOM_MODEL { + string id + string name + string providerId + } + + PROXY_CONFIG { + string global + json providers + } + + IP_FILTER { + string mode + string[] allowlist + string[] blocklist + } + + THINKING_BUDGET { + string mode + number customBudget + string effortLevel + } + + SYSTEM_PROMPT { + boolean enabled + string prompt + string position + } +``` + +Fizikai tároló fájlok: + +- fő állapot: `${DATA_DIR}/db.json` (vagy `$XDG_CONFIG_HOME/omniroute/db.json`, ha be van állítva, különben `~/.omniroute/db.json`) +- használati statisztika: `${DATA_DIR}/usage.json` +- kérésnapló sorai: `${DATA_DIR}/log.txt` +- opcionális fordítói/hibakereső munkamenetek kérése: `/logs/...` + +## Telepítési topológia + +```mermaid +flowchart LR + subgraph LocalHost[Developer Host] + CLI[CLI Tools] + Browser[Dashboard Browser] + end + + subgraph ContainerOrProcess[OmniRoute Runtime] + Next[Next.js Server\nPORT=20128] + Core[SSE Core + Executors] + MainDB[(db.json)] + UsageDB[(usage.json/log.txt)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Modulleképezés (döntéskritikus) + +### Útvonal- és API-modulok + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: kompatibilitási API-k +- `src/app/api/v1/providers/[provider]/*`: dedikált szolgáltatónkénti útvonalak (csevegés, beágyazás, képek) +- `src/app/api/providers*`: szolgáltató CRUD, érvényesítés, tesztelés +- `src/app/api/provider-nodes*`: egyéni kompatibilis csomópontkezelés +- `src/app/api/provider-models`: egyéni modellkezelés (CRUD) +- `src/app/api/models/catalog`: teljes modellkatalógus API (minden típus szolgáltató szerint csoportosítva) +- `src/app/api/oauth/*`: OAuth/eszközkód folyamatok +- `src/app/api/keys*`: helyi API kulcs életciklusa +- `src/app/api/models/alias`: alias kezelés +- `src/app/api/combos*`: tartalék kombinált kezelés +- `src/app/api/pricing`: az árképzés felülbírálása a költségszámításhoz +- `src/app/api/settings/proxy`: proxy konfiguráció (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: kimenő proxy csatlakozási teszt (POST) +- `src/app/api/usage/*`: használati és naplózási API-k +- `src/app/api/sync/*` + `src/app/api/cloud/*`: felhőszinkronizálás és felhő felé néző segítők +- `src/app/api/cli-tools/*`: helyi CLI konfigurációs írók/ellenőrzők +- `src/app/api/settings/ip-filter`: IP-engedélyezési lista/blokkolista (GET/PUT) +- `src/app/api/settings/thinking-budget`: gondolkodó token költségvetési konfiguráció (GET/PUT) +- `src/app/api/settings/system-prompt`: globális rendszerprompt (GET/PUT) +- `src/app/api/sessions`: aktív munkamenet-lista (GET) +- `src/app/api/rate-limits`: számlánkénti kamatkorlát állapota (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: kéréselemzés, kombinált kezelés, fiókválasztó hurok +- `open-sse/handlers/chatCore.ts`: fordítás, végrehajtó feladás, újrapróbálkozás/frissítés kezelése, adatfolyam beállítása +- `open-sse/executors/*`: szolgáltató-specifikus hálózati és formátumviselkedés + +### Fordítási nyilvántartó és formátumkonvertálók + +- `open-sse/translator/index.ts`: fordítói nyilvántartás és hangszerelés +- Fordítók kérése: `open-sse/translator/request/*` +- Válaszfordítók: `open-sse/translator/response/*` +- Formátum állandók: `open-sse/translator/formats.ts` + +### Kitartás + +- `src/lib/localDb.ts`: állandó konfiguráció/állapot +- `src/lib/usageDb.ts`: használati előzmények és gördülő kérésnaplók + +## Szolgáltatói végrehajtói lefedettség (stratégiai minta) + +Minden szolgáltató rendelkezik egy speciális végrehajtóval, amely kiterjeszti a `BaseExecutor`-t (a `open-sse/executors/base.ts`-ban), amely URL-építést, fejléc-építést, újrapróbálkozást exponenciális visszalépéssel, hitelesítő adatok frissítését és az `execute()` hangszerelési módszert biztosítja. + +| Végrehajtó | Szolgáltató(k) | Különleges kezelés | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Dinamikus URL/fejléc konfiguráció szolgáltatónként | +| `AntigravityExecutor` | Google Antigravitáció | Egyéni projekt/munkamenet azonosítók, Újrapróbálkozás-elemzés után | +| `CodexExecutor` | OpenAI Codex | Rendszerutasításokat szúr be, érvelési erőfeszítést kényszerít | +| `CursorExecutor` | Kurzor IDE | ConnectRPC protokoll, Protobuf kódolás, kérés aláírása ellenőrző összeggel | +| `GithubExecutor` | GitHub másodpilóta | Másodpilóta token frissítése, VSCode-utánzó fejlécek | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream bináris formátum → SSE konverzió | +| `GeminiCLIExecutor` | Gemini CLI | Google OAuth-token frissítési ciklus | + +Az összes többi szolgáltató (beleértve az egyéni kompatibilis csomópontokat is) használja a `DefaultExecutor`. + +## Szolgáltatói kompatibilitási mátrix + +| Szolgáltató | Formátum | Auth | Stream | Nem adatfolyam | Token Refresh | Használati API | +| ------------------ | ---------------- | ------------------------- | ------------------ | -------------- | ------------- | ------------------------- | +| Claude | claude | API kulcs / OAuth | ✅ | ✅ | ✅ | ⚠️ Csak adminisztrátor | +| Ikrek | ikrek | API kulcs / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravitáció | antigravitáció | OAuth | ✅ | ✅ | ✅ | ✅ Teljes kvóta API | +| OpenAI | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ kényszer | ❌ | ✅ | ✅ Díjkorlátok | +| GitHub másodpilóta | openai | OAuth + másodpilóta token | ✅ | ✅ | ✅ | ✅ Kvóta pillanatképek | +| Kurzor | kurzor | Egyéni ellenőrző összeg | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (Eseményfolyam) | ❌ | ✅ | ✅ Felhasználási korlátok | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Kérésre | +| iFlow | openai | OAuth (alap) | ✅ | ✅ | ✅ | ⚠️ Kérésre | +| OpenRouter | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API kulcs | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Zavartság | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Együtt AI | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Tűzijáték AI | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Cerebrák | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API kulcs | ✅ | ✅ | ❌ | ❌ | + +## Formátum fordítási lefedettség + +Az észlelt forrásformátumok a következők: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +A célformátumok a következők: + +- OpenAI chat/válaszok +- Claude +- Gemini/Gemini-CLI/Antigravitációs boríték +- Kiro +- Kurzor + +A fordítások az **OpenAI-t használják hub-formátumként** – minden konverzió köztesként az OpenAI-n megy keresztül: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +A fordítások kiválasztása dinamikusan történik a forrás hasznos adat alakja és a szolgáltató célformátuma alapján. + +További feldolgozási rétegek a fordítási folyamatban: + +- **Választisztítás** – Megszünteti a nem szabványos mezőket az OpenAI-formátumú válaszoktól (mind az adatfolyam-, mind a nem streameléstől) a szigorú SDK-megfelelőség biztosítása érdekében +- **Szerepnormalizálás** — `developer` → `system` konvertálása nem OpenAI-célokhoz; egyesíti a `system` → `user` a rendszerszerepkört elutasító modellekhez (GLM, ERNIE) +- **Think címke kivonatolás** — `...` blokkot elemzi a tartalomból a `reasoning_content` mezőbe +- **Strukturált kimenet** - Az OpenAI `response_format.json_schema` konvertálása Gemini `responseMimeType` + `responseSchema` + +## Támogatott API-végpontok + +| Végpont | Formátum | Kezelő | +| -------------------------------------------------- | ----------------------- | ---------------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Üzenetek | Ugyanaz a kezelő (automatikusan észlelve) | +| `POST /v1/responses` | OpenAI válaszok | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI beágyazások | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Modell lista | API útvonal | +| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Modell lista | API útvonal | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedikált szolgáltatónként modellellenőrzéssel | +| `POST /v1/providers/{provider}/embeddings` | OpenAI beágyazások | Dedikált szolgáltatónként modellellenőrzéssel | +| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | Dedikált szolgáltatónként modellellenőrzéssel | +| `POST /v1/messages/count_tokens` | Claude Token Count | API útvonal | +| `GET /v1/models` | OpenAI modellek listája | API útvonal (csevegés + beágyazás + kép + egyéni modellek) | +| `GET /api/models/catalog` | Katalógus | Minden modell szolgáltató + típus szerint csoportosítva | +| `POST /v1beta/models/*:streamGenerateContent` | Ikrek bennszülött | API útvonal | +| `GET/PUT/DELETE /api/settings/proxy` | Proxy konfiguráció | Hálózati proxy konfiguráció | +| `POST /api/settings/proxy/test` | Proxy kapcsolat | Proxy állapot/kapcsolati teszt végpontja | +| `GET/POST/DELETE /api/provider-models` | Egyedi modellek | Egyéni modellkezelés szolgáltatónként | + +## Bypass Handler + +A bypass kezelő (`open-sse/utils/bypassHandler.ts`) elfogja a Claude CLI ismert "kidobási" kéréseit – bemelegítő pingeket, címkivonatokat és tokenszámlálást –, és **hamis választ** ad vissza anélkül, hogy felhasználná a upstream szolgáltatói tokeneket. Ez csak akkor aktiválódik, ha az `User-Agent` tartalmazza a `claude-cli` értéket. + +## Kérjen Logger Pipeline-t + +A kérésnaplózó (`open-sse/utils/requestLogger.ts`) egy 7 szakaszból álló hibakeresési naplózási folyamatot biztosít, amely alapértelmezés szerint le van tiltva, és a következőn keresztül engedélyezett: `ENABLE_REQUEST_LOGS=true`: + +``` +1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json +→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt +``` + +A fájlok a `/logs//` címre íródnak minden egyes kérési munkamenethez. + +## Hibamódok és rugalmasság + +## 1) Számla/szolgáltató elérhetősége + +- szolgáltatói fiók lehűtése tranziens/sebesség/hitelesítési hibák esetén +- tartalék fiók a sikertelen kérés előtt +- kombinált modell tartalék, ha az aktuális modell/szolgáltató elérési útja kimerült + +## 2) Token lejárata + +- Előzetes ellenőrzés és frissítés újrapróbálkozással a frissíthető szolgáltatóknál +- 401/403 újrapróbálkozás frissítési kísérlet után az alapútvonalon + +## 3) Stream-biztonság + +- leválasztást érzékelő streamvezérlő +- fordítási adatfolyam a folyam végének kiürítésével és `[DONE]` kezelésével +- a használati becslés tartaléka, ha hiányoznak a szolgáltató használati metaadatai + +## 4) A felhőszinkronizálás leromlása + +- szinkronizálási hibák jelennek meg, de a helyi futásidő folytatódik +- Az ütemező rendelkezik újrapróbálkozásra alkalmas logikával, de az időszakos végrehajtás jelenleg alapértelmezés szerint egykísérletű szinkronizálást hív meg + +## 5) Adatintegritás + +- DB alakzat migráció/javítás a hiányzó kulcsok miatt +- sérült JSON-visszaállítási biztosítékok a localDb és a usageDb számára + +## Megfigyelhetőség és működési jelek + +Futásidejű láthatósági források: + +- konzolnaplók innen: `src/sse/utils/logger.ts` +- kérésenkénti használati összesítések a `usage.json`-ban +- szöveges kérés állapot bejelentkezés `log.txt` +- opcionális mélykérési/fordítási naplók a `logs/` alatt, amikor `ENABLE_REQUEST_LOGS=true` +- irányítópult-használati végpontok (`/api/usage/*`) a felhasználói felület használatához + +## Biztonságra érzékeny határok + +- A JWT titkos (`JWT_SECRET`) biztosítja az irányítópult-munkamenet cookie-ellenőrzését/aláírását +- A kezdeti tartalék jelszót (`INITIAL_PASSWORD`, alapértelmezett `123456`) felül kell bírálni valós telepítéseknél +- API kulcs HMAC titkos (`API_KEY_SECRET`) biztosítja a generált helyi API kulcs formátumát +- A szolgáltatói titkok (API-kulcsok/tokenek) megmaradnak a helyi adatbázisban, és fájlrendszer-szinten védeni kell őket +- A felhőszinkronizálási végpontok API kulcs hitelesítés + gépazonosító szemantikára támaszkodnak + +## Környezet és futásidejű mátrix + +A kód által aktívan használt környezeti változók: + +- Alkalmazás/hitelesítés: `JWT_SECRET`, `INITIAL_PASSWORD` +- Tárhely: `DATA_DIR` +- Kompatibilis csomópont viselkedése: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Opcionális tárhely-alap-felülírás (Linux/macOS, ha `DATA_DIR` nincs beállítva): `XDG_CONFIG_HOME` +- Biztonsági kivonatolás: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Naplózás: `ENABLE_REQUEST_LOGS` +- Szinkronizálás/felhő URL-elés: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Kimenő proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` és kisbetűs változatai +- SOCKS5 funkciójelzők: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Platform/futásidejű segítők (nem alkalmazás-specifikus konfiguráció): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Ismert építészeti megjegyzések + +1. `usageDb` és `localDb` most ugyanazt az alapkönyvtár-házirendet (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) osztja meg örökölt fájlmigrációval. +2. Az `/api/v1/route.ts` statikus modelllistát ad vissza, és nem a `/v1/models` által használt fő modellforrás. +3. A kérésnaplózó teljes fejlécet/törzsöt ír, ha engedélyezve van; a naplókönyvtárat érzékenyként kezeli. +4. A felhő viselkedése a helyes `NEXT_PUBLIC_BASE_URL` és a felhő-végpont elérhetőségétől függ. +5. Az `open-sse/` könyvtár `@omniroute/open-sse` **npm munkaterület-csomagként** lett közzétéve. A forráskód a `@omniroute/open-sse/...`-on keresztül importálja (a Next.js `transpilePackages` által megoldva). A dokumentum elérési útjai továbbra is a `open-sse/` könyvtárnevet használják a következetesség érdekében. +6. Az irányítópulton lévő diagramok **Újragrafikonokat** (SVG-alapú) használnak az elérhető, interaktív analitikai vizualizációkhoz (modellhasználati sávdiagramok, szolgáltatói bontási táblázatok sikerarányokkal). +7. Az E2E-tesztek a **Playwright**-ot (`tests/e2e/`) használják, a `npm run test:e2e`-on keresztül futnak. Az egységtesztek a **Node.js tesztfutót** (`tests/unit/`) használják, a `npm run test:plan3`-on keresztül futnak. A `src/` alatti forráskód **TypeScript** (`.ts`/`.tsx`); az `open-sse/` munkaterület továbbra is JavaScript marad (`.js`). +8. A Beállítások oldal 5 lapra van felosztva: Biztonság, Útválasztás (6 globális stratégia: kitöltés-első, kör-robin, p2c, véletlenszerű, legkevésbé használt, költségoptimalizált), Rugalmasság (szerkeszthető sebességkorlátok, megszakító, házirendek), AI (gondolkodó költségvetés, rendszerkérdés, gyorsítótár), Speciális (proxy). + +## Működési ellenőrzési ellenőrzőlista + +- Forrás: `npm run build` +- Build Docker kép: `docker build -t omniroute .` +- Indítsa el a szervizt és ellenőrizze: +- `GET /api/settings` +- `GET /api/v1/models` +- A CLI cél alap URL-jének `http://:20128/v1` kell lennie, amikor `PORT=20128` diff --git a/docs/i18n/hu/CODEBASE_DOCUMENTATION.md b/docs/i18n/hu/CODEBASE_DOCUMENTATION.md new file mode 100644 index 00000000..92412c34 --- /dev/null +++ b/docs/i18n/hu/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute — Kódbázis-dokumentáció + +🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) + +> Átfogó, kezdőbarát útmutató az **omniroute** több szolgáltató AI-proxy routeréhez. + +--- + +## 1. Mi az omniroute? + +Az omniroute egy **proxy router**, amely AI kliensek (Claude CLI, Codex, Cursor IDE stb.) és mesterséges intelligenciaszolgáltatók (Anthropic, Google, OpenAI, AWS, GitHub stb.) között helyezkedik el. Egy nagy problémát old meg: + +> **A különböző AI-kliensek különböző „nyelveket” (API-formátumokat) beszélnek, és a különböző AI-szolgáltatók is eltérő „nyelveket” várnak el.** Az omniroute automatikusan lefordítja őket. + +Tekints úgy, mint egy univerzális fordító az Egyesült Nemzetek Szervezetében – minden küldött bármilyen nyelven beszélhet, és a fordító bármely más küldött számára átalakítja. + +--- + +## 2. Építészet áttekintése + +```mermaid +graph LR + subgraph Clients + A[Claude CLI] + B[Codex] + C[Cursor IDE] + D[OpenAI-compatible] + end + + subgraph omniroute + E[Handler Layer] + F[Translator Layer] + G[Executor Layer] + H[Services Layer] + end + + subgraph Providers + I[Anthropic Claude] + J[Google Gemini] + K[OpenAI / Codex] + L[GitHub Copilot] + M[AWS Kiro] + N[Antigravity] + O[Cursor API] + end + + A --> E + B --> E + C --> E + D --> E + E --> F + F --> G + G --> I + G --> J + G --> K + G --> L + G --> M + G --> N + G --> O + H -.-> E + H -.-> G +``` + +### Alapelv: Hub-and-spoke fordítás + +Minden formátumfordítás átmegy az **OpenAI formátumon, mint központon**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +Ez azt jelenti, hogy csak **N fordítóra** (formátumonként egy) van szüksége a **N²** (minden pár) helyett. + +--- + +## 3. Projekt felépítése + +``` +omniroute/ +├── open-sse/ ← Core proxy library (portable, framework-agnostic) +│ ├── index.js ← Main entry point, exports everything +│ ├── config/ ← Configuration & constants +│ ├── executors/ ← Provider-specific request execution +│ ├── handlers/ ← Request handling orchestration +│ ├── services/ ← Business logic (auth, models, fallback, usage) +│ ├── translator/ ← Format translation engine +│ │ ├── request/ ← Request translators (8 files) +│ │ ├── response/ ← Response translators (7 files) +│ │ └── helpers/ ← Shared translation utilities (6 files) +│ └── utils/ ← Utility functions +├── src/ ← Application layer (Express/Worker runtime) +│ ├── app/ ← Web UI, API routes, middleware +│ ├── lib/ ← Database, auth, and shared library code +│ ├── mitm/ ← Man-in-the-middle proxy utilities +│ ├── models/ ← Database models +│ ├── shared/ ← Shared utilities (wrappers around open-sse) +│ ├── sse/ ← SSE endpoint handlers +│ └── store/ ← State management +├── data/ ← Runtime data (credentials, logs) +│ └── provider-credentials.json (external credentials override, gitignored) +└── tester/ ← Test utilities +``` + +--- + +## 4. Modulonkénti lebontás + +### 4.1 konfiguráció (`open-sse/config/`) + +Az **egyetlen igazságforrás** minden szolgáltatói konfigurációhoz. + +| Fájl | Cél | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `constants.ts` | `PROVIDERS` objektum alap URL-ekkel, OAuth hitelesítési adatokkal (alapértelmezett), fejlécekkel és alapértelmezett rendszerkérdésekkel minden szolgáltatóhoz. Meghatározza a következőt is: `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` és `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Betölti a külső hitelesítő adatokat a `data/provider-credentials.json` helyről, és egyesíti őket a `PROVIDERS` merevkódolt alapértékeihez. Kizárja a titkokat a forrás ellenőrzése alól, miközben fenntartja a visszafelé kompatibilitást. | +| `providerModels.ts` | Központi modellnyilvántartás: térképszolgáltatói álnevek → modellazonosítók. Funkciók, mint például `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | A Codex kérésekbe beszúrt rendszerutasítások (szerkesztési megszorítások, sandbox-szabályok, jóváhagyási szabályzatok). | +| `defaultThinkingSignature.ts` | Claude és Gemini modellek alapértelmezett "gondolkodó" aláírásai. | +| `ollamaModels.ts` | Sémadefiníció helyi Ollama modellekhez (név, méret, család, kvantálás). | + +#### Hitelesítési adatok betöltésének folyamata + +```mermaid +flowchart TD + A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"] + B --> C{"data/provider-credentials.json\nexists?"} + C -->|Yes| D["credentialLoader reads JSON"] + C -->|No| E["Use hardcoded defaults"] + D --> F{"For each provider in JSON"} + F --> G{"Provider exists\nin PROVIDERS?"} + G -->|No| H["Log warning, skip"] + G -->|Yes| I{"Value is object?"} + I -->|No| J["Log warning, skip"] + I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"] + K --> F + H --> F + J --> F + F -->|Done| L["PROVIDERS ready with\nmerged credentials"] + E --> L +``` + +--- + +### 4.2 Végrehajtók (`open-sse/executors/`) + +A végrehajtók a **szolgáltató-specifikus logikát** a **stratégiai minta** segítségével foglalják magukba. Minden végrehajtó szükség szerint felülírja az alapmetódusokat. + +```mermaid +classDiagram + class BaseExecutor { + +buildUrl(model, stream, options) + +buildHeaders(credentials, stream, body) + +transformRequest(body, model, stream, credentials) + +execute(url, options) + +shouldRetry(status, error) + +refreshCredentials(credentials, log) + } + + class DefaultExecutor { + +refreshCredentials() + } + + class AntigravityExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +shouldRetry() + +refreshCredentials() + } + + class CursorExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseResponse() + +generateChecksum() + } + + class KiroExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseEventStream() + +refreshCredentials() + } + + BaseExecutor <|-- DefaultExecutor + BaseExecutor <|-- AntigravityExecutor + BaseExecutor <|-- CursorExecutor + BaseExecutor <|-- KiroExecutor + BaseExecutor <|-- CodexExecutor + BaseExecutor <|-- GeminiCLIExecutor + BaseExecutor <|-- GithubExecutor +``` + +| Végrehajtó | Szolgáltató | Legfontosabb szakterületek | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Absztrakt alap: URL-építés, fejlécek, újrapróbálkozási logika, hitelesítő adatok frissítése | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Általános OAuth-token frissítés szabványos szolgáltatók számára | +| `antigravity.ts` | Google Cloud Code | Projekt/munkamenet azonosító generálása, több URL-es tartalék, egyéni újrapróbálkozás a hibaüzenetekből ("visszaállítás 2 óra 7 perc után") | +| `cursor.ts` | Kurzor IDE | **Legösszetettebb**: SHA-256 ellenőrzőösszeg hitelesítés, Protobuf kéréskódolás, bináris EventStream → SSE válaszelemzés | +| `codex.ts` | OpenAI Codex | Rendszerutasításokat injektál, gondolkodási szinteket kezel, eltávolítja a nem támogatott paramétereket | +| `gemini-cli.ts` | Google Gemini CLI | Egyéni URL-építés (`streamGenerateContent`), Google OAuth-token frissítése | +| `github.ts` | GitHub másodpilóta | Kettős token rendszer (GitHub OAuth + másodpilóta token), VSCode fejléc utánzás | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream bináris elemzés, AMZN eseménykeretek, token becslés | +| `index.ts` | — | Gyári: térképszolgáltató neve → végrehajtó osztály, alapértelmezett tartalék | + +--- + +### 4.3 Kezelők (`open-sse/handlers/`) + +A **hangszerelési réteg** — koordinálja a fordítást, a végrehajtást, a streamelést és a hibakezelést. + +| Fájl | Cél | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Központi hangszerelő** (~600 sor). Kezeli a teljes kérés életciklust: formátumészlelés → fordítás → végrehajtó feladása → streaming/nem streaming válasz → token frissítés → hibakezelés → használati naplózás. | +| `responsesHandler.ts` | Adapter az OpenAI Responses API-jához: átalakítja a válaszformátumot → Chat Completions → elküldi a `chatCore` címre → konvertálja vissza az SSE-t válaszformátumba. | +| `embeddings.ts` | Beágyazás generációs kezelő: feloldja a beágyazási modellt → szolgáltató, elküldi a szolgáltató API-nak, visszaküldi az OpenAI-kompatibilis beágyazási választ. 6+ szolgáltatót támogat. | +| `imageGeneration.ts` | Képgeneráló kezelő: feloldja a képmodell → szolgáltatót, támogatja az OpenAI-kompatibilis, a Gemini-image (Antigravitáció) és a tartalék (Nebius) módokat. A base64 vagy URL képeket adja vissza. | + +#### Életciklus kérése (chatCore.ts) + +```mermaid +sequenceDiagram + participant Client + participant chatCore + participant Translator + participant Executor + participant Provider + + Client->>chatCore: Request (any format) + chatCore->>chatCore: Detect source format + chatCore->>chatCore: Check bypass patterns + chatCore->>chatCore: Resolve model & provider + chatCore->>Translator: Translate request (source → OpenAI → target) + chatCore->>Executor: Get executor for provider + Executor->>Executor: Build URL, headers, transform request + Executor->>Executor: Refresh credentials if needed + Executor->>Provider: HTTP fetch (streaming or non-streaming) + + alt Streaming + Provider-->>chatCore: SSE stream + chatCore->>chatCore: Pipe through SSE transform stream + Note over chatCore: Transform stream translates
each chunk: target → OpenAI → source + chatCore-->>Client: Translated SSE stream + else Non-streaming + Provider-->>chatCore: JSON response + chatCore->>Translator: Translate response + chatCore-->>Client: Translated JSON + end + + alt Error (401, 429, 500...) + chatCore->>Executor: Retry with credential refresh + chatCore->>chatCore: Account fallback logic + end +``` + +--- + +### 4.4 Szolgáltatások (`open-sse/services/`) + +Üzleti logika, amely támogatja a kezelőket és a végrehajtókat. + +| Fájl | Cél | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Formátumészlelés** (`detectFormat`): elemzi a kérés törzsszerkezetét a Claude/OpenAI/Gemini/Antigravity/Responses formátumok azonosításához (beleértve a `max_tokens` heurisztikus Claude-ot). Továbbá: URL-építés, fejlécépítés, gondolkodási konfiguráció normalizálása. Támogatja a `openai-compatible-*` és `anthropic-compatible-*` dinamikus szolgáltatókat. | +| `model.ts` | Modellkarakterlánc-elemzés (`claude/model-name` → `{provider: "claude", model: "model-name"}`), álnév-feloldás ütközésészleléssel, bemeneti fertőtlenítés (elutasítja az útvonal bejárását/vezérlő karaktereket) és a modellinformáció-feloldás aszinkron alias getter támogatással. | +| `accountFallback.ts` | Rate-limit-kezelés: exponenciális visszalépés (1s → 2mp → 4mp → max 2perc), fiókhűtés-kezelés, hibabesorolás (mely hibák váltanak ki visszaesést, illetve nem). | +| `tokenRefresh.ts` | OAuth-token frissítése **minden szolgáltatóhoz**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + másodpilóta kettős token), Kiro (AWS SSO OIDC + Social Auth). Tartalmazza a menet közbeni ígéret-deduplikációs gyorsítótárat és az újrapróbálkozást exponenciális visszalépéssel. | +| `combo.ts` | **Kombinált modellek**: tartalék modellek láncai. Ha az A modell meghibásodik egy tartalék jogosultsági hibával, próbálja ki a B, majd a C modellt stb. A tényleges upstream állapotkódokat adja vissza. | +| `usage.ts` | Lekéri a kvóta/használati adatokat a szolgáltatói API-któl (GitHub másodpilóta kvóták, antigravitációs modellkvóták, Codex sebességkorlátok, Kiro használati lebontások, Claude beállítások). | +| `accountSelector.ts` | Intelligens számlakiválasztás pontozási algoritmussal: figyelembe veszi a prioritást, az egészségi állapotot, a körmérkőzéses pozíciót és a lemondási állapotot, hogy kiválaszthassa az optimális fiókot minden egyes kérelemhez. | +| `contextManager.ts` | Kéréskörnyezet-életciklus-kezelés: kérésenkénti kontextusobjektumokat hoz létre és nyomon követ metaadatokkal (kérelemazonosító, időbélyegek, szolgáltatói információk) hibakereséshez és naplózáshoz. | +| `ipFilter.ts` | IP-alapú hozzáférés-vezérlés: támogatja az engedélyezési listát és a tiltólistát. Az API-kérelmek feldolgozása előtt ellenőrzi az ügyfél IP-címét a konfigurált szabályok szerint. | +| `sessionManager.ts` | Munkamenetkövetés ügyfél ujjlenyomattal: nyomon követi az aktív munkameneteket kivonatolt ügyfélazonosítók segítségével, figyeli a kérések számát, és munkamenet-metrikákat biztosít. | +| `signatureCache.ts` | Aláírás-alapú deduplikációs gyorsítótár kérése: megakadályozza a duplikált kéréseket azáltal, hogy gyorsítótárazza a legutóbbi kérelmek aláírásait, és egy időablakon belül visszaadja a gyorsítótárazott válaszokat az azonos kérésekre. | +| `systemPrompt.ts` | Globális rendszerprompt injekció: minden kérés elé vagy hozzáfűz egy konfigurálható rendszerpromptot, szolgáltatónkénti kompatibilitáskezeléssel. | +| `thinkingBudget.ts` | Érvelési jogkivonat-költségvetés-kezelés: támogatja az áthárítást, az automatikus (szalagos gondolkodási konfiguráció), az egyéni (fix költségvetésű) és az adaptív (bonyolultságra skálázott) módokat a gondolkodási/érvelési tokenek vezérléséhez. | +| `wildcardRouter.ts` | Helyettesítő karakterminta-útválasztás: a helyettesítő karaktermintákat (pl. `*/claude-*`) konkrét szolgáltató/modell párokra oldja fel a rendelkezésre állás és a prioritás alapján. | + +#### Token frissítési deduplikáció + +```mermaid +sequenceDiagram + participant R1 as Request 1 + participant R2 as Request 2 + participant Cache as refreshPromiseCache + participant OAuth as OAuth Provider + + R1->>Cache: getAccessToken("gemini", token) + Cache->>Cache: No in-flight promise + Cache->>OAuth: Start refresh + R2->>Cache: getAccessToken("gemini", token) + Cache->>Cache: Found in-flight promise + Cache-->>R2: Return existing promise + OAuth-->>Cache: New access token + Cache-->>R1: New access token + Cache-->>R2: Same access token (shared) + Cache->>Cache: Delete cache entry +``` + +#### Fiók tartalék állapotú gép + +```mermaid +stateDiagram-v2 + [*] --> Active + Active --> Error: Request fails (401/429/500) + Error --> Cooldown: Apply backoff + Cooldown --> Active: Cooldown expires + Active --> Active: Request succeeds (reset backoff) + + state Error { + [*] --> ClassifyError + ClassifyError --> ShouldFallback: Rate limit / Auth / Transient + ClassifyError --> NoFallback: 400 Bad Request + } + + state Cooldown { + [*] --> ExponentialBackoff + ExponentialBackoff: Level 0 = 1s + ExponentialBackoff: Level 1 = 2s + ExponentialBackoff: Level 2 = 4s + ExponentialBackoff: Max = 2min + } +``` + +#### Kombinált modelllánc + +```mermaid +flowchart LR + A["Request with\ncombo model"] --> B["Model A"] + B -->|"2xx Success"| C["Return response"] + B -->|"429/401/500"| D{"Fallback\neligible?"} + D -->|Yes| E["Model B"] + D -->|No| F["Return error"] + E -->|"2xx Success"| C + E -->|"429/401/500"| G{"Fallback\neligible?"} + G -->|Yes| H["Model C"] + G -->|No| F + H -->|"2xx Success"| C + H -->|"Fail"| I["All failed →\nReturn last status"] +``` + +--- + +### 4.5 Fordító (`open-sse/translator/`) + +A **formátumfordító motor** egy önregisztráló bővítményrendszerrel. + +#### Építészet + +```mermaid +graph TD + subgraph "Request Translation" + A["Claude → OpenAI"] + B["Gemini → OpenAI"] + C["Antigravity → OpenAI"] + D["OpenAI Responses → OpenAI"] + E["OpenAI → Claude"] + F["OpenAI → Gemini"] + G["OpenAI → Kiro"] + H["OpenAI → Cursor"] + end + + subgraph "Response Translation" + I["Claude → OpenAI"] + J["Gemini → OpenAI"] + K["Kiro → OpenAI"] + L["Cursor → OpenAI"] + M["OpenAI → Claude"] + N["OpenAI → Antigravity"] + O["OpenAI → Responses"] + end +``` + +| Címtár | Fájlok | Leírás | +| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 fordító | A kéréstörzsek átalakítása formátumok között. Az importáláskor minden fájl önmagát regisztrálja a `register(from, to, fn)` segítségével. | +| `response/` | 7 fordító | A streaming válaszdarabok konvertálása formátumok között. Kezeli az SSE eseménytípusokat, gondolkodási blokkokat, eszközhívásokat. | +| `helpers/` | 6 segítő | Megosztott segédprogramok: `claudeHelper` (rendszerkérdések kibontása, gondolkodási konfiguráció), `geminiHelper` (alkatrészek/tartalom-leképezés), `openaiHelper` (formátumszűrés), `toolCallHelper`), _TOK_K_, hiányzó válasz_OM_8 `responsesApiHelper`. | +| `index.ts` | — | Fordítómotor: `translateRequest()`, `translateResponse()`, állapotkezelés, nyilvántartás. | +| `formats.ts` | — | Formátumkonstansok: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`_, _.EN*92_NI, *. | + +#### Kulcstervezés: Önregisztráló beépülő modulok + +```javascript +// Each translator file calls register() on import: +import { register } from "../index.js"; +register("claude", "openai", translateClaudeToOpenAI); + +// The index.js imports all translator files, triggering registration: +import "./request/claude-to-openai.js"; // ← self-registers +``` + +--- + +### 4.6 Utils (`open-sse/utils/`) + +| Fájl | Cél | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | Hibaválasz kiépítése (OpenAI-kompatibilis formátum), felfelé irányuló hibaelemzés, Antigravitációs újrapróbálkozási idő kivonat a hibaüzenetekből, SSE hibaadatfolyam. | +| `stream.ts` | **SSE Transform Stream** – a mag adatfolyam-folyamat. Két mód: `TRANSLATE` (teljes formátumú fordítás) és `PASSTHROUGH` (használat normalizálása + kibontása). Kezeli a darabok pufferelését, a felhasználás becslését, a tartalom hosszának követését. A folyamonkénti kódoló/dekódoló példányok elkerülik a megosztott állapotot. | +| `streamHelpers.ts` | Alacsony szintű SSE-segédprogramok: `parseSSELine` (szóköz-toleráns), `hasValuableContent` (üres darabokat szűr az OpenAI/Claude/Gemini számára), `fixInvalidId`, \_\_OMNI_TOKEN_1SE-3_TOKEN_1SE-serialization `perf_metrics` tisztítás). | +| `usageTracking.ts` | Tokenhasználati kinyerés bármilyen formátumból (Claude/OpenAI/Gemini/Responses), becslés külön eszköz/üzenet char-per-token arányokkal, puffer hozzáadása (2000 token biztonsági ráhagyás), formátum-specifikus mezőszűrés, konzolnaplózás ANSI színekkel. | +| `requestLogger.ts` | Fájlalapú kérések naplózása (feliratkozás a `ENABLE_REQUEST_LOGS=true` segítségével). Munkamenet mappákat hoz létre számozott fájlokkal: `1_req_client.json` → `7_res_client.txt`. Minden I/O aszinkron (gyújt és felejt). Elfedi az érzékeny fejléceket. | +| `bypassHandler.ts` | Elfogja a Claude CLI meghatározott mintáit (címkivonás, bemelegítés, számlálás), és hamis válaszokat ad vissza anélkül, hogy bármelyik szolgáltatót is felhívná. Támogatja a streaminget és a nem adatfolyamot egyaránt. Szándékosan a Claude CLI hatókörére korlátozva. | +| `networkProxy.ts` | Feloldja egy adott szolgáltató kimenő proxy URL-jét elsőbbséggel: szolgáltató-specifikus konfiguráció → globális konfiguráció → környezeti változók (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Támogatja a `NO_PROXY` kizárásokat. Gyorsítótár konfiguráció 30 másodpercig. | + +#### SSE Streaming Pipeline + +```mermaid +flowchart TD + A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"] + B --> C["Buffer lines\n(split on newline)"] + C --> D["parseSSELine()\n(trim whitespace, parse JSON)"] + D --> E{"Mode?"} + E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"] + E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"] + F --> H["hasValuableContent()\nfilter empty chunks"] + G --> H + H -->|"Has content"| I["extractUsage()\ntrack token counts"] + H -->|"Empty"| J["Skip chunk"] + I --> K["formatSSE()\nserialize + clean perf_metrics"] + K --> L["TextEncoder\n(per-stream instance)"] + L --> M["Enqueue to\nclient stream"] + + style A fill:#f9f,stroke:#333 + style M fill:#9f9,stroke:#333 +``` + +#### Kérjen naplózó munkamenet-struktúrát + +``` +logs/ +└── claude_gemini_claude-sonnet_20260208_143045/ + ├── 1_req_client.json ← Raw client request + ├── 2_req_source.json ← After initial conversion + ├── 3_req_openai.json ← OpenAI intermediate format + ├── 4_req_target.json ← Final target format + ├── 5_res_provider.txt ← Provider SSE chunks (streaming) + ├── 5_res_provider.json ← Provider response (non-streaming) + ├── 6_res_openai.txt ← OpenAI intermediate chunks + ├── 7_res_client.txt ← Client-facing SSE chunks + └── 6_error.json ← Error details (if any) +``` + +--- + +### 4.7 Alkalmazási réteg (`src/`) + +| Címtár | Cél | +| ------------- | -------------------------------------------------------------------------------------------- | +| `src/app/` | Webes felhasználói felület, API-útvonalak, Express köztes szoftver, OAuth visszahíváskezelők | +| `src/lib/` | Adatbázis-hozzáférés (`localDb.ts`, `usageDb.ts`), hitelesítés, megosztott | +| `src/mitm/` | Man-in-the-middle proxy segédprogramok a szolgáltatói forgalom lehallgatásához | +| `src/models/` | Adatbázismodell-definíciók | +| `src/shared/` | Az open-sse függvények körüli burkolók (szolgáltató, adatfolyam, hiba stb.) | +| `src/sse/` | SSE végpontkezelők, amelyek az open-sse könyvtárat az Express útvonalakhoz kötik | +| `src/store/` | Alkalmazás állapotkezelés | + +#### Figyelemre méltó API-útvonalak + +| Útvonal | Módszerek | Cél | +| --------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD egyedi modellekhez szolgáltatónként | +| `/api/models/catalog` | GET | Összesített katalógus az összes modellről (csevegés, beágyazás, kép, egyéni) szolgáltató szerint csoportosítva | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchikus kimenő proxykonfiguráció (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Ellenőrzi a proxy-kapcsolatot, és visszaadja a nyilvános IP-címet/latenciát | +| `/v1/providers/[provider]/chat/completions` | POST | Dedikált szolgáltatónkénti csevegés-befejezések modellellenőrzéssel | +| `/v1/providers/[provider]/embeddings` | POST | Dedikált szolgáltatónkénti beágyazások modellellenőrzéssel | +| `/v1/providers/[provider]/images/generations` | POST | Dedikált szolgáltatónkénti képgenerálás modellellenőrzéssel | +| `/api/settings/ip-filter` | GET/PUT | IP engedélyezési lista/blokklista kezelése | +| `/api/settings/thinking-budget` | GET/PUT | Indoklási token költségkeret-konfiguráció (passthrough/auto/custom/adaptative) | +| `/api/settings/system-prompt` | GET/PUT | Globális rendszer azonnali befecskendezése minden kérelemhez | +| `/api/sessions` | GET | Aktív munkamenet-követés és mérőszámok | +| `/api/rate-limits` | GET | számlánkénti kamatláb korlát állapota | + +--- + +## 5. Kulcsfontosságú tervezési minták + +### 5.1 Hub-and-Spoke fordítás + +Minden formátum az **OpenAI formátumon keresztül történik, mint a hub**. Új szolgáltató hozzáadásához csak **egy pár** fordítót kell írni (OpenAI-ra/OpenAI-ról), N párra nem. + +### 5.2 Végrehajtó stratégia minta + +Minden szolgáltatónak van egy dedikált végrehajtó osztálya, amely a `BaseExecutor`-ból öröklődik. A `executors/index.ts` gyára futás közben választja ki a megfelelőt. + +### 5.3 Önregisztráló beépülő modulrendszer + +A fordítómodulok regisztrálják magukat az importáláskor a `register()` címen. Új fordító hozzáadása csak egy fájl létrehozását és importálását jelenti. + +### 5.4 Fiók visszaállítása exponenciális visszalépéssel + +Amikor egy szolgáltató visszaadja a 429/401/500 számot, a rendszer átválthat a következő fiókra, exponenciális lehűtést alkalmazva (1 mp → 2 mp → 4 mp → max 2 perc). + +### 5.5 kombinált modellláncok + +A „kombó” több `provider/model` karakterláncot csoportosít. Ha az első sikertelen, akkor automatikusan visszaáll a következőre. + +### 5.6 Állapotalapú adatfolyam-fordítás + +A válaszfordítás a `initState()` mechanizmuson keresztül fenntartja az állapotot az SSE-darabokon (gondolkodási blokk követése, eszközhívás-gyűjtés, tartalomblokk indexelése). + +### 5.7 Használati biztonsági puffer + +Egy 2000 tokenből álló puffert adunk a jelentett használathoz, hogy megakadályozzuk, hogy az ügyfelek elérjék a kontextusablak korlátait a rendszerkérések és a formátumfordítás miatti többletterhelés miatt. + +--- + +## 6. Támogatott formátumok + +| Formátum | Irány | Azonosító | +| ----------------------- | ------------ | ------------------ | +| OpenAI Chat befejezések | forrás + cél | `openai` | +| OpenAI Responses API | forrás + cél | `openai-responses` | +| Antropikus Claude | forrás + cél | `claude` | +| Google Gemini | forrás + cél | `gemini` | +| Google Gemini CLI | csak cél | `gemini-cli` | +| Antigravitáció | forrás + cél | `antigravity` | +| AWS Kiro | csak cél | `kiro` | +| Kurzor | csak cél | `cursor` | + +--- + +## 7. Támogatott szolgáltatók + +| Szolgáltató | Hitelesítési módszer | Végrehajtó | Főbb megjegyzések | +| ------------------------ | --------------------------- | --------------- | ---------------------------------------------------- | +| Antropikus Claude | API-kulcs vagy OAuth | Alapértelmezett | `x-api-key` fejlécet használ | +| Google Gemini | API-kulcs vagy OAuth | Alapértelmezett | `x-goog-api-key` fejlécet használ | +| Google Gemini CLI | OAuth | GeminiCLI | `streamGenerateContent` végpontot használ | +| Antigravitáció | OAuth | Antigravitáció | Több URL-es tartalék, egyéni újrapróbálkozás | +| OpenAI | API kulcs | Alapértelmezett | Normál hordozó hitelesítés | +| Codex | OAuth | Codex | Rendszerutasításokat ad be, irányítja a gondolkodást | +| GitHub másodpilóta | OAuth + másodpilóta token | Github | Kettős token, VSCode fejléc utánzás | +| Kiro (AWS) | AWS SSO OIDC vagy Social | Kiro | Bináris EventStream elemzés | +| Kurzor IDE | Ellenőrzőösszeg hitelesítés | Kurzor | Protobuf kódolás, SHA-256 ellenőrző összegek | +| Qwen | OAuth | Alapértelmezett | Normál hitelesítés | +| iFlow | OAuth (alap + hordozó) | Alapértelmezett | Kettős hitelesítési fejléc | +| OpenRouter | API kulcs | Alapértelmezett | Normál hordozó hitelesítés | +| GLM, Kimi, MiniMax | API kulcs | Alapértelmezett | Claude-kompatibilis, használja a `x-api-key` | +| `openai-compatible-*` | API kulcs | Alapértelmezett | Dinamikus: bármely OpenAI-kompatibilis végpont | +| `anthropic-compatible-*` | API kulcs | Alapértelmezett | Dinamikus: bármely Claude-kompatibilis végpont | + +--- + +## 8. Adatfolyam összefoglalása + +### Streaming kérés + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor\nbuildUrl + buildHeaders"] + D --> E["fetch(providerURL)"] + E --> F["createSSEStream()\nTRANSLATE mode"] + F --> G["parseSSELine()"] + G --> H["translateResponse()\ntarget → OpenAI → source"] + H --> I["extractUsage()\n+ addBuffer"] + I --> J["formatSSE()"] + J --> K["Client receives\ntranslated SSE"] + K --> L["logUsage()\nsaveRequestUsage()"] +``` + +### Nem streamelési kérelem + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor.execute()"] + D --> E["translateResponse()\ntarget → OpenAI → source"] + E --> F["Return JSON\nresponse"] +``` + +### Bypass Flow (Claude CLI) + +```mermaid +flowchart LR + A["Claude CLI request"] --> B{"Match bypass\npattern?"} + B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] + B -->|"No match"| D["Normal flow"] + C --> E["Translate to\nsource format"] + E --> F["Return without\ncalling provider"] +``` diff --git a/docs/i18n/hu/FEATURES.md b/docs/i18n/hu/FEATURES.md new file mode 100644 index 00000000..f3defd1d --- /dev/null +++ b/docs/i18n/hu/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — Irányítópult-funkciók galériája + +🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) + +Vizuális útmutató az OmniRoute irányítópult minden részéhez. + +--- + +## 🔌 Szolgáltatók + +AI-szolgáltatói kapcsolatok kezelése: OAuth-szolgáltatók (Claude Code, Codex, Gemini CLI), API-kulcs-szolgáltatók (Groq, DeepSeek, OpenRouter) és ingyenes szolgáltatók (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨 kombók + +Hozzon létre modell-útválasztási kombókat 6 stratégiával: kitöltés először, körbefutó, kettős választási lehetőség, véletlenszerű, legkevésbé használt és költségoptimalizált. Mindegyik kombó több modellt láncol automatikus visszaállítással. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Analytics + +Átfogó használati elemzés token-fogyasztással, költségbecslésekkel, tevékenységi hőtérképekkel, heti elosztási diagramokkal és szolgáltatónkénti lebontásokkal. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Rendszer egészsége + +Valós idejű megfigyelés: üzemidő, memória, verzió, késleltetési százalékok (p50/p95/p99), gyorsítótár-statisztika és szolgáltatói megszakító állapotok. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Fordítói Játszótér + +Négy mód az API-fordítások hibakeresésére: **Playground** (formátum-átalakító), **Chat Tester** (élő kérések), **Test Bench** (kötegelt tesztek) és **Élő figyelő** (valós idejű adatfolyam). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Beállítások + +Általános beállítások, rendszertárolás, biztonsági mentések kezelése (export/import adatbázis), megjelenés (sötét/világos mód), biztonság (beleértve az API végpontvédelmet és az egyéni szolgáltatók blokkolását), útválasztás, rugalmasság és speciális konfiguráció. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 CLI eszközök + +Egykattintásos konfiguráció az AI kódoló eszközökhöz: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code és Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Kérelemnaplók + +Valós idejű kérések naplózása szolgáltató, modell, fiók és API kulcs szerinti szűréssel. Megjeleníti az állapotkódokat, a tokenhasználatot, a várakozási időt és a válasz részleteit. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 API végpont + +Az Ön egységes API-végpontja a képességek lebontásával: csevegési befejezések, beágyazások, képgenerálás, újrarangsorolás, hangátírás és regisztrált API-kulcsok. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/hu/TROUBLESHOOTING.md b/docs/i18n/hu/TROUBLESHOOTING.md new file mode 100644 index 00000000..59045dee --- /dev/null +++ b/docs/i18n/hu/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Hibaelhárítás + +🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) + +Az OmniRoute gyakori problémái és megoldásai. + +--- + +## Gyors javítások + +| Probléma | Megoldás | +| ----------------------------------- | ----------------------------------------------------------------------------- | ---------- | +| Az első bejelentkezés nem működik | `INITIAL_PASSWORD` ellenőrzése itt: `.env` (alapértelmezett: `123456`) | +| A műszerfal rossz porton nyílik meg | `PORT=20128` és `NEXT_PUBLIC_BASE_URL=http://localhost:20128` beállítása | +| Nincsenek kérésnaplók a `logs/` | alatt `ENABLE_REQUEST_LOGS=true` | beállítása | +| EACCES: engedély megtagadva | `DATA_DIR=/path/to/writable/dir` beállítása a `~/.omniroute` felülbírálásához | +| Az útválasztási stratégia nem menti | Frissítés v1.4.11+ verzióra (Zod-séma javítása a beállítások fennmaradásához) | + +--- + +## Szolgáltatói problémák + +### "A nyelvi modell nem adott üzenetet" + +**Ok:** A szolgáltatói kvóta kimerült. + +**Javítás:** + +1. Ellenőrizze az irányítópult kvótakövetőjét +2. Használjon kombót tartalék szintekkel +3. Váltson olcsóbb/ingyenes szintre + +### Díjkorlátozás + +**Ok:** Az előfizetési kvóta kimerült. + +**Javítás:** + +- Tartalék hozzáadása: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Használja a GLM/MiniMax-ot olcsó tartalékként + +### OAuth-token lejárt + +Az OmniRoute automatikusan frissíti a tokeneket. Ha a problémák továbbra is fennállnak: + +1. Irányítópult → Szolgáltató → Újracsatlakozás +2. Törölje és adja hozzá újra a szolgáltatói kapcsolatot + +--- + +## Felhővel kapcsolatos problémák + +### Felhőszinkronizálási hibák + +1. Ellenőrizze, hogy a futó példány `BASE_URL` pontja (pl. `http://localhost:20128`) +2. Igazoljon `CLOUD_URL` pontot a felhő-végponthoz (pl. `https://omniroute.dev`) +3. Tartsa az `NEXT_PUBLIC_*` értékeket a szerveroldali értékekkel összhangban + +### Felhő `stream=false` 500-at tér vissza + +**Tünet:** `Unexpected token 'd'...` a felhő-végponton nem streaming hívásokhoz. + +**Ok:** Az Upstream SSE hasznos adatot ad vissza, miközben az ügyfél a JSON-t várja. + +**Megkerülő megoldás:** Használja a `stream=true`-t a felhőalapú közvetlen hívásokhoz. A helyi futási környezet tartalmazza az SSE→JSON tartalékot. + +### A felhő azt mondja, hogy csatlakoztatva van, de "érvénytelen API-kulcs" + +1. Hozzon létre egy új kulcsot a helyi irányítópultról (`/api/keys`) +2. Futtassa a felhőszinkronizálást: Engedélyezze a Felhőt → Szinkronizálás most +3. A régi/nem szinkronizált kulcsok továbbra is visszaadhatják a következőt: `401` a felhőben + +--- + +## Docker problémák + +### A CLI eszköz azt mutatja, hogy nincs telepítve + +1. Ellenőrizze a futásidejű mezőket: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Hordozható módhoz: használja a `runner-cli` képcélt (csomagolt CLI-k) +3. Gazda beillesztési módhoz: állítsa be a `CLI_EXTRA_PATHS` értéket, és csatlakoztassa a gazdagép bin könyvtárát csak olvashatóként +4. Ha `installed=true` és `runnable=false`: bináris fájl található, de az állapotellenőrzés sikertelen + +### Gyors futásidejű érvényesítés + +```bash +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}' +``` + +--- + +## Költségproblémák + +### Magas költségek + +1. Ellenőrizze a használati statisztikákat az Irányítópult → Használat menüpontban +2. Állítsa át az elsődleges modellt GLM/MiniMax-ra +3. Használjon ingyenes réteget (Gemini CLI, iFlow) a nem kritikus feladatokhoz +4. Állítsa be a költségkereteket API-kulcsonként: Irányítópult → API-kulcsok → Költségvetés + +--- + +## Hibakeresés + +### Kérelemnaplók engedélyezése + +Állítsa be az `ENABLE_REQUEST_LOGS=true` értéket a `.env` fájlban. A naplók a `logs/` könyvtárban jelennek meg. + +### Ellenőrizze a szolgáltató állapotát + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Futásidejű tárhely + +- Fő állapot: `${DATA_DIR}/db.json` (szolgáltatók, kombinációk, álnevek, kulcsok, beállítások) +- Használat: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Kérelemnaplók: `/logs/...` (amikor `ENABLE_REQUEST_LOGS=true`) + +--- + +## Áramköri megszakítóval kapcsolatos problémák + +### A szolgáltató NYITOTT állapotban ragadt + +Amikor egy szolgáltató megszakítója NYITVA van, a kérések blokkolva vannak, amíg a leállás le nem jár. + +**Javítás:** + +1. Lépjen az **Irányítópult → Beállítások → Rugalmasság** menüpontra. +2. Ellenőrizze az érintett szolgáltató megszakítókártyáját +3. Kattintson a **Reset All** elemre az összes megszakító törléséhez, vagy várja meg, amíg a lehűlés lejár +4. A visszaállítás előtt ellenőrizze, hogy a szolgáltató valóban elérhető-e + +### A szolgáltató folyamatosan kioldja a megszakítót + +Ha egy szolgáltató ismételten NYITOTT állapotba lép: + +1. Ellenőrizze a **Irányítópult → Állapot → Szolgáltató állapota** menüpontban a hibamintát +2. Lépjen a **Beállítások → Ellenállás → Szolgáltatói profilok** menüpontra, és növelje a meghibásodási küszöböt. +3. Ellenőrizze, hogy a szolgáltató megváltoztatta-e az API-korlátokat, vagy nem igényel-e újbóli hitelesítést +4. Tekintse át a késleltetési telemetriát – a magas késleltetés időtúllépésen alapuló hibákat okozhat + +--- + +## Hangátírási problémák + +### "Nem támogatott modell" hiba + +- Győződjön meg arról, hogy a megfelelő előtagot használja: `deepgram/nova-3` vagy `assemblyai/best` +- Ellenőrizze, hogy a szolgáltató csatlakoztatva van-e az **Irányítópult → Szolgáltatók** menüpontban. + +### Az átírás üresen tér vissza, vagy meghiúsul + +- Ellenőrizze a támogatott hangformátumokat: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Ellenőrizze, hogy a fájl mérete a szolgáltatói korlátokon belül van (általában < 25 MB) +- Ellenőrizze a szolgáltatói API kulcs érvényességét a szolgáltatói kártyán + +--- + +## Fordítói hibakeresés + +Használja az **Irányítópult → Fordító** lehetőséget a formátumfordítási problémák elhárításához: + +| mód | Mikor kell használni | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **Játszótér** | Hasonlítsa össze a bemeneti/kimeneti formátumokat egymás mellett – illesszen be egy hibás kérést, hogy megtudja, hogyan fordítja le | +| **Csevegés tesztelő** | Küldjön élő üzeneteket, és ellenőrizze a teljes kérés/válasz hasznos adatot, beleértve a fejléceket | +| **Próbapad** | Futtasson kötegelt teszteket a formátumkombinációk között, hogy megtudja, mely fordítások hibásak | +| **Élő monitor** | Nézze meg a valós idejű kérések folyamatát az időszakos fordítási problémák észleléséhez | + +### Gyakori formátumproblémák + +- **Nem jelennek meg a gondolkodási címkék** — Ellenőrizze, hogy a célszolgáltató támogatja-e a gondolkodást és a gondolkodási költségvetés beállítását +- **Eszközhívások megszakítása** — Egyes formátumfordítások eltávolíthatják a nem támogatott mezőket; ellenőrizze Playground módban +- **Rendszerprompt hiányzik** — Claude és Gemini fogantyúrendszere eltérő módon szól; ellenőrizze a fordítás kimenetét +- **Az SDK nyers karakterláncot ad vissza az objektum helyett** - Javítva az 1.1.0 verzióban: a válasz-fertőtlenítő mostantól eltávolítja azokat a nem szabványos mezőket (`x_groq`, `usage_breakdown` stb.), amelyek az OpenAI SDK Pydantic ellenőrzési hibáit okozzák +- **GLM/ERNIE elutasítja a `system` szerepkört** - Javítva az 1.1.0 verzióban: a szerepnormalizáló automatikusan egyesíti a rendszerüzeneteket felhasználói üzenetekké az inkompatibilis modelleknél +- **`developer` szerepkör nem ismerhető fel** - Javítva az 1.1.0 verzióban: automatikusan `system`-ra konvertálva a nem OpenAI szolgáltatók számára +- **`json_schema` nem működik a Geminivel** - Javítva az 1.1.0-s verzióban: `response_format` mostantól Gemini `responseMimeType` + `responseSchema` + +--- + +## Rugalmassági beállítások + +### Az automatikus sebességkorlátozás nem aktiválódik + +- Az automatikus díjkorlát csak az API-kulcs-szolgáltatókra vonatkozik (nem az OAuth-ra/előfizetésre) +- Ellenőrizze, hogy a **Beállítások → Ellenállás → Szolgáltatói profilok** engedélyezve van-e az automatikus díjkorlátozás +- Ellenőrizze, hogy a szolgáltató `429` állapotkódokat vagy `Retry-After` fejlécet ad-e vissza + +### Exponenciális visszalépés hangolása + +A szolgáltatói profilok az alábbi beállításokat támogatják: + +- **Alapkésleltetés** - Kezdeti várakozási idő az első hiba után (alapértelmezett: 1 mp) +- **Maximális késleltetés** - Maximális várakozási idő (alapértelmezett: 30 mp) +- **Szorzó** - Mennyivel növelhető a késleltetés egy egymást követő hiba esetén (alapértelmezett: 2x) + +### Mennydörgés elleni csorda + +Amikor sok egyidejű kérés ér egy korlátozott sebességű szolgáltatót, az OmniRoute mutex + automatikus sebességkorlátozást használ a kérések sorba rendezésére és a lépcsőzetes hibák megelőzésére. Ez automatikus az API-kulcs-szolgáltatók számára. + +--- + +## Még mindig elakadt? + +- **GitHub-problémák**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architektúra**: A belső részletekért lásd: [**OMNI_TOKEN_55**](ARCHITECTURE.md) +- **API-referencia**: Lásd: [**OMNI_TOKEN_56**](API_REFERENCE.md) az összes végponthoz +- **Egészségügyi irányítópult**: Az **Irányítópult → Egészség** menüpontban ellenőrizze a valós idejű rendszerállapotot +- **Fordító**: Használja az **Irányítópult → Fordító** lehetőséget a formátumhibák elhárításához diff --git a/docs/i18n/hu/USER_GUIDE.md b/docs/i18n/hu/USER_GUIDE.md new file mode 100644 index 00000000..c34e9c95 --- /dev/null +++ b/docs/i18n/hu/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Használati útmutató + +🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) + +Teljes útmutató a szolgáltatók konfigurálásához, kombinációk létrehozásához, a CLI-eszközök integrálásához és az OmniRoute telepítéséhez. + +--- + +## Tartalomjegyzék + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [Provider Setup](#-provider-setup) +- [CLI Integration](#-cli-integration) +- [Deployment](#-deployment) +- [Available Models](#-available-models) +- [Advanced Features](#-advanced-features) + +--- + +## 💰 Árazás egy pillantásra + +| Tier | Szolgáltató | Költség | Kvóta visszaállítása | Legjobb a | +| ----------------- | ------------------ | ----------------------- | ---------------------- | ------------------------------- | +| **💳 ELŐFIZETÉS** | Claude Code (Pro) | 20 USD/hó | 5 óra + heti | Már előfizetett | +| | Codex (Plus/Pro) | 20-200 USD/hó | 5 óra + heti | OpenAI felhasználók | +| | Gemini CLI | **INGYENES** | 180 000/hó + 1 000/nap | Mindenki! | +| | GitHub másodpilóta | 10-19 USD/hó | Havi | GitHub felhasználók | +| **🔑 API KULCS** | DeepSeek | Fizetés használatonként | Nincs | Olcsó érvelés | +| | Groq | Fizetés használatonként | Nincs | Ultragyors következtetés | +| | xAI (Grok) | Fizetés használatonként | Nincs | Grok 4 okfejtés | +| | Mistral | Fizetés használatonként | Nincs | EU-ban működő modellek | +| | Zavartság | Fizetés használatonként | Nincs | Keresés-bővített | +| | Együtt AI | Fizetés használatonként | Nincs | Nyílt forráskódú modellek | +| | Tűzijáték AI | Fizetés használatonként | Nincs | Gyors FLUX képek | +| | Cerebrák | Fizetés használatonként | Nincs | Ostya léptékű sebesség | +| | Cohere | Fizetés használatonként | Nincs | Parancs R+ RAG | +| | NVIDIA NIM | Fizetés használatonként | Nincs | Vállalati modellek | +| **💰 OLCSÓ** | GLM-4.7 | 0,6 USD/1M | Naponta 10:00 | Költségvetési biztonsági mentés | +| | MiniMax M2.1 | 0,2 USD/1M | 5 órás gurulás | Legolcsóbb lehetőség | +| | Kimi K2 | 9 USD/hó lakás | 10 millió token/hó | Előrelátható költség | +| **🆓 INGYENES** | iFlow | $0 | Korlátlan | 8 modell ingyenes | +| | Qwen | $0 | Korlátlan | 3 modell ingyenes | +| | Kiro | $0 | Korlátlan | Claude ingyen | + +**💡 Pro tipp:** Kezdje a Gemini CLI-vel (180 000 ingyenes/hónap) + iFlow (korlátlan ingyenes) kombináció = 0 USD költség! + +--- + +## 🎯 Használati esetek + +### 1. eset: "Claude Pro előfizetésem van" + +**Probléma:** A kvóta lejár, kihasználatlanul, sebességkorlátozások erős kódolás közben + +``` +Combo: "maximize-claude" + 1. cc/claude-opus-4-6 (use subscription fully) + 2. glm/glm-4.7 (cheap backup when quota out) + 3. if/kimi-k2-thinking (free emergency fallback) + +Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total +vs. $20 + hitting limits = frustration +``` + +### 2. eset: "Nulla költséget akarok" + +**Probléma:** Nem engedheti meg magának az előfizetést, megbízható mesterséges intelligencia kódolásra van szüksége + +``` +Combo: "free-forever" + 1. gc/gemini-3-flash (180K free/month) + 2. if/kimi-k2-thinking (unlimited free) + 3. qw/qwen3-coder-plus (unlimited free) + +Monthly cost: $0 +Quality: Production-ready models +``` + +### 3. eset: "24 órás kódolásra van szükségem, megszakítás nélkül" + +**Probléma:** Határidők, nem engedheti meg magának az állásidőt + +``` +Combo: "always-on" + 1. cc/claude-opus-4-6 (best quality) + 2. cx/gpt-5.2-codex (second subscription) + 3. glm/glm-4.7 (cheap, resets daily) + 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) + 5. if/kimi-k2-thinking (free unlimited) + +Result: 5 layers of fallback = zero downtime +Monthly cost: $20-200 (subscriptions) + $10-20 (backup) +``` + +### 4. eset: "INGYENES AI-t akarok az OpenClawban" + +**Probléma:** AI-asszisztens szükséges az üzenetküldő alkalmazásokhoz, teljesen ingyenes + +``` +Combo: "openclaw-free" + 1. if/glm-4.7 (unlimited free) + 2. if/minimax-m2.1 (unlimited free) + 3. if/kimi-k2-thinking (unlimited free) + +Monthly cost: $0 +Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... +``` + +--- + +## 📖 Szolgáltató beállítása + +### 🔐 Előfizetéses szolgáltatók + +#### Claude Code (Pro/Max) + +```bash +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking + +Models: + cc/claude-opus-4-6 + cc/claude-sonnet-4-5-20250929 + cc/claude-haiku-4-5-20251001 +``` + +**Profi tipp:** Használja az Opust összetett feladatokhoz, a Sonnet pedig a sebességhez. Az OmniRoute nyomkövetési kvóta modellenként! + +#### OpenAI Codex (Plus/Pro) + +```bash +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset + +Models: + cx/gpt-5.2-codex + cx/gpt-5.1-codex-max +``` + +#### Gemini CLI (INGYENES 180 000/hó!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Legjobb érték:** Hatalmas ingyenes szint! Használja ezt a fizetett szintek előtt. + +#### GitHub másodpilóta + +```bash +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) + +Models: + gh/gpt-5 + gh/claude-4.5-sonnet + gh/gemini-3-pro +``` + +### 💰 Olcsó szolgáltatók + +#### GLM-4.7 (napi visszaállítás, 0,6 USD/1 millió) + +1. Regisztráljon: [Zhipu AI](https://open.bigmodel.cn/) +2. Szerezze be az API-kulcsot a Coding Plan-ból +3. Irányítópult → API-kulcs hozzáadása: Szolgáltató: `glm`, API-kulcs: `your-key` + +**Használat:** `glm/glm-4.7` — **Profi tipp:** A kódolási terv 3-szoros kvótát kínál 1/7 költséggel! Visszaállítás naponta 10:00. + +#### MiniMax M2.1 (5 óra visszaállítás, 0,20 USD/1 millió) + +1. Regisztráljon: [MiniMax](https://www.minimax.io/) +2. API-kulcs lekérése → Irányítópult → API-kulcs hozzáadása + +**Használat:** `minimax/MiniMax-M2.1` — **Profi tipp:** A legolcsóbb lehetőség hosszú kontextushoz (1 millió token)! + +#### Kimi K2 (9 USD/hó lakás) + +1. Feliratkozás: [Moonshot AI](https://platform.moonshot.ai/) +2. API-kulcs lekérése → Irányítópult → API-kulcs hozzáadása + +**Használat:** `kimi/kimi-latest` — **Profi tipp:** Fix 9 USD/hó 10 millió tokenek esetén = 0,90 USD/1 millió tényleges költség! + +### 🆓 INGYENES szolgáltatók + +#### iFlow (8 INGYENES modell) + +```bash +Dashboard → Connect iFlow → OAuth login → Unlimited usage + +Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 +``` + +#### Qwen (3 INGYENES modell) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude INGYENES) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨 kombók + +### 1. példa: Előfizetés maximalizálása → Olcsó biztonsági mentés + +``` +Dashboard → Combos → Create New + +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) + +Use in CLI: premium-coding +``` + +### 2. példa: Csak ingyenes (nulla költség) + +``` +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) + +Cost: $0 forever! +``` + +--- + +## 🔧 CLI integráció + +### Kurzor IDE + +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` + +### Claude Code + +`~/.claude/config.json` szerkesztése: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### Codex CLI + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +### OpenClaw + +`~/.openclaw/openclaw.json` szerkesztése: + +```json +{ + "agents": { + "defaults": { + "model": { "primary": "omniroute/if/glm-4.7" } + } + }, + "models": { + "providers": { + "omniroute": { + "baseUrl": "http://localhost:20128/v1", + "apiKey": "your-omniroute-api-key", + "api": "openai-completions", + "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }] + } + } + } +} +``` + +**Vagy használja az Irányítópultot:** CLI Tools → OpenClaw → Auto-config + +### Cline / Folytatás / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Bevezetés + +### VPS telepítés + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### Docker + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +A CLI binárisokkal rendelkező gazdagépbe integrált módhoz lásd a Docker szakaszt a fő dokumentumokban. + +### Környezeti változók + +| Változó | Alapértelmezett | Leírás | +| --------------------- | ------------------------------------ | --------------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT aláírási titok (**változás a gyártásban**) | +| `INITIAL_PASSWORD` | `123456` | Első bejelentkezési jelszó | +| `DATA_DIR` | `~/.omniroute` | Adatkönyvtár (db, használat, naplók) | +| `PORT` | keretrendszer alapértelmezett | Szervizport (`20128` a példákban) | +| `HOSTNAME` | keretrendszer alapértelmezett | Gazda kötése (a Docker alapértelmezett értéke `0.0.0.0`) | +| `NODE_ENV` | futásidejű alapértelmezett | Állítsa be az `production` értéket a telepítéshez | +| `BASE_URL` | `http://localhost:20128` | Szerveroldali belső alap URL | +| `CLOUD_URL` | `https://omniroute.dev` | Felhőszinkronizálási végpont alap URL-je | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC titkos a generált API-kulcsokhoz | +| `REQUIRE_API_KEY` | `false` | Bearer API kulcs kényszerítése a következőn: `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Engedélyezi a kérés/válasz naplózást | +| `AUTH_COOKIE_SECURE` | `false` | `Secure` hitelesítési cookie kényszerítése (a HTTPS fordított proxy mögött) | + +A teljes környezeti változó hivatkozását lásd: [README](../README.md). + +--- + +## 📊 Elérhető modellek + +
+Az összes elérhető modell megtekintése + +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Kód (`cx/`)** – Plusz/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` + +**Gemini CLI (`gc/`)** – INGYENES: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` + +**GitHub másodpilóta (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**GLM (`glm/`)** – 0,6 USD/1 millió: `glm/glm-4.7` + +**MiniMax (`minimax/`)** – 0,2 USD/1 millió: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** – INGYENES: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` + +**Qwen (`qw/`)** – INGYENES: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` + +**Kiro (`kr/`)** – INGYENES: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` + +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` + +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` + +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` + +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` + +**Zavarság (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Együtt AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**Fireworks AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Agy (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Speciális funkciók + +### Egyedi modellek + +Adjon hozzá bármilyen modellazonosítót bármely szolgáltatóhoz anélkül, hogy az alkalmazás frissítésére várna: + +```bash +# Via API +curl -X POST http://localhost:20128/api/provider-models \ + -H "Content-Type: application/json" \ + -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}' + +# List: curl http://localhost:20128/api/provider-models?provider=openai +# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" +``` + +Vagy használja az Irányítópultot: **Providers → [Provider] → Custom Models**. + +### Dedikált szolgáltatói útvonalak + +A kérések közvetlenül egy adott szolgáltatóhoz irányíthatók modellellenőrzéssel: + +```bash +POST http://localhost:20128/v1/providers/openai/chat/completions +POST http://localhost:20128/v1/providers/openai/embeddings +POST http://localhost:20128/v1/providers/fireworks/images/generations +``` + +A szolgáltató előtagja automatikusan hozzáadódik, ha hiányzik. A nem egyező modellek a következőt adják vissza: `400`. + +### Hálózati proxy konfiguráció + +```bash +# Set global proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' + +# Per-provider proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' + +# Test proxy +curl -X POST http://localhost:20128/api/settings/proxy/test \ + -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' +``` + +**Precencia:** Kulcsspecifikus → Kombinált → Szolgáltató-specifikus → Globális → Környezet. + +### Model Catalog API + +```bash +curl http://localhost:20128/api/models/catalog +``` + +A modelleket szolgáltató szerint csoportosítva adja vissza típusokkal (`chat`, `embedding`, `image`). + +### Cloud Sync + +- Szinkronizálja a szolgáltatókat, kombinációkat és beállításokat az eszközök között +- Automatikus háttérszinkronizálás időtúllépéssel + hibamentes +- Szerveroldali `BASE_URL`/`CLOUD_URL` előnyben részesítése éles környezetben + +### LLM Gateway Intelligence (9. fázis) + +- **Szemantikus gyorsítótár** – Automatikus gyorsítótárak, nem streamelés, hőmérséklet = 0 válasz (kihagyás a `X-OmniRoute-No-Cache: true` segítségével) +- **Idempotency kérése** – 5 másodpercen belül deduplikálja a kéréseket a `Idempotency-Key` vagy `X-Request-Id` fejlécen keresztül +- **Előrehaladás követése** — SSE `event: progress` események engedélyezése a `X-OmniRoute-Progress: true` fejlécen keresztül + +--- + +### Fordítói Játszótér + +Hozzáférés az **Irányítópult → Fordító** segítségével. Hibakeresés és vizualizálás, hogy az OmniRoute hogyan fordítja le az API-kéréseket a szolgáltatók között. + +| mód | Cél | +| --------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **Játszótér** | Válassza ki a forrás-/célformátumokat, illesszen be egy kérést, és azonnal megtekintheti a lefordított kimenetet | +| **Csevegés tesztelő** | Küldjön élő csevegési üzeneteket a proxyn keresztül, és ellenőrizze a teljes kérés/válasz ciklust | +| **Próbapad** | Futtasson kötegelt teszteket több formátumkombinációra a fordítás helyességének ellenőrzéséhez | +| **Élő monitor** | Nézze meg a valós idejű fordításokat, ahogy a kérések a proxyn keresztül áramlanak | + +**Használati esetek:** + +- Hibakeresés, miért nem sikerül egy adott ügyfél/szolgáltató kombináció +- Ellenőrizze, hogy a gondolkodó címkék, az eszközhívások és a rendszerkérések helyesen fordítódnak-e +- Hasonlítsa össze a formátumbeli különbségeket az OpenAI, Claude, Gemini és Responses API formátumok között + +--- + +### Útválasztási stratégiák + +Konfigurálás a **Irányítópult → Beállítások → Útválasztás** menüpontban. + +| Stratégia | Leírás | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| **Először töltse ki** | A fiókokat prioritási sorrendben használja – az elsődleges fiók minden kérést kezel, amíg el nem éri | +| **Round Robin** | A konfigurálható ragadós korláttal rendelkező összes fiókot végigjárja (alapértelmezett: fiókonként 3 hívás) | +| **P2C (Power of Two Choices)** | 2 véletlenszerű fiókot választ, és az egészségesebbhez vezet – egyensúlyba hozza a terhelést az egészségtudattal | +| **Véletlen** | Véletlenszerűen kiválaszt egy fiókot minden egyes kérelemhez a Fisher-Yates shuffle | +| **Legkevésbé használt** | Útvonalak a legrégebbi `lastUsedAt` időbélyeggel rendelkező fiókhoz, a forgalom egyenletes elosztása | +| **Költségoptimalizált** | Útvonalak a legalacsonyabb prioritású fiókhoz, a legalacsonyabb költségű szolgáltatókra optimalizálva | + +#### Helyettesítő modell álnevek + +Hozzon létre helyettesítő karakteres mintákat a modellnevek újratervezéséhez: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +A helyettesítő karakterek támogatják a `*` (bármilyen karakter) és az `?` (egykarakteres). + +#### Tartalékláncok + +Határozzon meg globális tartalék láncokat, amelyek minden kérelemre vonatkoznak: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Rugalmasság és megszakítók + +Konfigurálás a **Irányítópult → Beállítások → Ellenállás** menüpontban. + +Az OmniRoute szolgáltatói szintű rugalmasságot valósít meg négy összetevőből: + +1. **Szolgáltatói profilok** — Szolgáltatónkénti konfiguráció a következőkhöz: + - Meghibásodási küszöb (hány hiba történt a nyitás előtt) + - Lehűlés időtartama + - Sebességkorlát érzékelési érzékenység + - Exponenciális backoff paraméterek + +2. **Szerkeszthető díjkorlátok** — Az irányítópulton konfigurálható rendszerszintű alapértékek: + - **Percenkénti kérések (RPM)** – A percenkénti kérések száma fiókonként + - **Minimális idő a kérések között** - Minimális eltérés ezredmásodpercben a kérések között + - **Maximális egyidejű kérések** - Maximális egyidejű kérések száma fiókonként + - Kattintson a **Szerkesztés** gombra a módosításhoz, majd a **Mentés** vagy a **Mégse** gombra. Az értékek a rezilience API-n keresztül megmaradnak. + +3. **Circuit Breaker** – Nyomon követi a hibákat szolgáltatónként, és automatikusan megnyitja az áramkört egy küszöbérték elérésekor: + - **ZÁRVA** (egészséges) – A kérések normálisan futnak + - **NYITVA** — A szolgáltató ideiglenesen blokkolva van ismétlődő hibák után + - **HALF_OPEN** — Tesztelés, hogy a szolgáltató helyreállt-e + +4. **Policies & Locked Identifiers** — Megjeleníti a megszakító állapotát és a zárolt azonosítókat kényszer-feloldási képességgel. + +5. **Díjkorlát automatikus észlelése** – Figyeli a `429` és `Retry-After` fejléceket, hogy proaktívan elkerülje a szolgáltatói díjkorlátok átlépését. + +**Profi tipp:** Használja a **Reset All** gombot az összes megszakító és leállás törléséhez, amikor a szolgáltató felépül egy kiesésből. + +--- + +### Adatbázis exportálása/importálása + +Az adatbázis-mentéseket az **Irányítópult → Beállítások → Rendszer és tárhely** menüpontban kezelheti. + +| Akció | Leírás | +| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Adatbázis exportálása** | Letölti az aktuális SQLite adatbázist `.sqlite` fájlként | +| **Az összes exportálása (.tar.gz)** | Letölt egy teljes biztonsági másolat archívumot, beleértve: adatbázist, beállításokat, kombinációkat, szolgáltatói kapcsolatokat (hitelesítő adatok nélkül), API kulcs metaadatait | +| **Adatbázis importálása** | Töltsön fel egy `.sqlite` fájlt az aktuális adatbázis lecseréléséhez. Az importálás előtti biztonsági másolat automatikusan létrejön | + +```bash +# API: Export database +curl -o backup.sqlite http://localhost:20128/api/db-backups/export + +# API: Export all (full archive) +curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll + +# API: Import database +curl -X POST http://localhost:20128/api/db-backups/import \ + -F "file=@backup.sqlite" +``` + +**Importálás ellenőrzése:** Az importált fájl integritását (SQLite pragma ellenőrzés), a szükséges táblákat (`provider_connections`, `provider_nodes`, `combos`, \_\_OMNI_TOKEN_136_x ) és 0 MB-ot (0 MB_x ) ellenőrzik. + +**Használati esetek:** + +- Az OmniRoute áttelepítése a gépek között +- Készítsen külső biztonsági másolatot a katasztrófa utáni helyreállításhoz +- A konfigurációk megosztása a csapattagok között (összes exportálása → archívum megosztása) + +--- + +### Beállítások irányítópultja + +A beállítási oldal 5 lapra van felosztva a könnyű navigáció érdekében: + +| Tab | Tartalom | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Biztonság** | Bejelentkezés/jelszó beállítások, IP-hozzáférés-vezérlés, API-hitelesítés a `/models`-hoz és Szolgáltató blokkolása | +| **Útválasztás** | Globális útválasztási stratégia (6 lehetőség), helyettesítő karakteres modellálnevek, tartalék láncok, kombinált alapértelmezések | +| **rugalmasság** | Szolgáltatói profilok, szerkeszthető sebességkorlátok, megszakító állapota, szabályzatok és zárolt azonosítók | +| **AI** | Átgondolt költségkeret-konfiguráció, globális rendszerbefecskendezés, gyorsítótár-statisztikák | +| **Speciális** | Globális proxykonfiguráció (HTTP/SOCKS5) | + +--- + +### Költségek és költségvetés kezelése + +Hozzáférés az **Irányítópult → Költségek** menüponton keresztül. + +| Tab | Cél | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | +| **Költségvetés** | Költési korlátok beállítása API-kulcsonként napi/heti/havi költségkerettel és valós idejű követéssel | +| **Árak** | Modellárazási bejegyzések megtekintése és szerkesztése – szolgáltatónként 1 000 bemeneti/kimeneti tokenenkénti költség | + +```bash +# API: Set a budget +curl -X POST http://localhost:20128/api/usage/budget \ + -H "Content-Type: application/json" \ + -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' + +# API: Get current budget status +curl http://localhost:20128/api/usage/budget +``` + +**Költségkövetés:** Minden kérés naplózza a tokenhasználatot, és az ártáblázat segítségével kiszámítja a költségeket. Tekintse meg az **Irányítópult → Használat** szolgáltató, modell és API-kulcs szerinti lebontását. + +--- + +### Hangátírás + +Az OmniRoute támogatja a hang átírását az OpenAI-kompatibilis végponton keresztül: + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data + +# Example with curl +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@audio.mp3" \ + -F "model=deepgram/nova-3" +``` + +Elérhető szolgáltatók: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Támogatott hangformátumok: `mp3`, `wav`, `m4a`, `flac`, `ogg`, \_\_OMNI_TOKEN_145_TOKEN_1. + +--- + +### Kombinált egyensúlyozási stratégiák + +Konfigurálja a kombinált egyensúlyozást az **Irányítópult → Kombók → Létrehozás/Szerkesztés → Stratégia** menüpontban. + +| Stratégia | Leírás | +| ----------------------- | ------------------------------------------------------------------------------------------------ | +| **Round-Robin** | Sorozatosan forgatja a modelleket | +| **Prioritás** | Mindig az első modellt próbálja ki; csak hibára esik vissza | +| **Véletlen** | Véletlenszerű modellt választ a kombinációból minden egyes kéréshez | +| **Súlyozott** | Útvonalak arányosan a modellenként hozzárendelt súlyok alapján | +| **Legkevésbé használt** | Útvonalak a legutóbbi legkevesebb kéréssel rendelkező modellhez (kombinált mérőszámokat használ) | +| **Költségoptimalizált** | Útvonalak a legolcsóbb elérhető modellhez (árazási táblázatot használ) | + +A globális kombinált alapértelmezések az **Irányítópult → Beállítások → Útválasztás → Kombinált alapértelmezések** menüpontban állíthatók be. + +--- + +### Egészségügyi irányítópult + +Hozzáférés az **Irányítópult → Egészség** menüponton keresztül. Valós idejű rendszerállapot-áttekintés 6 kártyával: + +| Kártya | Mit mutat | +| ------------------------- | ---------------------------------------------------------------------- | +| **Rendszerállapot** | Üzemidő, verzió, memóriahasználat, adatkönyvtár | +| **Szolgáltatói egészség** | Szolgáltatónkénti megszakító állapota (Zárt/Nyitott/Félig nyitva) | +| **Díjkorlátok** | Aktív sebességkorlátozások fiókonként a hátralévő idővel | +| **Aktív kizárások** | A kizárási szabályzat által ideiglenesen letiltott szolgáltatók | +| **Aláírás-gyorsítótár** | Deduplikációs gyorsítótár statisztikái (aktív kulcsok, találati arány) | +| **Latencia telemetria** | p50/p95/p99 késleltetési összesítés szolgáltatónként | + +**Profi tipp:** Az Egészség oldal 10 másodpercenként automatikusan frissül. Használja a megszakító kártyát annak azonosítására, hogy mely szolgáltatók tapasztaltak problémákat. diff --git a/docs/i18n/id/API_REFERENCE.md b/docs/i18n/id/API_REFERENCE.md new file mode 100644 index 00000000..8d290faf --- /dev/null +++ b/docs/i18n/id/API_REFERENCE.md @@ -0,0 +1,441 @@ +# Referensi API + +🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) + +Referensi lengkap untuk semua titik akhir OmniRoute API. + +--- + +## Daftar Isi + +- [Chat Completions](#chat-completions) +- [Embeddings](#embeddings) +- [Image Generation](#image-generation) +- [List Models](#list-models) +- [Compatibility Endpoints](#compatibility-endpoints) +- [Semantic Cache](#semantic-cache) +- [Dashboard & Management](#dashboard--management) +- [Request Processing](#request-processing) +- [Authentication](#authentication) + +--- + +## Penyelesaian Obrolan + +```bash +POST /v1/chat/completions +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "cc/claude-opus-4-6", + "messages": [ + {"role": "user", "content": "Write a function to..."} + ], + "stream": true +} +``` + +### Header Khusus + +| Tajuk | Arah | Deskripsi | +| ------------------------ | ---------- | -------------------------------------- | +| `X-OmniRoute-No-Cache` | Permintaan | Setel ke `true` untuk melewati cache | +| `X-OmniRoute-Progress` | Permintaan | Setel ke `true` untuk acara kemajuan | +| `Idempotency-Key` | Permintaan | Kunci Dedup (jendela 5 detik) | +| `X-Request-Id` | Permintaan | Kunci dedup alternatif | +| `X-OmniRoute-Cache` | Tanggapan | `HIT` atau `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Tanggapan | `true` jika duplikatnya | +| `X-OmniRoute-Progress` | Tanggapan | `enabled` jika pelacakan kemajuan pada | + +--- + +## Penyematan + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Penyedia yang tersedia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## Pembuatan Gambar + +```bash +POST /v1/images/generations +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "openai/dall-e-3", + "prompt": "A beautiful sunset over mountains", + "size": "1024x1024" +} +``` + +Penyedia yang tersedia: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## Daftar Model + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## Titik Akhir Kompatibilitas + +| Metode | Jalur | Format | +| -------- | --------------------------- | -------------------------- | +| POSTING | `/v1/chat/completions` | OpenAI | +| POSTING | `/v1/messages` | Antropik | +| POSTING | `/v1/responses` | Tanggapan OpenAI | +| POSTING | `/v1/embeddings` | OpenAI | +| POSTING | `/v1/images/generations` | OpenAI | +| DAPATKAN | `/v1/models` | OpenAI | +| POSTING | `/v1/messages/count_tokens` | Antropik | +| DAPATKAN | `/v1beta/models` | kembar | +| POSTING | `/v1beta/models/{...path}` | Gemini menghasilkan Konten | +| POSTING | `/v1/api/chat` | Ollama | + +### Rute Penyedia Khusus + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +Awalan penyedia ditambahkan secara otomatis jika tidak ada. Model yang tidak cocok menampilkan `400`. + +--- + +## Cache Semantik + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +Contoh tanggapan: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Dasbor & Manajemen + +### Otentikasi + +| Titik akhir | Metode | Deskripsi | +| ----------------------------- | ----------------- | ------------------------ | +| `/api/auth/login` | POSTING | Masuk | +| `/api/auth/logout` | POSTING | Keluar | +| `/api/settings/require-login` | DAPATKAN/MASUKKAN | Beralih login diperlukan | + +### Manajemen Penyedia + +| Titik akhir | Metode | Deskripsi | +| ---------------------------- | ----------------------- | ----------------------------- | +| `/api/providers` | DAPATKAN/POSTING | Daftar / buat penyedia | +| `/api/providers/[id]` | DAPATKAN/MASUKKAN/HAPUS | Kelola penyedia | +| `/api/providers/[id]/test` | POSTING | Koneksi penyedia tes | +| `/api/providers/[id]/models` | DAPATKAN | Daftar model penyedia | +| `/api/providers/validate` | POSTING | Validasi konfigurasi penyedia | +| `/api/provider-nodes*` | Berbagai | Manajemen node penyedia | +| `/api/provider-models` | DAPATKAN/POSTING/HAPUS | Model khusus | + +### Alur OAuth + +| Titik akhir | Metode | Deskripsi | +| -------------------------------- | -------- | --------------------- | +| `/api/oauth/[provider]/[action]` | Berbagai | OAuth khusus penyedia | + +### Perutean & Konfigurasi + +| Titik akhir | Metode | Deskripsi | +| --------------------- | ---------------- | --------------------------------------- | +| `/api/models/alias` | DAPATKAN/POSTING | Alias ​​model | +| `/api/models/catalog` | DAPATKAN | Semua model berdasarkan penyedia + tipe | +| `/api/combos*` | Berbagai | Manajemen kombo | +| `/api/keys*` | Berbagai | Manajemen kunci API | +| `/api/pricing` | DAPATKAN | Penetapan harga model | + +### Penggunaan & Analisis + +| Titik akhir | Metode | Deskripsi | +| --------------------------- | -------- | ---------------------- | +| `/api/usage/history` | DAPATKAN | Riwayat penggunaan | +| `/api/usage/logs` | DAPATKAN | Log penggunaan | +| `/api/usage/request-logs` | DAPATKAN | Log tingkat permintaan | +| `/api/usage/[connectionId]` | DAPATKAN | Penggunaan per koneksi | + +### Pengaturan + +| Titik akhir | Metode | Deskripsi | +| ------------------------------- | ----------------- | -------------------------------------- | +| `/api/settings` | DAPATKAN/MASUKKAN | Pengaturan umum | +| `/api/settings/proxy` | DAPATKAN/MASUKKAN | Konfigurasi proksi jaringan | +| `/api/settings/proxy/test` | POSTING | Uji koneksi proxy | +| `/api/settings/ip-filter` | DAPATKAN/MASUKKAN | Daftar IP yang diizinkan/daftar blokir | +| `/api/settings/thinking-budget` | DAPATKAN/MASUKKAN | Penalaran anggaran token | +| `/api/settings/system-prompt` | DAPATKAN/MASUKKAN | Perintah sistem global | + +### Pemantauan + +| Titik akhir | Metode | Deskripsi | +| ------------------------ | -------------- | ----------------------- | +| `/api/sessions` | DAPATKAN | Pelacakan sesi aktif | +| `/api/rate-limits` | DAPATKAN | Batas tarif per akun | +| `/api/monitoring/health` | DAPATKAN | Pemeriksaan kesehatan | +| `/api/cache` | DAPATKAN/HAPUS | Statistik cache / hapus | + +### Cadangkan & Ekspor/Impor + +| Titik akhir | Metode | Deskripsi | +| --------------------------- | -------- | ----------------------------------------------- | +| `/api/db-backups` | DAPATKAN | Daftar cadangan yang tersedia | +| `/api/db-backups` | TETAPKAN | Buat cadangan manual | +| `/api/db-backups` | POSTING | Pulihkan dari cadangan tertentu | +| `/api/db-backups/export` | DAPATKAN | Unduh database sebagai file .sqlite | +| `/api/db-backups/import` | POSTING | Unggah file .sqlite untuk menggantikan database | +| `/api/db-backups/exportAll` | DAPATKAN | Unduh cadangan lengkap sebagai arsip .tar.gz | + +### Sinkronisasi Awan + +| Titik akhir | Metode | Deskripsi | +| ---------------------- | -------- | -------------------------- | +| `/api/sync/cloud` | Berbagai | Operasi sinkronisasi cloud | +| `/api/sync/initialize` | POSTING | Inisialisasi sinkronisasi | +| `/api/cloud/*` | Berbagai | Manajemen awan | + +### Alat CLI + +| Titik akhir | Metode | Deskripsi | +| ---------------------------------- | -------- | ------------------------ | +| `/api/cli-tools/claude-settings` | DAPATKAN | Status Claude CLI | +| `/api/cli-tools/codex-settings` | DAPATKAN | Status CLI Kodeks | +| `/api/cli-tools/droid-settings` | DAPATKAN | Status CLI Droid | +| `/api/cli-tools/openclaw-settings` | DAPATKAN | Status CLI OpenClaw | +| `/api/cli-tools/runtime/[toolId]` | DAPATKAN | Waktu proses CLI generik | + +Respons CLI meliputi: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### Ketahanan & Batas Nilai + +| Titik akhir | Metode | Deskripsi | +| ----------------------- | ----------------- | ---------------------------------- | +| `/api/resilience` | DAPATKAN/MASUKKAN | Dapatkan/perbarui profil ketahanan | +| `/api/resilience/reset` | POSTING | Setel ulang pemutus sirkuit | +| `/api/rate-limits` | DAPATKAN | Status batas tarif per akun | +| `/api/rate-limit` | DAPATKAN | Konfigurasi batas tarif global | + +### Evaluasi + +| Titik akhir | Metode | Deskripsi | +| ------------ | ---------------- | ------------------------------------ | +| `/api/evals` | DAPATKAN/POSTING | Daftar eval suites/jalankan evaluasi | + +### Kebijakan + +| Titik akhir | Metode | Deskripsi | +| --------------- | ---------------------- | ------------------------- | +| `/api/policies` | DAPATKAN/POSTING/HAPUS | Kelola kebijakan perutean | + +### Kepatuhan + +| Titik akhir | Metode | Deskripsi | +| --------------------------- | -------- | -------------------------------- | +| `/api/compliance/audit-log` | DAPATKAN | Log audit kepatuhan (N terakhir) | + +### v1beta (Kompatibel dengan Gemini) + +| Titik akhir | Metode | Deskripsi | +| -------------------------- | -------- | ------------------------------------ | +| `/v1beta/models` | DAPATKAN | Daftar model dalam format Gemini | +| `/v1beta/models/{...path}` | POSTING | Titik akhir Gemini `generateContent` | + +Titik akhir ini mencerminkan format API Gemini untuk klien yang mengharapkan kompatibilitas asli Gemini SDK. + +### API Internal/Sistem + +| Titik akhir | Metode | Deskripsi | +| --------------- | -------- | -------------------------------------------------------------------------- | +| `/api/init` | DAPATKAN | Pemeriksaan inisialisasi aplikasi (digunakan saat pertama kali dijalankan) | +| `/api/tags` | DAPATKAN | Tag model yang kompatibel dengan Ollama (untuk klien Ollama) | +| `/api/restart` | POSTING | Memicu restart server dengan anggun | +| `/api/shutdown` | POSTING | Memicu penutupan server dengan baik | + +> **Catatan:** Titik akhir ini digunakan secara internal oleh sistem atau untuk kompatibilitas klien Ollama. Mereka biasanya tidak dipanggil oleh pengguna akhir. + +--- + +## Transkripsi Audio + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Transkripsikan file audio menggunakan Deepgram atau AssemblyAI. + +**Permintaan:** + +```bash +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@recording.mp3" \ + -F "model=deepgram/nova-3" +``` + +**Respon:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**Penyedia yang didukung:** `deepgram/nova-3`, `assemblyai/best`. + +**Format yang didukung:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +## Kompatibilitas Ollama + +Untuk klien yang menggunakan format API Ollama: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +Permintaan secara otomatis diterjemahkan antara Ollama dan format internal. + +--- + +## Telemetri + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Respon:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## Anggaran + +```bash +# Get budget status for all API keys +GET /api/usage/budget + +# Set or update a budget +POST /api/usage/budget +Content-Type: application/json + +{ + "keyId": "key-123", + "limit": 50.00, + "period": "monthly" +} +``` + +--- + +## Ketersediaan Model + +```bash +# Get real-time model availability across all providers +GET /api/models/availability + +# Check availability for a specific model +POST /api/models/availability +Content-Type: application/json + +{ + "model": "claude-sonnet-4-5-20250929" +} +``` + +--- + +## Pemrosesan Permintaan + +1. Klien mengirimkan permintaan ke `/v1/*` +2. Pengendali rute memanggil `handleChat`, `handleEmbedding`, `handleAudioTranscription`, atau `handleImageGeneration` +3. Model terselesaikan (penyedia/model langsung atau alias/kombo) +4. Kredensial dipilih dari DB lokal dengan pemfilteran ketersediaan akun +5. Untuk obrolan: `handleChatCore` — deteksi format, terjemahan, pemeriksaan cache, pemeriksaan idempotensi +6. Pelaksana penyedia mengirimkan permintaan upstream +7. Respons diterjemahkan kembali ke format klien (obrolan) atau dikembalikan apa adanya (embeddings/images/audio) +8. Penggunaan/logging dicatat +9. Fallback berlaku pada error sesuai dengan aturan kombo + +Referensi arsitektur lengkap: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## Otentikasi + +- Rute dasbor (`/dashboard/*`) menggunakan cookie `auth_token` +- Login menggunakan hash kata sandi yang disimpan; mundur ke `INITIAL_PASSWORD` +- `requireLogin` dapat dialihkan melalui `/api/settings/require-login` +- Rute `/v1/*` secara opsional memerlukan kunci API Pembawa ketika `REQUIRE_API_KEY=true` diff --git a/docs/i18n/id/ARCHITECTURE.md b/docs/i18n/id/ARCHITECTURE.md new file mode 100644 index 00000000..7efab327 --- /dev/null +++ b/docs/i18n/id/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# Arsitektur OmniRoute + +🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) + +_Terakhir diperbarui: 18-02-2026_ + +## Ringkasan Eksekutif + +OmniRoute adalah gateway dan dasbor perutean AI lokal yang dibangun di Next.js. +Ini menyediakan satu titik akhir yang kompatibel dengan OpenAI (`/v1/*`) dan merutekan lalu lintas di beberapa penyedia upstream dengan terjemahan, fallback, penyegaran token, dan pelacakan penggunaan. + +Kemampuan inti: + +- Permukaan API yang kompatibel dengan OpenAI untuk CLI/alat (28 penyedia) +- Permintaan/tanggapan terjemahan lintas format penyedia +- Model kombo fallback (urutan multi-model) +- Penggantian tingkat akun (multi-akun per penyedia) +- Manajemen koneksi penyedia kunci OAuth + API +- Menyematkan generasi melalui `/v1/embeddings` (6 penyedia, 9 model) +- Pembuatan gambar melalui `/v1/images/generations` (4 penyedia, 9 model) +- Pikirkan penguraian tag (`...`) untuk model penalaran +- Sanitasi respons untuk kompatibilitas OpenAI SDK yang ketat +- Normalisasi peran (pengembang→sistem, sistem→pengguna) untuk kompatibilitas lintas penyedia +- Konversi keluaran terstruktur (json_schema → Gemini responSchema) +- Persistensi lokal untuk penyedia, kunci, alias, kombo, pengaturan, harga +- Pelacakan penggunaan/biaya dan pencatatan permintaan +- Sinkronisasi cloud opsional untuk sinkronisasi multi-perangkat/negara +- Daftar IP yang diizinkan/daftar blokir untuk kontrol akses API +- Memikirkan manajemen anggaran (passthrough/otomatis/custom/adaptif) +- Injeksi cepat sistem global +- Pelacakan sesi dan sidik jari +- Pembatasan tarif yang ditingkatkan per akun dengan profil khusus penyedia +- Pola pemutus sirkuit untuk ketahanan penyedia +- Perlindungan kawanan anti guntur dengan penguncian mutex +- Cache deduplikasi permintaan berbasis tanda tangan +- Lapisan domain: ketersediaan model, aturan biaya, kebijakan fallback, kebijakan lockout +- Persistensi status domain (cache tulis SQLite untuk fallback, anggaran, penguncian, pemutus sirkuit) +- Mesin kebijakan untuk evaluasi permintaan terpusat (lockout → anggaran → fallback) +- Minta telemetri dengan agregasi latensi p50/p95/p99 +- ID Korelasi (X-Request-Id) untuk penelusuran ujung ke ujung +- Pencatatan audit kepatuhan dengan opt-out per kunci API +- Kerangka evaluasi untuk penjaminan mutu LLM +- Dasbor UI ketahanan dengan status pemutus sirkuit waktu nyata +- Penyedia OAuth modular (12 modul individual di bawah `src/lib/oauth/providers/`) + +Model waktu proses utama: + +- Rute aplikasi Next.js di bawah `src/app/api/*` mengimplementasikan API dasbor dan API kompatibilitas +- Inti SSE/perutean bersama di `src/sse/*` + `open-sse/*` menangani eksekusi, terjemahan, streaming, fallback, dan penggunaan penyedia + +## Ruang Lingkup dan Batasan + +### Dalam Cakupan + +- Waktu aktif gateway lokal +- API manajemen dasbor +- Otentikasi penyedia dan penyegaran token +- Minta terjemahan dan streaming SSE +- Status lokal + persistensi penggunaan +- Orkestrasi sinkronisasi cloud opsional + +### Di Luar Cakupan + +- Implementasi layanan cloud di belakang `NEXT_PUBLIC_CLOUD_URL` +- Penyedia SLA/bidang kontrol di luar proses lokal +- Biner CLI eksternal itu sendiri (Claude CLI, Codex CLI, dll.) + +## Konteks Sistem Tingkat Tinggi + +```mermaid +flowchart LR + subgraph Clients[Developer Clients] + C1[Claude Code] + C2[Codex CLI] + C3[OpenClaw / Droid / Cline / Continue / Roo] + C4[Custom OpenAI-compatible clients] + BROWSER[Browser Dashboard] + end + + subgraph Router[OmniRoute Local Process] + API[V1 Compatibility API\n/v1/*] + DASH[Dashboard + Management API\n/api/*] + CORE[SSE + Translation Core\nopen-sse + src/sse] + DB[(db.json)] + UDB[(usage.json + log.txt)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity] + P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA] + P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible] + end + + subgraph Cloud[Optional Cloud Sync] + CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL] + end + + C1 --> API + C2 --> API + C3 --> API + C4 --> API + BROWSER --> DASH + + API --> CORE + DASH --> DB + CORE --> DB + CORE --> UDB + + CORE --> P1 + CORE --> P2 + CORE --> P3 + + DASH --> CLOUD +``` + +## Komponen Waktu Proses Inti + +## 1) API dan Lapisan Perutean (Rute Aplikasi Next.js) + +Direktori utama: + +- `src/app/api/v1/*` dan `src/app/api/v1beta/*` untuk API kompatibilitas +- `src/app/api/*` untuk API manajemen/konfigurasi +- Selanjutnya penulisan ulang di `next.config.mjs` peta `/v1/*` menjadi `/api/v1/*` + +Rute kompatibilitas penting: + +- `src/app/api/v1/chat/completions/route.ts` +- `src/app/api/v1/messages/route.ts` +- `src/app/api/v1/responses/route.ts` +- `src/app/api/v1/models/route.ts` — termasuk model khusus dengan `custom: true` +- `src/app/api/v1/embeddings/route.ts` — generasi penyematan (6 penyedia) +- `src/app/api/v1/images/generations/route.ts` — pembuatan gambar (4+ penyedia termasuk Antigravity/Nebius) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — obrolan khusus per penyedia +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — penyematan khusus per penyedia +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — gambar khusus per penyedia +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Domain manajemen: + +- Otentikasi/pengaturan: `src/app/api/auth/*`, `src/app/api/settings/*` +- Penyedia/koneksi: `src/app/api/providers*` +- Node penyedia: `src/app/api/provider-nodes*` +- Model khusus: `src/app/api/provider-models` (GET/POST/DELETE) +- Katalog model: `src/app/api/models/catalog` (GET) +- Konfigurasi proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Kunci/alias/kombo/harga: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Penggunaan: `src/app/api/usage/*` +- Sinkronisasi/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- Pembantu perkakas CLI: `src/app/api/cli-tools/*` +- Filter IP: `src/app/api/settings/ip-filter` (DAPATKAN/PUT) +- Memikirkan anggaran: `src/app/api/settings/thinking-budget` (GET/PUT) +- Perintah sistem: `src/app/api/settings/system-prompt` (GET/PUT) +- Sesi: `src/app/api/sessions` (DAPATKAN) +- Batas tarif: `src/app/api/rate-limits` (GET) +- Ketahanan: `src/app/api/resilience` (GET/PATCH) — profil penyedia, pemutus sirkuit, status batas kecepatan +- Reset ketahanan: `src/app/api/resilience/reset` (POST) — reset pemutus + cooldown +- Statistik cache: `src/app/api/cache/stats` (DAPATKAN/HAPUS) +- Ketersediaan model: `src/app/api/models/availability` (GET/POST) +- Telemetri: `src/app/api/telemetry/summary` (GET) +- Anggaran: `src/app/api/usage/budget` (DAPATKAN/POST) +- Rantai cadangan: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Audit kepatuhan: `src/app/api/compliance/audit-log` (GET) +- Nilai: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Kebijakan: `src/app/api/policies` (DAPATKAN/POST) + +## 2) SSE + Inti Terjemahan + +Modul aliran utama: + +- Entri: `src/sse/handlers/chat.ts` +- Orkestrasi inti: `open-sse/handlers/chatCore.ts` +- Adaptor eksekusi penyedia: `open-sse/executors/*` +- Deteksi format/konfigurasi penyedia: `open-sse/services/provider.ts` +- Model penguraian/penyelesaian: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Logika penggantian akun: `open-sse/services/accountFallback.ts` +- Registri terjemahan: `open-sse/translator/index.ts` +- Transformasi aliran: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Ekstraksi/normalisasi penggunaan: `open-sse/utils/usageTracking.ts` +- Pikirkan pengurai tag: `open-sse/utils/thinkTagParser.ts` +- Pengendali penyematan: `open-sse/handlers/embeddings.ts` +- Menanamkan registri penyedia: `open-sse/config/embeddingRegistry.ts` +- Pengendali pembuatan gambar: `open-sse/handlers/imageGeneration.ts` +- Registri penyedia gambar: `open-sse/config/imageRegistry.ts` +- Sanitasi respons: `open-sse/handlers/responseSanitizer.ts` +- Normalisasi peran: `open-sse/services/roleNormalizer.ts` + +Layanan (logika bisnis): + +- Pemilihan/penilaian akun: `open-sse/services/accountSelector.ts` +- Manajemen siklus hidup konteks: `open-sse/services/contextManager.ts` +- Penegakan filter IP: `open-sse/services/ipFilter.ts` +- Pelacakan sesi: `open-sse/services/sessionManager.ts` +- Permintaan deduplikasi: `open-sse/services/signatureCache.ts` +- Injeksi cepat sistem: `open-sse/services/systemPrompt.ts` +- Memikirkan pengelolaan anggaran: `open-sse/services/thinkingBudget.ts` +- Perutean model karakter pengganti: `open-sse/services/wildcardRouter.ts` +- Manajemen batas tarif: `open-sse/services/rateLimitManager.ts` +- Pemutus arus: `open-sse/services/circuitBreaker.ts` + +Modul lapisan domain: + +- Ketersediaan model: `src/lib/domain/modelAvailability.ts` +- Aturan biaya/anggaran: `src/lib/domain/costRules.ts` +- Kebijakan penggantian: `src/lib/domain/fallbackPolicy.ts` +- Penyelesai kombo: `src/lib/domain/comboResolver.ts` +- Kebijakan penguncian: `src/lib/domain/lockoutPolicy.ts` +- Mesin kebijakan: `src/domain/policyEngine.ts` — penguncian terpusat → anggaran → evaluasi cadangan +- Katalog kode kesalahan: `src/lib/domain/errorCodes.ts` +- ID Permintaan: `src/lib/domain/requestId.ts` +- Batas waktu pengambilan: `src/lib/domain/fetchTimeout.ts` +- Permintaan telemetri: `src/lib/domain/requestTelemetry.ts` +- Kepatuhan/audit: `src/lib/domain/compliance/index.ts` +- Pelari evaluasi: `src/lib/domain/evalRunner.ts` +- Persistensi status domain: `src/lib/db/domainState.ts` — SQLite CRUD untuk rantai cadangan, anggaran, riwayat biaya, status penguncian, pemutus sirkuit + +Modul penyedia OAuth (12 file individual di bawah `src/lib/oauth/providers/`): + +- Indeks registri: `src/lib/oauth/providers/index.ts` +- Penyedia perorangan: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Pembungkus tipis: `src/lib/oauth/providers.ts` — mengekspor ulang dari masing-masing modul + +## 3) Lapisan Persistensi + +DB negara bagian utama: + +- `src/lib/localDb.ts` +- file: `${DATA_DIR}/db.json` (atau `$XDG_CONFIG_HOME/omniroute/db.json` bila disetel, jika tidak `~/.omniroute/db.json`) +- entitas: penyediaConnections, penyediaNodes, modelAliases, kombo, apiKeys, pengaturan, harga, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +DB Penggunaan: + +- `src/lib/usageDb.ts` +- file: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- mengikuti kebijakan direktori dasar yang sama dengan `localDb` (`DATA_DIR`, lalu `XDG_CONFIG_HOME/omniroute` bila disetel) +- didekomposisi menjadi sub-modul terfokus: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +DB Status Domain (SQLite): + +- `src/lib/db/domainState.ts` — Operasi CRUD untuk status domain +- Tabel (dibuat di `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Pola cache write-through: Peta dalam memori bersifat otoritatif saat runtime; mutasi ditulis secara sinkron ke SQLite; keadaan dipulihkan dari DB pada start dingin + +## 4) Auth + Permukaan Keamanan + +- Otentikasi cookie dasbor: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- Pembuatan/verifikasi kunci API: `src/shared/utils/apiKey.ts` +- Rahasia penyedia tetap ada di `providerConnections` entri +- Dukungan proxy keluar melalui `open-sse/utils/proxyFetch.ts` (env vars) dan `open-sse/utils/networkProxy.ts` (dapat dikonfigurasi per penyedia atau global) + +## 5) Sinkronisasi Cloud + +- Penjadwal init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Tugas berkala: `src/shared/services/cloudSyncScheduler.ts` +- Rute kontrol: `src/app/api/sync/cloud/route.ts` + +## Siklus Hidup Permintaan (`/v1/chat/completions`) + +```mermaid +sequenceDiagram + autonumber + participant Client as CLI/SDK Client + participant Route as /api/v1/chat/completions + participant Chat as src/sse/handlers/chat + participant Core as open-sse/handlers/chatCore + participant Model as Model Resolver + participant Auth as Credential Selector + participant Exec as Provider Executor + participant Prov as Upstream Provider + participant Stream as Stream Translator + participant Usage as usageDb + + Client->>Route: POST /v1/chat/completions + Route->>Chat: handleChat(request) + Chat->>Model: parse/resolve model or combo + + alt Combo model + Chat->>Chat: iterate combo models (handleComboChat) + end + + Chat->>Auth: getProviderCredentials(provider) + Auth-->>Chat: active account + tokens/api key + + Chat->>Core: handleChatCore(body, modelInfo, credentials) + Core->>Core: detect source format + Core->>Core: translate request to target format + Core->>Exec: execute(provider, transformedBody) + Exec->>Prov: upstream API call + Prov-->>Exec: SSE/JSON response + Exec-->>Core: response + metadata + + alt 401/403 + Core->>Exec: refreshCredentials() + Exec-->>Core: updated tokens + Core->>Exec: retry request + end + + Core->>Stream: translate/normalize stream to client format + Stream-->>Client: SSE chunks / JSON response + + Stream->>Usage: extract usage + persist history/log +``` + +## Kombo + Alur Penggantian Akun + +```mermaid +flowchart TD + A[Incoming model string] --> B{Is combo name?} + B -- Yes --> C[Load combo models sequence] + B -- No --> D[Single model path] + + C --> E[Try model N] + E --> F[Resolve provider/model] + D --> F + + F --> G[Select account credentials] + G --> H{Credentials available?} + H -- No --> I[Return provider unavailable] + H -- Yes --> J[Execute request] + + J --> K{Success?} + K -- Yes --> L[Return response] + K -- No --> M{Fallback-eligible error?} + + M -- No --> N[Return error] + M -- Yes --> O[Mark account unavailable cooldown] + O --> P{Another account for provider?} + P -- Yes --> G + P -- No --> Q{In combo with next model?} + Q -- Yes --> E + Q -- No --> R[Return all unavailable] +``` + +Keputusan cadangan didorong oleh `open-sse/services/accountFallback.ts` menggunakan kode status dan heuristik pesan kesalahan. + +## Siklus Hidup Orientasi OAuth dan Penyegaran Token + +```mermaid +sequenceDiagram + autonumber + participant UI as Dashboard UI + participant OAuth as /api/oauth/[provider]/[action] + participant ProvAuth as Provider Auth Server + participant DB as localDb + participant Test as /api/providers/[id]/test + participant Exec as Provider Executor + + UI->>OAuth: GET authorize or device-code + OAuth->>ProvAuth: create auth/device flow + ProvAuth-->>OAuth: auth URL or device code payload + OAuth-->>UI: flow data + + UI->>OAuth: POST exchange or poll + OAuth->>ProvAuth: token exchange/poll + ProvAuth-->>OAuth: access/refresh tokens + OAuth->>DB: createProviderConnection(oauth data) + OAuth-->>UI: success + connection id + + UI->>Test: POST /api/providers/[id]/test + Test->>Exec: validate credentials / optional refresh + Exec-->>Test: valid or refreshed token info + Test->>DB: update status/tokens/errors + Test-->>UI: validation result +``` + +Penyegaran selama lalu lintas langsung dijalankan di dalam `open-sse/handlers/chatCore.ts` melalui pelaksana `refreshCredentials()`. + +## Siklus Hidup Cloud Sync (Aktifkan / Sinkronisasi / Nonaktifkan) + +```mermaid +sequenceDiagram + autonumber + participant UI as Endpoint Page UI + participant Sync as /api/sync/cloud + participant DB as localDb + participant Cloud as External Cloud Sync + participant Claude as ~/.claude/settings.json + + UI->>Sync: POST action=enable + Sync->>DB: set cloudEnabled=true + Sync->>DB: ensure API key exists + Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys) + Cloud-->>Sync: sync result + Sync->>Cloud: GET /{machineId}/v1/verify + Sync-->>UI: enabled + verification status + + UI->>Sync: POST action=sync + Sync->>Cloud: POST /sync/{machineId} + Cloud-->>Sync: remote data + Sync->>DB: update newer local tokens/status + Sync-->>UI: synced + + UI->>Sync: POST action=disable + Sync->>DB: set cloudEnabled=false + Sync->>Cloud: DELETE /sync/{machineId} + Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed) + Sync-->>UI: disabled +``` + +Sinkronisasi berkala dipicu oleh `CloudSyncScheduler` saat cloud diaktifkan. + +## Model Data dan Peta Penyimpanan + +```mermaid +erDiagram + SETTINGS ||--o{ PROVIDER_CONNECTION : controls + PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider + PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage + + SETTINGS { + boolean cloudEnabled + number stickyRoundRobinLimit + boolean requireLogin + string password_hash + string fallbackStrategy + json rateLimitDefaults + json providerProfiles + } + + PROVIDER_CONNECTION { + string id + string provider + string authType + string name + number priority + boolean isActive + string apiKey + string accessToken + string refreshToken + string expiresAt + string testStatus + string lastError + string rateLimitedUntil + json providerSpecificData + } + + PROVIDER_NODE { + string id + string type + string name + string prefix + string apiType + string baseUrl + } + + MODEL_ALIAS { + string alias + string targetModel + } + + COMBO { + string id + string name + string[] models + } + + API_KEY { + string id + string name + string key + string machineId + } + + USAGE_ENTRY { + string provider + string model + number prompt_tokens + number completion_tokens + string connectionId + string timestamp + } + + CUSTOM_MODEL { + string id + string name + string providerId + } + + PROXY_CONFIG { + string global + json providers + } + + IP_FILTER { + string mode + string[] allowlist + string[] blocklist + } + + THINKING_BUDGET { + string mode + number customBudget + string effortLevel + } + + SYSTEM_PROMPT { + boolean enabled + string prompt + string position + } +``` + +File penyimpanan fisik: + +- status utama: `${DATA_DIR}/db.json` (atau `$XDG_CONFIG_HOME/omniroute/db.json` jika disetel, jika tidak `~/.omniroute/db.json`) +- statistik penggunaan: `${DATA_DIR}/usage.json` +- baris log permintaan: `${DATA_DIR}/log.txt` +- sesi debug penerjemah/permintaan opsional: `/logs/...` + +## Topologi Penerapan + +```mermaid +flowchart LR + subgraph LocalHost[Developer Host] + CLI[CLI Tools] + Browser[Dashboard Browser] + end + + subgraph ContainerOrProcess[OmniRoute Runtime] + Next[Next.js Server\nPORT=20128] + Core[SSE Core + Executors] + MainDB[(db.json)] + UsageDB[(usage.json/log.txt)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Pemetaan Modul (Kritis Keputusan) + +### Rute dan Modul API + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API kompatibilitas +- `src/app/api/v1/providers/[provider]/*`: rute khusus per penyedia (obrolan, penyematan, gambar) +- `src/app/api/providers*` : penyedia CRUD, validasi, pengujian +- `src/app/api/provider-nodes*`: manajemen node khusus yang kompatibel +- `src/app/api/provider-models`: manajemen model khusus (CRUD) +- `src/app/api/models/catalog`: API katalog model lengkap (semua jenis dikelompokkan berdasarkan penyedia) +- `src/app/api/oauth/*`: OAuth/kode perangkat mengalir +- `src/app/api/keys*`: siklus hidup kunci API lokal +- `src/app/api/models/alias`: manajemen alias +- `src/app/api/combos*`: manajemen kombo cadangan +- `src/app/api/pricing`: penggantian harga untuk penghitungan biaya +- `src/app/api/settings/proxy`: konfigurasi proksi (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: uji konektivitas proxy keluar (POST) +- `src/app/api/usage/*`: API penggunaan dan log +- `src/app/api/sync/*` + `src/app/api/cloud/*`: sinkronisasi cloud dan pembantu yang menghadap cloud +- `src/app/api/cli-tools/*`: penulis/pemeriksa konfigurasi CLI lokal +- `src/app/api/settings/ip-filter`: Daftar IP yang diizinkan/daftar blokir (GET/PUT) +- `src/app/api/settings/thinking-budget`: memikirkan konfigurasi anggaran token (GET/PUT) +- `src/app/api/settings/system-prompt`: perintah sistem global (GET/PUT) +- `src/app/api/sessions`: daftar sesi aktif (GET) +- `src/app/api/rate-limits`: status batas tarif per akun (GET) + +### Perutean dan Inti Eksekusi + +- `src/sse/handlers/chat.ts`: penguraian permintaan, penanganan kombo, putaran pemilihan akun +- `open-sse/handlers/chatCore.ts`: terjemahan, pengiriman eksekutor, penanganan coba lagi/segarkan, pengaturan streaming +- `open-sse/executors/*`: perilaku format dan jaringan khusus penyedia + +### Registri Terjemahan dan Pengonversi Format + +- `open-sse/translator/index.ts`: registrasi dan orkestrasi penerjemah +- Permintaan penerjemah: `open-sse/translator/request/*` +- Penerjemah tanggapan: `open-sse/translator/response/*` +- Konstanta format: `open-sse/translator/formats.ts` + +### Ketekunan + +- `src/lib/localDb.ts`: konfigurasi/status persisten +- `src/lib/usageDb.ts`: riwayat penggunaan dan log permintaan bergulir + +## Cakupan Pelaksana Penyedia (Pola Strategi) + +Setiap penyedia memiliki pelaksana khusus yang memperluas `BaseExecutor` (di `open-sse/executors/base.ts`), yang menyediakan pembuatan URL, konstruksi header, percobaan ulang dengan backoff eksponensial, kait penyegaran kredensial, dan metode orkestrasi `execute()`. + +| Pelaksana | Penyedia | Penanganan Khusus | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Kebingungan, Bersama, Kembang Api, Cerebras, Cohere, NVIDIA | Konfigurasi URL/tajuk dinamis per penyedia | +| `AntigravityExecutor` | Google Antigravitasi | ID proyek/sesi khusus, Coba Lagi-Setelah penguraian | +| `CodexExecutor` | Kodeks OpenAI | Menyuntikkan instruksi sistem, memaksakan upaya penalaran | +| `CursorExecutor` | IDE Kursor | Protokol ConnectRPC, pengkodean Protobuf, penandatanganan permintaan melalui checksum | +| `GithubExecutor` | Kopilot GitHub | Penyegaran token kopilot, header yang meniru VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | Format biner AWS EventStream → konversi SSE | +| `GeminiCLIExecutor` | CLI Gemini | Siklus penyegaran token Google OAuth | + +Semua penyedia lain (termasuk node khusus yang kompatibel) menggunakan `DefaultExecutor`. + +## Matriks Kompatibilitas Penyedia + +| Penyedia | Format | Otentikasi | Aliran | Non-Aliran | Penyegaran Token | API Penggunaan | +| ---------------- | ---------------- | --------------------- | ----------------- | ---------- | ---------------- | --------------------- | +| Claude | claude | Kunci API / OAuth | ✅ | ✅ | ✅ | ⚠️ Admin saja | +| kembar | gemilang | Kunci API / OAuth | ✅ | ✅ | ✅ | ⚠️ Konsol Cloud | +| CLI Gemini | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Konsol Cloud | +| Antigravitasi | antigravitasi | OAuth | ✅ | ✅ | ✅ | ✅ API kuota penuh | +| OpenAI | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Kodeks | openai-responses | OAuth | ✅ dipaksa | ❌ | ✅ | ✅ Batas tarif | +| Kopilot GitHub | buka | OAuth + Token Kopilot | ✅ | ✅ | ✅ | ✅ Cuplikan kuota | +| Kursor | kursor | Checksum khusus | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiri | AWSSSO OIDC | ✅ (Aliran Acara) | ❌ | ✅ | ✅ Batasan penggunaan | +| Qwen | buka | OAuth | ✅ | ✅ | ✅ | ⚠️ Sesuai permintaan | +| iFlow | buka | OAuth (Dasar) | ✅ | ✅ | ✅ | ⚠️ Sesuai permintaan | +| BukaRouter | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Pencarian Dalam | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Bagus | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Mistral | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Kebingungan | openai | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Bersama AI | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| AI kembang api | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| Otak | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| menyatu | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | buka | Kunci API | ✅ | ✅ | ❌ | ❌ | + +## Format Cakupan Terjemahan + +Format sumber yang terdeteksi meliputi: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Format sasaran meliputi: + +- Obrolan/Respon OpenAI +- Claude +- Amplop Gemini/Gemini-CLI/Antigravitasi +- Kiro +- Kursor + +Penerjemahan menggunakan **OpenAI sebagai format hub** — semua konversi melalui OpenAI sebagai perantara: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +Terjemahan dipilih secara dinamis berdasarkan bentuk muatan sumber dan format target penyedia. + +Lapisan pemrosesan tambahan dalam alur terjemahan: + +- **Sanitasi respons** — Menghapus kolom non-standar dari respons format OpenAI (streaming dan non-streaming) untuk memastikan kepatuhan SDK yang ketat +- **Normalisasi peran** — Mengonversi `developer` → `system` untuk target non-OpenAI; menggabungkan `system` → `user` untuk model yang menolak peran sistem (GLM, ERNIE) +- **Pikirkan ekstraksi tag** — Mengurai `...` blok dari konten ke dalam bidang `reasoning_content` +- **Output terstruktur** — Mengonversi OpenAI `response_format.json_schema` menjadi `responseMimeType` + `responseSchema` Gemini + +## Titik Akhir API yang Didukung + +| Titik akhir | Format | Penangan | +| -------------------------------------------------- | ------------------- | ------------------------------------------------------- | +| `POST /v1/chat/completions` | Obrolan OpenAI | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Pesan Claude | Penangan yang sama (terdeteksi otomatis) | +| `POST /v1/responses` | Tanggapan OpenAI | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | Penyematan OpenAI | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Daftar model | Rute API | +| `POST /v1/images/generations` | Gambar OpenAI | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Daftar model | Rute API | +| `POST /v1/providers/{provider}/chat/completions` | Obrolan OpenAI | Per penyedia khusus dengan validasi model | +| `POST /v1/providers/{provider}/embeddings` | Penyematan OpenAI | Per penyedia khusus dengan validasi model | +| `POST /v1/providers/{provider}/images/generations` | Gambar OpenAI | Per penyedia khusus dengan validasi model | +| `POST /v1/messages/count_tokens` | Jumlah Token Claude | Rute API | +| `GET /v1/models` | Daftar Model OpenAI | Rute API (obrolan + penyematan + gambar + model khusus) | +| `GET /api/models/catalog` | Katalog | Semua model dikelompokkan berdasarkan penyedia + tipe | +| `POST /v1beta/models/*:streamGenerateContent` | Gemini asli | Rute API | +| `GET/PUT/DELETE /api/settings/proxy` | Konfigurasi Proksi | Konfigurasi proksi jaringan | +| `POST /api/settings/proxy/test` | Konektivitas Proksi | Titik akhir pengujian kesehatan/konektivitas proxy | +| `GET/POST/DELETE /api/provider-models` | Model Khusus | Manajemen model khusus per penyedia | + +## Pengendali Pintas + +Penangan bypass (`open-sse/utils/bypassHandler.ts`) mencegat permintaan "sekali pakai" yang diketahui dari Claude CLI — ping pemanasan, ekstraksi judul, dan jumlah token — dan mengembalikan **respons palsu** tanpa menggunakan token penyedia upstream. Ini dipicu hanya ketika `User-Agent` berisi `claude-cli`. + +## Minta Saluran Logger + +Logger permintaan (`open-sse/utils/requestLogger.ts`) menyediakan pipeline debug logging 7 tahap, dinonaktifkan secara default, diaktifkan melalui `ENABLE_REQUEST_LOGS=true`: + +``` +1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json +→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt +``` + +File ditulis ke `/logs//` untuk setiap sesi permintaan. + +## Mode Kegagalan dan Ketahanan + +## 1) Ketersediaan Akun/Penyedia + +- cooldown akun penyedia pada kesalahan sementara/rate/auth +- penggantian akun sebelum permintaan gagal +- penggantian model kombo ketika jalur model/penyedia saat ini habis + +## 2) Kedaluwarsa Token + +- pra-periksa dan segarkan dengan coba lagi untuk penyedia yang dapat disegarkan +- 401/403 percobaan ulang setelah upaya penyegaran di jalur inti + +## 3) Keamanan Aliran + +- pengontrol aliran yang sadar akan pemutusan hubungan +- aliran terjemahan dengan flush akhir aliran dan penanganan `[DONE]` +- penggantian estimasi penggunaan ketika metadata penggunaan penyedia tidak ada + +## 4) Degradasi Sinkronisasi Cloud + +- kesalahan sinkronisasi muncul tetapi runtime lokal terus berlanjut +- penjadwal memiliki logika yang mampu mencoba ulang, namun eksekusi berkala saat ini memanggil sinkronisasi upaya tunggal secara default + +## 5) Integritas Data + +- Migrasi/perbaikan bentuk DB untuk kunci yang hilang +- perlindungan reset JSON yang rusak untuk localDb dan usageDb + +## Observabilitas dan Sinyal Operasional + +Sumber visibilitas waktu proses: + +- log konsol dari `src/sse/utils/logger.ts` +- agregat penggunaan per permintaan di `usage.json` +- status permintaan tekstual masuk `log.txt` +- log permintaan/terjemahan dalam opsional di bawah `logs/` ketika `ENABLE_REQUEST_LOGS=true` +- titik akhir penggunaan dasbor (`/api/usage/*`) untuk konsumsi UI + +## Batasan yang Sensitif terhadap Keamanan + +- Rahasia JWT (`JWT_SECRET`) mengamankan verifikasi/penandatanganan cookie sesi dasbor +- Penggantian kata sandi awal (`INITIAL_PASSWORD`, default `123456`) harus diganti dalam penerapan nyata +- Rahasia HMAC kunci API (`API_KEY_SECRET`) mengamankan format kunci API lokal yang dihasilkan +- Rahasia penyedia (kunci/token API) disimpan di DB lokal dan harus dilindungi di tingkat sistem file +- Titik akhir sinkronisasi cloud mengandalkan autentikasi kunci API + semantik id mesin + +## Matriks Lingkungan dan Runtime + +Variabel lingkungan yang aktif digunakan oleh kode: + +- Aplikasi/autentikasi: `JWT_SECRET`, `INITIAL_PASSWORD` +- Penyimpanan: `DATA_DIR` +- Perilaku node yang kompatibel: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Penggantian basis penyimpanan opsional (Linux/macOS ketika `DATA_DIR` tidak disetel): `XDG_CONFIG_HOME` +- Pencirian keamanan: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Pencatatan: `ENABLE_REQUEST_LOGS` +- URL sinkronisasi/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Proksi keluar: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` dan varian huruf kecil +- Bendera fitur SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Pembantu platform/runtime (bukan konfigurasi khusus aplikasi): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Catatan Arsitektur yang Dikenal + +1. `usageDb` dan `localDb` sekarang berbagi kebijakan direktori dasar yang sama (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) dengan migrasi file lama. +2. `/api/v1/route.ts` mengembalikan daftar model statis dan bukan sumber model utama yang digunakan oleh `/v1/models`. +3. Pencatat permintaan menulis header/isi lengkap saat diaktifkan; memperlakukan direktori log sebagai sensitif. +4. Perilaku cloud bergantung pada `NEXT_PUBLIC_BASE_URL` yang benar dan jangkauan titik akhir cloud. +5. Direktori `open-sse/` diterbitkan sebagai `@omniroute/open-sse` **paket ruang kerja npm**. Kode sumber mengimpornya melalui `@omniroute/open-sse/...` (diselesaikan oleh Next.js `transpilePackages`). Jalur file dalam dokumen ini masih menggunakan nama direktori `open-sse/` untuk konsistensi. +6. Bagan di dasbor menggunakan **Recharts** (berbasis SVG) untuk visualisasi analitik interaktif yang mudah diakses (diagram batang penggunaan model, tabel perincian penyedia dengan tingkat keberhasilan). +7. Tes E2E menggunakan **Playwright** (`tests/e2e/`), dijalankan melalui `npm run test:e2e`. Pengujian unit menggunakan **Node.js test runner** (`tests/unit/`), dijalankan melalui `npm run test:plan3`. Kode sumber di bawah `src/` adalah **TypeScript** (`.ts`/`.tsx`); ruang kerja `open-sse/` tetap JavaScript (`.js`). +8. Halaman pengaturan disusun dalam 5 tab: Keamanan, Perutean (6 strategi global: isi dulu, round-robin, p2c, acak, jarang digunakan, optimal biaya), Ketahanan (batas kecepatan yang dapat diedit, pemutus sirkuit, kebijakan), AI (anggaran berpikir, perintah sistem, cache cepat), Lanjutan (proxy). + +## Daftar Periksa Verifikasi Operasional + +- Bangun dari sumber: `npm run build` +- Bangun gambar Docker: `docker build -t omniroute .` +- Mulai layanan dan verifikasi: +- `GET /api/settings` +- `GET /api/v1/models` +- URL dasar target CLI harus `http://:20128/v1` ketika `PORT=20128` diff --git a/docs/i18n/id/CODEBASE_DOCUMENTATION.md b/docs/i18n/id/CODEBASE_DOCUMENTATION.md new file mode 100644 index 00000000..2fe77820 --- /dev/null +++ b/docs/i18n/id/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute — Dokumentasi Basis Kode + +🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) + +> Panduan komprehensif dan mudah bagi pemula untuk router proxy AI multi-penyedia **omniroute**. + +--- + +## 1. Apa itu omniroute? + +omniroute adalah **router proxy** yang berada di antara klien AI (Claude CLI, Codex, Cursor IDE, dll.) dan penyedia AI (Anthropic, Google, OpenAI, AWS, GitHub, dll.). Ini memecahkan satu masalah besar: + +> **Klien AI yang berbeda menggunakan "bahasa" (format API) yang berbeda, dan penyedia AI yang berbeda juga mengharapkan "bahasa" yang berbeda.** omniroute menerjemahkan bahasa tersebut secara otomatis. + +Anggap saja seperti penerjemah universal di Perserikatan Bangsa-Bangsa — setiap delegasi dapat berbicara dalam bahasa apa pun, dan penerjemah tersebut mengonversikannya untuk delegasi lainnya. + +--- + +## 2. Ikhtisar Arsitektur + +```mermaid +graph LR + subgraph Clients + A[Claude CLI] + B[Codex] + C[Cursor IDE] + D[OpenAI-compatible] + end + + subgraph omniroute + E[Handler Layer] + F[Translator Layer] + G[Executor Layer] + H[Services Layer] + end + + subgraph Providers + I[Anthropic Claude] + J[Google Gemini] + K[OpenAI / Codex] + L[GitHub Copilot] + M[AWS Kiro] + N[Antigravity] + O[Cursor API] + end + + A --> E + B --> E + C --> E + D --> E + E --> F + F --> G + G --> I + G --> J + G --> K + G --> L + G --> M + G --> N + G --> O + H -.-> E + H -.-> G +``` + +### Prinsip Inti: Penerjemahan Hub-and-Spoke + +Semua terjemahan format melewati **format OpenAI sebagai hub**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +Artinya, Anda hanya memerlukan **N penerjemah** (satu per format) dan bukan **N²** (setiap pasangan). + +--- + +## 3. Struktur Proyek + +``` +omniroute/ +├── open-sse/ ← Core proxy library (portable, framework-agnostic) +│ ├── index.js ← Main entry point, exports everything +│ ├── config/ ← Configuration & constants +│ ├── executors/ ← Provider-specific request execution +│ ├── handlers/ ← Request handling orchestration +│ ├── services/ ← Business logic (auth, models, fallback, usage) +│ ├── translator/ ← Format translation engine +│ │ ├── request/ ← Request translators (8 files) +│ │ ├── response/ ← Response translators (7 files) +│ │ └── helpers/ ← Shared translation utilities (6 files) +│ └── utils/ ← Utility functions +├── src/ ← Application layer (Express/Worker runtime) +│ ├── app/ ← Web UI, API routes, middleware +│ ├── lib/ ← Database, auth, and shared library code +│ ├── mitm/ ← Man-in-the-middle proxy utilities +│ ├── models/ ← Database models +│ ├── shared/ ← Shared utilities (wrappers around open-sse) +│ ├── sse/ ← SSE endpoint handlers +│ └── store/ ← State management +├── data/ ← Runtime data (credentials, logs) +│ └── provider-credentials.json (external credentials override, gitignored) +└── tester/ ← Test utilities +``` + +--- + +## 4. Perincian Modul demi Modul + +### 4.1 Konfigurasi (`open-sse/config/`) + +**Satu-satunya sumber kebenaran** untuk semua konfigurasi penyedia. + +| Berkas | Tujuan | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | Objek `PROVIDERS` dengan URL dasar, kredensial OAuth (default), header, dan perintah sistem default untuk setiap penyedia. Juga mendefinisikan `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, dan `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Memuat kredensial eksternal dari `data/provider-credentials.json` dan menggabungkannya melalui default hardcode di `PROVIDERS`. Menjaga rahasia di luar kendali sumber sambil menjaga kompatibilitas ke belakang. | +| `providerModels.ts` | Registri model pusat: alias penyedia peta → ID model. Fungsi seperti `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | Instruksi sistem dimasukkan ke dalam permintaan Codex (batasan pengeditan, aturan sandbox, kebijakan persetujuan). | +| `defaultThinkingSignature.ts` | Tanda tangan "berpikir" default untuk model Claude dan Gemini. | +| `ollamaModels.ts` | Definisi skema untuk model Ollama lokal (nama, ukuran, keluarga, kuantisasi). | + +#### Alur Pemuatan Kredensial + +```mermaid +flowchart TD + A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"] + B --> C{"data/provider-credentials.json\nexists?"} + C -->|Yes| D["credentialLoader reads JSON"] + C -->|No| E["Use hardcoded defaults"] + D --> F{"For each provider in JSON"} + F --> G{"Provider exists\nin PROVIDERS?"} + G -->|No| H["Log warning, skip"] + G -->|Yes| I{"Value is object?"} + I -->|No| J["Log warning, skip"] + I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"] + K --> F + H --> F + J --> F + F -->|Done| L["PROVIDERS ready with\nmerged credentials"] + E --> L +``` + +--- + +### 4.2 Pelaksana (`open-sse/executors/`) + +Pelaksana merangkum **logika khusus penyedia** menggunakan **Pola Strategi**. Setiap pelaksana mengganti metode dasar sesuai kebutuhan. + +```mermaid +classDiagram + class BaseExecutor { + +buildUrl(model, stream, options) + +buildHeaders(credentials, stream, body) + +transformRequest(body, model, stream, credentials) + +execute(url, options) + +shouldRetry(status, error) + +refreshCredentials(credentials, log) + } + + class DefaultExecutor { + +refreshCredentials() + } + + class AntigravityExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +shouldRetry() + +refreshCredentials() + } + + class CursorExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseResponse() + +generateChecksum() + } + + class KiroExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseEventStream() + +refreshCredentials() + } + + BaseExecutor <|-- DefaultExecutor + BaseExecutor <|-- AntigravityExecutor + BaseExecutor <|-- CursorExecutor + BaseExecutor <|-- KiroExecutor + BaseExecutor <|-- CodexExecutor + BaseExecutor <|-- GeminiCLIExecutor + BaseExecutor <|-- GithubExecutor +``` + +| Pelaksana | Penyedia | Spesialisasi Utama | +| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Basis abstrak: Pembuatan URL, header, logika coba lagi, penyegaran kredensial | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Penyegaran token OAuth generik untuk penyedia standar | +| `antigravity.ts` | Kode Google Cloud | Pembuatan ID proyek/sesi, penggantian multi-URL, penguraian coba ulang khusus dari pesan kesalahan ("reset setelah 2h7m23s") | +| `cursor.ts` | IDE Kursor | **Paling rumit**: autentikasi checksum SHA-256, pengkodean permintaan Protobuf, biner EventStream → penguraian respons SSE | +| `codex.ts` | Kodeks OpenAI | Menyuntikkan instruksi sistem, mengelola tingkat pemikiran, menghapus parameter yang tidak didukung | +| `gemini-cli.ts` | CLI Google Gemini | Pembuatan URL khusus (`streamGenerateContent`), penyegaran token Google OAuth | +| `github.ts` | Kopilot GitHub | Sistem token ganda (GitHub OAuth + token Copilot), header VSCode meniru | +| `kiro.ts` | AWS CodeWhisperer | Penguraian biner AWS EventStream, bingkai peristiwa AMZN, estimasi token | +| `index.ts` | — | Pabrik: nama penyedia peta → kelas pelaksana, dengan fallback default | + +--- + +### 4.3 Penangan (`open-sse/handlers/`) + +**Lapisan orkestrasi** — mengoordinasikan terjemahan, eksekusi, streaming, dan penanganan kesalahan. + +| Berkas | Tujuan | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `chatCore.ts` | **Orkestra pusat** (~600 baris). Menangani siklus hidup permintaan secara lengkap: deteksi format → terjemahan → pengiriman pelaksana → respons streaming/non-streaming → penyegaran token → penanganan kesalahan → pencatatan penggunaan. | +| `responsesHandler.ts` | Adaptor untuk API Respons OpenAI: mengonversi format Respons → Penyelesaian Obrolan → mengirim ke `chatCore` → mengonversi SSE kembali ke format Respons. | +| `embeddings.ts` | Penangan generasi penyematan: menyelesaikan model penyematan → penyedia, mengirimkan ke API penyedia, mengembalikan respons penyematan yang kompatibel dengan OpenAI. Mendukung 6+ penyedia. | +| `imageGeneration.ts` | Pengendali pembuatan gambar: menyelesaikan model gambar → penyedia, mendukung mode yang kompatibel dengan OpenAI, gambar Gemini (Antigravity), dan fallback (Nebius). Mengembalikan gambar base64 atau URL. | + +#### Siklus Hidup Permintaan (chatCore.ts) + +```mermaid +sequenceDiagram + participant Client + participant chatCore + participant Translator + participant Executor + participant Provider + + Client->>chatCore: Request (any format) + chatCore->>chatCore: Detect source format + chatCore->>chatCore: Check bypass patterns + chatCore->>chatCore: Resolve model & provider + chatCore->>Translator: Translate request (source → OpenAI → target) + chatCore->>Executor: Get executor for provider + Executor->>Executor: Build URL, headers, transform request + Executor->>Executor: Refresh credentials if needed + Executor->>Provider: HTTP fetch (streaming or non-streaming) + + alt Streaming + Provider-->>chatCore: SSE stream + chatCore->>chatCore: Pipe through SSE transform stream + Note over chatCore: Transform stream translates
each chunk: target → OpenAI → source + chatCore-->>Client: Translated SSE stream + else Non-streaming + Provider-->>chatCore: JSON response + chatCore->>Translator: Translate response + chatCore-->>Client: Translated JSON + end + + alt Error (401, 429, 500...) + chatCore->>Executor: Retry with credential refresh + chatCore->>chatCore: Account fallback logic + end +``` + +--- + +### 4.4 Layanan (`open-sse/services/`) + +Logika bisnis yang mendukung penangan dan pelaksana. + +| Berkas | Tujuan | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Deteksi format** (`detectFormat`): menganalisis struktur isi permintaan untuk mengidentifikasi format Claude/OpenAI/Gemini/Antigravity/Responses (termasuk heuristik `max_tokens` untuk Claude). Juga: pembuatan URL, pembuatan header, normalisasi konfigurasi pemikiran. Mendukung penyedia dinamis `openai-compatible-*` dan `anthropic-compatible-*`. | +| `model.ts` | Penguraian string model (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolusi alias dengan deteksi tabrakan, sanitasi input (menolak traversal jalur/karakter kontrol), dan resolusi info model dengan dukungan pengambil alias asinkron. | +| `accountFallback.ts` | Penanganan batas kecepatan: backoff eksponensial (1 dtk → 2 dtk → 4 dtk → maks 2 menit), manajemen cooldown akun, klasifikasi kesalahan (kesalahan mana yang memicu fallback vs. tidak). | +| `tokenRefresh.ts` | Penyegaran token OAuth untuk **setiap penyedia**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Termasuk cache deduplikasi janji dalam penerbangan dan coba lagi dengan backoff eksponensial. | +| `combo.ts` | **Model kombo**: rangkaian model cadangan. Jika model A gagal dengan kesalahan yang memenuhi syarat fallback, coba model B, lalu C, dan seterusnya. Mengembalikan kode status upstream yang sebenarnya. | +| `usage.ts` | Mengambil data kuota/penggunaan dari API penyedia (kuota GitHub Copilot, kuota model Antigravity, batas kecepatan Codex, perincian penggunaan Kiro, pengaturan Claude). | +| `accountSelector.ts` | Pemilihan akun cerdas dengan algoritma penilaian: mempertimbangkan prioritas, status kesehatan, posisi round-robin, dan status cooldown untuk memilih akun optimal untuk setiap permintaan. | +| `contextManager.ts` | Manajemen siklus hidup konteks permintaan: membuat dan melacak objek konteks per permintaan dengan metadata (ID permintaan, stempel waktu, info penyedia) untuk debugging dan logging. | +| `ipFilter.ts` | Kontrol akses berbasis IP: mendukung mode daftar yang diizinkan dan daftar blokir. Memvalidasi IP klien terhadap aturan yang dikonfigurasi sebelum memproses permintaan API. | +| `sessionManager.ts` | Pelacakan sesi dengan sidik jari klien: melacak sesi aktif menggunakan pengidentifikasi klien yang di-hash, memantau jumlah permintaan, dan menyediakan metrik sesi. | +| `signatureCache.ts` | Permintaan cache deduplikasi berbasis tanda tangan: mencegah permintaan duplikat dengan menyimpan tanda tangan permintaan terbaru dalam cache dan mengembalikan respons cache untuk permintaan serupa dalam jangka waktu tertentu. | +| `systemPrompt.ts` | Injeksi perintah sistem global: menambahkan atau menambahkan perintah sistem yang dapat dikonfigurasi ke semua permintaan, dengan penanganan kompatibilitas per penyedia. | +| `thinkingBudget.ts` | Manajemen anggaran token penalaran: mendukung mode passthrough, otomatis (konfigurasi pemikiran strip), kustom (anggaran tetap), dan adaptif (skala kompleksitas) untuk mengendalikan token pemikiran/penalaran. | +| `wildcardRouter.ts` | Perutean pola model wildcard: menyelesaikan pola wildcard (misalnya, `*/claude-*`) ke pasangan penyedia/model tertentu berdasarkan ketersediaan dan prioritas. | + +#### Deduplikasi Penyegaran Token + +```mermaid +sequenceDiagram + participant R1 as Request 1 + participant R2 as Request 2 + participant Cache as refreshPromiseCache + participant OAuth as OAuth Provider + + R1->>Cache: getAccessToken("gemini", token) + Cache->>Cache: No in-flight promise + Cache->>OAuth: Start refresh + R2->>Cache: getAccessToken("gemini", token) + Cache->>Cache: Found in-flight promise + Cache-->>R2: Return existing promise + OAuth-->>Cache: New access token + Cache-->>R1: New access token + Cache-->>R2: Same access token (shared) + Cache->>Cache: Delete cache entry +``` + +#### Mesin Status Penggantian Akun + +```mermaid +stateDiagram-v2 + [*] --> Active + Active --> Error: Request fails (401/429/500) + Error --> Cooldown: Apply backoff + Cooldown --> Active: Cooldown expires + Active --> Active: Request succeeds (reset backoff) + + state Error { + [*] --> ClassifyError + ClassifyError --> ShouldFallback: Rate limit / Auth / Transient + ClassifyError --> NoFallback: 400 Bad Request + } + + state Cooldown { + [*] --> ExponentialBackoff + ExponentialBackoff: Level 0 = 1s + ExponentialBackoff: Level 1 = 2s + ExponentialBackoff: Level 2 = 4s + ExponentialBackoff: Max = 2min + } +``` + +#### Rantai Model Kombo + +```mermaid +flowchart LR + A["Request with\ncombo model"] --> B["Model A"] + B -->|"2xx Success"| C["Return response"] + B -->|"429/401/500"| D{"Fallback\neligible?"} + D -->|Yes| E["Model B"] + D -->|No| F["Return error"] + E -->|"2xx Success"| C + E -->|"429/401/500"| G{"Fallback\neligible?"} + G -->|Yes| H["Model C"] + G -->|No| F + H -->|"2xx Success"| C + H -->|"Fail"| I["All failed →\nReturn last status"] +``` + +--- + +### 4.5 Penerjemah (`open-sse/translator/`) + +**mesin terjemahan format** menggunakan sistem plugin pendaftaran mandiri. + +#### Arsitektur + +```mermaid +graph TD + subgraph "Request Translation" + A["Claude → OpenAI"] + B["Gemini → OpenAI"] + C["Antigravity → OpenAI"] + D["OpenAI Responses → OpenAI"] + E["OpenAI → Claude"] + F["OpenAI → Gemini"] + G["OpenAI → Kiro"] + H["OpenAI → Cursor"] + end + + subgraph "Response Translation" + I["Claude → OpenAI"] + J["Gemini → OpenAI"] + K["Kiro → OpenAI"] + L["Cursor → OpenAI"] + M["OpenAI → Claude"] + N["OpenAI → Antigravity"] + O["OpenAI → Responses"] + end +``` + +| Direktori | File | Deskripsi | +| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `request/` | 8 penerjemah | Konversi badan permintaan antar format. Setiap file didaftarkan sendiri melalui `register(from, to, fn)` saat diimpor. | +| `response/` | 7 penerjemah | Konversikan potongan respons streaming antar format. Menangani jenis acara SSE, blok pemikiran, panggilan alat. | +| `helpers/` | 6 pembantu | Utilitas bersama: `claudeHelper` (ekstraksi prompt sistem, konfigurasi pemikiran), `geminiHelper` (pemetaan bagian/konten), `openaiHelper` (pemfilteran format), `toolCallHelper` (pembuatan ID, injeksi respons hilang), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Mesin penerjemah: `translateRequest()`, `translateResponse()`, manajemen negara, registri. | +| `formats.ts` | — | Konstanta format: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | + +#### Desain Kunci: Plugin Pendaftaran Mandiri + +```javascript +// Each translator file calls register() on import: +import { register } from "../index.js"; +register("claude", "openai", translateClaudeToOpenAI); + +// The index.js imports all translator files, triggering registration: +import "./request/claude-to-openai.js"; // ← self-registers +``` + +--- + +### 4.6 Kegunaan (`open-sse/utils/`) + +| Berkas | Tujuan | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | Pembuatan respons kesalahan (format yang kompatibel dengan OpenAI), penguraian kesalahan hulu, ekstraksi waktu percobaan ulang Antigravitasi dari pesan kesalahan, streaming kesalahan SSE. | +| `stream.ts` | **SSE Transform Stream** — saluran streaming inti. Dua mode: `TRANSLATE` (terjemahan format penuh) dan `PASSTHROUGH` (menormalkan + mengekstrak penggunaan). Menangani buffering potongan, estimasi penggunaan, pelacakan panjang konten. Instance encoder/decoder per-aliran menghindari status bersama. | +| `streamHelpers.ts` | Utilitas SSE tingkat rendah: `parseSSELine` (toleran spasi), `hasValuableContent` (memfilter potongan kosong untuk OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialisasi SSE yang mendukung format dengan pembersihan `perf_metrics`). | +| `usageTracking.ts` | Ekstraksi penggunaan token dari format apa pun (Claude/OpenAI/Gemini/Responses), estimasi dengan rasio karakter per token alat/pesan terpisah, penambahan buffer (margin keamanan token 2000), pemfilteran bidang khusus format, logging konsol dengan warna ANSI. | +| `requestLogger.ts` | Pencatatan permintaan berbasis file (ikut serta melalui `ENABLE_REQUEST_LOGS=true`). Membuat folder sesi dengan file bernomor: `1_req_client.json` → `7_res_client.txt`. Semua I/O bersifat asinkron (api-dan-lupakan). Menutupi header sensitif. | +| `bypassHandler.ts` | Mencegat pola tertentu dari Claude CLI (ekstraksi judul, pemanasan, penghitungan) dan mengembalikan respons palsu tanpa menghubungi penyedia mana pun. Mendukung streaming dan non-streaming. Sengaja dibatasi pada scope Claude CLI. | +| `networkProxy.ts` | Menyelesaikan URL proksi keluar untuk penyedia tertentu dengan prioritas: konfigurasi khusus penyedia → konfigurasi global → variabel lingkungan (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Mendukung pengecualian `NO_PROXY`. Konfigurasi cache selama 30 detik. | + +#### Saluran Pipa Streaming SSE + +```mermaid +flowchart TD + A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"] + B --> C["Buffer lines\n(split on newline)"] + C --> D["parseSSELine()\n(trim whitespace, parse JSON)"] + D --> E{"Mode?"} + E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"] + E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"] + F --> H["hasValuableContent()\nfilter empty chunks"] + G --> H + H -->|"Has content"| I["extractUsage()\ntrack token counts"] + H -->|"Empty"| J["Skip chunk"] + I --> K["formatSSE()\nserialize + clean perf_metrics"] + K --> L["TextEncoder\n(per-stream instance)"] + L --> M["Enqueue to\nclient stream"] + + style A fill:#f9f,stroke:#333 + style M fill:#9f9,stroke:#333 +``` + +#### Struktur Sesi Pencatat Permintaan + +``` +logs/ +└── claude_gemini_claude-sonnet_20260208_143045/ + ├── 1_req_client.json ← Raw client request + ├── 2_req_source.json ← After initial conversion + ├── 3_req_openai.json ← OpenAI intermediate format + ├── 4_req_target.json ← Final target format + ├── 5_res_provider.txt ← Provider SSE chunks (streaming) + ├── 5_res_provider.json ← Provider response (non-streaming) + ├── 6_res_openai.txt ← OpenAI intermediate chunks + ├── 7_res_client.txt ← Client-facing SSE chunks + └── 6_error.json ← Error details (if any) +``` + +--- + +### 4.7 Lapisan Aplikasi (`src/`) + +| Direktori | Tujuan | +| ------------- | ------------------------------------------------------------------------------------ | +| `src/app/` | UI web, rute API, middleware Express, penangan panggilan balik OAuth | +| `src/lib/` | Akses basis data (`localDb.ts`, `usageDb.ts`), autentikasi, dibagikan | +| `src/mitm/` | Utilitas proxy man-in-the-middle untuk mencegat lalu lintas penyedia | +| `src/models/` | Definisi model basis data | +| `src/shared/` | Pembungkus di sekitar fungsi open-sse (penyedia, aliran, kesalahan, dll.) | +| `src/sse/` | Penangan titik akhir SSE yang menghubungkan perpustakaan sse terbuka ke rute Ekspres | +| `src/store/` | Manajemen status aplikasi | + +#### Rute API Penting + +| Rute | Metode | Tujuan | +| --------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | +| `/api/provider-models` | DAPATKAN/POSTING/HAPUS | CRUD untuk model khusus per penyedia | +| `/api/models/catalog` | DAPATKAN | Katalog gabungan semua model (obrolan, penyematan, gambar, khusus) dikelompokkan berdasarkan penyedia | +| `/api/settings/proxy` | DAPATKAN/MASUKKAN/HAPUS | Konfigurasi proksi keluar hierarki (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POSTING | Memvalidasi konektivitas proxy dan mengembalikan IP/latensi publik | +| `/v1/providers/[provider]/chat/completions` | POSTING | Penyelesaian obrolan khusus per penyedia dengan validasi model | +| `/v1/providers/[provider]/embeddings` | POSTING | Penyematan khusus per penyedia dengan validasi model | +| `/v1/providers/[provider]/images/generations` | POSTING | Pembuatan gambar khusus per penyedia dengan validasi model | +| `/api/settings/ip-filter` | DAPATKAN/MASUKKAN | Manajemen daftar IP yang diizinkan/daftar blokir | +| `/api/settings/thinking-budget` | DAPATKAN/MASUKKAN | Penalaran konfigurasi anggaran token (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | DAPATKAN/MASUKKAN | Injeksi prompt sistem global untuk semua permintaan | +| `/api/sessions` | DAPATKAN | Pelacakan dan metrik sesi aktif | +| `/api/rate-limits` | DAPATKAN | Status batas tarif per akun | + +--- + +## 5. Pola Desain Utama + +### 5.1 Terjemahan Hub-and-Spoke + +Semua format diterjemahkan melalui **format OpenAI sebagai hub**. Menambahkan penyedia baru hanya memerlukan penulisan **satu pasang** penerjemah (ke/dari OpenAI), bukan N pasang. + +### 5.2 Pola Strategi Pelaksana + +Setiap penyedia memiliki kelas eksekutor khusus yang diwarisi dari `BaseExecutor`. Pabrik di `executors/index.ts` memilih yang tepat saat runtime. + +### 5.3 Sistem Plugin Pendaftaran Mandiri + +Modul penerjemah mendaftarkan dirinya saat diimpor melalui `register()`. Menambahkan penerjemah baru hanyalah membuat file dan mengimpornya. + +### 5.4 Penggantian Akun dengan Backoff Eksponensial + +Ketika penyedia mengembalikan 429/401/500, sistem dapat beralih ke akun berikutnya, menerapkan cooldown eksponensial (1 dtk → 2 dtk → 4 dtk → maksimal 2 menit). + +### 5.5 Rantai Model Kombo + +Sebuah "kombo" mengelompokkan beberapa string `provider/model`. Jika yang pertama gagal, kembali ke yang berikutnya secara otomatis. + +### 5.6 Terjemahan Streaming Stateful + +Terjemahan respons mempertahankan status di seluruh potongan SSE (pelacakan blok pemikiran, akumulasi panggilan alat, pengindeksan blok konten) melalui mekanisme `initState()`. + +### 5.7 Buffer Keamanan Penggunaan + +Buffer 2000 token ditambahkan ke penggunaan yang dilaporkan untuk mencegah klien mencapai batas jendela konteks karena overhead dari perintah sistem dan terjemahan format. + +--- + +## 6. Format yang Didukung + +| Format | Arah | Pengenal | +| --------------------------- | ---------------- | ------------------ | +| Penyelesaian Obrolan OpenAI | sumber + sasaran | `openai` | +| API Respons OpenAI | sumber + sasaran | `openai-responses` | +| Claude Antropik | sumber + sasaran | `claude` | +| Google Gemini | sumber + sasaran | `gemini` | +| CLI Google Gemini | hanya sasaran | `gemini-cli` | +| Antigravitasi | sumber + sasaran | `antigravity` | +| AWSKiro | hanya sasaran | `kiro` | +| Kursor | hanya sasaran | `cursor` | + +--- + +## 7. Penyedia yang Didukung + +| Penyedia | Metode Otentikasi | Pelaksana | Catatan Penting | +| ------------------------ | ------------------------ | ------------- | ---------------------------------------------------------- | +| Claude Antropik | Kunci API atau OAuth | Bawaan | Menggunakan tajuk `x-api-key` | +| Google Gemini | Kunci API atau OAuth | Bawaan | Menggunakan tajuk `x-goog-api-key` | +| CLI Google Gemini | OAuth | Gemini CLI | Menggunakan titik akhir `streamGenerateContent` | +| Antigravitasi | OAuth | Antigravitasi | Penggantian multi-URL, penguraian coba ulang khusus | +| OpenAI | Kunci API | Bawaan | Autentikasi Pembawa Standar | +| Kodeks | OAuth | Kodeks | Menyuntikkan instruksi sistem, mengelola pemikiran | +| Kopilot GitHub | OAuth + Token Kopilot | Github | Token ganda, header VSCode meniru | +| Kiro (AWS) | AWS SSO OIDC atau Sosial | Kiro | Penguraian Biner EventStream | +| IDE Kursor | Otentikasi checksum | Kursor | Pengkodean protobuf, checksum SHA-256 | +| Qwen | OAuth | Bawaan | Otentikasi standar | +| iFlow | OAuth (Dasar + Pembawa) | Bawaan | Header autentikasi ganda | +| BukaRouter | Kunci API | Bawaan | Autentikasi Pembawa Standar | +| GLM, Kimi, MiniMax | Kunci API | Bawaan | Kompatibel dengan Claude, gunakan `x-api-key` | +| `openai-compatible-*` | Kunci API | Bawaan | Dinamis: semua titik akhir yang kompatibel dengan OpenAI | +| `anthropic-compatible-*` | Kunci API | Bawaan | Dinamis: titik akhir apa pun yang kompatibel dengan Claude | + +--- + +## 8. Ringkasan Aliran Data + +### Permintaan Streaming + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor\nbuildUrl + buildHeaders"] + D --> E["fetch(providerURL)"] + E --> F["createSSEStream()\nTRANSLATE mode"] + F --> G["parseSSELine()"] + G --> H["translateResponse()\ntarget → OpenAI → source"] + H --> I["extractUsage()\n+ addBuffer"] + I --> J["formatSSE()"] + J --> K["Client receives\ntranslated SSE"] + K --> L["logUsage()\nsaveRequestUsage()"] +``` + +### Permintaan Non-Streaming + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor.execute()"] + D --> E["translateResponse()\ntarget → OpenAI → source"] + E --> F["Return JSON\nresponse"] +``` + +### Aliran Bypass (Claude CLI) + +```mermaid +flowchart LR + A["Claude CLI request"] --> B{"Match bypass\npattern?"} + B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] + B -->|"No match"| D["Normal flow"] + C --> E["Translate to\nsource format"] + E --> F["Return without\ncalling provider"] +``` diff --git a/docs/i18n/id/FEATURES.md b/docs/i18n/id/FEATURES.md new file mode 100644 index 00000000..f348e734 --- /dev/null +++ b/docs/i18n/id/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — Galeri Fitur Dasbor + +🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) + +Panduan visual untuk setiap bagian dasbor OmniRoute. + +--- + +## 🔌 Penyedia + +Kelola koneksi penyedia AI: Penyedia OAuth (Claude Code, Codex, Gemini CLI), penyedia kunci API (Groq, DeepSeek, OpenRouter), dan penyedia gratis (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨 Kombo + +Buat kombo perutean model dengan 6 strategi: pengisian pertama, round-robin, pilihan ganda, acak, paling jarang digunakan, dan hemat biaya. Setiap kombo merangkai beberapa model dengan fallback otomatis. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Analisis + +Analisis penggunaan yang komprehensif dengan konsumsi token, perkiraan biaya, peta panas aktivitas, grafik distribusi mingguan, dan perincian per penyedia. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Kesehatan Sistem + +Pemantauan waktu nyata: waktu aktif, memori, versi, persentil latensi (p50/p95/p99), statistik cache, dan status pemutus sirkuit penyedia. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Taman Bermain Penerjemah + +Empat mode untuk men-debug terjemahan API: **Playground** (konverter format), **Chat Tester** (permintaan langsung), **Test Bench** (pengujian batch), dan **Live Monitor** (streaming real-time). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Pengaturan + +Pengaturan umum, penyimpanan sistem, manajemen cadangan (database ekspor/impor), tampilan (mode gelap/terang), keamanan (termasuk perlindungan titik akhir API dan pemblokiran penyedia khusus), perutean, ketahanan, dan konfigurasi lanjutan. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Alat CLI + +Konfigurasi sekali klik untuk alat pengkodean AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, dan Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Minta Log + +Pencatatan permintaan secara real-time dengan pemfilteran berdasarkan penyedia, model, akun, dan kunci API. Menampilkan kode status, penggunaan token, latensi, dan detail respons. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 Titik Akhir API + +Titik akhir API terpadu Anda dengan perincian kemampuan: Penyelesaian Obrolan, Penyematan, Pembuatan Gambar, Pemeringkatan Ulang, Transkripsi Audio, dan kunci API terdaftar. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/id/TROUBLESHOOTING.md b/docs/i18n/id/TROUBLESHOOTING.md new file mode 100644 index 00000000..278e3fb3 --- /dev/null +++ b/docs/i18n/id/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Pemecahan masalah + +🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) + +Masalah umum dan solusi untuk OmniRoute. + +--- + +## Perbaikan Cepat + +| Masalah | Solusi | +| ----------------------------------------- | ----------------------------------------------------------------------- | +| Login pertama tidak berfungsi | Centang `INITIAL_PASSWORD` di `.env` (default: `123456`) | +| Dasbor terbuka pada port yang salah | Tetapkan `PORT=20128` dan `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Tidak ada log permintaan di bawah `logs/` | Setel `ENABLE_REQUEST_LOGS=true` | +| EACCES: izin ditolak | Setel `DATA_DIR=/path/to/writable/dir` untuk mengganti `~/.omniroute` | +| Strategi perutean tidak menyimpan | Perbarui ke v1.4.11+ (perbaikan skema Zod untuk persistensi pengaturan) | + +--- + +## Masalah Penyedia + +### "Model bahasa tidak memberikan pesan" + +**Penyebab:** Kuota penyedia habis. + +**Perbaikan:** + +1. Periksa pelacak kuota dasbor +2. Gunakan kombo dengan tier fallback +3. Beralih ke tingkat yang lebih murah/gratis + +### Pembatasan Nilai + +**Penyebab:** Kuota berlangganan habis. + +**Perbaikan:** + +- Tambahkan cadangan: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Gunakan GLM/MiniMax sebagai cadangan murah + +### Token OAuth Kedaluwarsa + +OmniRoute menyegarkan token secara otomatis. Jika masalah terus berlanjut: + +1. Dasbor → Penyedia → Sambungkan kembali +2. Hapus dan tambahkan kembali koneksi penyedia + +--- + +## Masalah Awan + +### Kesalahan Sinkronisasi Cloud + +1. Verifikasikan `BASE_URL` poin ke instance Anda yang sedang berjalan (misalnya, `http://localhost:20128`) +2. Verifikasikan `CLOUD_URL` poin ke titik akhir cloud Anda (misalnya, `https://omniroute.dev`) +3. Jaga agar nilai `NEXT_PUBLIC_*` selaras dengan nilai sisi server + +### Cloud `stream=false` Mengembalikan 500 + +**Gejala:** `Unexpected token 'd'...` di titik akhir cloud untuk panggilan non-streaming. + +**Penyebab:** Upstream mengembalikan payload SSE sementara klien mengharapkan JSON. + +**Solusi:** Gunakan `stream=true` untuk panggilan langsung cloud. Waktu proses lokal mencakup penggantian SSE→JSON. + +### Cloud Mengatakan Terhubung tetapi "Kunci API tidak valid" + +1. Buat kunci baru dari dasbor lokal (`/api/keys`) +2. Jalankan sinkronisasi cloud: Aktifkan Cloud → Sinkronkan Sekarang +3. Kunci lama/tidak tersinkronisasi masih dapat mengembalikan `401` di cloud + +--- + +## Masalah Docker + +### Alat CLI Tidak Dipasang + +1. Periksa kolom runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Untuk mode portabel: gunakan target gambar `runner-cli` (CL yang dibundel) +3. Untuk mode pemasangan host: setel `CLI_EXTRA_PATHS` dan pasang direktori host bin sebagai hanya-baca +4. Jika `installed=true` dan `runnable=false`: biner ditemukan tetapi pemeriksaan kesehatan gagal + +### Validasi Waktu Proses Cepat + +```bash +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}' +``` + +--- + +## Masalah Biaya + +### Biaya Tinggi + +1. Periksa statistik penggunaan di Dashboard → Penggunaan +2. Ganti model utama ke GLM/MiniMax +3. Gunakan tingkat gratis (Gemini CLI, iFlow) untuk tugas-tugas yang tidak penting +4. Tetapkan anggaran biaya per kunci API: Dasbor → Kunci API → Anggaran + +--- + +## Men-debug + +### Aktifkan Log Permintaan + +Setel `ENABLE_REQUEST_LOGS=true` di file `.env` Anda. Log muncul di bawah direktori `logs/`. + +### Periksa Kesehatan Penyedia + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Penyimpanan Waktu Proses + +- Status utama: `${DATA_DIR}/db.json` (penyedia, kombo, alias, kunci, pengaturan) +- Penggunaan: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Log permintaan: `/logs/...` (saat `ENABLE_REQUEST_LOGS=true`) + +--- + +## Masalah Pemutus Arus + +### Penyedia terjebak dalam keadaan TERBUKA + +Ketika pemutus arus penyedia TERBUKA, permintaan diblokir hingga cooldown berakhir. + +**Perbaikan:** + +1. Buka **Dasbor → Pengaturan → Ketahanan** +2. Periksa kartu pemutus arus untuk penyedia yang terpengaruh +3. Klik **Reset Semua** untuk menghapus semua pemutus, atau tunggu hingga cooldown berakhir +4. Pastikan penyedia benar-benar tersedia sebelum melakukan reset + +### Penyedia terus membuat pemutus arus tersandung + +Jika penyedia berulang kali memasuki status OPEN: + +1. Periksa **Dasbor → Kesehatan → Kesehatan Penyedia** untuk mengetahui pola kegagalannya +2. Buka **Pengaturan → Ketahanan → Profil Penyedia** dan tingkatkan ambang kegagalan +3. Periksa apakah penyedia telah mengubah batas API atau memerlukan autentikasi ulang +4. Tinjau telemetri latensi — latensi tinggi dapat menyebabkan kegagalan berbasis waktu habis + +--- + +## Masalah Transkripsi Audio + +### Kesalahan "Model tidak didukung". + +- Pastikan Anda menggunakan awalan yang benar: `deepgram/nova-3` atau `assemblyai/best` +- Verifikasi penyedia terhubung di **Dasbor → Penyedia** + +### Transkripsi kembali kosong atau gagal + +- Periksa format audio yang didukung: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Pastikan ukuran file berada dalam batas penyedia (biasanya <25MB) +- Periksa validitas kunci API penyedia di kartu penyedia + +--- + +## Proses Debug Penerjemah + +Gunakan **Dasbor → Penerjemah** untuk men-debug masalah terjemahan format: + +| Modus | Kapan Menggunakan | +| -------------------- | -------------------------------------------------------------------------------------------------------------------- | +| **Taman bermain** | Bandingkan format masukan/keluaran secara berdampingan — tempelkan permintaan yang gagal untuk melihat terjemahannya | +| **Penguji Obrolan** | Kirim pesan langsung dan periksa muatan permintaan/respons lengkap termasuk header | +| **Bangku Tes** | Jalankan pengujian batch di seluruh kombinasi format untuk menemukan terjemahan mana yang rusak | +| **Monitor Langsung** | Tonton alur permintaan waktu nyata untuk mengetahui masalah terjemahan yang terputus-putus | + +### Masalah format umum + +- **Tag berpikir tidak muncul** — Periksa apakah penyedia target mendukung pemikiran dan pengaturan anggaran pemikiran +- **Panggilan alat terputus** — Beberapa terjemahan format mungkin menghapus bidang yang tidak didukung; verifikasi dalam mode Taman Bermain +- **Perintah sistem hilang** — Claude dan Gemini menangani perintah sistem secara berbeda; periksa keluaran terjemahan +- **SDK mengembalikan string mentah, bukan objek** — Diperbaiki di v1.1.0: pembersih respons sekarang menghapus kolom non-standar (`x_groq`, `usage_breakdown`, dll.) yang menyebabkan kegagalan validasi OpenAI SDK Pydantic +- **GLM/ERNIE menolak peran `system`** — Diperbaiki di v1.1.0: penormal peran secara otomatis menggabungkan pesan sistem ke dalam pesan pengguna untuk model yang tidak kompatibel +- **Peran `developer` tidak dikenali** — Diperbaiki di v1.1.0: otomatis dikonversi ke `system` untuk penyedia non-OpenAI +- **`json_schema` tidak berfungsi dengan Gemini** — Diperbaiki di v1.1.0: `response_format` kini dikonversi ke `responseMimeType` + `responseSchema` Gemini + +--- + +## Pengaturan Ketahanan + +### Batas tarif otomatis tidak terpicu + +- Batas tarif otomatis hanya berlaku untuk penyedia kunci API (bukan OAuth/langganan) +- Verifikasi **Pengaturan → Ketahanan → Profil Penyedia** telah mengaktifkan batas tarif otomatis +- Periksa apakah penyedia mengembalikan kode status `429` atau header `Retry-After` + +### Menyetel backoff eksponensial + +Profil penyedia mendukung pengaturan berikut: + +- **Penundaan dasar** — Waktu tunggu awal setelah kegagalan pertama (default: 1 detik) +- **Penundaan maksimal** — Batas waktu tunggu maksimum (default: 30 detik) +- **Pengganda** — Berapa banyak peningkatan penundaan per kegagalan berturut-turut (default: 2x) + +### Kawanan anti petir + +Ketika banyak permintaan bersamaan mencapai penyedia dengan tarif terbatas, OmniRoute menggunakan mutex + pembatasan tarif otomatis untuk membuat serialisasi permintaan dan mencegah kegagalan berjenjang. Ini otomatis untuk penyedia kunci API. + +--- + +## Masih Terjebak? + +- **Masalah GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Arsitektur**: Lihat [**OMNI_TOKEN_55**](ARCHITECTURE.md) untuk detail internal +- **Referensi API**: Lihat [**OMNI_TOKEN_56**](API_REFERENCE.md) untuk semua titik akhir +- **Dasbor Kesehatan**: Periksa **Dasbor → Kesehatan** untuk status sistem waktu nyata +- **Penerjemah**: Gunakan **Dasbor → Penerjemah** untuk men-debug masalah format diff --git a/docs/i18n/id/USER_GUIDE.md b/docs/i18n/id/USER_GUIDE.md new file mode 100644 index 00000000..85fdaa70 --- /dev/null +++ b/docs/i18n/id/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Panduan Pengguna + +🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) + +Panduan lengkap untuk mengonfigurasi penyedia, membuat kombo, mengintegrasikan alat CLI, dan menerapkan OmniRoute. + +--- + +## Daftar Isi + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [Provider Setup](#-provider-setup) +- [CLI Integration](#-cli-integration) +- [Deployment](#-deployment) +- [Available Models](#-available-models) +- [Advanced Features](#-advanced-features) + +--- + +## 💰 Sekilas tentang Harga + +| Tingkat | Penyedia | Biaya | Reset Kuota | Terbaik Untuk | +| ------------------- | ----------------- | -------------------- | ------------------------- | --------------------------- | +| **💳 BERLANGGANAN** | Kode Claude (Pro) | $20/bln | 5 jam + mingguan | Sudah berlangganan | +| | Kodeks (Plus/Pro) | $20-200/bln | 5 jam + mingguan | Pengguna OpenAI | +| | CLI Gemini | **GRATIS** | 180K/bln + 1K/hari | Setiap orang! | +| | Kopilot GitHub | $10-19/bln | Bulanan | Pengguna GitHub | +| **🔑 KUNCI API** | Pencarian Dalam | Bayar per penggunaan | Tidak ada | Alasan murah | +| | Bagus | Bayar per penggunaan | Tidak ada | Inferensi ultra-cepat | +| | xAI (Grok) | Bayar per penggunaan | Tidak ada | Alasan Grok 4 | +| | Mistral | Bayar per penggunaan | Tidak ada | Model yang dihosting di UE | +| | Kebingungan | Bayar per penggunaan | Tidak ada | Ditambah pencarian | +| | Bersama AI | Bayar per penggunaan | Tidak ada | Model sumber terbuka | +| | AI kembang api | Bayar per penggunaan | Tidak ada | Gambar FLUX Cepat | +| | Otak | Bayar per penggunaan | Tidak ada | Kecepatan skala wafer | +| | menyatu | Bayar per penggunaan | Tidak ada | Perintah R+ RAG | +| | NVIDIA NIM | Bayar per penggunaan | Tidak ada | Model perusahaan | +| **💰 MURAH** | GLM-4.7 | $0,6/1 juta | Setiap hari pukul 10 pagi | Cadangan anggaran | +| | MiniMax M2.1 | $0,2/1 juta | 5 jam bergulir | Pilihan termurah | +| | Kimi K2 | $9/bln tetap | 10 juta token/bln | Biaya yang dapat diprediksi | +| **🆓 GRATIS** | iFlow | $0 | Tidak terbatas | 8 model gratis | +| | Qwen | $0 | Tidak terbatas | 3 model gratis | +| | Kiro | $0 | Tidak terbatas | Claude gratis | + +**💡 Kiat Pro:** Mulai dengan Gemini CLI (gratis 180 ribu/bulan) + kombo iFlow (gratis tanpa batas) = ​​biaya $0! + +--- + +## 🎯 Kasus Penggunaan + +### Kasus 1: "Saya berlangganan Claude Pro" + +**Masalah:** Kuota habis tanpa terpakai, batas kecepatan selama coding berat + +``` +Combo: "maximize-claude" + 1. cc/claude-opus-4-6 (use subscription fully) + 2. glm/glm-4.7 (cheap backup when quota out) + 3. if/kimi-k2-thinking (free emergency fallback) + +Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total +vs. $20 + hitting limits = frustration +``` + +### Kasus 2: "Saya ingin tanpa biaya" + +**Masalah:** Tidak mampu berlangganan, memerlukan pengkodean AI yang andal + +``` +Combo: "free-forever" + 1. gc/gemini-3-flash (180K free/month) + 2. if/kimi-k2-thinking (unlimited free) + 3. qw/qwen3-coder-plus (unlimited free) + +Monthly cost: $0 +Quality: Production-ready models +``` + +### Kasus 3: "Saya memerlukan pengkodean 24/7, tanpa gangguan" + +**Masalah:** Tenggat waktu, tidak mampu membayar downtime + +``` +Combo: "always-on" + 1. cc/claude-opus-4-6 (best quality) + 2. cx/gpt-5.2-codex (second subscription) + 3. glm/glm-4.7 (cheap, resets daily) + 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) + 5. if/kimi-k2-thinking (free unlimited) + +Result: 5 layers of fallback = zero downtime +Monthly cost: $20-200 (subscriptions) + $10-20 (backup) +``` + +### Kasus 4: "Saya ingin AI GRATIS di OpenClaw" + +**Masalah:** Membutuhkan asisten AI dalam aplikasi perpesanan, sepenuhnya gratis + +``` +Combo: "openclaw-free" + 1. if/glm-4.7 (unlimited free) + 2. if/minimax-m2.1 (unlimited free) + 3. if/kimi-k2-thinking (unlimited free) + +Monthly cost: $0 +Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... +``` + +--- + +## 📖 Pengaturan Penyedia + +### 🔐 Penyedia Langganan + +#### Kode Claude (Pro/Maks) + +```bash +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking + +Models: + cc/claude-opus-4-6 + cc/claude-sonnet-4-5-20250929 + cc/claude-haiku-4-5-20251001 +``` + +**Kiat Pro:** Gunakan Opus untuk tugas kompleks, Soneta untuk kecepatan. OmniRoute melacak kuota per model! + +#### Kodeks OpenAI (Plus/Pro) + +```bash +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset + +Models: + cx/gpt-5.2-codex + cx/gpt-5.1-codex-max +``` + +#### Gemini CLI (GRATIS 180K/bulan!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Nilai Terbaik:** Tingkat gratis yang sangat besar! Gunakan ini sebelum tingkatan berbayar. + +#### Kopilot GitHub + +```bash +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) + +Models: + gh/gpt-5 + gh/claude-4.5-sonnet + gh/gemini-3-pro +``` + +### 💰 Penyedia Murah + +#### GLM-4.7 (Reset harian, $0,6/1 juta) + +1. Daftar: [Zhipu AI](https://open.bigmodel.cn/) +2. Dapatkan kunci API dari Coding Plan +3. Dasbor → Tambahkan Kunci API: Penyedia: `glm`, Kunci API: `your-key` + +**Gunakan:** `glm/glm-4.7` — **Tips Pro:** Paket Coding menawarkan 3× kuota dengan biaya 1/7! Reset setiap hari pukul 10.00. + +#### MiniMax M2.1 (reset 5 jam, $0,20/1 juta) + +1. Daftar: [MiniMax](https://www.minimax.io/) +2. Dapatkan kunci API → Dasbor → Tambahkan Kunci API + +**Gunakan:** `minimax/MiniMax-M2.1` — **Tips Pro:** Opsi termurah untuk konteks panjang (1 juta token)! + +#### Kimi K2 ($9/bulan tetap) + +1. Berlangganan: [Moonshot AI](https://platform.moonshot.ai/) +2. Dapatkan kunci API → Dasbor → Tambahkan Kunci API + +**Penggunaan:** `kimi/kimi-latest` — **Tips Pro:** Memperbaiki $9/bulan untuk 10 juta token = biaya efektif $0,90/1 juta! + +### 🆓 Penyedia GRATIS + +#### iFlow (8 model GRATIS) + +```bash +Dashboard → Connect iFlow → OAuth login → Unlimited usage + +Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 +``` + +#### Qwen (3 model GRATIS) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude GRATIS) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨 Kombo + +### Contoh 1: Maksimalkan Langganan → Cadangan Murah + +``` +Dashboard → Combos → Create New + +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) + +Use in CLI: premium-coding +``` + +### Contoh 2: Gratis Saja (Tanpa Biaya) + +``` +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) + +Cost: $0 forever! +``` + +--- + +## 🔧 Integrasi CLI + +### IDE Kursor + +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` + +### Kode Claude + +Sunting `~/.claude/config.json`: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### Kodeks CLI + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +### Buka Cakar + +Sunting `~/.openclaw/openclaw.json`: + +```json +{ + "agents": { + "defaults": { + "model": { "primary": "omniroute/if/glm-4.7" } + } + }, + "models": { + "providers": { + "omniroute": { + "baseUrl": "http://localhost:20128/v1", + "apiKey": "your-omniroute-api-key", + "api": "openai-completions", + "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }] + } + } + } +} +``` + +**Atau gunakan Dasbor:** Alat CLI → OpenClaw → Konfigurasi otomatis + +### Cline / Lanjutkan / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Penerapan + +### Penerapan VPS + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### buruh pelabuhan + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +Untuk mode terintegrasi host dengan biner CLI, lihat bagian Docker di dokumen utama. + +### Variabel Lingkungan + +| Variabel | Bawaan | Deskripsi | +| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | Rahasia penandatanganan JWT (**perubahan produksi**) | +| `INITIAL_PASSWORD` | `123456` | Kata sandi masuk pertama | +| `DATA_DIR` | `~/.omniroute` | Direktori data (db, penggunaan, log) | +| `PORT` | kerangka default | Port layanan (`20128` dalam contoh) | +| `HOSTNAME` | kerangka default | Ikat host (Docker defaultnya adalah `0.0.0.0`) | +| `NODE_ENV` | default waktu proses | Tetapkan `production` untuk diterapkan | +| `BASE_URL` | `http://localhost:20128` | URL dasar internal sisi server | +| `CLOUD_URL` | `https://omniroute.dev` | URL dasar titik akhir sinkronisasi cloud | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Rahasia HMAC untuk kunci API yang dihasilkan | +| `REQUIRE_API_KEY` | `false` | Terapkan kunci API Pembawa di `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Mengaktifkan log permintaan/respons | +| `AUTH_COOKIE_SECURE` | `false` | Paksa cookie autentikasi `Secure` (di belakang proksi terbalik HTTPS) | + +Untuk referensi variabel lingkungan selengkapnya, lihat [README](../README.md). + +--- + +## 📊 Model yang Tersedia + +
+Lihat semua model yang tersedia + +**Kode Claude (`cc/`)** — Pro/Maks: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Kodeks (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` + +**Gemini CLI (`gc/`)** — GRATIS: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` + +**Copilot GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**GLM (`glm/`)** — $0,6/1 juta: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — $0,2/1 juta: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** — GRATIS: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` + +**Qwen (`qw/`)** — GRATIS: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` + +**Kiro (`kr/`)** — GRATIS: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` + +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` + +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` + +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` + +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` + +**Kebingungan (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Bersama AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**AI Kembang Api (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Otak Otak (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Di sini (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Fitur Lanjutan + +### Model Khusus + +Tambahkan ID model apa pun ke penyedia mana pun tanpa menunggu pembaruan aplikasi: + +```bash +# Via API +curl -X POST http://localhost:20128/api/provider-models \ + -H "Content-Type: application/json" \ + -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}' + +# List: curl http://localhost:20128/api/provider-models?provider=openai +# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" +``` + +Atau gunakan Dasbor: **Penyedia → [Penyedia] → Model Khusus**. + +### Rute Penyedia Khusus + +Rutekan permintaan langsung ke penyedia tertentu dengan validasi model: + +```bash +POST http://localhost:20128/v1/providers/openai/chat/completions +POST http://localhost:20128/v1/providers/openai/embeddings +POST http://localhost:20128/v1/providers/fireworks/images/generations +``` + +Awalan penyedia ditambahkan secara otomatis jika tidak ada. Model yang tidak cocok menampilkan `400`. + +### Konfigurasi Proksi Jaringan + +```bash +# Set global proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' + +# Per-provider proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' + +# Test proxy +curl -X POST http://localhost:20128/api/settings/proxy/test \ + -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' +``` + +**Prioritas:** Khusus kunci → Khusus kombo → Khusus penyedia → Global → Lingkungan. + +### API Katalog Model + +```bash +curl http://localhost:20128/api/models/catalog +``` + +Mengembalikan model yang dikelompokkan berdasarkan penyedia dengan tipe (`chat`, `embedding`, `image`). + +### Sinkronisasi Awan + +- Sinkronisasi penyedia, kombo, dan pengaturan di seluruh perangkat +- Sinkronisasi latar belakang otomatis dengan batas waktu + cepat gagal +- Lebih memilih `BASE_URL`/`CLOUD_URL` sisi server dalam produksi + +### LLM Gateway Intelligence (Fase 9) + +- **Cache Semantik** — Cache otomatis non-streaming, suhu=0 tanggapan (bypass dengan `X-OmniRoute-No-Cache: true`) +- **Idempotency Permintaan** — Menghapus duplikat permintaan dalam waktu 5 detik melalui header `Idempotency-Key` atau `X-Request-Id` +- **Pelacakan Kemajuan** — Ikut serta dalam acara SSE `event: progress` melalui header `X-OmniRoute-Progress: true` + +--- + +### Taman Bermain Penerjemah + +Akses melalui **Dasbor → Penerjemah**. Debug dan visualisasikan bagaimana OmniRoute menerjemahkan permintaan API antar penyedia. + +| Modus | Tujuan | +| -------------------- | ------------------------------------------------------------------------------------------------ | +| **Taman bermain** | Pilih format sumber/target, tempelkan permintaan, dan lihat keluaran terjemahan secara instan | +| **Penguji Obrolan** | Kirim pesan obrolan langsung melalui proxy dan periksa siklus permintaan/respons lengkap | +| **Bangku Tes** | Jalankan pengujian batch pada berbagai kombinasi format untuk memverifikasi kebenaran terjemahan | +| **Monitor Langsung** | Tonton terjemahan real-time saat permintaan mengalir melalui proxy | + +**Kasus penggunaan:** + +- Debug mengapa kombinasi klien/penyedia tertentu gagal +- Verifikasi bahwa tag pemikiran, panggilan alat, dan perintah sistem diterjemahkan dengan benar +- Bandingkan perbedaan format antara format OpenAI, Claude, Gemini, dan Responses API + +--- + +### Strategi Perutean + +Konfigurasikan melalui **Dasbor → Pengaturan → Perutean**. + +| Strategi | Deskripsi | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| **Isi Dulu** | Menggunakan akun dalam urutan prioritas — akun utama menangani semua permintaan hingga tidak tersedia | +| **Robin Bulat** | Menggilir semua akun dengan batas melekat yang dapat dikonfigurasi (default: 3 panggilan per akun) | +| **P2C (Kekuatan Dua Pilihan)** | Pilih 2 akun acak dan rute ke akun yang lebih sehat — menyeimbangkan beban dengan kesadaran akan kesehatan | +| **Acak** | Memilih akun secara acak untuk setiap permintaan menggunakan Fisher-Yates shuffle | +| **Jarang Digunakan** | Merutekan ke akun dengan stempel waktu `lastUsedAt` terlama, mendistribusikan lalu lintas secara merata | +| **Pengoptimalan Biaya** | Merutekan ke akun dengan nilai prioritas terendah, mengoptimalkan penyedia berbiaya terendah | + +#### Alias Model Wildcard + +Buat pola wildcard untuk memetakan ulang nama model: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +Wildcard mendukung `*` (karakter apa saja) dan `?` (karakter tunggal). + +#### Rantai Pengganti + +Tentukan rantai fallback global yang berlaku di semua permintaan: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Ketahanan & Pemutus Sirkuit + +Konfigurasikan melalui **Dasbor → Pengaturan → Ketahanan**. + +OmniRoute mengimplementasikan ketahanan tingkat penyedia dengan empat komponen: + +1. **Profil Penyedia** — Konfigurasi per penyedia untuk: + - Ambang batas kegagalan (berapa banyak kegagalan sebelum dibuka) + - Durasi pendinginan + - Sensitivitas deteksi batas kecepatan + - Parameter backoff eksponensial + +2. **Batas Tarif yang Dapat Diedit** — Default tingkat sistem dapat dikonfigurasi di dasbor: + - **Permintaan Per Menit (RPM)** — Permintaan maksimum per menit per akun + - **Waktu Minimum Antar Permintaan** — Kesenjangan minimum dalam milidetik antar permintaan + - **Permintaan Bersamaan Maksimum** — Permintaan simultan maksimum per akun + - Klik **Edit** untuk mengubah, lalu **Simpan** atau **Batal**. Nilai-nilai bertahan melalui API ketahanan. + +3. **Pemutus Sirkuit** — Melacak kegagalan per penyedia dan secara otomatis membuka sirkuit ketika ambang batas tercapai: + - **TUTUP** (Sehat) — Permintaan mengalir normal + - **BUKA** — Penyedia diblokir sementara setelah kegagalan berulang kali + - **HALF_OPEN** — Menguji apakah penyedia telah pulih + +4. **Kebijakan & Pengidentifikasi Terkunci** — Menampilkan status pemutus sirkuit dan pengidentifikasi terkunci dengan kemampuan buka paksa. + +5. **Deteksi Otomatis Batas Tarif** — Memantau header `429` dan `Retry-After` untuk secara proaktif menghindari batas tarif penyedia. + +**Kiat Pro:** Gunakan tombol **Reset Semua** untuk menghapus semua pemutus sirkuit dan cooldown saat penyedia pulih dari pemadaman listrik. + +--- + +### Ekspor/Impor Basis Data + +Kelola cadangan basis data di **Dasbor → Pengaturan → Sistem & Penyimpanan**. + +| Aksi | Deskripsi | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| **Ekspor Basis Data** | Mengunduh database SQLite saat ini sebagai file `.sqlite` | +| **Ekspor Semua (.tar.gz)** | Mengunduh arsip cadangan lengkap termasuk: basis data, pengaturan, kombo, koneksi penyedia (tanpa kredensial), metadata kunci API | +| **Impor Basis Data** | Unggah file `.sqlite` untuk menggantikan database saat ini. Cadangan pra-impor dibuat secara otomatis | + +```bash +# API: Export database +curl -o backup.sqlite http://localhost:20128/api/db-backups/export + +# API: Export all (full archive) +curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll + +# API: Import database +curl -X POST http://localhost:20128/api/db-backups/import \ + -F "file=@backup.sqlite" +``` + +**Validasi Impor:** File yang diimpor divalidasi integritasnya (pemeriksaan pragma SQLite), tabel yang diperlukan (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), dan ukuran (maks 100MB). + +**Kasus Penggunaan:** + +- Migrasi OmniRoute antar mesin +- Buat cadangan eksternal untuk pemulihan bencana +- Bagikan konfigurasi antar anggota tim (ekspor semua → bagikan arsip) + +--- + +### Pengaturan Dasbor + +Halaman pengaturan disusun menjadi 5 tab untuk memudahkan navigasi: + +| Tab | Isi | +| ------------- | ------------------------------------------------------------------------------------------------------------- | +| **Keamanan** | Pengaturan Login/Kata Sandi, Kontrol Akses IP, Autentikasi API untuk `/models`, dan Pemblokiran Penyedia | +| **Perutean** | Strategi perutean global (6 opsi), alias model wildcard, rantai fallback, default kombo | +| **Ketahanan** | Profil penyedia, batas tarif yang dapat diedit, status pemutus sirkuit, kebijakan & pengidentifikasi terkunci | +| **AI** | Memikirkan konfigurasi anggaran, injeksi cepat sistem global, statistik cache cepat | +| **Lanjutan** | Konfigurasi proksi global (HTTP/SOCKS5) | + +--- + +### Biaya & Manajemen Anggaran + +Akses melalui **Dasbor → Biaya**. + +| Tab | Tujuan | +| ------------ | ---------------------------------------------------------------------------------------------------------- | +| **Anggaran** | Tetapkan batas pengeluaran per kunci API dengan anggaran harian/mingguan/bulanan dan pelacakan waktu nyata | +| **Harga** | Lihat dan edit entri harga model — biaya per 1K token input/output per penyedia | + +```bash +# API: Set a budget +curl -X POST http://localhost:20128/api/usage/budget \ + -H "Content-Type: application/json" \ + -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' + +# API: Get current budget status +curl http://localhost:20128/api/usage/budget +``` + +**Pelacakan Biaya:** Setiap permintaan mencatat penggunaan token dan menghitung biaya menggunakan tabel harga. Lihat pengelompokan di **Dasbor → Penggunaan** menurut penyedia, model, dan kunci API. + +--- + +### Transkripsi Audio + +OmniRoute mendukung transkripsi audio melalui titik akhir yang kompatibel dengan OpenAI: + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data + +# Example with curl +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@audio.mp3" \ + -F "model=deepgram/nova-3" +``` + +Penyedia yang tersedia: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Format audio yang didukung: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +### Strategi Penyeimbangan Kombo + +Konfigurasikan penyeimbangan per kombo di **Dasbor → Kombo → Buat/Edit → Strategi**. + +| Strategi | Deskripsi | +| ---------------------- | -------------------------------------------------------------------------------------- | +| **Robin Bulat** | Berputar melalui model secara berurutan | +| **Prioritas** | Selalu mencoba model pertama; jatuh kembali hanya karena kesalahan | +| **Acak** | Memilih model acak dari kombo untuk setiap permintaan | +| **Berbobot** | Rute secara proporsional berdasarkan bobot yang ditetapkan per model | +| **Jarang Digunakan** | Merutekan ke model dengan permintaan terkini paling sedikit (menggunakan metrik kombo) | +| **Dioptimalkan Biaya** | Rute ke model termurah yang tersedia (menggunakan tabel harga) | + +Default kombo global dapat diatur di **Dasbor → Pengaturan → Perutean → Default Kombo**. + +--- + +### Dasbor Kesehatan + +Akses melalui **Dasbor → Kesehatan**. Ikhtisar kesehatan sistem real-time dengan 6 kartu: + +| Kartu | Apa yang Ditunjukkannya | +| ---------------------- | ----------------------------------------------------------------------- | +| **Status Sistem** | Uptime, versi, penggunaan memori, direktori data | +| **Kesehatan Penyedia** | Status pemutus sirkuit per penyedia (Tertutup/Terbuka/Setengah Terbuka) | +| **Batas Tarif** | Cooldown batas tarif aktif per akun dengan sisa waktu | +| **Penguncian Aktif** | Penyedia diblokir sementara oleh kebijakan lockout | +| **Cache Tanda Tangan** | Statistik cache deduplikasi (kunci aktif, tingkat hit) | +| **Telemetri Latensi** | agregasi latensi p50/p95/p99 per penyedia | + +**Tips Pro:** Halaman Kesehatan disegarkan secara otomatis setiap 10 detik. Gunakan kartu pemutus sirkuit untuk mengidentifikasi penyedia mana yang mengalami masalah. diff --git a/docs/i18n/in/API_REFERENCE.md b/docs/i18n/in/API_REFERENCE.md new file mode 100644 index 00000000..e347f9f3 --- /dev/null +++ b/docs/i18n/in/API_REFERENCE.md @@ -0,0 +1,363 @@ +# एपीआई संदर्भ + +🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) + +सभी ओमनीरूट एपीआई एंडपॉइंट के लिए पूरा संदर्भ। + +--- + +## सामग्री तालिका + +- [Chat Completions](#chat-completions) +- [Embeddings](#embeddings) +- [Image Generation](#image-generation) +- [List Models](#list-models) +- [Compatibility Endpoints](#compatibility-endpoints) +- [Semantic Cache](#semantic-cache) +- [Dashboard & Management](#dashboard--management) +- [Request Processing](#request-processing) +- [Authentication](#authentication) + +--- + +## चैट समापन + +```bash +POST /v1/chat/completions +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "cc/claude-opus-4-6", + "messages": [ + {"role": "user", "content": "Write a function to..."} + ], + "stream": true +} +``` + +### कस्टम हेडर + +| हेडर | दिशा | विवरण | +| ------------------------ | ----------- | -------------------------------------------- | ----- | +| `X-OmniRoute-No-Cache` | निवेदन | कैश को बायपास करने के लिए `true` पर सेट करें | +| `X-OmniRoute-Progress` | निवेदन | प्रगति घटनाओं के लिए `true` पर सेट करें | +| `Idempotency-Key` | निवेदन | डेडअप कुंजी (5एस विंडो) | +| **OMNI_टोकन_22** | निवेदन | वैकल्पिक डिडअप कुंजी | +| `X-OmniRoute-Cache` | प्रतिक्रिया | `HIT` या `MISS` (गैर-स्ट्रीमिंग) | +| `X-OmniRoute-Idempotent` | प्रतिक्रिया | `true` यदि डुप्लीकेट काटा गया है | +| `X-OmniRoute-Progress` | प्रतिक्रिया | `enabled` यदि प्रगति ट्रैकिंग | पर है | + +--- + +## एम्बेडिंग + +**OMNI_टोकन_1** + +उपलब्ध प्रदाता: नेबियस, ओपनएआई, मिस्ट्रल, टुगेदर एआई, फायरवर्क्स, एनवीआईडीआईए। + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## छवि निर्माण + +```bash +POST /v1/images/generations +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "openai/dall-e-3", + "prompt": "A beautiful sunset over mountains", + "size": "1024x1024" +} +``` + +उपलब्ध प्रदाता: OpenAI (DALL-E), xAI (ग्रोक इमेज), टुगेदर AI (FLUX), फायरवर्क्स AI। + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## सूची मॉडल + +**OMNI_टोकन_5** + +--- + +## संगतता समापन बिंदु + +| विधि | पथ | प्रारूप | +| ------------ | --------------------------- | -------------------- | +| पोस्ट | `/v1/chat/completions` | ओपनएआई | +| पोस्ट | `/v1/messages` | मानवशास्त्रीय | +| पोस्ट | `/v1/responses` | ओपनएआई प्रतिक्रियाएँ | +| पोस्ट | `/v1/embeddings` | ओपनएआई | +| पोस्ट | `/v1/images/generations` | ओपनएआई | +| प्राप्त करें | `/v1/models` | ओपनएआई | +| पोस्ट | `/v1/messages/count_tokens` | मानवशास्त्रीय | +| प्राप्त करें | `/v1beta/models` | मिथुन | +| पोस्ट | `/v1beta/models/{...path}` | मिथुन जनरेटकंटेंट | +| पोस्ट | `/v1/api/chat` | ओलामा | + +### समर्पित प्रदाता मार्ग + +**OMNI_टोकन_6** + +गायब होने पर प्रदाता उपसर्ग स्वतः जुड़ जाता है। बेमेल मॉडल `400` लौटाते हैं। + +--- + +## सिमेंटिक कैश + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +प्रतिक्रिया उदाहरण: + +**OMNI_टोकन_8** + +--- + +## डैशबोर्ड एवं प्रबंधन + +### प्रमाणीकरण + +| समापन बिंदु | Method | विवरण | +| ----------------------------- | ------- | --------------------- | +| `/api/auth/login` | POST | Login | +| `/api/auth/logout` | POST | लॉगआउट | +| `/api/settings/require-login` | GET/PUT | Toggle login required | + +### Provider Management + +| समापन बिंदु | Method | विवरण | +| ---------------------------- | ----------------------------- | ---------------------------------- | +| `/api/providers` | GET/POST | प्रदाताओं की सूची बनाएं/बनाएँ | +| `/api/providers/[id]` | GET/PUT/DELETE | एक प्रदाता प्रबंधित करें | +| `/api/providers/[id]/test` | पोस्ट | परीक्षण प्रदाता कनेक्शन | +| `/api/providers/[id]/models` | GET | सूची प्रदाता मॉडल | +| `/api/providers/validate` | POST | प्रदाता कॉन्फ़िगरेशन सत्यापित करें | +| `/api/provider-nodes*` | Various | प्रदाता नोड प्रबंधन | +| `/api/provider-models` | प्राप्त करें/पोस्ट करें/हटाएं | कस्टम मॉडल | + +### OAuth Flows + +| समापन बिंदु | Method | विवरण | +| -------------------------------- | ------ | --------------------- | +| `/api/oauth/[provider]/[action]` | विविध | प्रदाता-विशिष्ट OAuth | + +### रूटिंग और कॉन्फ़िगरेशन + +| Endpoint | Method | विवरण | +| --------------------- | ------------ | -------------------------------- | +| `/api/models/alias` | GET/POST | मॉडल उपनाम | +| `/api/models/catalog` | प्राप्त करें | प्रदाता द्वारा सभी मॉडल + प्रकार | +| `/api/combos*` | विविध | कॉम्बो प्रबंधन | +| `/api/keys*` | Various | एपीआई कुंजी प्रबंधन | +| `/api/pricing` | प्राप्त करें | मॉडल मूल्य निर्धारण | + +### उपयोग एवं विश्लेषण + +| समापन बिंदु | विधि | Description | +| --------------------------- | ------------ | -------------------- | +| `/api/usage/history` | प्राप्त करें | उपयोग इतिहास | +| `/api/usage/logs` | प्राप्त करें | Usage logs | +| `/api/usage/request-logs` | प्राप्त करें | Request-level logs | +| `/api/usage/[connectionId]` | प्राप्त करें | Per-connection usage | + +### Settings + +| समापन बिंदु | Method | Description | +| ------------------------------- | ------- | ---------------------- | +| `/api/settings` | GET/PUT | General settings | +| `/api/settings/proxy` | GET/PUT | Network proxy config | +| `/api/settings/proxy/test` | POST | Test proxy connection | +| `/api/settings/ip-filter` | GET/PUT | IP allowlist/blocklist | +| `/api/settings/thinking-budget` | GET/PUT | Reasoning token budget | +| `/api/settings/system-prompt` | GET/PUT | Global system prompt | + +### Monitoring + +| समापन बिंदु | विधि | विवरण | +| ------------------------ | ------------------ | -------------------- | +| `/api/sessions` | प्राप्त करें | सक्रिय सत्र ट्रैकिंग | +| `/api/rate-limits` | प्राप्त करें | प्रति खाता दर सीमा | +| `/api/monitoring/health` | प्राप्त करें | स्वास्थ्य जांच | +| `/api/cache` | प्राप्त करें/हटाएं | कैश आँकड़े / साफ़ | + +### बैकअप और निर्यात/आयात + +| समापन बिंदु | विधि | विवरण | +| --------------------------- | ------------ | -------------------------------------------------- | +| `/api/db-backups` | प्राप्त करें | उपलब्ध बैकअप की सूची | +| `/api/db-backups` | डालो | मैन्युअल बैकअप बनाएं | +| `/api/db-backups` | पोस्ट | किसी विशिष्ट बैकअप से पुनर्स्थापित करें | +| `/api/db-backups/export` | प्राप्त करें | डेटाबेस को .sqlite फ़ाइल के रूप में डाउनलोड करें | +| `/api/db-backups/import` | पोस्ट | डेटाबेस को बदलने के लिए .sqlite फ़ाइल अपलोड करें | +| `/api/db-backups/exportAll` | प्राप्त करें | .tar.gz संग्रह के रूप में पूर्ण बैकअप डाउनलोड करें | + +### क्लाउड सिंक + +| समापन बिंदु | विधि | विवरण | +| ---------------------- | ----- | ------------------ | +| `/api/sync/cloud` | विविध | क्लाउड सिंक ऑपरेशन | +| `/api/sync/initialize` | पोस्ट | सिंक प्रारंभ करें | +| `/api/cloud/*` | विविध | बादल प्रबंधन | + +### सीएलआई उपकरण + +| समापन बिंदु | विधि | विवरण | +| ---------------------------------- | ------------ | --------------------- | +| `/api/cli-tools/claude-settings` | प्राप्त करें | क्लाउड सीएलआई स्थिति | +| `/api/cli-tools/codex-settings` | प्राप्त करें | कोडेक्स सीएलआई स्थिति | +| `/api/cli-tools/droid-settings` | प्राप्त करें | Droid CLI स्थिति | +| `/api/cli-tools/openclaw-settings` | प्राप्त करें | ओपनक्लॉ सीएलआई स्थिति | +| **OMNI_टोकन_84** | प्राप्त करें | जेनेरिक सीएलआई रनटाइम | + +सीएलआई प्रतिक्रियाओं में शामिल हैं: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`। + +### लचीलापन और दर सीमाएँ + +| समापन बिंदु | विधि | विवरण | +| ----------------------- | ------------- | ------------------------------------- | +| `/api/resilience` | प्राप्त/डालें | लचीलापन प्रोफ़ाइल प्राप्त/अद्यतन करें | +| `/api/resilience/reset` | पोस्ट | सर्किट ब्रेकर रीसेट करें | +| `/api/rate-limits` | प्राप्त करें | प्रति खाता दर सीमा स्थिति | +| `/api/rate-limit` | प्राप्त करें | वैश्विक दर सीमा विन्यास | + +### मूल्यांकन + +| समापन बिंदु | विधि | विवरण | +| ------------ | ------------------ | ----------------------------- | +| `/api/evals` | प्राप्त/पोस्ट करें | सूची eval सुइट्स/रन मूल्यांकन | + +### नीतियां + +| समापन बिंदु | विधि | विवरण | +| --------------- | ----------------------------- | ---------------------------- | +| `/api/policies` | प्राप्त करें/पोस्ट करें/हटाएं | रूटिंग नीतियां प्रबंधित करें | + +### अनुपालन + +| समापन बिंदु | विधि | विवरण | +| --------------------------- | ------------ | --------------------------- | +| `/api/compliance/audit-log` | प्राप्त करें | अनुपालन ऑडिट लॉग (अंतिम एन) | + +### v1बीटा (मिथुन-संगत) + +| समापन बिंदु | विधि | विवरण | +| -------------------------- | ------------ | --------------------------------------- | +| `/v1beta/models` | प्राप्त करें | जेमिनी प्रारूप में मॉडलों की सूची बनाएं | +| `/v1beta/models/{...path}` | पोस्ट | मिथुन `generateContent` समापन बिंदु | + +ये समापन बिंदु उन ग्राहकों के लिए जेमिनी के एपीआई प्रारूप को प्रतिबिंबित करते हैं जो मूल जेमिनी एसडीके संगतता की अपेक्षा करते हैं। + +### आंतरिक/सिस्टम एपीआई + +| समापन बिंदु | विधि | विवरण | +| --------------- | ------------ | --------------------------------------------------- | +| `/api/init` | प्राप्त करें | एप्लिकेशन इनिशियलाइज़ेशन जांच (पहले रन पर प्रयुक्त) | +| `/api/tags` | प्राप्त करें | ओलामा-संगत मॉडल टैग (ओलामा ग्राहकों के लिए) | +| `/api/restart` | पोस्ट | ट्रिगर सुशोभित सर्वर पुनरारंभ | +| `/api/shutdown` | पोस्ट | ट्रिगर ग्रेसफुल सर्वर शटडाउन | + +> **ध्यान दें:** इन समापन बिंदुओं का उपयोग सिस्टम द्वारा आंतरिक रूप से या ओलामा क्लाइंट संगतता के लिए किया जाता है। उन्हें आम तौर पर अंतिम उपयोगकर्ताओं द्वारा नहीं बुलाया जाता है। + +--- + +## ऑडियो ट्रांसक्रिप्शन + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +डीपग्राम या असेंबलीएआई का उपयोग करके ऑडियो फ़ाइलों को ट्रांसक्राइब करें। + +**अनुरोध:** + +```bash +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@recording.mp3" \ + -F "model=deepgram/nova-3" +``` + +**प्रतिक्रिया:** + +**OMNI_टोकन_11** + +**समर्थित प्रदाता:** `deepgram/nova-3`, `assemblyai/best`। + +**समर्थित प्रारूप:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`। + +--- + +## ओलामा अनुकूलता + +ओलामा के एपीआई प्रारूप का उपयोग करने वाले ग्राहकों के लिए: + +**OMNI_टोकन_12** + +अनुरोध स्वचालित रूप से ओलामा और आंतरिक प्रारूपों के बीच अनुवादित होते हैं। + +--- + +## टेलीमेट्री + +**OMNI_टोकन_13** + +**प्रतिक्रिया:** + +**OMNI_टोकन_14** + +--- + +## बजट + +**OMNI_टोकन_15** + +--- + +## मॉडल उपलब्धता + +**OMNI_टोकन_16** + +--- + +## अनुरोध प्रसंस्करण + +1. ग्राहक `/v1/*` पर अनुरोध भेजता है +2. रूट हैंडलर `handleChat`, `handleEmbedding`, `handleAudioTranscription`, या `handleImageGeneration` को कॉल करता है। +3. मॉडल हल हो गया है (प्रत्यक्ष प्रदाता/मॉडल या उपनाम/कॉम्बो) +4. खाता उपलब्धता फ़िल्टरिंग के साथ स्थानीय डीबी से चयनित क्रेडेंशियल +5. चैट के लिए: `handleChatCore` - प्रारूप का पता लगाना, अनुवाद, कैश जांच, निष्क्रियता जांच +6. प्रदाता निष्पादक अपस्ट्रीम अनुरोध भेजता है +7. प्रतिक्रिया को क्लाइंट प्रारूप (चैट) में वापस अनुवादित किया गया या जैसा है वैसा ही लौटाया गया (एम्बेडिंग/छवियां/ऑडियो) +8. उपयोग/लॉगिंग रिकॉर्ड किया गया +9. कॉम्बो नियमों के अनुसार त्रुटियों पर फ़ॉलबैक लागू होता है + +पूर्ण वास्तुकला संदर्भ: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## प्रमाणीकरण + +- डैशबोर्ड रूट (`/dashboard/*`) `auth_token` कुकी का उपयोग करते हैं +- लॉगिन सहेजे गए पासवर्ड हैश का उपयोग करता है; `INITIAL_PASSWORD` पर फ़ॉलबैक +- `requireLogin` `/api/settings/require-login` के माध्यम से टॉगल करने योग्य +- `/v1/*` मार्गों को वैकल्पिक रूप से बियरर एपीआई कुंजी की आवश्यकता होती है जब `REQUIRE_API_KEY=true` diff --git a/docs/i18n/in/ARCHITECTURE.md b/docs/i18n/in/ARCHITECTURE.md new file mode 100644 index 00000000..7c64f949 --- /dev/null +++ b/docs/i18n/in/ARCHITECTURE.md @@ -0,0 +1,611 @@ +# ओमनीरूट आर्किटेक्चर + +🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) + +_अंतिम अद्यतन: 2026-02-18_ + +## कार्यकारी सारांश + +ओमनीरूट एक स्थानीय एआई रूटिंग गेटवे और नेक्स्ट.जेएस पर निर्मित डैशबोर्ड है। +यह एक एकल OpenAI-संगत एंडपॉइंट (`/v1/*`) प्रदान करता है और अनुवाद, फ़ॉलबैक, टोकन रिफ्रेश और उपयोग ट्रैकिंग के साथ कई अपस्ट्रीम प्रदाताओं के बीच ट्रैफ़िक को रूट करता है। + +मुख्य क्षमताएं: + +- सीएलआई/टूल्स के लिए ओपनएआई-संगत एपीआई सतह (28 प्रदाता) +- प्रदाता प्रारूपों में अनुरोध/प्रतिक्रिया अनुवाद +- मॉडल कॉम्बो फ़ॉलबैक (मल्टी-मॉडल अनुक्रम) +- खाता-स्तरीय फ़ॉलबैक (प्रति प्रदाता बहु-खाता) +- OAuth + एपीआई-कुंजी प्रदाता कनेक्शन प्रबंधन +- `/v1/embeddings` के माध्यम से एम्बेडिंग पीढ़ी (6 प्रदाता, 9 मॉडल) +- `/v1/images/generations` के माध्यम से छवि निर्माण (4 प्रदाता, 9 मॉडल) +- तर्क मॉडल के लिए टैग पार्सिंग (`...`) के बारे में सोचें +- सख्त ओपनएआई एसडीके संगतता के लिए प्रतिक्रिया स्वच्छता +- क्रॉस-प्रदाता अनुकूलता के लिए भूमिका सामान्यीकरण (डेवलपर→सिस्टम, सिस्टम→उपयोगकर्ता)। +- संरचित आउटपुट रूपांतरण (json_schema → जेमिनी रिस्पॉन्सस्कीमा) +- प्रदाताओं, चाबियाँ, उपनाम, कॉम्बो, सेटिंग्स, मूल्य निर्धारण के लिए स्थानीय दृढ़ता +- उपयोग/लागत ट्रैकिंग और अनुरोध लॉगिंग +- मल्टी-डिवाइस/स्टेट सिंक के लिए वैकल्पिक क्लाउड सिंक +- एपीआई एक्सेस नियंत्रण के लिए आईपी अनुमति सूची/ब्लॉकलिस्ट +- सोच बजट प्रबंधन (पासथ्रू/ऑटो/कस्टम/अनुकूली) +- वैश्विक प्रणाली शीघ्र इंजेक्शन +- सत्र ट्रैकिंग और फ़िंगरप्रिंटिंग +- प्रदाता-विशिष्ट प्रोफाइल के साथ प्रति-खाता बढ़ी हुई दर सीमित करना +- प्रदाता लचीलेपन के लिए सर्किट ब्रेकर पैटर्न +- म्यूटेक्स लॉकिंग के साथ एंटी-थंडरिंग झुंड सुरक्षा +- हस्ताक्षर-आधारित अनुरोध डिडुप्लीकेशन कैश +- डोमेन परत: मॉडल उपलब्धता, लागत नियम, फ़ॉलबैक नीति, लॉकआउट नीति +- डोमेन स्थिति दृढ़ता (फ़ॉलबैक, बजट, लॉकआउट, सर्किट ब्रेकर के लिए SQLite राइट-थ्रू कैश) +- केंद्रीकृत अनुरोध मूल्यांकन के लिए नीति इंजन (लॉकआउट → बजट → फ़ॉलबैक) +- p50/p95/p99 विलंबता एकत्रीकरण के साथ टेलीमेट्री का अनुरोध करें +- एंड-टू-एंड ट्रेसिंग के लिए सहसंबंध आईडी (एक्स-रिक्वेस्ट-आईडी)। +- एपीआई कुंजी के अनुसार ऑप्ट-आउट के साथ अनुपालन ऑडिट लॉगिंग +- एलएलएम गुणवत्ता आश्वासन के लिए इवल फ्रेमवर्क +- वास्तविक समय सर्किट ब्रेकर स्थिति के साथ लचीलापन यूआई डैशबोर्ड +- मॉड्यूलर OAuth प्रदाता (`src/lib/oauth/providers/` के अंतर्गत 12 व्यक्तिगत मॉड्यूल) + +प्राथमिक रनटाइम मॉडल: + +- `src/app/api/*` के अंतर्गत Next.js ऐप रूट डैशबोर्ड एपीआई और संगतता एपीआई दोनों को लागू करते हैं +- `src/sse/*` + `open-sse/*` में एक साझा SSE/रूटिंग कोर प्रदाता निष्पादन, अनुवाद, स्ट्रीमिंग, फ़ॉलबैक और उपयोग को संभालता है + +## दायरा और सीमाएँ + +### दायरे में + +- स्थानीय गेटवे रनटाइम +- डैशबोर्ड प्रबंधन एपीआई +- प्रदाता प्रमाणीकरण और टोकन ताज़ा करें +- अनुवाद और एसएसई स्ट्रीमिंग का अनुरोध करें +- स्थानीय स्थिति + उपयोग की दृढ़ता +- वैकल्पिक क्लाउड सिंक ऑर्केस्ट्रेशन + +### दायरे से बाहर + +- `NEXT_PUBLIC_CLOUD_URL` के पीछे क्लाउड सेवा कार्यान्वयन +- स्थानीय प्रक्रिया के बाहर प्रदाता एसएलए/नियंत्रण विमान +- बाहरी सीएलआई बायनेरिज़ स्वयं (क्लाउड सीएलआई, कोडेक्स सीएलआई, आदि) + +## उच्च स्तरीय सिस्टम संदर्भ + +```mermaid +flowchart LR + subgraph Clients[Developer Clients] + C1[Claude Code] + C2[Codex CLI] + C3[OpenClaw / Droid / Cline / Continue / Roo] + C4[Custom OpenAI-compatible clients] + BROWSER[Browser Dashboard] + end + + subgraph Router[OmniRoute Local Process] + API[V1 Compatibility API\n/v1/*] + DASH[Dashboard + Management API\n/api/*] + CORE[SSE + Translation Core\nopen-sse + src/sse] + DB[(db.json)] + UDB[(usage.json + log.txt)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity] + P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA] + P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible] + end + + subgraph Cloud[Optional Cloud Sync] + CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL] + end + + C1 --> API + C2 --> API + C3 --> API + C4 --> API + BROWSER --> DASH + + API --> CORE + DASH --> DB + CORE --> DB + CORE --> UDB + + CORE --> P1 + CORE --> P2 + CORE --> P3 + + DASH --> CLOUD +``` + +## कोर रनटाइम घटक + +## 1) एपीआई और रूटिंग लेयर (नेक्स्ट.जेएस ऐप रूट्स) + +मुख्य निर्देशिकाएँ: + +- अनुकूलता एपीआई के लिए `src/app/api/v1/*` और `src/app/api/v1beta/*` +- प्रबंधन/कॉन्फ़िगरेशन एपीआई के लिए `src/app/api/*` +- अगला `next.config.mjs` मानचित्र `/v1/*` से `/api/v1/*` में पुनः लिखता है + +महत्वपूर्ण अनुकूलता मार्ग: + +- **OMNI_टोकन_24** +- `src/app/api/v1/messages/route.ts` +- `src/app/api/v1/responses/route.ts` +- `src/app/api/v1/models/route.ts` - `custom: true` के साथ कस्टम मॉडल शामिल हैं +- `src/app/api/v1/embeddings/route.ts` - एम्बेडिंग जेनरेशन (6 प्रदाता) +- `src/app/api/v1/images/generations/route.ts` - छवि निर्माण (एंटीग्रेविटी/नेबियस सहित 4+ प्रदाता) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` - प्रति-प्रदाता समर्पित चैट +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` - प्रति-प्रदाता समर्पित एम्बेडिंग +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` - प्रति-प्रदाता समर्पित छवियां +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +प्रबंधन डोमेन: + +- प्रमाणीकरण/सेटिंग्स: `src/app/api/auth/*`, `src/app/api/settings/*` +- प्रदाता/कनेक्शन: `src/app/api/providers*` +- प्रदाता नोड: `src/app/api/provider-nodes*` +- कस्टम मॉडल: `src/app/api/provider-models` (प्राप्त करें/पोस्ट करें/हटाएं) +- मॉडल कैटलॉग: `src/app/api/models/catalog` (प्राप्त करें) +- प्रॉक्सी कॉन्फ़िगरेशन: `src/app/api/settings/proxy` (प्राप्त/पुट/डिलीट) + `src/app/api/settings/proxy/test` (पोस्ट) +- OAuth: `src/app/api/oauth/*` +- कुंजी/उपनाम/कॉम्बोस/मूल्य निर्धारण: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- उपयोग: `src/app/api/usage/*` +- सिंक/क्लाउड: `src/app/api/sync/*`, `src/app/api/cloud/*` +- सीएलआई टूलींग सहायक: `src/app/api/cli-tools/*` +- आईपी फ़िल्टर: `src/app/api/settings/ip-filter` (प्राप्त/पुट) +- सोच बजट: `src/app/api/settings/thinking-budget` (प्राप्त/पुट) +- सिस्टम प्रॉम्प्ट: `src/app/api/settings/system-prompt` (प्राप्त/पुट) +- सत्र: `src/app/api/sessions` (प्राप्त करें) +- दर सीमा: `src/app/api/rate-limits` (प्राप्त करें) +- लचीलापन: `src/app/api/resilience` (प्राप्त/पैच) - प्रदाता प्रोफ़ाइल, सर्किट ब्रेकर, दर सीमा स्थिति +- लचीलापन रीसेट: `src/app/api/resilience/reset` (पोस्ट) - ब्रेकर रीसेट करें + कूलडाउन +- कैश आँकड़े: `src/app/api/cache/stats` (प्राप्त करें/हटाएँ) +- मॉडल उपलब्धता: `src/app/api/models/availability` (प्राप्त करें/पोस्ट करें) +- टेलीमेट्री: `src/app/api/telemetry/summary` (प्राप्त करें) +- बजट: `src/app/api/usage/budget` (प्राप्त/पोस्ट करें) +- फ़ॉलबैक चेन: `src/app/api/fallback/chains` (प्राप्त करें/पोस्ट करें/हटाएँ) +- अनुपालन लेखापरीक्षा: `src/app/api/compliance/audit-log` (प्राप्त करें) +- मूल्यांकन: `src/app/api/evals` (प्राप्त/पोस्ट), `src/app/api/evals/[suiteId]` (प्राप्त करें) +- नीतियां: `src/app/api/policies` (प्राप्त/पोस्ट करें) + +## 2) एसएसई + अनुवाद कोर + +मुख्य प्रवाह मॉड्यूल: + +- प्रवेश: `src/sse/handlers/chat.ts` +- कोर ऑर्केस्ट्रेशन: `open-sse/handlers/chatCore.ts` +- प्रदाता निष्पादन एडाप्टर: `open-sse/executors/*` +- प्रारूप पहचान/प्रदाता कॉन्फिगरेशन: `open-sse/services/provider.ts` +- मॉडल पार्स/रिज़ॉल्यूशन: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- खाता फ़ॉलबैक तर्क: `open-sse/services/accountFallback.ts` +- अनुवाद रजिस्ट्री: `open-sse/translator/index.ts` +- स्ट्रीम परिवर्तन: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- उपयोग निष्कर्षण/सामान्यीकरण: `open-sse/utils/usageTracking.ts` +- टैग पार्सर सोचें: `open-sse/utils/thinkTagParser.ts` +- एंबेडिंग हैंडलर: `open-sse/handlers/embeddings.ts` +- एंबेडिंग प्रदाता रजिस्ट्री: `open-sse/config/embeddingRegistry.ts` +- छवि निर्माण हैंडलर: `open-sse/handlers/imageGeneration.ts` +- छवि प्रदाता रजिस्ट्री: `open-sse/config/imageRegistry.ts` +- प्रतिक्रिया स्वच्छता: `open-sse/handlers/responseSanitizer.ts` +- भूमिका सामान्यीकरण: `open-sse/services/roleNormalizer.ts` + +सेवाएँ (व्यावसायिक तर्क): + +- खाता चयन/स्कोरिंग: `open-sse/services/accountSelector.ts` +- संदर्भ जीवनचक्र प्रबंधन: `open-sse/services/contextManager.ts` +- आईपी फ़िल्टर प्रवर्तन: `open-sse/services/ipFilter.ts` +- सत्र ट्रैकिंग: `open-sse/services/sessionManager.ts` +- डुप्लिकेशन अनुरोध: `open-sse/services/signatureCache.ts` +- सिस्टम प्रॉम्प्ट इंजेक्शन: `open-sse/services/systemPrompt.ts` +- सोच बजट प्रबंधन: `open-sse/services/thinkingBudget.ts` +- वाइल्डकार्ड मॉडल रूटिंग: `open-sse/services/wildcardRouter.ts` +- दर सीमा प्रबंधन: `open-sse/services/rateLimitManager.ts` +- सर्किट ब्रेकर: `open-sse/services/circuitBreaker.ts` + +डोमेन परत मॉड्यूल: + +- मॉडल उपलब्धता: `src/lib/domain/modelAvailability.ts` +- लागत नियम/बजट: `src/lib/domain/costRules.ts` +- फ़ॉलबैक नीति: `src/lib/domain/fallbackPolicy.ts` +- कॉम्बो रिज़ॉल्वर: `src/lib/domain/comboResolver.ts` +- तालाबंदी नीति: `src/lib/domain/lockoutPolicy.ts` +- नीति इंजन: `src/domain/policyEngine.ts` - केंद्रीकृत तालाबंदी → बजट → फ़ॉलबैक मूल्यांकन +- त्रुटि कोड सूची: `src/lib/domain/errorCodes.ts` +- अनुरोध आईडी: `src/lib/domain/requestId.ts` +- फ़ेच टाइमआउट: `src/lib/domain/fetchTimeout.ts` +- अनुरोध टेलीमेट्री: `src/lib/domain/requestTelemetry.ts` +- अनुपालन/ऑडिट: `src/lib/domain/compliance/index.ts` +- इवल धावक: `src/lib/domain/evalRunner.ts` +- डोमेन स्थिति दृढ़ता: `src/lib/db/domainState.ts` - फ़ॉलबैक चेन, बजट, लागत इतिहास, लॉकआउट स्थिति, सर्किट ब्रेकर के लिए SQLite CRUD + +OAuth प्रदाता मॉड्यूल (`src/lib/oauth/providers/` के अंतर्गत 12 व्यक्तिगत फ़ाइलें): + +- रजिस्ट्री सूचकांक: `src/lib/oauth/providers/index.ts` +- व्यक्तिगत प्रदाता: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- पतला आवरण: `src/lib/oauth/providers.ts` - अलग-अलग मॉड्यूल से पुनः निर्यात + +## 3) दृढ़ता परत + +प्राथमिक स्थिति डीबी: + +- **OMNI_टोकन_126** +- फ़ाइल: `${DATA_DIR}/db.json` (या सेट होने पर `$XDG_CONFIG_HOME/omniroute/db.json`, अन्यथा `~/.omniroute/db.json`) +- संस्थाएँ: प्रदाता कनेक्शन, प्रदाता नोड्स, मॉडल उपनाम, कॉम्बो, एपीकीज़, सेटिंग्स, मूल्य निर्धारण, **कस्टम मॉडल**, **प्रॉक्सी कॉन्फिग**, **आईपीफिल्टर**, **थिंकिंगबजट**, **सिस्टमप्रॉम्प्ट** + +उपयोग डीबी: + +- `src/lib/usageDb.ts` +- फ़ाइलें: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- `localDb` के समान मूल निर्देशिका नीति का पालन करता है (`DATA_DIR`, फिर सेट होने पर `XDG_CONFIG_HOME/omniroute`) +- केंद्रित उप-मॉड्यूल में विघटित: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +डोमेन स्थिति DB (SQLite): + +- `src/lib/db/domainState.ts` - डोमेन स्थिति के लिए CRUD संचालन +- तालिकाएँ (`src/lib/db/core.ts` में निर्मित): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- राइट-थ्रू कैश पैटर्न: इन-मेमोरी मैप्स रनटाइम पर आधिकारिक होते हैं; उत्परिवर्तन SQLite के साथ समकालिक रूप से लिखे जाते हैं; कोल्ड स्टार्ट पर राज्य को डीबी से बहाल किया जाता है + +## 4) प्रामाणिक + सुरक्षा सतहें + +- डैशबोर्ड कुकी प्रमाणीकरण: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- एपीआई कुंजी निर्माण/सत्यापन: `src/shared/utils/apiKey.ts` +- प्रदाता रहस्य `providerConnections` प्रविष्टियों में बने रहे +- `open-sse/utils/proxyFetch.ts` (env vars) और `open-sse/utils/networkProxy.ts` (प्रति-प्रदाता या वैश्विक रूप से कॉन्फ़िगर करने योग्य) के माध्यम से आउटबाउंड प्रॉक्सी समर्थन + +## 5) क्लाउड सिंक + +- शेड्यूलर init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- आवधिक कार्य: `src/shared/services/cloudSyncScheduler.ts` +- नियंत्रण मार्ग: `src/app/api/sync/cloud/route.ts` + +## अनुरोध जीवनचक्र (`/v1/chat/completions`) + +**OMNI_टोकन_1** + +## कॉम्बो + अकाउंट फ़ॉलबैक फ़्लो + +```mermaid +flowchart TD + A[Incoming model string] --> B{Is combo name?} + B -- Yes --> C[Load combo models sequence] + B -- No --> D[Single model path] + + C --> E[Try model N] + E --> F[Resolve provider/model] + D --> F + + F --> G[Select account credentials] + G --> H{Credentials available?} + H -- No --> I[Return provider unavailable] + H -- Yes --> J[Execute request] + + J --> K{Success?} + K -- Yes --> L[Return response] + K -- No --> M{Fallback-eligible error?} + + M -- No --> N[Return error] + M -- Yes --> O[Mark account unavailable cooldown] + O --> P{Another account for provider?} + P -- Yes --> G + P -- No --> Q{In combo with next model?} + Q -- Yes --> E + Q -- No --> R[Return all unavailable] +``` + +फ़ॉलबैक निर्णय स्थिति कोड और त्रुटि-संदेश अनुमानों का उपयोग करके `open-sse/services/accountFallback.ts` द्वारा संचालित होते हैं। + +## OAuth ऑनबोर्डिंग और टोकन रिफ्रेश जीवनचक्र + +```mermaid +sequenceDiagram + autonumber + participant UI as Dashboard UI + participant OAuth as /api/oauth/[provider]/[action] + participant ProvAuth as Provider Auth Server + participant DB as localDb + participant Test as /api/providers/[id]/test + participant Exec as Provider Executor + + UI->>OAuth: GET authorize or device-code + OAuth->>ProvAuth: create auth/device flow + ProvAuth-->>OAuth: auth URL or device code payload + OAuth-->>UI: flow data + + UI->>OAuth: POST exchange or poll + OAuth->>ProvAuth: token exchange/poll + ProvAuth-->>OAuth: access/refresh tokens + OAuth->>DB: createProviderConnection(oauth data) + OAuth-->>UI: success + connection id + + UI->>Test: POST /api/providers/[id]/test + Test->>Exec: validate credentials / optional refresh + Exec-->>Test: valid or refreshed token info + Test->>DB: update status/tokens/errors + Test-->>UI: validation result +``` + +लाइव ट्रैफ़िक के दौरान रिफ्रेश को निष्पादक `refreshCredentials()` के माध्यम से `open-sse/handlers/chatCore.ts` के अंदर निष्पादित किया जाता है। + +## क्लाउड सिंक जीवनचक्र (सक्षम/सिंक/अक्षम) + +```mermaid +sequenceDiagram + autonumber + participant UI as Endpoint Page UI + participant Sync as /api/sync/cloud + participant DB as localDb + participant Cloud as External Cloud Sync + participant Claude as ~/.claude/settings.json + + UI->>Sync: POST action=enable + Sync->>DB: set cloudEnabled=true + Sync->>DB: ensure API key exists + Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys) + Cloud-->>Sync: sync result + Sync->>Cloud: GET /{machineId}/v1/verify + Sync-->>UI: enabled + verification status + + UI->>Sync: POST action=sync + Sync->>Cloud: POST /sync/{machineId} + Cloud-->>Sync: remote data + Sync->>DB: update newer local tokens/status + Sync-->>UI: synced + + UI->>Sync: POST action=disable + Sync->>DB: set cloudEnabled=false + Sync->>Cloud: DELETE /sync/{machineId} + Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed) + Sync-->>UI: disabled +``` + +क्लाउड सक्षम होने पर आवधिक सिंक `CloudSyncScheduler` द्वारा ट्रिगर किया जाता है। + +## डेटा मॉडल और स्टोरेज मैप + +**OMNI_टोकन_5** + +भौतिक भंडारण फ़ाइलें: + +- मुख्य स्थिति: `${DATA_DIR}/db.json` (या सेट होने पर `$XDG_CONFIG_HOME/omniroute/db.json`, अन्यथा `~/.omniroute/db.json`) +- उपयोग आँकड़े: `${DATA_DIR}/usage.json` +- अनुरोध लॉग लाइनें: `${DATA_DIR}/log.txt` +- वैकल्पिक अनुवादक/अनुरोध डिबग सत्र: `/logs/...` + +## परिनियोजन टोपोलॉजी + +**OMNI_टोकन_6** + +## मॉड्यूल मैपिंग (निर्णय-महत्वपूर्ण) + +### रूट और एपीआई मॉड्यूल + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: अनुकूलता एपीआई +- `src/app/api/v1/providers/[provider]/*`: प्रति-प्रदाता समर्पित मार्ग (चैट, एम्बेडिंग, चित्र) +- `src/app/api/providers*`: प्रदाता CRUD, सत्यापन, परीक्षण +- `src/app/api/provider-nodes*`: कस्टम संगत नोड प्रबंधन +- `src/app/api/provider-models`: कस्टम मॉडल प्रबंधन (CRUD) +- `src/app/api/models/catalog`: पूर्ण मॉडल कैटलॉग एपीआई (प्रदाता द्वारा समूहीकृत सभी प्रकार) +- `src/app/api/oauth/*`: OAuth/डिवाइस-कोड प्रवाह +- `src/app/api/keys*`: स्थानीय एपीआई कुंजी जीवनचक्र +- `src/app/api/models/alias`: उपनाम प्रबंधन +- `src/app/api/combos*`: फ़ॉलबैक कॉम्बो प्रबंधन +- `src/app/api/pricing`: लागत गणना के लिए मूल्य निर्धारण ओवरराइड होता है +- `src/app/api/settings/proxy`: प्रॉक्सी कॉन्फ़िगरेशन (प्राप्त/पुट/हटाएं) +- `src/app/api/settings/proxy/test`: आउटबाउंड प्रॉक्सी कनेक्टिविटी टेस्ट (POST) +- `src/app/api/usage/*`: एपीआई का उपयोग और लॉग +- `src/app/api/sync/*` + `src/app/api/cloud/*`: क्लाउड सिंक और क्लाउड-फेसिंग सहायक +- `src/app/api/cli-tools/*`: स्थानीय सीएलआई कॉन्फ़िगरेशन लेखक/चेकर्स +- `src/app/api/settings/ip-filter`: आईपी अनुमति सूची/ब्लॉकलिस्ट (प्राप्त/पुट) +- `src/app/api/settings/thinking-budget`: सोच टोकन बजट कॉन्फ़िगरेशन (प्राप्त/पुट) +- `src/app/api/settings/system-prompt`: ग्लोबल सिस्टम प्रॉम्प्ट (प्राप्त/पुट) +- `src/app/api/sessions`: सक्रिय सत्र सूची (प्राप्त करें) +- `src/app/api/rate-limits`: प्रति खाता दर सीमा स्थिति (GET) + +### रूटिंग और निष्पादन कोर + +- `src/sse/handlers/chat.ts`: अनुरोध पार्स, कॉम्बो हैंडलिंग, खाता चयन लूप +- `open-sse/handlers/chatCore.ts`: अनुवाद, निष्पादक प्रेषण, पुनः प्रयास/रीफ्रेश हैंडलिंग, स्ट्रीम सेटअप +- `open-sse/executors/*`: प्रदाता-विशिष्ट नेटवर्क और प्रारूप व्यवहार + +### अनुवाद रजिस्ट्री और प्रारूप परिवर्तक + +- `open-sse/translator/index.ts`: अनुवादक रजिस्ट्री और ऑर्केस्ट्रेशन +- अनुवादकों के लिए अनुरोध: `open-sse/translator/request/*` +- प्रतिक्रिया अनुवादक: `open-sse/translator/response/*` +- प्रारूप स्थिरांक: `open-sse/translator/formats.ts` + +### दृढ़ता + +- `src/lib/localDb.ts`: लगातार कॉन्फ़िगरेशन/स्थिति +- `src/lib/usageDb.ts`: उपयोग इतिहास और रोलिंग अनुरोध लॉग + +## प्रदाता निष्पादक कवरेज (रणनीति पैटर्न) + +प्रत्येक प्रदाता के पास `BaseExecutor` (`open-sse/executors/base.ts` में) का विस्तार करने वाला एक विशेष निष्पादक होता है, जो URL निर्माण, हेडर निर्माण, घातीय बैकऑफ़ के साथ पुनः प्रयास, क्रेडेंशियल रिफ्रेश हुक और `execute()` ऑर्केस्ट्रेशन विधि प्रदान करता है। + +| निष्पादक | प्रदाता(ओं) | विशेष हैंडलिंग | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `DefaultExecutor` | ओपनएआई, क्लाउड, जेमिनी, क्वेन, आईफ्लो, ओपनराउटर, जीएलएम, किमी, मिनीमैक्स, डीपसीक, ग्रोक, एक्सएआई, मिस्ट्रल, पर्प्लेक्सिटी, टुगेदर, फायरवर्क्स, सेरेब्रा, कोहेरे, एनवीआईडीआईए | प्रति प्रदाता डायनामिक यूआरएल/हेडर कॉन्फिगरेशन | +| `AntigravityExecutor` | गूगल एंटीग्रेविटी | कस्टम प्रोजेक्ट/सत्र आईडी, पुनः प्रयास करें-पार्सिंग के बाद | +| `CodexExecutor` | ओपनएआई कोडेक्स | सिस्टम निर्देश इंजेक्ट करता है, तर्क करने का प्रयास करता है | +| `CursorExecutor` | कर्सर आईडीई | कनेक्टआरपीसी प्रोटोकॉल, प्रोटोबफ एन्कोडिंग, चेकसम के माध्यम से हस्ताक्षर करने का अनुरोध | +| `GithubExecutor` | गिटहब कोपायलट | कोपायलट टोकन ताज़ा करें, VSCode-नकल हेडर | +| `KiroExecutor` | एडब्ल्यूएस कोडव्हिस्परर/किरो | एडब्ल्यूएस इवेंटस्ट्रीम बाइनरी प्रारूप → एसएसई रूपांतरण | +| `GeminiCLIExecutor` | जेमिनी सीएलआई | Google OAuth टोकन ताज़ा चक्र | + +अन्य सभी प्रदाता (कस्टम संगत नोड्स सहित) `DefaultExecutor` का उपयोग करते हैं। + +## प्रदाता संगतता मैट्रिक्स + +| प्रदाता | प्रारूप | प्रामाणिक | स्ट्रीम | नॉन-स्ट्रीम | टोकन ताज़ा करें | उपयोग एपीआई | +| --------------------- | -------------------- | ------------------------ | ----------------- | ----------- | --------------- | ------------------- | +| क्लाउड | क्लाउड | एपीआई कुंजी / OAuth | ✅ | ✅ | ✅ | ⚠️ केवल एडमिन | +| मिथुन | मिथुन | एपीआई कुंजी / OAuth | ✅ | ✅ | ✅ | ⚠️ क्लाउड कंसोल | +| जेमिनी सीएलआई | मिथुन-क्ली | OAuth | ✅ | ✅ | ✅ | ⚠️ क्लाउड कंसोल | +| प्रतिगुरुत्वाकर्षण | प्रतिगुरुत्वाकर्षण | OAuth | ✅ | ✅ | ✅ | ✅ पूर्ण कोटा एपीआई | +| ओपनएआई | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| कोडेक्स | openai-प्रतिक्रियाएं | OAuth | ✅ मजबूर | ❌ | ✅ | ✅ दर सीमा | +| गिटहब कोपायलट | ओपनाई | OAuth + सहपायलट टोकन | ✅ | ✅ | ✅ | ✅ कोटा स्नैपशॉट | +| कर्सर | कर्सर | कस्टम चेकसम | ✅ | ✅ | ❌ | ❌ | +| किरो | किरो | एडब्ल्यूएस एसएसओ ओआईडीसी | ✅ (इवेंटस्ट्रीम) | ❌ | ✅ | ✅ उपयोग सीमा | +| क्वेन | ओपनाई | OAuth | ✅ | ✅ | ✅ | ⚠️ प्रति अनुरोध | +| आईफ्लो | ओपनाई | OAuth (बेसिक) | ✅ | ✅ | ✅ | ⚠️ प्रति अनुरोध | +| ओपनराउटर | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| जीएलएम/किमी/मिनीमैक्स | क्लाउड | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| डीपसीक | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| ग्रोक | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| एक्सएआई (ग्रोक) | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| मिस्ट्रल | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| उलझन | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| एक साथ एआई | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| आतिशबाजी एआई | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| सेरेब्रस | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| सहभागी | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | +| एनवीडिया एनआईएम | ओपनाई | एपीआई कुंजी | ✅ | ✅ | ❌ | ❌ | + +## प्रारूप अनुवाद कवरेज + +पता लगाए गए स्रोत प्रारूपों में शामिल हैं: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +लक्ष्य प्रारूपों में शामिल हैं: + +- ओपनएआई चैट/प्रतिक्रियाएं + -क्लाउड +- मिथुन/मिथुन-सीएलआई/एंटीग्रेविटी लिफाफा +- किरो +- कर्सर + +अनुवाद **हब प्रारूप के रूप में ओपनएआई** का उपयोग करते हैं - सभी रूपांतरण मध्यवर्ती के रूप में ओपनएआई से गुजरते हैं: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +स्रोत पेलोड आकार और प्रदाता लक्ष्य प्रारूप के आधार पर अनुवादों का चयन गतिशील रूप से किया जाता है। + +अनुवाद पाइपलाइन में अतिरिक्त प्रसंस्करण परतें: + +- **प्रतिक्रिया स्वच्छता** - सख्त एसडीके अनुपालन सुनिश्चित करने के लिए ओपनएआई-प्रारूप प्रतिक्रियाओं (स्ट्रीमिंग और गैर-स्ट्रीमिंग दोनों) से गैर-मानक फ़ील्ड हटा देता है +- **भूमिका सामान्यीकरण** - गैर-ओपनएआई लक्ष्यों के लिए `developer` → `system` परिवर्तित करता है; सिस्टम भूमिका को अस्वीकार करने वाले मॉडलों के लिए `system` → `user` का विलय (GLM, ERNIE) +- **टैग निष्कर्षण के बारे में सोचें** - पार्स `...` सामग्री को `reasoning_content` फ़ील्ड में ब्लॉक करता है +- **संरचित आउटपुट** - OpenAI `response_format.json_schema` को मिथुन के `responseMimeType` + `responseSchema` में परिवर्तित करता है + +## समर्थित एपीआई समापन बिंदु + +| समापन बिंदु | प्रारूप | हैंडलर | +| -------------------------------------------------- | -------------------- | -------------------------------------------------- | ------------------------ | +| `POST /v1/chat/completions` | ओपनएआई चैट | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | क्लाउड संदेश | वही हैंडलर (स्वतः पता चला) | +| `POST /v1/responses` | ओपनएआई प्रतिक्रियाएँ | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | ओपनएआई एंबेडिंग्स | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | मॉडल सूची | एपीआई मार्ग | +| `POST /v1/images/generations` | OpenAI छवियाँ | **OMNI_टोकन_235** | +| `GET /v1/images/generations` | मॉडल सूची | एपीआई मार्ग | +| `POST /v1/providers/{provider}/chat/completions` | ओपनएआई चैट | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित | +| **OMNI_टोकन_238** | ओपनएआई एंबेडिंग्स | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित | +| `POST /v1/providers/{provider}/images/generations` | OpenAI छवियाँ | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित | +| `POST /v1/messages/count_tokens` | क्लाउड टोकन गिनती | एपीआई मार्ग | +| **OMNI_टोकन_241** | OpenAI मॉडल सूची | एपीआई मार्ग (चैट + एम्बेडिंग + छवि + कस्टम मॉडल) | +| `GET /api/models/catalog` | कैटलॉग | प्रदाता + प्रकार | द्वारा समूहीकृत सभी मॉडल | +| `POST /v1beta/models/*:streamGenerateContent` | मिथुन राशि के जातक | एपीआई मार्ग | +| **OMNI_टोकन_244** | प्रॉक्सी कॉन्फिग | नेटवर्क प्रॉक्सी कॉन्फ़िगरेशन | +| **OMNI_टोकन_245** | प्रॉक्सी कनेक्टिविटी | प्रॉक्सी स्वास्थ्य/कनेक्टिविटी परीक्षण समापन बिंदु | +| **OMNI_टोकन_246** | कस्टम मॉडल | प्रति प्रदाता कस्टम मॉडल प्रबंधन | + +## बायपास हैंडलर + +बाईपास हैंडलर (`open-sse/utils/bypassHandler.ts`) क्लाउड सीएलआई से ज्ञात "थ्रोअवे" अनुरोधों को रोकता है - वार्मअप पिंग, शीर्षक निष्कर्षण, और टोकन गिनती - और अपस्ट्रीम प्रदाता टोकन का उपभोग किए बिना **नकली प्रतिक्रिया** लौटाता है। यह तभी ट्रिगर होता है जब `User-Agent` में `claude-cli` होता है। + +## लॉगर पाइपलाइन का अनुरोध करें + +अनुरोध लकड़हारा (`open-sse/utils/requestLogger.ts`) एक 7-चरण डीबग लॉगिंग पाइपलाइन प्रदान करता है, जो डिफ़ॉल्ट रूप से अक्षम है, `ENABLE_REQUEST_LOGS=true` के माध्यम से सक्षम है: + +**OMNI_टोकन_8** + +प्रत्येक अनुरोध सत्र के लिए फ़ाइलें `/logs//` पर लिखी जाती हैं। + +## विफलता के तरीके और लचीलापन + +## 1) खाता/प्रदाता उपलब्धता + +- क्षणिक/दर/प्रामाणिक त्रुटियों पर प्रदाता खाता ठंडा हो गया +- अनुरोध विफल होने से पहले खाता फ़ॉलबैक +- वर्तमान मॉडल/प्रदाता पथ समाप्त होने पर कॉम्बो मॉडल फ़ॉलबैक + +## 2) टोकन समाप्ति + +- ताज़ा करने योग्य प्रदाताओं के लिए पुनः प्रयास के साथ पूर्व-जांच और ताज़ा करें +- कोर पथ में ताज़ा प्रयास के बाद 401/403 पुनः प्रयास करें + +## 3) स्ट्रीम सुरक्षा + +- डिस्कनेक्ट-अवेयर स्ट्रीम नियंत्रक +- एंड-ऑफ-स्ट्रीम फ्लश और `[DONE]` हैंडलिंग के साथ अनुवाद स्ट्रीम +- प्रदाता उपयोग मेटाडेटा अनुपलब्ध होने पर उपयोग अनुमान फ़ॉलबैक + +## 4) क्लाउड सिंक गिरावट + +- समन्वयन त्रुटियाँ सामने आती हैं लेकिन स्थानीय रनटाइम जारी रहता है +- शेड्यूलर में पुनः प्रयास-सक्षम तर्क है, लेकिन आवधिक निष्पादन वर्तमान में डिफ़ॉल्ट रूप से एकल-प्रयास सिंक को कॉल करता है + +## 5) डेटा इंटीग्रिटी + +- गुम चाबियों के लिए डीबी आकार माइग्रेशन/मरम्मत +- लोकलडीबी और यूज़डीबी के लिए भ्रष्ट JSON रीसेट सुरक्षा उपाय + +## अवलोकनशीलता और परिचालन संकेत + +रनटाइम दृश्यता स्रोत: + +- `src/sse/utils/logger.ts` से कंसोल लॉग +- `usage.json` में प्रति-अनुरोध उपयोग समुच्चय +- पाठ्य अनुरोध स्थिति लॉग इन `log.txt` +- `logs/` के अंतर्गत वैकल्पिक गहन अनुरोध/अनुवाद लॉग जब `ENABLE_REQUEST_LOGS=true` +- यूआई खपत के लिए डैशबोर्ड उपयोग समापन बिंदु (`/api/usage/*`)। + +## सुरक्षा-संवेदनशील सीमाएँ + +- JWT सीक्रेट (`JWT_SECRET`) डैशबोर्ड सत्र कुकी सत्यापन/हस्ताक्षर को सुरक्षित करता है +- प्रारंभिक पासवर्ड फ़ॉलबैक (`INITIAL_PASSWORD`, डिफ़ॉल्ट `123456`) को वास्तविक परिनियोजन में ओवरराइड किया जाना चाहिए +- एपीआई कुंजी एचएमएसी रहस्य (`API_KEY_SECRET`) उत्पन्न स्थानीय एपीआई कुंजी प्रारूप को सुरक्षित करता है +- प्रदाता रहस्य (एपीआई कुंजी/टोकन) स्थानीय डीबी में बने रहते हैं और उन्हें फ़ाइल सिस्टम स्तर पर संरक्षित किया जाना चाहिए +- क्लाउड सिंक एंडपॉइंट एपीआई कुंजी ऑथ + मशीन आईडी सेमेन्टिक्स पर निर्भर करते हैं + +## पर्यावरण और रनटाइम मैट्रिक्स + +कोड द्वारा सक्रिय रूप से उपयोग किए जाने वाले पर्यावरण चर: + +- ऐप/ऑथ: `JWT_SECRET`, `INITIAL_PASSWORD` +- भंडारण: `DATA_DIR` +- संगत नोड व्यवहार: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- वैकल्पिक स्टोरेज बेस ओवरराइड (लिनक्स/मैकओएस जब `DATA_DIR` सेट न हो): `XDG_CONFIG_HOME` +- सुरक्षा हैशिंग: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- लॉगिंग: `ENABLE_REQUEST_LOGS` +- सिंक/क्लाउड यूआरएल: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- आउटबाउंड प्रॉक्सी: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` और लोअरकेस वेरिएंट +- SOCKS5 फ़ीचर फ़्लैग: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- प्लेटफ़ॉर्म/रनटाइम सहायक (ऐप-विशिष्ट कॉन्फ़िगरेशन नहीं): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## ज्ञात वास्तुशिल्प नोट्स + +1. `usageDb` और `localDb` अब लीगेसी फ़ाइल माइग्रेशन के साथ समान आधार निर्देशिका नीति (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) साझा करते हैं। +2. `/api/v1/route.ts` एक स्थिर मॉडल सूची लौटाता है और यह `/v1/models` द्वारा उपयोग किया जाने वाला मुख्य मॉडल स्रोत नहीं है। +3. अनुरोध लकड़हारा सक्षम होने पर पूर्ण हेडर/बॉडी लिखता है; लॉग निर्देशिका को संवेदनशील मानें। +4. क्लाउड व्यवहार सही `NEXT_PUBLIC_BASE_URL` और क्लाउड एंडपॉइंट रीचैबिलिटी पर निर्भर करता है। +5. `open-sse/` निर्देशिका को `@omniroute/open-sse` **npm कार्यक्षेत्र पैकेज** के रूप में प्रकाशित किया गया है। स्रोत कोड इसे `@omniroute/open-sse/...` के माध्यम से आयात करता है (Next.js `transpilePackages` द्वारा हल किया गया)। इस दस्तावेज़ में फ़ाइल पथ अभी भी स्थिरता के लिए निर्देशिका नाम `open-sse/` का उपयोग करते हैं। +6. डैशबोर्ड में चार्ट सुलभ, इंटरैक्टिव एनालिटिक्स विज़ुअलाइज़ेशन (मॉडल उपयोग बार चार्ट, सफलता दर के साथ प्रदाता ब्रेकडाउन टेबल) के लिए **रिचार्ट्स** (एसवीजी-आधारित) का उपयोग करते हैं। +7. E2E परीक्षण **Playwright** (`tests/e2e/`) का उपयोग करते हैं, `npm run test:e2e` के माध्यम से चलते हैं। यूनिट परीक्षण **Node.js टेस्ट रनर** (`tests/unit/`) का उपयोग करते हैं, जो `npm run test:plan3` के माध्यम से चलते हैं। `src/` के अंतर्गत स्रोत कोड **टाइपस्क्रिप्ट** (`.ts`/`.tsx`) है; `open-sse/` कार्यस्थान जावास्क्रिप्ट (`.js`) बना हुआ है। +8. सेटिंग्स पृष्ठ को 5 टैब में व्यवस्थित किया गया है: सुरक्षा, रूटिंग (6 वैश्विक रणनीतियाँ: भरण-प्रथम, राउंड-रॉबिन, पी2सी, यादृच्छिक, कम से कम उपयोग किया गया, लागत-अनुकूलित), लचीलापन (संपादन योग्य दर सीमा, सर्किट ब्रेकर, नीतियां), एआई (सोच बजट, सिस्टम प्रॉम्प्ट, प्रॉम्प्ट कैश), उन्नत (प्रॉक्सी)। + +## परिचालन सत्यापन चेकलिस्ट + +- स्रोत से निर्मित: `npm run build` +- डॉकर छवि बनाएं: `docker build -t omniroute .` +- सेवा प्रारंभ करें और सत्यापित करें: +- `GET /api/settings` +- `GET /api/v1/models` +- जब `PORT=20128` हो तो CLI लक्ष्य आधार URL `http://:20128/v1` होना चाहिए diff --git a/docs/i18n/in/CODEBASE_DOCUMENTATION.md b/docs/i18n/in/CODEBASE_DOCUMENTATION.md new file mode 100644 index 00000000..4609a59a --- /dev/null +++ b/docs/i18n/in/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,466 @@ +# omniroute - कोडबेस दस्तावेज़ीकरण + +🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) + +> **ओम्नीरूटे** मल्टी-प्रोवाइडर एआई प्रॉक्सी राउटर के लिए एक व्यापक, शुरुआती-अनुकूल मार्गदर्शिका। + +--- + +## 1. सर्वव्यापी क्या है? + +ऑम्नीरूट एक **प्रॉक्सी राउटर** है जो एआई क्लाइंट (क्लाउड सीएलआई, कोडेक्स, कर्सर आईडीई, आदि) और एआई प्रदाताओं (एंथ्रोपिक, गूगल, ओपनएआई, एडब्ल्यूएस, गिटहब, आदि) के बीच बैठता है। यह एक बड़ी समस्या का समाधान करता है: + +> **अलग-अलग एआई क्लाइंट अलग-अलग "भाषाएं" (एपीआई प्रारूप) बोलते हैं, और अलग-अलग एआई प्रदाता भी अलग-अलग "भाषाओं" की अपेक्षा करते हैं।** ऑम्नीरूट स्वचालित रूप से उनके बीच अनुवाद करता है। + +इसे संयुक्त राष्ट्र में एक सार्वभौमिक अनुवादक की तरह समझें - कोई भी प्रतिनिधि कोई भी भाषा बोल सकता है, और अनुवादक इसे किसी अन्य प्रतिनिधि के लिए परिवर्तित कर देता है। + +--- + +## 2. वास्तुकला अवलोकन + +```mermaid +graph LR + subgraph Clients + A[Claude CLI] + B[Codex] + C[Cursor IDE] + D[OpenAI-compatible] + end + + subgraph omniroute + E[Handler Layer] + F[Translator Layer] + G[Executor Layer] + H[Services Layer] + end + + subgraph Providers + I[Anthropic Claude] + J[Google Gemini] + K[OpenAI / Codex] + L[GitHub Copilot] + M[AWS Kiro] + N[Antigravity] + O[Cursor API] + end + + A --> E + B --> E + C --> E + D --> E + E --> F + F --> G + G --> I + G --> J + G --> K + G --> L + G --> M + G --> N + G --> O + H -.-> E + H -.-> G +``` + +### मुख्य सिद्धांत: हब-एंड-स्पोक अनुवाद + +सभी प्रारूप अनुवाद **हब के रूप में ओपनएआई प्रारूप** से होकर गुजरता है: + +**OMNI_टोकन_1** + +इसका मतलब है कि आपको **N²** (प्रत्येक जोड़ी) के बजाय केवल **N अनुवादकों** (प्रति प्रारूप एक) की आवश्यकता है। + +--- + +## 3. परियोजना संरचना + +``` +omniroute/ +├── open-sse/ ← Core proxy library (portable, framework-agnostic) +│ ├── index.js ← Main entry point, exports everything +│ ├── config/ ← Configuration & constants +│ ├── executors/ ← Provider-specific request execution +│ ├── handlers/ ← Request handling orchestration +│ ├── services/ ← Business logic (auth, models, fallback, usage) +│ ├── translator/ ← Format translation engine +│ │ ├── request/ ← Request translators (8 files) +│ │ ├── response/ ← Response translators (7 files) +│ │ └── helpers/ ← Shared translation utilities (6 files) +│ └── utils/ ← Utility functions +├── src/ ← Application layer (Express/Worker runtime) +│ ├── app/ ← Web UI, API routes, middleware +│ ├── lib/ ← Database, auth, and shared library code +│ ├── mitm/ ← Man-in-the-middle proxy utilities +│ ├── models/ ← Database models +│ ├── shared/ ← Shared utilities (wrappers around open-sse) +│ ├── sse/ ← SSE endpoint handlers +│ └── store/ ← State management +├── data/ ← Runtime data (credentials, logs) +│ └── provider-credentials.json (external credentials override, gitignored) +└── tester/ ← Test utilities +``` + +--- + +## 4. मॉड्यूल-दर-मॉड्यूल ब्रेकडाउन + +### 4.1 कॉन्फ़िगरेशन (`open-sse/config/`) + +सभी प्रदाता कॉन्फ़िगरेशन के लिए **सत्य का एकल स्रोत**। + +| फ़ाइल | उद्देश्य | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` प्रत्येक प्रदाता के लिए आधार URL, OAuth क्रेडेंशियल (डिफ़ॉल्ट), हेडर और डिफ़ॉल्ट सिस्टम संकेतों के साथ ऑब्जेक्ट। `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG`, और `SKIP_PATTERNS` को भी परिभाषित करता है। | +| `credentialLoader.ts` | `data/provider-credentials.json` से बाहरी क्रेडेंशियल लोड करता है और उन्हें `PROVIDERS` में हार्डकोडेड डिफ़ॉल्ट पर मर्ज करता है। पश्चगामी संगतता बनाए रखते हुए रहस्यों को स्रोत नियंत्रण से बाहर रखता है। | +| `providerModels.ts` | केंद्रीय मॉडल रजिस्ट्री: मानचित्र प्रदाता उपनाम → मॉडल आईडी। `getModels()`, `getProviderByAlias()` जैसे कार्य। | +| `codexInstructions.ts` | सिस्टम निर्देश कोडेक्स अनुरोधों (संपादन बाधाएं, सैंडबॉक्स नियम, अनुमोदन नीतियां) में शामिल किए गए हैं। | +| `defaultThinkingSignature.ts` | क्लाउड और जेमिनी मॉडल के लिए डिफ़ॉल्ट "सोच" हस्ताक्षर। | +| `ollamaModels.ts` | स्थानीय ओलामा मॉडल के लिए स्कीमा परिभाषा (नाम, आकार, परिवार, परिमाणीकरण)। | + +#### क्रेडेंशियल लोडिंग फ़्लो + +```mermaid +flowchart TD + A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"] + B --> C{"data/provider-credentials.json\nexists?"} + C -->|Yes| D["credentialLoader reads JSON"] + C -->|No| E["Use hardcoded defaults"] + D --> F{"For each provider in JSON"} + F --> G{"Provider exists\nin PROVIDERS?"} + G -->|No| H["Log warning, skip"] + G -->|Yes| I{"Value is object?"} + I -->|No| J["Log warning, skip"] + I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"] + K --> F + H --> F + J --> F + F -->|Done| L["PROVIDERS ready with\nmerged credentials"] + E --> L +``` + +--- + +### 4.2 निष्पादक (`open-sse/executors/`) + +निष्पादक **रणनीति पैटर्न** का उपयोग करके **प्रदाता-विशिष्ट तर्क** को समाहित करते हैं। प्रत्येक निष्पादक आवश्यकतानुसार आधार विधियों को ओवरराइड करता है। + +```mermaid +classDiagram + class BaseExecutor { + +buildUrl(model, stream, options) + +buildHeaders(credentials, stream, body) + +transformRequest(body, model, stream, credentials) + +execute(url, options) + +shouldRetry(status, error) + +refreshCredentials(credentials, log) + } + + class DefaultExecutor { + +refreshCredentials() + } + + class AntigravityExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +shouldRetry() + +refreshCredentials() + } + + class CursorExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseResponse() + +generateChecksum() + } + + class KiroExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseEventStream() + +refreshCredentials() + } + + BaseExecutor <|-- DefaultExecutor + BaseExecutor <|-- AntigravityExecutor + BaseExecutor <|-- CursorExecutor + BaseExecutor <|-- KiroExecutor + BaseExecutor <|-- CodexExecutor + BaseExecutor <|-- GeminiCLIExecutor + BaseExecutor <|-- GithubExecutor +``` + +| निष्पादक | प्रदाता | प्रमुख विशेषज्ञताएं | +| ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | सार आधार: यूआरएल निर्माण, हेडर, पुनः प्रयास तर्क, क्रेडेंशियल ताज़ा | +| `default.ts` | क्लाउड, जेमिनी, ओपनएआई, जीएलएम, किमी, मिनीमैक्स | मानक प्रदाताओं के लिए जेनेरिक OAuth टोकन ताज़ा करें | +| `antigravity.ts` | गूगल क्लाउड कोड | प्रोजेक्ट/सत्र आईडी जनरेशन, मल्टी-यूआरएल फ़ॉलबैक, त्रुटि संदेशों से कस्टम पुनः प्रयास पार्सिंग ("2h7m23s के बाद रीसेट करें") | +| `cursor.ts` | कर्सर आईडीई | **सबसे जटिल**: SHA-256 चेकसम ऑथ, प्रोटोबफ अनुरोध एन्कोडिंग, बाइनरी इवेंटस्ट्रीम → SSE प्रतिक्रिया पार्सिंग | +| `codex.ts` | ओपनएआई कोडेक्स | सिस्टम निर्देशों को इंजेक्ट करता है, सोच के स्तर को प्रबंधित करता है, असमर्थित मापदंडों को हटाता है | +| `gemini-cli.ts` | गूगल जेमिनी सीएलआई | कस्टम यूआरएल बिल्डिंग (`streamGenerateContent`), Google OAuth टोकन रिफ्रेश | +| `github.ts` | गिटहब कोपायलट | दोहरी टोकन प्रणाली (GitHub OAuth + Copilot टोकन), VSCode हेडर की नकल | +| `kiro.ts` | एडब्ल्यूएस कोडव्हिस्परर | एडब्ल्यूएस इवेंटस्ट्रीम बाइनरी पार्सिंग, एएमजेडएन इवेंट फ्रेम, टोकन अनुमान | +| `index.ts` | — | फ़ैक्टरी: मानचित्र प्रदाता का नाम → निष्पादक वर्ग, डिफ़ॉल्ट फ़ॉलबैक के साथ | + +--- + +### 4.3 हैंडलर (`open-sse/handlers/`) + +**ऑर्केस्ट्रेशन परत** - अनुवाद, निष्पादन, स्ट्रीमिंग और त्रुटि प्रबंधन का समन्वय करती है। + +| फ़ाइल | उद्देश्य | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `chatCore.ts` | **केंद्रीय ऑर्केस्ट्रेटर** (~600 पंक्तियाँ)। संपूर्ण अनुरोध जीवनचक्र को संभालता है: प्रारूप का पता लगाना → अनुवाद → निष्पादक प्रेषण → स्ट्रीमिंग/गैर-स्ट्रीमिंग प्रतिक्रिया → टोकन ताज़ा करना → त्रुटि प्रबंधन → उपयोग लॉगिंग। | +| `responsesHandler.ts` | OpenAI के रिस्पॉन्स एपीआई के लिए एडाप्टर: रिस्पॉन्स फॉर्मेट को कनवर्ट करता है → चैट कंप्लीटेशन → `chatCore` को भेजता है → SSE को रिस्पॉन्स फॉर्मेट में वापस कनवर्ट करता है। | +| `embeddings.ts` | एंबेडिंग जेनरेशन हैंडलर: एंबेडिंग मॉडल → प्रदाता को हल करता है, प्रदाता एपीआई को भेजता है, ओपनएआई-संगत एंबेडिंग प्रतिक्रिया देता है। 6+ प्रदाताओं का समर्थन करता है। | +| `imageGeneration.ts` | छवि निर्माण हैंडलर: छवि मॉडल → प्रदाता को हल करता है, ओपनएआई-संगत, जेमिनी-छवि (एंटीग्रेविटी), और फ़ॉलबैक (नेबियस) मोड का समर्थन करता है। बेस64 या यूआरएल छवियाँ लौटाता है। | + +#### अनुरोध जीवनचक्र (chatCore.ts) + +**OMNI_टोकन_5** + +--- + +### 4.4 सेवाएँ (`open-sse/services/`) + +व्यावसायिक तर्क जो संचालकों और निष्पादकों का समर्थन करता है। + +| फ़ाइल | उद्देश्य | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **प्रारूप का पता लगाना** (`detectFormat`): क्लॉड/ओपनएआई/जेमिनी/एंटीग्रेविटी/प्रतिक्रिया प्रारूपों की पहचान करने के लिए अनुरोध बॉडी संरचना का विश्लेषण करता है (क्लाउड के लिए `max_tokens` अनुमान शामिल है)। इसके अलावा: यूआरएल बिल्डिंग, हेडर बिल्डिंग, थिंकिंग कॉन्फिग सामान्यीकरण। `openai-compatible-*` और `anthropic-compatible-*` गतिशील प्रदाताओं का समर्थन करता है। | +| `model.ts` | मॉडल स्ट्रिंग पार्सिंग (`claude/model-name` → `{provider: "claude", model: "model-name"}`), टकराव का पता लगाने के साथ उपनाम रिज़ॉल्यूशन, इनपुट सैनिटाइजेशन (पथ ट्रैवर्सल/नियंत्रण वर्ण को अस्वीकार करता है), और एसिंक उपनाम गेटर समर्थन के साथ मॉडल जानकारी रिज़ॉल्यूशन। | +| `accountFallback.ts` | दर-सीमा प्रबंधन: घातीय बैकऑफ़ (1s → 2s → 4s → अधिकतम 2 मिनट), खाता कूल्डाउन प्रबंधन, त्रुटि वर्गीकरण (कौन सी त्रुटियाँ फ़ॉलबैक को ट्रिगर करती हैं बनाम नहीं)। | +| `tokenRefresh.ts` | **प्रत्येक प्रदाता** के लिए OAuth टोकन ताज़ा करें: Google (मिथुन, एंटीग्रेविटी), क्लाउड, कोडेक्स, क्वेन, iFlow, GitHub (OAuth + Copilot डुअल-टोकन), किरो (AWS SSO OIDC + सोशल ऑथ)। इसमें इन-फ़्लाइट प्रॉमिस डिडुप्लीकेशन कैश और एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास शामिल है। | +| `combo.ts` | **कॉम्बो मॉडल**: फ़ॉलबैक मॉडल की श्रृंखलाएँ। यदि मॉडल ए फ़ॉलबैक-योग्य त्रुटि के साथ विफल हो जाता है, तो मॉडल बी, फिर सी, आदि का प्रयास करें। वास्तविक अपस्ट्रीम स्थिति कोड लौटाता है। | +| `usage.ts` | प्रदाता एपीआई (गिटहब कोपायलट कोटा, एंटीग्रेविटी मॉडल कोटा, कोडेक्स दर सीमा, किरो उपयोग ब्रेकडाउन, क्लाउड सेटिंग्स) से कोटा/उपयोग डेटा प्राप्त करता है। | +| `accountSelector.ts` | स्कोरिंग एल्गोरिदम के साथ स्मार्ट खाता चयन: प्रत्येक अनुरोध के लिए इष्टतम खाता चुनने के लिए प्राथमिकता, स्वास्थ्य स्थिति, राउंड-रॉबिन स्थिति और कूलडाउन स्थिति पर विचार करता है। | +| `contextManager.ts` | अनुरोध संदर्भ जीवनचक्र प्रबंधन: डिबगिंग और लॉगिंग के लिए मेटाडेटा (अनुरोध आईडी, टाइमस्टैम्प, प्रदाता जानकारी) के साथ प्रति-अनुरोध संदर्भ ऑब्जेक्ट बनाता है और ट्रैक करता है। | +| `ipFilter.ts` | आईपी-आधारित अभिगम नियंत्रण: अनुमति सूची और ब्लॉकलिस्ट मोड का समर्थन करता है। एपीआई अनुरोधों को संसाधित करने से पहले कॉन्फ़िगर किए गए नियमों के विरुद्ध क्लाइंट आईपी को सत्यापित करता है। | +| `sessionManager.ts` | क्लाइंट फ़िंगरप्रिंटिंग के साथ सत्र ट्रैकिंग: हैश किए गए क्लाइंट पहचानकर्ताओं का उपयोग करके सक्रिय सत्रों को ट्रैक करता है, अनुरोधों की संख्या पर नज़र रखता है, और सत्र मेट्रिक्स प्रदान करता है। | +| `signatureCache.ts` | अनुरोध हस्ताक्षर-आधारित डिडुप्लीकेशन कैश: हाल के अनुरोध हस्ताक्षरों को कैश करके और एक समय विंडो के भीतर समान अनुरोधों के लिए कैश्ड प्रतिक्रियाओं को लौटाकर डुप्लिकेट अनुरोधों को रोकता है। | +| `systemPrompt.ts` | वैश्विक सिस्टम प्रॉम्प्ट इंजेक्शन: प्रति-प्रदाता संगतता प्रबंधन के साथ, सभी अनुरोधों के लिए एक कॉन्फ़िगर करने योग्य सिस्टम प्रॉम्प्ट को जोड़ता या जोड़ता है। | +| `thinkingBudget.ts` | रीज़निंग टोकन बजट प्रबंधन: सोच/तर्क टोकन को नियंत्रित करने के लिए पासथ्रू, ऑटो (स्ट्रिप थिंकिंग कॉन्फ़िगरेशन), कस्टम (निश्चित बजट), और अनुकूली (जटिलता-स्केल) मोड का समर्थन करता है। | +| `wildcardRouter.ts` | वाइल्डकार्ड मॉडल पैटर्न रूटिंग: उपलब्धता और प्राथमिकता के आधार पर वाइल्डकार्ड पैटर्न (उदाहरण के लिए, `*/claude-*`) को ठोस प्रदाता/मॉडल जोड़े में हल करता है। | + +#### टोकन रिफ्रेश डिडुप्लीकेशन + +**OMNI_टोकन_6** + +#### खाता फ़ॉलबैक स्टेट मशीन + +```mermaid +stateDiagram-v2 + [*] --> Active + Active --> Error: Request fails (401/429/500) + Error --> Cooldown: Apply backoff + Cooldown --> Active: Cooldown expires + Active --> Active: Request succeeds (reset backoff) + + state Error { + [*] --> ClassifyError + ClassifyError --> ShouldFallback: Rate limit / Auth / Transient + ClassifyError --> NoFallback: 400 Bad Request + } + + state Cooldown { + [*] --> ExponentialBackoff + ExponentialBackoff: Level 0 = 1s + ExponentialBackoff: Level 1 = 2s + ExponentialBackoff: Level 2 = 4s + ExponentialBackoff: Max = 2min + } +``` + +#### कॉम्बो मॉडल श्रृंखला + +**OMNI_टोकन_8** + +--- + +### 4.5 अनुवादक (`open-sse/translator/`) + +स्व-पंजीकरण प्लगइन सिस्टम का उपयोग करके **प्रारूप अनुवाद इंजन**। + +#### वास्तुकला + +```mermaid +graph TD + subgraph "Request Translation" + A["Claude → OpenAI"] + B["Gemini → OpenAI"] + C["Antigravity → OpenAI"] + D["OpenAI Responses → OpenAI"] + E["OpenAI → Claude"] + F["OpenAI → Gemini"] + G["OpenAI → Kiro"] + H["OpenAI → Cursor"] + end + + subgraph "Response Translation" + I["Claude → OpenAI"] + J["Gemini → OpenAI"] + K["Kiro → OpenAI"] + L["Cursor → OpenAI"] + M["OpenAI → Claude"] + N["OpenAI → Antigravity"] + O["OpenAI → Responses"] + end +``` + +| निर्देशिका | फ़ाइलें | विवरण | +| ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 अनुवादक | प्रारूपों के बीच अनुरोध निकायों को परिवर्तित करें। प्रत्येक फ़ाइल आयात पर `register(from, to, fn)` के माध्यम से स्व-पंजीकृत होती है। | +| `response/` | 7 अनुवादक | प्रारूपों के बीच स्ट्रीमिंग प्रतिक्रिया खंडों को परिवर्तित करें। एसएसई इवेंट प्रकार, थिंकिंग ब्लॉक, टूल कॉल को संभालता है। | +| `helpers/` | 6 सहायक | साझा उपयोगिताएँ: `claudeHelper` (सिस्टम प्रॉम्प्ट निष्कर्षण, सोच कॉन्फ़िगरेशन), `geminiHelper` (भाग/सामग्री मैपिंग), `openaiHelper` (प्रारूप फ़िल्टरिंग), `toolCallHelper` (आईडी जनरेशन, अनुपलब्ध प्रतिक्रिया इंजेक्शन), `maxTokensHelper`, `responsesApiHelper`। | +| `index.ts` | — | अनुवाद इंजन: `translateRequest()`, `translateResponse()`, राज्य प्रबंधन, रजिस्ट्री। | +| **OMNI_टोकन_86** | — | प्रारूप स्थिरांक: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`। | + +#### मुख्य डिज़ाइन: स्व-पंजीकरण प्लगइन्स + +```javascript +// Each translator file calls register() on import: +import { register } from "../index.js"; +register("claude", "openai", translateClaudeToOpenAI); + +// The index.js imports all translator files, triggering registration: +import "./request/claude-to-openai.js"; // ← self-registers +``` + +--- + +### 4.6 उपयोगिताएँ (`open-sse/utils/`) + +| फ़ाइल | उद्देश्य | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | त्रुटि प्रतिक्रिया निर्माण (ओपनएआई-संगत प्रारूप), अपस्ट्रीम त्रुटि पार्सिंग, त्रुटि संदेशों से एंटीग्रेविटी रिट्री-टाइम निष्कर्षण, एसएसई त्रुटि स्ट्रीमिंग। | +| `stream.ts` | **एसएसई ट्रांसफॉर्म स्ट्रीम** - कोर स्ट्रीमिंग पाइपलाइन। दो मोड: `TRANSLATE` (पूर्ण प्रारूप अनुवाद) और `PASSTHROUGH` (सामान्यीकरण + उपयोग निकालें)। चंक बफ़रिंग, उपयोग अनुमान, सामग्री लंबाई ट्रैकिंग को संभालता है। प्रति-स्ट्रीम एनकोडर/डिकोडर उदाहरण साझा स्थिति से बचते हैं। | +| `streamHelpers.ts` | निम्न-स्तरीय SSE उपयोगिताएँ: `parseSSELine` (व्हाट्सएप-सहिष्णु), `hasValuableContent` (OpenAI/क्लाउड/जेमिनी के लिए खाली हिस्सों को फ़िल्टर करता है), `fixInvalidId`, `formatSSE` (`perf_metrics` क्लीनअप के साथ प्रारूप-जागरूक SSE क्रमबद्धता)। | +| `usageTracking.ts` | किसी भी प्रारूप से टोकन उपयोग निष्कर्षण (क्लाउड/ओपनएआई/मिथुन/प्रतिक्रियाएं), अलग टूल/संदेश चार-प्रति-टोकन अनुपात के साथ अनुमान, बफर जोड़ (2000 टोकन सुरक्षा मार्जिन), प्रारूप-विशिष्ट फ़ील्ड फ़िल्टरिंग, एएनएसआई रंगों के साथ कंसोल लॉगिंग। | +| `requestLogger.ts` | फ़ाइल-आधारित अनुरोध लॉगिंग (`ENABLE_REQUEST_LOGS=true` के माध्यम से ऑप्ट-इन)। क्रमांकित फ़ाइलों के साथ सत्र फ़ोल्डर बनाता है: `1_req_client.json` → `7_res_client.txt`। सभी I/O async (दाग-और-भूल) है। संवेदनशील हेडर को छुपाता है. | +| `bypassHandler.ts` | क्लाउड सीएलआई (शीर्षक निष्कर्षण, वार्मअप, गिनती) से विशिष्ट पैटर्न को रोकता है और किसी भी प्रदाता को कॉल किए बिना नकली प्रतिक्रियाएं लौटाता है। स्ट्रीमिंग और नॉन-स्ट्रीमिंग दोनों का समर्थन करता है। जानबूझकर क्लाउड सीएलआई दायरे तक सीमित। | +| `networkProxy.ts` | किसी दिए गए प्रदाता के लिए आउटबाउंड प्रॉक्सी URL को प्राथमिकता के साथ हल करता है: प्रदाता-विशिष्ट कॉन्फ़िगरेशन → वैश्विक कॉन्फ़िगरेशन → पर्यावरण चर (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`)। `NO_PROXY` बहिष्करण का समर्थन करता है। 30 के दशक के लिए कैश कॉन्फिगरेशन। | + +#### एसएसई स्ट्रीमिंग पाइपलाइन + +**OMNI_टोकन_11** + +#### लॉगर सत्र संरचना का अनुरोध करें + +**OMNI_टोकन_12** + +--- + +### 4.7 अनुप्रयोग परत (`src/`) + +| निर्देशिका | उद्देश्य | +| ------------- | ------------------------------------------------------------------------------- | +| `src/app/` | वेब यूआई, एपीआई रूट, एक्सप्रेस मिडलवेयर, ओएथ कॉलबैक हैंडलर | +| `src/lib/` | डेटाबेस एक्सेस (`localDb.ts`, `usageDb.ts`), प्रमाणीकरण, साझा | +| `src/mitm/` | प्रदाता ट्रैफ़िक को रोकने के लिए मैन-इन-द-मिडिल प्रॉक्सी उपयोगिताएँ | +| `src/models/` | डेटाबेस मॉडल परिभाषाएँ | +| `src/shared/` | ओपन-एसएसई फ़ंक्शंस (प्रदाता, स्ट्रीम, त्रुटि, आदि) के आसपास रैपर | +| `src/sse/` | एसएसई एंडपॉइंट हैंडलर जो ओपन-एसएसई लाइब्रेरी को एक्सप्रेस मार्गों से जोड़ते हैं | +| `src/store/` | आवेदन राज्य प्रबंधन | + +#### उल्लेखनीय एपीआई रूट + +| मार्ग | तरीके | उद्देश्य | +| --------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------- | +| `/api/provider-models` | प्राप्त करें/पोस्ट करें/हटाएं | प्रति प्रदाता कस्टम मॉडल के लिए सीआरयूडी | +| `/api/models/catalog` | प्राप्त करें | प्रदाता द्वारा समूहीकृत सभी मॉडलों (चैट, एम्बेडिंग, छवि, कस्टम) की एकत्रित सूची | +| `/api/settings/proxy` | प्राप्त/पुट/डिलीट | पदानुक्रमित आउटबाउंड प्रॉक्सी कॉन्फ़िगरेशन (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | पोस्ट | प्रॉक्सी कनेक्टिविटी को सत्यापित करता है और सार्वजनिक आईपी/विलंबता लौटाता है | +| `/v1/providers/[provider]/chat/completions` | पोस्ट | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित चैट पूर्णताएँ | +| `/v1/providers/[provider]/embeddings` | पोस्ट | मॉडल सत्यापन के साथ समर्पित प्रति-प्रदाता एम्बेडिंग | +| `/v1/providers/[provider]/images/generations` | पोस्ट | मॉडल सत्यापन के साथ प्रति-प्रदाता समर्पित छवि निर्माण | +| `/api/settings/ip-filter` | प्राप्त/डालें | आईपी ​​अनुमति सूची/अवरुद्ध सूची प्रबंधन | +| `/api/settings/thinking-budget` | प्राप्त/डालें | रीज़निंग टोकन बजट कॉन्फ़िगरेशन (पासथ्रू/ऑटो/कस्टम/अनुकूली) | +| `/api/settings/system-prompt` | प्राप्त/डालें | सभी अनुरोधों के लिए वैश्विक सिस्टम प्रॉम्प्ट इंजेक्शन | +| `/api/sessions` | प्राप्त करें | सक्रिय सत्र ट्रैकिंग और मेट्रिक्स | +| `/api/rate-limits` | प्राप्त करें | प्रति खाता दर सीमा स्थिति | + +--- + +## 5. मुख्य डिज़ाइन पैटर्न + +### 5.1 हब-एंड-स्पोक अनुवाद + +सभी प्रारूप **हब के रूप में ओपनएआई प्रारूप** के माध्यम से अनुवादित होते हैं। एक नया प्रदाता जोड़ने के लिए केवल अनुवादकों की **एक जोड़ी** (OpenAI से/से) लिखने की आवश्यकता होती है, N जोड़ी की नहीं। + +### 5.2 निष्पादक रणनीति पैटर्न + +प्रत्येक प्रदाता के पास `BaseExecutor` से विरासत में मिला एक समर्पित निष्पादक वर्ग होता है। `executors/index.ts` में फ़ैक्टरी रनटाइम पर सही का चयन करती है। + +### 5.3 स्व-पंजीकरण प्लगइन सिस्टम + +अनुवादक मॉड्यूल `register()` के माध्यम से आयात पर स्वयं को पंजीकृत करते हैं। एक नया अनुवादक जोड़ने का अर्थ केवल एक फ़ाइल बनाना और उसे आयात करना है। + +### 5.4 एक्सपोनेंशियल बैकऑफ़ के साथ खाता फ़ॉलबैक + +जब कोई प्रदाता 429/401/500 लौटाता है, तो सिस्टम घातीय कूलडाउन (1s → 2s → 4s → अधिकतम 2 मिनट) लागू करते हुए, अगले खाते पर स्विच कर सकता है। + +### 5.5 कॉम्बो मॉडल चेन + +एक "कॉम्बो" कई `provider/model` स्ट्रिंग्स को समूहित करता है। यदि पहला विफल हो जाता है, तो स्वचालित रूप से अगले पर फ़ॉलबैक हो जाता है। + +### 5.6 स्टेटफुल स्ट्रीमिंग अनुवाद + +प्रतिक्रिया अनुवाद `initState()` तंत्र के माध्यम से SSE खंडों (सोच ब्लॉक ट्रैकिंग, टूल कॉल संचय, सामग्री ब्लॉक अनुक्रमण) में स्थिति बनाए रखता है। + +### 5.7 उपयोग सुरक्षा बफर + +सिस्टम संकेतों और प्रारूप अनुवाद से ओवरहेड के कारण ग्राहकों को संदर्भ विंडो सीमा तक पहुंचने से रोकने के लिए रिपोर्ट किए गए उपयोग में 2000-टोकन बफर जोड़ा गया है। + +--- + +## 6. समर्थित प्रारूप + +| प्रारूप | दिशा | पहचानकर्ता | +| ---------------------- | -------------- | ------------------ | +| OpenAI चैट पूर्णताएँ | स्रोत + लक्ष्य | `openai` | +| ओपनएआई रिस्पॉन्स एपीआई | स्रोत + लक्ष्य | `openai-responses` | +| एंथ्रोपिक क्लाउड | स्रोत + लक्ष्य | `claude` | +| गूगल जेमिनी | स्रोत + लक्ष्य | `gemini` | +| गूगल जेमिनी सीएलआई | केवल लक्ष्य | `gemini-cli` | +| प्रतिगुरुत्वाकर्षण | स्रोत + लक्ष्य | `antigravity` | +| एडब्ल्यूएस किरो | केवल लक्ष्य | `kiro` | +| कर्सर | केवल लक्ष्य | `cursor` | + +--- + +## 7. समर्थित प्रदाता + +| प्रदाता | प्रामाणिक विधि | निष्पादक | मुख्य नोट्स | +| ------------------------ | -------------------------------- | ------------------ | ------------------------------------------------------ | +| एंथ्रोपिक क्लाउड | एपीआई कुंजी या OAuth | डिफ़ॉल्ट | `x-api-key` हेडर का उपयोग करता है | +| गूगल जेमिनी | एपीआई कुंजी या OAuth | डिफ़ॉल्ट | `x-goog-api-key` हेडर का उपयोग करता है | +| गूगल जेमिनी सीएलआई | OAuth | जेमिनीसीएलआई | `streamGenerateContent` समापन बिंदु का उपयोग करता है | +| प्रतिगुरुत्वाकर्षण | OAuth | प्रतिगुरुत्वाकर्षण | मल्टी-यूआरएल फ़ॉलबैक, कस्टम पुनः प्रयास पार्सिंग | +| ओपनएआई | एपीआई कुंजी | डिफ़ॉल्ट | मानक वाहक प्राधिकरण | +| कोडेक्स | OAuth | कोडेक्स | सिस्टम निर्देश इंजेक्ट करता है, सोच का प्रबंधन करता है | +| गिटहब कोपायलट | OAuth + सहपायलट टोकन | जीथूब | दोहरा टोकन, VSCode हेडर की नकल | +| किरो (एडब्ल्यूएस) | एडब्ल्यूएस एसएसओ ओआईडीसी या सोशल | किरो | बाइनरी इवेंटस्ट्रीम पार्सिंग | +| कर्सर आईडीई | चेकसम ऑथ | कर्सर | प्रोटोबफ़ एन्कोडिंग, SHA-256 चेकसम | +| क्वेन | OAuth | डिफ़ॉल्ट | मानक प्रमाणीकरण | +| आईफ्लो | OAuth (बेसिक + बियरर) | डिफ़ॉल्ट | डुअल ऑथ हेडर | +| ओपनराउटर | एपीआई कुंजी | डिफ़ॉल्ट | मानक वाहक प्राधिकरण | +| जीएलएम, किमी, मिनीमैक्स | एपीआई कुंजी | डिफ़ॉल्ट | क्लाउड-संगत, `x-api-key` का उपयोग करें | +| `openai-compatible-*` | एपीआई कुंजी | डिफ़ॉल्ट | गतिशील: कोई भी OpenAI-संगत समापन बिंदु | +| `anthropic-compatible-*` | एपीआई कुंजी | डिफ़ॉल्ट | गतिशील: कोई भी क्लाउड-संगत समापन बिंदु | + +--- + +## 8. डेटा प्रवाह सारांश + +### स्ट्रीमिंग अनुरोध + +**OMNI_टोकन_13** + +### गैर-स्ट्रीमिंग अनुरोध + +**OMNI_टोकन_14** + +### बाईपास प्रवाह (क्लाउड सीएलआई) + +**OMNI_टोकन_15** diff --git a/docs/i18n/in/FEATURES.md b/docs/i18n/in/FEATURES.md new file mode 100644 index 00000000..e3af59c7 --- /dev/null +++ b/docs/i18n/in/FEATURES.md @@ -0,0 +1,77 @@ +# ओमनीरूट - डैशबोर्ड फीचर गैलरी + +🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) + +ओमनीरूट डैशबोर्ड के प्रत्येक अनुभाग के लिए विज़ुअल गाइड। + +--- + +## 🔌 प्रदाता + +एआई प्रदाता कनेक्शन प्रबंधित करें: OAuth प्रदाता (क्लाउड कोड, कोडेक्स, जेमिनी सीएलआई), एपीआई कुंजी प्रदाता (ग्रोक, डीपसीक, ओपनराउटर), और मुफ्त प्रदाता (आईफ्लो, क्वेन, किरो)। + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨कॉम्बोज़ + +6 रणनीतियों के साथ मॉडल रूटिंग कॉम्बो बनाएं: पहले भरें, राउंड-रॉबिन, दो-विकल्पों की शक्ति, यादृच्छिक, कम से कम उपयोग और लागत-अनुकूलित। प्रत्येक कॉम्बो स्वचालित फ़ॉलबैक के साथ कई मॉडलों को जोड़ता है। + +**OMNI_टोकन_1** + +--- + +## 📊 विश्लेषिकी + +टोकन खपत, लागत अनुमान, गतिविधि हीटमैप, साप्ताहिक वितरण चार्ट और प्रति-प्रदाता विश्लेषण के साथ व्यापक उपयोग विश्लेषण। + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 सिस्टम हेल्थ + +वास्तविक समय की निगरानी: अपटाइम, मेमोरी, संस्करण, विलंबता प्रतिशत (p50/p95/p99), कैश आँकड़े, और प्रदाता सर्किट ब्रेकर स्थिति। + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 अनुवादक खेल का मैदान + +एपीआई अनुवादों को डीबग करने के लिए चार मोड: **प्लेग्राउंड** (फॉर्मेट कनवर्टर), **चैट टेस्टर** (लाइव अनुरोध), **टेस्ट बेंच** (बैच टेस्ट), और **लाइव मॉनिटर** (रियल-टाइम स्ट्रीम)। + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ सेटिंग्स + +सामान्य सेटिंग्स, सिस्टम स्टोरेज, बैकअप प्रबंधन (निर्यात/आयात डेटाबेस), उपस्थिति (डार्क/लाइट मोड), सुरक्षा (एपीआई एंडपॉइंट सुरक्षा और कस्टम प्रदाता ब्लॉकिंग शामिल है), रूटिंग, लचीलापन और उन्नत कॉन्फ़िगरेशन। + +**OMNI_टोकन_5** + +--- + +## 🔧 सीएलआई उपकरण + +एआई कोडिंग टूल के लिए एक-क्लिक कॉन्फ़िगरेशन: क्लाउड कोड, कोडेक्स सीएलआई, जेमिनी सीएलआई, ओपनक्लाव, किलो कोड और एंटीग्रेविटी। + +**OMNI_टोकन_6** + +--- + +## 📝 अनुरोध लॉग + +प्रदाता, मॉडल, खाता और एपीआई कुंजी द्वारा फ़िल्टरिंग के साथ वास्तविक समय अनुरोध लॉगिंग। स्थिति कोड, टोकन उपयोग, विलंबता और प्रतिक्रिया विवरण दिखाता है। + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 एपीआई समापन बिंदु + +क्षमता विश्लेषण के साथ आपका एकीकृत एपीआई समापन बिंदु: चैट पूर्णताएं, एंबेडिंग, छवि निर्माण, पुनर्रैंकिंग, ऑडियो ट्रांसक्रिप्शन और पंजीकृत एपीआई कुंजी। + +**OMNI_टोकन_8** diff --git a/docs/i18n/in/TROUBLESHOOTING.md b/docs/i18n/in/TROUBLESHOOTING.md new file mode 100644 index 00000000..405457f1 --- /dev/null +++ b/docs/i18n/in/TROUBLESHOOTING.md @@ -0,0 +1,213 @@ +🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) + +#समस्या निवारण + +ओम्निरूट के लिए सामान्य समस्याएं और समाधान। + +--- + +## त्वरित सुधार + +| समस्या | समाधान | +| -------------------------------------- | ------------------------------------------------------------------------------- | +| पहला लॉगिन काम नहीं कर रहा | `.env` में `INITIAL_PASSWORD` को जांचें (डिफ़ॉल्ट: `123456`) | +| गलत पोर्ट पर डैशबोर्ड खुलता है | `PORT=20128` और `NEXT_PUBLIC_BASE_URL=http://localhost:20128` सेट करें | +| `logs/` के अंतर्गत कोई अनुरोध लॉग नहीं | `ENABLE_REQUEST_LOGS=true` सेट करें | +| EACCES: अनुमति अस्वीकृत | `~/.omniroute` को ओवरराइड करने के लिए `DATA_DIR=/path/to/writable/dir` सेट करें | +| रूटिंग रणनीति सहेजी नहीं जा रही | v1.4.11+ पर अपडेट करें (सेटिंग्स दृढ़ता के लिए ज़ोड स्कीमा फिक्स) | + +--- + +## प्रदाता मुद्दे + +### "भाषा मॉडल ने संदेश प्रदान नहीं किया" + +**कारण:** प्रदाता कोटा समाप्त हो गया। + +**ठीक करें:** + +1. डैशबोर्ड कोटा ट्रैकर की जाँच करें +2. फ़ॉलबैक टियर वाले कॉम्बो का उपयोग करें +3. सस्ते/मुफ़्त स्तर पर स्विच करें + +### दर सीमित करना + +**कारण:** सदस्यता कोटा समाप्त हो गया। + +**ठीक करें:** + +- फ़ॉलबैक जोड़ें: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- सस्ते बैकअप के रूप में GLM/MiniMax का उपयोग करें + +### OAuth टोकन समाप्त हो गया + +ओम्निरूट स्वचालित रूप से टोकन ताज़ा करता है। यदि समस्याएँ बनी रहती हैं: + +1. डैशबोर्ड → प्रदाता → पुनः कनेक्ट करें +2. प्रदाता कनेक्शन हटाएं और पुनः जोड़ें + +--- + +## बादल मुद्दे + +### क्लाउड सिंक त्रुटियाँ + +1. अपने चल रहे उदाहरण के लिए `BASE_URL` अंक सत्यापित करें (उदाहरण के लिए, `http://localhost:20128`) +2. अपने क्लाउड एंडपॉइंट पर `CLOUD_URL` पॉइंट सत्यापित करें (जैसे, `https://omniroute.dev`) +3. `NEXT_PUBLIC_*` मानों को सर्वर-साइड मानों के साथ संरेखित रखें + +### क्लाउड `stream=false` 500 लौटाता है + +**लक्षण:** गैर-स्ट्रीमिंग कॉल के लिए क्लाउड एंडपॉइंट पर `Unexpected token 'd'...`। + +**कारण:** अपस्ट्रीम एसएसई पेलोड लौटाता है जबकि ग्राहक JSON की अपेक्षा करता है। + +**समाधान:** क्लाउड डायरेक्ट कॉल के लिए `stream=true` का उपयोग करें। स्थानीय रनटाइम में SSE→JSON फ़ॉलबैक शामिल है। + +### क्लाउड कहता है कनेक्टेड लेकिन "अमान्य एपीआई कुंजी" + +1. स्थानीय डैशबोर्ड से एक नई कुंजी बनाएं (`/api/keys`) +2. क्लाउड सिंक चलाएँ: क्लाउड सक्षम करें → अभी सिंक करें +3. पुरानी/गैर-सिंक की गई कुंजियाँ अभी भी क्लाउड पर `401` लौटा सकती हैं + +--- + +## डॉकर मुद्दे + +### सीएलआई टूल शो स्थापित नहीं है + +1. रनटाइम फ़ील्ड जांचें: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. पोर्टेबल मोड के लिए: छवि लक्ष्य `runner-cli` (बंडल सीएलआई) का उपयोग करें +3. होस्ट माउंट मोड के लिए: `CLI_EXTRA_PATHS` सेट करें और होस्ट बिन निर्देशिका को केवल पढ़ने के लिए माउंट करें +4. यदि `installed=true` और `runnable=false`: बाइनरी पाई गई लेकिन स्वास्थ्य जांच विफल रही + +### त्वरित रनटाइम सत्यापन + +```bash +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}' +``` + +--- + +## लागत संबंधी मुद्दे + +### उच्च लागत + +1. डैशबोर्ड → उपयोग में उपयोग के आँकड़े जाँचें +2. प्राथमिक मॉडल को जीएलएम/मिनीमैक्स पर स्विच करें +3. गैर-महत्वपूर्ण कार्यों के लिए फ्री टियर (मिथुन सीएलआई, आईफ्लो) का उपयोग करें +4. प्रति एपीआई कुंजी लागत बजट निर्धारित करें: डैशबोर्ड → एपीआई कुंजी → बजट + +--- + +## डिबगिंग + +### अनुरोध लॉग सक्षम करें + +अपनी `.env` फ़ाइल में `ENABLE_REQUEST_LOGS=true` सेट करें। लॉग `logs/` निर्देशिका के अंतर्गत दिखाई देते हैं। + +### प्रदाता के स्वास्थ्य की जाँच करें + +**OMNI_टोकन_1** + +### रनटाइम स्टोरेज + +- मुख्य स्थिति: `${DATA_DIR}/db.json` (प्रदाता, कॉम्बो, उपनाम, कुंजियाँ, सेटिंग्स) +- उपयोग: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- अनुरोध लॉग: `/logs/...` (जब `ENABLE_REQUEST_LOGS=true`) + +--- + +## सर्किट ब्रेकर मुद्दे + +### प्रदाता खुली स्थिति में फंसा हुआ है + +जब किसी प्रदाता का सर्किट ब्रेकर खुला होता है, तो कूलडाउन समाप्त होने तक अनुरोध अवरुद्ध हो जाते हैं। + +**ठीक करें:** + +1. **डैशबोर्ड → सेटिंग्स → लचीलापन** पर जाएं +2. प्रभावित प्रदाता के लिए सर्किट ब्रेकर कार्ड की जाँच करें +3. सभी ब्रेकर साफ़ करने के लिए **रीसेट ऑल** पर क्लिक करें, या कूलडाउन समाप्त होने तक प्रतीक्षा करें +4. रीसेट करने से पहले सत्यापित करें कि प्रदाता वास्तव में उपलब्ध है + +### प्रदाता सर्किट ब्रेकर को ट्रिप करता रहता है + +यदि कोई प्रदाता बार-बार खुली स्थिति में प्रवेश करता है: + +1. विफलता पैटर्न के लिए **डैशबोर्ड → स्वास्थ्य → प्रदाता स्वास्थ्य** की जाँच करें +2. **सेटिंग्स → लचीलापन → प्रदाता प्रोफाइल** पर जाएं और विफलता सीमा बढ़ाएं +3. जांचें कि क्या प्रदाता ने एपीआई सीमाएं बदल दी हैं या पुनः प्रमाणीकरण की आवश्यकता है +4. विलंबता टेलीमेट्री की समीक्षा करें - उच्च विलंबता टाइमआउट-आधारित विफलताओं का कारण बन सकती है + +--- + +## ऑडियो ट्रांस्क्रिप्शन मुद्दे + +### "असमर्थित मॉडल" त्रुटि + +- सुनिश्चित करें कि आप सही उपसर्ग का उपयोग कर रहे हैं: `deepgram/nova-3` या `assemblyai/best` +- सत्यापित करें कि प्रदाता **डैशबोर्ड → प्रदाता** में जुड़ा हुआ है + +### प्रतिलेखन खाली या विफल रहता है + +- समर्थित ऑडियो प्रारूप जांचें: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- सत्यापित करें कि फ़ाइल का आकार प्रदाता सीमा के भीतर है (आमतौर पर <25MB) +- प्रदाता कार्ड में प्रदाता एपीआई कुंजी वैधता की जांच करें + +--- + +## अनुवादक डिबगिंग + +प्रारूप अनुवाद समस्याओं को डीबग करने के लिए **डैशबोर्ड → अनुवादक** का उपयोग करें: + +| मोड | कब उपयोग करें | +| ---------------- | ------------------------------------------------------------------------------------------------------------- | +| **खेल का मैदान** | इनपुट/आउटपुट स्वरूपों की साथ-साथ तुलना करें - यह कैसे अनुवादित होता है यह देखने के लिए एक असफल अनुरोध चिपकाएँ | +| **चैट परीक्षक** | लाइव संदेश भेजें और हेडर सहित पूर्ण अनुरोध/प्रतिक्रिया पेलोड का निरीक्षण करें | +| **टेस्ट बेंच** | यह पता लगाने के लिए कि कौन से अनुवाद टूटे हुए हैं, सभी प्रारूप संयोजनों में बैच परीक्षण चलाएँ | +| **लाइव मॉनिटर** | रुक-रुक कर होने वाली अनुवाद समस्याओं को पकड़ने के लिए वास्तविक समय अनुरोध प्रवाह देखें | + +### सामान्य प्रारूप मुद्दे + +- **सोच टैग दिखाई नहीं दे रहे हैं** - जांचें कि क्या लक्ष्य प्रदाता सोच और सोच बजट सेटिंग का समर्थन करता है +- **टूल कॉल ड्रॉपिंग** — कुछ प्रारूप अनुवाद असमर्थित फ़ील्ड को हटा सकते हैं; खेल का मैदान मोड में सत्यापित करें +- **सिस्टम प्रॉम्प्ट गायब** — क्लाउड और जेमिनी हैंडल सिस्टम प्रॉम्प्ट अलग-अलग होते हैं; अनुवाद आउटपुट की जाँच करें +- **एसडीके ऑब्जेक्ट के बजाय कच्ची स्ट्रिंग लौटाता है** - v1.1.0 में फिक्स्ड: रिस्पॉन्स सैनिटाइज़र अब गैर-मानक फ़ील्ड्स (`x_groq`, `usage_breakdown`, आदि) को हटा देता है जो OpenAI SDK पायडेंटिक सत्यापन विफलताओं का कारण बनता है +- **GLM/ERNIE `system` भूमिका को अस्वीकार करता है** - v1.1.0 में फिक्स्ड: रोल नॉर्मलाइज़र स्वचालित रूप से असंगत मॉडल के लिए सिस्टम संदेशों को उपयोगकर्ता संदेशों में मर्ज कर देता है +- **`developer` भूमिका पहचानी नहीं गई** - v1.1.0 में ठीक किया गया: गैर-ओपनएआई प्रदाताओं के लिए स्वचालित रूप से `system` में परिवर्तित हो गया +- **`json_schema` मिथुन राशि के साथ काम नहीं कर रहा** - v1.1.0 में ठीक किया गया: `response_format` अब मिथुन राशि के `responseMimeType` + `responseSchema` में परिवर्तित हो गया है + +--- + +## लचीलापन सेटिंग्स + +### स्वचालित दर-सीमा ट्रिगर नहीं हो रही है + +- ऑटो दर-सीमा केवल एपीआई कुंजी प्रदाताओं पर लागू होती है (OAuth/सदस्यता पर नहीं) +- सत्यापित करें **सेटिंग्स → लचीलापन → प्रदाता प्रोफाइल** में ऑटो-दर-सीमा सक्षम है +- जांचें कि क्या प्रदाता `429` स्टेटस कोड या `Retry-After` हेडर लौटाता है + +### ट्यूनिंग घातीय बैकऑफ़ + +प्रदाता प्रोफ़ाइल इन सेटिंग्स का समर्थन करती हैं: + +- **आधार विलंब** — पहली विफलता के बाद प्रारंभिक प्रतीक्षा समय (डिफ़ॉल्ट: 1 सेकंड) +- **अधिकतम विलंब** — अधिकतम प्रतीक्षा समय सीमा (डिफ़ॉल्ट: 30s) +- **गुणक** - लगातार विफलता के बाद विलंब को कितना बढ़ाया जाए (डिफ़ॉल्ट: 2x) + +### वज्र-विरोधी झुंड + +जब कई समवर्ती अनुरोध एक दर-सीमित प्रदाता से टकराते हैं, तो ओमनीरूट अनुरोधों को क्रमबद्ध करने और कैस्केडिंग विफलताओं को रोकने के लिए म्यूटेक्स + ऑटो रेट-लिमिटिंग का उपयोग करता है। यह एपीआई कुंजी प्रदाताओं के लिए स्वचालित है। + +--- + +## अभी भी अटका हुआ है? + +- **गिटहब मुद्दे**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **आर्किटेक्चर**: आंतरिक विवरण के लिए [**OMNI_TOKEN_55**](ARCHITECTURE.md) देखें +- **एपीआई संदर्भ**: सभी समापन बिंदुओं के लिए [**OMNI_TOKEN_56**](API_REFERENCE.md) देखें +- **स्वास्थ्य डैशबोर्ड**: वास्तविक समय प्रणाली की स्थिति के लिए **डैशबोर्ड → स्वास्थ्य** जांचें +- **अनुवादक**: प्रारूप संबंधी समस्याओं को डीबग करने के लिए **डैशबोर्ड → अनुवादक** का उपयोग करें diff --git a/docs/i18n/in/USER_GUIDE.md b/docs/i18n/in/USER_GUIDE.md new file mode 100644 index 00000000..aad017a7 --- /dev/null +++ b/docs/i18n/in/USER_GUIDE.md @@ -0,0 +1,559 @@ +# उपयोगकर्ता गाइड + +🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) + +प्रदाताओं को कॉन्फ़िगर करने, कॉम्बो बनाने, सीएलआई टूल को एकीकृत करने और ओमनीरूट को तैनात करने के लिए संपूर्ण मार्गदर्शिका। + +--- + +## सामग्री तालिका + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [Provider Setup](#-provider-setup) +- [CLI Integration](#-cli-integration) +- [Deployment](#-deployment) +- [Available Models](#-available-models) +- [Advanced Features](#-advanced-features) + +--- + +## 💰 मूल्य निर्धारण एक नज़र में + +| टियर | प्रदाता | लागत | कोटा रीसेट | के लिए सर्वश्रेष्ठ | +| ----------------- | ------------------- | ----------------------- | -------------------- | ---------------------------- | +| **💳 सदस्यता** | क्लाउड कोड (प्रो) | $20/माह | 5 घंटे + साप्ताहिक | पहले ही सदस्यता ले ली है | +| | कोडेक्स (प्लस/प्रो) | $20-200/महीना | 5 घंटे + साप्ताहिक | OpenAI उपयोगकर्ता | +| | जेमिनी सीएलआई | **मुफ़्त** | 180K/माह + 1K/दिन | सब लोग! | +| | गिटहब कोपायलट | $10-19/माह | मासिक | GitHub उपयोगकर्ता | +| **🔑एपीआई कुंजी** | डीपसीक | प्रति उपयोग भुगतान करें | कोई नहीं | सस्ता तर्क | +| | ग्रोक | प्रति उपयोग भुगतान करें | कोई नहीं | अल्ट्रा-फास्ट अनुमान | +| | एक्सएआई (ग्रोक) | प्रति उपयोग भुगतान करें | कोई नहीं | ग्रोक 4 तर्क | +| | मिस्ट्रल | प्रति उपयोग भुगतान करें | कोई नहीं | ईयू द्वारा होस्ट किए गए मॉडल | +| | उलझन | प्रति उपयोग भुगतान करें | कोई नहीं | खोज-संवर्धित | +| | एक साथ एआई | प्रति उपयोग भुगतान करें | कोई नहीं | ओपन-सोर्स मॉडल | +| | आतिशबाजी एआई | प्रति उपयोग भुगतान करें | कोई नहीं | फास्ट फ्लक्स छवियां | +| | सेरेब्रस | प्रति उपयोग भुगतान करें | कोई नहीं | वेफर-स्केल गति | +| | सहभागी | प्रति उपयोग भुगतान करें | कोई नहीं | कमांड आर+आरएजी | +| | एनवीडिया एनआईएम | प्रति उपयोग भुगतान करें | कोई नहीं | एंटरप्राइज़ मॉडल | +| **💰सस्ता** | जीएलएम-4.7 | $0.6/1 मिलियन | प्रतिदिन सुबह 10 बजे | बजट बैकअप | +| | मिनीमैक्स एम2.1 | $0.2/1 मिलियन | 5 घंटे की रोलिंग | सबसे सस्ता विकल्प | +| | किमी K2 | $9/महीना फ्लैट | 10एम टोकन/माह | अनुमानित लागत | +| **🆓 मुफ़्त** | आईफ्लो | $0 | असीमित | 8 मॉडल निःशुल्क | +| | क्वेन | $0 | असीमित | 3 मॉडल मुफ़्त | +| | किरो | $0 | असीमित | क्लाउड मुक्त | + +**💡 प्रो टिप:** जेमिनी सीएलआई (180 हजार निःशुल्क/माह) + आईफ्लो (असीमित निःशुल्क) कॉम्बो = $0 लागत से शुरू करें! + +--- + +## 🎯 उपयोग के मामले + +### केस 1: "मेरे पास क्लाउड प्रो सदस्यता है" + +**समस्या:** भारी कोडिंग के दौरान कोटा अप्रयुक्त, दर सीमा समाप्त हो जाता है + +``` +Combo: "maximize-claude" + 1. cc/claude-opus-4-6 (use subscription fully) + 2. glm/glm-4.7 (cheap backup when quota out) + 3. if/kimi-k2-thinking (free emergency fallback) + +Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total +vs. $20 + hitting limits = frustration +``` + +### केस 2: "मुझे शून्य लागत चाहिए" + +**समस्या:** सदस्यताएं वहन नहीं कर सकते, विश्वसनीय एआई कोडिंग की आवश्यकता है + +**OMNI_टोकन_1** + +### केस 3: "मुझे 24/7 कोडिंग चाहिए, कोई रुकावट नहीं" + +**समस्या:** समय सीमा, डाउनटाइम बर्दाश्त नहीं कर सकते + +``` +Combo: "always-on" + 1. cc/claude-opus-4-6 (best quality) + 2. cx/gpt-5.2-codex (second subscription) + 3. glm/glm-4.7 (cheap, resets daily) + 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) + 5. if/kimi-k2-thinking (free unlimited) + +Result: 5 layers of fallback = zero downtime +Monthly cost: $20-200 (subscriptions) + $10-20 (backup) +``` + +### केस 4: "मुझे ओपनक्लॉ में मुफ़्त एआई चाहिए" + +**समस्या:** मैसेजिंग ऐप्स में AI सहायक की आवश्यकता है, पूरी तरह से निःशुल्क + +``` +Combo: "openclaw-free" + 1. if/glm-4.7 (unlimited free) + 2. if/minimax-m2.1 (unlimited free) + 3. if/kimi-k2-thinking (unlimited free) + +Monthly cost: $0 +Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... +``` + +--- + +## 📖 प्रदाता सेटअप + +### 🔐 सदस्यता प्रदाता + +#### क्लाउड कोड (प्रो/मैक्स) + +```bash +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking + +Models: + cc/claude-opus-4-6 + cc/claude-sonnet-4-5-20250929 + cc/claude-haiku-4-5-20251001 +``` + +**प्रो टिप:** जटिल कार्यों के लिए ओपस और गति के लिए सॉनेट का उपयोग करें। ओमनीरूट प्रति मॉडल कोटा ट्रैक करता है! + +#### ओपनएआई कोडेक्स (प्लस/प्रो) + +**OMNI_टोकन_5** + +#### जेमिनी सीएलआई (मुफ़्त 180K/माह!) + +**OMNI_टोकन_6** + +**सर्वोत्तम मूल्य:** विशाल निःशुल्क स्तर! सशुल्क स्तरों से पहले इसका उपयोग करें। + +#### गिटहब कोपायलट + +```bash +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) + +Models: + gh/gpt-5 + gh/claude-4.5-sonnet + gh/gemini-3-pro +``` + +### 💰 सस्ते प्रदाता + +#### GLM-4.7 (दैनिक रीसेट, $0.6/1 मिलियन) + +1. साइन अप करें: [Zhipu AI](https://open.bigmodel.cn/) +2. कोडिंग योजना से एपीआई कुंजी प्राप्त करें +3. डैशबोर्ड → एपीआई कुंजी जोड़ें: प्रदाता: `glm`, एपीआई कुंजी: `your-key` + +**उपयोग करें:** `glm/glm-4.7` - **प्रो टिप:** कोडिंग प्लान 1/7 लागत पर 3× कोटा प्रदान करता है! प्रतिदिन सुबह 10:00 बजे रीसेट करें। + +#### मिनीमैक्स एम2.1 (5 घंटे रीसेट, $0.20/1 मिलियन) + +1. साइन अप करें: [MiniMax](https://www.minimax.io/) +2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें + +**उपयोग करें:** `minimax/MiniMax-M2.1` - **प्रो टिप:** लंबे संदर्भ के लिए सबसे सस्ता विकल्प (1M टोकन)! + +#### किमी K2 ($9/माह फ्लैट) + +1. सदस्यता लें: [Moonshot AI](https://platform.moonshot.ai/) +2. एपीआई कुंजी प्राप्त करें → डैशबोर्ड → एपीआई कुंजी जोड़ें + +**उपयोग करें:** `kimi/kimi-latest` - **प्रो टिप:** 10M टोकन के लिए निश्चित $9/माह = $0.90/1M प्रभावी लागत! + +### 🆓 निःशुल्क प्रदाता + +#### आईफ्लो (8 मुफ़्त मॉडल) + +**OMNI_टोकन_8** + +#### क्वेन (3 मुफ़्त मॉडल) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### किरो (क्लाउड फ्री) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨कॉम्बोज़ + +### उदाहरण 1: सदस्यता अधिकतम करें → सस्ता बैकअप + +**OMNI_टोकन_11** + +### उदाहरण 2: केवल निःशुल्क (शून्य लागत) + +**OMNI_टोकन_12** + +--- + +## 🔧 सीएलआई एकीकरण + +### कर्सर आईडीई + +**OMNI_टोकन_13** + +### क्लाउड कोड + +संपादित करें `~/.claude/config.json`: + +**OMNI_टोकन_14** + +### कोडेक्स सीएलआई + +**OMNI_टोकन_15** + +### ओपनक्लॉ + +संपादित करें `~/.openclaw/openclaw.json`: + +**OMNI_टोकन_16** + +**या डैशबोर्ड का उपयोग करें:** सीएलआई टूल्स → ओपनक्लॉ → ऑटो-कॉन्फ़िगरेशन + +### क्लाइन / जारी रखें / रूकोड + +**OMNI_टोकन_17** + +--- + +## 🚀 परिनियोजन + +### वीपीएस परिनियोजन + +**OMNI_टोकन_18** + +### डॉकर + +**OMNI_टोकन_19** + +सीएलआई बायनेरिज़ के साथ होस्ट-एकीकृत मोड के लिए, मुख्य दस्तावेज़ में डॉकर अनुभाग देखें। + +### पर्यावरण चर + +| परिवर्तनीय | डिफ़ॉल्ट | विवरण | +| --------------------- | ------------------------------------ | ------------------------------------------------------ | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT हस्ताक्षर रहस्य (**उत्पादन में परिवर्तन**) | +| `INITIAL_PASSWORD` | `123456` | पहला लॉगिन पासवर्ड | +| `DATA_DIR` | `~/.omniroute` | डेटा निर्देशिका (डीबी, उपयोग, लॉग) | +| `PORT` | फ्रेमवर्क डिफ़ॉल्ट | सर्विस पोर्ट (उदाहरणों में `20128`) | +| `HOSTNAME` | फ्रेमवर्क डिफ़ॉल्ट | बाइंड होस्ट (डॉकर डिफ़ॉल्ट रूप से `0.0.0.0`) | +| `NODE_ENV` | रनटाइम डिफ़ॉल्ट | तैनाती के लिए `production` सेट करें | +| `BASE_URL` | `http://localhost:20128` | सर्वर-साइड आंतरिक आधार URL | +| `CLOUD_URL` | `https://omniroute.dev` | क्लाउड सिंक एंडपॉइंट बेस यूआरएल | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | जेनरेट की गई एपीआई कुंजियों के लिए एचएमएसी रहस्य | +| `REQUIRE_API_KEY` | `false` | `/v1/*` पर बियरर एपीआई कुंजी लागू करें | +| `ENABLE_REQUEST_LOGS` | `false` | अनुरोध/प्रतिक्रिया लॉग सक्षम करता है | +| `AUTH_COOKIE_SECURE` | `false` | फोर्स `Secure` ऑथ कुकी (HTTPS रिवर्स प्रॉक्सी के पीछे) | + +संपूर्ण पर्यावरण चर संदर्भ के लिए, [README](../README.md) देखें। + +--- + +## 📊 उपलब्ध मॉडल + +**OMNI_टोकन_157** + +सभी उपलब्ध मॉडल देखें + +**क्लाउड कोड (`cc/`)** — प्रो/मैक्स: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**कोडेक्स (`cx/`)** — प्लस/प्रो: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` + +**मिथुन सीएलआई (`gc/`)** — मुफ़्त: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` + +**गिटहब कोपायलट (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**जीएलएम (`glm/`)** — $0.6/1M: `glm/glm-4.7` + +**मिनीमैक्स (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** — मुफ़्त: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` + +**क्वेन (`qw/`)** — मुफ़्त: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` + +**किरो (`kr/`)** — मुफ़्त: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` + +**डीपसीक (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` + +**ग्रोक (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` + +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` + +**मिस्ट्रल (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` + +**व्याकुलता (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**एक साथ AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**आतिशबाजी एआई (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**सेरेब्रस (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**यहां (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**एनवीडिया एनआईएम (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +**OMNI_टोकन_162** + +--- + +## 🧩 उन्नत सुविधाएँ + +### कस्टम मॉडल + +ऐप अपडेट की प्रतीक्षा किए बिना किसी भी प्रदाता से कोई भी मॉडल आईडी जोड़ें: + +```bash +# Via API +curl -X POST http://localhost:20128/api/provider-models \ + -H "Content-Type: application/json" \ + -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}' + +# List: curl http://localhost:20128/api/provider-models?provider=openai +# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" +``` + +या डैशबोर्ड का उपयोग करें: **प्रदाता → [प्रदाता] → कस्टम मॉडल**। + +### समर्पित प्रदाता मार्ग + +मॉडल सत्यापन के साथ सीधे एक विशिष्ट प्रदाता को रूट अनुरोध: + +**OMNI_टोकन_21** + +गायब होने पर प्रदाता उपसर्ग स्वतः जुड़ जाता है। बेमेल मॉडल `400` लौटाते हैं। + +### नेटवर्क प्रॉक्सी कॉन्फ़िगरेशन + +**OMNI_टोकन_22** + +**प्राथमिकता:** कुंजी-विशिष्ट → कॉम्बो-विशिष्ट → प्रदाता-विशिष्ट → वैश्विक → पर्यावरण। + +### मॉडल कैटलॉग एपीआई + +**OMNI_टोकन_23** + +प्रदाता द्वारा प्रकारों (`chat`, `embedding`, `image`) के साथ समूहीकृत मॉडल लौटाता है। + +### क्लाउड सिंक + +- सभी डिवाइसों में सिंक प्रदाता, कॉम्बो और सेटिंग्स +- टाइमआउट + फेल-फास्ट के साथ स्वचालित पृष्ठभूमि सिंक +- उत्पादन में सर्वर-साइड `BASE_URL`/`CLOUD_URL` को प्राथमिकता दें + +### एलएलएम गेटवे इंटेलिजेंस (चरण 9) + +- **सिमेंटिक कैश** - ऑटो-कैश नॉन-स्ट्रीमिंग, तापमान = 0 प्रतिक्रियाएँ (`X-OmniRoute-No-Cache: true` के साथ बायपास) +- **इडेम्पोटेंसी का अनुरोध करें** - `Idempotency-Key` या `X-Request-Id` हेडर के माध्यम से 5s के भीतर अनुरोधों को डीडुप्लिकेट करता है +- **प्रगति ट्रैकिंग** - `X-OmniRoute-Progress: true` हेडर के माध्यम से SSE `event: progress` इवेंट में ऑप्ट-इन करें + +--- + +### अनुवादक खेल का मैदान + +**डैशबोर्ड → अनुवादक** के माध्यम से पहुंच। डीबग करें और कल्पना करें कि कैसे ओमनीरूट प्रदाताओं के बीच एपीआई अनुरोधों का अनुवाद करता है। + +| मोड | उद्देश्य | +| ---------------- | -------------------------------------------------------------------------------------------- | +| **खेल का मैदान** | स्रोत/लक्ष्य प्रारूप चुनें, एक अनुरोध चिपकाएँ, और अनुवादित आउटपुट तुरंत देखें | +| **चैट परीक्षक** | प्रॉक्सी के माध्यम से लाइव चैट संदेश भेजें और पूर्ण अनुरोध/प्रतिक्रिया चक्र का निरीक्षण करें | +| **टेस्ट बेंच** | अनुवाद की शुद्धता को सत्यापित करने के लिए कई प्रारूप संयोजनों में बैच परीक्षण चलाएँ | +| **लाइव मॉनिटर** | प्रॉक्सी के माध्यम से अनुरोध प्रवाहित होने पर वास्तविक समय में अनुवाद देखें | + +**उपयोग के मामले:** + +- डीबग करें कि कोई विशिष्ट ग्राहक/प्रदाता संयोजन विफल क्यों होता है +- सत्यापित करें कि थिंकिंग टैग, टूल कॉल और सिस्टम प्रॉम्प्ट सही ढंग से अनुवाद करते हैं +- ओपनएआई, क्लाउड, जेमिनी और रिस्पॉन्स एपीआई प्रारूपों के बीच प्रारूप अंतर की तुलना करें + +--- + +### रूटिंग रणनीतियाँ + +**डैशबोर्ड → सेटिंग्स → रूटिंग** के माध्यम से कॉन्फ़िगर करें। + +| रणनीति | विवरण | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | +| **पहले भरें** | प्राथमिकता क्रम में खातों का उपयोग करता है - प्राथमिक खाता अनुपलब्ध होने तक सभी अनुरोधों को संभालता है | +| **राउंड रॉबिन** | एक विन्यास योग्य चिपचिपा सीमा के साथ सभी खातों के माध्यम से चक्र (डिफ़ॉल्ट: प्रति खाता 3 कॉल) | +| **पी2सी (दो विकल्पों की शक्ति)** | 2 यादृच्छिक खाते चुनता है और स्वस्थ खाते की ओर ले जाता है - स्वास्थ्य के प्रति जागरूकता के साथ भार संतुलित करता है | +| **यादृच्छिक** | फिशर-येट्स शफल | का उपयोग करके प्रत्येक अनुरोध के लिए यादृच्छिक रूप से एक खाता चुनता है | +| **कम से कम इस्तेमाल** | सबसे पुराने `lastUsedAt` टाइमस्टैम्प के साथ खाते तक रूट, ट्रैफ़िक को समान रूप से वितरित करना | +| **लागत अनुकूलित** | सबसे कम लागत वाले प्रदाताओं के लिए अनुकूलन, सबसे कम प्राथमिकता मूल्य वाले खाते तक रूट | + +#### वाइल्डकार्ड मॉडल उपनाम + +मॉडल नामों को रीमैप करने के लिए वाइल्डकार्ड पैटर्न बनाएं: + +**OMNI_टोकन_24** + +वाइल्डकार्ड `*` (कोई भी वर्ण) और `?` (एकल वर्ण) का समर्थन करते हैं। + +#### फ़ॉलबैक चेन + +वैश्विक फ़ॉलबैक श्रृंखलाओं को परिभाषित करें जो सभी अनुरोधों पर लागू होती हैं: + +**OMNI_टोकन_25** + +--- + +### लचीलापन और सर्किट ब्रेकर + +**डैशबोर्ड → सेटिंग्स → लचीलापन** के माध्यम से कॉन्फ़िगर करें। + +ओमनीरूट चार घटकों के साथ प्रदाता-स्तरीय लचीलापन लागू करता है: + +1. **प्रदाता प्रोफाइल** - प्रति-प्रदाता कॉन्फ़िगरेशन: + - विफलता सीमा (उद्घाटन से पहले कितनी विफलताएं) + - कूलडाउन अवधि + - दर सीमा का पता लगाने की संवेदनशीलता + - घातीय बैकऑफ़ पैरामीटर + +2. **संपादन योग्य दर सीमाएँ** — डैशबोर्ड में कॉन्फ़िगर करने योग्य सिस्टम-स्तरीय डिफ़ॉल्ट: + - **प्रति मिनट अनुरोध (आरपीएम)** - प्रति खाता प्रति मिनट अधिकतम अनुरोध + - **अनुरोधों के बीच न्यूनतम समय** - अनुरोधों के बीच मिलीसेकंड में न्यूनतम अंतर + - **अधिकतम समवर्ती अनुरोध** — प्रति खाता अधिकतम एक साथ अनुरोध + - संशोधित करने के लिए **संपादित करें** पर क्लिक करें, फिर **सहेजें** या **रद्द करें** पर क्लिक करें। मान लचीलापन एपीआई के माध्यम से बने रहते हैं। + +3. **सर्किट ब्रेकर** - प्रति प्रदाता विफलताओं को ट्रैक करता है और सीमा तक पहुंचने पर स्वचालित रूप से सर्किट खोलता है: + - **बंद** (स्वस्थ) - अनुरोध सामान्य रूप से प्रवाहित होते हैं + - **खुला** - बार-बार विफलताओं के बाद प्रदाता अस्थायी रूप से अवरुद्ध हो जाता है + - **आधा_खुला** — परीक्षण किया जा रहा है कि प्रदाता ठीक हो गया है या नहीं + +4. **नीतियाँ और लॉक किए गए पहचानकर्ता** - बल-अनलॉक क्षमता के साथ सर्किट ब्रेकर की स्थिति और लॉक किए गए पहचानकर्ताओं को दिखाता है। + +5. **दर सीमा ऑटो-डिटेक्शन** - प्रदाता दर सीमा से बचने के लिए `429` और `Retry-After` हेडर मॉनिटर करता है। + +**प्रो टिप:** जब कोई प्रदाता आउटेज से उबरता है तो सभी सर्किट ब्रेकर और कूलडाउन को साफ़ करने के लिए **रीसेट ऑल** बटन का उपयोग करें। + +--- + +### डेटाबेस निर्यात/आयात + +**डैशबोर्ड → सेटिंग्स → सिस्टम और स्टोरेज** में डेटाबेस बैकअप प्रबंधित करें। + +| कार्रवाई | विवरण | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| **डेटाबेस निर्यात करें** | वर्तमान SQLite डेटाबेस को `.sqlite` फ़ाइल के रूप में डाउनलोड करता है | +| **सभी निर्यात करें (.tar.gz)** | एक पूर्ण बैकअप संग्रह डाउनलोड करता है जिसमें शामिल हैं: डेटाबेस, सेटिंग्स, कॉम्बो, प्रदाता कनेक्शन (कोई क्रेडेंशियल नहीं), एपीआई कुंजी मेटाडेटा | +| **डेटाबेस आयात करें** | वर्तमान डेटाबेस को बदलने के लिए `.sqlite` फ़ाइल अपलोड करें। एक पूर्व-आयात बैकअप स्वचालित रूप से बनाया जाता है | + +**OMNI_टोकन_26** + +**आयात सत्यापन:** आयातित फ़ाइल को अखंडता (SQLite प्राग्मा चेक), आवश्यक तालिकाओं (`provider_connections`, `provider_nodes`, `combos`, `api_keys`), और आकार (अधिकतम 100MB) के लिए मान्य किया गया है। + +**उपयोग के मामले:** + +- मशीनों के बीच ओम्निरूट माइग्रेट करें +- आपदा पुनर्प्राप्ति के लिए बाहरी बैकअप बनाएं +- टीम के सदस्यों के बीच कॉन्फ़िगरेशन साझा करें (सभी निर्यात करें → संग्रह साझा करें) + +--- + +### सेटिंग्स डैशबोर्ड + +आसान नेविगेशन के लिए सेटिंग पृष्ठ को 5 टैब में व्यवस्थित किया गया है: + +| टैब | सामग्री | +| ----------- | --------------------------------------------------------------------------------------------------- | +| **सुरक्षा** | लॉगिन/पासवर्ड सेटिंग्स, आईपी एक्सेस कंट्रोल, `/models` के लिए एपीआई प्रमाणीकरण, और प्रदाता ब्लॉकिंग | +| **रूटिंग** | वैश्विक रूटिंग रणनीति (6 विकल्प), वाइल्डकार्ड मॉडल उपनाम, फ़ॉलबैक चेन, कॉम्बो डिफ़ॉल्ट | +| **लचीलापन** | प्रदाता प्रोफाइल, संपादन योग्य दर सीमा, सर्किट ब्रेकर स्थिति, नीतियां और लॉक पहचानकर्ता | +| **एआई** | बजट कॉन्फ़िगरेशन, ग्लोबल सिस्टम प्रॉम्प्ट इंजेक्शन, प्रॉम्प्ट कैश आँकड़े सोचना | +| **उन्नत** | वैश्विक प्रॉक्सी कॉन्फ़िगरेशन (HTTP/SOCKS5) | + +--- + +### लागत एवं बजट प्रबंधन + +**डैशबोर्ड → लागत** के माध्यम से पहुंच। + +| टैब | उद्देश्य | +| ------------------ | --------------------------------------------------------------------------------------------------------- | +| **बजट** | दैनिक/साप्ताहिक/मासिक बजट और वास्तविक समय ट्रैकिंग के साथ प्रति एपीआई कुंजी खर्च सीमा निर्धारित करें | +| **मूल्य निर्धारण** | मॉडल मूल्य निर्धारण प्रविष्टियाँ देखें और संपादित करें - प्रति प्रदाता प्रति 1K इनपुट/आउटपुट टोकन की लागत | + +```bash +# API: Set a budget +curl -X POST http://localhost:20128/api/usage/budget \ + -H "Content-Type: application/json" \ + -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' + +# API: Get current budget status +curl http://localhost:20128/api/usage/budget +``` + +**लागत ट्रैकिंग:** प्रत्येक अनुरोध टोकन उपयोग को लॉग करता है और मूल्य निर्धारण तालिका का उपयोग करके लागत की गणना करता है। प्रदाता, मॉडल और एपीआई कुंजी द्वारा **डैशबोर्ड → उपयोग** में विश्लेषण देखें। + +--- + +### ऑडियो ट्रांसक्रिप्शन + +ओमनीरूट ओपनएआई-संगत एंडपॉइंट के माध्यम से ऑडियो ट्रांसक्रिप्शन का समर्थन करता है: + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data + +# Example with curl +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@audio.mp3" \ + -F "model=deepgram/nova-3" +``` + +उपलब्ध प्रदाता: **डीपग्राम** (`deepgram/`), **AssemblyAI** (`assemblyai/`)। + +समर्थित ऑडियो प्रारूप: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`। + +--- + +### कॉम्बो संतुलन रणनीतियाँ + +**डैशबोर्ड → कॉम्बो → बनाएं/संपादित करें → रणनीति** में प्रति-कॉम्बो संतुलन कॉन्फ़िगर करें। + +| रणनीति | विवरण | +| --------------------- | ------------------------------------------------------------------------------ | +| **राउंड-रॉबिन** | मॉडलों के माध्यम से क्रमिक रूप से घूमता है | +| **प्राथमिकता** | हमेशा पहला मॉडल आज़माता है; केवल त्रुटि पर वापस आता है | +| **यादृच्छिक** | प्रत्येक अनुरोध के लिए कॉम्बो से एक यादृच्छिक मॉडल चुनता है | +| **भारित** | प्रति मॉडल निर्दिष्ट भार के आधार पर आनुपातिक रूप से मार्ग | +| **कम से कम इस्तेमाल** | सबसे कम हालिया अनुरोधों के साथ मॉडल पर रूट (कॉम्बो मेट्रिक्स का उपयोग करता है) | +| **लागत-अनुकूलित** | सबसे सस्ते उपलब्ध मॉडल के लिए मार्ग (मूल्य निर्धारण तालिका का उपयोग करता है) | + +ग्लोबल कॉम्बो डिफॉल्ट्स को **डैशबोर्ड → सेटिंग्स → रूटिंग → कॉम्बो डिफॉल्ट्स** में सेट किया जा सकता है। + +--- + +### स्वास्थ्य डैशबोर्ड + +**डैशबोर्ड → स्वास्थ्य** के माध्यम से पहुंच। 6 कार्डों के साथ वास्तविक समय प्रणाली स्वास्थ्य अवलोकन: + +| कार्ड | यह क्या दिखाता है | +| ---------------------- | ----------------------------------------------------------------------- | +| **सिस्टम स्थिति** | अपटाइम, संस्करण, मेमोरी उपयोग, डेटा निर्देशिका | +| **प्रदाता स्वास्थ्य** | प्रति-प्रदाता सर्किट ब्रेकर स्थिति (बंद/खुला/आधा-खुला) | +| **दर सीमा** | शेष समय के साथ प्रति खाता सक्रिय दर सीमा को शांत करना | +| **सक्रिय तालाबंदी** | प्रदाताओं को तालाबंदी नीति द्वारा अस्थायी रूप से अवरुद्ध कर दिया गया है | +| **हस्ताक्षर कैश** | डिडुप्लीकेशन कैश आँकड़े (सक्रिय कुंजियाँ, हिट दर) | +| **विलंबता टेलीमेट्री** | प्रति प्रदाता p50/p95/p99 विलंबता एकत्रीकरण | + +**प्रो टिप:** स्वास्थ्य पृष्ठ हर 10 सेकंड में स्वतः ताज़ा हो जाता है। यह पहचानने के लिए सर्किट ब्रेकर कार्ड का उपयोग करें कि कौन से प्रदाता समस्याओं का सामना कर रहे हैं। diff --git a/docs/i18n/it/API_REFERENCE.md b/docs/i18n/it/API_REFERENCE.md new file mode 100644 index 00000000..3dea1f9a --- /dev/null +++ b/docs/i18n/it/API_REFERENCE.md @@ -0,0 +1,441 @@ +# Riferimento API + +🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) + +Riferimento completo per tutti gli endpoint API OmniRoute. + +--- + +## Sommario + +- [Chat Completions](#chat-completions) +- [Embeddings](#embeddings) +- [Image Generation](#image-generation) +- [List Models](#list-models) +- [Compatibility Endpoints](#compatibility-endpoints) +- [Semantic Cache](#semantic-cache) +- [Dashboard & Management](#dashboard--management) +- [Request Processing](#request-processing) +- [Authentication](#authentication) + +--- + +## Completamenti della chat + +```bash +POST /v1/chat/completions +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "cc/claude-opus-4-6", + "messages": [ + {"role": "user", "content": "Write a function to..."} + ], + "stream": true +} +``` + +### Intestazioni personalizzate + +| Intestazione | Direzione | Descrizione | +| ------------------------ | --------- | --------------------------------------------------- | +| `X-OmniRoute-No-Cache` | Richiedi | Imposta su `true` per ignorare la cache | +| `X-OmniRoute-Progress` | Richiedi | Imposta su `true` per gli eventi di avanzamento | +| `Idempotency-Key` | Richiedi | Chiave di deduplicazione (finestra 5s) | +| `X-Request-Id` | Richiedi | Chiave di deduplicazione alternativa | +| `X-OmniRoute-Cache` | Risposta | `HIT` o `MISS` (non streaming) | +| `X-OmniRoute-Idempotent` | Risposta | `true` se deduplicato | +| `X-OmniRoute-Progress` | Risposta | `enabled` se il monitoraggio dei progressi è attivo | + +--- + +## Incorporamenti + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Fornitori disponibili: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## Generazione di immagini + +```bash +POST /v1/images/generations +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "openai/dall-e-3", + "prompt": "A beautiful sunset over mountains", + "size": "1024x1024" +} +``` + +Fornitori disponibili: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## Elenco modelli + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## Endpoint di compatibilità + +| Metodo | Percorso | Formato | +| ------- | --------------------------- | ----------------------- | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | Antropico | +| POST | `/v1/responses` | Risposte OpenAI | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| OTTIENI | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | Antropico | +| OTTIENI | `/v1beta/models` | Gemelli | +| POST | `/v1beta/models/{...path}` | Gemini genera contenuto | +| POST | `/v1/api/chat` | Ollama | + +### Percorsi di provider dedicati + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +Se mancante, il prefisso del provider viene aggiunto automaticamente. I modelli non corrispondenti restituiscono `400`. + +--- + +## Cache semantica + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +Esempio di risposta: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Cruscotto e gestione + +### Autenticazione + +| Punto finale | Metodo | Descrizione | +| ----------------------------- | ------------- | ----------------------------------- | +| `/api/auth/login` | POST | Accedi | +| `/api/auth/logout` | POST | Esci | +| `/api/settings/require-login` | OTTIENI/METTI | Attiva/disattiva il login richiesto | + +### Gestione dei fornitori + +| Punto finale | Metodo | Descrizione | +| ---------------------------- | ------------------------- | ---------------------------------------- | +| `/api/providers` | OTTIENI/POSTA | Elenca/crea fornitori | +| `/api/providers/[id]` | OTTIENI/INSERISCI/ELIMINA | Gestisci un fornitore | +| `/api/providers/[id]/test` | POST | Testare la connessione al provider | +| `/api/providers/[id]/models` | OTTIENI | Elenco modelli provider | +| `/api/providers/validate` | POST | Convalida la configurazione del provider | +| `/api/provider-nodes*` | Vari | Gestione nodo provider | +| `/api/provider-models` | OTTIENI/INVIA/ELIMINA | Modelli personalizzati | + +### Flussi OAuth + +| Punto finale | Metodo | Descrizione | +| -------------------------------- | ------ | ---------------------------- | +| `/api/oauth/[provider]/[action]` | Vari | OAuth specifico del provider | + +### Routing e configurazione + +| Punto finale | Metodo | Descrizione | +| --------------------- | ------------- | ------------------------------------ | +| `/api/models/alias` | OTTIENI/POSTA | Alias ​​del modello | +| `/api/models/catalog` | OTTIENI | Tutti i modelli per fornitore + tipo | +| `/api/combos*` | Vari | Gestione combinata | +| `/api/keys*` | Vari | Gestione delle chiavi API | +| `/api/pricing` | OTTIENI | Prezzo del modello | + +### Utilizzo e analisi + +| Punto finale | Metodo | Descrizione | +| --------------------------- | ------- | ------------------------------- | +| `/api/usage/history` | OTTIENI | Cronologia utilizzo | +| `/api/usage/logs` | OTTIENI | Registri di utilizzo | +| `/api/usage/request-logs` | OTTIENI | Registri a livello di richiesta | +| `/api/usage/[connectionId]` | OTTIENI | Utilizzo per connessione | + +### Impostazioni + +| Punto finale | Metodo | Descrizione | +| ------------------------------- | ------------- | ---------------------------------- | +| `/api/settings` | OTTIENI/METTI | Impostazioni generali | +| `/api/settings/proxy` | OTTIENI/METTI | Configurazione proxy di rete | +| `/api/settings/proxy/test` | POST | Testare la connessione proxy | +| `/api/settings/ip-filter` | OTTIENI/METTI | Lista consentita/lista bloccata IP | +| `/api/settings/thinking-budget` | OTTIENI/METTI | Ragionamento gettone bilancio | +| `/api/settings/system-prompt` | OTTIENI/METTI | Prompt del sistema globale | + +### Monitoraggio + +| Punto finale | Metodo | Descrizione | +| ------------------------ | --------------- | ---------------------------------- | +| `/api/sessions` | OTTIENI | Monitoraggio della sessione attiva | +| `/api/rate-limits` | OTTIENI | Limiti di tasso per conto | +| `/api/monitoring/health` | OTTIENI | Controllo sanitario | +| `/api/cache` | OTTIENI/ELIMINA | Statistiche cache / cancella | + +### Backup ed esportazione/importazione + +| Punto finale | Metodo | Descrizione | +| --------------------------- | ------- | ------------------------------------------------- | +| `/api/db-backups` | OTTIENI | Elenca i backup disponibili | +| `/api/db-backups` | METTERE | Crea un backup manuale | +| `/api/db-backups` | POST | Ripristina da un backup specifico | +| `/api/db-backups/export` | OTTIENI | Scarica il database come file .sqlite | +| `/api/db-backups/import` | POST | Carica il file .sqlite per sostituire il database | +| `/api/db-backups/exportAll` | OTTIENI | Scarica il backup completo come archivio .tar.gz | + +### Sincronizzazione nel cloud + +| Punto finale | Metodo | Descrizione | +| ---------------------- | ------ | ---------------------------------------- | +| `/api/sync/cloud` | Vari | Operazioni di sincronizzazione nel cloud | +| `/api/sync/initialize` | POST | Inizializza sincronizzazione | +| `/api/cloud/*` | Vari | Gestione del cloud | + +### Strumenti CLI + +| Punto finale | Metodo | Descrizione | +| ---------------------------------- | ------- | --------------------------- | +| `/api/cli-tools/claude-settings` | OTTIENI | Stato CLI di Claude | +| `/api/cli-tools/codex-settings` | OTTIENI | Stato CLI del Codice | +| `/api/cli-tools/droid-settings` | OTTIENI | Stato CLI Droid | +| `/api/cli-tools/openclaw-settings` | OTTIENI | Stato della CLI di OpenClaw | +| `/api/cli-tools/runtime/[toolId]` | OTTIENI | Runtime CLI generico | + +Le risposte della CLI includono: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### Resilienza e limiti di velocità + +| Punto finale | Metodo | Descrizione | +| ----------------------- | ------------- | -------------------------------------------- | +| `/api/resilience` | OTTIENI/METTI | Ottieni/aggiorna profili di resilienza | +| `/api/resilience/reset` | POST | Ripristinare gli interruttori automatici | +| `/api/rate-limits` | OTTIENI | Stato limite tariffa per account | +| `/api/rate-limit` | OTTIENI | Configurazione del limite tariffario globale | + +### Valutazioni + +| Punto finale | Metodo | Descrizione | +| ------------ | ------------- | ------------------------------------------------------ | +| `/api/evals` | OTTIENI/POSTA | Elenca le suite di valutazione / esegui la valutazione | + +### Politiche + +| Punto finale | Metodo | Descrizione | +| --------------- | --------------------- | ------------------------------- | +| `/api/policies` | OTTIENI/INVIA/ELIMINA | Gestire le politiche di routing | + +### Conformità + +| Punto finale | Metodo | Descrizione | +| --------------------------- | ------- | ------------------------------------------------- | +| `/api/compliance/audit-log` | OTTIENI | Registro di controllo della conformità (ultimi N) | + +### v1beta (compatibile con Gemini) + +| Punto finale | Metodo | Descrizione | +| -------------------------- | ------- | -------------------------------------- | +| `/v1beta/models` | OTTIENI | Elenco modelli in formato Gemini | +| `/v1beta/models/{...path}` | POST | Gemelli `generateContent` punto finale | + +Questi endpoint rispecchiano il formato API di Gemini per i client che prevedono la compatibilità nativa dell'SDK Gemini. + +### API interne/di sistema + +| Punto finale | Metodo | Descrizione | +| --------------- | ------- | ------------------------------------------------------------------------------------ | +| `/api/init` | OTTIENI | Controllo dell'inizializzazione dell'applicazione (utilizzato alla prima esecuzione) | +| `/api/tags` | OTTIENI | Tag modello compatibili con Ollama (per client Ollama) | +| `/api/restart` | POST | Attiva il riavvio corretto del server | +| `/api/shutdown` | POST | Attiva l'arresto regolare del server | + +> **Nota:** questi endpoint vengono utilizzati internamente dal sistema o per la compatibilità del client Ollama. In genere non vengono chiamati dagli utenti finali. + +--- + +## Trascrizione audio + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Trascrivi file audio utilizzando Deepgram o AssemblyAI. + +**Richiesta:** + +```bash +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@recording.mp3" \ + -F "model=deepgram/nova-3" +``` + +**Risposta:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**Fornitori supportati:** `deepgram/nova-3`, `assemblyai/best`. + +**Formati supportati:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +## Compatibilità con Ollama + +Per i clienti che utilizzano il formato API di Ollama: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +Le richieste vengono tradotte automaticamente tra Ollama e formati interni. + +--- + +## Telemetria + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Risposta:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## Bilancio + +```bash +# Get budget status for all API keys +GET /api/usage/budget + +# Set or update a budget +POST /api/usage/budget +Content-Type: application/json + +{ + "keyId": "key-123", + "limit": 50.00, + "period": "monthly" +} +``` + +--- + +## Disponibilità del modello + +```bash +# Get real-time model availability across all providers +GET /api/models/availability + +# Check availability for a specific model +POST /api/models/availability +Content-Type: application/json + +{ + "model": "claude-sonnet-4-5-20250929" +} +``` + +--- + +## Elaborazione della richiesta + +1. Il cliente invia la richiesta a `/v1/*` +2. Chiamate del gestore del percorso `handleChat`, `handleEmbedding`, `handleAudioTranscription` o `handleImageGeneration` +3. Il modello è risolto (provider/modello diretto o alias/combo) +4. Credenziali selezionate dal DB locale con filtro sulla disponibilità dell'account +5. Per chat: `handleChatCore`: rilevamento del formato, traduzione, controllo della cache, controllo dell'idempotenza +6. L'esecutore del provider invia una richiesta upstream +7. Risposta ricondotta nel formato client (chat) o restituita così com'è (incorporamenti/immagini/audio) +8. Utilizzo/registrazione registrati +9. Il fallback si applica agli errori secondo le regole della combo + +Riferimento completo all'architettura: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## Autenticazione + +- I percorsi della dashboard (`/dashboard/*`) utilizzano il cookie `auth_token` +- L'accesso utilizza l'hash della password salvata; fallback su `INITIAL_PASSWORD` +- `requireLogin` attivabile tramite `/api/settings/require-login` +- Le rotte `/v1/*` richiedono facoltativamente la chiave API Bearer quando `REQUIRE_API_KEY=true` diff --git a/docs/i18n/it/ARCHITECTURE.md b/docs/i18n/it/ARCHITECTURE.md new file mode 100644 index 00000000..2d42cb82 --- /dev/null +++ b/docs/i18n/it/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# Architettura OmniRoute + +🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) + +_Ultimo aggiornamento: 2026-02-18_ + +## Sintesi + +OmniRoute è un gateway di routing AI locale e un dashboard basato su Next.js. +Fornisce un singolo endpoint compatibile con OpenAI (`/v1/*`) e instrada il traffico attraverso più provider upstream con traduzione, fallback, aggiornamento dei token e monitoraggio dell'utilizzo. + +Funzionalità principali: + +- Superficie API compatibile con OpenAI per CLI/strumenti (28 provider) +- Traduzione di richieste/risposte tra formati di fornitori +- Fallback combo modello (sequenza multi-modello) +- Fallback a livello di account (più account per fornitore) +- Gestione della connessione del provider OAuth + chiave API +- Generazione di incorporamento tramite `/v1/embeddings` (6 fornitori, 9 modelli) +- Generazione di immagini tramite `/v1/images/generations` (4 fornitori, 9 modelli) +- Pensa all'analisi dei tag (`...`) per i modelli di ragionamento +- Sanificazione della risposta per una rigorosa compatibilità con l'SDK OpenAI +- Normalizzazione dei ruoli (sviluppatore→sistema, sistema→utente) per compatibilità tra provider +- Conversione dell'output strutturato (json_schema → Gemini ResponseSchema) +- Persistenza locale per provider, chiavi, alias, combo, impostazioni, prezzi +- Monitoraggio dell'utilizzo/costo e registrazione delle richieste +- Sincronizzazione cloud opzionale per la sincronizzazione multi-dispositivo/stato +- Lista consentita/lista bloccata IP per il controllo dell'accesso API +- Gestione intelligente del budget (passthrough/automatico/personalizzato/adattivo) +- Iniezione rapida del sistema globale +- Monitoraggio della sessione e rilevamento delle impronte digitali +- Limitazione tariffaria migliorata per account con profili specifici del fornitore +- Modello di interruttore automatico per la resilienza del fornitore +- Protezione gregge antituono con bloccaggio mutex +- Cache di deduplicazione delle richieste basata su firma +- Livello dominio: disponibilità del modello, regole di costo, politica di fallback, politica di blocco +- Persistenza dello stato del dominio (cache write-through SQLite per fallback, budget, blocchi, interruttori automatici) +- Motore di policy per la valutazione centralizzata delle richieste (blocco → budget → fallback) +- Richiedi telemetria con aggregazione della latenza p50/p95/p99 +- ID di correlazione (X-Request-Id) per la traccia end-to-end +- Registrazione del controllo di conformità con rinuncia per chiave API +- Quadro di valutazione per la garanzia della qualità LLM +- Dashboard dell'interfaccia utente di resilienza con stato dell'interruttore automatico in tempo reale +- Provider OAuth modulari (12 moduli individuali in `src/lib/oauth/providers/`) + +Modello runtime primario: + +- I percorsi dell'app Next.js in `src/app/api/*` implementano sia le API del dashboard che le API di compatibilità +- Un core SSE/routing condiviso in `src/sse/*` + `open-sse/*` gestisce l'esecuzione, la traduzione, lo streaming, il fallback e l'utilizzo del provider + +## Ambito e confini + +### Nell'ambito + +- Runtime del gateway locale +- API di gestione della dashboard +- Autenticazione del provider e aggiornamento del token +- Richiedi traduzione e streaming SSE +- Stato locale + persistenza dell'utilizzo +- Orchestrazione opzionale della sincronizzazione cloud + +### Fuori portata + +- Implementazione del servizio cloud dietro `NEXT_PUBLIC_CLOUD_URL` +- SLA/piano di controllo del fornitore esterno al processo locale +- Gli stessi binari CLI esterni (Claude CLI, Codex CLI, ecc.) + +## Contesto del sistema di alto livello + +```mermaid +flowchart LR + subgraph Clients[Developer Clients] + C1[Claude Code] + C2[Codex CLI] + C3[OpenClaw / Droid / Cline / Continue / Roo] + C4[Custom OpenAI-compatible clients] + BROWSER[Browser Dashboard] + end + + subgraph Router[OmniRoute Local Process] + API[V1 Compatibility API\n/v1/*] + DASH[Dashboard + Management API\n/api/*] + CORE[SSE + Translation Core\nopen-sse + src/sse] + DB[(db.json)] + UDB[(usage.json + log.txt)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity] + P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA] + P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible] + end + + subgraph Cloud[Optional Cloud Sync] + CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL] + end + + C1 --> API + C2 --> API + C3 --> API + C4 --> API + BROWSER --> DASH + + API --> CORE + DASH --> DB + CORE --> DB + CORE --> UDB + + CORE --> P1 + CORE --> P2 + CORE --> P3 + + DASH --> CLOUD +``` + +## Componenti runtime principali + +## 1) API e livello di routing (percorsi dell'app Next.js) + +Directory principali: + +- `src/app/api/v1/*` e `src/app/api/v1beta/*` per API di compatibilità +- `src/app/api/*` per le API di gestione/configurazione +- Successivamente riscrive nella mappa `next.config.mjs` `/v1/*` in `/api/v1/*` + +Percorsi di compatibilità importanti: + +- `src/app/api/v1/chat/completions/route.ts` +- `src/app/api/v1/messages/route.ts` +- `src/app/api/v1/responses/route.ts` +- `src/app/api/v1/models/route.ts`: include modelli personalizzati con `custom: true` +- `src/app/api/v1/embeddings/route.ts`: generazione di incorporamenti (6 fornitori) +- `src/app/api/v1/images/generations/route.ts` — generazione di immagini (4+ fornitori incluso Antigravity/Nebius) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts`: chat dedicata per provider +- `src/app/api/v1/providers/[provider]/embeddings/route.ts`: incorporamenti dedicati per provider +- `src/app/api/v1/providers/[provider]/images/generations/route.ts`: immagini dedicate per provider +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Domini di gestione: + +- Autenticazione/impostazioni: `src/app/api/auth/*`, `src/app/api/settings/*` +- Provider/connessioni: `src/app/api/providers*` +- Nodi fornitore: `src/app/api/provider-nodes*` +- Modelli personalizzati: `src/app/api/provider-models` (GET/POST/DELETE) +- Catalogo modelli: `src/app/api/models/catalog` (OTTIENI) +- Configurazione proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Chiavi/alias/combo/prezzi: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Utilizzo: `src/app/api/usage/*` +- Sincronizzazione/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- Aiutanti degli strumenti CLI: `src/app/api/cli-tools/*` +- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT) +- Budget pensato: `src/app/api/settings/thinking-budget` (GET/PUT) +- Richiesta di sistema: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessioni: `src/app/api/sessions` (GET) +- Limiti di velocità: `src/app/api/rate-limits` (GET) +- Resilienza: `src/app/api/resilience` (GET/PATCH): profili dei fornitori, interruttore automatico, stato limite di velocità +- Ripristino della resilienza: `src/app/api/resilience/reset` (POST): ripristina gli interruttori + tempi di recupero +- Statistiche cache: `src/app/api/cache/stats` (OTTIENI/ELIMINA) +- Disponibilità del modello: `src/app/api/models/availability` (GET/POST) +- Telemetria: `src/app/api/telemetry/summary` (OTTIENI) +- Budget: `src/app/api/usage/budget` (OTTIENI/POST) +- Catene di fallback: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Controllo di conformità: `src/app/api/compliance/audit-log` (GET) +- Valutazioni: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Politiche: `src/app/api/policies` (GET/POST) + +## 2) SSE + Nucleo di traduzione + +Principali moduli di flusso: + +- Voce: `src/sse/handlers/chat.ts` +- Orchestrazione principale: `open-sse/handlers/chatCore.ts` +- Adattatori di esecuzione del provider: `open-sse/executors/*` +- Rilevamento formato/configurazione provider: `open-sse/services/provider.ts` +- Analisi/risoluzione del modello: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Logica di fallback dell'account: `open-sse/services/accountFallback.ts` +- Registro delle traduzioni: `open-sse/translator/index.ts` +- Trasformazioni del flusso: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Estrazione/normalizzazione dell'utilizzo: `open-sse/utils/usageTracking.ts` +- Pensa al parser dei tag: `open-sse/utils/thinkTagParser.ts` +- Gestore di incorporamento: `open-sse/handlers/embeddings.ts` +- Incorporamento del registro dei provider: `open-sse/config/embeddingRegistry.ts` +- Gestore di generazione di immagini: `open-sse/handlers/imageGeneration.ts` +- Registro del fornitore di immagini: `open-sse/config/imageRegistry.ts` +- Sanificazione della risposta: `open-sse/handlers/responseSanitizer.ts` +- Normalizzazione del ruolo: `open-sse/services/roleNormalizer.ts` + +Servizi (logica aziendale): + +- Selezione/punteggio dell'account: `open-sse/services/accountSelector.ts` +- Gestione del ciclo di vita del contesto: `open-sse/services/contextManager.ts` +- Applicazione del filtro IP: `open-sse/services/ipFilter.ts` +- Monitoraggio della sessione: `open-sse/services/sessionManager.ts` +- Richiedi deduplicazione: `open-sse/services/signatureCache.ts` +- Inserimento prompt del sistema: `open-sse/services/systemPrompt.ts` +- Gestione intelligente del budget: `open-sse/services/thinkingBudget.ts` +- Routing del modello con caratteri jolly: `open-sse/services/wildcardRouter.ts` +- Gestione dei limiti di velocità: `open-sse/services/rateLimitManager.ts` +- Interruttore automatico: `open-sse/services/circuitBreaker.ts` + +Moduli del livello di dominio: + +- Disponibilità del modello: `src/lib/domain/modelAvailability.ts` +- Regole di costo/budget: `src/lib/domain/costRules.ts` +- Politica di riserva: `src/lib/domain/fallbackPolicy.ts` +- Risolutore combinato: `src/lib/domain/comboResolver.ts` +- Politica di blocco: `src/lib/domain/lockoutPolicy.ts` +- Motore delle politiche: `src/domain/policyEngine.ts` — blocco centralizzato → budget → valutazione fallback +- Catalogo codici errore: `src/lib/domain/errorCodes.ts` +- ID richiesta: `src/lib/domain/requestId.ts` +- Timeout recupero: `src/lib/domain/fetchTimeout.ts` +- Richiedi telemetria: `src/lib/domain/requestTelemetry.ts` +- Conformità/controllo: `src/lib/domain/compliance/index.ts` +- Corridore di valutazione: `src/lib/domain/evalRunner.ts` +- Persistenza dello stato del dominio: `src/lib/db/domainState.ts` — SQLite CRUD per catene di fallback, budget, cronologia dei costi, stato di blocco, interruttori automatici + +Moduli provider OAuth (12 file singoli in `src/lib/oauth/providers/`): + +- Indice del registro: `src/lib/oauth/providers/index.ts` +- Singoli fornitori: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, `qwen.ts`, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Involucro sottile: `src/lib/oauth/providers.ts` — riesporta da singoli moduli + +## 3) Livello di persistenza + +DB di stato primario: + +- `src/lib/localDb.ts` +- file: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` quando impostato, altrimenti `~/.omniroute/db.json`) +- entità: providerConnections, providerNodes, modelAliases, combo, apiKeys, impostazioni, prezzi, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +DB di utilizzo: + +- `src/lib/usageDb.ts` +- file: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- segue la stessa policy di directory di base di `localDb` (`DATA_DIR`, quindi `XDG_CONFIG_HOME/omniroute` quando impostato) +- scomposto in sottomoduli focalizzati: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +DB dello stato del dominio (SQLite): + +- `src/lib/db/domainState.ts`: operazioni CRUD per lo stato del dominio +- Tabelle (create in `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Schema cache write-through: le mappe in memoria sono autorevoli in fase di esecuzione; le mutazioni vengono scritte in modo sincrono su SQLite; lo stato viene ripristinato dal DB all'avvio a freddo + +## 4) Superfici di autenticazione e sicurezza + +- Autenticazione cookie dashboard: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- Generazione/verifica della chiave API: `src/shared/utils/apiKey.ts` +- I segreti del provider sono persistenti nelle voci `providerConnections` +- Supporto proxy in uscita tramite `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurabile per provider o globale) + +## 5) Sincronizzazione nel cloud + +- Inizializzazione pianificazione: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Attività periodica: `src/shared/services/cloudSyncScheduler.ts` +- Percorso di controllo: `src/app/api/sync/cloud/route.ts` + +## Ciclo di vita della richiesta (`/v1/chat/completions`) + +```mermaid +sequenceDiagram + autonumber + participant Client as CLI/SDK Client + participant Route as /api/v1/chat/completions + participant Chat as src/sse/handlers/chat + participant Core as open-sse/handlers/chatCore + participant Model as Model Resolver + participant Auth as Credential Selector + participant Exec as Provider Executor + participant Prov as Upstream Provider + participant Stream as Stream Translator + participant Usage as usageDb + + Client->>Route: POST /v1/chat/completions + Route->>Chat: handleChat(request) + Chat->>Model: parse/resolve model or combo + + alt Combo model + Chat->>Chat: iterate combo models (handleComboChat) + end + + Chat->>Auth: getProviderCredentials(provider) + Auth-->>Chat: active account + tokens/api key + + Chat->>Core: handleChatCore(body, modelInfo, credentials) + Core->>Core: detect source format + Core->>Core: translate request to target format + Core->>Exec: execute(provider, transformedBody) + Exec->>Prov: upstream API call + Prov-->>Exec: SSE/JSON response + Exec-->>Core: response + metadata + + alt 401/403 + Core->>Exec: refreshCredentials() + Exec-->>Core: updated tokens + Core->>Exec: retry request + end + + Core->>Stream: translate/normalize stream to client format + Stream-->>Client: SSE chunks / JSON response + + Stream->>Usage: extract usage + persist history/log +``` + +## Combo + Flusso di fallback dell'account + +```mermaid +flowchart TD + A[Incoming model string] --> B{Is combo name?} + B -- Yes --> C[Load combo models sequence] + B -- No --> D[Single model path] + + C --> E[Try model N] + E --> F[Resolve provider/model] + D --> F + + F --> G[Select account credentials] + G --> H{Credentials available?} + H -- No --> I[Return provider unavailable] + H -- Yes --> J[Execute request] + + J --> K{Success?} + K -- Yes --> L[Return response] + K -- No --> M{Fallback-eligible error?} + + M -- No --> N[Return error] + M -- Yes --> O[Mark account unavailable cooldown] + O --> P{Another account for provider?} + P -- Yes --> G + P -- No --> Q{In combo with next model?} + Q -- Yes --> E + Q -- No --> R[Return all unavailable] +``` + +Le decisioni di fallback sono guidate da `open-sse/services/accountFallback.ts` utilizzando codici di stato ed euristica dei messaggi di errore. + +## Ciclo di vita dell'onboarding OAuth e dell'aggiornamento dei token + +```mermaid +sequenceDiagram + autonumber + participant UI as Dashboard UI + participant OAuth as /api/oauth/[provider]/[action] + participant ProvAuth as Provider Auth Server + participant DB as localDb + participant Test as /api/providers/[id]/test + participant Exec as Provider Executor + + UI->>OAuth: GET authorize or device-code + OAuth->>ProvAuth: create auth/device flow + ProvAuth-->>OAuth: auth URL or device code payload + OAuth-->>UI: flow data + + UI->>OAuth: POST exchange or poll + OAuth->>ProvAuth: token exchange/poll + ProvAuth-->>OAuth: access/refresh tokens + OAuth->>DB: createProviderConnection(oauth data) + OAuth-->>UI: success + connection id + + UI->>Test: POST /api/providers/[id]/test + Test->>Exec: validate credentials / optional refresh + Exec-->>Test: valid or refreshed token info + Test->>DB: update status/tokens/errors + Test-->>UI: validation result +``` + +L'aggiornamento durante il traffico in tempo reale viene eseguito all'interno di `open-sse/handlers/chatCore.ts` tramite l'esecutore `refreshCredentials()`. + +## Ciclo di vita della sincronizzazione cloud (Abilita/Sincronizza/Disabilita) + +```mermaid +sequenceDiagram + autonumber + participant UI as Endpoint Page UI + participant Sync as /api/sync/cloud + participant DB as localDb + participant Cloud as External Cloud Sync + participant Claude as ~/.claude/settings.json + + UI->>Sync: POST action=enable + Sync->>DB: set cloudEnabled=true + Sync->>DB: ensure API key exists + Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys) + Cloud-->>Sync: sync result + Sync->>Cloud: GET /{machineId}/v1/verify + Sync-->>UI: enabled + verification status + + UI->>Sync: POST action=sync + Sync->>Cloud: POST /sync/{machineId} + Cloud-->>Sync: remote data + Sync->>DB: update newer local tokens/status + Sync-->>UI: synced + + UI->>Sync: POST action=disable + Sync->>DB: set cloudEnabled=false + Sync->>Cloud: DELETE /sync/{machineId} + Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed) + Sync-->>UI: disabled +``` + +La sincronizzazione periodica viene attivata da `CloudSyncScheduler` quando il cloud è abilitato. + +## Modello dei dati e mappa di archiviazione + +```mermaid +erDiagram + SETTINGS ||--o{ PROVIDER_CONNECTION : controls + PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider + PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage + + SETTINGS { + boolean cloudEnabled + number stickyRoundRobinLimit + boolean requireLogin + string password_hash + string fallbackStrategy + json rateLimitDefaults + json providerProfiles + } + + PROVIDER_CONNECTION { + string id + string provider + string authType + string name + number priority + boolean isActive + string apiKey + string accessToken + string refreshToken + string expiresAt + string testStatus + string lastError + string rateLimitedUntil + json providerSpecificData + } + + PROVIDER_NODE { + string id + string type + string name + string prefix + string apiType + string baseUrl + } + + MODEL_ALIAS { + string alias + string targetModel + } + + COMBO { + string id + string name + string[] models + } + + API_KEY { + string id + string name + string key + string machineId + } + + USAGE_ENTRY { + string provider + string model + number prompt_tokens + number completion_tokens + string connectionId + string timestamp + } + + CUSTOM_MODEL { + string id + string name + string providerId + } + + PROXY_CONFIG { + string global + json providers + } + + IP_FILTER { + string mode + string[] allowlist + string[] blocklist + } + + THINKING_BUDGET { + string mode + number customBudget + string effortLevel + } + + SYSTEM_PROMPT { + boolean enabled + string prompt + string position + } +``` + +File di archiviazione fisica: + +- stato principale: `${DATA_DIR}/db.json` (o `$XDG_CONFIG_HOME/omniroute/db.json` quando impostato, altrimenti `~/.omniroute/db.json`) +- statistiche di utilizzo: `${DATA_DIR}/usage.json` +- righe di registro della richiesta: `${DATA_DIR}/log.txt` +- sessioni di debug traduttore/richiesta opzionali: `/logs/...` + +## Topologia di distribuzione + +```mermaid +flowchart LR + subgraph LocalHost[Developer Host] + CLI[CLI Tools] + Browser[Dashboard Browser] + end + + subgraph ContainerOrProcess[OmniRoute Runtime] + Next[Next.js Server\nPORT=20128] + Core[SSE Core + Executors] + MainDB[(db.json)] + UsageDB[(usage.json/log.txt)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Mappatura dei moduli (critica per la decisione) + +### Itinerario e moduli API + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API di compatibilità +- `src/app/api/v1/providers/[provider]/*`: percorsi dedicati per provider (chat, incorporamenti, immagini) +- `src/app/api/providers*`: CRUD del fornitore, convalida, test +- `src/app/api/provider-nodes*`: gestione personalizzata dei nodi compatibili +- `src/app/api/provider-models`: gestione del modello personalizzato (CRUD) +- `src/app/api/models/catalog`: API del catalogo modelli completo (tutti i tipi raggruppati per fornitore) +- `src/app/api/oauth/*`: flussi OAuth/codice dispositivo +- `src/app/api/keys*`: ciclo di vita della chiave API locale +- `src/app/api/models/alias`: gestione alias +- `src/app/api/combos*`: gestione combo fallback +- `src/app/api/pricing`: il prezzo sostituisce il calcolo dei costi +- `src/app/api/settings/proxy`: configurazione proxy (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: test di connettività proxy in uscita (POST) +- `src/app/api/usage/*`: API di utilizzo e log +- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronizzazione cloud e aiutanti rivolti al cloud +- `src/app/api/cli-tools/*`: scrittori/controllori di configurazione CLI locale +- `src/app/api/settings/ip-filter`: lista consentita/lista bloccata IP (GET/PUT) +- `src/app/api/settings/thinking-budget`: configurazione del budget del token pensante (GET/PUT) +- `src/app/api/settings/system-prompt`: prompt di sistema globale (GET/PUT) +- `src/app/api/sessions`: elenco sessioni attive (GET) +- `src/app/api/rate-limits`: stato limite tariffa per account (GET) + +### Nucleo di routing ed esecuzione + +- `src/sse/handlers/chat.ts`: analisi delle richieste, gestione delle combo, ciclo di selezione dell'account +- `open-sse/handlers/chatCore.ts`: traduzione, invio dell'esecutore, gestione di nuovi tentativi/aggiornamenti, impostazione del flusso +- `open-sse/executors/*`: comportamento di rete e formato specifico del provider + +### Registro di traduzione e convertitori di formato + +- `open-sse/translator/index.ts`: registro e orchestrazione dei traduttori +- Richiedi traduttori: `open-sse/translator/request/*` +- Traduttori di risposta: `open-sse/translator/response/*` +- Costanti di formato: `open-sse/translator/formats.ts` + +### Persistenza + +- `src/lib/localDb.ts`: configurazione/stato persistente +- `src/lib/usageDb.ts`: cronologia di utilizzo e registri delle richieste in sequenza + +## Copertura dell'esecutore del provider (modello strategico) + +Ogni provider dispone di un esecutore specializzato che estende `BaseExecutor` (in `open-sse/executors/base.ts`), che fornisce la creazione di URL, la costruzione di intestazioni, nuovi tentativi con backoff esponenziale, hook di aggiornamento delle credenziali e il metodo di orchestrazione `execute()`. + +| Esecutore testamentario | Fornitore/i | Movimentazione speciale | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configurazione URL/intestazione dinamica per provider | +| `AntigravityExecutor` | Google Antigravità | ID progetto/sessione personalizzati, analisi Riprova dopo | +| `CodexExecutor` | Codice OpenAI | Inserisce istruzioni di sistema, forza lo sforzo di ragionamento | +| `CursorExecutor` | Cursore IDE | Protocollo ConnectRPC, codifica Protobuf, firma della richiesta tramite checksum | +| `GithubExecutor` | Copilota GitHub | Aggiornamento del token Copilot, intestazioni che imitano VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binario AWS EventStream → conversione SSE | +| `GeminiCLIExecutor` | Gemelli CLI | Ciclo di aggiornamento del token OAuth di Google | + +Tutti gli altri provider (inclusi i nodi compatibili personalizzati) utilizzano `DefaultExecutor`. + +## Matrice di compatibilità del fornitore + +| Fornitore | Formato | Aut. | Flusso | Non streaming | Aggiornamento token | API di utilizzo | +| --------------------- | --------------- | ----------------------- | ---------------- | ------------- | ------------------- | ------------------------ | +| Claudio | claude | Chiave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Solo amministratore | +| Gemelli | gemelli | Chiave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Console cloud | +| Gemelli CLI | gemelli-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Console cloud | +| Antigravità | antigravità | OAuth | ✅ | ✅ | ✅ | ✅ API quota completa | +| OpenAI | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Codice | risposte-openai | OAuth | ✅ forzato | ❌ | ✅ | ✅ Limiti tariffari | +| Copilota GitHub | openai | OAuth + token copilota | ✅ | ✅ | ✅ | ✅Istantanee delle quote | +| Cursore | cursore | Checksum personalizzato | ✅ | ✅ | ❌ | ❌ | +| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limiti di utilizzo | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Su richiesta | +| iFlow | openai | OAuth (base) | ✅ | ✅ | ✅ | ⚠️ Su richiesta | +| OpenRouter | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Ricerca profonda | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Maestrale | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Perplessità | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Insieme AI | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Fuochi d'artificio AI | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Cerebri | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| Coerenza | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | Chiave API | ✅ | ✅ | ❌ | ❌ | + +## Copertura della traduzione del formato + +I formati sorgente rilevati includono: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +I formati di destinazione includono: + +- Chat/risposte OpenAI +- Claudio +- Busta Gemini/Gemini-CLI/Antigravità +- Kiro +- Cursore + +Le traduzioni utilizzano **OpenAI come formato hub**: tutte le conversioni passano attraverso OpenAI come formato intermedio: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +Le traduzioni vengono selezionate dinamicamente in base alla forma del payload di origine e al formato di destinazione del provider. + +Ulteriori livelli di elaborazione nella pipeline di traduzione: + +- **Sanificazione delle risposte**: rimuove i campi non standard dalle risposte in formato OpenAI (sia in streaming che non in streaming) per garantire la rigorosa conformità dell'SDK +- **Normalizzazione del ruolo**: converte `developer` → `system` per target non OpenAI; unisce `system` → `user` per i modelli che rifiutano il ruolo di sistema (GLM, ERNIE) +- **Estrazione tag Think**: analizza i blocchi `...` dal contenuto nel campo `reasoning_content` +- **Output strutturato**: converte OpenAI `response_format.json_schema` in `responseMimeType` di Gemini + `responseSchema` + +## Endpoint API supportati + +| Punto finale | Formato | Gestore | +| -------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ | +| `POST /v1/chat/completions` | Chatta OpenAI | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Messaggi di Claude | Stesso gestore (rilevato automaticamente) | +| `POST /v1/responses` | Risposte OpenAI | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | Incorporamenti OpenAI | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Elenco dei modelli | Percorso API | +| `POST /v1/images/generations` | Immagini OpenAI | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Elenco dei modelli | Percorso API | +| `POST /v1/providers/{provider}/chat/completions` | Chatta OpenAI | Dedicato per provider con convalida del modello | +| `POST /v1/providers/{provider}/embeddings` | Incorporamenti OpenAI | Dedicato per provider con convalida del modello | +| `POST /v1/providers/{provider}/images/generations` | Immagini OpenAI | Dedicato per provider con convalida del modello | +| `POST /v1/messages/count_tokens` | Conteggio gettoni Claude | Percorso API | +| `GET /v1/models` | Elenco modelli OpenAI | Percorso API (chat + incorporamento + immagine + modelli personalizzati) | +| `GET /api/models/catalog` | Catalogo | Tutti i modelli raggruppati per fornitore + tipo | +| `POST /v1beta/models/*:streamGenerateContent` | Nativo dei Gemelli | Percorso API | +| `GET/PUT/DELETE /api/settings/proxy` | Configurazione proxy | Configurazione proxy di rete | +| `POST /api/settings/proxy/test` | Connettività proxy | Endpoint di test di integrità/connettività proxy | +| `GET/POST/DELETE /api/provider-models` | Modelli personalizzati | Gestione modelli personalizzati per fornitore | + +## Gestore di bypass + +Il gestore di bypass (`open-sse/utils/bypassHandler.ts`) intercetta le richieste "usa e getta" note dalla CLI di Claude (ping di riscaldamento, estrazioni di titoli e conteggi di token) e restituisce una **risposta falsa** senza consumare token del provider upstream. Questo viene attivato solo quando `User-Agent` contiene `claude-cli`. + +## Richiedi la pipeline del registratore + +Il logger delle richieste (`open-sse/utils/requestLogger.ts`) fornisce una pipeline di registrazione del debug in 7 fasi, disabilitata per impostazione predefinita, abilitata tramite `ENABLE_REQUEST_LOGS=true`: + +``` +1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json +→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt +``` + +I file vengono scritti in `/logs//` per ogni sessione di richiesta. + +## Modalità di fallimento e resilienza + +## 1) Disponibilità dell'account/fornitore + +- Tempo di recupero dell'account del provider in caso di errori temporanei/velocità/autenticazione +- fallback dell'account prima di fallire la richiesta +- fallback del modello combinato quando il percorso del modello/provider corrente è esaurito + +## 2) Scadenza del token + +- controllo preliminare e aggiornamento con nuovo tentativo per i provider aggiornabili +- Nuovo tentativo 401/403 dopo il tentativo di aggiornamento nel percorso principale + +## 3) Sicurezza dello streaming + +- controller di flusso in grado di riconoscere la disconnessione +- flusso di traduzione con scarico di fine flusso e gestione `[DONE]` +- fallback della stima dell'utilizzo quando mancano i metadati di utilizzo del provider + +## 4) Degrado della sincronizzazione cloud + +- Sono emersi errori di sincronizzazione ma il runtime locale continua +- Lo scheduler ha una logica che consente di riprovare, ma l'esecuzione periodica attualmente chiama la sincronizzazione a tentativo singolo per impostazione predefinita + +## 5) Integrità dei dati + +- Migrazione/riparazione della forma DB per chiavi mancanti +- protezioni di reimpostazione JSON corrotte per localDb e UsageDb + +## Osservabilità e segnali operativi + +Origini della visibilità in runtime: + +- registri della console da `src/sse/utils/logger.ts` +- aggregati di utilizzo per richiesta in `usage.json` +- accesso testuale sullo stato della richiesta `log.txt` +- log di richiesta/traduzione approfonditi opzionali in `logs/` quando `ENABLE_REQUEST_LOGS=true` +- Endpoint di utilizzo del dashboard (`/api/usage/*`) per il consumo dell'interfaccia utente + +## Confini sensibili alla sicurezza + +- Il segreto JWT (`JWT_SECRET`) protegge la verifica/firma dei cookie della sessione del dashboard +- Il fallback della password iniziale (`INITIAL_PASSWORD`, predefinito `123456`) deve essere sovrascritto nelle distribuzioni reali +- Il segreto HMAC della chiave API (`API_KEY_SECRET`) protegge il formato della chiave API locale generata +- I segreti del provider (chiavi/token API) vengono mantenuti nel DB locale e devono essere protetti a livello di file system +- Gli endpoint di sincronizzazione cloud si basano sull'autenticazione della chiave API e sulla semantica dell'ID macchina + +## Matrice di ambiente e runtime + +Variabili d'ambiente utilizzate attivamente dal codice: + +- App/autenticazione: `JWT_SECRET`, `INITIAL_PASSWORD` +- Spazio di archiviazione: `DATA_DIR` +- Comportamento del nodo compatibile: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Override opzionale della base di archiviazione (Linux/macOS quando `DATA_DIR` non impostato): `XDG_CONFIG_HOME` +- Hashing di sicurezza: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Registrazione: `ENABLE_REQUEST_LOGS` +- URL di sincronizzazione/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Proxy in uscita: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e varianti minuscole +- Flag funzionalità SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Supporti piattaforma/runtime (non configurazione specifica dell'app): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Note architettoniche conosciute + +1. `usageDb` e `localDb` ora condividono la stessa policy di directory di base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) con la migrazione dei file legacy. +2. `/api/v1/route.ts` restituisce un elenco di modelli statici e non è la fonte principale dei modelli utilizzata da `/v1/models`. +3. Il registro delle richieste scrive intestazioni/corpo completi quando abilitato; considera la directory dei log come sensibile. +4. Il comportamento del cloud dipende dalla corretta `NEXT_PUBLIC_BASE_URL` e dalla raggiungibilità dell'endpoint cloud. +5. La directory `open-sse/` viene pubblicata come `@omniroute/open-sse` **pacchetto area di lavoro npm**. Il codice sorgente lo importa tramite `@omniroute/open-sse/...` (risolto da Next.js `transpilePackages`). I percorsi dei file in questo documento utilizzano ancora il nome della directory `open-sse/` per coerenza. +6. I grafici nel dashboard utilizzano **Recharts** (basati su SVG) per visualizzazioni analitiche accessibili e interattive (grafici a barre sull'utilizzo del modello, tabelle di suddivisione dei fornitori con percentuali di successo). +7. I test E2E utilizzano **Playwright** (`tests/e2e/`), eseguiti tramite `npm run test:e2e`. I test unitari utilizzano **Node.js test runner** (`tests/unit/`), eseguiti tramite `npm run test:plan3`. Il codice sorgente in `src/` è **TypeScript** (`.ts`/`.tsx`); l'area di lavoro `open-sse/` rimane JavaScript (`.js`). +8. La pagina Impostazioni è organizzata in 5 schede: Sicurezza, Routing (6 strategie globali: riempimento prima, round robin, p2c, casuale, meno utilizzato, ottimizzato in termini di costi), Resilienza (limiti di velocità modificabili, interruttore automatico, policy), AI (budget pensato, prompt di sistema, cache dei prompt), Avanzate (proxy). + +## Lista di controllo per la verifica operativa + +- Costruisci dalla fonte: `npm run build` +- Crea immagine Docker: `docker build -t omniroute .` +- Avviare il servizio e verificare: +- `GET /api/settings` +- `GET /api/v1/models` +- L'URL di base di destinazione della CLI deve essere `http://:20128/v1` quando `PORT=20128` diff --git a/docs/i18n/it/CODEBASE_DOCUMENTATION.md b/docs/i18n/it/CODEBASE_DOCUMENTATION.md new file mode 100644 index 00000000..f702ddd0 --- /dev/null +++ b/docs/i18n/it/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute: documentazione della base di codice + +🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) + +> Una guida completa e adatta ai principianti al router proxy AI multi-provider **omniroute**. + +--- + +## 1. Che cos'è omniroute? + +omniroute è un **router proxy** che si trova tra i client AI (Claude CLI, Codex, Cursor IDE, ecc.) e i fornitori di AI (Anthropic, Google, OpenAI, AWS, GitHub, ecc.). Risolve un grosso problema: + +> **Client IA diversi parlano "linguaggi" diversi (formati API) e anche fornitori di IA diversi si aspettano "linguaggi" diversi.** omniroute traduce automaticamente tra loro. + +Pensatelo come un traduttore universale alle Nazioni Unite: qualsiasi delegato può parlare qualsiasi lingua e il traduttore la converte per qualsiasi altro delegato. + +--- + +## 2. Panoramica dell'architettura + +```mermaid +graph LR + subgraph Clients + A[Claude CLI] + B[Codex] + C[Cursor IDE] + D[OpenAI-compatible] + end + + subgraph omniroute + E[Handler Layer] + F[Translator Layer] + G[Executor Layer] + H[Services Layer] + end + + subgraph Providers + I[Anthropic Claude] + J[Google Gemini] + K[OpenAI / Codex] + L[GitHub Copilot] + M[AWS Kiro] + N[Antigravity] + O[Cursor API] + end + + A --> E + B --> E + C --> E + D --> E + E --> F + F --> G + G --> I + G --> J + G --> K + G --> L + G --> M + G --> N + G --> O + H -.-> E + H -.-> G +``` + +### Principio fondamentale: traduzione Hub-and-Spoke + +Tutte le traduzioni dei formati passano attraverso il **formato OpenAI come hub**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +Ciò significa che hai bisogno solo di **N traduttori** (uno per formato) invece di **N²** (ogni coppia). + +--- + +## 3. Struttura del progetto + +``` +omniroute/ +├── open-sse/ ← Core proxy library (portable, framework-agnostic) +│ ├── index.js ← Main entry point, exports everything +│ ├── config/ ← Configuration & constants +│ ├── executors/ ← Provider-specific request execution +│ ├── handlers/ ← Request handling orchestration +│ ├── services/ ← Business logic (auth, models, fallback, usage) +│ ├── translator/ ← Format translation engine +│ │ ├── request/ ← Request translators (8 files) +│ │ ├── response/ ← Response translators (7 files) +│ │ └── helpers/ ← Shared translation utilities (6 files) +│ └── utils/ ← Utility functions +├── src/ ← Application layer (Express/Worker runtime) +│ ├── app/ ← Web UI, API routes, middleware +│ ├── lib/ ← Database, auth, and shared library code +│ ├── mitm/ ← Man-in-the-middle proxy utilities +│ ├── models/ ← Database models +│ ├── shared/ ← Shared utilities (wrappers around open-sse) +│ ├── sse/ ← SSE endpoint handlers +│ └── store/ ← State management +├── data/ ← Runtime data (credentials, logs) +│ └── provider-credentials.json (external credentials override, gitignored) +└── tester/ ← Test utilities +``` + +--- + +## 4. Analisi modulo per modulo + +### 4.1 Configurazione (`open-sse/config/`) + +L'**unica fonte di verità** per la configurazione di tutti i provider. + +| File | Scopo | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | Oggetto `PROVIDERS` con URL di base, credenziali OAuth (predefinite), intestazioni e prompt di sistema predefiniti per ogni provider. Definisce anche `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` e `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Carica le credenziali esterne da `data/provider-credentials.json` e le unisce alle impostazioni predefinite hardcoded in `PROVIDERS`. Mantiene i segreti fuori dal controllo del codice sorgente mantenendo la compatibilità con le versioni precedenti. | +| `providerModels.ts` | Registro centrale del modello: alias del fornitore delle mappe → ID del modello. Funzioni come `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | Istruzioni di sistema inserite nelle richieste del Codex (vincoli di modifica, regole sandbox, politiche di approvazione). | +| `defaultThinkingSignature.ts` | Firme "pensanti" predefinite per i modelli Claude e Gemini. | +| `ollamaModels.ts` | Definizione di schemi per modelli Ollama locali (nome, dimensione, famiglia, quantizzazione). | + +#### Flusso di caricamento delle credenziali + +```mermaid +flowchart TD + A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"] + B --> C{"data/provider-credentials.json\nexists?"} + C -->|Yes| D["credentialLoader reads JSON"] + C -->|No| E["Use hardcoded defaults"] + D --> F{"For each provider in JSON"} + F --> G{"Provider exists\nin PROVIDERS?"} + G -->|No| H["Log warning, skip"] + G -->|Yes| I{"Value is object?"} + I -->|No| J["Log warning, skip"] + I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"] + K --> F + H --> F + J --> F + F -->|Done| L["PROVIDERS ready with\nmerged credentials"] + E --> L +``` + +--- + +### 4.2 Esecutori (`open-sse/executors/`) + +Gli esecutori incapsulano la **logica specifica del provider** utilizzando il **Strategy Pattern**. Ogni esecutore sovrascrive i metodi di base secondo necessità. + +```mermaid +classDiagram + class BaseExecutor { + +buildUrl(model, stream, options) + +buildHeaders(credentials, stream, body) + +transformRequest(body, model, stream, credentials) + +execute(url, options) + +shouldRetry(status, error) + +refreshCredentials(credentials, log) + } + + class DefaultExecutor { + +refreshCredentials() + } + + class AntigravityExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +shouldRetry() + +refreshCredentials() + } + + class CursorExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseResponse() + +generateChecksum() + } + + class KiroExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseEventStream() + +refreshCredentials() + } + + BaseExecutor <|-- DefaultExecutor + BaseExecutor <|-- AntigravityExecutor + BaseExecutor <|-- CursorExecutor + BaseExecutor <|-- KiroExecutor + BaseExecutor <|-- CodexExecutor + BaseExecutor <|-- GeminiCLIExecutor + BaseExecutor <|-- GithubExecutor +``` + +| Esecutore testamentario | Fornitore | Specializzazioni chiave | +| ----------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Base astratta: creazione di URL, intestazioni, logica dei tentativi, aggiornamento delle credenziali | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Aggiornamento del token OAuth generico per i provider standard | +| `antigravity.ts` | Codice Google Cloud | Generazione ID progetto/sessione, fallback multi-URL, nuovi tentativi di analisi personalizzati dai messaggi di errore ("reimposta dopo 2h7m23s") | +| `cursor.ts` | Cursore IDE | **Più complesso**: autenticazione checksum SHA-256, codifica della richiesta Protobuf, EventStream binario → Analisi della risposta SSE | +| `codex.ts` | Codice OpenAI | Inserisce istruzioni di sistema, gestisce i livelli di pensiero, rimuove i parametri non supportati | +| `gemini-cli.ts` | CLI di Google Gemini | Creazione di URL personalizzati (`streamGenerateContent`), aggiornamento del token OAuth di Google | +| `github.ts` | Copilota GitHub | Sistema a doppio token (GitHub OAuth + token Copilot), intestazione VSCode che imita | +| `kiro.ts` | AWS CodeWhisperer | Analisi binaria AWS EventStream, frame di eventi AMZN, stima dei token | +| `index.ts` | — | Fabbrica: nome del provider delle mappe → classe dell'esecutore, con fallback predefinito | + +--- + +### 4.3 Gestori (`open-sse/handlers/`) + +Il **livello di orchestrazione**: coordina la traduzione, l'esecuzione, lo streaming e la gestione degli errori. + +| File | Scopo | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Orchestratore centrale** (~600 linee). Gestisce il ciclo di vita completo della richiesta: rilevamento del formato → traduzione → invio dell'esecutore → risposta in streaming/non streaming → aggiornamento del token → gestione degli errori → registrazione dell'utilizzo. | +| `responsesHandler.ts` | Adattatore per l'API Responses di OpenAI: converte il formato delle risposte → Completamenti chat → invia a `chatCore` → riconverte SSE nel formato delle risposte. | +| `embeddings.ts` | Gestore della generazione di incorporamento: risolve il modello di incorporamento → provider, invia all'API del provider, restituisce una risposta di incorporamento compatibile con OpenAI. Supporta più di 6 fornitori. | +| `imageGeneration.ts` | Gestore di generazione di immagini: risolve il modello di immagine → provider, supporta le modalità compatibili con OpenAI, Gemini-image (Antigravity) e fallback (Nebius). Restituisce immagini base64 o URL. | + +#### Ciclo di vita della richiesta (chatCore.ts) + +```mermaid +sequenceDiagram + participant Client + participant chatCore + participant Translator + participant Executor + participant Provider + + Client->>chatCore: Request (any format) + chatCore->>chatCore: Detect source format + chatCore->>chatCore: Check bypass patterns + chatCore->>chatCore: Resolve model & provider + chatCore->>Translator: Translate request (source → OpenAI → target) + chatCore->>Executor: Get executor for provider + Executor->>Executor: Build URL, headers, transform request + Executor->>Executor: Refresh credentials if needed + Executor->>Provider: HTTP fetch (streaming or non-streaming) + + alt Streaming + Provider-->>chatCore: SSE stream + chatCore->>chatCore: Pipe through SSE transform stream + Note over chatCore: Transform stream translates
each chunk: target → OpenAI → source + chatCore-->>Client: Translated SSE stream + else Non-streaming + Provider-->>chatCore: JSON response + chatCore->>Translator: Translate response + chatCore-->>Client: Translated JSON + end + + alt Error (401, 429, 500...) + chatCore->>Executor: Retry with credential refresh + chatCore->>chatCore: Account fallback logic + end +``` + +--- + +### 4.4 Servizi (`open-sse/services/`) + +Logica di business che supporta i gestori e gli esecutori. + +| File | Scopo | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `provider.ts` | **Rilevamento formato** (`detectFormat`): analizza la struttura del corpo della richiesta per identificare i formati Claude/OpenAI/Gemini/Antigravity/Responses (include l'euristica `max_tokens` per Claude). Inoltre: creazione di URL, creazione di intestazioni, normalizzazione della configurazione del pensiero. Supporta i provider dinamici `openai-compatible-*` e `anthropic-compatible-*`. | +| `model.ts` | Analisi delle stringhe del modello (`claude/model-name` → `{provider: "claude", model: "model-name"}`), risoluzione degli alias con rilevamento delle collisioni, sanificazione dell'input (rifiuta i caratteri di controllo/attraversamento del percorso) e risoluzione delle informazioni del modello con supporto getter di alias asincrono. | +| `accountFallback.ts` | Gestione dei limiti di velocità: backoff esponenziale (1s → 2s → 4s → max 2min), gestione del cooldown dell'account, classificazione degli errori (quali errori attivano il fallback e quali no). | +| `tokenRefresh.ts` | Aggiornamento del token OAuth per **ogni provider**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (doppio token OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Include cache di deduplicazione delle promesse in volo e tentativi con backoff esponenziale. | +| `combo.ts` | **Modelli combo**: catene di modelli fallback. Se il modello A fallisce con un errore idoneo al fallback, prova il modello B, poi C, ecc. Restituisce i codici di stato upstream effettivi. | +| `usage.ts` | Recupera i dati sulle quote/utilizzo dalle API del provider (quote GitHub Copilot, quote del modello Antigravity, limiti di velocità del Codex, suddivisioni sull'utilizzo di Kiro, impostazioni di Claude). | +| `accountSelector.ts` | Selezione intelligente dell'account con algoritmo di punteggio: considera la priorità, lo stato di salute, la posizione nel round robin e lo stato di recupero per scegliere l'account ottimale per ogni richiesta. | +| `contextManager.ts` | Gestione del ciclo di vita del contesto della richiesta: crea e tiene traccia degli oggetti di contesto per richiesta con metadati (ID della richiesta, timestamp, informazioni sul provider) per il debug e il logging. | +| `ipFilter.ts` | Controllo degli accessi basato su IP: supporta le modalità lista consentita e lista bloccata. Convalida l'IP del client rispetto alle regole configurate prima di elaborare le richieste API. | +| `sessionManager.ts` | Tracciamento delle sessioni con l'impronta digitale del client: tiene traccia delle sessioni attive utilizzando identificatori client con hash, monitora i conteggi delle richieste e fornisce metriche di sessione. | +| `signatureCache.ts` | Cache di deduplicazione basata sulla firma: impedisce le richieste duplicate memorizzando nella cache le firme delle richieste recenti e restituendo risposte memorizzate nella cache per richieste identiche entro un intervallo di tempo. | +| `systemPrompt.ts` | Iniezione di prompt di sistema globale: antepone o accoda un prompt di sistema configurabile a tutte le richieste, con gestione della compatibilità per provider. | +| `thinkingBudget.ts` | Gestione del budget dei token di ragionamento: supporta le modalità passthrough, automatica (configurazione del pensiero a strisce), personalizzata (budget fisso) e adattiva (a scala di complessità) per il controllo dei token di pensiero/ragionamento. | +| `wildcardRouter.ts` | Routing dei modelli di caratteri jolly: risolve i modelli di caratteri jolly (ad esempio, `*/claude-*`) in coppie provider/modello concrete in base alla disponibilità e alla priorità. | + +#### Deduplicazione aggiornamento token + +```mermaid +sequenceDiagram + participant R1 as Request 1 + participant R2 as Request 2 + participant Cache as refreshPromiseCache + participant OAuth as OAuth Provider + + R1->>Cache: getAccessToken("gemini", token) + Cache->>Cache: No in-flight promise + Cache->>OAuth: Start refresh + R2->>Cache: getAccessToken("gemini", token) + Cache->>Cache: Found in-flight promise + Cache-->>R2: Return existing promise + OAuth-->>Cache: New access token + Cache-->>R1: New access token + Cache-->>R2: Same access token (shared) + Cache->>Cache: Delete cache entry +``` + +#### Macchina a stati di fallback dell'account + +```mermaid +stateDiagram-v2 + [*] --> Active + Active --> Error: Request fails (401/429/500) + Error --> Cooldown: Apply backoff + Cooldown --> Active: Cooldown expires + Active --> Active: Request succeeds (reset backoff) + + state Error { + [*] --> ClassifyError + ClassifyError --> ShouldFallback: Rate limit / Auth / Transient + ClassifyError --> NoFallback: 400 Bad Request + } + + state Cooldown { + [*] --> ExponentialBackoff + ExponentialBackoff: Level 0 = 1s + ExponentialBackoff: Level 1 = 2s + ExponentialBackoff: Level 2 = 4s + ExponentialBackoff: Max = 2min + } +``` + +#### Catena modello combinato + +```mermaid +flowchart LR + A["Request with\ncombo model"] --> B["Model A"] + B -->|"2xx Success"| C["Return response"] + B -->|"429/401/500"| D{"Fallback\neligible?"} + D -->|Yes| E["Model B"] + D -->|No| F["Return error"] + E -->|"2xx Success"| C + E -->|"429/401/500"| G{"Fallback\neligible?"} + G -->|Yes| H["Model C"] + G -->|No| F + H -->|"2xx Success"| C + H -->|"Fail"| I["All failed →\nReturn last status"] +``` + +--- + +### 4.5 Traduttore (`open-sse/translator/`) + +Il **motore di traduzione dei formati** che utilizza un sistema di plugin autoregistranti. + +#### Architettura + +```mermaid +graph TD + subgraph "Request Translation" + A["Claude → OpenAI"] + B["Gemini → OpenAI"] + C["Antigravity → OpenAI"] + D["OpenAI Responses → OpenAI"] + E["OpenAI → Claude"] + F["OpenAI → Gemini"] + G["OpenAI → Kiro"] + H["OpenAI → Cursor"] + end + + subgraph "Response Translation" + I["Claude → OpenAI"] + J["Gemini → OpenAI"] + K["Kiro → OpenAI"] + L["Cursor → OpenAI"] + M["OpenAI → Claude"] + N["OpenAI → Antigravity"] + O["OpenAI → Responses"] + end +``` + +| Elenco | File | Descrizione | +| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 traduttori | Converti corpi di richiesta tra formati. Ogni file si registra automaticamente tramite `register(from, to, fn)` al momento dell'importazione. | +| `response/` | 7 traduttori | Converti blocchi di risposta in streaming tra formati. Gestisce tipi di eventi SSE, blocchi di pensiero, chiamate a strumenti. | +| `helpers/` | 6 aiutanti | Utilità condivise: `claudeHelper` (estrazione prompt di sistema, configurazione pensiero), `geminiHelper` (mappatura di parti/contenuti), `openaiHelper` (filtro formato), `toolCallHelper` (generazione ID, inserimento risposta mancante), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Motore di traduzione: `translateRequest()`, `translateResponse()`, gestione dello stato, registro. | +| `formats.ts` | — | Costanti di formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | + +#### Progettazione chiave: plugin autoregistranti + +```javascript +// Each translator file calls register() on import: +import { register } from "../index.js"; +register("claude", "openai", translateClaudeToOpenAI); + +// The index.js imports all translator files, triggering registration: +import "./request/claude-to-openai.js"; // ← self-registers +``` + +--- + +### 4.6 Utilità (`open-sse/utils/`) + +| File | Scopo | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `error.ts` | Creazione di risposte agli errori (formato compatibile con OpenAI), analisi degli errori upstream, estrazione del tempo di tentativo Antigravity dai messaggi di errore, streaming degli errori SSE. | +| `stream.ts` | **SSE Transform Stream**: la pipeline di streaming principale. Due modalità: `TRANSLATE` (traduzione del formato completo) e `PASSTHROUGH` (normalizza + estrai l'utilizzo). Gestisce il buffering dei blocchi, la stima dell'utilizzo, il monitoraggio della lunghezza del contenuto. Le istanze del codificatore/decodificatore per flusso evitano lo stato condiviso. | +| `streamHelpers.ts` | Utilità SSE di basso livello: `parseSSELine` (tollerante agli spazi bianchi), `hasValuableContent` (filtra blocchi vuoti per OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serializzazione SSE compatibile con il formato con `perf_metrics` pulizia). | +| `usageTracking.ts` | Estrazione dell'utilizzo dei token da qualsiasi formato (Claude/OpenAI/Gemini/Responses), stima con rapporti separati strumento/messaggio caratteri per token, aggiunta buffer (margine di sicurezza di 2000 token), filtraggio dei campi specifici del formato, registrazione della console con colori ANSI. | +| `requestLogger.ts` | Registrazione delle richieste basata su file (attivazione tramite `ENABLE_REQUEST_LOGS=true`). Crea cartelle di sessione con file numerati: `1_req_client.json` → `7_res_client.txt`. Tutto l'I/O è asincrono (fire-and-forget). Maschera le intestazioni riservate. | +| `bypassHandler.ts` | Intercetta modelli specifici dalla CLI di Claude (estrazione del titolo, riscaldamento, conteggio) e restituisce risposte false senza chiamare alcun fornitore. Supporta sia lo streaming che il non streaming. Intenzionalmente limitato all'ambito CLI di Claude. | +| `networkProxy.ts` | Risolve l'URL proxy in uscita per un determinato provider con precedenza: configurazione specifica del provider → configurazione globale → variabili di ambiente (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Supporta le esclusioni `NO_PROXY`. Configurazione della cache per 30 secondi. | + +#### Pipeline di streaming SSE + +```mermaid +flowchart TD + A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"] + B --> C["Buffer lines\n(split on newline)"] + C --> D["parseSSELine()\n(trim whitespace, parse JSON)"] + D --> E{"Mode?"} + E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"] + E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"] + F --> H["hasValuableContent()\nfilter empty chunks"] + G --> H + H -->|"Has content"| I["extractUsage()\ntrack token counts"] + H -->|"Empty"| J["Skip chunk"] + I --> K["formatSSE()\nserialize + clean perf_metrics"] + K --> L["TextEncoder\n(per-stream instance)"] + L --> M["Enqueue to\nclient stream"] + + style A fill:#f9f,stroke:#333 + style M fill:#9f9,stroke:#333 +``` + +#### Richiedi la struttura della sessione del logger + +``` +logs/ +└── claude_gemini_claude-sonnet_20260208_143045/ + ├── 1_req_client.json ← Raw client request + ├── 2_req_source.json ← After initial conversion + ├── 3_req_openai.json ← OpenAI intermediate format + ├── 4_req_target.json ← Final target format + ├── 5_res_provider.txt ← Provider SSE chunks (streaming) + ├── 5_res_provider.json ← Provider response (non-streaming) + ├── 6_res_openai.txt ← OpenAI intermediate chunks + ├── 7_res_client.txt ← Client-facing SSE chunks + └── 6_error.json ← Error details (if any) +``` + +--- + +### 4.7 Livello applicazione (`src/`) + +| Elenco | Scopo | +| ------------- | ----------------------------------------------------------------------------------- | +| `src/app/` | Interfaccia utente Web, percorsi API, middleware Express, gestori di callback OAuth | +| `src/lib/` | Accesso al database (`localDb.ts`, `usageDb.ts`), autenticazione, condivisa | +| `src/mitm/` | Utilità proxy man-in-the-middle per intercettare il traffico del provider | +| `src/models/` | Definizioni del modello di database | +| `src/shared/` | Wrapper attorno alle funzioni open-sse (provider, stream, errore, ecc.) | +| `src/sse/` | Gestori endpoint SSE che collegano la libreria open-sse alle rotte Express | +| `src/store/` | Gestione dello stato dell'applicazione | + +#### Percorsi API notevoli + +| Itinerario | Metodi | Scopo | +| --------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `/api/provider-models` | OTTIENI/INVIA/ELIMINA | CRUD per modelli personalizzati per fornitore | +| `/api/models/catalog` | OTTIENI | Catalogo aggregato di tutti i modelli (chat, incorporamento, immagine, personalizzato) raggruppati per fornitore | +| `/api/settings/proxy` | OTTIENI/INSERISCI/ELIMINA | Configurazione proxy in uscita gerarchica (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Convalida la connettività proxy e restituisce IP pubblico/latenza | +| `/v1/providers/[provider]/chat/completions` | POST | Completamenti chat dedicati per provider con convalida del modello | +| `/v1/providers/[provider]/embeddings` | POST | Incorporamenti dedicati per provider con convalida del modello | +| `/v1/providers/[provider]/images/generations` | POST | Generazione di immagini dedicate per provider con convalida del modello | +| `/api/settings/ip-filter` | OTTIENI/METTI | Gestione lista consentita/lista bloccata IP | +| `/api/settings/thinking-budget` | OTTIENI/METTI | Configurazione del budget del token di ragionamento (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | OTTIENI/METTI | Iniezione rapida del sistema globale per tutte le richieste | +| `/api/sessions` | OTTIENI | Monitoraggio e metriche della sessione attiva | +| `/api/rate-limits` | OTTIENI | Stato limite tariffa per account | + +--- + +## 5. Modelli di progettazione chiave + +### 5.1 Traduzione Hub-and-Spoke + +Tutti i formati vengono tradotti tramite il **formato OpenAI come hub**. L'aggiunta di un nuovo provider richiede solo la scrittura di **una coppia** di traduttori (da/verso OpenAI), non N coppie. + +### 5.2 Modello strategico dell'esecutore + +Ogni provider dispone di una classe esecutore dedicata che eredita da `BaseExecutor`. La factory in `executors/index.ts` seleziona quella giusta in fase di runtime. + +### 5.3 Sistema di plug-in di autoregistrazione + +I moduli traduttore si registrano durante l'importazione tramite `register()`. Aggiungere un nuovo traduttore significa semplicemente creare un file e importarlo. + +### 5.4 Fallback dell'account con backoff esponenziale + +Quando un fornitore restituisce 429/401/500, il sistema può passare all'account successivo, applicando tempi di recupero esponenziali (1s → 2s → 4s → max 2min). + +### 5.5 Catene modello combo + +Una "combo" raggruppa più stringhe `provider/model`. Se il primo fallisce, passa automaticamente al successivo. + +### 5.6 Traduzione dello streaming con stato + +La traduzione della risposta mantiene lo stato tra i blocchi SSE (tracciamento dei blocchi di pensiero, accumulo di chiamate allo strumento, indicizzazione dei blocchi di contenuto) tramite il meccanismo `initState()`. + +### 5.7 Buffer di sicurezza per l'utilizzo + +Viene aggiunto un buffer da 2000 token all'utilizzo segnalato per impedire ai client di raggiungere i limiti della finestra di contesto a causa del sovraccarico derivante dai prompt di sistema e dalla conversione del formato. + +--- + +## 6. Formati supportati + +| Formato | Direzione | Identificatore | +| ------------------------- | -------------------- | ------------------ | +| Completamenti OpenAI Chat | fonte + destinazione | `openai` | +| API di risposta OpenAI | fonte + destinazione | `openai-responses` | +| Claude antropico | fonte + destinazione | `claude` | +| Google Gemelli | fonte + destinazione | `gemini` | +| CLI di Google Gemini | solo obiettivo | `gemini-cli` | +| Antigravità | fonte + destinazione | `antigravity` | +| AWS Kiro | solo obiettivo | `kiro` | +| Cursore | solo obiettivo | `cursor` | + +--- + +## 7. Provider supportati + +| Fornitore | Metodo di autenticazione | Esecutore testamentario | Note chiave | +| ------------------------ | ------------------------ | ----------------------- | -------------------------------------------------------- | +| Claude antropico | Chiave API o OAuth | Predefinito | Utilizza l'intestazione `x-api-key` | +| Google Gemelli | Chiave API o OAuth | Predefinito | Utilizza l'intestazione `x-goog-api-key` | +| CLI di Google Gemini | OAuth | GemelliCLI | Utilizza l'endpoint `streamGenerateContent` | +| Antigravità | OAuth | Antigravità | Fallback multi-URL, analisi dei tentativi personalizzata | +| OpenAI | Chiave API | Predefinito | Aut. alfiere | +| Codice | OAuth | Codice | Inserisce istruzioni di sistema, gestisce il pensiero | +| Copilota GitHub | OAuth + token copilota | Github | Doppio token, intestazione VSCode che imita | +| Kiro (AWS) | AWS SSO OIDC o Social | Kiro | Analisi binaria EventStream | +| Cursore IDE | Autenticazione checksum | Cursore | Codifica Protobuf, checksum SHA-256 | +| Qwen | OAuth | Predefinito | Aut. standard | +| iFlow | OAuth (base + portatore) | Predefinito | Intestazione doppia autenticazione | +| OpenRouter | Chiave API | Predefinito | Aut. alfiere | +| GLM, Kimi, MiniMax | Chiave API | Predefinito | Compatibile con Claude, usa `x-api-key` | +| `openai-compatible-*` | Chiave API | Predefinito | Dinamico: qualsiasi endpoint compatibile con OpenAI | +| `anthropic-compatible-*` | Chiave API | Predefinito | Dinamico: qualsiasi endpoint compatibile con Claude | + +--- + +## 8. Riepilogo del flusso di dati + +### Richiesta di streaming + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor\nbuildUrl + buildHeaders"] + D --> E["fetch(providerURL)"] + E --> F["createSSEStream()\nTRANSLATE mode"] + F --> G["parseSSELine()"] + G --> H["translateResponse()\ntarget → OpenAI → source"] + H --> I["extractUsage()\n+ addBuffer"] + I --> J["formatSSE()"] + J --> K["Client receives\ntranslated SSE"] + K --> L["logUsage()\nsaveRequestUsage()"] +``` + +### Richiesta di non streaming + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor.execute()"] + D --> E["translateResponse()\ntarget → OpenAI → source"] + E --> F["Return JSON\nresponse"] +``` + +### Bypass flusso (Claude CLI) + +```mermaid +flowchart LR + A["Claude CLI request"] --> B{"Match bypass\npattern?"} + B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] + B -->|"No match"| D["Normal flow"] + C --> E["Translate to\nsource format"] + E --> F["Return without\ncalling provider"] +``` diff --git a/docs/i18n/it/FEATURES.md b/docs/i18n/it/FEATURES.md new file mode 100644 index 00000000..3122df74 --- /dev/null +++ b/docs/i18n/it/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute: Galleria delle funzionalità del dashboard + +🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) + +Guida visiva a ogni sezione del dashboard OmniRoute. + +--- + +## 🔌 Fornitori + +Gestisci le connessioni dei provider AI: provider OAuth (Claude Code, Codex, Gemini CLI), provider di chiavi API (Groq, DeepSeek, OpenRouter) e provider gratuiti (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨Combo + +Crea combinazioni di routing del modello con 6 strategie: riempimento prima, round robin, scelta potenza di due, casuale, meno utilizzata e con ottimizzazione dei costi. Ogni combo concatena più modelli con fallback automatico. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊Analitica + +Analisi completa dell'utilizzo con consumo di token, stime dei costi, mappe di calore delle attività, grafici di distribuzione settimanale e suddivisioni per fornitore. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥Salute del sistema + +Monitoraggio in tempo reale: tempo di attività, memoria, versione, percentili di latenza (p50/p95/p99), statistiche della cache e stati degli interruttori automatici del provider. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Parco giochi per traduttori + +Quattro modalità per il debug delle traduzioni API: **Playground** (convertitore di formato), **Chat Tester** (richieste live), **Test Bench** (test batch) e **Live Monitor** (streaming in tempo reale). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Impostazioni + +Impostazioni generali, archiviazione di sistema, gestione del backup (database di esportazione/importazione), aspetto (modalità scuro/chiaro), sicurezza (include protezione endpoint API e blocco provider personalizzato), routing, resilienza e configurazione avanzata. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Strumenti CLI + +Configurazione con un clic per gli strumenti di codifica AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code e Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Richiedi registri + +Registrazione delle richieste in tempo reale con filtraggio per provider, modello, account e chiave API. Mostra i codici di stato, l'utilizzo del token, la latenza e i dettagli della risposta. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 Endpoint API + +Il tuo endpoint API unificato con suddivisione delle funzionalità: completamenti chat, incorporamenti, generazione di immagini, riclassificazione, trascrizione audio e chiavi API registrate. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/it/TROUBLESHOOTING.md b/docs/i18n/it/TROUBLESHOOTING.md new file mode 100644 index 00000000..aedad34c --- /dev/null +++ b/docs/i18n/it/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Risoluzione dei problemi + +🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) + +Problemi comuni e soluzioni per OmniRoute. + +--- + +## Soluzioni rapide + +| Problema | Soluzione | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------- | +| Primo accesso non funzionante | Seleziona `INITIAL_PASSWORD` in `.env` (predefinito: `123456`) | +| Il dashboard si apre sulla porta sbagliata | Imposta `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Nessun registro delle richieste in `logs/` | Imposta `ENABLE_REQUEST_LOGS=true` | +| EACCES: permesso negato | Imposta `DATA_DIR=/path/to/writable/dir` per sovrascrivere `~/.omniroute` | +| La strategia di routing non viene salvata | Aggiornamento alla v1.4.11+ (correzione dello schema Zod per la persistenza delle impostazioni) | + +--- + +## Problemi con il fornitore + +### "Il modello linguistico non ha fornito messaggi" + +**Causa:** Quota del fornitore esaurita. + +**Aggiustare:** + +1. Controlla il monitoraggio delle quote del dashboard +2. Utilizza una combinazione con livelli di fallback +3. Passa al livello più economico/gratuito + +### Limitazione della velocità + +**Causa:** Quota di abbonamento esaurita. + +**Aggiustare:** + +- Aggiungi riserva: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Utilizza GLM/MiniMax come backup economico + +### Token OAuth scaduto + +OmniRoute aggiorna automaticamente i token. Se i problemi persistono: + +1. Dashboard → Fornitore → Riconnetti +2. Elimina e aggiungi nuovamente la connessione del provider + +--- + +## Problemi relativi al cloud + +### Errori di sincronizzazione cloud + +1. Verifica che `BASE_URL` punti all'istanza in esecuzione (ad esempio, `http://localhost:20128`) +2. Verifica che `CLOUD_URL` punti al tuo endpoint cloud (ad esempio, `https://omniroute.dev`) +3. Mantieni i valori `NEXT_PUBLIC_*` allineati con i valori lato server + +### Cloud `stream=false` Restituisce 500 + +**Sintomo:** `Unexpected token 'd'...` sull'endpoint cloud per chiamate non in streaming. + +**Causa:** l'upstream restituisce il payload SSE mentre il client si aspetta JSON. + +**Soluzione alternativa:** utilizzare `stream=true` per le chiamate dirette sul cloud. Il runtime locale include il fallback SSE→JSON. + +### Cloud dice che è connesso ma "Chiave API non valida" + +1. Crea una nuova chiave dal dashboard locale (`/api/keys`) +2. Eseguire la sincronizzazione cloud: Abilita Cloud → Sincronizza ora +3. Le chiavi vecchie/non sincronizzate possono ancora restituire `401` sul cloud + +--- + +## Problemi con Docker + +### Lo strumento CLI risulta non installato + +1. Controlla i campi di runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Per la modalità portatile: utilizzare la destinazione dell'immagine `runner-cli` (CLI in bundle) +3. Per la modalità di montaggio host: impostare `CLI_EXTRA_PATHS` e montare la directory bin dell'host come di sola lettura +4. Se `installed=true` e `runnable=false`: il binario è stato trovato ma il controllo dello stato non è riuscito + +### Convalida rapida del runtime + +```bash +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}' +``` + +--- + +## Problemi di costi + +### Costi elevati + +1. Controlla le statistiche di utilizzo in Dashboard → Utilizzo +2. Passare dal modello principale a GLM/MiniMax +3. Utilizza il livello gratuito (Gemini CLI, iFlow) per attività non critiche +4. Imposta i budget dei costi per chiave API: Dashboard → Chiavi API → Budget + +--- + +## Debug + +### Abilita i registri delle richieste + +Imposta `ENABLE_REQUEST_LOGS=true` nel tuo file `.env`. I registri vengono visualizzati nella directory `logs/`. + +### Controlla lo stato del fornitore + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Archiviazione del runtime + +- Stato principale: `${DATA_DIR}/db.json` (provider, combo, alias, chiavi, impostazioni) +- Utilizzo: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Registri delle richieste: `/logs/...` (quando `ENABLE_REQUEST_LOGS=true`) + +--- + +## Problemi con l'interruttore automatico + +### Provider bloccato nello stato APERTO + +Quando l'interruttore di un provider è APERTO, le richieste vengono bloccate fino alla scadenza del tempo di recupero. + +**Aggiustare:** + +1. Vai su **Dashboard → Impostazioni → Resilienza** +2. Controllare la scheda dell'interruttore del provider interessato +3. Fare clic su **Reimposta tutto** per cancellare tutti gli interruttori o attendere la scadenza del tempo di recupero +4. Verificare che il provider sia effettivamente disponibile prima di reimpostare + +### Il provider continua a far scattare l'interruttore + +Se un provider entra ripetutamente nello stato OPEN: + +1. Selezionare **Dashboard → Salute → Salute del provider** per il modello di errore +2. Vai su **Impostazioni → Resilienza → Profili fornitore** e aumenta la soglia di errore +3. Controlla se il provider ha modificato i limiti API o richiede la riautenticazione +4. Esaminare la telemetria della latenza: un'elevata latenza può causare errori basati sul timeout + +--- + +## Problemi di trascrizione audio + +### Errore "Modello non supportato". + +- Assicurati di utilizzare il prefisso corretto: `deepgram/nova-3` o `assemblyai/best` +- Verificare che il provider sia connesso in **Dashboard → Provider** + +### La trascrizione restituisce un valore vuoto o non riesce + +- Controlla i formati audio supportati: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verificare che la dimensione del file rientri nei limiti del provider (in genere < 25 MB) +- Controlla la validità della chiave API del fornitore nella scheda del fornitore + +--- + +## Debug del traduttore + +Utilizza **Dashboard → Traduttore** per eseguire il debug dei problemi di traduzione del formato: + +| Modalità | Quando usarlo | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| **Parco giochi** | Confronta i formati di input/output fianco a fianco: incolla una richiesta non riuscita per vedere come viene tradotta | +| **Tester della chat** | Invia messaggi in tempo reale e controlla l'intero payload di richiesta/risposta, comprese le intestazioni | +| **Banco di prova** | Esegui test batch su combinazioni di formati per scoprire quali traduzioni sono interrotte | +| **Monitoraggio dal vivo** | Guarda il flusso di richieste in tempo reale per individuare problemi di traduzione intermittenti | + +### Problemi comuni di formato + +- **I tag Thinking non vengono visualizzati**: controlla se il fornitore di destinazione supporta il pensiero e l'impostazione del budget per il pensiero +- **Chiamate dello strumento eliminate**: alcune traduzioni di formato potrebbero eliminare i campi non supportati; verificare in modalità Parco giochi +- **Prompt di sistema mancante** — Claude e Gemini gestiscono i prompt di sistema in modo diverso; controllare l'output della traduzione +- **L'SDK restituisce una stringa non elaborata anziché un oggetto** — Risolto nella versione 1.1.0: il sanitizer della risposta ora rimuove i campi non standard (`x_groq`, `usage_breakdown` e così via) che causano errori di convalida OpenAI SDK Pydantic +- **GLM/ERNIE rifiuta il ruolo `system`** — Risolto nella versione 1.1.0: il normalizzatore del ruolo unisce automaticamente i messaggi di sistema nei messaggi utente per modelli incompatibili +- **Ruolo `developer` non riconosciuto** — Risolto il problema nella v1.1.0: convertito automaticamente in `system` per provider non OpenAI +- **`json_schema` non funziona con Gemini** — Risolto il problema nella v1.1.0: `response_format` è ora convertito in `responseMimeType` di Gemini + `responseSchema` + +--- + +## Impostazioni di resilienza + +### Il limite di velocità automatico non si attiva + +- Il limite di velocità automatico si applica solo ai fornitori di chiavi API (non OAuth/abbonamento) +- Verificare che **Impostazioni → Resilienza → Profili fornitore** abbia il limite di velocità automatico abilitato +- Controlla se il provider restituisce codici di stato `429` o intestazioni `Retry-After` + +### Ottimizzazione del backoff esponenziale + +I profili dei fornitori supportano queste impostazioni: + +- **Ritardo base**: tempo di attesa iniziale dopo il primo errore (impostazione predefinita: 1 s) +- **Ritardo massimo**: limite massimo del tempo di attesa (impostazione predefinita: 30 secondi) +- **Moltiplicatore**: quanto aumentare il ritardo per guasto consecutivo (impostazione predefinita: 2x) + +### Mandria antituono + +Quando molte richieste simultanee raggiungono un provider con velocità limitata, OmniRoute utilizza mutex + limitazione automatica della velocità per serializzare le richieste e prevenire errori a catena. Questo è automatico per i fornitori di chiavi API. + +--- + +## Sei ancora bloccato? + +- **Problemi GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architettura**: vedi [**OMNI_TOKEN_55**](ARCHITECTURE.md) per i dettagli interni +- **Riferimento API**: vedere [**OMNI_TOKEN_56**](API_REFERENCE.md) per tutti gli endpoint +- **Dashboard salute**: controlla **Dashboard → Salute** per lo stato del sistema in tempo reale +- **Traduttore**: utilizza **Dashboard → Traduttore** per eseguire il debug dei problemi di formato diff --git a/docs/i18n/it/USER_GUIDE.md b/docs/i18n/it/USER_GUIDE.md new file mode 100644 index 00000000..2f159abb --- /dev/null +++ b/docs/i18n/it/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Guida per l'utente + +🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) + +Guida completa per la configurazione dei provider, la creazione di combinazioni, l'integrazione degli strumenti CLI e la distribuzione di OmniRoute. + +--- + +## Sommario + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [Provider Setup](#-provider-setup) +- [CLI Integration](#-cli-integration) +- [Deployment](#-deployment) +- [Available Models](#-available-models) +- [Advanced Features](#-advanced-features) + +--- + +## 💰 Prezzi in breve + +| Livello | Fornitore | Costo | Reimpostazione quota | Ideale per | +| ------------------ | --------------------- | ----------------- | ------------------------ | ------------------------ | +| **💳 ABBONAMENTO** | Codice Claude (Pro) | $20/mese | 5 ore + settimanale | Già iscritto | +| | Codice (Plus/Pro) | $20-200/mese | 5 ore + settimanale | Utenti OpenAI | +| | Gemelli CLI | **GRATIS** | 180K/mese + 1K/giorno | Tutti! | +| | Copilota GitHub | $ 10-19/mese | Mensile | Utenti GitHub | +| **🔑 CHIAVE API** | Ricerca profonda | Paga per utilizzo | Nessuno | Ragionamento economico | +| | Groq | Paga per utilizzo | Nessuno | Inferenza ultraveloce | +| | xAI (Grok) | Paga per utilizzo | Nessuno | Grok 4 ragionamento | +| | Maestrale | Paga per utilizzo | Nessuno | Modelli ospitati nell'UE | +| | Perplessità | Paga per utilizzo | Nessuno | Ricerca aumentata | +| | Insieme AI | Paga per utilizzo | Nessuno | Modelli open source | +| | Fuochi d'artificio AI | Paga per utilizzo | Nessuno | Immagini FLUX veloci | +| | Cerebri | Paga per utilizzo | Nessuno | Velocità su scala wafer | +| | Coerenza | Paga per utilizzo | Nessuno | Comando R+ RAG | +| | NVIDIA NIM | Paga per utilizzo | Nessuno | Modelli di impresa | +| **💰 ECONOMICO** | GLM-4.7 | $ 0,6/1 milione | Tutti i giorni 10:00 | Backup del budget | +| | MiniMax M2.1 | $ 0,2/1 milione | 5 ore di rotazione | Opzione più economica | +| | Kimi K2 | $ 9/mese fisso | 10 milioni di token/mese | Costo prevedibile | +| **🆓 GRATUITO** | iFlow | $0 | Illimitato | 8 modelli gratuiti | +| | Qwen | $0 | Illimitato | 3 modelli gratuiti | +| | Kiro | $0 | Illimitato | Claude libero | + +**💡 Suggerimento da professionista:** Inizia con la combinazione Gemini CLI (180.000 gratuiti al mese) + iFlow (gratuito illimitato) = costo $ 0! + +--- + +## 🎯 Casi d'uso + +### Caso 1: "Ho un abbonamento Claude Pro" + +**Problema:** La quota scade inutilizzata, limiti di velocità durante la codifica pesante + +``` +Combo: "maximize-claude" + 1. cc/claude-opus-4-6 (use subscription fully) + 2. glm/glm-4.7 (cheap backup when quota out) + 3. if/kimi-k2-thinking (free emergency fallback) + +Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total +vs. $20 + hitting limits = frustration +``` + +### Caso 2: "Voglio zero costi" + +**Problema:** non posso permettermi abbonamenti, ho bisogno di una codifica IA affidabile + +``` +Combo: "free-forever" + 1. gc/gemini-3-flash (180K free/month) + 2. if/kimi-k2-thinking (unlimited free) + 3. qw/qwen3-coder-plus (unlimited free) + +Monthly cost: $0 +Quality: Production-ready models +``` + +### Caso 3: "Ho bisogno di codifica 24 ore su 24, 7 giorni su 7, senza interruzioni" + +**Problema:** Scadenze, non posso permettermi tempi di inattività + +``` +Combo: "always-on" + 1. cc/claude-opus-4-6 (best quality) + 2. cx/gpt-5.2-codex (second subscription) + 3. glm/glm-4.7 (cheap, resets daily) + 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) + 5. if/kimi-k2-thinking (free unlimited) + +Result: 5 layers of fallback = zero downtime +Monthly cost: $20-200 (subscriptions) + $10-20 (backup) +``` + +### Caso 4: "Voglio un'intelligenza artificiale GRATUITA in OpenClaw" + +**Problema:** È necessario un assistente AI nelle app di messaggistica, completamente gratuito + +``` +Combo: "openclaw-free" + 1. if/glm-4.7 (unlimited free) + 2. if/minimax-m2.1 (unlimited free) + 3. if/kimi-k2-thinking (unlimited free) + +Monthly cost: $0 +Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... +``` + +--- + +## 📖 Configurazione del fornitore + +### 🔐 Fornitori di abbonamenti + +#### Codice Claude (Pro/Max) + +```bash +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking + +Models: + cc/claude-opus-4-6 + cc/claude-sonnet-4-5-20250929 + cc/claude-haiku-4-5-20251001 +``` + +**Suggerimento professionale:** usa Opus per attività complesse, Sonnet per la velocità. OmniRoute tiene traccia della quota per modello! + +#### Codice OpenAI (Plus/Pro) + +```bash +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset + +Models: + cx/gpt-5.2-codex + cx/gpt-5.1-codex-max +``` + +#### Gemini CLI (180.000 GRATIS al mese!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Miglior rapporto qualità-prezzo:** Enorme livello gratuito! Utilizzalo prima dei livelli a pagamento. + +#### Copilota GitHub + +```bash +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) + +Models: + gh/gpt-5 + gh/claude-4.5-sonnet + gh/gemini-3-pro +``` + +### 💰 Fornitori economici + +#### GLM-4.7 (ripristino giornaliero, $ 0,6/1 milione) + +1. Iscriviti: [Zhipu AI](https://open.bigmodel.cn/) +2. Ottieni la chiave API dal piano di codifica +3. Dashboard → Aggiungi chiave API: Provider: `glm`, Chiave API: `your-key` + +**Utilizza:** `glm/glm-4.7` — **Suggerimento professionale:** Il piano di codifica offre una quota 3× a un costo di 1/7! Resetta ogni giorno alle 10:00. + +#### MiniMax M2.1 (ripristino in 5 ore, $ 0,20/1 milione) + +1. Iscriviti: [MiniMax](https://www.minimax.io/) +2. Ottieni chiave API → Dashboard → Aggiungi chiave API + +**Utilizza:** `minimax/MiniMax-M2.1` — **Suggerimento professionale:** Opzione più economica per contesti lunghi (token da 1 milione)! + +#### Kimi K2 ($9/mese fisso) + +1. Iscriviti: [Moonshot AI](https://platform.moonshot.ai/) +2. Ottieni chiave API → Dashboard → Aggiungi chiave API + +**Utilizza:** `kimi/kimi-latest` — **Suggerimento da professionista:** $ 9/mese fissi per 10 milioni di token = $ 0,90/1 milione di costi effettivi! + +### 🆓 Fornitori GRATUITI + +#### iFlow (8 modelli GRATUITI) + +```bash +Dashboard → Connect iFlow → OAuth login → Unlimited usage + +Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 +``` + +#### Qwen (3 modelli GRATUITI) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude GRATIS) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨Combo + +### Esempio 1: Massimizza l'abbonamento → Backup economico + +``` +Dashboard → Combos → Create New + +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) + +Use in CLI: premium-coding +``` + +### Esempio 2: solo gratuito (costo zero) + +``` +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) + +Cost: $0 forever! +``` + +--- + +## 🔧Integrazione CLI + +### IDE del cursore + +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` + +### Codice Claude + +Modifica `~/.claude/config.json`: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### Codice CLI + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +### OpenClaw + +Modifica `~/.openclaw/openclaw.json`: + +```json +{ + "agents": { + "defaults": { + "model": { "primary": "omniroute/if/glm-4.7" } + } + }, + "models": { + "providers": { + "omniroute": { + "baseUrl": "http://localhost:20128/v1", + "apiKey": "your-omniroute-api-key", + "api": "openai-completions", + "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }] + } + } + } +} +``` + +**Oppure utilizza Dashboard:** Strumenti CLI → OpenClaw → Configurazione automatica + +### Cline / Continua / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Distribuzione + +### Distribuzione VPS + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### Finestra mobile + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +Per la modalità integrata nell'host con i file binari della CLI, consulta la sezione Docker nella documentazione principale. + +### Variabili d'ambiente + +| Variabile | Predefinito | Descrizione | +| --------------------- | ------------------------------------ | -------------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segreto firma JWT (**cambio di produzione**) | +| `INITIAL_PASSWORD` | `123456` | Prima password di accesso | +| `DATA_DIR` | `~/.omniroute` | Directory dati (db, utilizzo, log) | +| `PORT` | quadro predefinito | Porta di servizio (`20128` negli esempi) | +| `HOSTNAME` | quadro predefinito | Associa host (Docker per impostazione predefinita è `0.0.0.0`) | +| `NODE_ENV` | impostazione predefinita di runtime | Imposta `production` per la distribuzione | +| `BASE_URL` | `http://localhost:20128` | URL di base interno lato server | +| `CLOUD_URL` | `https://omniroute.dev` | URL di base dell'endpoint di sincronizzazione cloud | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segreto HMAC per le chiavi API generate | +| `REQUIRE_API_KEY` | `false` | Applica la chiave API Bearer su `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Abilita i log di richiesta/risposta | +| `AUTH_COOKIE_SECURE` | `false` | Forza il cookie di autenticazione `Secure` (dietro il proxy inverso HTTPS) | + +Per il riferimento completo alle variabili di ambiente, vedere [README](../README.md). + +--- + +## 📊 Modelli Disponibili + +
+Visualizza tutti i modelli disponibili + +**Codice Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Codice (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` + +**Gemini CLI (`gc/`)** — GRATUITO: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` + +**Copilota GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**GLM (`glm/`)** — $ 0,6/1 milione: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — $ 0,2/1 milione: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** — GRATUITO: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` + +**Qwen (`qw/`)** — GRATUITO: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` + +**Kiro (`kr/`)** — GRATUITO: `kr/claude-sonnet-4.5`, `kr/claude-haiku-4.5` + +**DeepSeek (`ds/`)**: `ds/deepseek-chat`, `ds/deepseek-reasoner` + +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`, `groq/llama-4-maverick-17b-128e-instruct` + +**xAI (`xai/`)**: `xai/grok-4`, `xai/grok-4-0709-fast-reasoning`, `xai/grok-code-mini` + +**Maestrale (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` + +**Perplessità (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Insieme AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**Fuochi d'artificio AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Cerebra (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Coerenza (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Funzionalità avanzate + +### Modelli personalizzati + +Aggiungi qualsiasi ID modello a qualsiasi provider senza attendere un aggiornamento dell'app: + +```bash +# Via API +curl -X POST http://localhost:20128/api/provider-models \ + -H "Content-Type: application/json" \ + -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}' + +# List: curl http://localhost:20128/api/provider-models?provider=openai +# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" +``` + +Oppure utilizza la Dashboard: **Provider → [Provider] → Modelli personalizzati**. + +### Percorsi di provider dedicati + +Instrada le richieste direttamente a un fornitore specifico con convalida del modello: + +```bash +POST http://localhost:20128/v1/providers/openai/chat/completions +POST http://localhost:20128/v1/providers/openai/embeddings +POST http://localhost:20128/v1/providers/fireworks/images/generations +``` + +Se mancante, il prefisso del provider viene aggiunto automaticamente. I modelli non corrispondenti restituiscono `400`. + +### Configurazione del proxy di rete + +```bash +# Set global proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' + +# Per-provider proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' + +# Test proxy +curl -X POST http://localhost:20128/api/settings/proxy/test \ + -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' +``` + +**Precedenza:** Specifico per chiave → Specifico per combo → Specifico per provider → Globale → Ambiente. + +### API del catalogo modelli + +```bash +curl http://localhost:20128/api/models/catalog +``` + +Restituisce modelli raggruppati per provider con tipi (`chat`, `embedding`, `image`). + +### Sincronizzazione nel cloud + +- Sincronizza provider, combo e impostazioni su tutti i dispositivi +- Sincronizzazione automatica in background con timeout + fail-fast +- Preferisci lato server `BASE_URL`/`CLOUD_URL` in produzione + +### LLM Gateway Intelligence (Fase 9) + +- **Cache semantica**: memorizza automaticamente nella cache le risposte non in streaming, temperatura=0 (ignora con `X-OmniRoute-No-Cache: true`) +- **Idempotenza richiesta**: deduplica le richieste entro 5 secondi tramite l'intestazione `Idempotency-Key` o `X-Request-Id` +- **Monitoraggio dei progressi**: attivazione degli eventi SSE `event: progress` tramite l'intestazione `X-OmniRoute-Progress: true` + +--- + +### Parco giochi per traduttori + +Accesso tramite **Dashboard → Traduttore**. Eseguire il debug e visualizzare il modo in cui OmniRoute traduce le richieste API tra provider. + +| Modalità | Scopo | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **Parco giochi** | Seleziona i formati di origine/destinazione, incolla una richiesta e visualizza immediatamente l'output tradotto | +| **Tester della chat** | Invia messaggi di chat dal vivo tramite il proxy e controlla l'intero ciclo di richiesta/risposta | +| **Banco di prova** | Esegui test batch su più combinazioni di formati per verificare la correttezza della traduzione | +| **Monitoraggio dal vivo** | Guarda le traduzioni in tempo reale mentre le richieste passano attraverso il proxy | + +**Casi d'uso:** + +- Debug del motivo per cui una specifica combinazione client/provider non riesce +- Verificare che i tag pensanti, le chiamate agli strumenti e i prompt di sistema vengano tradotti correttamente +- Confronta le differenze di formato tra i formati OpenAI, Claude, Gemini e Responses API + +--- + +### Strategie di instradamento + +Configura tramite **Dashboard → Impostazioni → Routing**. + +| Strategia | Descrizione | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **Compila prima** | Utilizza gli account in ordine di priorità: l'account principale gestisce tutte le richieste fino a quando non è disponibile | +| **Round Robin** | Scorre tutti gli account con un limite permanente configurabile (impostazione predefinita: 3 chiamate per account) | +| **P2C (il potere di due scelte)** | Scegli 2 account casuali e percorsi verso quello più sano: bilancia il carico con la consapevolezza della salute | +| **Casuale** | Seleziona casualmente un account per ciascuna richiesta utilizzando Fisher-Yates shuffle | +| **Meno usato** | Indirizza all'account con il timestamp `lastUsedAt` più vecchio, distribuendo il traffico in modo uniforme | +| **Costi ottimizzati** | Instrada all'account con il valore di priorità più basso, ottimizzando per i fornitori a basso costo | + +#### Alias ​​del modello con caratteri jolly + +Crea modelli con caratteri jolly per rimappare i nomi dei modelli: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +I caratteri jolly supportano `*` (qualsiasi carattere) e `?` (carattere singolo). + +#### Catene di riserva + +Definisci catene di fallback globali che si applicano a tutte le richieste: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Resilienza e interruttori automatici + +Configura tramite **Dashboard → Impostazioni → Resilienza**. + +OmniRoute implementa la resilienza a livello di fornitore con quattro componenti: + +1. **Profili fornitore**: configurazione per fornitore per: + - Soglia di guasto (quanti guasti prima dell'apertura) + - Durata del raffreddamento + - Sensibilità di rilevamento del limite di velocità + - Parametri di backoff esponenziale + +2. **Limiti di velocità modificabili**: impostazioni predefinite a livello di sistema configurabili nel dashboard: + - **Richieste al minuto (RPM)**: numero massimo di richieste al minuto per account + - **Tempo minimo tra le richieste**: intervallo minimo in millisecondi tra le richieste + - **Numero massimo di richieste simultanee**: numero massimo di richieste simultanee per account + - Fai clic su **Modifica** per modificare, quindi su **Salva** o **Annulla**. I valori persistono tramite l'API di resilienza. + +3. **Interruttore di circuito**: tiene traccia dei guasti per fornitore e apre automaticamente il circuito quando viene raggiunta una soglia: + - **CHIUSO** (integro): le richieste fluiscono normalmente + - **APERTO**: il provider è temporaneamente bloccato dopo ripetuti errori + - **HALF_OPEN**: verifica se il provider è stato ripristinato + +4. **Criteri e identificatori bloccati**: mostra lo stato dell'interruttore automatico e gli identificatori bloccati con funzionalità di sblocco forzato. + +5. **Rilevamento automatico del limite di velocità**: monitora le intestazioni `429` e `Retry-After` per evitare in modo proattivo di raggiungere i limiti di velocità del provider. + +**Suggerimento avanzato:** utilizza il pulsante **Reimposta tutto** per eliminare tutti gli interruttori automatici e i tempi di recupero quando un fornitore si riprende da un'interruzione. + +--- + +### Esportazione/importazione del database + +Gestisci i backup del database in **Dashboard → Impostazioni → Sistema e archiviazione**. + +| Azione | Descrizione | +| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Esporta database** | Scarica il database SQLite corrente come file `.sqlite` | +| **Esporta tutto (.tar.gz)** | Scarica un archivio di backup completo che include: database, impostazioni, combo, connessioni al provider (nessuna credenziale), metadati della chiave API | +| **Importa database** | Carica un file `.sqlite` per sostituire il database corrente. Viene creato automaticamente un backup pre-importazione | + +```bash +# API: Export database +curl -o backup.sqlite http://localhost:20128/api/db-backups/export + +# API: Export all (full archive) +curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll + +# API: Import database +curl -X POST http://localhost:20128/api/db-backups/import \ + -F "file=@backup.sqlite" +``` + +**Convalida dell'importazione:** il file importato viene convalidato per l'integrità (controllo pragma SQLite), le tabelle richieste (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e le dimensioni (max 100 MB). + +**Casi d'uso:** + +- Migrare OmniRoute tra macchine +- Creare backup esterni per il ripristino di emergenza +- Condividi le configurazioni tra i membri del team (esporta tutto → condividi archivio) + +--- + +### Pannello delle impostazioni + +La pagina delle impostazioni è organizzata in 5 schede per una facile navigazione: + +| Scheda | Contenuto | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **Sicurezza** | Impostazioni accesso/password, controllo accesso IP, autenticazione API per `/models` e blocco provider | +| **Percorso** | Strategia di routing globale (6 opzioni), alias del modello con caratteri jolly, catene di fallback, impostazioni predefinite combinate | +| **Resilienza** | Profili dei fornitori, limiti di velocità modificabili, stato dell'interruttore automatico, policy e identificatori bloccati | +| **AI** | Pensare alla configurazione del budget, all'inserimento dei prompt del sistema globale, alle statistiche della cache dei prompt | +| **Avanzato** | Configurazione proxy globale (HTTP/SOCKS5) | + +--- + +### Gestione dei costi e del budget + +Accesso tramite **Dashboard → Costi**. + +| Scheda | Scopo | +| ------------ | --------------------------------------------------------------------------------------------------------------- | +| **Bilancio** | Imposta limiti di spesa per chiave API con budget giornalieri/settimanali/mensili e monitoraggio in tempo reale | +| **Prezzi** | Visualizza e modifica le voci dei prezzi dei modelli: costo per token di input/output da 1.000 per fornitore | + +```bash +# API: Set a budget +curl -X POST http://localhost:20128/api/usage/budget \ + -H "Content-Type: application/json" \ + -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' + +# API: Get current budget status +curl http://localhost:20128/api/usage/budget +``` + +**Monitoraggio dei costi:** ogni richiesta registra l'utilizzo del token e calcola il costo utilizzando la tabella dei prezzi. Visualizza i dettagli in **Dashboard → Utilizzo** per provider, modello e chiave API. + +--- + +### Trascrizione audio + +OmniRoute supporta la trascrizione audio tramite l'endpoint compatibile con OpenAI: + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data + +# Example with curl +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@audio.mp3" \ + -F "model=deepgram/nova-3" +``` + +Provider disponibili: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Formati audio supportati: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +### Strategie di bilanciamento combinate + +Configura il bilanciamento per combo in **Dashboard → Combo → Crea/Modifica → Strategia**. + +| Strategia | Descrizione | +| ---------------------------- | ------------------------------------------------------------------------------------------- | +| **Round-Robin** | Ruota i modelli in sequenza | +| **Priorità** | Prova sempre il primo modello; ricorre solo in caso di errore | +| **Casuale** | Sceglie un modello casuale dalla combo per ogni richiesta | +| **Ponderato** | Percorsi proporzionali in base ai pesi assegnati per modello | +| **Meno utilizzato** | Indirizza al modello con il minor numero di richieste recenti (utilizza metriche combinate) | +| **Ottimizzazione dei costi** | Itinerari verso il modello disponibile più economico (utilizza la tabella dei prezzi) | + +Le impostazioni predefinite globali della combo possono essere impostate in **Dashboard → Impostazioni → Routing → Impostazioni combo**. + +--- + +### Pannello di controllo della salute + +Accesso tramite **Dashboard → Salute**. Panoramica sullo stato del sistema in tempo reale con 6 carte: + +| Carta | Cosa mostra | +| ---------------------------- | ---------------------------------------------------------------------------------- | +| **Stato del sistema** | Tempo di attività, versione, utilizzo della memoria, directory dei dati | +| **Salute del fornitore** | Stato dell'interruttore automatico per provider (chiuso/aperto/semiaperto) | +| **Limiti di tariffa** | Raffreddamenti del limite di velocità attivi per account con tempo rimanente | +| **Blocchi attivi** | Provider temporaneamente bloccati dalla politica di blocco | +| **Cache delle firme** | Statistiche della cache di deduplicazione (chiavi attive, percentuale di successo) | +| **Telemetria della latenza** | Aggregazione della latenza p50/p95/p99 per provider | + +**Suggerimento avanzato:** la pagina Salute si aggiorna automaticamente ogni 10 secondi. Utilizza la scheda dell'interruttore per identificare quali fornitori stanno riscontrando problemi. diff --git a/docs/i18n/ja/API_REFERENCE.md b/docs/i18n/ja/API_REFERENCE.md new file mode 100644 index 00000000..37108903 --- /dev/null +++ b/docs/i18n/ja/API_REFERENCE.md @@ -0,0 +1,441 @@ +# APIリファレンス + +🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md) + +すべての OmniRoute API エンドポイントの完全なリファレンス。 + +--- + +## 目次 + +- [Chat Completions](#chat-completions) +- [Embeddings](#embeddings) +- [Image Generation](#image-generation) +- [List Models](#list-models) +- [Compatibility Endpoints](#compatibility-endpoints) +- [Semantic Cache](#semantic-cache) +- [Dashboard & Management](#dashboard--management) +- [Request Processing](#request-processing) +- [Authentication](#authentication) + +--- + +## チャットの完了 + +```bash +POST /v1/chat/completions +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "cc/claude-opus-4-6", + "messages": [ + {"role": "user", "content": "Write a function to..."} + ], + "stream": true +} +``` + +### カスタムヘッダー + +| ヘッダー | 方向 | 説明 | +| ------------------------ | ---------- | --------------------------------------------------- | ------------------------ | +| `X-OmniRoute-No-Cache` | リクエスト | キャッシュをバイパスするには、`true` に設定します。 | +| `X-OmniRoute-Progress` | リクエスト | 進行状況イベントの場合は `true` に設定します。 | +| `Idempotency-Key` | リクエスト | 重複排除キー (5 秒ウィンドウ) | +| `X-Request-Id` | リクエスト | 代替の重複排除キー | +| `X-OmniRoute-Cache` | 応答 | `HIT` または `MISS` (非ストリーミング) | +| `X-OmniRoute-Idempotent` | 応答 | `true` (重複排除の場合) | +| `X-OmniRoute-Progress` | 応答 | `enabled` | で進行状況を追跡する場合 | + +--- + +## 埋め込み + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +利用可能なプロバイダー: Nebius、OpenAI、Mistral、Togetter AI、Fireworks、NVIDIA。 + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## 画像の生成 + +```bash +POST /v1/images/generations +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "openai/dall-e-3", + "prompt": "A beautiful sunset over mountains", + "size": "1024x1024" +} +``` + +利用可能なプロバイダー: OpenAI (DALL-E)、xAI (Grok Image)、Togetter AI (FLUX)、Fireworks AI。 + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## モデルのリスト + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## 互換性エンドポイント + +| 方法 | パス | フォーマット | +| ---- | --------------------------- | --------------------- | +| 投稿 | `/v1/chat/completions` | オープンAI | +| 投稿 | `/v1/messages` | 人類 | +| 投稿 | `/v1/responses` | OpenAI の応答 | +| 投稿 | `/v1/embeddings` | オープンAI | +| 投稿 | `/v1/images/generations` | オープンAI | +| 入手 | `/v1/models` | オープンAI | +| 投稿 | `/v1/messages/count_tokens` | 人類 | +| 入手 | `/v1beta/models` | ジェミニ | +| 投稿 | `/v1beta/models/{...path}` | Gemini コンテンツ生成 | +| 投稿 | `/v1/api/chat` | オラマ | + +### 専用プロバイダー ルート + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +プロバイダーのプレフィックスが存在しない場合は、自動的に追加されます。モデルが一致しない場合は、`400` が返されます。 + +--- + +## セマンティック キャッシュ + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +応答例: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## ダッシュボードと管理 + +### 認証 + +| エンドポイント | 方法 | 説明 | +| ----------------------------- | ------- | ------------------------------------ | +| `/api/auth/login` | 投稿 | ログイン | +| `/api/auth/logout` | 投稿 | ログアウト | +| `/api/settings/require-login` | GET/PUT | ログインが必要かどうかを切り替えます | + +### プロバイダー管理 + +| エンドポイント | 方法 | 説明 | +| ---------------------------- | -------------- | ---------------------------- | +| `/api/providers` | 取得/投稿 | プロバイダーのリスト/作成 | +| `/api/providers/[id]` | 取得/挿入/削除 | プロバイダーを管理する | +| `/api/providers/[id]/test` | 投稿 | プロバイダー接続をテストする | +| `/api/providers/[id]/models` | 入手 | プロバイダーモデルのリスト | +| `/api/providers/validate` | 投稿 | プロバイダー構成を検証する | +| `/api/provider-nodes*` | いろいろ | プロバイダーノード管理 | +| `/api/provider-models` | 取得/投稿/削除 | カスタムモデル | + +### OAuth フロー + +| エンドポイント | 方法 | 説明 | +| -------------------------------- | -------- | ------------------------ | +| `/api/oauth/[provider]/[action]` | いろいろ | プロバイダー固有の OAuth | + +### ルーティングと構成 + +| エンドポイント | 方法 | 説明 | +| --------------------- | --------- | --------------------------------------- | +| `/api/models/alias` | 取得/投稿 | モデルの別名 | +| `/api/models/catalog` | 入手 | プロバイダー + タイプ別のすべてのモデル | +| `/api/combos*` | いろいろ | コンボ管理 | +| `/api/keys*` | いろいろ | API キー管理 | +| `/api/pricing` | 入手 | モデルの価格 | + +### 使用状況と分析 + +| エンドポイント | 方法 | 説明 | +| --------------------------- | ---- | ---------------------- | +| `/api/usage/history` | 入手 | 利用履歴 | +| `/api/usage/logs` | 入手 | 使用ログ | +| `/api/usage/request-logs` | 入手 | リクエストレベルのログ | +| `/api/usage/[connectionId]` | 入手 | 接続ごとの使用量 | + +### 設定 + +| エンドポイント | 方法 | 説明 | +| ------------------------------- | ------- | ------------------------------ | +| `/api/settings` | GET/PUT | 一般設定 | +| `/api/settings/proxy` | GET/PUT | ネットワークプロキシ設定 | +| `/api/settings/proxy/test` | 投稿 | プロキシ接続をテストする | +| `/api/settings/ip-filter` | GET/PUT | IP 許可リスト/ブロックリスト | +| `/api/settings/thinking-budget` | GET/PUT | トークンの予算の推論 | +| `/api/settings/system-prompt` | GET/PUT | グローバル システム プロンプト | + +### モニタリング + +| エンドポイント | 方法 | 説明 | +| ------------------------ | --------- | ---------------------------- | +| `/api/sessions` | 入手 | アクティブなセッションの追跡 | +| `/api/rate-limits` | 入手 | アカウントごとのレート制限 | +| `/api/monitoring/health` | 入手 | 健康診断 | +| `/api/cache` | 取得/削除 | キャッシュ統計 / クリア | + +### バックアップとエクスポート/インポート + +| エンドポイント | 方法 | 説明 | +| --------------------------- | ---- | ---------------------------------------------------------- | +| `/api/db-backups` | 入手 | 利用可能なバックアップをリストする | +| `/api/db-backups` | 置く | 手動バックアップを作成する | +| `/api/db-backups` | 投稿 | 特定のバックアップから復元する | +| `/api/db-backups/export` | 入手 | データベースを .sqlite ファイルとしてダウンロード | +| `/api/db-backups/import` | 投稿 | .sqlite ファイルをアップロードしてデータベースを置き換える | +| `/api/db-backups/exportAll` | 入手 | 完全バックアップを .tar.gz アーカイブとしてダウンロード | + +### クラウド同期 + +| エンドポイント | 方法 | 説明 | +| ---------------------- | -------- | ---------------- | +| `/api/sync/cloud` | いろいろ | クラウド同期操作 | +| `/api/sync/initialize` | 投稿 | 同期を初期化する | +| `/api/cloud/*` | いろいろ | クラウド管理 | + +### CLI ツール + +| エンドポイント | 方法 | 説明 | +| ---------------------------------- | ---- | ----------------------- | +| `/api/cli-tools/claude-settings` | 入手 | クロード CLI ステータス | +| `/api/cli-tools/codex-settings` | 入手 | Codex CLI ステータス | +| `/api/cli-tools/droid-settings` | 入手 | Droid CLI ステータス | +| `/api/cli-tools/openclaw-settings` | 入手 | OpenClaw CLI ステータス | +| `/api/cli-tools/runtime/[toolId]` | 入手 | 汎用 CLI ランタイム | + +CLI 応答には、`installed`、`runnable`、`command`、`commandPath`、`runtimeMode`、`reason` が含まれます。 + +### 復元力とレート制限 + +| エンドポイント | 方法 | 説明 | +| ----------------------- | ------- | ------------------------------------ | +| `/api/resilience` | GET/PUT | 回復力プロファイルを取得/更新する | +| `/api/resilience/reset` | 投稿 | サーキットブレーカーをリセットする | +| `/api/rate-limits` | 入手 | アカウントごとのレート制限ステータス | +| `/api/rate-limit` | 入手 | グローバルレート制限の設定 | + +### 評価 + +| エンドポイント | 方法 | 説明 | +| -------------- | --------- | --------------------------------- | +| `/api/evals` | 取得/投稿 | 評価スイートのリスト / 評価の実行 | + +### ポリシー + +| エンドポイント | 方法 | 説明 | +| --------------- | -------------- | ------------------------------- | +| `/api/policies` | 取得/投稿/削除 | ルーティング ポリシーを管理する | + +### コンプライアンス + +| エンドポイント | 方法 | 説明 | +| --------------------------- | ---- | ----------------------------------- | +| `/api/compliance/audit-log` | 入手 | コンプライアンス監査ログ (最後の N) | + +### v1beta (Gemini 互換) + +| エンドポイント | 方法 | 説明 | +| -------------------------- | ---- | --------------------------------------- | +| `/v1beta/models` | 入手 | Gemini 形式でモデルをリストする | +| `/v1beta/models/{...path}` | 投稿 | Gemini `generateContent` エンドポイント | + +これらのエンドポイントは、ネイティブの Gemini SDK 互換性を期待するクライアント向けに、Gemini の API 形式を反映しています。 + +### 内部/システム API + +| エンドポイント | 方法 | 説明 | +| --------------- | ---- | --------------------------------------------------- | +| `/api/init` | 入手 | アプリケーション初期化チェック (最初の実行時に使用) | +| `/api/tags` | 入手 | Ollama 互換モデル タグ (Ollama クライアント用) | +| `/api/restart` | 投稿 | サーバーの正常な再起動をトリガーする | +| `/api/shutdown` | 投稿 | サーバーの正常なシャットダウンをトリガーする | + +> **注:** これらのエンドポイントは、システムによって内部的に使用されるか、Ollama クライアントの互換性のために使用されます。通常、これらはエンド ユーザーによって呼び出されることはありません。 + +--- + +## 音声文字起こし + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Deepgram または AssemblyAI を使用して音声ファイルを文字起こしします。 + +**リクエスト:** + +```bash +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@recording.mp3" \ + -F "model=deepgram/nova-3" +``` + +**応答:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**サポートされているプロバイダー:** `deepgram/nova-3`、`assemblyai/best`。 + +**サポートされている形式:** `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 + +--- + +## Ollama の互換性 + +Ollama の API 形式を使用するクライアントの場合: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +リクエストは、Ollama 形式と内部形式の間で自動的に変換されます。 + +--- + +## テレメトリ + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**応答:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## 予算 + +```bash +# Get budget status for all API keys +GET /api/usage/budget + +# Set or update a budget +POST /api/usage/budget +Content-Type: application/json + +{ + "keyId": "key-123", + "limit": 50.00, + "period": "monthly" +} +``` + +--- + +## モデルの利用可能性 + +```bash +# Get real-time model availability across all providers +GET /api/models/availability + +# Check availability for a specific model +POST /api/models/availability +Content-Type: application/json + +{ + "model": "claude-sonnet-4-5-20250929" +} +``` + +--- + +## リクエストの処理 + +1. クライアントはリクエストを `/v1/*` に送信します +2. ルート ハンドラーが `handleChat`、`handleEmbedding`、`handleAudioTranscription`、または `handleImageGeneration` を呼び出します。 +3. モデルが解決されます (直接プロバイダー/モデルまたはエイリアス/コンボ) +4. アカウント可用性フィルタリングを使用してローカル DB から選択された資格情報 +5. チャットの場合: `handleChatCore` — フォーマット検出、変換、キャッシュ チェック、冪等性チェック +6. プロバイダーエグゼキューターがアップストリームリクエストを送信します +7. 応答はクライアント形式に変換されるか (チャット)、またはそのまま返されます (埋め込み/画像/音声) +8. 使用状況/ログの記録 +9. フォールバックはコンボルールに従ってエラーに適用されます + +完全なアーキテクチャリファレンス: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## 認証 + +- ダッシュボード ルート (`/dashboard/*`) は `auth_token` Cookie を使用します +- ログインには保存されたパスワード ハッシュが使用されます。 `INITIAL_PASSWORD` へのフォールバック +- `requireLogin` は `/api/settings/require-login` 経由で切り替え可能 +- `/v1/*` ルートでは、`REQUIRE_API_KEY=true` の場合、オプションでベアラー API キーが必要です diff --git a/docs/i18n/ja/ARCHITECTURE.md b/docs/i18n/ja/ARCHITECTURE.md new file mode 100644 index 00000000..60bddbb1 --- /dev/null +++ b/docs/i18n/ja/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# オムニルート アーキテクチャ + +🌐 **Languages:** 🇺🇸 [English](../../ARCHITECTURE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/ARCHITECTURE.md) | 🇪🇸 [Español](../es/ARCHITECTURE.md) | 🇫🇷 [Français](../fr/ARCHITECTURE.md) | 🇮🇹 [Italiano](../it/ARCHITECTURE.md) | 🇷🇺 [Русский](../ru/ARCHITECTURE.md) | 🇨🇳 [中文 (简体)](../zh-CN/ARCHITECTURE.md) | 🇩🇪 [Deutsch](../de/ARCHITECTURE.md) | 🇮🇳 [हिन्दी](../in/ARCHITECTURE.md) | 🇹🇭 [ไทย](../th/ARCHITECTURE.md) | 🇺🇦 [Українська](../uk-UA/ARCHITECTURE.md) | 🇸🇦 [العربية](../ar/ARCHITECTURE.md) | 🇯🇵 [日本語](../ja/ARCHITECTURE.md) | 🇻🇳 [Tiếng Việt](../vi/ARCHITECTURE.md) | 🇧🇬 [Български](../bg/ARCHITECTURE.md) | 🇩🇰 [Dansk](../da/ARCHITECTURE.md) | 🇫🇮 [Suomi](../fi/ARCHITECTURE.md) | 🇮🇱 [עברית](../he/ARCHITECTURE.md) | 🇭🇺 [Magyar](../hu/ARCHITECTURE.md) | 🇮🇩 [Bahasa Indonesia](../id/ARCHITECTURE.md) | 🇰🇷 [한국어](../ko/ARCHITECTURE.md) | 🇲🇾 [Bahasa Melayu](../ms/ARCHITECTURE.md) | 🇳🇱 [Nederlands](../nl/ARCHITECTURE.md) | 🇳🇴 [Norsk](../no/ARCHITECTURE.md) | 🇵🇹 [Português (Portugal)](../pt/ARCHITECTURE.md) | 🇷🇴 [Română](../ro/ARCHITECTURE.md) | 🇵🇱 [Polski](../pl/ARCHITECTURE.md) | 🇸🇰 [Slovenčina](../sk/ARCHITECTURE.md) | 🇸🇪 [Svenska](../sv/ARCHITECTURE.md) | 🇵🇭 [Filipino](../phi/ARCHITECTURE.md) + +_最終更新日: 2026-02-18_ + +## エグゼクティブサマリー + +OmniRoute は、Next.js 上に構築されたローカル AI ルーティング ゲートウェイおよびダッシュボードです。 +これは、単一の OpenAI 互換エンドポイント (`/v1/*`) を提供し、変換、フォールバック、トークン更新、および使用状況追跡を使用して複数の上流プロバイダー間でトラフィックをルーティングします。 + +コア機能: + +- CLI/ツール用の OpenAI 互換 API サーフェス (28 プロバイダー) +- プロバイダ形式間でのリクエスト/レスポンスの変換 +- モデル コンボ フォールバック (マルチモデル シーケンス) +- アカウントレベルのフォールバック (プロバイダーごとにマルチアカウント) +- OAuth + APIキープロバイダ接続管理 +- `/v1/embeddings` による埋め込み生成 (6 プロバイダー、9 モデル) +- `/v1/images/generations` によるイメージ生成 (4 プロバイダー、9 モデル) +- 推論モデルのタグ解析 (`...`) を考える +- 厳密な OpenAI SDK 互換性のための応答のサニタイズ +- プロバイダー間の互換性のための役割の正規化 (開発者→システム、システム→ユーザー) +- 構造化出力変換 (json_schema → Gemini responseSchema) +- プロバイダー、キー、エイリアス、コンボ、設定、価格設定のローカル永続性 +- 使用量/コストの追跡とリクエストのロギング +- マルチデバイス/状態同期のためのオプションのクラウド同期 +- API アクセス制御用の IP 許可リスト/ブロックリスト +- 予算管理を考える (パススルー/自動/カスタム/アダプティブ) +- グローバル システム プロンプト インジェクション +- セッション追跡とフィンガープリンティング +- プロバイダー固有のプロファイルによるアカウントごとの強化されたレート制限 +- プロバイダーの回復力を高めるサーキット ブレーカー パターン +- ミューテックスロックによるアンチサンダーリング保護 +- 署名ベースのリクエスト重複排除キャッシュ +- ドメイン層: モデルの可用性、コスト ルール、フォールバック ポリシー、ロックアウト ポリシー +- ドメイン状態の永続性 (フォールバック、バジェット、ロックアウト、サーキット ブレーカー用の SQLite ライトスルー キャッシュ) +- リクエストを一元的に評価するためのポリシー エンジン (ロックアウト → 予算 → フォールバック) +- p50/p95/p99 レイテンシ集約を使用したテレメトリのリクエスト +- エンドツーエンド トレース用の相関 ID (X-Request-Id) +- API キーごとのオプトアウトによるコンプライアンス監査ログ +- LLM品質保証のための評価フレームワーク +- リアルタイムのサーキット ブレーカー ステータスを備えた Resilience UI ダッシュボード +- モジュラー OAuth プロバイダー (`src/lib/oauth/providers/` の下の 12 個の個別モジュール) + +プライマリ ランタイム モデル: + +- `src/app/api/*` の下の Next.js アプリ ルートは、ダッシュボード API と互換性 API の両方を実装します +- `src/sse/*` + `open-sse/*` の共有 SSE/ルーティング コアは、プロバイダーの実行、変換、ストリーミング、フォールバック、および使用法を処理します。 + +## 範囲と境界 + +### 範囲内 + +- ローカルゲートウェイランタイム +- ダッシュボード管理 API +- プロバイダー認証とトークンの更新 +- 翻訳と SSE ストリーミングのリクエスト +- ローカル状態 + 使用状況の永続性 +- オプションのクラウド同期オーケストレーション + +### 範囲外 + +- `NEXT_PUBLIC_CLOUD_URL` の背後にあるクラウド サービスの実装 +- ローカル プロセス外のプロバイダー SLA/コントロール プレーン +- 外部 CLI バイナリ自体 (Claude CLI、Codex CLI など) + +## 高レベルのシステムコンテキスト + +```mermaid +flowchart LR + subgraph Clients[Developer Clients] + C1[Claude Code] + C2[Codex CLI] + C3[OpenClaw / Droid / Cline / Continue / Roo] + C4[Custom OpenAI-compatible clients] + BROWSER[Browser Dashboard] + end + + subgraph Router[OmniRoute Local Process] + API[V1 Compatibility API\n/v1/*] + DASH[Dashboard + Management API\n/api/*] + CORE[SSE + Translation Core\nopen-sse + src/sse] + DB[(db.json)] + UDB[(usage.json + log.txt)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/iFlow/GitHub/Kiro/Cursor/Antigravity] + P2[API Key Providers\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA] + P3[Compatible Nodes\nOpenAI-compatible / Anthropic-compatible] + end + + subgraph Cloud[Optional Cloud Sync] + CLOUD[Cloud Sync Endpoint\nNEXT_PUBLIC_CLOUD_URL] + end + + C1 --> API + C2 --> API + C3 --> API + C4 --> API + BROWSER --> DASH + + API --> CORE + DASH --> DB + CORE --> DB + CORE --> UDB + + CORE --> P1 + CORE --> P2 + CORE --> P3 + + DASH --> CLOUD +``` + +## コア ランタイム コンポーネント + +## 1) API とルーティング レイヤー (Next.js アプリ ルート) + +メインディレクトリ: + +- `src/app/api/v1/*` および `src/app/api/v1beta/*` (互換性 API) +- `src/app/api/*` 管理/構成 API 用 +- 次に、`next.config.mjs` で書き換えて、`/v1/*` を `/api/v1/*` にマップします。 + +重要な互換性ルート: + +- `src/app/api/v1/chat/completions/route.ts` +- `src/app/api/v1/messages/route.ts` +- `src/app/api/v1/responses/route.ts` +- `src/app/api/v1/models/route.ts` — `custom: true` のカスタム モデルが含まれます +- `src/app/api/v1/embeddings/route.ts` — 埋め込み生成 (6 プロバイダー) +- `src/app/api/v1/images/generations/route.ts` — 画像生成 (Antigravity/Nebius を含む 4 つ以上のプロバイダー) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — プロバイダーごとの専用チャット +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — プロバイダーごとの専用埋め込み +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — プロバイダーごとの専用イメージ +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +管理ドメイン: + +- 認証/設定: `src/app/api/auth/*`、`src/app/api/settings/*` +- プロバイダー/接続: `src/app/api/providers*` +- プロバイダーノード: `src/app/api/provider-nodes*` +- カスタム モデル: `src/app/api/provider-models` (GET/POST/DELETE) +- モデルカタログ: `src/app/api/models/catalog` (GET) +- プロキシ構成: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- キー/エイリアス/コンボ/価格: `src/app/api/keys*`、`src/app/api/models/alias`、`src/app/api/combos*`、`src/app/api/pricing` +- 使用法: `src/app/api/usage/*` +- 同期/クラウド: `src/app/api/sync/*`、`src/app/api/cloud/*` +- CLI ツールヘルパー: `src/app/api/cli-tools/*` +- IP フィルター: `src/app/api/settings/ip-filter` (GET/PUT) +- 検討予算: `src/app/api/settings/thinking-budget` (GET/PUT) +- システム プロンプト: `src/app/api/settings/system-prompt` (GET/PUT) +- セッション: `src/app/api/sessions` (GET) +- レート制限: `src/app/api/rate-limits` (GET) +- 復元力: `src/app/api/resilience` (GET/PATCH) — プロバイダー プロファイル、サーキット ブレーカー、レート制限状態 +- レジリエンスのリセット: `src/app/api/resilience/reset` (POST) — ブレーカー + クールダウンをリセット +- キャッシュ統計: `src/app/api/cache/stats` (GET/DELETE) +- 利用可能なモデル: `src/app/api/models/availability` (GET/POST) +- テレメトリ: `src/app/api/telemetry/summary` (GET) +- 予算: `src/app/api/usage/budget` (GET/POST) +- フォールバック チェーン: `src/app/api/fallback/chains` (GET/POST/DELETE) +- コンプライアンス監査: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST)、`src/app/api/evals/[suiteId]` (GET) +- ポリシー: `src/app/api/policies` (GET/POST) + +## 2) SSE + 翻訳コア + +メインフローモジュール: + +- エントリ: `src/sse/handlers/chat.ts` +- コアオーケストレーション: `open-sse/handlers/chatCore.ts` +- プロバイダー実行アダプター: `open-sse/executors/*` +- フォーマット検出/プロバイダー構成: `open-sse/services/provider.ts` +- モデル解析/解決: `src/sse/services/model.ts`、`open-sse/services/model.ts` +- アカウントのフォールバック ロジック: `open-sse/services/accountFallback.ts` +- 翻訳レジストリ: `open-sse/translator/index.ts` +- ストリーム変換: `open-sse/utils/stream.ts`、`open-sse/utils/streamHandler.ts` +- 使用量の抽出/正規化: `open-sse/utils/usageTracking.ts` +- シンクタグパーサー: `open-sse/utils/thinkTagParser.ts` +- 埋め込みハンドラー: `open-sse/handlers/embeddings.ts` +- 埋め込みプロバイダー レジストリ: `open-sse/config/embeddingRegistry.ts` +- 画像生成ハンドラー: `open-sse/handlers/imageGeneration.ts` +- イメージプロバイダーレジストリ: `open-sse/config/imageRegistry.ts` +- 応答のサニタイズ: `open-sse/handlers/responseSanitizer.ts` +- ロールの正規化: `open-sse/services/roleNormalizer.ts` + +サービス (ビジネス ロジック): + +- アカウントの選択/スコアリング: `open-sse/services/accountSelector.ts` +- コンテキストのライフサイクル管理: `open-sse/services/contextManager.ts` +- IP フィルターの適用: `open-sse/services/ipFilter.ts` +- セッション追跡: `open-sse/services/sessionManager.ts` +- 重複排除のリクエスト: `open-sse/services/signatureCache.ts` +- システムプロンプトインジェクション: `open-sse/services/systemPrompt.ts` +- 予算管理を考える: `open-sse/services/thinkingBudget.ts` +- ワイルドカード モデル ルーティング: `open-sse/services/wildcardRouter.ts` +- レート制限管理: `open-sse/services/rateLimitManager.ts` +- サーキットブレーカー: `open-sse/services/circuitBreaker.ts` + +ドメイン層モジュール: + +- 利用可能なモデル: `src/lib/domain/modelAvailability.ts` +- コストルール/予算: `src/lib/domain/costRules.ts` +- フォールバック ポリシー: `src/lib/domain/fallbackPolicy.ts` +- コンボリゾルバー: `src/lib/domain/comboResolver.ts` +- ロックアウト ポリシー: `src/lib/domain/lockoutPolicy.ts` +- ポリシー エンジン: `src/domain/policyEngine.ts` — 集中ロックアウト → 予算 → フォールバック評価 +- エラーコードカタログ: `src/lib/domain/errorCodes.ts` +- リクエストID: `src/lib/domain/requestId.ts` +- フェッチタイムアウト: `src/lib/domain/fetchTimeout.ts` +- テレメトリのリクエスト: `src/lib/domain/requestTelemetry.ts` +- コンプライアンス/監査: `src/lib/domain/compliance/index.ts` +- 評価ランナー: `src/lib/domain/evalRunner.ts` +- ドメイン状態の永続性: `src/lib/db/domainState.ts` — フォールバック チェーン、予算、コスト履歴、ロックアウト状態、サーキット ブレーカー用の SQLite CRUD + +OAuth プロバイダー モジュール (`src/lib/oauth/providers/` の下の 12 個の個別ファイル): + +- レジストリ インデックス: `src/lib/oauth/providers/index.ts` +- 個別プロバイダー: `claude.ts`、`codex.ts`、`gemini.ts`、`antigravity.ts`、`iflow.ts`、`qwen.ts`、`kimi-coding.ts`、`github.ts`、 `kiro.ts`、`cursor.ts`、`kilocode.ts`、`cline.ts` +- 薄いラッパー: `src/lib/oauth/providers.ts` — 個々のモジュールからの再エクスポート + +## 3) 永続層 + +プライマリ状態 DB: + +- `src/lib/localDb.ts` +- ファイル: `${DATA_DIR}/db.json` (設定されている場合は `$XDG_CONFIG_HOME/omniroute/db.json`、それ以外の場合は `~/.omniroute/db.json`) +- エンティティ: ProviderConnections、providerNodes、modelAliases、コンボ、apiKeys、設定、価格設定、**customModels**、**proxyConfig**、**ipFilter**、** ThinkingBudget**、**systemPrompt** + +使用状況DB: + +- `src/lib/usageDb.ts` +- ファイル: `${DATA_DIR}/usage.json`、`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/` +- `localDb` と同じベース ディレクトリ ポリシーに従います (`DATA_DIR`、設定されている場合は `XDG_CONFIG_HOME/omniroute`) +- 重点的なサブモジュールに分解: `migrations.ts`、`usageHistory.ts`、`costCalculator.ts`、`usageStats.ts`、`callLogs.ts` + +ドメイン状態 DB (SQLite): + +- `src/lib/db/domainState.ts` — ドメイン状態の CRUD 操作 +- テーブル (`src/lib/db/core.ts` で作成): `domain_fallback_chains`、`domain_budgets`、`domain_cost_history`、`domain_lockout_state`、`domain_circuit_breakers` +- ライトスルー キャッシュ パターン: メモリ内マップは実行時に権限を持ちます。変更は SQLite に同期的に書き込まれます。状態はコールド スタート時に DB から復元されます + +## 4) 認証 + セキュリティ サーフェス + +- ダッシュボード Cookie 認証: `src/proxy.ts`、`src/app/api/auth/login/route.ts` +- API キーの生成/検証: `src/shared/utils/apiKey.ts` +- プロバイダーのシークレットは `providerConnections` エントリに保持されます +- `open-sse/utils/proxyFetch.ts` (環境変数) および `open-sse/utils/networkProxy.ts` (プロバイダーごとまたはグローバルに構成可能) による送信プロキシのサポート + +## 5) クラウド同期 + +- スケジューラの初期化: `src/lib/initCloudSync.ts`、`src/shared/services/initializeCloudSync.ts` +- 定期タスク: `src/shared/services/cloudSyncScheduler.ts` +- 制御ルート: `src/app/api/sync/cloud/route.ts` + +## リクエストのライフサイクル (`/v1/chat/completions`) + +```mermaid +sequenceDiagram + autonumber + participant Client as CLI/SDK Client + participant Route as /api/v1/chat/completions + participant Chat as src/sse/handlers/chat + participant Core as open-sse/handlers/chatCore + participant Model as Model Resolver + participant Auth as Credential Selector + participant Exec as Provider Executor + participant Prov as Upstream Provider + participant Stream as Stream Translator + participant Usage as usageDb + + Client->>Route: POST /v1/chat/completions + Route->>Chat: handleChat(request) + Chat->>Model: parse/resolve model or combo + + alt Combo model + Chat->>Chat: iterate combo models (handleComboChat) + end + + Chat->>Auth: getProviderCredentials(provider) + Auth-->>Chat: active account + tokens/api key + + Chat->>Core: handleChatCore(body, modelInfo, credentials) + Core->>Core: detect source format + Core->>Core: translate request to target format + Core->>Exec: execute(provider, transformedBody) + Exec->>Prov: upstream API call + Prov-->>Exec: SSE/JSON response + Exec-->>Core: response + metadata + + alt 401/403 + Core->>Exec: refreshCredentials() + Exec-->>Core: updated tokens + Core->>Exec: retry request + end + + Core->>Stream: translate/normalize stream to client format + Stream-->>Client: SSE chunks / JSON response + + Stream->>Usage: extract usage + persist history/log +``` + +## コンボ + アカウントのフォールバック フロー + +```mermaid +flowchart TD + A[Incoming model string] --> B{Is combo name?} + B -- Yes --> C[Load combo models sequence] + B -- No --> D[Single model path] + + C --> E[Try model N] + E --> F[Resolve provider/model] + D --> F + + F --> G[Select account credentials] + G --> H{Credentials available?} + H -- No --> I[Return provider unavailable] + H -- Yes --> J[Execute request] + + J --> K{Success?} + K -- Yes --> L[Return response] + K -- No --> M{Fallback-eligible error?} + + M -- No --> N[Return error] + M -- Yes --> O[Mark account unavailable cooldown] + O --> P{Another account for provider?} + P -- Yes --> G + P -- No --> Q{In combo with next model?} + Q -- Yes --> E + Q -- No --> R[Return all unavailable] +``` + +フォールバックの決定は、ステータス コードとエラー メッセージのヒューリスティックを使用して、`open-sse/services/accountFallback.ts` によって行われます。 + +## OAuth オンボーディングとトークン更新のライフサイクル + +```mermaid +sequenceDiagram + autonumber + participant UI as Dashboard UI + participant OAuth as /api/oauth/[provider]/[action] + participant ProvAuth as Provider Auth Server + participant DB as localDb + participant Test as /api/providers/[id]/test + participant Exec as Provider Executor + + UI->>OAuth: GET authorize or device-code + OAuth->>ProvAuth: create auth/device flow + ProvAuth-->>OAuth: auth URL or device code payload + OAuth-->>UI: flow data + + UI->>OAuth: POST exchange or poll + OAuth->>ProvAuth: token exchange/poll + ProvAuth-->>OAuth: access/refresh tokens + OAuth->>DB: createProviderConnection(oauth data) + OAuth-->>UI: success + connection id + + UI->>Test: POST /api/providers/[id]/test + Test->>Exec: validate credentials / optional refresh + Exec-->>Test: valid or refreshed token info + Test->>DB: update status/tokens/errors + Test-->>UI: validation result +``` + +ライブ トラフィック中の更新は、エグゼキュータ `refreshCredentials()` を介して `open-sse/handlers/chatCore.ts` 内で実行されます。 + +## クラウド同期ライフサイクル (有効化/同期/無効化) + +```mermaid +sequenceDiagram + autonumber + participant UI as Endpoint Page UI + participant Sync as /api/sync/cloud + participant DB as localDb + participant Cloud as External Cloud Sync + participant Claude as ~/.claude/settings.json + + UI->>Sync: POST action=enable + Sync->>DB: set cloudEnabled=true + Sync->>DB: ensure API key exists + Sync->>Cloud: POST /sync/{machineId} (providers/aliases/combos/keys) + Cloud-->>Sync: sync result + Sync->>Cloud: GET /{machineId}/v1/verify + Sync-->>UI: enabled + verification status + + UI->>Sync: POST action=sync + Sync->>Cloud: POST /sync/{machineId} + Cloud-->>Sync: remote data + Sync->>DB: update newer local tokens/status + Sync-->>UI: synced + + UI->>Sync: POST action=disable + Sync->>DB: set cloudEnabled=false + Sync->>Cloud: DELETE /sync/{machineId} + Sync->>Claude: switch ANTHROPIC_BASE_URL back to local (if needed) + Sync-->>UI: disabled +``` + +クラウドが有効な場合、定期的な同期は `CloudSyncScheduler` によってトリガーされます。 + +## データモデルとストレージマップ + +```mermaid +erDiagram + SETTINGS ||--o{ PROVIDER_CONNECTION : controls + PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : backs_compatible_provider + PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : emits_usage + + SETTINGS { + boolean cloudEnabled + number stickyRoundRobinLimit + boolean requireLogin + string password_hash + string fallbackStrategy + json rateLimitDefaults + json providerProfiles + } + + PROVIDER_CONNECTION { + string id + string provider + string authType + string name + number priority + boolean isActive + string apiKey + string accessToken + string refreshToken + string expiresAt + string testStatus + string lastError + string rateLimitedUntil + json providerSpecificData + } + + PROVIDER_NODE { + string id + string type + string name + string prefix + string apiType + string baseUrl + } + + MODEL_ALIAS { + string alias + string targetModel + } + + COMBO { + string id + string name + string[] models + } + + API_KEY { + string id + string name + string key + string machineId + } + + USAGE_ENTRY { + string provider + string model + number prompt_tokens + number completion_tokens + string connectionId + string timestamp + } + + CUSTOM_MODEL { + string id + string name + string providerId + } + + PROXY_CONFIG { + string global + json providers + } + + IP_FILTER { + string mode + string[] allowlist + string[] blocklist + } + + THINKING_BUDGET { + string mode + number customBudget + string effortLevel + } + + SYSTEM_PROMPT { + boolean enabled + string prompt + string position + } +``` + +物理ストレージ ファイル: + +- メイン状態: `${DATA_DIR}/db.json` (設定されている場合は `$XDG_CONFIG_HOME/omniroute/db.json`、それ以外の場合は `~/.omniroute/db.json`) +- 使用状況統計: `${DATA_DIR}/usage.json` +- リクエストログ行: `${DATA_DIR}/log.txt` +- オプションのトランスレータ/リクエスト デバッグ セッション: `/logs/...` + +## デプロイメントトポロジ + +```mermaid +flowchart LR + subgraph LocalHost[Developer Host] + CLI[CLI Tools] + Browser[Dashboard Browser] + end + + subgraph ContainerOrProcess[OmniRoute Runtime] + Next[Next.js Server\nPORT=20128] + Core[SSE Core + Executors] + MainDB[(db.json)] + UsageDB[(usage.json/log.txt)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## モジュール マッピング (意思決定が重要) + +### ルートと API モジュール + +- `src/app/api/v1/*`、`src/app/api/v1beta/*`: 互換性 API +- `src/app/api/v1/providers/[provider]/*`: プロバイダーごとの専用ルート (チャット、埋め込み、画像) +- `src/app/api/providers*`: プロバイダー CRUD、検証、テスト +- `src/app/api/provider-nodes*`: カスタム互換ノード管理 +- `src/app/api/provider-models`: カスタム モデル管理 (CRUD) +- `src/app/api/models/catalog`: 完全なモデル カタログ API (プロバイダーごとにグループ化されたすべてのタイプ) +- `src/app/api/oauth/*`: OAuth/デバイスコードフロー +- `src/app/api/keys*`: ローカル API キーのライフサイクル +- `src/app/api/models/alias`: エイリアス管理 +- `src/app/api/combos*`: フォールバック コンボ管理 +- `src/app/api/pricing`: コスト計算のための価格設定の上書き +- `src/app/api/settings/proxy`: プロキシ構成 (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: 送信プロキシ接続テスト (POST) +- `src/app/api/usage/*`: 使用状況とログ API +- `src/app/api/sync/*` + `src/app/api/cloud/*`: クラウド同期およびクラウド対応ヘルパー +- `src/app/api/cli-tools/*`: ローカル CLI 構成ライター/チェッカー +- `src/app/api/settings/ip-filter`: IP 許可リスト/ブロックリスト (GET/PUT) +- `src/app/api/settings/thinking-budget`: 思考トークン予算構成 (GET/PUT) +- `src/app/api/settings/system-prompt`: グローバル システム プロンプト (GET/PUT) +- `src/app/api/sessions`: アクティブなセッションのリスト (GET) +- `src/app/api/rate-limits`: アカウントごとのレート制限ステータス (GET) + +### ルーティングおよび実行コア + +- `src/sse/handlers/chat.ts`: リクエスト解析、コンボ処理、アカウント選択ループ +- `open-sse/handlers/chatCore.ts`: 変換、実行プログラムのディスパッチ、再試行/リフレッシュ処理、ストリームのセットアップ +- `open-sse/executors/*`: プロバイダー固有のネットワークと形式の動作 + +### 翻訳レジストリとフォーマットコンバータ + +- `open-sse/translator/index.ts`: トランスレータ レジストリとオーケストレーション +- 翻訳者のリクエスト: `open-sse/translator/request/*` +- 応答翻訳者: `open-sse/translator/response/*` +- フォーマット定数: `open-sse/translator/formats.ts` + +### 永続性 + +- `src/lib/localDb.ts`: 永続的な構成/状態 +- `src/lib/usageDb.ts`: 使用履歴とローリングリクエストログ + +## Provider Executor カバレッジ (戦略パターン) + +各プロバイダーには、`BaseExecutor` (`open-sse/executors/base.ts` 内) を拡張する特殊なエグゼキューターがあり、URL の構築、ヘッダーの構築、指数バックオフによる再試行、資格情報の更新フック、および `execute()` オーケストレーション メソッドを提供します。 + +| 執行者 | プロバイダー | 特殊な取り扱い | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI、Claude、Gemini、Qwen、iFlow、OpenRouter、GLM、Kimi、MiniMax、DeepSeek、Groq、xAI、Mistral、Perplexity、Togetter、Fireworks、Cerebros、Cohere、NVIDIA | プロバイダーごとの動的 URL/ヘッダー構成 | +| `AntigravityExecutor` | Google 反重力 | カスタム プロジェクト/セッション ID、解析後の再試行 | +| `CodexExecutor` | OpenAI コーデックス | システム命令を挿入し、推論努力を強制する | +| `CursorExecutor` | カーソルIDE | ConnectRPC プロトコル、Protobuf エンコーディング、チェックサムによる要求署名 | +| `GithubExecutor` | GitHub コパイロット | コパイロット トークンの更新、VSCode を模倣したヘッダー | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream バイナリ形式 → SSE 変換 | +| `GeminiCLIExecutor` | ジェミニ CLI | Google OAuth トークンの更新サイクル | + +他のすべてのプロバイダー (カスタム互換ノードを含む) は `DefaultExecutor` を使用します。 + +## プロバイダー互換性マトリックス + +| プロバイダー | フォーマット | 認証 | ストリーム | 非ストリーム | トークンのリフレッシュ | 使用法 API | +| --------------------- | ------------------ | ----------------------------- | ----------------------- | ------------ | ---------------------- | ----------------------------- | +| クロード | クロード | APIキー/OAuth | ✅ | ✅ | ✅ | ⚠️管理者のみ | +| ジェミニ | ジェミニ | APIキー/OAuth | ✅ | ✅ | ✅ | ⚠️クラウドコンソール | +| ジェミニ CLI | ジェミニクリ | OAuth | ✅ | ✅ | ✅ | ⚠️クラウドコンソール | +| 反重力 | 反重力 | OAuth | ✅ | ✅ | ✅ | ✅ フルクォータ API | +| オープンAI | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| コーデックス | オープンナイの応答 | OAuth | ✅強制 | ❌ | ✅ | ✅ レート制限 | +| GitHub コパイロット | オープンナイ | OAuth + コパイロット トークン | ✅ | ✅ | ✅ | ✅ クォータのスナップショット | +| カーソル | カーソル | カスタムチェックサム | ✅ | ✅ | ❌ | ❌ | +| キロ | キロ | AWS SSO OIDC | ✅ (イベントストリーム) | ❌ | ✅ | ✅ 使用制限 | +| クウェン | オープンナイ | OAuth | ✅ | ✅ | ✅ | ⚠️リクエストに応じて | +| iFlow | オープンナイ | OAuth (基本) | ✅ | ✅ | ✅ | ⚠️リクエストに応じて | +| オープンルーター | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| GLM/キミ/ミニマックス | クロード | APIキー | ✅ | ✅ | ❌ | ❌ | +| ディープシーク | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| グロク | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| xAI (グロック) | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| ミストラル | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| 困惑 | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| 一緒にAI | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| 花火AI | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| 大脳 | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| コヒア | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | オープンナイ | APIキー | ✅ | ✅ | ❌ | ❌ | + +## フォーマット翻訳の範囲 + +検出されたソース形式は次のとおりです。 + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +対象となる形式は次のとおりです。 + +- OpenAI チャット/応答 +- クロード +- ジェミニ/ジェミニ-CLI/反重力エンベロープ +- キロ +- カーソル + +翻訳では **OpenAI をハブ形式**として使用します。すべての変換は中間として OpenAI を経由します。 + +``` +Source Format → OpenAI (hub) → Target Format +``` + +翻訳は、ソース ペイロードの形状とプロバイダーのターゲット形式に基づいて動的に選択されます。 + +翻訳パイプラインの追加の処理レイヤー: + +- **レスポンスのサニタイズ** — OpenAI 形式のレスポンス (ストリーミングと非ストリーミングの両方) から非標準フィールドを削除し、厳密な SDK コンプライアンスを確保します。 +- **ロールの正規化** — 非 OpenAI ターゲットの場合は `developer` → `system` を変換します。システムロールを拒否するモデル (GLM、ERNIE) の `system` → `user` をマージします。 +- **思考タグ抽出** — コンテンツから `...` ブロックを解析して `reasoning_content` フィールドに変換します +- **構造化出力** — OpenAI `response_format.json_schema` を Gemini の `responseMimeType` + `responseSchema` に変換します + +## サポートされる API エンドポイント + +| エンドポイント | フォーマット | ハンドラー | +| -------------------------------------------------- | --------------------- | --------------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAIチャット | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | クロードのメッセージ | 同じハンドラー (自動検出) | +| `POST /v1/responses` | OpenAI の応答 | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI 埋め込み | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | モデル一覧 | APIルート | +| `POST /v1/images/generations` | OpenAI 画像 | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | モデル一覧 | APIルート | +| `POST /v1/providers/{provider}/chat/completions` | OpenAIチャット | モデル検証を備えた専用のプロバイダーごと | +| `POST /v1/providers/{provider}/embeddings` | OpenAI 埋め込み | モデル検証を備えた専用のプロバイダーごと | +| `POST /v1/providers/{provider}/images/generations` | OpenAI 画像 | モデル検証を備えた専用のプロバイダーごと | +| `POST /v1/messages/count_tokens` | クロードトークン数 | APIルート | +| `GET /v1/models` | OpenAI モデルのリスト | API ルート (チャット + 埋め込み + 画像 + カスタム モデル) | +| `GET /api/models/catalog` | カタログ | プロバイダー + タイプごとにグループ化されたすべてのモデル | +| `POST /v1beta/models/*:streamGenerateContent` | 双子座出身 | APIルート | +| `GET/PUT/DELETE /api/settings/proxy` | プロキシ構成 | ネットワークプロキシ構成 | +| `POST /api/settings/proxy/test` | プロキシ接続 | プロキシの健全性/接続テスト エンドポイント | +| `GET/POST/DELETE /api/provider-models` | カスタムモデル | プロバイダーごとのカスタム モデル管理 | + +## バイパスハンドラー + +バイパス ハンドラー (`open-sse/utils/bypassHandler.ts`) は、Claude CLI からの既知の「使い捨て」リクエスト (ウォームアップ ping、タイトル抽出、トークン カウント) をインターセプトし、アップストリーム プロバイダー トークンを消費せずに **偽の応答** を返します。これは、`User-Agent` に `claude-cli` が含まれている場合にのみトリガーされます。 + +## リクエストロガーパイプライン + +リクエスト ロガー (`open-sse/utils/requestLogger.ts`) は、7 段階のデバッグ ロギング パイプラインを提供します。デフォルトでは無効になっており、`ENABLE_REQUEST_LOGS=true` によって有効になります。 + +``` +1_req_client.json → 2_req_source.json → 3_req_openai.json → 4_req_target.json +→ 5_res_provider.txt → 6_res_openai.txt → 7_res_client.txt +``` + +ファイルはリクエスト セッションごとに `/logs//` に書き込まれます。 + +## 障害モードと回復力 + +## 1) アカウント/プロバイダーの可用性 + +- 一時的/レート/認証エラー時のプロバイダー アカウントのクールダウン +- リクエストが失敗する前のアカウントのフォールバック +- 現在のモデル/プロバイダー パスが枯渇した場合のコンボ モデル フォールバック + +## 2) トークンの有効期限 + +- 更新可能なプロバイダーの事前チェックと再試行による更新 +- コア パスでの更新試行後の 401/403 再試行 + +## 3) ストリームの安全性 + +- 切断対応ストリーム コントローラー +- ストリーム終了フラッシュと `[DONE]` 処理を備えた変換ストリーム +- プロバイダーの使用量メタデータが欠落している場合の使用量推定フォールバック + +## 4) クラウド同期の低下 + +- 同期エラーが表面化しましたが、ローカル ランタイムは継続します +- スケジューラには再試行可能なロジックがありますが、定期的な実行では現在、デフォルトで単一試行同期が呼び出されます。 + +## 5) データの整合性 + +- DB 形状の移行/欠落キーの修復 +- localDb と useDb に対する破損した JSON リセットの保護策 + +## 可観測性と動作信号 + +実行時の可視性ソース: + +- `src/sse/utils/logger.ts` からのコンソール ログ +- `usage.json` でのリクエストごとの使用量の集計 +- `log.txt` のテキスト形式のリクエスト ステータス ログ +- `ENABLE_REQUEST_LOGS=true` の場合、`logs/` の下のオプションの詳細なリクエスト/変換ログ +- UI 消費のためのダッシュボード使用エンドポイント (`/api/usage/*`) + +## セキュリティに注意が必要な境界 + +- JWT シークレット (`JWT_SECRET`) により、ダッシュボード セッションの Cookie 検証/署名が保護されます +- 初期パスワード フォールバック (`INITIAL_PASSWORD`、デフォルト `123456`) は実際のデプロイメントではオーバーライドする必要があります +- API キー HMAC シークレット (`API_KEY_SECRET`) は、生成されたローカル API キー形式を保護します +- プロバイダーのシークレット (API キー/トークン) はローカル DB に保存され、ファイルシステム レベルで保護される必要があります。 +- クラウド同期エンドポイントは、API キー認証 + マシン ID セマンティクスに依存します。 + +## 環境とランタイムのマトリックス + +コードによってアクティブに使用される環境変数: + +- アプリ/認証: `JWT_SECRET`、`INITIAL_PASSWORD` +- ストレージ: `DATA_DIR` +- 互換性のあるノードの動作: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- オプションのストレージ ベース オーバーライド (Linux/macOS `DATA_DIR` が設定されていない場合): `XDG_CONFIG_HOME` +- セキュリティハッシュ: `API_KEY_SECRET`、`MACHINE_ID_SALT` +- ロギング: `ENABLE_REQUEST_LOGS` +- 同期/クラウド URL: `NEXT_PUBLIC_BASE_URL`、`NEXT_PUBLIC_CLOUD_URL` +- 送信プロキシ: `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY` および小文字のバリアント +- SOCKS5 機能フラグ: `ENABLE_SOCKS5_PROXY`、`NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- プラットフォーム/ランタイム ヘルパー (アプリ固有の構成ではない): `APPDATA`、`NODE_ENV`、`PORT`、`HOSTNAME` + +## 既知のアーキテクチャに関するメモ + +1. `usageDb` と `localDb` は、レガシー ファイル移行と同じベース ディレクトリ ポリシー (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) を共有するようになりました。 +2. `/api/v1/route.ts` は静的モデル リストを返しますが、`/v1/models` によって使用されるメイン モデル ソースではありません。 +3. リクエスト ロガーは有効な場合、完全なヘッダー/本文を書き込みます。ログ ディレクトリを機密として扱います。 +4. クラウドの動作は、正しい `NEXT_PUBLIC_BASE_URL` とクラウド エンドポイントの到達可能性に依存します。 +5. `open-sse/` ディレクトリは、`@omniroute/open-sse` **npm ワークスペース パッケージ**として公開されます。ソース コードは `@omniroute/open-sse/...` 経由でインポートします (Next.js `transpilePackages` によって解決されます)。このドキュメントのファイル パスでは、一貫性を保つために引き続きディレクトリ名 `open-sse/` が使用されています。 +6. ダッシュボードのグラフでは、**Recharts** (SVG ベース) を使用して、アクセスしやすく対話型の分析を視覚化します (モデル使用状況の棒グラフ、成功率を示すプロバイダーの内訳表)。 +7. E2E テストは **Playwright** (`tests/e2e/`) を使用し、`npm run test:e2e` 経由で実行します。単体テストは **Node.js テスト ランナー** (`tests/unit/`) を使用し、`npm run test:plan3` 経由で実行されます。 `src/` のソース コードは **TypeScript** (`.ts`/`.tsx`) です。 `open-sse/` ワークスペースは JavaScript (`.js`) のままです。 +8. 設定ページは 5 つのタブで構成されています: セキュリティ、ルーティング (6 つのグローバル戦略: フィルファースト、ラウンドロビン、p2c、ランダム、最小使用、コスト最適化)、復元力 (編集可能なレート制限、サーキット ブレーカー、ポリシー)、AI (思考予算、システム プロンプト、プロンプト キャッシュ)、詳細 (プロキシ)。 + +## 動作検証チェックリスト + +- ソースからビルド: `npm run build` +- Docker イメージのビルド: `docker build -t omniroute .` +- サービスを開始して以下を確認します。 +- `GET /api/settings` +- `GET /api/v1/models` +- `PORT=20128` の場合、CLI ターゲット ベース URL は `http://:20128/v1` である必要があります。 diff --git a/docs/i18n/ja/CODEBASE_DOCUMENTATION.md b/docs/i18n/ja/CODEBASE_DOCUMENTATION.md new file mode 100644 index 00000000..68557a14 --- /dev/null +++ b/docs/i18n/ja/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +🌐 **Languages:** 🇺🇸 [English](../../CODEBASE_DOCUMENTATION.md) | 🇧🇷 [Português (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | 🇪🇸 [Español](../es/CODEBASE_DOCUMENTATION.md) | 🇫🇷 [Français](../fr/CODEBASE_DOCUMENTATION.md) | 🇮🇹 [Italiano](../it/CODEBASE_DOCUMENTATION.md) | 🇷🇺 [Русский](../ru/CODEBASE_DOCUMENTATION.md) | 🇨🇳 [中文 (简体)](../zh-CN/CODEBASE_DOCUMENTATION.md) | 🇩🇪 [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | 🇮🇳 [हिन्दी](../in/CODEBASE_DOCUMENTATION.md) | 🇹🇭 [ไทย](../th/CODEBASE_DOCUMENTATION.md) | 🇺🇦 [Українська](../uk-UA/CODEBASE_DOCUMENTATION.md) | 🇸🇦 [العربية](../ar/CODEBASE_DOCUMENTATION.md) | 🇯🇵 [日本語](../ja/CODEBASE_DOCUMENTATION.md) | 🇻🇳 [Tiếng Việt](../vi/CODEBASE_DOCUMENTATION.md) | 🇧🇬 [Български](../bg/CODEBASE_DOCUMENTATION.md) | 🇩🇰 [Dansk](../da/CODEBASE_DOCUMENTATION.md) | 🇫🇮 [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | 🇮🇱 [עברית](../he/CODEBASE_DOCUMENTATION.md) | 🇭🇺 [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | 🇮🇩 [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | 🇰🇷 [한국어](../ko/CODEBASE_DOCUMENTATION.md) | 🇲🇾 [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | 🇳🇱 [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | 🇳🇴 [Norsk](../no/CODEBASE_DOCUMENTATION.md) | 🇵🇹 [Português (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | 🇷🇴 [Română](../ro/CODEBASE_DOCUMENTATION.md) | 🇵🇱 [Polski](../pl/CODEBASE_DOCUMENTATION.md) | 🇸🇰 [Slovenčina](../sk/CODEBASE_DOCUMENTATION.md) | 🇸🇪 [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | 🇵🇭 [Filipino](../phi/CODEBASE_DOCUMENTATION.md) + +#omniroute — コードベースのドキュメント + +> **omniroute** マルチプロバイダー AI プロキシ ルーターに関する初心者向けの包括的なガイド。 + +--- + +## 1. オムニルートとは何ですか? + +オムニルートは、AI クライアント (Claude CLI、Codex、Cursor IDE など) と AI プロバイダー (Anthropic、Google、OpenAI、AWS、GitHub など) の間に位置する **プロキシ ルーター** です。これにより、1 つの大きな問題が解決されます。 + +> **異なる AI クライアントは異なる「言語」(API 形式) を話し、異なる AI プロバイダーも異なる「言語」を期待します。** オムニルートはそれらの間で自動的に翻訳します。 + +これを国連の万能翻訳者のようなものだと考えてください。どの代表者もあらゆる言語を話すことができ、翻訳者は他の代表者のためにそれを変換します。 + +--- + +## 2. アーキテクチャの概要 + +```mermaid +graph LR + subgraph Clients + A[Claude CLI] + B[Codex] + C[Cursor IDE] + D[OpenAI-compatible] + end + + subgraph omniroute + E[Handler Layer] + F[Translator Layer] + G[Executor Layer] + H[Services Layer] + end + + subgraph Providers + I[Anthropic Claude] + J[Google Gemini] + K[OpenAI / Codex] + L[GitHub Copilot] + M[AWS Kiro] + N[Antigravity] + O[Cursor API] + end + + A --> E + B --> E + C --> E + D --> E + E --> F + F --> G + G --> I + G --> J + G --> K + G --> L + G --> M + G --> N + G --> O + H -.-> E + H -.-> G +``` + +### 基本原則: ハブアンドスポーク変換 + +すべての形式変換は、**OpenAI 形式をハブとして** 通過します。 + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +これは、**N²** (ペアごと) ではなく、**N トランスレーター** (フォーマットごとに 1 人) だけが必要であることを意味します。 + +--- + +## 3. プロジェクトの構造 + +``` +omniroute/ +├── open-sse/ ← Core proxy library (portable, framework-agnostic) +│ ├── index.js ← Main entry point, exports everything +│ ├── config/ ← Configuration & constants +│ ├── executors/ ← Provider-specific request execution +│ ├── handlers/ ← Request handling orchestration +│ ├── services/ ← Business logic (auth, models, fallback, usage) +│ ├── translator/ ← Format translation engine +│ │ ├── request/ ← Request translators (8 files) +│ │ ├── response/ ← Response translators (7 files) +│ │ └── helpers/ ← Shared translation utilities (6 files) +│ └── utils/ ← Utility functions +├── src/ ← Application layer (Express/Worker runtime) +│ ├── app/ ← Web UI, API routes, middleware +│ ├── lib/ ← Database, auth, and shared library code +│ ├── mitm/ ← Man-in-the-middle proxy utilities +│ ├── models/ ← Database models +│ ├── shared/ ← Shared utilities (wrappers around open-sse) +│ ├── sse/ ← SSE endpoint handlers +│ └── store/ ← State management +├── data/ ← Runtime data (credentials, logs) +│ └── provider-credentials.json (external credentials override, gitignored) +└── tester/ ← Test utilities +``` + +--- + +## 4. モジュールごとの内訳 + +### 4.1 構成 (`open-sse/config/`) + +すべてのプロバイダー構成に関する **唯一の信頼できる情報源**。 + +| ファイル | 目的 | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` オブジェクトには、ベース URL、OAuth 資格情報 (デフォルト)、ヘッダー、および各プロバイダーのデフォルトのシステム プロンプトが含​​まれます。 `HTTP_STATUS`、`ERROR_TYPES`、`COOLDOWN_MS`、`BACKOFF_CONFIG`、および `SKIP_PATTERNS` も定義します。 | +| `credentialLoader.ts` | `data/provider-credentials.json` から外部資格情報をロードし、`PROVIDERS` のハードコードされたデフォルトにそれらをマージします。下位互換性を維持しながら、秘密をソース管理から除外します。 | +| `providerModels.ts` | 中央モデル レジストリ: プロバイダーのエイリアス → モデル ID をマップします。 `getModels()`、`getProviderByAlias()` のような関数。 | +| `codexInstructions.ts` | Codex リクエストに挿入されるシステム命令 (編集制約、サンドボックス ルール、承認ポリシー)。 | +| `defaultThinkingSignature.ts` | Claude モデルと Gemini モデルのデフォルトの「思考」シグネチャ。 | +| `ollamaModels.ts` | ローカル Ollama モデルのスキーマ定義 (名前、サイズ、ファミリー、量子化)。 | + +#### 認証情報の読み込みフロー + +```mermaid +flowchart TD + A["App starts"] --> B["constants.ts defines PROVIDERS\nwith hardcoded defaults"] + B --> C{"data/provider-credentials.json\nexists?"} + C -->|Yes| D["credentialLoader reads JSON"] + C -->|No| E["Use hardcoded defaults"] + D --> F{"For each provider in JSON"} + F --> G{"Provider exists\nin PROVIDERS?"} + G -->|No| H["Log warning, skip"] + G -->|Yes| I{"Value is object?"} + I -->|No| J["Log warning, skip"] + I -->|Yes| K["Merge clientId, clientSecret,\ntokenUrl, authUrl, refreshUrl"] + K --> F + H --> F + J --> F + F -->|Done| L["PROVIDERS ready with\nmerged credentials"] + E --> L +``` + +--- + +### 4.2 実行者 (`open-sse/executors/`) + +エグゼキュータは、**戦略パターン**を使用して**プロバイダ固有のロジック**をカプセル化します。各エグゼキュータは、必要に応じて基本メソッドをオーバーライドします。 + +```mermaid +classDiagram + class BaseExecutor { + +buildUrl(model, stream, options) + +buildHeaders(credentials, stream, body) + +transformRequest(body, model, stream, credentials) + +execute(url, options) + +shouldRetry(status, error) + +refreshCredentials(credentials, log) + } + + class DefaultExecutor { + +refreshCredentials() + } + + class AntigravityExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +shouldRetry() + +refreshCredentials() + } + + class CursorExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseResponse() + +generateChecksum() + } + + class KiroExecutor { + +buildUrl() + +buildHeaders() + +transformRequest() + +parseEventStream() + +refreshCredentials() + } + + BaseExecutor <|-- DefaultExecutor + BaseExecutor <|-- AntigravityExecutor + BaseExecutor <|-- CursorExecutor + BaseExecutor <|-- KiroExecutor + BaseExecutor <|-- CodexExecutor + BaseExecutor <|-- GeminiCLIExecutor + BaseExecutor <|-- GithubExecutor +``` + +| 執行者 | プロバイダー | 主な専門分野 | +| ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | 抽象ベース: URL 構築、ヘッダー、再試行ロジック、資格情報の更新 | +| `default.ts` | クロード、ジェミニ、OpenAI、GLM、キミ、MiniMax | 標準プロバイダーの汎用 OAuth トークンの更新 | +| `antigravity.ts` | Googleクラウドコード | プロジェクト/セッション ID の生成、マルチ URL フォールバック、エラー メッセージからのカスタム再試行解析 (「2 時間 7 分 23 秒後にリセット」) | +| `cursor.ts` | カーソルIDE | **最も複雑**: SHA-256 チェックサム認証、Protobuf リクエスト エンコード、バイナリ EventStream → SSE レスポンス解析 | +| `codex.ts` | OpenAI コーデックス | システム命令の挿入、思考レベルの管理、サポートされていないパラメータの削除 | +| `gemini-cli.ts` | Google Gemini CLI | カスタム URL の構築 (`streamGenerateContent`)、Google OAuth トークンの更新 | +| `github.ts` | GitHub コパイロット | デュアル トークン システム (GitHub OAuth + Copilot トークン)、VSCode ヘッダーの模倣 | +| `kiro.ts` | AWS CodeWhisperer | AWS EventStream バイナリ解析、AMZN イベント フレーム、トークン推定 | +| `index.ts` | — | ファクトリ: デフォルトのフォールバックを使用して、プロバイダー名 → エグゼキューター クラスをマップします。 | + +--- + +### 4.3 ハンドラー (`open-sse/handlers/`) + +**オーケストレーション レイヤー** — 変換、実行、ストリーミング、エラー処理を調整します。 + +| ファイル | 目的 | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **中央オーケストレーター** (約 600 行)。リクエストのライフサイクル全体を処理します: フォーマット検出→変換→エグゼキュータディスパッチ→ストリーミング/非ストリーミング応答→トークン更新→エラー処理→使用状況ログ。 | +| `responsesHandler.ts` | OpenAI の応答 API 用アダプター: 応答形式を変換 → チャット完了 → `chatCore` に送信 → SSE を応答形式に変換します。 | +| `embeddings.ts` | 埋め込み生成ハンドラー: 埋め込みモデル→プロバイダーを解決し、プロバイダー API にディスパッチし、OpenAI 互換の埋め込み応答を返します。 6 つ以上のプロバイダーをサポートします。 | +| `imageGeneration.ts` | イメージ生成ハンドラー: イメージ モデル → プロバイダーを解決し、OpenAI 互換、Gemini イメージ (Antigravity)、およびフォールバック (Nebius) モードをサポートします。 Base64 または URL イメージを返します。 | + +#### リクエストのライフサイクル (chatCore.ts) + +```mermaid +sequenceDiagram + participant Client + participant chatCore + participant Translator + participant Executor + participant Provider + + Client->>chatCore: Request (any format) + chatCore->>chatCore: Detect source format + chatCore->>chatCore: Check bypass patterns + chatCore->>chatCore: Resolve model & provider + chatCore->>Translator: Translate request (source → OpenAI → target) + chatCore->>Executor: Get executor for provider + Executor->>Executor: Build URL, headers, transform request + Executor->>Executor: Refresh credentials if needed + Executor->>Provider: HTTP fetch (streaming or non-streaming) + + alt Streaming + Provider-->>chatCore: SSE stream + chatCore->>chatCore: Pipe through SSE transform stream + Note over chatCore: Transform stream translates
each chunk: target → OpenAI → source + chatCore-->>Client: Translated SSE stream + else Non-streaming + Provider-->>chatCore: JSON response + chatCore->>Translator: Translate response + chatCore-->>Client: Translated JSON + end + + alt Error (401, 429, 500...) + chatCore->>Executor: Retry with credential refresh + chatCore->>chatCore: Account fallback logic + end +``` + +--- + +### 4.4 サービス (`open-sse/services/`) + +ハンドラーとエグゼキューターをサポートするビジネス ロジック。 + +| ファイル | 目的 | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **形式検出** (`detectFormat`): リクエスト本文の構造を分析して、Claude/OpenAI/Gemini/Antigravity/Responses 形式を識別します (Claude の `max_tokens` ヒューリスティックを含む)。また、URL の構築、ヘッダーの構築、思考構成の正規化も行います。 `openai-compatible-*` および `anthropic-compatible-*` 動的プロバイダーをサポートします。 | +| `model.ts` | モデル文字列解析 (`claude/model-name` → `{provider: "claude", model: "model-name"}`)、衝突検出によるエイリアス解決、入力サニタイズ (パス トラバーサル/制御文字の拒否)、および非同期エイリアス ゲッター サポートによるモデル情報解決。 | +| `accountFallback.ts` | レート制限の処理: 指数関数的バックオフ (1 秒 → 2 秒 → 4 秒 → 最大 2 分)、アカウントのクールダウン管理、エラー分類 (どのエラーがフォールバックをトリガーするのか、トリガーしないのか)。 | +| `tokenRefresh.ts` | **すべてのプロバイダ**の OAuth トークン更新: Google (Gemini、Antigravity)、Claude、Codex、Qwen、iFlow、GitHub (OAuth + Copilot デュアル トークン)、Kiro (AWS SSO OIDC + Social Auth)。実行中の Promise 重複排除キャッシュと指数バックオフによる再試行が含まれます。 | +| `combo.ts` | **コンボ モデル**: フォールバック モデルのチェーン。モデル A がフォールバック対象エラーで失敗した場合は、モデル B、次にモデル C などを試します。実際のアップストリーム ステータス コードを返します。 | +| `usage.ts` | プロバイダー API からクォータ/使用量データを取得します (GitHub Copilot クォータ、反重力モデル クォータ、Codex レート制限、Kiro 使用量の内訳、Claude 設定)。 | +| `accountSelector.ts` | スコアリング アルゴリズムを使用したスマートなアカウント選択: 優先度、健全性ステータス、ラウンドロビン ポジション、クールダウン状態を考慮して、各リクエストに最適なアカウントを選択します。 | +| `contextManager.ts` | リクエスト コンテキストのライフサイクル管理: デバッグとロギングのために、メタデータ (リクエスト ID、タイムスタンプ、プロバイダー情報) を含むリクエストごとのコンテキスト オブジェクトを作成および追跡します。 | +| `ipFilter.ts` | IP ベースのアクセス制御: ホワイトリスト モードとブロックリスト モードをサポートします。 API リクエストを処理する前に、設定されたルールに照らしてクライアント IP を検証します。 | +| `sessionManager.ts` | クライアント フィンガープリントによるセッション追跡: ハッシュされたクライアント ID を使用してアクティブなセッションを追跡し、リクエスト数を監視し、セッション メトリックを提供します。 | +| `signatureCache.ts` | リクエスト署名ベースの重複排除キャッシュ: 最近のリクエスト署名をキャッシュし、時間枠内の同一リクエストに対してキャッシュされた応答を返すことで、リクエストの重複を防ぎます。 | +| `systemPrompt.ts` | グローバル システム プロンプト インジェクション: プロバイダーごとの互換性処理を使用して、構成可能なシステム プロンプトをすべてのリクエストの先頭または末尾に追加します。 | +| `thinkingBudget.ts` | 推論トークンの予算管理: 思考/推論トークンを制御するためのパススルー、自動 (ストリップ思考構成)、カスタム (固定予算)、および適応型 (複雑さスケール) モードをサポートします。 | +| `wildcardRouter.ts` | ワイルドカード モデル パターン ルーティング: 可用性と優先度に基づいて、ワイルドカード パターン (`*/claude-*` など) を具体的なプロバイダー/モデルのペアに解決します。 | + +#### トークンのリフレッシュの重複排除 + +```mermaid +sequenceDiagram + participant R1 as Request 1 + participant R2 as Request 2 + participant Cache as refreshPromiseCache + participant OAuth as OAuth Provider + + R1->>Cache: getAccessToken("gemini", token) + Cache->>Cache: No in-flight promise + Cache->>OAuth: Start refresh + R2->>Cache: getAccessToken("gemini", token) + Cache->>Cache: Found in-flight promise + Cache-->>R2: Return existing promise + OAuth-->>Cache: New access token + Cache-->>R1: New access token + Cache-->>R2: Same access token (shared) + Cache->>Cache: Delete cache entry +``` + +#### アカウント フォールバック ステート マシン + +```mermaid +stateDiagram-v2 + [*] --> Active + Active --> Error: Request fails (401/429/500) + Error --> Cooldown: Apply backoff + Cooldown --> Active: Cooldown expires + Active --> Active: Request succeeds (reset backoff) + + state Error { + [*] --> ClassifyError + ClassifyError --> ShouldFallback: Rate limit / Auth / Transient + ClassifyError --> NoFallback: 400 Bad Request + } + + state Cooldown { + [*] --> ExponentialBackoff + ExponentialBackoff: Level 0 = 1s + ExponentialBackoff: Level 1 = 2s + ExponentialBackoff: Level 2 = 4s + ExponentialBackoff: Max = 2min + } +``` + +#### コンボ モデル チェーン + +```mermaid +flowchart LR + A["Request with\ncombo model"] --> B["Model A"] + B -->|"2xx Success"| C["Return response"] + B -->|"429/401/500"| D{"Fallback\neligible?"} + D -->|Yes| E["Model B"] + D -->|No| F["Return error"] + E -->|"2xx Success"| C + E -->|"429/401/500"| G{"Fallback\neligible?"} + G -->|Yes| H["Model C"] + G -->|No| F + H -->|"2xx Success"| C + H -->|"Fail"| I["All failed →\nReturn last status"] +``` + +--- + +### 4.5 トランスレータ (`open-sse/translator/`) + +自己登録プラグイン システムを使用した **フォーマット変換エンジン**。 + +#### アーキテクチャ + +```mermaid +graph TD + subgraph "Request Translation" + A["Claude → OpenAI"] + B["Gemini → OpenAI"] + C["Antigravity → OpenAI"] + D["OpenAI Responses → OpenAI"] + E["OpenAI → Claude"] + F["OpenAI → Gemini"] + G["OpenAI → Kiro"] + H["OpenAI → Cursor"] + end + + subgraph "Response Translation" + I["Claude → OpenAI"] + J["Gemini → OpenAI"] + K["Kiro → OpenAI"] + L["Cursor → OpenAI"] + M["OpenAI → Claude"] + N["OpenAI → Antigravity"] + O["OpenAI → Responses"] + end +``` + +| ディレクトリ | ファイル | 説明 | +| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 翻訳者8名 | リクエストボディをフォーマット間で変換します。各ファイルは、インポート時に `register(from, to, fn)` を介して自己登録されます。 | +| `response/` | 翻訳者 7 名 | ストリーミング応答チャンクをフォーマット間で変換します。 SSE イベント タイプ、思考ブロック、ツール呼び出しを処理します。 | +| `helpers/` | 6人のヘルパー | 共有ユーティリティ: `claudeHelper` (システム プロンプト抽出、シンキング構成)、`geminiHelper` (パーツ/コンテンツ マッピング)、`openaiHelper` (フォーマット フィルタリング)、`toolCallHelper` (ID 生成、欠落応答挿入)、`maxTokensHelper`、`responsesApiHelper`。 | +| `index.ts` | — | 変換エンジン: `translateRequest()`、`translateResponse()`、状態管理、レジストリ。 | +| `formats.ts` | — | フォーマット定数: `OPENAI`、`CLAUDE`、`GEMINI`、`ANTIGRAVITY`、`KIRO`、`CURSOR`、`OPENAI_RESPONSES`。 | + +#### 主な設計: 自己登録プラグイン + +```javascript +// Each translator file calls register() on import: +import { register } from "../index.js"; +register("claude", "openai", translateClaudeToOpenAI); + +// The index.js imports all translator files, triggering registration: +import "./request/claude-to-openai.js"; // ← self-registers +``` + +--- + +### 4.6 ユーティリティ (`open-sse/utils/`) + +| ファイル | 目的 | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | エラー応答の構築 (OpenAI 互換形式)、アップストリーム エラー解析、エラー メッセージからの反重力再試行時間の抽出、SSE エラー ストリーミング。 | +| `stream.ts` | **SSE Transform Stream** — コア ストリーミング パイプライン。 2 つのモード: `TRANSLATE` (完全な形式の変換) と `PASSTHROUGH` (正規化 + 使用法の抽出)。チャンクのバッファリング、使用量の推定、コンテンツの長さの追跡を処理します。ストリームごとのエンコーダ/デコーダ インスタンスは共有状態を回避します。 | +| `streamHelpers.ts` | 低レベル SSE ユーティリティ: `parseSSELine` (ホワイトスペース耐性)、`hasValuableContent` (OpenAI/Claude/Gemini の空のチャンクをフィルタリング)、`fixInvalidId`、`formatSSE` (`perf_metrics` クリーンアップによる形式認識 SSE シリアル化)。 | +| `usageTracking.ts` | 任意の形式 (Claude/OpenAI/Gemini/Responses) からのトークン使用量の抽出、別個のツール/メッセージの文字数とトークンの比率による推定、バッファーの追加 (2000 トークンの安全マージン)、形式固有のフィールド フィルタリング、ANSI カラーでのコンソール ロギング。 | +| `requestLogger.ts` | ファイルベースのリクエストログ (`ENABLE_REQUEST_LOGS=true` によるオプトイン)。番号付きファイルを含むセッション フォルダーを作成します: `1_req_client.json` → `7_res_client.txt`。すべての I/O は非同期 (ファイア アンド フォーゲット) です。機密ヘッダーをマスクします。 | +| `bypassHandler.ts` | Claude CLI からの特定のパターン (タイトル抽出、ウォームアップ、カウント) を傍受し、プロバイダーを呼び出さずに偽の応答を返します。ストリーミングと非ストリーミングの両方をサポートします。意図的に Claude CLI スコープに限定されています。 | +| `networkProxy.ts` | 指定されたプロバイダーの送信プロキシ URL を優先順位で解決します: プロバイダー固有の構成 → グローバル構成 → 環境変数 (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`)。 `NO_PROXY` の除外をサポートします。設定を 30 秒間キャッシュします。 | + +#### SSE ストリーミング パイプライン + +```mermaid +flowchart TD + A["Provider SSE stream"] --> B["TextDecoder\n(per-stream instance)"] + B --> C["Buffer lines\n(split on newline)"] + C --> D["parseSSELine()\n(trim whitespace, parse JSON)"] + D --> E{"Mode?"} + E -->|TRANSLATE| F["translateResponse()\ntarget → OpenAI → source"] + E -->|PASSTHROUGH| G["fixInvalidId()\nnormalize chunk"] + F --> H["hasValuableContent()\nfilter empty chunks"] + G --> H + H -->|"Has content"| I["extractUsage()\ntrack token counts"] + H -->|"Empty"| J["Skip chunk"] + I --> K["formatSSE()\nserialize + clean perf_metrics"] + K --> L["TextEncoder\n(per-stream instance)"] + L --> M["Enqueue to\nclient stream"] + + style A fill:#f9f,stroke:#333 + style M fill:#9f9,stroke:#333 +``` + +#### リクエスト ロガー セッション構造 + +``` +logs/ +└── claude_gemini_claude-sonnet_20260208_143045/ + ├── 1_req_client.json ← Raw client request + ├── 2_req_source.json ← After initial conversion + ├── 3_req_openai.json ← OpenAI intermediate format + ├── 4_req_target.json ← Final target format + ├── 5_res_provider.txt ← Provider SSE chunks (streaming) + ├── 5_res_provider.json ← Provider response (non-streaming) + ├── 6_res_openai.txt ← OpenAI intermediate chunks + ├── 7_res_client.txt ← Client-facing SSE chunks + └── 6_error.json ← Error details (if any) +``` + +--- + +### 4.7 アプリケーション層 (`src/`) + +| ディレクトリ | 目的 | +| ------------- | ---------------------------------------------------------------------------- | +| `src/app/` | Web UI、API ルート、Express ミドルウェア、OAuth コールバック ハンドラー | +| `src/lib/` | データベース アクセス (`localDb.ts`、`usageDb.ts`)、認証、共有 | +| `src/mitm/` | プロバイダーのトラフィックを傍受する中間者プロキシ ユーティリティ | +| `src/models/` | データベースモデルの定義 | +| `src/shared/` | open-sse 関数 (プロバイダー、ストリーム、エラーなど) のラッパー | +| `src/sse/` | open-sse ライブラリを Express ルートに接続する SSE エンドポイント ハンドラー | +| `src/store/` | アプリケーション状態管理 | + +#### 注目すべき API ルート + +| ルート | メソッド | 目的 | +| --------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- | +| `/api/provider-models` | 取得/投稿/削除 | プロバイダーごとのカスタム モデルの CRUD | +| `/api/models/catalog` | 入手 | プロバイダーごとにグループ化されたすべてのモデル (チャット、埋め込み、イメージ、カスタム) の集約カタログ | +| `/api/settings/proxy` | 取得/挿入/削除 | 階層型送信プロキシ構成 (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | 投稿 | プロキシ接続を検証し、パブリック IP/遅延を返します。 | +| `/v1/providers/[provider]/chat/completions` | 投稿 | モデル検証を備えたプロバイダーごとの専用チャット補完 | +| `/v1/providers/[provider]/embeddings` | 投稿 | モデル検証を備えたプロバイダーごとの専用埋め込み | +| `/v1/providers/[provider]/images/generations` | 投稿 | モデル検証を備えたプロバイダーごとの専用イメージ生成 | +| `/api/settings/ip-filter` | GET/PUT | IP ホワイトリスト/ブロックリスト管理 | +| `/api/settings/thinking-budget` | GET/PUT | 推論トークンの予算構成 (パススルー/自動/カスタム/アダプティブ) | +| `/api/settings/system-prompt` | GET/PUT | すべてのリクエストに対するグローバル システム プロンプト インジェクション | +| `/api/sessions` | 入手 | アクティブなセッションの追跡とメトリクス | +| `/api/rate-limits` | 入手 | アカウントごとのレート制限ステータス | + +--- + +## 5. 主要な設計パターン + +### 5.1 ハブアンドスポーク変換 + +すべての形式は **OpenAI 形式をハブ**として変換します。新しいプロバイダーを追加するには、N ペアではなく、**1 ペア** のトランスレーター (OpenAI との間) を作成するだけで済みます。 + +### 5.2 エグゼキューター戦略パターン + +各プロバイダーには、`BaseExecutor` を継承する専用の実行クラスがあります。 `executors/index.ts` のファクトリは、実行時に正しいものを選択します。 + +### 5.3 自己登録プラグイン システム + +トランスレータ モジュールは、インポート時に `register()` を介して自身を登録します。新しいトランスレータを追加するには、ファイルを作成してインポートするだけです。 + +### 5.4 指数関数的バックオフによるアカウントのフォールバック + +プロバイダーが 429/401/500 を返すと、システムは次のアカウントに切り替えて、指数関数的なクールダウン (1 秒 → 2 秒 → 4 秒 → 最大 2 分) を適用できます。 + +### 5.5 コンボモデルチェーン + +「コンボ」は、複数の `provider/model` 文字列をグループ化します。最初の処理が失敗した場合は、自動的に次の処理にフォールバックします。 + +### 5.6 ステートフル ストリーミング変換 + +応答の変換は、`initState()` メカニズムを介して、SSE チャンク全体 (思考ブロックの追跡、ツール呼び出しの蓄積、コンテンツ ブロックのインデックス作成) の状態を維持します。 + +### 5.7 使用安全バッファー + +システム プロンプトや形式変換によるオーバーヘッドによってクライアントがコンテキスト ウィンドウの制限に達するのを防ぐために、報告された使用量に 2000 トークンのバッファーが追加されます。 + +--- + +## 6. サポートされている形式 + +| フォーマット | 方向 | 識別子 | +| --------------------- | ------------------- | ------------------ | +| OpenAI チャットの完了 | ソース + ターゲット | `openai` | +| OpenAI レスポンス API | ソース + ターゲット | `openai-responses` | +| 人間のクロード | ソース + ターゲット | `claude` | +| Google ジェミニ | ソース + ターゲット | `gemini` | +| Google Gemini CLI | ターゲットのみ | `gemini-cli` | +| 反重力 | ソース + ターゲット | `antigravity` | +| AWS キロ | ターゲットのみ | `kiro` | +| カーソル | ターゲットのみ | `cursor` | + +--- + +## 7. サポートされているプロバイダー + +| プロバイダー | 認証方法 | 執行者 | 重要なメモ | +| ------------------------ | ----------------------------- | ------------ | ----------------------------------------------------------- | +| 人間のクロード | API キーまたは OAuth | デフォルト | `x-api-key` ヘッダーを使用します。 | +| Google ジェミニ | API キーまたは OAuth | デフォルト | `x-goog-api-key` ヘッダーを使用します。 | +| Google Gemini CLI | OAuth | ジェミニCLI | `streamGenerateContent` エンドポイントを使用します。 | +| 反重力 | OAuth | 反重力 | マルチ URL フォールバック、カスタム再試行解析 | +| オープンAI | APIキー | デフォルト | 標準ベアラー認証 | +| コーデックス | OAuth | コーデックス | システム命令を注入し、思考を管理します | +| GitHub コパイロット | OAuth + コパイロット トークン | ギットハブ | デュアル トークン、VSCode ヘッダーの模倣 | +| キロ (AWS) | AWS SSO OIDC またはソーシャル | キロ | バイナリ EventStream 解析 | +| カーソルIDE | チェックサム認証 | カーソル | Protobuf エンコーディング、SHA-256 チェックサム | +| クウェン | OAuth | デフォルト | 標準認証 | +| iFlow | OAuth (ベーシック + ベアラー) | デフォルト | デュアル認証ヘッダー | +| オープンルーター | APIキー | デフォルト | 標準ベアラー認証 | +| GLM、キミ、ミニマックス | APIキー | デフォルト | Claude と互換性があるため、`x-api-key` を使用してください。 | +| `openai-compatible-*` | APIキー | デフォルト | 動的: 任意の OpenAI 互換エンドポイント | +| `anthropic-compatible-*` | APIキー | デフォルト | 動的: クロードと互換性のある任意のエンドポイント | + +--- + +## 8. データフローの概要 + +### ストリーミングリクエスト + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor\nbuildUrl + buildHeaders"] + D --> E["fetch(providerURL)"] + E --> F["createSSEStream()\nTRANSLATE mode"] + F --> G["parseSSELine()"] + G --> H["translateResponse()\ntarget → OpenAI → source"] + H --> I["extractUsage()\n+ addBuffer"] + I --> J["formatSSE()"] + J --> K["Client receives\ntranslated SSE"] + K --> L["logUsage()\nsaveRequestUsage()"] +``` + +### 非ストリーミングリクエスト + +```mermaid +flowchart LR + A["Client"] --> B["detectFormat()"] + B --> C["translateRequest()\nsource → OpenAI → target"] + C --> D["Executor.execute()"] + D --> E["translateResponse()\ntarget → OpenAI → source"] + E --> F["Return JSON\nresponse"] +``` + +### バイパス フロー (Claude CLI) + +```mermaid +flowchart LR + A["Claude CLI request"] --> B{"Match bypass\npattern?"} + B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] + B -->|"No match"| D["Normal flow"] + C --> E["Translate to\nsource format"] + E --> F["Return without\ncalling provider"] +``` diff --git a/docs/i18n/ja/FEATURES.md b/docs/i18n/ja/FEATURES.md new file mode 100644 index 00000000..19e62357 --- /dev/null +++ b/docs/i18n/ja/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — ダッシュボード機能ギャラリー + +🌐 **Languages:** 🇺🇸 [English](../../FEATURES.md) | 🇧🇷 [Português (Brasil)](../pt-BR/FEATURES.md) | 🇪🇸 [Español](../es/FEATURES.md) | 🇫🇷 [Français](../fr/FEATURES.md) | 🇮🇹 [Italiano](../it/FEATURES.md) | 🇷🇺 [Русский](../ru/FEATURES.md) | 🇨🇳 [中文 (简体)](../zh-CN/FEATURES.md) | 🇩🇪 [Deutsch](../de/FEATURES.md) | 🇮🇳 [हिन्दी](../in/FEATURES.md) | 🇹🇭 [ไทย](../th/FEATURES.md) | 🇺🇦 [Українська](../uk-UA/FEATURES.md) | 🇸🇦 [العربية](../ar/FEATURES.md) | 🇯🇵 [日本語](../ja/FEATURES.md) | 🇻🇳 [Tiếng Việt](../vi/FEATURES.md) | 🇧🇬 [Български](../bg/FEATURES.md) | 🇩🇰 [Dansk](../da/FEATURES.md) | 🇫🇮 [Suomi](../fi/FEATURES.md) | 🇮🇱 [עברית](../he/FEATURES.md) | 🇭🇺 [Magyar](../hu/FEATURES.md) | 🇮🇩 [Bahasa Indonesia](../id/FEATURES.md) | 🇰🇷 [한국어](../ko/FEATURES.md) | 🇲🇾 [Bahasa Melayu](../ms/FEATURES.md) | 🇳🇱 [Nederlands](../nl/FEATURES.md) | 🇳🇴 [Norsk](../no/FEATURES.md) | 🇵🇹 [Português (Portugal)](../pt/FEATURES.md) | 🇷🇴 [Română](../ro/FEATURES.md) | 🇵🇱 [Polski](../pl/FEATURES.md) | 🇸🇰 [Slovenčina](../sk/FEATURES.md) | 🇸🇪 [Svenska](../sv/FEATURES.md) | 🇵🇭 [Filipino](../phi/FEATURES.md) + +OmniRoute ダッシュボードの各セクションへの視覚的なガイド。 + +--- + +## 🔌 プロバイダー + +AI プロバイダー接続の管理: OAuth プロバイダー (Claude Code、Codex、Gemini CLI)、API キー プロバイダー (Groq、DeepSeek、OpenRouter)、および無料プロバイダー (iFlow、Qwen、Kiro)。 + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨 コンボ + +フィルファースト、ラウンドロビン、2 つのべき乗、ランダム、最小使用、コスト最適化の 6 つの戦略を使用してモデル ルーティング コンボを作成します。各コンボは、自動フォールバックを使用して複数のモデルをチェーンします。 + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 分析 + +トークン消費量、コスト見積もり、アクティビティヒートマップ、週次分布グラフ、プロバイダーごとの内訳を含む包括的な使用状況分析。 + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 システムの健全性 + +リアルタイム監視: 稼働時間、メモリ、バージョン、遅延パーセンタイル (p50/p95/p99)、キャッシュ統計、プロバイダーのサーキット ブレーカーの状態。 + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 翻訳者の遊び場 + +API 変換をデバッグするための 4 つのモード: **プレイグラウンド** (フォーマット コンバーター)、**チャット テスター** (ライブ リクエスト)、**テスト ベンチ** (バッチ テスト)、**ライブ モニター** (リアルタイム ストリーム)。 + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ 設定 + +一般設定、システム ストレージ、バックアップ管理 (データベースのエクスポート/インポート)、外観 (ダーク/ライト モード)、セキュリティ (API エンドポイント保護とカスタム プロバイダーのブロックを含む)、ルーティング、復元力、および詳細な構成。 + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 CLI ツール + +AI コーディング ツールのワンクリック構成: Claude Code、Codex CLI、Gemini CLI、OpenClaw、Kilo Code、Antigravity。 + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 リクエストログ + +プロバイダー、モデル、アカウント、API キーによるフィルタリングを備えたリアルタイムのリクエストログ。ステータス コード、トークンの使用状況、待ち時間、応答の詳細を表示します。 + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 API エンドポイント + +機能の内訳を含む統合 API エンドポイント: チャット完了、埋め込み、画像生成、再ランキング、音声文字起こし、登録された API キー。 + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/ja/TROUBLESHOOTING.md b/docs/i18n/ja/TROUBLESHOOTING.md new file mode 100644 index 00000000..5beec7a9 --- /dev/null +++ b/docs/i18n/ja/TROUBLESHOOTING.md @@ -0,0 +1,216 @@ +# トラブルシューティング + +🌐 **Languages:** 🇺🇸 [English](../../TROUBLESHOOTING.md) | 🇧🇷 [Português (Brasil)](../pt-BR/TROUBLESHOOTING.md) | 🇪🇸 [Español](../es/TROUBLESHOOTING.md) | 🇫🇷 [Français](../fr/TROUBLESHOOTING.md) | 🇮🇹 [Italiano](../it/TROUBLESHOOTING.md) | 🇷🇺 [Русский](../ru/TROUBLESHOOTING.md) | 🇨🇳 [中文 (简体)](../zh-CN/TROUBLESHOOTING.md) | 🇩🇪 [Deutsch](../de/TROUBLESHOOTING.md) | 🇮🇳 [हिन्दी](../in/TROUBLESHOOTING.md) | 🇹🇭 [ไทย](../th/TROUBLESHOOTING.md) | 🇺🇦 [Українська](../uk-UA/TROUBLESHOOTING.md) | 🇸🇦 [العربية](../ar/TROUBLESHOOTING.md) | 🇯🇵 [日本語](../ja/TROUBLESHOOTING.md) | 🇻🇳 [Tiếng Việt](../vi/TROUBLESHOOTING.md) | 🇧🇬 [Български](../bg/TROUBLESHOOTING.md) | 🇩🇰 [Dansk](../da/TROUBLESHOOTING.md) | 🇫🇮 [Suomi](../fi/TROUBLESHOOTING.md) | 🇮🇱 [עברית](../he/TROUBLESHOOTING.md) | 🇭🇺 [Magyar](../hu/TROUBLESHOOTING.md) | 🇮🇩 [Bahasa Indonesia](../id/TROUBLESHOOTING.md) | 🇰🇷 [한국어](../ko/TROUBLESHOOTING.md) | 🇲🇾 [Bahasa Melayu](../ms/TROUBLESHOOTING.md) | 🇳🇱 [Nederlands](../nl/TROUBLESHOOTING.md) | 🇳🇴 [Norsk](../no/TROUBLESHOOTING.md) | 🇵🇹 [Português (Portugal)](../pt/TROUBLESHOOTING.md) | 🇷🇴 [Română](../ro/TROUBLESHOOTING.md) | 🇵🇱 [Polski](../pl/TROUBLESHOOTING.md) | 🇸🇰 [Slovenčina](../sk/TROUBLESHOOTING.md) | 🇸🇪 [Svenska](../sv/TROUBLESHOOTING.md) | 🇵🇭 [Filipino](../phi/TROUBLESHOOTING.md) + +OmniRoute の一般的な問題と解決策。 + +--- + +## クイックフィックス + +| 問題 | ソリューション | +| ----------------------------------------- | ------------------------------------------------------------------------------- | +| 最初のログインが機能しない | `.env` の `INITIAL_PASSWORD` を確認します (デフォルト: `123456`)。 | +| ダッシュボードが間違ったポートで開きます | `PORT=20128` と `NEXT_PUBLIC_BASE_URL=http://localhost:20128` を設定します。 | +| `logs/` の下にリクエスト ログがありません | `ENABLE_REQUEST_LOGS=true` を設定 | +| EACCES: 許可が拒否されました | `DATA_DIR=/path/to/writable/dir` を設定して `~/.omniroute` をオーバーライドする | +| ルーティング戦略が保存されない | v1.4.11+ に更新 (設定永続性のための Zod スキーマ修正) | + +--- + +## プロバイダーの問題 + +### 「言語モデルがメッセージを提供しませんでした」 + +**原因:** プロバイダーの割り当てが枯渇しました。 + +**修正:** + +1. ダッシュボードのクォータ トラッカーを確認する +2. フォールバック層とのコンボを使用する +3. より安価な/無料枠に切り替える + +### レート制限 + +**原因:** サブスクリプション割り当てを使い果たしました。 + +**修正:** + +- フォールバックを追加: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- 安価なバックアップとして GLM/MiniMax を使用する + +### OAuth トークンの有効期限が切れました + +OmniRoute はトークンを自動更新します。問題が解決しない場合: + +1. ダッシュボード → プロバイダー → 再接続 +2. プロバイダー接続を削除して再度追加します。 + +--- + +## クラウドの問題 + +### クラウド同期エラー + +1. `BASE_URL` が実行中のインスタンス (例: `http://localhost:20128`) を指していることを確認します。 +2. `CLOUD_URL` がクラウド エンドポイント (例: `https://omniroute.dev`) を指していることを確認します。 +3. `NEXT_PUBLIC_*` 値をサーバー側の値と一致させておく + +### クラウド `stream=false` は 500 を返します + +**症状:** 非ストリーミング通話のクラウド エンドポイントで `Unexpected token 'd'...` が発生します。 + +**原因:** クライアントが JSON を期待しているのに、アップストリームは SSE ペイロードを返します。 + +**回避策:** クラウド直接呼び出しには `stream=true` を使用します。ローカル ランタイムには SSE→JSON フォールバックが含まれます。 + +### クラウドは接続済みだが「API キーが無効です」と表示します + +1. ローカル ダッシュボードから新しいキーを作成します (`/api/keys`) +2. クラウド同期を実行します: [クラウドを有効にする] → [今すぐ同期] +3. 古い/非同期キーはクラウド上でも `401` を返すことができます + +--- + +## Docker の問題 + +### CLI ツールがインストールされていないと表示される + +1. 実行時フィールドを確認します: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. ポータブル モードの場合: イメージ ターゲット `runner-cli` (バンドルされた CLI) を使用します。 +3. ホスト マウント モードの場合: `CLI_EXTRA_PATHS` を設定し、ホストの bin ディレクトリを読み取り専用としてマウントします。 +4. `installed=true` および `runnable=false` の場合: バイナリは見つかりましたが、ヘルスチェックに失敗しました + +### 迅速なランタイム検証 + +```bash +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}' +``` + +--- + +## コストの問題 + +### 高コスト + +1.「ダッシュボード」→「使用状況」で使用状況統計を確認します。2. プライマリ モデルを GLM/MiniMax に切り替える 3. 重要ではないタスクには無料枠 (Gemini CLI、iFlow) を使用する 4. API キーごとにコスト予算を設定します: [ダッシュボード] → [API キー] → [予算] + +--- + +## デバッグ + +### リクエストログを有効にする + +`.env` ファイルに `ENABLE_REQUEST_LOGS=true` を設定します。ログは `logs/` ディレクトリの下に表示されます。 + +### プロバイダーの健全性を確認する + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### ランタイムストレージ + +- メイン状態: `${DATA_DIR}/db.json` (プロバイダー、コンボ、エイリアス、キー、設定) +- 使用法: `${DATA_DIR}/usage.json`、`${DATA_DIR}/log.txt`、`${DATA_DIR}/call_logs/` +- リクエストログ：`/logs/...`（`ENABLE_REQUEST_LOGS=true`の場合） + +--- + +## サーキットブレーカーの問題 + +### プロバイダーが OPEN 状態でスタックしている + +プロバイダーのサーキット ブレーカーが OPEN の場合、リクエストはクールダウンが期限切れになるまでブロックされます。 + +**修正:** + +1. **ダッシュボード → 設定 → レジリエンス** に移動します +2. 影響を受けるプロバイダーのサーキット ブレーカー カードを確認します。 +3. [**すべてリセット**] をクリックしてすべてのブレーカーをクリアするか、クールダウンが期限切れになるまで待ちます。 +4. リセットする前に、プロバイダーが実際に利用可能であることを確認します。 + +### プロバイダーがサーキットブレーカーを落とし続けます + +プロバイダーが繰り返し OPEN 状態になる場合: + +1. **ダッシュボード → ヘルス → プロバイダーのヘルス** で障害パターンを確認します。 +2. **[設定] → [復元力] → [プロバイダー プロファイル]** に移動し、失敗のしきい値を増やします。 +3. プロバイダーが API 制限を変更したか、再認証が必要かどうかを確認します。 +4. レイテンシーテレメトリを確認します - レイテンシーが長いとタイムアウトベースのエラーが発生する可能性があります + +--- + +## 音声文字起こしの問題 + +### 「サポートされていないモデル」エラー + +- 正しいプレフィックスを使用していることを確認してください: `deepgram/nova-3` または `assemblyai/best` +- **「ダッシュボード」→「プロバイダー」**でプロバイダーが接続されていることを確認します。 + +### 文字起こしが空を返すか失敗する + +- サポートされているオーディオ形式を確認します: `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm` +- ファイル サイズがプロバイダーの制限内であることを確認します (通常は < 25MB) +- プロバイダー カードのプロバイダー API キーの有効性を確認します。 + +--- + +## トランスレータのデバッグ + +**ダッシュボード → トランスレーター** を使用して、形式変換の問題をデバッグします。 + +| モード | いつ使用するか | +| --------------------- | ----------------------------------------------------------------------------------------------------------- | +| **遊び場** | 入力/出力形式を並べて比較します。失敗したリクエストを貼り付けて、それがどのように変換されるかを確認します。 | +| **チャット テスター** | ライブ メッセージを送信し、ヘッダーを含む完全なリクエスト/レスポンス ペイロードを検査します。 | +| **テストベンチ** | フォーマットの組み合わせ全体でバッチ テストを実行して、どの翻訳が壊れているかを見つけます。 | +| **ライブモニター** | リアルタイムのリクエスト フローを監視して断続的な翻訳の問題を検出 | + +### 一般的な形式の問題 + +- **思考タグが表示されない** — ターゲットプロバイダーが思考と思考予算設定をサポートしているかどうかを確認してください +- **ツール呼び出しのドロップ** — 一部の形式変換では、サポートされていないフィールドが削除される場合があります。プレイグラウンド モードで確認する +- **システム プロンプトがありません** — クロードとジェミニはシステム プロンプトの処理方法が異なります。翻訳出力を確認する +- **SDK はオブジェクトではなく生の文字列を返します** — v1.1.0 で修正されました: 応答サニタイザーは、OpenAI SDK Pydantic 検証エラーの原因となる非標準フィールド (`x_groq`、`usage_breakdown` など) を削除するようになりました。 +- **GLM/ERNIE が `system` ロールを拒否します** — v1.1.0 で修正: ロール ノーマライザーは、互換性のないモデルのシステム メッセージをユーザー メッセージに自動的にマージします +- **`developer` ロールが認識されない** — v1.1.0 で修正: 非 OpenAI プロバイダーの場合は自動的に `system` に変換されます +- **`json_schema` が Gemini で動作しない** — v1.1.0 で修正: `response_format` は Gemini の `responseMimeType` + `responseSchema` に変換されるようになりました。 + +--- + +## 復元力の設定 + +### 自動レート制限がトリガーされない + +- 自動レート制限は API キープロバイダーにのみ適用されます (OAuth/サブスクリプションには適用されません) +- **設定 → 復元力 → プロバイダー プロファイル** で自動レート制限が有効になっていることを確認します +- プロバイダーが `429` ステータス コードまたは `Retry-After` ヘッダーを返すかどうかを確認します。 + +### 指数バックオフの調整 + +プロバイダー プロファイルは次の設定をサポートします。 + +- **基本遅延** — 最初の失敗後の初期待機時間 (デフォルト: 1 秒) +- **最大遅延** — 最大待機時間の上限 (デフォルト: 30 秒) +- **乗数** — 連続した失敗ごとにどれだけ遅延を増加させるか (デフォルト: 2x) + +### 対雷の群れ + +多くの同時リクエストがレート制限プロバイダーに到達すると、OmniRoute はミューテックスと自動レート制限を使用してリクエストをシリアル化し、連鎖的な失敗を防ぎます。これは API キープロバイダーの場合は自動的に行われます。 + +--- + +## まだ行き詰まっていますか? + +- **GitHub の問題**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **アーキテクチャ**: 内部の詳細については、[**OMNI_TOKEN_55**](ARCHITECTURE.md) を参照してください。 +- **API リファレンス**: すべてのエンドポイントについては、[**OMNI_TOKEN_56**](API_REFERENCE.md) を参照してください。 +- **ヘルス ダッシュボード**: リアルタイムのシステム ステータスについては、**ダッシュボード → ヘルス** を確認してください。 +- **トランスレータ**: **ダッシュボード → トランスレータ**を使用して形式の問題をデバッグします diff --git a/docs/i18n/ja/USER_GUIDE.md b/docs/i18n/ja/USER_GUIDE.md new file mode 100644 index 00000000..a24bb408 --- /dev/null +++ b/docs/i18n/ja/USER_GUIDE.md @@ -0,0 +1,697 @@ +# ユーザーガイド + +🌐 **Languages:** 🇺🇸 [English](../../USER_GUIDE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/USER_GUIDE.md) | 🇪🇸 [Español](../es/USER_GUIDE.md) | 🇫🇷 [Français](../fr/USER_GUIDE.md) | 🇮🇹 [Italiano](../it/USER_GUIDE.md) | 🇷🇺 [Русский](../ru/USER_GUIDE.md) | 🇨🇳 [中文 (简体)](../zh-CN/USER_GUIDE.md) | 🇩🇪 [Deutsch](../de/USER_GUIDE.md) | 🇮🇳 [हिन्दी](../in/USER_GUIDE.md) | 🇹🇭 [ไทย](../th/USER_GUIDE.md) | 🇺🇦 [Українська](../uk-UA/USER_GUIDE.md) | 🇸🇦 [العربية](../ar/USER_GUIDE.md) | 🇯🇵 [日本語](../ja/USER_GUIDE.md) | 🇻🇳 [Tiếng Việt](../vi/USER_GUIDE.md) | 🇧🇬 [Български](../bg/USER_GUIDE.md) | 🇩🇰 [Dansk](../da/USER_GUIDE.md) | 🇫🇮 [Suomi](../fi/USER_GUIDE.md) | 🇮🇱 [עברית](../he/USER_GUIDE.md) | 🇭🇺 [Magyar](../hu/USER_GUIDE.md) | 🇮🇩 [Bahasa Indonesia](../id/USER_GUIDE.md) | 🇰🇷 [한국어](../ko/USER_GUIDE.md) | 🇲🇾 [Bahasa Melayu](../ms/USER_GUIDE.md) | 🇳🇱 [Nederlands](../nl/USER_GUIDE.md) | 🇳🇴 [Norsk](../no/USER_GUIDE.md) | 🇵🇹 [Português (Portugal)](../pt/USER_GUIDE.md) | 🇷🇴 [Română](../ro/USER_GUIDE.md) | 🇵🇱 [Polski](../pl/USER_GUIDE.md) | 🇸🇰 [Slovenčina](../sk/USER_GUIDE.md) | 🇸🇪 [Svenska](../sv/USER_GUIDE.md) | 🇵🇭 [Filipino](../phi/USER_GUIDE.md) + +プロバイダーの構成、コンボの作成、CLI ツールの統合、OmniRoute の展開に関する完全なガイド。 + +--- + +## 目次 + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [Provider Setup](#-provider-setup) +- [CLI Integration](#-cli-integration) +- [Deployment](#-deployment) +- [Available Models](#-available-models) +- [Advanced Features](#-advanced-features) + +--- + +## 💰 価格の概要 + +| 階層 | プロバイダー | コスト | クォータのリセット | 最適な用途 | +| ------------------------- | -------------------------- | --------------------- | ------------------- | ---------------------- | +| **💳 サブスクリプション** | クロード・コード (プロ) | $20/月 | 5 時間 + 毎週 | すでに購読済み | +| | コーデックス (プラス/プロ) | $20-200/月 | 5 時間 + 毎週 | OpenAI ユーザー | +| | ジェミニ CLI | **無料** | 180K/月 + 1K/日 | みんな！ | +| | GitHub コパイロット | $10-19/月 | 月刊 | GitHub ユーザー | +| **🔑 API キー** | ディープシーク | 使用ごとに支払い | なし | 安っぽい推論 | +| | グロク | 使用ごとに支払い | なし | 超高速推論 | +| | xAI (グロック) | 使用ごとに支払い | なし | Grok 4 の推論 | +| | ミストラル | 使用ごとに支払い | なし | EU がホストするモデル | +| | 困惑 | 使用ごとに支払い | なし | 検索拡張 | +| | 一緒にAI | 使用ごとに支払い | なし | オープンソース モデル | +| | 花火AI | 使用ごとに支払い | なし | 高速 FLUX 画像 | +| | 大脳 | 使用ごとに支払い | なし | ウェーハスケールの速度 | +| | コヒア | 使用ごとに支払い | なし | コマンド R+ RAG | +| | NVIDIA NIM | 使用ごとに支払い | なし | エンタープライズモデル | +| **💰安い** | GLM-4.7 | $0.6/100万 | 毎日午前 10 時 | 予算のバックアップ | +| | ミニマックス M2.1 | $0.2/100万 | 5時間ローリング | 最も安いオプション | +| | キミ K2 | 月額 9 ドルのフラット | 1,000 万トークン/月 | 予測可能なコスト | +| **🆓 無料** | iFlow | $0 | 無制限 | 8 モデルは無料 | +| | クウェン | $0 | 無制限 | 3 モデルは無料 | +| | キロ | $0 | 無制限 | クロード・フリー | + +**💡 プロのヒント:** Gemini CLI (180,000 無料/月) + iFlow (無制限の無料) コンボ = コスト 0 ドルから始めましょう! + +--- + +## 🎯 使用例 + +### ケース 1: 「Claude Pro サブスクリプションを持っています」 + +**問題:** 大量のコーディング中にクォータが使用されずに期限切れになり、レート制限が発生する + +``` +Combo: "maximize-claude" + 1. cc/claude-opus-4-6 (use subscription fully) + 2. glm/glm-4.7 (cheap backup when quota out) + 3. if/kimi-k2-thinking (free emergency fallback) + +Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total +vs. $20 + hitting limits = frustration +``` + +### ケース 2: 「コストをゼロにしたい」 + +**問題:** サブスクリプションを購入する余裕がないため、信頼性の高い AI コーディングが必要です + +``` +Combo: "free-forever" + 1. gc/gemini-3-flash (180K free/month) + 2. if/kimi-k2-thinking (unlimited free) + 3. qw/qwen3-coder-plus (unlimited free) + +Monthly cost: $0 +Quality: Production-ready models +``` + +### ケース 3: 「24 時間年中無休でコーディングが必要で、中断はありません」 + +**問題:** 締め切りが迫っており、ダウンタイムを許すことができません + +``` +Combo: "always-on" + 1. cc/claude-opus-4-6 (best quality) + 2. cx/gpt-5.2-codex (second subscription) + 3. glm/glm-4.7 (cheap, resets daily) + 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) + 5. if/kimi-k2-thinking (free unlimited) + +Result: 5 layers of fallback = zero downtime +Monthly cost: $20-200 (subscriptions) + $10-20 (backup) +``` + +### ケース 4: 「OpenClaw に無料の AI が欲しい」 + +**問題:** メッセージング アプリには AI アシスタントが必要ですが、完全に無料です + +``` +Combo: "openclaw-free" + 1. if/glm-4.7 (unlimited free) + 2. if/minimax-m2.1 (unlimited free) + 3. if/kimi-k2-thinking (unlimited free) + +Monthly cost: $0 +Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... +``` + +--- + +## 📖 プロバイダーのセットアップ + +### 🔐 サブスクリプションプロバイダー + +#### クロード コード (Pro/Max) + +```bash +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking + +Models: + cc/claude-opus-4-6 + cc/claude-sonnet-4-5-20250929 + cc/claude-haiku-4-5-20251001 +``` + +**プロのヒント:** 複雑なタスクには Opus を使用し、速度を求める場合は Sonnet を使用します。 OmniRoute はモデルごとの割り当てを追跡します。 + +#### OpenAI Codex (Plus/Pro) + +```bash +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset + +Models: + cx/gpt-5.2-codex + cx/gpt-5.1-codex-max +``` + +#### Gemini CLI (月額 180,000 が無料!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**ベストバリュー:** 膨大な無料枠!有料レベルの前にこれを使用してください。 + +#### GitHub コパイロット + +```bash +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) + +Models: + gh/gpt-5 + gh/claude-4.5-sonnet + gh/gemini-3-pro +``` + +### 💰 格安プロバイダー + +#### GLM-4.7 (毎日リセット、0.6 ドル/100 万ドル) + +1. サインアップ: [Zhipu AI](https://open.bigmodel.cn/) 2.コーディングプランからAPIキーを取得 +2. ダッシュボード → API キーの追加: プロバイダー: `glm`、API キー: `your-key` + +**使用方法:** `glm/glm-4.7` — **プロのヒント:** コーディング プランでは、1/7 のコストで 3 倍のクォータを提供します。毎日午前 10 時にリセットされます。 + +#### MiniMax M2.1 (5 時間リセット、$0.20/1M) + +1. サインアップ: [MiniMax](https://www.minimax.io/) +2. APIキーの取得 → ダッシュボード → APIキーの追加 + +**使用方法:** `minimax/MiniMax-M2.1` — **プロのヒント:** 長いコンテキスト (100 万トークン) の最も安価なオプション! + +#### キミ K2 (月額一律 9 ドル) + +1. 購読: [Moonshot AI](https://platform.moonshot.ai/) +2. APIキーの取得 → ダッシュボード → APIキーの追加 + +**使用方法:** `kimi/kimi-latest` — **プロのヒント:** 1,000 万トークンの固定 $9/月 = 0.90 ドル/100 万の実効コスト! + +### 🆓 無料プロバイダー + +#### iFlow (8 つの無料モデル) + +```bash +Dashboard → Connect iFlow → OAuth login → Unlimited usage + +Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 +``` + +#### Qwen (3 つの無料モデル) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### キロ (クロード フリー) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨 コンボ + +### 例 1: サブスクリプションを最大化 → 安価なバックアップ + +``` +Dashboard → Combos → Create New + +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) + +Use in CLI: premium-coding +``` + +### 例 2: 無料のみ (コストゼロ) + +``` +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) + +Cost: $0 forever! +``` + +--- + +## 🔧 CLI の統合 + +### カーソル IDE + +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` + +### クロードコード + +`~/.claude/config.json` を編集します: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### コーデックス CLI + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +### オープンクロー + +`~/.openclaw/openclaw.json` を編集します: + +```json +{ + "agents": { + "defaults": { + "model": { "primary": "omniroute/if/glm-4.7" } + } + }, + "models": { + "providers": { + "omniroute": { + "baseUrl": "http://localhost:20128/v1", + "apiKey": "your-omniroute-api-key", + "api": "openai-completions", + "models": [{ "id": "if/glm-4.7", "name": "glm-4.7" }] + } + } + } +} +``` + +**またはダッシュボードを使用します:** CLI ツール → OpenClaw → 自動構成 + +### クライン / 継続 / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 導入 + +### VPS 導入 + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### ドッカー + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +CLI バイナリを使用したホスト統合モードについては、メイン ドキュメントの Docker セクションを参照してください。 + +### 環境変数 + +| 変数 | デフォルト | 説明 | +| --------------------- | ------------------------------------ | ----------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT 署名シークレット (**本番環境での変更**) | +| `INITIAL_PASSWORD` | `123456` | 初回ログインパスワード | +| `DATA_DIR` | `~/.omniroute` | データ ディレクトリ (データベース、使用状況、ログ) | +| `PORT` | フレームワークのデフォルト | サービスポート (例では `20128`) | +| `HOSTNAME` | フレームワークのデフォルト | バインド ホスト (Docker のデフォルトは `0.0.0.0`) | +| `NODE_ENV` | 実行時のデフォルト | デプロイ用に `production` を設定 | +| `BASE_URL` | `http://localhost:20128` | サーバー側の内部ベース URL | +| `CLOUD_URL` | `https://omniroute.dev` | クラウド同期エンドポイントのベース URL | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | 生成された API キーの HMAC シークレット | +| `REQUIRE_API_KEY` | `false` | `/v1/*` にベアラー API キーを強制する | +| `ENABLE_REQUEST_LOGS` | `false` | リクエスト/レスポンスログを有効にする | +| `AUTH_COOKIE_SECURE` | `false` | `Secure` 認証 Cookie を強制する (HTTPS リバース プロキシの背後で) | + +環境変数の完全なリファレンスについては、[README](../README.md) を参照してください。 + +--- + +## 📊 利用可能なモデル + +
+利用可能なモデルをすべて表示 + +**クロード コード (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`、`cc/claude-sonnet-4-5-20250929`、`cc/claude-haiku-4-5-20251001` + +**コーデックス (`cx/`)** — プラス/プロ: `cx/gpt-5.2-codex`、`cx/gpt-5.1-codex-max` + +**Gemini CLI (`gc/`)** — 無料: `gc/gemini-3-flash-preview`、`gc/gemini-2.5-pro` + +**GitHub コパイロット (`gh/`)**: `gh/gpt-5`、`gh/claude-4.5-sonnet` + +**GLM (`glm/`)** — $0.6/1M: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — $0.2/1M: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** — 無料: `if/kimi-k2-thinking`、`if/qwen3-coder-plus`、`if/deepseek-r1` + +**クウェン (`qw/`)** — 無料: `qw/qwen3-coder-plus`、`qw/qwen3-coder-flash` + +**キロ (`kr/`)** — 無料: `kr/claude-sonnet-4.5`、`kr/claude-haiku-4.5` + +**ディープシーク (`ds/`)**: `ds/deepseek-chat`、`ds/deepseek-reasoner` + +**Groq (`groq/`)**: `groq/llama-3.3-70b-versatile`、`groq/llama-4-maverick-17b-128e-instruct` + +**xAI (`xai/`)**: `xai/grok-4`、`xai/grok-4-0709-fast-reasoning`、`xai/grok-code-mini` + +**ミストラル (`mistral/`)**: `mistral/mistral-large-2501`、`mistral/codestral-2501` + +**混乱 (`pplx/`)**: `pplx/sonar-pro`、`pplx/sonar` + +**一緒に AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**花火 AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**セレブ (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**ここにあります (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 高度な機能 + +### カスタムモデル + +アプリの更新を待たずに、任意のモデル ID を任意のプロバイダーに追加します。 + +```bash +# Via API +curl -X POST http://localhost:20128/api/provider-models \ + -H "Content-Type: application/json" \ + -d '{"provider": "openai", "modelId": "gpt-4.5-preview", "modelName": "GPT-4.5 Preview"}' + +# List: curl http://localhost:20128/api/provider-models?provider=openai +# Remove: curl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" +``` + +または、ダッシュボードを使用します: **プロバイダー → [プロバイダー] → カスタム モデル**。 + +### 専用プロバイダー ルート + +モデル検証を使用してリクエストを特定のプロバイダーに直接ルーティングします。 + +```bash +POST http://localhost:20128/v1/providers/openai/chat/completions +POST http://localhost:20128/v1/providers/openai/embeddings +POST http://localhost:20128/v1/providers/fireworks/images/generations +``` + +プロバイダーのプレフィックスが存在しない場合は、自動的に追加されます。モデルが一致しない場合は、`400` が返されます。 + +### ネットワークプロキシ構成 + +```bash +# Set global proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' + +# Per-provider proxy +curl -X PUT http://localhost:20128/api/settings/proxy \ + -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' + +# Test proxy +curl -X POST http://localhost:20128/api/settings/proxy/test \ + -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' +``` + +**優先順位:** キー固有 → コンボ固有 → プロバイダー固有 → グローバル → 環境。 + +### モデル カタログ API + +```bash +curl http://localhost:20128/api/models/catalog +``` + +タイプ (`chat`、`embedding`、`image`) を持つプロバイダーごとにグループ化されたモデルを返します。 + +### クラウド同期 + +- デバイス間でプロバイダー、コンボ、設定を同期します +- タイムアウト + フェイルファストによる自動バックグラウンド同期 +- 運用環境ではサーバー側の `BASE_URL`/`CLOUD_URL` を優先します + +### LLM ゲートウェイ インテリジェンス (フェーズ 9) + +- **セマンティック キャッシュ** — 非ストリーミング、温度=0 の応答を自動キャッシュします (`X-OmniRoute-No-Cache: true` によるバイパス) +- **リクエストのべき等性** — `Idempotency-Key` または `X-Request-Id` ヘッダーを介して 5 秒以内にリクエストの重複を排除します。 +- **進行状況の追跡** — `X-OmniRoute-Progress: true` ヘッダーを介した SSE `event: progress` イベントのオプトイン + +--- + +### 翻訳者の遊び場 + +**ダッシュボード → トランスレーター** からアクセスします。 OmniRoute がプロバイダー間で API リクエストをどのように変換するかをデバッグして視覚化します。 + +| モード | 目的 | +| --------------------- | --------------------------------------------------------------------------------------------- | +| **遊び場** | ソース/ターゲット形式を選択し、リクエストを貼り付けると、翻訳された出力が即座に表示されます。 | +| **チャット テスター** | プロキシ経由でライブ チャット メッセージを送信し、完全な要求/応答サイクルを検査します。 | +| **テストベンチ** | 複数の形式の組み合わせに対してバッチ テストを実行して、翻訳の正確さを検証します。 | +| **ライブモニター** | リクエストがプロキシを通過するときにリアルタイムの翻訳を監視します。 | + +**使用例:** + +- 特定のクライアント/プロバイダーの組み合わせが失敗する理由をデバッグする +- 思考タグ、ツール呼び出し、システム プロンプトが正しく翻訳されていることを確認します。 +- OpenAI、Claude、Gemini、および Responses API 形式間の形式の違いを比較します。 + +--- + +### ルーティング戦略 + +**[ダッシュボード] → [設定] → [ルーティング]** から設定します。 + +| 戦略 | 説明 | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| **最初に記入してください** | 優先順位に従ってアカウントを使用します。プライマリ アカウントは利用できなくなるまですべてのリクエストを処理します。 | +| **ラウンドロビン** | 設定可能なスティッキー制限を使用して、すべてのアカウントを循環します (デフォルト: アカウントごとに 3 コール)。 | +| **P2C (2 つの選択肢の累乗)** | ランダムな 2 つのアカウントを選択し、より健全なアカウントにルーティングします — 健康を意識しながら負荷のバランスをとります | +| **ランダム** | Fisher-Yates shuffle | を使用してリクエストごとにアカウントをランダムに選択します。 | +| **使用頻度が最も低い** | 最も古い `lastUsedAt` タイムスタンプを持つアカウントにルーティングし、トラフィックを均等に分散します。 | +| **コストの最適化** | 最も低い優先順位の値を持つアカウントにルーティングし、最もコストの低いプロバイダー向けに最適化します。 | + +#### ワイルドカード モデルのエイリアス + +ワイルドカード パターンを作成してモデル名を再マッピングします。 + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +ワイルドカードは、`*` (任意の文字) および `?` (単一文字) をサポートします。 + +#### フォールバック チェーン + +すべてのリクエストに適用されるグローバル フォールバック チェーンを定義します。 + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### レジリエンスとサーキットブレーカー + +**ダッシュボード → 設定 → レジリエンス** から設定します。 + +OmniRoute は、次の 4 つのコンポーネントでプロバイダー レベルの復元力を実装します。 + +1. **プロバイダー プロファイル** — 以下のプロバイダーごとの構成: + - 失敗しきい値 (開くまでに何回失敗したか) + - クールダウン期間 + - レート制限検出感度 + - 指数バックオフパラメータ + +2. **編集可能なレート制限** — ダッシュボードで構成可能なシステムレベルのデフォルト: + - **1 分あたりのリクエスト数 (RPM)** — アカウントごとの 1 分あたりの最大リクエスト数 + - **リクエスト間の最小時間** — リクエスト間の最小ギャップ (ミリ秒単位) + - **最大同時リクエスト** — アカウントあたりの最大同時リクエスト + - [**編集**] をクリックして変更し、**保存** または **キャンセル** をクリックします。値は復元 API を介して保持されます。 + +3. **サーキット ブレーカー** — プロバイダーごとに障害を追跡し、しきい値に達すると自動的に回線を開きます。 + - **クローズ** (正常) — リクエストは正常に流れます + - **OPEN** — プロバイダーは失敗が繰り返された後、一時的にブロックされています + - **HALF_OPEN** — プロバイダーが回復したかどうかをテストします + +4. **ポリシーとロックされた識別子** — 強制ロック解除機能を備えたサーキット ブレーカーのステータスとロックされた識別子を表示します。 + +5. **レート制限の自動検出** — `429` ヘッダーと `Retry-After` ヘッダーを監視して、プロバイダーのレート制限に達することを事前に回避します。 + +**プロのヒント:** プロバイダーが停止から回復したときに、**すべてリセット** ボタンを使用して、すべてのサーキット ブレーカーとクールダウンをクリアします。 + +--- + +### データベースのエクスポート/インポート + +**[ダッシュボード] > [設定] > [システムとストレージ]** でデータベースのバックアップを管理します。 + +| アクション | 説明 | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| **データベースのエクスポート** | 現在の SQLite データベースを `.sqlite` ファイルとしてダウンロードします。 | +| **すべてエクスポート (.tar.gz)** | データベース、設定、コンボ、プロバイダー接続 (認証情報なし)、API キー メタデータを含む完全なバックアップ アーカイブをダウンロードします。 | +| **データベースのインポート** | `.sqlite` ファイルをアップロードして、現在のデータベースを置き換えます。インポート前のバックアップが自動的に作成されます。 | + +```bash +# API: Export database +curl -o backup.sqlite http://localhost:20128/api/db-backups/export + +# API: Export all (full archive) +curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll + +# API: Import database +curl -X POST http://localhost:20128/api/db-backups/import \ + -F "file=@backup.sqlite" +``` + +**インポートの検証:** インポートされたファイルは、整合性 (SQLite プラグマ チェック)、必要なテーブル (`provider_connections`、`provider_nodes`、`combos`、`api_keys`)、およびサイズ (最大 100MB) について検証されます。 + +**使用例:** + +- マシン間で OmniRoute を移行する +- 災害復旧のために外部バックアップを作成する +- チームメンバー間で設定を共有（すべてエクスポート→アーカイブを共有） + +--- + +### 設定ダッシュボード + +設定ページは 5 つのタブで構成されており、簡単にナビゲーションできます。 + +| タブ | 目次 | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **セキュリティ** | ログイン/パスワード設定、IP アクセス制御、`/models` の API 認証、およびプロバイダーのブロック | +| **ルーティング** | グローバル ルーティング戦略 (6 つのオプション)、ワイルドカード モデル エイリアス、フォールバック チェーン、コンボ デフォルト | +| **回復力** | プロバイダー プロファイル、編集可能なレート制限、サーキット ブレーカーのステータス、ポリシー、ロックされた識別子 | +| **AI** | 予算構成、グローバル システム プロンプト インジェクション、プロンプト キャッシュ統計を考える | +| **上級** | グローバル プロキシ構成 (HTTP/SOCKS5) | + +--- + +### コストと予算の管理 + +**[ダッシュボード] → [コスト]** からアクセスします。 + +| タブ | 目的 | +| -------- | ----------------------------------------------------------------------------------- | +| **予算** | 日次/週次/月次の予算とリアルタイムの追跡を使用して、API キーごとに支出制限を設定 | +| **価格** | モデル価格エントリの表示と編集 - プロバイダーごとの 1K 入出力トークンあたりのコスト | + +```bash +# API: Set a budget +curl -X POST http://localhost:20128/api/usage/budget \ + -H "Content-Type: application/json" \ + -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' + +# API: Get current budget status +curl http://localhost:20128/api/usage/budget +``` + +**コスト追跡:** すべてのリクエストはトークンの使用状況を記録し、価格表を使用してコストを計算します。 **「ダッシュボード」→「使用状況**」でプロバイダー、モデル、API キーごとの内訳を表示します。 + +--- + +### 音声文字起こし + +OmniRoute は、OpenAI 互換エンドポイントを介した音声転写をサポートしています。 + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data + +# Example with curl +curl -X POST http://localhost:20128/v1/audio/transcriptions \ + -H "Authorization: Bearer your-api-key" \ + -F "file=@audio.mp3" \ + -F "model=deepgram/nova-3" +``` + +利用可能なプロバイダー: **Deepgram** (`deepgram/`)、**AssemblyAI** (`assemblyai/`)。 + +サポートされている音声形式: `mp3`、`wav`、`m4a`、`flac`、`ogg`、`webm`。 + +--- + +### コンボバランス戦略 + +**ダッシュボード → コンボ → 作成/編集 → 戦略** でコンボごとのバランスを設定します。 + +| 戦略 | 説明 | +| ---------------------- | -------------------------------------------------------------------------------- | +| **ラウンドロビン** | モデルを順番に回転します。 | +| **優先度** | 常に最初のモデルを試します。エラーの場合のみフォールバック | +| **ランダム** | 各リクエストのコンボからランダムなモデルを選択します。 | +| **加重** | モデルごとに割り当てられた重みに基づいて比例的にルーティングします。 | +| **使用頻度が最も低い** | 最近のリクエストが最も少ないモデルにルーティングします (コンボ メトリックを使用) | +| **コストの最適化** | 利用可能な最も安価なモデルへのルート (価格表を使用) | + +グローバル コンボ デフォルトは、**[ダッシュボード] → [設定] → [ルーティング] → [コンボ デフォルト]** で設定できます。 + +--- + +### 健康ダッシュボード + +**「ダッシュボード」→「ヘルス」** からアクセスします。 6 枚のカードによるリアルタイムのシステム状態の概要: + +| カード | それが示すもの | +| ---------------------------- | -------------------------------------------------------------------------------- | +| **システムステータス** | 稼働時間、バージョン、メモリ使用量、データ ディレクトリ | +| **プロバイダーの状態** | プロバイダーごとのサーキット ブレーカーの状態 (クローズ/オープン/ハーフオープン) | +| **レート制限** | アカウントごとのアクティブなレート制限クールダウンと残り時間 | +| **アクティブなロックアウト** | ロックアウト ポリシーによって一時的にブロックされたプロバイダー | +| **署名キャッシュ** | 重複排除キャッシュの統計 (アクティブなキー、ヒット率) | +| **レイテンシ テレメトリ** | プロバイダーごとの p50/p95/p99 レイテンシの集計 | + +**プロのヒント:** [ヘルス] ページは 10 秒ごとに自動更新されます。サーキット ブレーカー カードを使用して、どのプロバイダーで問題が発生しているかを特定します。