diff --git a/docs/i18n/pt-BR/API_REFERENCE.md b/docs/i18n/pt-BR/API_REFERENCE.md new file mode 100644 index 0000000000..b607ba62ef --- /dev/null +++ b/docs/i18n/pt-BR/API_REFERENCE.md @@ -0,0 +1,441 @@ +# Referência de 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) + +Referência completa para todos os endpoints da API OmniRoute. + +--- + +## Índice + +- [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) + +--- + +## Conclusões de bate-papo + +```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 +} +``` + +### Cabeçalhos personalizados + +| Cabeçalho | Direção | Descrição | +| ------------------------ | ----------- | ---------------------------------------------------------- | +| `X-OmniRoute-No-Cache` | Solicitação | Defina como `true` para ignorar o cache | +| `X-OmniRoute-Progress` | Solicitação | Defina como `true` para eventos de progresso | +| `Idempotency-Key` | Solicitação | Chave de desduplicação (janela 5s) | +| `X-Request-Id` | Solicitação | Chave de desduplicação alternativa | +| `X-OmniRoute-Cache` | Resposta | `HIT` ou `MISS` (sem streaming) | +| `X-OmniRoute-Idempotent` | Resposta | `true` se desduplicado | +| `X-OmniRoute-Progress` | Resposta | `enabled` se o acompanhamento do progresso estiver ativado | + +--- + +## Incorporações + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Provedores disponíveis: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## Geração de imagem + +```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" +} +``` + +Provedores disponíveis: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## Listar modelos + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## Terminais de compatibilidade + +| Método | Caminho | Formato | +| ------ | --------------------------- | -------------------- | +| POSTAR | `/v1/chat/completions` | OpenAI | +| POSTAR | `/v1/messages` | Antrópico | +| POSTAR | `/v1/responses` | Respostas OpenAI | +| POSTAR | `/v1/embeddings` | OpenAI | +| POSTAR | `/v1/images/generations` | OpenAI | +| OBTER | `/v1/models` | OpenAI | +| POSTAR | `/v1/messages/count_tokens` | Antrópico | +| OBTER | `/v1beta/models` | Gêmeos | +| POSTAR | `/v1beta/models/{...path}` | Gêmeos gera conteúdo | +| POSTAR | `/v1/api/chat` | Ollama | + +### Rotas de provedores dedicados + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. + +--- + +## Cache Semântico + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +Exemplo de resposta: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Painel e gerenciamento + +### Autenticação + +| Ponto final | Método | Descrição | +| ----------------------------- | ------------- | ------------------------- | +| `/api/auth/login` | POSTAR | Entrar | +| `/api/auth/logout` | POSTAR | Sair | +| `/api/settings/require-login` | OBTER/COLOCAR | Alternar login necessário | + +### Gerenciamento de Provedores + +| Ponto final | Método | Descrição | +| ---------------------------- | --------------------- | -------------------------------- | +| `/api/providers` | OBTER/POSTAR | Listar/criar provedores | +| `/api/providers/[id]` | OBTER/COLOCAR/EXCLUIR | Gerenciar um provedor | +| `/api/providers/[id]/test` | POSTAR | Testar conexão do provedor | +| `/api/providers/[id]/models` | OBTER | Listar modelos de provedores | +| `/api/providers/validate` | POSTAR | Validar configuração do provedor | +| `/api/provider-nodes*` | Vários | Gerenciamento de nós de provedor | +| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | Modelos personalizados | + +### Fluxos OAuth + +| Ponto final | Método | Descrição | +| -------------------------------- | ------ | ---------------------------- | +| `/api/oauth/[provider]/[action]` | Vários | OAuth específico do provedor | + +### Roteamento e configuração + +| Ponto final | Método | Descrição | +| --------------------- | ------------ | -------------------------------------- | +| `/api/models/alias` | OBTER/POSTAR | Aliases de modelo | +| `/api/models/catalog` | OBTER | Todos os modelos por fornecedor + tipo | +| `/api/combos*` | Vários | Gestão de combos | +| `/api/keys*` | Vários | Gerenciamento de chaves API | +| `/api/pricing` | OBTER | Preços do modelo | + +### Uso e análise + +| Ponto final | Método | Descrição | +| --------------------------- | ------ | ---------------------------- | +| `/api/usage/history` | OBTER | Histórico de uso | +| `/api/usage/logs` | OBTER | Registros de uso | +| `/api/usage/request-logs` | OBTER | Logs em nível de solicitação | +| `/api/usage/[connectionId]` | OBTER | Uso por conexão | + +### Configurações + +| Ponto final | Método | Descrição | +| ------------------------------- | ------------- | -------------------------------------------- | +| `/api/settings` | OBTER/COLOCAR | Configurações gerais | +| `/api/settings/proxy` | OBTER/COLOCAR | Configuração de proxy de rede | +| `/api/settings/proxy/test` | POSTAR | Testar conexão proxy | +| `/api/settings/ip-filter` | OBTER/COLOCAR | Lista de permissões/lista de bloqueios de IP | +| `/api/settings/thinking-budget` | OBTER/COLOCAR | Orçamento de token de raciocínio | +| `/api/settings/system-prompt` | OBTER/COLOCAR | Alerta do sistema global | + +### Monitoramento + +| Ponto final | Método | Descrição | +| ------------------------ | ------------- | ------------------------------ | +| `/api/sessions` | OBTER | Acompanhamento de sessão ativa | +| `/api/rate-limits` | OBTER | Limites de taxas por conta | +| `/api/monitoring/health` | OBTER | Exame de saúde | +| `/api/cache` | OBTER/EXCLUIR | Estatísticas de cache/limpar | + +### Backup e exportação/importação + +| Ponto final | Método | Descrição | +| --------------------------- | ------- | ------------------------------------------------------- | +| `/api/db-backups` | OBTER | Listar backups disponíveis | +| `/api/db-backups` | COLOCAR | Crie um backup manual | +| `/api/db-backups` | POSTAR | Restaurar de um backup específico | +| `/api/db-backups/export` | OBTER | Baixe o banco de dados como arquivo .sqlite | +| `/api/db-backups/import` | POSTAR | Carregar arquivo .sqlite para substituir banco de dados | +| `/api/db-backups/exportAll` | OBTER | Baixe o backup completo como arquivo .tar.gz | + +### Sincronização na nuvem + +| Ponto final | Método | Descrição | +| ---------------------- | ------ | ----------------------------------- | +| `/api/sync/cloud` | Vários | Operações de sincronização em nuvem | +| `/api/sync/initialize` | POSTAR | Inicializar sincronização | +| `/api/cloud/*` | Vários | Gerenciamento de nuvem | + +### Ferramentas CLI + +| Ponto final | Método | Descrição | +| ---------------------------------- | ------ | ------------------------------ | +| `/api/cli-tools/claude-settings` | OBTER | Status CLI de Claude | +| `/api/cli-tools/codex-settings` | OBTER | Status da CLI do Codex | +| `/api/cli-tools/droid-settings` | OBTER | Status da CLI do Droid | +| `/api/cli-tools/openclaw-settings` | OBTER | Status da CLI do OpenClaw | +| `/api/cli-tools/runtime/[toolId]` | OBTER | Tempo de execução CLI genérico | + +As respostas CLI incluem: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### Resiliência e limites de taxas + +| Ponto final | Método | Descrição | +| ----------------------- | ------------- | ------------------------------------- | +| `/api/resilience` | OBTER/COLOCAR | Obter/atualizar perfis de resiliência | +| `/api/resilience/reset` | POSTAR | Reinicializar disjuntores | +| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | +| `/api/rate-limit` | OBTER | Configuração de limite de taxa global | + +### Avaliações + +| Ponto final | Método | Descrição | +| ------------ | ------------ | --------------------------------------------- | +| `/api/evals` | OBTER/POSTAR | Listar suítes de avaliação/executar avaliação | + +### Políticas + +| Ponto final | Método | Descrição | +| --------------- | -------------------- | --------------------------------- | +| `/api/policies` | OBTER/POSTAR/EXCLUIR | Gerenciar políticas de roteamento | + +### Conformidade + +| Ponto final | Método | Descrição | +| --------------------------- | ------ | ----------------------------------------------- | +| `/api/compliance/audit-log` | OBTER | Registo de auditoria de conformidade (último N) | + +### v1beta (compatível com Gemini) + +| Ponto final | Método | Descrição | +| -------------------------- | ------ | --------------------------------------------- | +| `/v1beta/models` | OBTER | Listar modelos no formato Gemini | +| `/v1beta/models/{...path}` | POSTAR | Ponto de extremidade Gêmeos `generateContent` | + +Esses endpoints refletem o formato API do Gemini para clientes que esperam compatibilidade nativa do Gemini SDK. + +### APIs internas/do sistema + +| Ponto final | Método | Descrição | +| --------------- | ------ | ----------------------------------------------------------------------- | +| `/api/init` | OBTER | Verificação de inicialização do aplicativo (usada na primeira execução) | +| `/api/tags` | OBTER | Tags de modelo compatíveis com Ollama (para clientes Ollama) | +| `/api/restart` | POSTAR | Acionar reinicialização normal do servidor | +| `/api/shutdown` | POSTAR | Acionar o desligamento normal do servidor | + +> **Observação:** Esses endpoints são usados internamente pelo sistema ou para compatibilidade do cliente Ollama. Eles normalmente não são chamados pelos usuários finais. + +--- + +## Transcrição de áudio + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Transcreva arquivos de áudio usando Deepgram ou AssemblyAI. + +**Solicitação:** + +```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" +``` + +**Resposta:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**Provedores suportados:** `deepgram/nova-3`, `assemblyai/best`. + +**Formatos suportados:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +## Compatibilidade com Ollama + +Para clientes que usam o formato API do Ollama: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +As solicitações são traduzidas automaticamente entre o Ollama e os formatos internos. + +--- + +## Telemetria + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Resposta:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## Orçamento + +```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" +} +``` + +--- + +## Disponibilidade do modelo + +```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" +} +``` + +--- + +## Processamento de solicitação + +1. Cliente envia solicitação para `/v1/*` +2. O manipulador de rota chama `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration` +3. O modelo foi resolvido (provedor/modelo direto ou alias/combo) +4. Credenciais selecionadas do banco de dados local com filtragem de disponibilidade de conta +5. Para bate-papo: `handleChatCore` — detecção de formato, tradução, verificação de cache, verificação de idempotência +6. O executor do provedor envia uma solicitação upstream +7. Resposta traduzida de volta para o formato do cliente (chat) ou retornada como está (incorporações/imagens/áudio) +8. Uso/registro registrado +9. Fallback se aplica a erros de acordo com regras de combinação + +Referência completa da arquitetura: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## Autenticação + +- Rotas do painel (`/dashboard/*`) usam cookie `auth_token` +- O login utiliza hash de senha salva; substituto para `INITIAL_PASSWORD` +- `requireLogin` alternável via `/api/settings/require-login` +- As rotas `/v1/*` requerem opcionalmente a chave da API do portador quando `REQUIRE_API_KEY=true` diff --git a/docs/i18n/pt-BR/ARCHITECTURE.md b/docs/i18n/pt-BR/ARCHITECTURE.md new file mode 100644 index 0000000000..1b7e0f1766 --- /dev/null +++ b/docs/i18n/pt-BR/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# Arquitetura 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) + +_Última atualização: 18/02/2026_ + +## Resumo Executivo + +OmniRoute é um gateway de roteamento de IA local e painel construído em Next.js. +Ele fornece um único endpoint compatível com OpenAI (`/v1/*`) e roteia o tráfego entre vários provedores upstream com tradução, fallback, atualização de token e rastreamento de uso. + +Capacidades principais: + +- Superfície API compatível com OpenAI para CLI/ferramentas (28 provedores) +- Tradução de solicitação/resposta em formatos de provedores +- Fallback de combinação de modelos (sequência de vários modelos) +- Fallback em nível de conta (várias contas por provedor) +- Gerenciamento de conexão de provedor de chave OAuth + API +- Geração de incorporação via `/v1/embeddings` (6 provedores, 9 modelos) +- Geração de imagens via `/v1/images/generations` (4 provedores, 9 modelos) +- Pense na análise de tags (`...`) para modelos de raciocínio +- Sanitização de resposta para compatibilidade estrita com OpenAI SDK +- Normalização de funções (desenvolvedor→sistema, sistema→usuário) para compatibilidade entre provedores +- Conversão de saída estruturada (json_schema → Gemini responseSchema) +- Persistência local para provedores, chaves, aliases, combos, configurações, preços +- Acompanhamento de uso/custo e registro de solicitações +- Sincronização em nuvem opcional para sincronização de vários dispositivos/estado +- Lista de permissões/lista de bloqueio de IP para controle de acesso à API +- Pensando na gestão orçamentária (passthrough/auto/custom/adaptive) +- Injeção imediata do sistema global +- Rastreamento de sessão e impressão digital +- Limitação de taxa aprimorada por conta com perfis específicos do provedor +- Padrão de disjuntor para resiliência do provedor +- Proteção de rebanho anti-trovão com bloqueio mutex +- Cache de desduplicação de solicitação baseada em assinatura +- Camada de domínio: disponibilidade do modelo, regras de custo, política de fallback, política de bloqueio +- Persistência de estado de domínio (cache write-through SQLite para fallbacks, orçamentos, bloqueios, disjuntores) +- Mecanismo de política para avaliação centralizada de solicitações (bloqueio → orçamento → fallback) +- Solicitar telemetria com agregação de latência p50/p95/p99 +- ID de correlação (X-Request-Id) para rastreamento ponta a ponta +- Registro de auditoria de conformidade com cancelamento por chave de API +- Estrutura de avaliação para garantia de qualidade LLM +- Painel de UI de resiliência com status do disjuntor em tempo real +- Provedores OAuth modulares (12 módulos individuais em `src/lib/oauth/providers/`) + +Modelo de tempo de execução primário: + +- As rotas do aplicativo Next.js em `src/app/api/*` implementam APIs de painel e APIs de compatibilidade +- Um núcleo SSE/roteamento compartilhado em `src/sse/*` + `open-sse/*` lida com execução, tradução, streaming, fallback e uso do provedor + +## Escopo e limites + +### No escopo + +- Tempo de execução do gateway local +- APIs de gerenciamento de painel +- Autenticação do provedor e atualização de token +- Solicitar tradução e streaming SSE +- Estado local + persistência de uso +- Orquestração opcional de sincronização em nuvem + +### Fora do escopo + +- Implementação de serviço em nuvem por trás de `NEXT_PUBLIC_CLOUD_URL` +- Plano de controle/SLA do provedor fora do processo local +- Os próprios binários CLI externos (Claude CLI, Codex CLI, etc.) + +## Contexto do sistema de alto nível + +```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 +``` + +## Componentes principais de tempo de execução + +## 1) API e camada de roteamento (rotas de aplicativos Next.js) + +Diretórios principais: + +- `src/app/api/v1/*` e `src/app/api/v1beta/*` para APIs de compatibilidade +- `src/app/api/*` para APIs de gerenciamento/configuração +- Próximas reescritas em `next.config.mjs` mapeiam `/v1/*` para `/api/v1/*` + +Rotas de compatibilidade importantes: + +- `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` — inclui modelos personalizados com `custom: true` +- `src/app/api/v1/embeddings/route.ts` — geração de incorporação (6 provedores) +- `src/app/api/v1/images/generations/route.ts` — geração de imagens (4+ provedores incluindo Antigravidade/Nebius) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — bate-papo dedicado por provedor +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — embeddings dedicados por provedor +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagens dedicadas por provedor +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Domínios de gerenciamento: + +- Autenticação/configurações: `src/app/api/auth/*`, `src/app/api/settings/*` +- Provedores/conexões: `src/app/api/providers*` +- Nós do provedor: `src/app/api/provider-nodes*` +- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE) +- Catálogo de modelos: `src/app/api/models/catalog` (GET) +- Configuração de proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Chaves/aliases/combos/preços: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Uso: `src/app/api/usage/*` +- Sincronização/nuvem: `src/app/api/sync/*`, `src/app/api/cloud/*` +- Ajudantes de ferramentas CLI: `src/app/api/cli-tools/*` +- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT) +- Orçamento pensado: `src/app/api/settings/thinking-budget` (GET/PUT) +- Prompt do sistema: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessões: `src/app/api/sessions` (GET) +- Limites de taxa: `src/app/api/rate-limits` (GET) +- Resiliência: `src/app/api/resilience` (GET/PATCH) — perfis de provedor, disjuntor, estado limite de taxa +- Redefinição de resiliência: `src/app/api/resilience/reset` (POST) — redefinir disjuntores + resfriamento +- Estatísticas de cache: `src/app/api/cache/stats` (GET/DELETE) +- Disponibilidade do modelo: `src/app/api/models/availability` (GET/POST) +- Telemetria: `src/app/api/telemetry/summary` (GET) +- Orçamento: `src/app/api/usage/budget` (GET/POST) +- Cadeias de fallback: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Auditoria de conformidade: `src/app/api/compliance/audit-log` (GET) +- Avaliações: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Políticas: `src/app/api/policies` (GET/POST) + +## 2) SSE + Núcleo de Tradução + +Principais módulos de fluxo: + +- Entrada: `src/sse/handlers/chat.ts` +- Orquestração principal: `open-sse/handlers/chatCore.ts` +- Adaptadores de execução do provedor: `open-sse/executors/*` +- Detecção de formato/configuração do provedor: `open-sse/services/provider.ts` +- Análise/resolução de modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Lógica de substituição da conta: `open-sse/services/accountFallback.ts` +- Registro de tradução: `open-sse/translator/index.ts` +- Transformações de fluxo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Extração/normalização de uso: `open-sse/utils/usageTracking.ts` +- Pense no analisador de tags: `open-sse/utils/thinkTagParser.ts` +- Manipulador de incorporação: `open-sse/handlers/embeddings.ts` +- Incorporação de registro de provedor: `open-sse/config/embeddingRegistry.ts` +- Manipulador de geração de imagem: `open-sse/handlers/imageGeneration.ts` +- Registro do provedor de imagens: `open-sse/config/imageRegistry.ts` +- Sanitização de resposta: `open-sse/handlers/responseSanitizer.ts` +- Normalização de função: `open-sse/services/roleNormalizer.ts` + +Serviços (lógica de negócios): + +- Seleção/pontuação de conta: `open-sse/services/accountSelector.ts` +- Gerenciamento do ciclo de vida do contexto: `open-sse/services/contextManager.ts` +- Aplicação do filtro IP: `open-sse/services/ipFilter.ts` +- Acompanhamento de sessão: `open-sse/services/sessionManager.ts` +- Solicitar desduplicação: `open-sse/services/signatureCache.ts` +- Injeção de prompt do sistema: `open-sse/services/systemPrompt.ts` +- Pensando na gestão orçamentária: `open-sse/services/thinkingBudget.ts` +- Roteamento de modelo curinga: `open-sse/services/wildcardRouter.ts` +- Gerenciamento de limite de taxa: `open-sse/services/rateLimitManager.ts` +- Disjuntor: `open-sse/services/circuitBreaker.ts` + +Módulos da camada de domínio: + +- Disponibilidade do modelo: `src/lib/domain/modelAvailability.ts` +- Regras/orçamentos de custos: `src/lib/domain/costRules.ts` +- Política de substituto: `src/lib/domain/fallbackPolicy.ts` +- Resolvedor combinado: `src/lib/domain/comboResolver.ts` +- Política de bloqueio: `src/lib/domain/lockoutPolicy.ts` +- Mecanismo de política: `src/domain/policyEngine.ts` — bloqueio centralizado → orçamento → avaliação alternativa +- Catálogo de códigos de erro: `src/lib/domain/errorCodes.ts` +- ID da solicitação: `src/lib/domain/requestId.ts` +- Tempo limite de busca: `src/lib/domain/fetchTimeout.ts` +- Solicitar telemetria: `src/lib/domain/requestTelemetry.ts` +- Conformidade/auditoria: `src/lib/domain/compliance/index.ts` +- Corredor de avaliação: `src/lib/domain/evalRunner.ts` +- Persistência de estado de domínio: `src/lib/db/domainState.ts` — SQLite CRUD para cadeias de fallback, orçamentos, histórico de custos, estado de bloqueio, disjuntores + +Módulos do provedor OAuth (12 arquivos individuais em `src/lib/oauth/providers/`): + +- Índice de registro: `src/lib/oauth/providers/index.ts` +- Provedores individuais: `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` +- Thin wrapper: `src/lib/oauth/providers.ts` — reexportações de módulos individuais + +## 3) Camada de Persistência + +Banco de dados de estado primário: + +- `src/lib/localDb.ts` +- arquivo: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) +- entidades: ProviderConnections, ProviderNodes, modelAliases, combos, apiKeys, configurações, preços, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Banco de dados de uso: + +- `src/lib/usageDb.ts` +- arquivos: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- segue a mesma política de diretório base de `localDb` (`DATA_DIR`, então `XDG_CONFIG_HOME/omniroute` quando definido) +- decomposto em submódulos focados: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +Banco de dados de estado de domínio (SQLite): + +- `src/lib/db/domainState.ts` — Operações CRUD para estado de domínio +- Tabelas (criadas em `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Padrão de cache write-through: os mapas na memória são autoritativos em tempo de execução; as mutações são escritas de forma síncrona no SQLite; o estado é restaurado do banco de dados na inicialização a frio + +## 4) Superfícies de autenticação + segurança + +- Autenticação de cookie do painel: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- Geração/verificação de chave de API: `src/shared/utils/apiKey.ts` +- Os segredos do provedor persistiram nas entradas `providerConnections` +- Suporte a proxy de saída via `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurável por provedor ou global) + +## 5) Sincronização na nuvem + +- Inicialização do agendador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Tarefa periódica: `src/shared/services/cloudSyncScheduler.ts` +- Rota de controle: `src/app/api/sync/cloud/route.ts` + +## Ciclo de vida da solicitação (`/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 + Fluxo substituto da conta + +```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] +``` + +As decisões de fallback são orientadas por `open-sse/services/accountFallback.ts` usando códigos de status e heurísticas de mensagens de erro. + +## Integração do OAuth e ciclo de vida de atualização de 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 +``` + +A atualização durante o tráfego ativo é executada dentro de `open-sse/handlers/chatCore.ts` por meio do executor `refreshCredentials()`. + +## Ciclo de vida da sincronização na nuvem (ativar/sincronizar/desativar) + +```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 +``` + +A sincronização periódica é acionada por `CloudSyncScheduler` quando a nuvem está habilitada. + +## Modelo de dados e mapa de armazenamento + +```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 + } +``` + +Arquivos de armazenamento físico: + +- estado principal: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) +- estatísticas de uso: `${DATA_DIR}/usage.json` +- solicitar linhas de registro: `${DATA_DIR}/log.txt` +- sessões opcionais de depuração de tradução/solicitação: `/logs/...` + +## Topologia de implantação + +```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 +``` + +## Mapeamento de módulos (crítico para decisões) + +### Módulos de rota e API + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: APIs de compatibilidade +- `src/app/api/v1/providers/[provider]/*`: rotas dedicadas por provedor (chat, embeddings, imagens) +- `src/app/api/providers*`: provedor CRUD, validação, teste +- `src/app/api/provider-nodes*`: gerenciamento de nó compatível personalizado +- `src/app/api/provider-models`: gerenciamento de modelo personalizado (CRUD) +- `src/app/api/models/catalog`: API de catálogo de modelos completo (todos os tipos agrupados por provedor) +- `src/app/api/oauth/*`: fluxos OAuth/código do dispositivo +- `src/app/api/keys*`: ciclo de vida da chave de API local +- `src/app/api/models/alias`: gerenciamento de alias +- `src/app/api/combos*`: gerenciamento de combinação alternativa +- `src/app/api/pricing`: substituições de preços para cálculo de custos +- `src/app/api/settings/proxy`: configuração de proxy (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: teste de conectividade de proxy de saída (POST) +- `src/app/api/usage/*`: APIs de uso e registros +- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronização na nuvem e ajudantes voltados para a nuvem +- `src/app/api/cli-tools/*`: gravadores/verificadores de configuração CLI locais +- `src/app/api/settings/ip-filter`: lista de permissões/lista de bloqueios de IP (GET/PUT) +- `src/app/api/settings/thinking-budget`: configuração do orçamento do token de pensamento (GET/PUT) +- `src/app/api/settings/system-prompt`: prompt global do sistema (GET/PUT) +- `src/app/api/sessions`: listagem de sessões ativas (GET) +- `src/app/api/rate-limits`: status de limite de taxa por conta (GET) + +### Núcleo de Roteamento e Execução + +- `src/sse/handlers/chat.ts`: análise de solicitação, tratamento de combinação, loop de seleção de conta +- `open-sse/handlers/chatCore.ts`: tradução, envio do executor, manipulação de novas tentativas/atualizações, configuração de stream +- `open-sse/executors/*`: rede específica do provedor e comportamento do formato + +### Registro de tradução e conversores de formato + +- `open-sse/translator/index.ts`: registro e orquestração do tradutor +- Solicitar tradutores: `open-sse/translator/request/*` +- Tradutores de resposta: `open-sse/translator/response/*` +- Constantes de formato: `open-sse/translator/formats.ts` + +### Persistência + +- `src/lib/localDb.ts`: configuração/estado persistente +- `src/lib/usageDb.ts`: histórico de uso e registros de solicitação contínua + +## Cobertura do Executor do Provedor (Padrão de Estratégia) + +Cada provedor tem um executor especializado que estende `BaseExecutor` (em `open-sse/executors/base.ts`), que fornece construção de URL, construção de cabeçalho, nova tentativa com espera exponencial, ganchos de atualização de credenciais e o método de orquestração `execute()`. + +| Executor | Fornecedor(es) | Tratamento Especial | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Juntos, Fireworks, Cerebras, Cohere, NVIDIA | Configuração dinâmica de URL/cabeçalho por provedor | +| `AntigravityExecutor` | Antigravidade do Google | IDs de projeto/sessão personalizados, análise repetida após | +| `CodexExecutor` | Códice OpenAI | Injeta instruções do sistema, força esforço de raciocínio | +| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de solicitação via checksum | +| `GithubExecutor` | Copiloto GitHub | Atualização de token do copiloto, cabeçalhos que imitam VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário AWS EventStream → conversão SSE | +| `GeminiCLIExecutor` | Gêmeos CLI | Ciclo de atualização do token OAuth do Google | + +Todos os outros provedores (incluindo nós compatíveis personalizados) usam `DefaultExecutor`. + +## Matriz de compatibilidade do provedor + +| Provedor | Formato | Autenticação | Transmitir | Não-transmissão | Atualização de token | API de uso | +| ------------------------ | ---------------- | --------------------------------- | ---------------- | --------------- | -------------------- | ------------------------ | +| Cláudio | Cláudio | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Somente administrador | +| Gêmeos | gêmeos | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | +| Gêmeos CLI | gêmeo-cli | OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | +| Antigravidade | antigravidade | OAuth | ✅ | ✅ | ✅ | ✅ API de cota completa | +| OpenAI | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Códice | respostas openai | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxas | +| Copiloto GitHub | abrirai | OAuth + token de copiloto | ✅ | ✅ | ✅ | ✅ Instantâneos de cota | +| Cursor | cursor | Soma de verificação personalizada | ✅ | ✅ | ❌ | ❌ | +| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso | +| Qwen | abrirai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação | +| iFlow | abrirai | OAuth (Básico) | ✅ | ✅ | ✅ | ⚠️ Por solicitação | +| OpenRouter | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | Cláudio | Chave API | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Groq | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| xAI (Groque) | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Mistral | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Perplexidade | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Juntos IA | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| IA de fogos de artifício | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Cérebros | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Coerente | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | + +## Cobertura de tradução de formato + +Os formatos de origem detectados incluem: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Os formatos de destino incluem: + +- Bate-papo/respostas OpenAI + -Cláudio +- Envelope Gemini/Gemini-CLI/Antigravidade + -Kiro +- Cursor + +As traduções usam **OpenAI como formato de hub** — todas as conversões passam pelo OpenAI como intermediário: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +As traduções são selecionadas dinamicamente com base no formato da carga útil de origem e no formato de destino do provedor. + +Camadas de processamento adicionais no pipeline de tradução: + +- **Sanitização de respostas** — Remove campos não padrão de respostas no formato OpenAI (streaming e não streaming) para garantir conformidade estrita com o SDK +- **Normalização de funções** — Converte `developer` → `system` para alvos não-OpenAI; mescla `system` → `user` para modelos que rejeitam a função do sistema (GLM, ERNIE) +- **Extração de tag Think** — Analisa blocos `...` do conteúdo no campo `reasoning_content` +- **Saída estruturada** — Converte OpenAI `response_format.json_schema` em `responseMimeType` + `responseSchema` do Gemini + +## Terminais de API suportados + +| Ponto final | Formato | Manipulador | +| -------------------------------------------------- | ---------------------------- | -------------------------------------------------------------- | +| `POST /v1/chat/completions` | Bate-papo OpenAI | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Mensagens de Cláudio | Mesmo manipulador (detectado automaticamente) | +| `POST /v1/responses` | Respostas OpenAI | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | Incorporações OpenAI | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Listagem de modelos | Rota API | +| `POST /v1/images/generations` | Imagens OpenAI | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Listagem de modelos | Rota API | +| `POST /v1/providers/{provider}/chat/completions` | Bate-papo OpenAI | Dedicado por provedor com validação de modelo | +| `POST /v1/providers/{provider}/embeddings` | Incorporações OpenAI | Dedicado por provedor com validação de modelo | +| `POST /v1/providers/{provider}/images/generations` | Imagens OpenAI | Dedicado por provedor com validação de modelo | +| `POST /v1/messages/count_tokens` | Contagem de tokens de Claude | Rota API | +| `GET /v1/models` | Lista de modelos OpenAI | Rota API (chat + incorporação + imagem + modelos customizados) | +| `GET /api/models/catalog` | Catálogo | Todos os modelos agrupados por fornecedor + tipo | +| `POST /v1beta/models/*:streamGenerateContent` | Nativo de Gêmeos | Rota API | +| `GET/PUT/DELETE /api/settings/proxy` | Configuração de proxy | Configuração de proxy de rede | +| `POST /api/settings/proxy/test` | Conectividade proxy | Endpoint de teste de integridade/conectividade do proxy | +| `GET/POST/DELETE /api/provider-models` | Modelos personalizados | Gestão de modelos customizados por provedor | + +## Ignorar manipulador + +O manipulador de bypass (`open-sse/utils/bypassHandler.ts`) intercepta solicitações "descartáveis" conhecidas da CLI de Claude — pings de aquecimento, extrações de títulos e contagens de tokens — e retorna uma **resposta falsa** sem consumir tokens do provedor upstream. Isso é acionado somente quando `User-Agent` contém `claude-cli`. + +## Solicitar pipeline do registrador + +O registrador de solicitações (`open-sse/utils/requestLogger.ts`) fornece um pipeline de registro de depuração de 7 estágios, desabilitado por padrão, habilitado por meio de `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 +``` + +Os arquivos são gravados em `/logs//` para cada sessão de solicitação. + +## Modos de falha e resiliência + +## 1) Disponibilidade da conta/provedor + +- resfriamento da conta do provedor em erros transitórios/taxa/autenticação +- fallback da conta antes da falha na solicitação +- modelo combinado substituto quando o caminho do modelo/provedor atual se esgota + +## 2) Expiração do token + +- pré-verificação e atualização com nova tentativa para provedores atualizáveis +- Nova tentativa 401/403 após tentativa de atualização no caminho principal + +## 3) Segurança de transmissão + +- controlador de fluxo com reconhecimento de desconexão +- fluxo de tradução com liberação de fim de fluxo e manipulação de `[DONE]` +- fallback de estimativa de uso quando faltam metadados de uso do provedor + +## 4) Degradação da sincronização na nuvem + +- erros de sincronização aparecem, mas o tempo de execução local continua +- o agendador tem lógica com capacidade de repetição, mas a execução periódica atualmente chama a sincronização de tentativa única por padrão + +## 5) Integridade de dados + +- Migração/reparo de formato de banco de dados para chaves ausentes +- proteções de redefinição JSON corrompidas para localDb e usageDb + +## Observabilidade e Sinais Operacionais + +Fontes de visibilidade em tempo de execução: + +- registros do console de `src/sse/utils/logger.ts` +- agregados de uso por solicitação em `usage.json` +- registro de status da solicitação textual em `log.txt` +- registros opcionais de solicitação/tradução profunda em `logs/` quando `ENABLE_REQUEST_LOGS=true` +- endpoints de uso do painel (`/api/usage/*`) para consumo de UI + +## Limites sensíveis à segurança + +- Segredo JWT (`JWT_SECRET`) protege a verificação/assinatura de cookies da sessão do painel +- O substituto de senha inicial (`INITIAL_PASSWORD`, padrão `123456`) deve ser substituído em implantações reais +- O segredo HMAC da chave de API (`API_KEY_SECRET`) protege o formato de chave de API local gerado +- Os segredos do provedor (chaves/tokens de API) persistem no banco de dados local e devem ser protegidos no nível do sistema de arquivos +- Os endpoints de sincronização em nuvem dependem da semântica de autenticação de chave de API + ID de máquina + +## Matriz de Ambiente e Tempo de Execução + +Variáveis de ambiente usadas ativamente pelo código: + +- Aplicativo/autenticação: `JWT_SECRET`, `INITIAL_PASSWORD` +- Armazenamento: `DATA_DIR` +- Comportamento do nó compatível: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Substituição opcional da base de armazenamento (Linux/macOS quando `DATA_DIR` não definido): `XDG_CONFIG_HOME` +- Hash de segurança: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Registro: `ENABLE_REQUEST_LOGS` +- URL de sincronização/nuvem: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Proxy de saída: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e variantes minúsculas +- Sinalizadores de recurso SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Auxiliares de plataforma/tempo de execução (não configuração específica do aplicativo): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Notas arquitetônicas conhecidas + +1. `usageDb` e `localDb` agora compartilham a mesma política de diretório base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) com migração de arquivo legado. +2. `/api/v1/route.ts` retorna uma lista de modelos estáticos e não é a principal fonte de modelos usada por `/v1/models`. +3. O registrador de solicitações grava cabeçalhos/corpo completos quando habilitado; trate o diretório de log como confidencial. +4. O comportamento da nuvem depende do `NEXT_PUBLIC_BASE_URL` correto e da acessibilidade do endpoint na nuvem. +5. O diretório `open-sse/` é publicado como o `@omniroute/open-sse` **pacote de espaço de trabalho npm**. O código-fonte o importa via `@omniroute/open-sse/...` (resolvido por Next.js `transpilePackages`). Os caminhos de arquivo neste documento ainda usam o nome de diretório `open-sse/` para consistência. +6. Os gráficos no painel usam **Recharts** (baseados em SVG) para visualizações analíticas interativas e acessíveis (gráficos de barras de uso de modelo, tabelas de detalhamento de fornecedores com taxas de sucesso). +7. Os testes E2E usam **Playwright** (`tests/e2e/`), executados via `npm run test:e2e`. Os testes de unidade usam o **executor de testes Node.js** (`tests/unit/`), executado por meio de `npm run test:plan3`. O código-fonte em `src/` é **TypeScript** (`.ts`/`.tsx`); o espaço de trabalho `open-sse/` permanece JavaScript (`.js`). +8. A página de configurações é organizada em 5 guias: Segurança, Roteamento (6 estratégias globais: preenchimento primeiro, round-robin, p2c, aleatório, menos usado, com custo otimizado), Resiliência (limites de taxa editáveis, disjuntor, políticas), IA (pensando no orçamento, prompt do sistema, cache de prompt), Avançado (proxy). + +## Lista de verificação de verificação operacional + +- Construir a partir da fonte: `npm run build` +- Construir imagem Docker: `docker build -t omniroute .` +- Inicie o serviço e verifique: +- `GET /api/settings` +- `GET /api/v1/models` +- O URL base de destino da CLI deve ser `http://:20128/v1` quando `PORT=20128` diff --git a/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..16693c3fb1 --- /dev/null +++ b/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute — Documentação da base de código + +🌐 **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) + +> Um guia abrangente e para iniciantes sobre o roteador proxy AI multiprovedor **omniroute**. + +--- + +## 1. O que é OmniRoute? + +omniroute é um **roteador proxy** que fica entre clientes de IA (Claude CLI, Codex, Cursor IDE, etc.) e provedores de IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Isso resolve um grande problema: + +> **Diferentes clientes de IA falam "idiomas" diferentes (formatos de API), e diferentes provedores de IA também esperam "idiomas" diferentes.** omniroute traduz entre eles automaticamente. + +Pense nisso como um tradutor universal nas Nações Unidas – qualquer delegado pode falar qualquer idioma, e o tradutor converte para qualquer outro delegado. + +--- + +## 2. Visão geral da arquitetura + +```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 +``` + +### Princípio Básico: Tradução Hub-and-Spoke + +Toda a tradução de formato passa pelo **formato OpenAI como hub**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +Isso significa que você só precisa de **N tradutores** (um por formato) em vez de **N²** (cada par). + +--- + +## 3. Estrutura do Projeto + +``` +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. Divisão módulo por módulo + +### 4.1 Configuração (`open-sse/config/`) + +A **única fonte de verdade** para todas as configurações do provedor. + +| Arquivo | Finalidade | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `constants.ts` | Objeto `PROVIDERS` com URLs base, credenciais OAuth (padrões), cabeçalhos e prompts de sistema padrão para cada provedor. Também define `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` e `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Carrega credenciais externas de `data/provider-credentials.json` e as mescla nos padrões codificados em `PROVIDERS`. Mantém os segredos fora do controle de origem, mantendo a compatibilidade com versões anteriores. | +| `providerModels.ts` | Registro central de modelos: aliases de provedores de mapas → IDs de modelos. Funções como `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | Instruções do sistema injetadas em solicitações do Codex (restrições de edição, regras de sandbox, políticas de aprovação). | +| `defaultThinkingSignature.ts` | Assinaturas de "pensamento" padrão para os modelos Claude e Gemini. | +| `ollamaModels.ts` | Definição de esquema para modelos locais de Ollama (nome, tamanho, família, quantização). | + +#### Fluxo de carregamento de credenciais + +```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 Executores (`open-sse/executors/`) + +Os executores encapsulam **lógica específica do provedor** usando o **Padrão de estratégia**. Cada executor substitui os métodos básicos conforme necessário. + +```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 +``` + +| Executor | Provedor | Principais Especializações | +| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Base abstrata: construção de URL, cabeçalhos, lógica de repetição, atualização de credenciais | +| `default.ts` | Claude, Gêmeos, OpenAI, GLM, Kimi, MiniMax | Atualização genérica de token OAuth para provedores padrão | +| `antigravity.ts` | Código do Google Cloud | Geração de ID de projeto/sessão, fallback de vários URLs, análise de repetição personalizada de mensagens de erro ("redefinir após 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Mais complexo**: autenticação de soma de verificação SHA-256, codificação de solicitação Protobuf, EventStream binário → análise de resposta SSE | +| `codex.ts` | Códice OpenAI | Injeta instruções do sistema, gerencia níveis de pensamento, remove parâmetros não suportados | +| `gemini-cli.ts` | CLI do Google Gemini | Criação de URL personalizado (`streamGenerateContent`), atualização de token Google OAuth | +| `github.ts` | Copiloto GitHub | Sistema de token duplo (token GitHub OAuth + Copilot), imitação de cabeçalho VSCode | +| `kiro.ts` | AWS CodeWhisperer | Análise binária AWS EventStream, event frames AMZN, estimativa de token | +| `index.ts` | — | Fábrica: nome do provedor de mapas → classe do executor, com fallback padrão | + +--- + +### 4.3 Manipuladores (`open-sse/handlers/`) + +A **camada de orquestração** — coordena tradução, execução, streaming e tratamento de erros. + +| Arquivo | Finalidade | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Orquestrador central** (~600 linhas). Lida com o ciclo de vida completo da solicitação: detecção de formato → tradução → envio do executor → resposta de streaming/não streaming → atualização de token → tratamento de erros → registro de uso. | +| `responsesHandler.ts` | Adaptador para API de respostas da OpenAI: converte o formato de respostas → conclusões de bate-papo → envia para `chatCore` → converte SSE de volta para o formato de respostas. | +| `embeddings.ts` | Manipulador de geração de incorporação: resolve o modelo de incorporação → provedor, despacha para a API do provedor, retorna uma resposta de incorporação compatível com OpenAI. Suporta mais de 6 provedores. | +| `imageGeneration.ts` | Manipulador de geração de imagem: resolve modelo de imagem → provedor, suporta modos compatíveis com OpenAI, imagem Gemini (Antigravidade) e fallback (Nebius). Retorna imagens base64 ou URL. | + +#### Ciclo de vida da solicitação (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 Serviços (`open-sse/services/`) + +Lógica de negócios que dá suporte aos manipuladores e executores. + +| Arquivo | Finalidade | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Detecção de formato** (`detectFormat`): analisa a estrutura do corpo da solicitação para identificar formatos Claude/OpenAI/Gemini/Antigravity/Responses (inclui heurística `max_tokens` para Claude). Além disso: construção de URL, construção de cabeçalho, normalização de configuração de pensamento. Suporta provedores dinâmicos `openai-compatible-*` e `anthropic-compatible-*`. | +| `model.ts` | Análise de string de modelo (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolução de alias com detecção de colisão, limpeza de entrada (rejeita caracteres de passagem/controle de caminho) e resolução de informações de modelo com suporte a getter de alias assíncrono. | +| `accountFallback.ts` | Tratamento de limite de taxa: espera exponencial (1s → 2s → 4s → máx. 2min), gerenciamento de resfriamento da conta, classificação de erros (quais erros acionam fallback versus não). | +| `tokenRefresh.ts` | Atualização de token OAuth para **todos os provedores**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inclui cache de desduplicação de promessa em andamento e nova tentativa com espera exponencial. | +| `combo.ts` | **Modelos combinados**: cadeias de modelos alternativos. Se o modelo A falhar com um erro elegível para fallback, tente o modelo B, depois o C, etc. Retorna os códigos de status upstream reais. | +| `usage.ts` | Busca dados de cota/uso de APIs do provedor (cotas do GitHub Copilot, cotas do modelo antigravidade, limites de taxa do Codex, detalhamentos de uso do Kiro, configurações do Claude). | +| `accountSelector.ts` | Seleção inteligente de conta com algoritmo de pontuação: considera prioridade, status de integridade, posição round-robin e estado de espera para escolher a conta ideal para cada solicitação. | +| `contextManager.ts` | Gerenciamento do ciclo de vida do contexto de solicitação: cria e rastreia objetos de contexto por solicitação com metadados (ID da solicitação, carimbos de data/hora, informações do provedor) para depuração e registro em log. | +| `ipFilter.ts` | Controle de acesso baseado em IP: suporta modos de lista de permissões e lista de bloqueios. Valida o IP do cliente em relação às regras configuradas antes de processar solicitações de API. | +| `sessionManager.ts` | Rastreamento de sessão com impressão digital do cliente: rastreia sessões ativas usando identificadores de cliente com hash, monitora contagens de solicitações e fornece métricas de sessão. | +| `signatureCache.ts` | Solicitar cache de desduplicação baseado em assinatura: evita solicitações duplicadas armazenando em cache assinaturas de solicitações recentes e retornando respostas armazenadas em cache para solicitações idênticas dentro de um intervalo de tempo. | +| `systemPrompt.ts` | Injeção global de prompt do sistema: acrescenta ou acrescenta um prompt do sistema configurável a todas as solicitações, com tratamento de compatibilidade por provedor. | +| `thinkingBudget.ts` | Gerenciamento de orçamento de token de raciocínio: oferece suporte aos modos passthrough, automático (configuração de pensamento), personalizado (orçamento fixo) e adaptativo (escala de complexidade) para controlar tokens de pensamento/raciocínio. | +| `wildcardRouter.ts` | Roteamento de padrão de modelo curinga: resolve padrões curinga (por exemplo, `*/claude-*`) para pares concretos de provedor/modelo com base na disponibilidade e prioridade. | + +#### Desduplicação de atualização de 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 +``` + +#### Máquina de estado substituto da conta + +```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 + } +``` + +#### Cadeia de modelos combinados + +```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 Tradutor (`open-sse/translator/`) + +O **mecanismo de tradução de formatos** usando um sistema de plugins com autorregistro. + +#### Arquitetura + +```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 +``` + +| Diretório | Arquivos | Descrição | +| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `request/` | 8 tradutores | Converta corpos de solicitação entre formatos. Cada arquivo é registrado automaticamente via `register(from, to, fn)` na importação. | +| `response/` | 7 tradutores | Converta pedaços de resposta de streaming entre formatos. Lida com tipos de eventos SSE, blocos de pensamento e chamadas de ferramentas. | +| `helpers/` | 6 ajudantes | Utilitários compartilhados: `claudeHelper` (extração de prompt do sistema, configuração de pensamento), `geminiHelper` (mapeamento de partes/conteúdo), `openaiHelper` (filtragem de formato), `toolCallHelper` (geração de ID, injeção de resposta ausente), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Mecanismo de tradução: `translateRequest()`, `translateResponse()`, gerenciamento de estado, registro. | +| `formats.ts` | — | Constantes de formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | + +#### Design principal: plug-ins de autorregistro + +```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ários (`open-sse/utils/`) + +| Arquivo | Finalidade | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | Criação de resposta a erros (formato compatível com OpenAI), análise de erros upstream, extração de tempo de repetição antigravidade de mensagens de erro, streaming de erros SSE. | +| `stream.ts` | **SSE Transform Stream** — o principal pipeline de streaming. Dois modos: `TRANSLATE` (tradução de formato completo) e `PASSTHROUGH` (normalizar + extrair uso). Lida com buffer de blocos, estimativa de uso e rastreamento de comprimento de conteúdo. As instâncias do codificador/decodificador por fluxo evitam o estado compartilhado. | +| `streamHelpers.ts` | Utilitários SSE de baixo nível: `parseSSELine` (tolerante a espaços em branco), `hasValuableContent` (filtra pedaços vazios para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialização SSE com reconhecimento de formato com limpeza `perf_metrics`). | +| `usageTracking.ts` | Extração de uso de token de qualquer formato (Claude/OpenAI/Gemini/Responses), estimativa com proporções separadas de caracteres por ferramenta/mensagem por token, adição de buffer (margem de segurança de 2.000 tokens), filtragem de campo específica de formato, registro de console com cores ANSI. | +| `requestLogger.ts` | Registro de solicitação baseado em arquivo (aceitação via `ENABLE_REQUEST_LOGS=true`). Cria pastas de sessão com arquivos numerados: `1_req_client.json` → `7_res_client.txt`. Toda E/S é assíncrona (dispare e esqueça). Mascara cabeçalhos sensíveis. | +| `bypassHandler.ts` | Intercepta padrões específicos do Claude CLI (extração de título, aquecimento, contagem) e retorna respostas falsas sem ligar para nenhum provedor. Suporta streaming e não streaming. Intencionalmente limitado ao escopo Claude CLI. | +| `networkProxy.ts` | Resolve URL de proxy de saída para um determinado provedor com precedência: configuração específica do provedor → configuração global → variáveis ​​de ambiente (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Suporta exclusões `NO_PROXY`. Configuração de caches por 30s. | + +#### Pipeline de 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 +``` + +#### Estrutura da sessão do registrador de solicitações + +``` +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 Camada de Aplicação (`src/`) + +| Diretório | Finalidade | +| ------------- | -------------------------------------------------------------------------------------- | +| `src/app/` | UI da Web, rotas de API, middleware Express, manipuladores de retorno de chamada OAuth | +| `src/lib/` | Acesso à base de dados (`localDb.ts`, `usageDb.ts`), autenticação, partilhada | +| `src/mitm/` | Utilitários proxy man-in-the-middle para interceptar o tráfego do provedor | +| `src/models/` | Definições de modelo de banco de dados | +| `src/shared/` | Wrappers em torno de funções open-sse (provedor, fluxo, erro, etc.) | +| `src/sse/` | Manipuladores de endpoint SSE que conectam a biblioteca open-sse às rotas Express | +| `src/store/` | Gerenciamento de estado de aplicação | + +#### Rotas de API notáveis + +| Rota | Métodos | Finalidade | +| --------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | +| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | CRUD para modelos customizados por provedor | +| `/api/models/catalog` | OBTER | Catálogo agregado de todos os modelos (chat, incorporação, imagem, customizado) agrupados por provedor | +| `/api/settings/proxy` | OBTER/COLOCAR/EXCLUIR | Configuração hierárquica de proxy de saída (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POSTAR | Valida a conectividade do proxy e retorna IP público/latência | +| `/v1/providers/[provider]/chat/completions` | POSTAR | Conclusões de chat dedicadas por provedor com validação de modelo | +| `/v1/providers/[provider]/embeddings` | POSTAR | Incorporações dedicadas por provedor com validação de modelo | +| `/v1/providers/[provider]/images/generations` | POSTAR | Geração de imagens dedicadas por provedor com validação de modelo | +| `/api/settings/ip-filter` | OBTER/COLOCAR | Gerenciamento de lista de permissão/lista de bloqueio de IP | +| `/api/settings/thinking-budget` | OBTER/COLOCAR | Configuração do orçamento do token de raciocínio (passagem/automática/personalizada/adaptável) | +| `/api/settings/system-prompt` | OBTER/COLOCAR | Injeção imediata do sistema global para todas as solicitações | +| `/api/sessions` | OBTER | Acompanhamento e métricas de sessões ativas | +| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | + +--- + +## 5. Principais padrões de design + +### 5.1 Tradução Hub-and-Spoke + +Todos os formatos são traduzidos através do **formato OpenAI como hub**. Adicionar um novo provedor requer apenas escrever **um par** de tradutores (de/para OpenAI), não N pares. + +### 5.2 Padrão de Estratégia do Executor + +Cada provedor possui uma classe de executor dedicada herdada de `BaseExecutor`. A fábrica em `executors/index.ts` seleciona o correto em tempo de execução. + +### 5.3 Sistema de plug-ins de autorregistro + +Os módulos tradutores se registram na importação via `register()`. Adicionar um novo tradutor é apenas criar um arquivo e importá-lo. + +### 5.4 Fallback de conta com backoff exponencial + +Quando um provedor retorna 429/401/500, o sistema pode mudar para a próxima conta, aplicando cooldowns exponenciais (1s → 2s → 4s → máx. 2min). + +### 5.5 Cadeias de modelos combinados + +Um "combo" agrupa várias strings `provider/model`. Se o primeiro falhar, volte para o próximo automaticamente. + +### 5.6 Tradução de streaming com estado + +A tradução de resposta mantém o estado em blocos SSE (rastreamento de blocos de pensamento, acúmulo de chamadas de ferramentas, indexação de blocos de conteúdo) por meio do mecanismo `initState()`. + +### 5.7 Buffer de segurança de uso + +Um buffer de 2.000 tokens é adicionado ao uso relatado para evitar que os clientes atinjam os limites da janela de contexto devido à sobrecarga dos prompts do sistema e da tradução de formato. + +--- + +## 6. Formatos Suportados + +| Formato | Direção | Identificador | +| ------------------------------ | ---------------- | ------------------ | +| Conclusões do bate-papo OpenAI | origem + destino | `openai` | +| API de respostas OpenAI | origem + destino | `openai-responses` | +| Claude Antrópico | origem + destino | `claude` | +| Google Gêmeos | origem + destino | `gemini` | +| CLI do Google Gemini | apenas alvo | `gemini-cli` | +| Antigravidade | origem + destino | `antigravity` | +| AWSKiro | apenas alvo | `kiro` | +| Cursor | apenas alvo | `cursor` | + +--- + +## 7. Provedores Suportados + +| Provedor | Método de autenticação | Executor | Notas principais | +| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------- | +| Claude Antrópico | Chave API ou OAuth | Padrão | Usa cabeçalho `x-api-key` | +| Google Gêmeos | Chave API ou OAuth | Padrão | Usa cabeçalho `x-goog-api-key` | +| CLI do Google Gemini | OAuth | GêmeosCLI | Usa ponto de extremidade `streamGenerateContent` | +| Antigravidade | OAuth | Antigravidade | Fallback de vários URLs, análise de repetição personalizada | +| OpenAI | Chave de API | Padrão | Autenticação do portador padrão | +| Códice | OAuth | Códice | Injeta instruções do sistema, gerencia o pensamento | +| Copiloto GitHub | Token OAuth + Copiloto | GitHub | Token duplo, imitação de cabeçalho VSCode | +| Kiro (AWS) | AWS SSO OIDC ou social | Kiro | Análise binária de EventStream | +| Cursor IDE | Autenticação de soma de verificação | Cursor | Codificação protobuf, somas de verificação SHA-256 | +| Qwen | OAuth | Padrão | Autenticação padrão | +| iFlow | OAuth (Básico + Portador) | Padrão | Cabeçalho de autenticação dupla | +| OpenRouter | Chave de API | Padrão | Autenticação do portador padrão | +| GLM, Kimi, MiniMax | Chave de API | Padrão | Compatível com Claude, use `x-api-key` | +| `openai-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com OpenAI | +| `anthropic-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com Claude | + +--- + +## 8. Resumo do fluxo de dados + +### Solicitação de 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()"] +``` + +### Solicitação de não 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"] +``` + +### Desviar fluxo (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/pt-BR/FEATURES.md b/docs/i18n/pt-BR/FEATURES.md new file mode 100644 index 0000000000..599e62469b --- /dev/null +++ b/docs/i18n/pt-BR/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — Galeria de recursos do painel + +🌐 **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) + +Guia visual para cada seção do painel do OmniRoute. + +--- + +## 🔌 Provedores + +Gerencie conexões de provedores de IA: provedores OAuth (Claude Code, Codex, Gemini CLI), provedores de chaves de API (Groq, DeepSeek, OpenRouter) e provedores gratuitos (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨Combos + +Crie combos de roteamento de modelos com 6 estratégias: preenchimento primeiro, round-robin, potência de duas opções, aleatório, menos usado e com custo otimizado. Cada combinação encadeia vários modelos com fallback automático. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Análise + +Análise de uso abrangente com consumo de tokens, estimativas de custos, mapas de calor de atividades, gráficos de distribuição semanais e detalhamentos por provedor. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Saúde do Sistema + +Monitoramento em tempo real: tempo de atividade, memória, versão, percentis de latência (p50/p95/p99), estatísticas de cache e estados de disjuntores do provedor. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Parque do Tradutor + +Quatro modos para depurar traduções de API: **Playground** (conversor de formato), **Chat Tester** (solicitações ao vivo), **Test Bench** (testes em lote) e **Live Monitor** (transmissão em tempo real). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Configurações + +Configurações gerais, armazenamento do sistema, gerenciamento de backup (banco de dados de exportação/importação), aparência (modo escuro/claro), segurança (inclui proteção de endpoint de API e bloqueio de provedor personalizado), roteamento, resiliência e configuração avançada. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Ferramentas CLI + +Configuração com um clique para ferramentas de codificação de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code e Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Solicitar registros + +Registro de solicitações em tempo real com filtragem por provedor, modelo, conta e chave de API. Mostra códigos de status, uso de token, latência e detalhes de resposta. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 Ponto final da API + +Seu endpoint de API unificado com detalhamento de recursos: conclusões de bate-papo, incorporações, geração de imagens, reclassificação, transcrição de áudio e chaves de API registradas. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/pt-BR/TROUBLESHOOTING.md b/docs/i18n/pt-BR/TROUBLESHOOTING.md new file mode 100644 index 0000000000..f678130061 --- /dev/null +++ b/docs/i18n/pt-BR/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Solução de problemas + +🌐 **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) + +Problemas e soluções comuns para OmniRoute. + +--- + +## Correções rápidas + +| Problema | Solução | +| ----------------------------------------- | -------------------------------------------------------------------------------------- | +| O primeiro login não funciona | Verifique `INITIAL_PASSWORD` em `.env` (padrão: `123456`) | +| Painel abre na porta errada | Definir `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Nenhum registro de solicitação em `logs/` | Definir `ENABLE_REQUEST_LOGS=true` | +| EACCES: permissão negada | Defina `DATA_DIR=/path/to/writable/dir` para substituir `~/.omniroute` | +| Estratégia de roteamento não salva | Atualização para v1.4.11+ (correção do esquema Zod para persistência de configurações) | + +--- + +## Problemas do provedor + +### "O modelo de linguagem não forneceu mensagens" + +**Causa:** Cota do provedor esgotada. + +**Correção:** + +1. Verifique o rastreador de cota do painel +2. Use um combo com níveis alternativos +3. Mude para um nível mais barato/gratuito + +### Limitação de taxa + +**Causa:** Cota de assinatura esgotada. + +**Correção:** + +- Adicionar substituto: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax como backup barato + +### Token OAuth expirado + +OmniRoute atualiza automaticamente os tokens. Se os problemas persistirem: + +1. Painel → Provedor → Reconectar +2. Exclua e adicione novamente a conexão do provedor + +--- + +## Problemas de nuvem + +### Erros de sincronização na nuvem + +1. Verifique `BASE_URL` aponta para sua instância em execução (por exemplo, `http://localhost:20128`) +2. Verifique os pontos `CLOUD_URL` para seu endpoint de nuvem (por exemplo, `https://omniroute.dev`) +3. Mantenha os valores `NEXT_PUBLIC_*` alinhados com os valores do lado do servidor + +### Nuvem `stream=false` Retorna 500 + +**Sintoma:** `Unexpected token 'd'...` no endpoint da nuvem para chamadas sem streaming. + +**Causa:** O upstream retorna a carga SSE enquanto o cliente espera JSON. + +**Solução alternativa:** use `stream=true` para chamadas diretas na nuvem. O tempo de execução local inclui substituto SSE→JSON. + +### Cloud diz conectado, mas "chave de API inválida" + +1. Crie uma nova chave no painel local (`/api/keys`) +2. Execute a sincronização na nuvem: Habilite Nuvem → Sincronizar agora +3. Chaves antigas/não sincronizadas ainda podem retornar `401` na nuvem + +--- + +## Problemas do Docker + +### A ferramenta CLI mostra não instalada + +1. Verifique os campos de tempo de execução: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Para modo portátil: use o destino de imagem `runner-cli` (CLIs agrupados) +3. Para o modo de montagem do host: defina `CLI_EXTRA_PATHS` e monte o diretório bin do host como somente leitura +4. Se `installed=true` e `runnable=false`: o binário foi encontrado, mas falhou na verificação de integridade + +### Validação Rápida de Tempo de Execução + +```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}' +``` + +--- + +## Problemas de custo + +### Custos elevados + +1. Verifique as estatísticas de uso em Painel → Uso +2. Mude o modelo primário para GLM/MiniMax +3. Use o nível gratuito (Gemini CLI, iFlow) para tarefas não críticas +4. Defina orçamentos de custos por chave de API: Painel → Chaves de API → Orçamento + +--- + +## Depuração + +### Habilitar registros de solicitação + +Defina `ENABLE_REQUEST_LOGS=true` em seu arquivo `.env`. Os logs aparecem no diretório `logs/`. + +### Verifique a integridade do provedor + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Armazenamento em tempo de execução + +- Estado principal: `${DATA_DIR}/db.json` (provedores, combos, aliases, chaves, configurações) +- Uso: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Registros de solicitação: `/logs/...` (quando `ENABLE_REQUEST_LOGS=true`) + +--- + +## Problemas com disjuntores + +### Provedor preso no estado OPEN + +Quando o disjuntor de um provedor está ABERTO, as solicitações são bloqueadas até que o tempo de espera expire. + +**Correção:** + +1. Vá para **Painel → Configurações → Resiliência** +2. Verifique a placa do disjuntor do provedor afetado +3. Clique em **Redefinir tudo** para limpar todos os disjuntores ou aguarde o tempo de espera expirar +4. Verifique se o provedor está realmente disponível antes de redefinir + +### O provedor continua desarmando o disjuntor + +Se um provedor entrar repetidamente no estado OPEN: + +1. Verifique **Dashboard → Health → Provider Health** para ver o padrão de falha +2. Vá para **Configurações → Resiliência → Perfis do Provedor** e aumente o limite de falha +3. Verifique se o provedor alterou os limites da API ou requer nova autenticação +4. Revise a telemetria de latência – alta latência pode causar falhas baseadas em tempo limite + +--- + +## Problemas de transcrição de áudio + +### Erro "Modelo não suportado" + +- Certifique-se de usar o prefixo correto: `deepgram/nova-3` ou `assemblyai/best` +- Verifique se o provedor está conectado em **Painel → Provedores** + +### A transcrição retorna vazia ou falha + +- Verifique os formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verifique se o tamanho do arquivo está dentro dos limites do provedor (normalmente <25 MB) +- Verifique a validade da chave API do provedor no cartão do provedor + +--- + +## Depuração do tradutor + +Use **Dashboard → Tradutor** para depurar problemas de tradução de formato: + +| Modo | Quando usar | +| ------------------------- | --------------------------------------------------------------------------------------------------------------- | +| **Parque Infantil** | Compare os formatos de entrada/saída lado a lado — cole uma solicitação com falha para ver como ela é traduzida | +| **Testador de bate-papo** | Envie mensagens ao vivo e inspecione a carga completa de solicitação/resposta, incluindo cabeçalhos | +| **Banco de testes** | Execute testes em lote em combinações de formatos para descobrir quais traduções estão quebradas | +| **Monitoramento ao vivo** | Observe o fluxo de solicitações em tempo real para detectar problemas intermitentes de tradução | + +### Problemas comuns de formato + +- **Tags de pensamento não aparecem** — Verifique se o provedor alvo apoia o pensamento e a configuração do orçamento de pensamento +- **Queda de chamadas de ferramentas** — Algumas traduções de formato podem remover campos não suportados; verificar no modo Playground +- **Prompt do sistema ausente** — Claude e Gemini lidam com os prompts do sistema de maneira diferente; verifique o resultado da tradução +- **SDK retorna string bruta em vez de objeto** — Corrigido na v1.1.0: o sanitizador de resposta agora remove campos não padrão (`x_groq`, `usage_breakdown`, etc.) que causam falhas de validação do OpenAI SDK Pydantic +- **GLM/ERNIE rejeita função `system`** — Corrigido na v1.1.0: o normalizador de função mescla automaticamente mensagens do sistema em mensagens do usuário para modelos incompatíveis +- Função **`developer` não reconhecida** — Corrigido na v1.1.0: convertido automaticamente para `system` para provedores não-OpenAI +- **`json_schema` não funciona com Gemini** — Corrigido na v1.1.0: `response_format` agora é convertido para `responseMimeType` + `responseSchema` do Gemini + +--- + +## Configurações de resiliência + +### Limite de taxa automático não acionado + +- O limite automático de taxa se aplica apenas a provedores de chaves de API (não a OAuth/assinatura) +- Verifique se **Configurações → Resiliência → Perfis do Provedor** tem limite de taxa automática ativado +- Verifique se o provedor retorna códigos de status `429` ou cabeçalhos `Retry-After` + +### Ajustando a espera exponencial + +Os perfis do provedor oferecem suporte a estas configurações: + +- **Atraso base** — Tempo de espera inicial após a primeira falha (padrão: 1s) +- **Atraso máximo** — Limite máximo de tempo de espera (padrão: 30s) +- **Multiplicador** — Quanto aumentar o atraso por falha consecutiva (padrão: 2x) + +### Rebanho anti-trovão + +Quando muitas solicitações simultâneas atingem um provedor com taxa limitada, o OmniRoute usa mutex + limitação automática de taxa para serializar solicitações e evitar falhas em cascata. Isso é automático para provedores de chaves de API. + +--- + +## Ainda preso? + +- **Problemas do GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Arquitetura**: Consulte [**OMNI_TOKEN_55**](ARCHITECTURE.md) para detalhes internos +- **Referência da API**: Consulte [**OMNI_TOKEN_56**](API_REFERENCE.md) para todos os endpoints +- **Painel de saúde**: verifique **Painel → Saúde** para ver o status do sistema em tempo real +- **Tradutor**: Use **Dashboard → Tradutor** para depurar problemas de formato diff --git a/docs/i18n/pt-BR/USER_GUIDE.md b/docs/i18n/pt-BR/USER_GUIDE.md new file mode 100644 index 0000000000..d1a6876022 --- /dev/null +++ b/docs/i18n/pt-BR/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Guia do usuário + +🌐 **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) + +Guia completo para configurar provedores, criar combos, integrar ferramentas CLI e implantar OmniRoute. + +--- + +## Índice + +- [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) + +--- + +## 💰 Visão geral dos preços + +| Nível | Provedor | Custo | Redefinição de cota | Melhor para | +| ------------------- | ------------------------ | ---------------- | ------------------------ | ----------------------------- | +| **💳 ASSINATURA** | Código Claude (Pro) | $ 20/mês | 5h + semanalmente | Já inscrito | +| | Códice (Plus/Pro) | US$ 20-200/mês | 5h + semanalmente | Usuários OpenAI | +| | Gêmeos CLI | **GRÁTIS** | 180 mil/mês + 1 mil/dia | Todos! | +| | Copiloto GitHub | US$ 10-19/mês | Mensalmente | Usuários do GitHub | +| **🔑 CHAVE DE API** | DeepSeek | Pague por uso | Nenhum | Raciocínio barato | +| | Groq | Pague por uso | Nenhum | Inferência ultrarrápida | +| | xAI (Groque) | Pague por uso | Nenhum | Raciocínio Grok 4 | +| | Mistral | Pague por uso | Nenhum | Modelos hospedados na UE | +| | Perplexidade | Pague por uso | Nenhum | Pesquisa aumentada | +| | Juntos IA | Pague por uso | Nenhum | Modelos de código aberto | +| | IA de fogos de artifício | Pague por uso | Nenhum | Imagens FLUX rápidas | +| | Cérebros | Pague por uso | Nenhum | Velocidade em escala de wafer | +| | Coerente | Pague por uso | Nenhum | Comando R+ RAG | +| | NVIDIA NIM | Pague por uso | Nenhum | Modelos empresariais | +| **💰 BARATO** | GLM-4.7 | US$ 0,6/1 milhão | Diariamente 10h | Backup de orçamento | +| | MiniMax M2.1 | US$ 0,2/1 milhão | Rolamento de 5 horas | Opção mais barata | +| | Kimi K2 | $ 9 / mês fixo | 10 milhões de tokens/mês | Custo previsível | +| **🆓 GRÁTIS** | iFlow | $0 | Ilimitado | 8 modelos grátis | +| | Qwen | $0 | Ilimitado | 3 modelos grátis | +| | Kiro | $0 | Ilimitado | Cláudio grátis | + +**💡 Dica profissional:** Comece com Gemini CLI (180 mil grátis/mês) + combo iFlow (gratuito ilimitado) = custo de $ 0! + +--- + +## 🎯 Casos de uso + +### Caso 1: "Tenho assinatura do Claude Pro" + +**Problema:** A cota expira sem ser utilizada, limites de taxa durante codificação pesada + +``` +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: "Quero custo zero" + +**Problema:** Não posso pagar assinaturas, preciso de codificação de IA confiável + +``` +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: "Preciso de codificação 24 horas por dia, 7 dias por semana, sem interrupções" + +**Problema:** Prazos, não podemos arcar com o tempo de inatividade + +``` +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: "Quero IA GRATUITA no OpenClaw" + +**Problema:** Precisa de assistente de IA em aplicativos de mensagens, totalmente 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... +``` + +--- + +## 📖 Configuração do provedor + +### 🔐 Provedores de assinatura + +#### Código 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 +``` + +**Dica profissional:** Use o Opus para tarefas complexas e o Sonnet para velocidade. OmniRoute rastreia cota por modelo! + +#### 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 (GRÁTIS 180 mil/mês!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Melhor valor:** Grande nível gratuito! Use isso antes dos níveis pagos. + +#### GitHub Copiloto + +```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 +``` + +### 💰 Fornecedores baratos + +#### GLM-4.7 (redefinição diária, US$ 0,6/1 milhão) + +1. Inscreva-se: [Zhipu AI](https://open.bigmodel.cn/) +2. Obtenha a chave API do plano de codificação +3. Painel → Adicionar chave de API: Provedor: `glm`, chave de API: `your-key` + +**Usar:** `glm/glm-4.7` — **Dica profissional:** O plano de codificação oferece 3× cota a 1/7 de custo! Redefinir diariamente às 10h. + +#### MiniMax M2.1 (redefinição de 5h, US$ 0,20/1 milhão) + +1. Inscreva-se: [MiniMax](https://www.minimax.io/) +2. Obter chave de API → Painel → Adicionar chave de API + +**Use:** `minimax/MiniMax-M2.1` — **Dica profissional:** Opção mais barata para contexto longo (1 milhão de tokens)! + +#### Kimi K2 (US$ 9/mês fixo) + +1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/) +2. Obter chave de API → Painel → Adicionar chave de API + +**Uso:** `kimi/kimi-latest` — **Dica profissional:** Fixo US$ 9/mês para 10 milhões de tokens = US$ 0,90/1 milhão de custo efetivo! + +### 🆓 Provedores GRATUITOS + +#### iFlow (8 modelos GRATUITOS) + +```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 modelos GRATUITOS) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude GRÁTIS) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨Combos + +### Exemplo 1: Maximize a assinatura → Backup barato + +``` +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 +``` + +### Exemplo 2: somente gratuito (custo 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! +``` + +--- + +## 🔧 Integração CLI + +### Cursor IDE + +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` + +### Código Cláudio + +Editar `~/.claude/config.json`: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### CLI do Codex + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +###OpenClaw + +Editar `~/.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" }] + } + } + } +} +``` + +**Ou use o Dashboard:** Ferramentas CLI → OpenClaw → Configuração automática + +### Cline / Continuar / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Implantação + +### Implantação 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 +``` + +### 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 +``` + +Para o modo integrado ao host com binários CLI, consulte a seção Docker na documentação principal. + +### Variáveis de Ambiente + +| Variável | Padrão | Descrição | +| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segredo de assinatura do JWT (**mudança na produção**) | +| `INITIAL_PASSWORD` | `123456` | Senha do primeiro login | +| `DATA_DIR` | `~/.omniroute` | Diretório de dados (banco de dados, uso, logs) | +| `PORT` | padrão da estrutura | Porta de serviço (`20128` em exemplos) | +| `HOSTNAME` | padrão da estrutura | Host de vinculação (o padrão do Docker é `0.0.0.0`) | +| `NODE_ENV` | padrão de tempo de execução | Definir `production` para implantação | +| `BASE_URL` | `http://localhost:20128` | URL base interna do lado do servidor | +| `CLOUD_URL` | `https://omniroute.dev` | URL base do endpoint de sincronização em nuvem | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segredo HMAC para chaves de API geradas | +| `REQUIRE_API_KEY` | `false` | Aplicar chave de API do portador em `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Habilita registros de solicitação/resposta | +| `AUTH_COOKIE_SECURE` | `false` | Forçar cookie de autenticação `Secure` (atrás do proxy reverso HTTPS) | + +Para obter a referência completa da variável de ambiente, consulte [README](../README.md). + +--- + +## 📊 Modelos Disponíveis + +
+Ver todos os modelos disponíveis + +**Código Claude (`cc/`)** — Pro/Máx: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Códice (`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` + +**Copiloto do GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**GLM (`glm/`)** — US$ 0,6/1 milhão: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — US$ 0,2/1 milhão: `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` + +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` + +**Perplexidade (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Juntos AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**IA do Fireworks (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Cérebros (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Coerente (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Recursos avançados + +### Modelos personalizados + +Adicione qualquer ID de modelo a qualquer provedor sem esperar por uma atualização do aplicativo: + +```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" +``` + +Ou use o Dashboard: **Provedores → [Provedor] → Modelos personalizados**. + +### Rotas de provedores dedicados + +Encaminhe solicitações diretamente para um provedor específico com validação de modelo: + +```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 +``` + +O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. + +### Configuração de proxy de rede + +```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"}}' +``` + +**Precedência:** Específico da chave → Específico do combo → Específico do provedor → Global → Ambiente. + +### API de catálogo de modelos + +```bash +curl http://localhost:20128/api/models/catalog +``` + +Retorna modelos agrupados por provedor com tipos (`chat`, `embedding`, `image`). + +### Sincronização na nuvem + +- Sincronize provedores, combos e configurações entre dispositivos +- Sincronização automática em segundo plano com tempo limite + falha rápida +- Prefira `BASE_URL`/`CLOUD_URL` do lado do servidor na produção + +### LLM Gateway Intelligence (Fase 9) + +- **Cache Semântico** — Armazena automaticamente em cache sem streaming, temperatura = 0 respostas (ignorar com `X-OmniRoute-No-Cache: true`) +- **Idempotência de solicitação** — Desduplica solicitações em 5s por meio do cabeçalho `Idempotency-Key` ou `X-Request-Id` +- **Acompanhamento de progresso** — Eventos SSE `event: progress` de aceitação por meio do cabeçalho `X-OmniRoute-Progress: true` + +--- + +### Parque do Tradutor + +Acesso via **Painel → Tradutor**. Depure e visualize como o OmniRoute traduz solicitações de API entre provedores. + +| Modo | Finalidade | +| ------------------------- | ----------------------------------------------------------------------------------------------------------- | +| **Parque Infantil** | Selecione os formatos de origem/destino, cole uma solicitação e veja o resultado traduzido instantaneamente | +| **Testador de bate-papo** | Envie mensagens de chat ao vivo através do proxy e inspecione todo o ciclo de solicitação/resposta | +| **Banco de testes** | Execute testes em lote em múltiplas combinações de formatos para verificar a exatidão da tradução | +| **Monitoramento ao vivo** | Assista às traduções em tempo real enquanto as solicitações fluem pelo proxy | + +**Casos de uso:** + +- Depure por que uma combinação específica de cliente/provedor falha +- Verifique se as tags de pensamento, as chamadas de ferramentas e os prompts do sistema são traduzidos corretamente +- Compare as diferenças de formato entre os formatos OpenAI, Claude, Gemini e Responses API + +--- + +### Estratégias de roteamento + +Configure via **Painel → Configurações → Roteamento**. + +| Estratégia | Descrição | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| **Preencha primeiro** | Usa contas em ordem de prioridade – a conta principal lida com todas as solicitações até ficar indisponível | +| **Round Robin** | Percorre todas as contas com um limite fixo configurável (padrão: 3 chamadas por conta) | +| **P2C (Poder de Duas Escolhas)** | Escolhe 2 contas aleatórias e direciona para a mais saudável — equilibra a carga com a consciência da saúde | +| **Aleatório** | Seleciona aleatoriamente uma conta para cada solicitação usando o embaralhamento Fisher-Yates | +| **Menos usado** | Roteia para a conta com o carimbo de data/hora `lastUsedAt` mais antigo, distribuindo o tráfego uniformemente | +| **Custo Otimizado** | Rotas para a conta com menor valor de prioridade, otimizando para provedores de menor custo | + +#### Aliases de modelo curinga + +Crie padrões curinga para remapear nomes de modelos: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +Os curingas suportam `*` (qualquer caractere) e `?` (caractere único). + +#### Cadeias substitutas + +Defina cadeias de fallback globais que se aplicam a todas as solicitações: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Resiliência e Disjuntores + +Configure via **Painel → Configurações → Resiliência**. + +OmniRoute implementa resiliência em nível de provedor com quatro componentes: + +1. **Perfis de Provedores** — Configuração por provedor para: + - Limite de falha (quantas falhas antes da abertura) + - Duração do resfriamento + - Sensibilidade de detecção de limite de taxa + - Parâmetros de espera exponencial + +2. **Limites de taxa editáveis** — Padrões de nível de sistema configuráveis no painel: + - **Solicitações por minuto (RPM)** — Máximo de solicitações por minuto por conta + - **Tempo mínimo entre solicitações** — Intervalo mínimo em milissegundos entre solicitações + - **Máximo de solicitações simultâneas** — Máximo de solicitações simultâneas por conta + - Clique em **Editar** para modificar e depois em **Salvar** ou **Cancelar**. Os valores persistem por meio da API de resiliência. + +3. **Disjuntor** — Rastreia falhas por provedor e abre automaticamente o circuito quando um limite é atingido: + - **FECHADO** (Saudável) — As solicitações fluem normalmente + - **OPEN** — O provedor é bloqueado temporariamente após falhas repetidas + - **HALF_OPEN** — Testando se o provedor se recuperou + +4. **Políticas e identificadores bloqueados** — Mostra o status do disjuntor e identificadores bloqueados com capacidade de desbloqueio forçado. + +5. **Detecção automática de limite de taxa** — Monitora os cabeçalhos `429` e `Retry-After` para evitar proativamente atingir os limites de taxa do provedor. + +**Dica profissional:** Use o botão **Redefinir tudo** para limpar todos os disjuntores e resfriamentos quando um provedor se recupera de uma interrupção. + +--- + +### Exportação/Importação de banco de dados + +Gerencie backups de banco de dados em **Painel → Configurações → Sistema e armazenamento**. + +| Ação | Descrição | +| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Exportar banco de dados** | Baixa o banco de dados SQLite atual como um arquivo `.sqlite` | +| **Exportar tudo (.tar.gz)** | Baixa um arquivo de backup completo, incluindo: banco de dados, configurações, combos, conexões de provedor (sem credenciais), metadados de chave API | +| **Importar banco de dados** | Faça upload de um arquivo `.sqlite` para substituir o banco de dados atual. Um backup de pré-importação é criado automaticamente | + +```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" +``` + +**Validação de importação:** O arquivo importado é validado quanto à integridade (verificação de pragma SQLite), tabelas necessárias (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e tamanho (máximo de 100 MB). + +**Casos de uso:** + +- Migrar OmniRoute entre máquinas +- Crie backups externos para recuperação de desastres +- Compartilhe configurações entre membros da equipe (exportar tudo → compartilhar arquivo) + +--- + +### Painel de configurações + +A página de configurações está organizada em 5 guias para facilitar a navegação: + +| Guia | Conteúdo | +| --------------- | ----------------------------------------------------------------------------------------------------------------- | +| **Segurança** | Configurações de login/senha, controle de acesso IP, autenticação de API para `/models` e bloqueio de provedor | +| **Roteamento** | Estratégia de roteamento global (6 opções), aliases de modelo curinga, cadeias de fallback, padrões de combinação | +| **Resiliência** | Perfis de provedores, limites de taxas editáveis, status de disjuntores, políticas e identificadores bloqueados | +| **IA** | Pensando na configuração do orçamento, injeção de prompt do sistema global, estatísticas de cache de prompt | +| **Avançado** | Configuração de proxy global (HTTP/SOCKS5) | + +--- + +### Gestão de Custos e Orçamento + +Acesso via **Painel → Custos**. + +| Guia | Finalidade | +| ------------- | -------------------------------------------------------------------------------------------------------------- | +| **Orçamento** | Defina limites de gastos por chave de API com orçamentos diários/semanais/mensais e rastreamento em tempo real | +| **Preços** | Visualize e edite entradas de preços de modelo — custo por 1 mil tokens de entrada/saída por provedor | + +```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 +``` + +**Acompanhamento de custos:** cada solicitação registra o uso do token e calcula o custo usando a tabela de preços. Veja detalhes em **Painel → Uso** por provedor, modelo e chave de API. + +--- + +### Transcrição de áudio + +OmniRoute oferece suporte à transcrição de áudio por meio do endpoint compatível com 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" +``` + +Provedores disponíveis: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +### Estratégias de balanceamento de combinação + +Configure o balanceamento por combo em **Painel → Combos → Criar/Editar → Estratégia**. + +| Estratégia | Descrição | +| ------------------- | ----------------------------------------------------------------------------------------- | +| **Round-Robin** | Gira pelos modelos sequencialmente | +| **Prioridade** | Tenta sempre o primeiro modelo; recorre apenas ao erro | +| **Aleatório** | Escolhe um modelo aleatório do combo para cada solicitação | +| **Ponderada** | Rotas proporcionalmente com base nos pesos atribuídos por modelo | +| **Menos usado** | Rotas para o modelo com o menor número de solicitações recentes (usa métricas combinadas) | +| **Custo Otimizado** | Rotas para o modelo mais barato disponível (usa tabela de preços) | + +Os padrões de combinação global podem ser definidos em **Painel → Configurações → Roteamento → Padrões de combinação**. + +--- + +### Painel de saúde + +Acesso via **Painel → Saúde**. Visão geral da integridade do sistema em tempo real com 6 cartões: + +| Cartão | O que mostra | +| -------------------------- | ----------------------------------------------------------------------- | +| **Status do sistema** | Tempo de atividade, versão, uso de memória, diretório de dados | +| **Provedor de Saúde** | Estado do disjuntor por fornecedor (Fechado/Aberto/Meio-aberto) | +| **Limites de Tarifas** | Cooldowns de limite de taxa ativa por conta com tempo restante | +| **Bloqueios ativos** | Prestadores bloqueados temporariamente pela política de lockout | +| **Cache de Assinaturas** | Estatísticas do cache de desduplicação (chaves ativas, taxa de acertos) | +| **Telemetria de latência** | Agregação de latência p50/p95/p99 por provedor | + +**Dica profissional:** a página Saúde é atualizada automaticamente a cada 10 segundos. Use a placa do disjuntor para identificar quais provedores estão enfrentando problemas. diff --git a/docs/i18n/pt/API_REFERENCE.md b/docs/i18n/pt/API_REFERENCE.md new file mode 100644 index 0000000000..b607ba62ef --- /dev/null +++ b/docs/i18n/pt/API_REFERENCE.md @@ -0,0 +1,441 @@ +# Referência de 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) + +Referência completa para todos os endpoints da API OmniRoute. + +--- + +## Índice + +- [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) + +--- + +## Conclusões de bate-papo + +```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 +} +``` + +### Cabeçalhos personalizados + +| Cabeçalho | Direção | Descrição | +| ------------------------ | ----------- | ---------------------------------------------------------- | +| `X-OmniRoute-No-Cache` | Solicitação | Defina como `true` para ignorar o cache | +| `X-OmniRoute-Progress` | Solicitação | Defina como `true` para eventos de progresso | +| `Idempotency-Key` | Solicitação | Chave de desduplicação (janela 5s) | +| `X-Request-Id` | Solicitação | Chave de desduplicação alternativa | +| `X-OmniRoute-Cache` | Resposta | `HIT` ou `MISS` (sem streaming) | +| `X-OmniRoute-Idempotent` | Resposta | `true` se desduplicado | +| `X-OmniRoute-Progress` | Resposta | `enabled` se o acompanhamento do progresso estiver ativado | + +--- + +## Incorporações + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Provedores disponíveis: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## Geração de imagem + +```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" +} +``` + +Provedores disponíveis: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## Listar modelos + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## Terminais de compatibilidade + +| Método | Caminho | Formato | +| ------ | --------------------------- | -------------------- | +| POSTAR | `/v1/chat/completions` | OpenAI | +| POSTAR | `/v1/messages` | Antrópico | +| POSTAR | `/v1/responses` | Respostas OpenAI | +| POSTAR | `/v1/embeddings` | OpenAI | +| POSTAR | `/v1/images/generations` | OpenAI | +| OBTER | `/v1/models` | OpenAI | +| POSTAR | `/v1/messages/count_tokens` | Antrópico | +| OBTER | `/v1beta/models` | Gêmeos | +| POSTAR | `/v1beta/models/{...path}` | Gêmeos gera conteúdo | +| POSTAR | `/v1/api/chat` | Ollama | + +### Rotas de provedores dedicados + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. + +--- + +## Cache Semântico + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +Exemplo de resposta: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Painel e gerenciamento + +### Autenticação + +| Ponto final | Método | Descrição | +| ----------------------------- | ------------- | ------------------------- | +| `/api/auth/login` | POSTAR | Entrar | +| `/api/auth/logout` | POSTAR | Sair | +| `/api/settings/require-login` | OBTER/COLOCAR | Alternar login necessário | + +### Gerenciamento de Provedores + +| Ponto final | Método | Descrição | +| ---------------------------- | --------------------- | -------------------------------- | +| `/api/providers` | OBTER/POSTAR | Listar/criar provedores | +| `/api/providers/[id]` | OBTER/COLOCAR/EXCLUIR | Gerenciar um provedor | +| `/api/providers/[id]/test` | POSTAR | Testar conexão do provedor | +| `/api/providers/[id]/models` | OBTER | Listar modelos de provedores | +| `/api/providers/validate` | POSTAR | Validar configuração do provedor | +| `/api/provider-nodes*` | Vários | Gerenciamento de nós de provedor | +| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | Modelos personalizados | + +### Fluxos OAuth + +| Ponto final | Método | Descrição | +| -------------------------------- | ------ | ---------------------------- | +| `/api/oauth/[provider]/[action]` | Vários | OAuth específico do provedor | + +### Roteamento e configuração + +| Ponto final | Método | Descrição | +| --------------------- | ------------ | -------------------------------------- | +| `/api/models/alias` | OBTER/POSTAR | Aliases de modelo | +| `/api/models/catalog` | OBTER | Todos os modelos por fornecedor + tipo | +| `/api/combos*` | Vários | Gestão de combos | +| `/api/keys*` | Vários | Gerenciamento de chaves API | +| `/api/pricing` | OBTER | Preços do modelo | + +### Uso e análise + +| Ponto final | Método | Descrição | +| --------------------------- | ------ | ---------------------------- | +| `/api/usage/history` | OBTER | Histórico de uso | +| `/api/usage/logs` | OBTER | Registros de uso | +| `/api/usage/request-logs` | OBTER | Logs em nível de solicitação | +| `/api/usage/[connectionId]` | OBTER | Uso por conexão | + +### Configurações + +| Ponto final | Método | Descrição | +| ------------------------------- | ------------- | -------------------------------------------- | +| `/api/settings` | OBTER/COLOCAR | Configurações gerais | +| `/api/settings/proxy` | OBTER/COLOCAR | Configuração de proxy de rede | +| `/api/settings/proxy/test` | POSTAR | Testar conexão proxy | +| `/api/settings/ip-filter` | OBTER/COLOCAR | Lista de permissões/lista de bloqueios de IP | +| `/api/settings/thinking-budget` | OBTER/COLOCAR | Orçamento de token de raciocínio | +| `/api/settings/system-prompt` | OBTER/COLOCAR | Alerta do sistema global | + +### Monitoramento + +| Ponto final | Método | Descrição | +| ------------------------ | ------------- | ------------------------------ | +| `/api/sessions` | OBTER | Acompanhamento de sessão ativa | +| `/api/rate-limits` | OBTER | Limites de taxas por conta | +| `/api/monitoring/health` | OBTER | Exame de saúde | +| `/api/cache` | OBTER/EXCLUIR | Estatísticas de cache/limpar | + +### Backup e exportação/importação + +| Ponto final | Método | Descrição | +| --------------------------- | ------- | ------------------------------------------------------- | +| `/api/db-backups` | OBTER | Listar backups disponíveis | +| `/api/db-backups` | COLOCAR | Crie um backup manual | +| `/api/db-backups` | POSTAR | Restaurar de um backup específico | +| `/api/db-backups/export` | OBTER | Baixe o banco de dados como arquivo .sqlite | +| `/api/db-backups/import` | POSTAR | Carregar arquivo .sqlite para substituir banco de dados | +| `/api/db-backups/exportAll` | OBTER | Baixe o backup completo como arquivo .tar.gz | + +### Sincronização na nuvem + +| Ponto final | Método | Descrição | +| ---------------------- | ------ | ----------------------------------- | +| `/api/sync/cloud` | Vários | Operações de sincronização em nuvem | +| `/api/sync/initialize` | POSTAR | Inicializar sincronização | +| `/api/cloud/*` | Vários | Gerenciamento de nuvem | + +### Ferramentas CLI + +| Ponto final | Método | Descrição | +| ---------------------------------- | ------ | ------------------------------ | +| `/api/cli-tools/claude-settings` | OBTER | Status CLI de Claude | +| `/api/cli-tools/codex-settings` | OBTER | Status da CLI do Codex | +| `/api/cli-tools/droid-settings` | OBTER | Status da CLI do Droid | +| `/api/cli-tools/openclaw-settings` | OBTER | Status da CLI do OpenClaw | +| `/api/cli-tools/runtime/[toolId]` | OBTER | Tempo de execução CLI genérico | + +As respostas CLI incluem: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### Resiliência e limites de taxas + +| Ponto final | Método | Descrição | +| ----------------------- | ------------- | ------------------------------------- | +| `/api/resilience` | OBTER/COLOCAR | Obter/atualizar perfis de resiliência | +| `/api/resilience/reset` | POSTAR | Reinicializar disjuntores | +| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | +| `/api/rate-limit` | OBTER | Configuração de limite de taxa global | + +### Avaliações + +| Ponto final | Método | Descrição | +| ------------ | ------------ | --------------------------------------------- | +| `/api/evals` | OBTER/POSTAR | Listar suítes de avaliação/executar avaliação | + +### Políticas + +| Ponto final | Método | Descrição | +| --------------- | -------------------- | --------------------------------- | +| `/api/policies` | OBTER/POSTAR/EXCLUIR | Gerenciar políticas de roteamento | + +### Conformidade + +| Ponto final | Método | Descrição | +| --------------------------- | ------ | ----------------------------------------------- | +| `/api/compliance/audit-log` | OBTER | Registo de auditoria de conformidade (último N) | + +### v1beta (compatível com Gemini) + +| Ponto final | Método | Descrição | +| -------------------------- | ------ | --------------------------------------------- | +| `/v1beta/models` | OBTER | Listar modelos no formato Gemini | +| `/v1beta/models/{...path}` | POSTAR | Ponto de extremidade Gêmeos `generateContent` | + +Esses endpoints refletem o formato API do Gemini para clientes que esperam compatibilidade nativa do Gemini SDK. + +### APIs internas/do sistema + +| Ponto final | Método | Descrição | +| --------------- | ------ | ----------------------------------------------------------------------- | +| `/api/init` | OBTER | Verificação de inicialização do aplicativo (usada na primeira execução) | +| `/api/tags` | OBTER | Tags de modelo compatíveis com Ollama (para clientes Ollama) | +| `/api/restart` | POSTAR | Acionar reinicialização normal do servidor | +| `/api/shutdown` | POSTAR | Acionar o desligamento normal do servidor | + +> **Observação:** Esses endpoints são usados internamente pelo sistema ou para compatibilidade do cliente Ollama. Eles normalmente não são chamados pelos usuários finais. + +--- + +## Transcrição de áudio + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Transcreva arquivos de áudio usando Deepgram ou AssemblyAI. + +**Solicitação:** + +```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" +``` + +**Resposta:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**Provedores suportados:** `deepgram/nova-3`, `assemblyai/best`. + +**Formatos suportados:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +## Compatibilidade com Ollama + +Para clientes que usam o formato API do Ollama: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +As solicitações são traduzidas automaticamente entre o Ollama e os formatos internos. + +--- + +## Telemetria + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Resposta:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## Orçamento + +```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" +} +``` + +--- + +## Disponibilidade do modelo + +```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" +} +``` + +--- + +## Processamento de solicitação + +1. Cliente envia solicitação para `/v1/*` +2. O manipulador de rota chama `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration` +3. O modelo foi resolvido (provedor/modelo direto ou alias/combo) +4. Credenciais selecionadas do banco de dados local com filtragem de disponibilidade de conta +5. Para bate-papo: `handleChatCore` — detecção de formato, tradução, verificação de cache, verificação de idempotência +6. O executor do provedor envia uma solicitação upstream +7. Resposta traduzida de volta para o formato do cliente (chat) ou retornada como está (incorporações/imagens/áudio) +8. Uso/registro registrado +9. Fallback se aplica a erros de acordo com regras de combinação + +Referência completa da arquitetura: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## Autenticação + +- Rotas do painel (`/dashboard/*`) usam cookie `auth_token` +- O login utiliza hash de senha salva; substituto para `INITIAL_PASSWORD` +- `requireLogin` alternável via `/api/settings/require-login` +- As rotas `/v1/*` requerem opcionalmente a chave da API do portador quando `REQUIRE_API_KEY=true` diff --git a/docs/i18n/pt/ARCHITECTURE.md b/docs/i18n/pt/ARCHITECTURE.md new file mode 100644 index 0000000000..1b7e0f1766 --- /dev/null +++ b/docs/i18n/pt/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# Arquitetura 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) + +_Última atualização: 18/02/2026_ + +## Resumo Executivo + +OmniRoute é um gateway de roteamento de IA local e painel construído em Next.js. +Ele fornece um único endpoint compatível com OpenAI (`/v1/*`) e roteia o tráfego entre vários provedores upstream com tradução, fallback, atualização de token e rastreamento de uso. + +Capacidades principais: + +- Superfície API compatível com OpenAI para CLI/ferramentas (28 provedores) +- Tradução de solicitação/resposta em formatos de provedores +- Fallback de combinação de modelos (sequência de vários modelos) +- Fallback em nível de conta (várias contas por provedor) +- Gerenciamento de conexão de provedor de chave OAuth + API +- Geração de incorporação via `/v1/embeddings` (6 provedores, 9 modelos) +- Geração de imagens via `/v1/images/generations` (4 provedores, 9 modelos) +- Pense na análise de tags (`...`) para modelos de raciocínio +- Sanitização de resposta para compatibilidade estrita com OpenAI SDK +- Normalização de funções (desenvolvedor→sistema, sistema→usuário) para compatibilidade entre provedores +- Conversão de saída estruturada (json_schema → Gemini responseSchema) +- Persistência local para provedores, chaves, aliases, combos, configurações, preços +- Acompanhamento de uso/custo e registro de solicitações +- Sincronização em nuvem opcional para sincronização de vários dispositivos/estado +- Lista de permissões/lista de bloqueio de IP para controle de acesso à API +- Pensando na gestão orçamentária (passthrough/auto/custom/adaptive) +- Injeção imediata do sistema global +- Rastreamento de sessão e impressão digital +- Limitação de taxa aprimorada por conta com perfis específicos do provedor +- Padrão de disjuntor para resiliência do provedor +- Proteção de rebanho anti-trovão com bloqueio mutex +- Cache de desduplicação de solicitação baseada em assinatura +- Camada de domínio: disponibilidade do modelo, regras de custo, política de fallback, política de bloqueio +- Persistência de estado de domínio (cache write-through SQLite para fallbacks, orçamentos, bloqueios, disjuntores) +- Mecanismo de política para avaliação centralizada de solicitações (bloqueio → orçamento → fallback) +- Solicitar telemetria com agregação de latência p50/p95/p99 +- ID de correlação (X-Request-Id) para rastreamento ponta a ponta +- Registro de auditoria de conformidade com cancelamento por chave de API +- Estrutura de avaliação para garantia de qualidade LLM +- Painel de UI de resiliência com status do disjuntor em tempo real +- Provedores OAuth modulares (12 módulos individuais em `src/lib/oauth/providers/`) + +Modelo de tempo de execução primário: + +- As rotas do aplicativo Next.js em `src/app/api/*` implementam APIs de painel e APIs de compatibilidade +- Um núcleo SSE/roteamento compartilhado em `src/sse/*` + `open-sse/*` lida com execução, tradução, streaming, fallback e uso do provedor + +## Escopo e limites + +### No escopo + +- Tempo de execução do gateway local +- APIs de gerenciamento de painel +- Autenticação do provedor e atualização de token +- Solicitar tradução e streaming SSE +- Estado local + persistência de uso +- Orquestração opcional de sincronização em nuvem + +### Fora do escopo + +- Implementação de serviço em nuvem por trás de `NEXT_PUBLIC_CLOUD_URL` +- Plano de controle/SLA do provedor fora do processo local +- Os próprios binários CLI externos (Claude CLI, Codex CLI, etc.) + +## Contexto do sistema de alto nível + +```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 +``` + +## Componentes principais de tempo de execução + +## 1) API e camada de roteamento (rotas de aplicativos Next.js) + +Diretórios principais: + +- `src/app/api/v1/*` e `src/app/api/v1beta/*` para APIs de compatibilidade +- `src/app/api/*` para APIs de gerenciamento/configuração +- Próximas reescritas em `next.config.mjs` mapeiam `/v1/*` para `/api/v1/*` + +Rotas de compatibilidade importantes: + +- `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` — inclui modelos personalizados com `custom: true` +- `src/app/api/v1/embeddings/route.ts` — geração de incorporação (6 provedores) +- `src/app/api/v1/images/generations/route.ts` — geração de imagens (4+ provedores incluindo Antigravidade/Nebius) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — bate-papo dedicado por provedor +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — embeddings dedicados por provedor +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagens dedicadas por provedor +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Domínios de gerenciamento: + +- Autenticação/configurações: `src/app/api/auth/*`, `src/app/api/settings/*` +- Provedores/conexões: `src/app/api/providers*` +- Nós do provedor: `src/app/api/provider-nodes*` +- Modelos personalizados: `src/app/api/provider-models` (GET/POST/DELETE) +- Catálogo de modelos: `src/app/api/models/catalog` (GET) +- Configuração de proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Chaves/aliases/combos/preços: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Uso: `src/app/api/usage/*` +- Sincronização/nuvem: `src/app/api/sync/*`, `src/app/api/cloud/*` +- Ajudantes de ferramentas CLI: `src/app/api/cli-tools/*` +- Filtro IP: `src/app/api/settings/ip-filter` (GET/PUT) +- Orçamento pensado: `src/app/api/settings/thinking-budget` (GET/PUT) +- Prompt do sistema: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessões: `src/app/api/sessions` (GET) +- Limites de taxa: `src/app/api/rate-limits` (GET) +- Resiliência: `src/app/api/resilience` (GET/PATCH) — perfis de provedor, disjuntor, estado limite de taxa +- Redefinição de resiliência: `src/app/api/resilience/reset` (POST) — redefinir disjuntores + resfriamento +- Estatísticas de cache: `src/app/api/cache/stats` (GET/DELETE) +- Disponibilidade do modelo: `src/app/api/models/availability` (GET/POST) +- Telemetria: `src/app/api/telemetry/summary` (GET) +- Orçamento: `src/app/api/usage/budget` (GET/POST) +- Cadeias de fallback: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Auditoria de conformidade: `src/app/api/compliance/audit-log` (GET) +- Avaliações: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Políticas: `src/app/api/policies` (GET/POST) + +## 2) SSE + Núcleo de Tradução + +Principais módulos de fluxo: + +- Entrada: `src/sse/handlers/chat.ts` +- Orquestração principal: `open-sse/handlers/chatCore.ts` +- Adaptadores de execução do provedor: `open-sse/executors/*` +- Detecção de formato/configuração do provedor: `open-sse/services/provider.ts` +- Análise/resolução de modelo: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Lógica de substituição da conta: `open-sse/services/accountFallback.ts` +- Registro de tradução: `open-sse/translator/index.ts` +- Transformações de fluxo: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Extração/normalização de uso: `open-sse/utils/usageTracking.ts` +- Pense no analisador de tags: `open-sse/utils/thinkTagParser.ts` +- Manipulador de incorporação: `open-sse/handlers/embeddings.ts` +- Incorporação de registro de provedor: `open-sse/config/embeddingRegistry.ts` +- Manipulador de geração de imagem: `open-sse/handlers/imageGeneration.ts` +- Registro do provedor de imagens: `open-sse/config/imageRegistry.ts` +- Sanitização de resposta: `open-sse/handlers/responseSanitizer.ts` +- Normalização de função: `open-sse/services/roleNormalizer.ts` + +Serviços (lógica de negócios): + +- Seleção/pontuação de conta: `open-sse/services/accountSelector.ts` +- Gerenciamento do ciclo de vida do contexto: `open-sse/services/contextManager.ts` +- Aplicação do filtro IP: `open-sse/services/ipFilter.ts` +- Acompanhamento de sessão: `open-sse/services/sessionManager.ts` +- Solicitar desduplicação: `open-sse/services/signatureCache.ts` +- Injeção de prompt do sistema: `open-sse/services/systemPrompt.ts` +- Pensando na gestão orçamentária: `open-sse/services/thinkingBudget.ts` +- Roteamento de modelo curinga: `open-sse/services/wildcardRouter.ts` +- Gerenciamento de limite de taxa: `open-sse/services/rateLimitManager.ts` +- Disjuntor: `open-sse/services/circuitBreaker.ts` + +Módulos da camada de domínio: + +- Disponibilidade do modelo: `src/lib/domain/modelAvailability.ts` +- Regras/orçamentos de custos: `src/lib/domain/costRules.ts` +- Política de substituto: `src/lib/domain/fallbackPolicy.ts` +- Resolvedor combinado: `src/lib/domain/comboResolver.ts` +- Política de bloqueio: `src/lib/domain/lockoutPolicy.ts` +- Mecanismo de política: `src/domain/policyEngine.ts` — bloqueio centralizado → orçamento → avaliação alternativa +- Catálogo de códigos de erro: `src/lib/domain/errorCodes.ts` +- ID da solicitação: `src/lib/domain/requestId.ts` +- Tempo limite de busca: `src/lib/domain/fetchTimeout.ts` +- Solicitar telemetria: `src/lib/domain/requestTelemetry.ts` +- Conformidade/auditoria: `src/lib/domain/compliance/index.ts` +- Corredor de avaliação: `src/lib/domain/evalRunner.ts` +- Persistência de estado de domínio: `src/lib/db/domainState.ts` — SQLite CRUD para cadeias de fallback, orçamentos, histórico de custos, estado de bloqueio, disjuntores + +Módulos do provedor OAuth (12 arquivos individuais em `src/lib/oauth/providers/`): + +- Índice de registro: `src/lib/oauth/providers/index.ts` +- Provedores individuais: `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` +- Thin wrapper: `src/lib/oauth/providers.ts` — reexportações de módulos individuais + +## 3) Camada de Persistência + +Banco de dados de estado primário: + +- `src/lib/localDb.ts` +- arquivo: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) +- entidades: ProviderConnections, ProviderNodes, modelAliases, combos, apiKeys, configurações, preços, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Banco de dados de uso: + +- `src/lib/usageDb.ts` +- arquivos: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- segue a mesma política de diretório base de `localDb` (`DATA_DIR`, então `XDG_CONFIG_HOME/omniroute` quando definido) +- decomposto em submódulos focados: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +Banco de dados de estado de domínio (SQLite): + +- `src/lib/db/domainState.ts` — Operações CRUD para estado de domínio +- Tabelas (criadas em `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers` +- Padrão de cache write-through: os mapas na memória são autoritativos em tempo de execução; as mutações são escritas de forma síncrona no SQLite; o estado é restaurado do banco de dados na inicialização a frio + +## 4) Superfícies de autenticação + segurança + +- Autenticação de cookie do painel: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- Geração/verificação de chave de API: `src/shared/utils/apiKey.ts` +- Os segredos do provedor persistiram nas entradas `providerConnections` +- Suporte a proxy de saída via `open-sse/utils/proxyFetch.ts` (env vars) e `open-sse/utils/networkProxy.ts` (configurável por provedor ou global) + +## 5) Sincronização na nuvem + +- Inicialização do agendador: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Tarefa periódica: `src/shared/services/cloudSyncScheduler.ts` +- Rota de controle: `src/app/api/sync/cloud/route.ts` + +## Ciclo de vida da solicitação (`/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 + Fluxo substituto da conta + +```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] +``` + +As decisões de fallback são orientadas por `open-sse/services/accountFallback.ts` usando códigos de status e heurísticas de mensagens de erro. + +## Integração do OAuth e ciclo de vida de atualização de 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 +``` + +A atualização durante o tráfego ativo é executada dentro de `open-sse/handlers/chatCore.ts` por meio do executor `refreshCredentials()`. + +## Ciclo de vida da sincronização na nuvem (ativar/sincronizar/desativar) + +```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 +``` + +A sincronização periódica é acionada por `CloudSyncScheduler` quando a nuvem está habilitada. + +## Modelo de dados e mapa de armazenamento + +```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 + } +``` + +Arquivos de armazenamento físico: + +- estado principal: `${DATA_DIR}/db.json` (ou `$XDG_CONFIG_HOME/omniroute/db.json` quando definido, caso contrário, `~/.omniroute/db.json`) +- estatísticas de uso: `${DATA_DIR}/usage.json` +- solicitar linhas de registro: `${DATA_DIR}/log.txt` +- sessões opcionais de depuração de tradução/solicitação: `/logs/...` + +## Topologia de implantação + +```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 +``` + +## Mapeamento de módulos (crítico para decisões) + +### Módulos de rota e API + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: APIs de compatibilidade +- `src/app/api/v1/providers/[provider]/*`: rotas dedicadas por provedor (chat, embeddings, imagens) +- `src/app/api/providers*`: provedor CRUD, validação, teste +- `src/app/api/provider-nodes*`: gerenciamento de nó compatível personalizado +- `src/app/api/provider-models`: gerenciamento de modelo personalizado (CRUD) +- `src/app/api/models/catalog`: API de catálogo de modelos completo (todos os tipos agrupados por provedor) +- `src/app/api/oauth/*`: fluxos OAuth/código do dispositivo +- `src/app/api/keys*`: ciclo de vida da chave de API local +- `src/app/api/models/alias`: gerenciamento de alias +- `src/app/api/combos*`: gerenciamento de combinação alternativa +- `src/app/api/pricing`: substituições de preços para cálculo de custos +- `src/app/api/settings/proxy`: configuração de proxy (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: teste de conectividade de proxy de saída (POST) +- `src/app/api/usage/*`: APIs de uso e registros +- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronização na nuvem e ajudantes voltados para a nuvem +- `src/app/api/cli-tools/*`: gravadores/verificadores de configuração CLI locais +- `src/app/api/settings/ip-filter`: lista de permissões/lista de bloqueios de IP (GET/PUT) +- `src/app/api/settings/thinking-budget`: configuração do orçamento do token de pensamento (GET/PUT) +- `src/app/api/settings/system-prompt`: prompt global do sistema (GET/PUT) +- `src/app/api/sessions`: listagem de sessões ativas (GET) +- `src/app/api/rate-limits`: status de limite de taxa por conta (GET) + +### Núcleo de Roteamento e Execução + +- `src/sse/handlers/chat.ts`: análise de solicitação, tratamento de combinação, loop de seleção de conta +- `open-sse/handlers/chatCore.ts`: tradução, envio do executor, manipulação de novas tentativas/atualizações, configuração de stream +- `open-sse/executors/*`: rede específica do provedor e comportamento do formato + +### Registro de tradução e conversores de formato + +- `open-sse/translator/index.ts`: registro e orquestração do tradutor +- Solicitar tradutores: `open-sse/translator/request/*` +- Tradutores de resposta: `open-sse/translator/response/*` +- Constantes de formato: `open-sse/translator/formats.ts` + +### Persistência + +- `src/lib/localDb.ts`: configuração/estado persistente +- `src/lib/usageDb.ts`: histórico de uso e registros de solicitação contínua + +## Cobertura do Executor do Provedor (Padrão de Estratégia) + +Cada provedor tem um executor especializado que estende `BaseExecutor` (em `open-sse/executors/base.ts`), que fornece construção de URL, construção de cabeçalho, nova tentativa com espera exponencial, ganchos de atualização de credenciais e o método de orquestração `execute()`. + +| Executor | Fornecedor(es) | Tratamento Especial | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Juntos, Fireworks, Cerebras, Cohere, NVIDIA | Configuração dinâmica de URL/cabeçalho por provedor | +| `AntigravityExecutor` | Antigravidade do Google | IDs de projeto/sessão personalizados, análise repetida após | +| `CodexExecutor` | Códice OpenAI | Injeta instruções do sistema, força esforço de raciocínio | +| `CursorExecutor` | Cursor IDE | Protocolo ConnectRPC, codificação Protobuf, assinatura de solicitação via checksum | +| `GithubExecutor` | Copiloto GitHub | Atualização de token do copiloto, cabeçalhos que imitam VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | Formato binário AWS EventStream → conversão SSE | +| `GeminiCLIExecutor` | Gêmeos CLI | Ciclo de atualização do token OAuth do Google | + +Todos os outros provedores (incluindo nós compatíveis personalizados) usam `DefaultExecutor`. + +## Matriz de compatibilidade do provedor + +| Provedor | Formato | Autenticação | Transmitir | Não-transmissão | Atualização de token | API de uso | +| ------------------------ | ---------------- | --------------------------------- | ---------------- | --------------- | -------------------- | ------------------------ | +| Cláudio | Cláudio | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️ Somente administrador | +| Gêmeos | gêmeos | Chave API/OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | +| Gêmeos CLI | gêmeo-cli | OAuth | ✅ | ✅ | ✅ | ⚠️Console em nuvem | +| Antigravidade | antigravidade | OAuth | ✅ | ✅ | ✅ | ✅ API de cota completa | +| OpenAI | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Códice | respostas openai | OAuth | ✅ forçado | ❌ | ✅ | ✅ Limites de taxas | +| Copiloto GitHub | abrirai | OAuth + token de copiloto | ✅ | ✅ | ✅ | ✅ Instantâneos de cota | +| Cursor | cursor | Soma de verificação personalizada | ✅ | ✅ | ❌ | ❌ | +| Kiro | Kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limites de uso | +| Qwen | abrirai | OAuth | ✅ | ✅ | ✅ | ⚠️ Por solicitação | +| iFlow | abrirai | OAuth (Básico) | ✅ | ✅ | ✅ | ⚠️ Por solicitação | +| OpenRouter | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | Cláudio | Chave API | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Groq | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| xAI (Groque) | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Mistral | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Perplexidade | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Juntos IA | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| IA de fogos de artifício | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Cérebros | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| Coerente | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | abrirai | Chave API | ✅ | ✅ | ❌ | ❌ | + +## Cobertura de tradução de formato + +Os formatos de origem detectados incluem: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Os formatos de destino incluem: + +- Bate-papo/respostas OpenAI + -Cláudio +- Envelope Gemini/Gemini-CLI/Antigravidade + -Kiro +- Cursor + +As traduções usam **OpenAI como formato de hub** — todas as conversões passam pelo OpenAI como intermediário: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +As traduções são selecionadas dinamicamente com base no formato da carga útil de origem e no formato de destino do provedor. + +Camadas de processamento adicionais no pipeline de tradução: + +- **Sanitização de respostas** — Remove campos não padrão de respostas no formato OpenAI (streaming e não streaming) para garantir conformidade estrita com o SDK +- **Normalização de funções** — Converte `developer` → `system` para alvos não-OpenAI; mescla `system` → `user` para modelos que rejeitam a função do sistema (GLM, ERNIE) +- **Extração de tag Think** — Analisa blocos `...` do conteúdo no campo `reasoning_content` +- **Saída estruturada** — Converte OpenAI `response_format.json_schema` em `responseMimeType` + `responseSchema` do Gemini + +## Terminais de API suportados + +| Ponto final | Formato | Manipulador | +| -------------------------------------------------- | ---------------------------- | -------------------------------------------------------------- | +| `POST /v1/chat/completions` | Bate-papo OpenAI | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Mensagens de Cláudio | Mesmo manipulador (detectado automaticamente) | +| `POST /v1/responses` | Respostas OpenAI | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | Incorporações OpenAI | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Listagem de modelos | Rota API | +| `POST /v1/images/generations` | Imagens OpenAI | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Listagem de modelos | Rota API | +| `POST /v1/providers/{provider}/chat/completions` | Bate-papo OpenAI | Dedicado por provedor com validação de modelo | +| `POST /v1/providers/{provider}/embeddings` | Incorporações OpenAI | Dedicado por provedor com validação de modelo | +| `POST /v1/providers/{provider}/images/generations` | Imagens OpenAI | Dedicado por provedor com validação de modelo | +| `POST /v1/messages/count_tokens` | Contagem de tokens de Claude | Rota API | +| `GET /v1/models` | Lista de modelos OpenAI | Rota API (chat + incorporação + imagem + modelos customizados) | +| `GET /api/models/catalog` | Catálogo | Todos os modelos agrupados por fornecedor + tipo | +| `POST /v1beta/models/*:streamGenerateContent` | Nativo de Gêmeos | Rota API | +| `GET/PUT/DELETE /api/settings/proxy` | Configuração de proxy | Configuração de proxy de rede | +| `POST /api/settings/proxy/test` | Conectividade proxy | Endpoint de teste de integridade/conectividade do proxy | +| `GET/POST/DELETE /api/provider-models` | Modelos personalizados | Gestão de modelos customizados por provedor | + +## Ignorar manipulador + +O manipulador de bypass (`open-sse/utils/bypassHandler.ts`) intercepta solicitações "descartáveis" conhecidas da CLI de Claude — pings de aquecimento, extrações de títulos e contagens de tokens — e retorna uma **resposta falsa** sem consumir tokens do provedor upstream. Isso é acionado somente quando `User-Agent` contém `claude-cli`. + +## Solicitar pipeline do registrador + +O registrador de solicitações (`open-sse/utils/requestLogger.ts`) fornece um pipeline de registro de depuração de 7 estágios, desabilitado por padrão, habilitado por meio de `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 +``` + +Os arquivos são gravados em `/logs//` para cada sessão de solicitação. + +## Modos de falha e resiliência + +## 1) Disponibilidade da conta/provedor + +- resfriamento da conta do provedor em erros transitórios/taxa/autenticação +- fallback da conta antes da falha na solicitação +- modelo combinado substituto quando o caminho do modelo/provedor atual se esgota + +## 2) Expiração do token + +- pré-verificação e atualização com nova tentativa para provedores atualizáveis +- Nova tentativa 401/403 após tentativa de atualização no caminho principal + +## 3) Segurança de transmissão + +- controlador de fluxo com reconhecimento de desconexão +- fluxo de tradução com liberação de fim de fluxo e manipulação de `[DONE]` +- fallback de estimativa de uso quando faltam metadados de uso do provedor + +## 4) Degradação da sincronização na nuvem + +- erros de sincronização aparecem, mas o tempo de execução local continua +- o agendador tem lógica com capacidade de repetição, mas a execução periódica atualmente chama a sincronização de tentativa única por padrão + +## 5) Integridade de dados + +- Migração/reparo de formato de banco de dados para chaves ausentes +- proteções de redefinição JSON corrompidas para localDb e usageDb + +## Observabilidade e Sinais Operacionais + +Fontes de visibilidade em tempo de execução: + +- registros do console de `src/sse/utils/logger.ts` +- agregados de uso por solicitação em `usage.json` +- registro de status da solicitação textual em `log.txt` +- registros opcionais de solicitação/tradução profunda em `logs/` quando `ENABLE_REQUEST_LOGS=true` +- endpoints de uso do painel (`/api/usage/*`) para consumo de UI + +## Limites sensíveis à segurança + +- Segredo JWT (`JWT_SECRET`) protege a verificação/assinatura de cookies da sessão do painel +- O substituto de senha inicial (`INITIAL_PASSWORD`, padrão `123456`) deve ser substituído em implantações reais +- O segredo HMAC da chave de API (`API_KEY_SECRET`) protege o formato de chave de API local gerado +- Os segredos do provedor (chaves/tokens de API) persistem no banco de dados local e devem ser protegidos no nível do sistema de arquivos +- Os endpoints de sincronização em nuvem dependem da semântica de autenticação de chave de API + ID de máquina + +## Matriz de Ambiente e Tempo de Execução + +Variáveis de ambiente usadas ativamente pelo código: + +- Aplicativo/autenticação: `JWT_SECRET`, `INITIAL_PASSWORD` +- Armazenamento: `DATA_DIR` +- Comportamento do nó compatível: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Substituição opcional da base de armazenamento (Linux/macOS quando `DATA_DIR` não definido): `XDG_CONFIG_HOME` +- Hash de segurança: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Registro: `ENABLE_REQUEST_LOGS` +- URL de sincronização/nuvem: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Proxy de saída: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` e variantes minúsculas +- Sinalizadores de recurso SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Auxiliares de plataforma/tempo de execução (não configuração específica do aplicativo): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Notas arquitetônicas conhecidas + +1. `usageDb` e `localDb` agora compartilham a mesma política de diretório base (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) com migração de arquivo legado. +2. `/api/v1/route.ts` retorna uma lista de modelos estáticos e não é a principal fonte de modelos usada por `/v1/models`. +3. O registrador de solicitações grava cabeçalhos/corpo completos quando habilitado; trate o diretório de log como confidencial. +4. O comportamento da nuvem depende do `NEXT_PUBLIC_BASE_URL` correto e da acessibilidade do endpoint na nuvem. +5. O diretório `open-sse/` é publicado como o `@omniroute/open-sse` **pacote de espaço de trabalho npm**. O código-fonte o importa via `@omniroute/open-sse/...` (resolvido por Next.js `transpilePackages`). Os caminhos de arquivo neste documento ainda usam o nome de diretório `open-sse/` para consistência. +6. Os gráficos no painel usam **Recharts** (baseados em SVG) para visualizações analíticas interativas e acessíveis (gráficos de barras de uso de modelo, tabelas de detalhamento de fornecedores com taxas de sucesso). +7. Os testes E2E usam **Playwright** (`tests/e2e/`), executados via `npm run test:e2e`. Os testes de unidade usam o **executor de testes Node.js** (`tests/unit/`), executado por meio de `npm run test:plan3`. O código-fonte em `src/` é **TypeScript** (`.ts`/`.tsx`); o espaço de trabalho `open-sse/` permanece JavaScript (`.js`). +8. A página de configurações é organizada em 5 guias: Segurança, Roteamento (6 estratégias globais: preenchimento primeiro, round-robin, p2c, aleatório, menos usado, com custo otimizado), Resiliência (limites de taxa editáveis, disjuntor, políticas), IA (pensando no orçamento, prompt do sistema, cache de prompt), Avançado (proxy). + +## Lista de verificação de verificação operacional + +- Construir a partir da fonte: `npm run build` +- Construir imagem Docker: `docker build -t omniroute .` +- Inicie o serviço e verifique: +- `GET /api/settings` +- `GET /api/v1/models` +- O URL base de destino da CLI deve ser `http://:20128/v1` quando `PORT=20128` diff --git a/docs/i18n/pt/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..16693c3fb1 --- /dev/null +++ b/docs/i18n/pt/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute — Documentação da base de código + +🌐 **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) + +> Um guia abrangente e para iniciantes sobre o roteador proxy AI multiprovedor **omniroute**. + +--- + +## 1. O que é OmniRoute? + +omniroute é um **roteador proxy** que fica entre clientes de IA (Claude CLI, Codex, Cursor IDE, etc.) e provedores de IA (Anthropic, Google, OpenAI, AWS, GitHub, etc.). Isso resolve um grande problema: + +> **Diferentes clientes de IA falam "idiomas" diferentes (formatos de API), e diferentes provedores de IA também esperam "idiomas" diferentes.** omniroute traduz entre eles automaticamente. + +Pense nisso como um tradutor universal nas Nações Unidas – qualquer delegado pode falar qualquer idioma, e o tradutor converte para qualquer outro delegado. + +--- + +## 2. Visão geral da arquitetura + +```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 +``` + +### Princípio Básico: Tradução Hub-and-Spoke + +Toda a tradução de formato passa pelo **formato OpenAI como hub**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +Isso significa que você só precisa de **N tradutores** (um por formato) em vez de **N²** (cada par). + +--- + +## 3. Estrutura do Projeto + +``` +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. Divisão módulo por módulo + +### 4.1 Configuração (`open-sse/config/`) + +A **única fonte de verdade** para todas as configurações do provedor. + +| Arquivo | Finalidade | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `constants.ts` | Objeto `PROVIDERS` com URLs base, credenciais OAuth (padrões), cabeçalhos e prompts de sistema padrão para cada provedor. Também define `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` e `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Carrega credenciais externas de `data/provider-credentials.json` e as mescla nos padrões codificados em `PROVIDERS`. Mantém os segredos fora do controle de origem, mantendo a compatibilidade com versões anteriores. | +| `providerModels.ts` | Registro central de modelos: aliases de provedores de mapas → IDs de modelos. Funções como `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | Instruções do sistema injetadas em solicitações do Codex (restrições de edição, regras de sandbox, políticas de aprovação). | +| `defaultThinkingSignature.ts` | Assinaturas de "pensamento" padrão para os modelos Claude e Gemini. | +| `ollamaModels.ts` | Definição de esquema para modelos locais de Ollama (nome, tamanho, família, quantização). | + +#### Fluxo de carregamento de credenciais + +```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 Executores (`open-sse/executors/`) + +Os executores encapsulam **lógica específica do provedor** usando o **Padrão de estratégia**. Cada executor substitui os métodos básicos conforme necessário. + +```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 +``` + +| Executor | Provedor | Principais Especializações | +| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Base abstrata: construção de URL, cabeçalhos, lógica de repetição, atualização de credenciais | +| `default.ts` | Claude, Gêmeos, OpenAI, GLM, Kimi, MiniMax | Atualização genérica de token OAuth para provedores padrão | +| `antigravity.ts` | Código do Google Cloud | Geração de ID de projeto/sessão, fallback de vários URLs, análise de repetição personalizada de mensagens de erro ("redefinir após 2h7m23s") | +| `cursor.ts` | Cursor IDE | **Mais complexo**: autenticação de soma de verificação SHA-256, codificação de solicitação Protobuf, EventStream binário → análise de resposta SSE | +| `codex.ts` | Códice OpenAI | Injeta instruções do sistema, gerencia níveis de pensamento, remove parâmetros não suportados | +| `gemini-cli.ts` | CLI do Google Gemini | Criação de URL personalizado (`streamGenerateContent`), atualização de token Google OAuth | +| `github.ts` | Copiloto GitHub | Sistema de token duplo (token GitHub OAuth + Copilot), imitação de cabeçalho VSCode | +| `kiro.ts` | AWS CodeWhisperer | Análise binária AWS EventStream, event frames AMZN, estimativa de token | +| `index.ts` | — | Fábrica: nome do provedor de mapas → classe do executor, com fallback padrão | + +--- + +### 4.3 Manipuladores (`open-sse/handlers/`) + +A **camada de orquestração** — coordena tradução, execução, streaming e tratamento de erros. + +| Arquivo | Finalidade | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Orquestrador central** (~600 linhas). Lida com o ciclo de vida completo da solicitação: detecção de formato → tradução → envio do executor → resposta de streaming/não streaming → atualização de token → tratamento de erros → registro de uso. | +| `responsesHandler.ts` | Adaptador para API de respostas da OpenAI: converte o formato de respostas → conclusões de bate-papo → envia para `chatCore` → converte SSE de volta para o formato de respostas. | +| `embeddings.ts` | Manipulador de geração de incorporação: resolve o modelo de incorporação → provedor, despacha para a API do provedor, retorna uma resposta de incorporação compatível com OpenAI. Suporta mais de 6 provedores. | +| `imageGeneration.ts` | Manipulador de geração de imagem: resolve modelo de imagem → provedor, suporta modos compatíveis com OpenAI, imagem Gemini (Antigravidade) e fallback (Nebius). Retorna imagens base64 ou URL. | + +#### Ciclo de vida da solicitação (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 Serviços (`open-sse/services/`) + +Lógica de negócios que dá suporte aos manipuladores e executores. + +| Arquivo | Finalidade | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Detecção de formato** (`detectFormat`): analisa a estrutura do corpo da solicitação para identificar formatos Claude/OpenAI/Gemini/Antigravity/Responses (inclui heurística `max_tokens` para Claude). Além disso: construção de URL, construção de cabeçalho, normalização de configuração de pensamento. Suporta provedores dinâmicos `openai-compatible-*` e `anthropic-compatible-*`. | +| `model.ts` | Análise de string de modelo (`claude/model-name` → `{provider: "claude", model: "model-name"}`), resolução de alias com detecção de colisão, limpeza de entrada (rejeita caracteres de passagem/controle de caminho) e resolução de informações de modelo com suporte a getter de alias assíncrono. | +| `accountFallback.ts` | Tratamento de limite de taxa: espera exponencial (1s → 2s → 4s → máx. 2min), gerenciamento de resfriamento da conta, classificação de erros (quais erros acionam fallback versus não). | +| `tokenRefresh.ts` | Atualização de token OAuth para **todos os provedores**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Inclui cache de desduplicação de promessa em andamento e nova tentativa com espera exponencial. | +| `combo.ts` | **Modelos combinados**: cadeias de modelos alternativos. Se o modelo A falhar com um erro elegível para fallback, tente o modelo B, depois o C, etc. Retorna os códigos de status upstream reais. | +| `usage.ts` | Busca dados de cota/uso de APIs do provedor (cotas do GitHub Copilot, cotas do modelo antigravidade, limites de taxa do Codex, detalhamentos de uso do Kiro, configurações do Claude). | +| `accountSelector.ts` | Seleção inteligente de conta com algoritmo de pontuação: considera prioridade, status de integridade, posição round-robin e estado de espera para escolher a conta ideal para cada solicitação. | +| `contextManager.ts` | Gerenciamento do ciclo de vida do contexto de solicitação: cria e rastreia objetos de contexto por solicitação com metadados (ID da solicitação, carimbos de data/hora, informações do provedor) para depuração e registro em log. | +| `ipFilter.ts` | Controle de acesso baseado em IP: suporta modos de lista de permissões e lista de bloqueios. Valida o IP do cliente em relação às regras configuradas antes de processar solicitações de API. | +| `sessionManager.ts` | Rastreamento de sessão com impressão digital do cliente: rastreia sessões ativas usando identificadores de cliente com hash, monitora contagens de solicitações e fornece métricas de sessão. | +| `signatureCache.ts` | Solicitar cache de desduplicação baseado em assinatura: evita solicitações duplicadas armazenando em cache assinaturas de solicitações recentes e retornando respostas armazenadas em cache para solicitações idênticas dentro de um intervalo de tempo. | +| `systemPrompt.ts` | Injeção global de prompt do sistema: acrescenta ou acrescenta um prompt do sistema configurável a todas as solicitações, com tratamento de compatibilidade por provedor. | +| `thinkingBudget.ts` | Gerenciamento de orçamento de token de raciocínio: oferece suporte aos modos passthrough, automático (configuração de pensamento), personalizado (orçamento fixo) e adaptativo (escala de complexidade) para controlar tokens de pensamento/raciocínio. | +| `wildcardRouter.ts` | Roteamento de padrão de modelo curinga: resolve padrões curinga (por exemplo, `*/claude-*`) para pares concretos de provedor/modelo com base na disponibilidade e prioridade. | + +#### Desduplicação de atualização de 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 +``` + +#### Máquina de estado substituto da conta + +```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 + } +``` + +#### Cadeia de modelos combinados + +```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 Tradutor (`open-sse/translator/`) + +O **mecanismo de tradução de formatos** usando um sistema de plugins com autorregistro. + +#### Arquitetura + +```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 +``` + +| Diretório | Arquivos | Descrição | +| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `request/` | 8 tradutores | Converta corpos de solicitação entre formatos. Cada arquivo é registrado automaticamente via `register(from, to, fn)` na importação. | +| `response/` | 7 tradutores | Converta pedaços de resposta de streaming entre formatos. Lida com tipos de eventos SSE, blocos de pensamento e chamadas de ferramentas. | +| `helpers/` | 6 ajudantes | Utilitários compartilhados: `claudeHelper` (extração de prompt do sistema, configuração de pensamento), `geminiHelper` (mapeamento de partes/conteúdo), `openaiHelper` (filtragem de formato), `toolCallHelper` (geração de ID, injeção de resposta ausente), `maxTokensHelper`, `responsesApiHelper`. | +| `index.ts` | — | Mecanismo de tradução: `translateRequest()`, `translateResponse()`, gerenciamento de estado, registro. | +| `formats.ts` | — | Constantes de formato: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, `CURSOR`, `OPENAI_RESPONSES`. | + +#### Design principal: plug-ins de autorregistro + +```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ários (`open-sse/utils/`) + +| Arquivo | Finalidade | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | Criação de resposta a erros (formato compatível com OpenAI), análise de erros upstream, extração de tempo de repetição antigravidade de mensagens de erro, streaming de erros SSE. | +| `stream.ts` | **SSE Transform Stream** — o principal pipeline de streaming. Dois modos: `TRANSLATE` (tradução de formato completo) e `PASSTHROUGH` (normalizar + extrair uso). Lida com buffer de blocos, estimativa de uso e rastreamento de comprimento de conteúdo. As instâncias do codificador/decodificador por fluxo evitam o estado compartilhado. | +| `streamHelpers.ts` | Utilitários SSE de baixo nível: `parseSSELine` (tolerante a espaços em branco), `hasValuableContent` (filtra pedaços vazios para OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (serialização SSE com reconhecimento de formato com limpeza `perf_metrics`). | +| `usageTracking.ts` | Extração de uso de token de qualquer formato (Claude/OpenAI/Gemini/Responses), estimativa com proporções separadas de caracteres por ferramenta/mensagem por token, adição de buffer (margem de segurança de 2.000 tokens), filtragem de campo específica de formato, registro de console com cores ANSI. | +| `requestLogger.ts` | Registro de solicitação baseado em arquivo (aceitação via `ENABLE_REQUEST_LOGS=true`). Cria pastas de sessão com arquivos numerados: `1_req_client.json` → `7_res_client.txt`. Toda E/S é assíncrona (dispare e esqueça). Mascara cabeçalhos sensíveis. | +| `bypassHandler.ts` | Intercepta padrões específicos do Claude CLI (extração de título, aquecimento, contagem) e retorna respostas falsas sem ligar para nenhum provedor. Suporta streaming e não streaming. Intencionalmente limitado ao escopo Claude CLI. | +| `networkProxy.ts` | Resolve URL de proxy de saída para um determinado provedor com precedência: configuração específica do provedor → configuração global → variáveis ​​de ambiente (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Suporta exclusões `NO_PROXY`. Configuração de caches por 30s. | + +#### Pipeline de 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 +``` + +#### Estrutura da sessão do registrador de solicitações + +``` +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 Camada de Aplicação (`src/`) + +| Diretório | Finalidade | +| ------------- | -------------------------------------------------------------------------------------- | +| `src/app/` | UI da Web, rotas de API, middleware Express, manipuladores de retorno de chamada OAuth | +| `src/lib/` | Acesso à base de dados (`localDb.ts`, `usageDb.ts`), autenticação, partilhada | +| `src/mitm/` | Utilitários proxy man-in-the-middle para interceptar o tráfego do provedor | +| `src/models/` | Definições de modelo de banco de dados | +| `src/shared/` | Wrappers em torno de funções open-sse (provedor, fluxo, erro, etc.) | +| `src/sse/` | Manipuladores de endpoint SSE que conectam a biblioteca open-sse às rotas Express | +| `src/store/` | Gerenciamento de estado de aplicação | + +#### Rotas de API notáveis + +| Rota | Métodos | Finalidade | +| --------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | +| `/api/provider-models` | OBTER/POSTAR/EXCLUIR | CRUD para modelos customizados por provedor | +| `/api/models/catalog` | OBTER | Catálogo agregado de todos os modelos (chat, incorporação, imagem, customizado) agrupados por provedor | +| `/api/settings/proxy` | OBTER/COLOCAR/EXCLUIR | Configuração hierárquica de proxy de saída (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POSTAR | Valida a conectividade do proxy e retorna IP público/latência | +| `/v1/providers/[provider]/chat/completions` | POSTAR | Conclusões de chat dedicadas por provedor com validação de modelo | +| `/v1/providers/[provider]/embeddings` | POSTAR | Incorporações dedicadas por provedor com validação de modelo | +| `/v1/providers/[provider]/images/generations` | POSTAR | Geração de imagens dedicadas por provedor com validação de modelo | +| `/api/settings/ip-filter` | OBTER/COLOCAR | Gerenciamento de lista de permissão/lista de bloqueio de IP | +| `/api/settings/thinking-budget` | OBTER/COLOCAR | Configuração do orçamento do token de raciocínio (passagem/automática/personalizada/adaptável) | +| `/api/settings/system-prompt` | OBTER/COLOCAR | Injeção imediata do sistema global para todas as solicitações | +| `/api/sessions` | OBTER | Acompanhamento e métricas de sessões ativas | +| `/api/rate-limits` | OBTER | Status do limite de taxa por conta | + +--- + +## 5. Principais padrões de design + +### 5.1 Tradução Hub-and-Spoke + +Todos os formatos são traduzidos através do **formato OpenAI como hub**. Adicionar um novo provedor requer apenas escrever **um par** de tradutores (de/para OpenAI), não N pares. + +### 5.2 Padrão de Estratégia do Executor + +Cada provedor possui uma classe de executor dedicada herdada de `BaseExecutor`. A fábrica em `executors/index.ts` seleciona o correto em tempo de execução. + +### 5.3 Sistema de plug-ins de autorregistro + +Os módulos tradutores se registram na importação via `register()`. Adicionar um novo tradutor é apenas criar um arquivo e importá-lo. + +### 5.4 Fallback de conta com backoff exponencial + +Quando um provedor retorna 429/401/500, o sistema pode mudar para a próxima conta, aplicando cooldowns exponenciais (1s → 2s → 4s → máx. 2min). + +### 5.5 Cadeias de modelos combinados + +Um "combo" agrupa várias strings `provider/model`. Se o primeiro falhar, volte para o próximo automaticamente. + +### 5.6 Tradução de streaming com estado + +A tradução de resposta mantém o estado em blocos SSE (rastreamento de blocos de pensamento, acúmulo de chamadas de ferramentas, indexação de blocos de conteúdo) por meio do mecanismo `initState()`. + +### 5.7 Buffer de segurança de uso + +Um buffer de 2.000 tokens é adicionado ao uso relatado para evitar que os clientes atinjam os limites da janela de contexto devido à sobrecarga dos prompts do sistema e da tradução de formato. + +--- + +## 6. Formatos Suportados + +| Formato | Direção | Identificador | +| ------------------------------ | ---------------- | ------------------ | +| Conclusões do bate-papo OpenAI | origem + destino | `openai` | +| API de respostas OpenAI | origem + destino | `openai-responses` | +| Claude Antrópico | origem + destino | `claude` | +| Google Gêmeos | origem + destino | `gemini` | +| CLI do Google Gemini | apenas alvo | `gemini-cli` | +| Antigravidade | origem + destino | `antigravity` | +| AWSKiro | apenas alvo | `kiro` | +| Cursor | apenas alvo | `cursor` | + +--- + +## 7. Provedores Suportados + +| Provedor | Método de autenticação | Executor | Notas principais | +| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------- | +| Claude Antrópico | Chave API ou OAuth | Padrão | Usa cabeçalho `x-api-key` | +| Google Gêmeos | Chave API ou OAuth | Padrão | Usa cabeçalho `x-goog-api-key` | +| CLI do Google Gemini | OAuth | GêmeosCLI | Usa ponto de extremidade `streamGenerateContent` | +| Antigravidade | OAuth | Antigravidade | Fallback de vários URLs, análise de repetição personalizada | +| OpenAI | Chave de API | Padrão | Autenticação do portador padrão | +| Códice | OAuth | Códice | Injeta instruções do sistema, gerencia o pensamento | +| Copiloto GitHub | Token OAuth + Copiloto | GitHub | Token duplo, imitação de cabeçalho VSCode | +| Kiro (AWS) | AWS SSO OIDC ou social | Kiro | Análise binária de EventStream | +| Cursor IDE | Autenticação de soma de verificação | Cursor | Codificação protobuf, somas de verificação SHA-256 | +| Qwen | OAuth | Padrão | Autenticação padrão | +| iFlow | OAuth (Básico + Portador) | Padrão | Cabeçalho de autenticação dupla | +| OpenRouter | Chave de API | Padrão | Autenticação do portador padrão | +| GLM, Kimi, MiniMax | Chave de API | Padrão | Compatível com Claude, use `x-api-key` | +| `openai-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com OpenAI | +| `anthropic-compatible-*` | Chave de API | Padrão | Dinâmico: qualquer endpoint compatível com Claude | + +--- + +## 8. Resumo do fluxo de dados + +### Solicitação de 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()"] +``` + +### Solicitação de não 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"] +``` + +### Desviar fluxo (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/pt/FEATURES.md b/docs/i18n/pt/FEATURES.md new file mode 100644 index 0000000000..599e62469b --- /dev/null +++ b/docs/i18n/pt/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — Galeria de recursos do painel + +🌐 **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) + +Guia visual para cada seção do painel do OmniRoute. + +--- + +## 🔌 Provedores + +Gerencie conexões de provedores de IA: provedores OAuth (Claude Code, Codex, Gemini CLI), provedores de chaves de API (Groq, DeepSeek, OpenRouter) e provedores gratuitos (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨Combos + +Crie combos de roteamento de modelos com 6 estratégias: preenchimento primeiro, round-robin, potência de duas opções, aleatório, menos usado e com custo otimizado. Cada combinação encadeia vários modelos com fallback automático. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Análise + +Análise de uso abrangente com consumo de tokens, estimativas de custos, mapas de calor de atividades, gráficos de distribuição semanais e detalhamentos por provedor. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Saúde do Sistema + +Monitoramento em tempo real: tempo de atividade, memória, versão, percentis de latência (p50/p95/p99), estatísticas de cache e estados de disjuntores do provedor. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Parque do Tradutor + +Quatro modos para depurar traduções de API: **Playground** (conversor de formato), **Chat Tester** (solicitações ao vivo), **Test Bench** (testes em lote) e **Live Monitor** (transmissão em tempo real). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Configurações + +Configurações gerais, armazenamento do sistema, gerenciamento de backup (banco de dados de exportação/importação), aparência (modo escuro/claro), segurança (inclui proteção de endpoint de API e bloqueio de provedor personalizado), roteamento, resiliência e configuração avançada. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Ferramentas CLI + +Configuração com um clique para ferramentas de codificação de IA: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code e Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Solicitar registros + +Registro de solicitações em tempo real com filtragem por provedor, modelo, conta e chave de API. Mostra códigos de status, uso de token, latência e detalhes de resposta. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 Ponto final da API + +Seu endpoint de API unificado com detalhamento de recursos: conclusões de bate-papo, incorporações, geração de imagens, reclassificação, transcrição de áudio e chaves de API registradas. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/pt/TROUBLESHOOTING.md b/docs/i18n/pt/TROUBLESHOOTING.md new file mode 100644 index 0000000000..f678130061 --- /dev/null +++ b/docs/i18n/pt/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Solução de problemas + +🌐 **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) + +Problemas e soluções comuns para OmniRoute. + +--- + +## Correções rápidas + +| Problema | Solução | +| ----------------------------------------- | -------------------------------------------------------------------------------------- | +| O primeiro login não funciona | Verifique `INITIAL_PASSWORD` em `.env` (padrão: `123456`) | +| Painel abre na porta errada | Definir `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Nenhum registro de solicitação em `logs/` | Definir `ENABLE_REQUEST_LOGS=true` | +| EACCES: permissão negada | Defina `DATA_DIR=/path/to/writable/dir` para substituir `~/.omniroute` | +| Estratégia de roteamento não salva | Atualização para v1.4.11+ (correção do esquema Zod para persistência de configurações) | + +--- + +## Problemas do provedor + +### "O modelo de linguagem não forneceu mensagens" + +**Causa:** Cota do provedor esgotada. + +**Correção:** + +1. Verifique o rastreador de cota do painel +2. Use um combo com níveis alternativos +3. Mude para um nível mais barato/gratuito + +### Limitação de taxa + +**Causa:** Cota de assinatura esgotada. + +**Correção:** + +- Adicionar substituto: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Use GLM/MiniMax como backup barato + +### Token OAuth expirado + +OmniRoute atualiza automaticamente os tokens. Se os problemas persistirem: + +1. Painel → Provedor → Reconectar +2. Exclua e adicione novamente a conexão do provedor + +--- + +## Problemas de nuvem + +### Erros de sincronização na nuvem + +1. Verifique `BASE_URL` aponta para sua instância em execução (por exemplo, `http://localhost:20128`) +2. Verifique os pontos `CLOUD_URL` para seu endpoint de nuvem (por exemplo, `https://omniroute.dev`) +3. Mantenha os valores `NEXT_PUBLIC_*` alinhados com os valores do lado do servidor + +### Nuvem `stream=false` Retorna 500 + +**Sintoma:** `Unexpected token 'd'...` no endpoint da nuvem para chamadas sem streaming. + +**Causa:** O upstream retorna a carga SSE enquanto o cliente espera JSON. + +**Solução alternativa:** use `stream=true` para chamadas diretas na nuvem. O tempo de execução local inclui substituto SSE→JSON. + +### Cloud diz conectado, mas "chave de API inválida" + +1. Crie uma nova chave no painel local (`/api/keys`) +2. Execute a sincronização na nuvem: Habilite Nuvem → Sincronizar agora +3. Chaves antigas/não sincronizadas ainda podem retornar `401` na nuvem + +--- + +## Problemas do Docker + +### A ferramenta CLI mostra não instalada + +1. Verifique os campos de tempo de execução: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Para modo portátil: use o destino de imagem `runner-cli` (CLIs agrupados) +3. Para o modo de montagem do host: defina `CLI_EXTRA_PATHS` e monte o diretório bin do host como somente leitura +4. Se `installed=true` e `runnable=false`: o binário foi encontrado, mas falhou na verificação de integridade + +### Validação Rápida de Tempo de Execução + +```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}' +``` + +--- + +## Problemas de custo + +### Custos elevados + +1. Verifique as estatísticas de uso em Painel → Uso +2. Mude o modelo primário para GLM/MiniMax +3. Use o nível gratuito (Gemini CLI, iFlow) para tarefas não críticas +4. Defina orçamentos de custos por chave de API: Painel → Chaves de API → Orçamento + +--- + +## Depuração + +### Habilitar registros de solicitação + +Defina `ENABLE_REQUEST_LOGS=true` em seu arquivo `.env`. Os logs aparecem no diretório `logs/`. + +### Verifique a integridade do provedor + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Armazenamento em tempo de execução + +- Estado principal: `${DATA_DIR}/db.json` (provedores, combos, aliases, chaves, configurações) +- Uso: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Registros de solicitação: `/logs/...` (quando `ENABLE_REQUEST_LOGS=true`) + +--- + +## Problemas com disjuntores + +### Provedor preso no estado OPEN + +Quando o disjuntor de um provedor está ABERTO, as solicitações são bloqueadas até que o tempo de espera expire. + +**Correção:** + +1. Vá para **Painel → Configurações → Resiliência** +2. Verifique a placa do disjuntor do provedor afetado +3. Clique em **Redefinir tudo** para limpar todos os disjuntores ou aguarde o tempo de espera expirar +4. Verifique se o provedor está realmente disponível antes de redefinir + +### O provedor continua desarmando o disjuntor + +Se um provedor entrar repetidamente no estado OPEN: + +1. Verifique **Dashboard → Health → Provider Health** para ver o padrão de falha +2. Vá para **Configurações → Resiliência → Perfis do Provedor** e aumente o limite de falha +3. Verifique se o provedor alterou os limites da API ou requer nova autenticação +4. Revise a telemetria de latência – alta latência pode causar falhas baseadas em tempo limite + +--- + +## Problemas de transcrição de áudio + +### Erro "Modelo não suportado" + +- Certifique-se de usar o prefixo correto: `deepgram/nova-3` ou `assemblyai/best` +- Verifique se o provedor está conectado em **Painel → Provedores** + +### A transcrição retorna vazia ou falha + +- Verifique os formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verifique se o tamanho do arquivo está dentro dos limites do provedor (normalmente <25 MB) +- Verifique a validade da chave API do provedor no cartão do provedor + +--- + +## Depuração do tradutor + +Use **Dashboard → Tradutor** para depurar problemas de tradução de formato: + +| Modo | Quando usar | +| ------------------------- | --------------------------------------------------------------------------------------------------------------- | +| **Parque Infantil** | Compare os formatos de entrada/saída lado a lado — cole uma solicitação com falha para ver como ela é traduzida | +| **Testador de bate-papo** | Envie mensagens ao vivo e inspecione a carga completa de solicitação/resposta, incluindo cabeçalhos | +| **Banco de testes** | Execute testes em lote em combinações de formatos para descobrir quais traduções estão quebradas | +| **Monitoramento ao vivo** | Observe o fluxo de solicitações em tempo real para detectar problemas intermitentes de tradução | + +### Problemas comuns de formato + +- **Tags de pensamento não aparecem** — Verifique se o provedor alvo apoia o pensamento e a configuração do orçamento de pensamento +- **Queda de chamadas de ferramentas** — Algumas traduções de formato podem remover campos não suportados; verificar no modo Playground +- **Prompt do sistema ausente** — Claude e Gemini lidam com os prompts do sistema de maneira diferente; verifique o resultado da tradução +- **SDK retorna string bruta em vez de objeto** — Corrigido na v1.1.0: o sanitizador de resposta agora remove campos não padrão (`x_groq`, `usage_breakdown`, etc.) que causam falhas de validação do OpenAI SDK Pydantic +- **GLM/ERNIE rejeita função `system`** — Corrigido na v1.1.0: o normalizador de função mescla automaticamente mensagens do sistema em mensagens do usuário para modelos incompatíveis +- Função **`developer` não reconhecida** — Corrigido na v1.1.0: convertido automaticamente para `system` para provedores não-OpenAI +- **`json_schema` não funciona com Gemini** — Corrigido na v1.1.0: `response_format` agora é convertido para `responseMimeType` + `responseSchema` do Gemini + +--- + +## Configurações de resiliência + +### Limite de taxa automático não acionado + +- O limite automático de taxa se aplica apenas a provedores de chaves de API (não a OAuth/assinatura) +- Verifique se **Configurações → Resiliência → Perfis do Provedor** tem limite de taxa automática ativado +- Verifique se o provedor retorna códigos de status `429` ou cabeçalhos `Retry-After` + +### Ajustando a espera exponencial + +Os perfis do provedor oferecem suporte a estas configurações: + +- **Atraso base** — Tempo de espera inicial após a primeira falha (padrão: 1s) +- **Atraso máximo** — Limite máximo de tempo de espera (padrão: 30s) +- **Multiplicador** — Quanto aumentar o atraso por falha consecutiva (padrão: 2x) + +### Rebanho anti-trovão + +Quando muitas solicitações simultâneas atingem um provedor com taxa limitada, o OmniRoute usa mutex + limitação automática de taxa para serializar solicitações e evitar falhas em cascata. Isso é automático para provedores de chaves de API. + +--- + +## Ainda preso? + +- **Problemas do GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Arquitetura**: Consulte [**OMNI_TOKEN_55**](ARCHITECTURE.md) para detalhes internos +- **Referência da API**: Consulte [**OMNI_TOKEN_56**](API_REFERENCE.md) para todos os endpoints +- **Painel de saúde**: verifique **Painel → Saúde** para ver o status do sistema em tempo real +- **Tradutor**: Use **Dashboard → Tradutor** para depurar problemas de formato diff --git a/docs/i18n/pt/USER_GUIDE.md b/docs/i18n/pt/USER_GUIDE.md new file mode 100644 index 0000000000..d1a6876022 --- /dev/null +++ b/docs/i18n/pt/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Guia do usuário + +🌐 **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) + +Guia completo para configurar provedores, criar combos, integrar ferramentas CLI e implantar OmniRoute. + +--- + +## Índice + +- [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) + +--- + +## 💰 Visão geral dos preços + +| Nível | Provedor | Custo | Redefinição de cota | Melhor para | +| ------------------- | ------------------------ | ---------------- | ------------------------ | ----------------------------- | +| **💳 ASSINATURA** | Código Claude (Pro) | $ 20/mês | 5h + semanalmente | Já inscrito | +| | Códice (Plus/Pro) | US$ 20-200/mês | 5h + semanalmente | Usuários OpenAI | +| | Gêmeos CLI | **GRÁTIS** | 180 mil/mês + 1 mil/dia | Todos! | +| | Copiloto GitHub | US$ 10-19/mês | Mensalmente | Usuários do GitHub | +| **🔑 CHAVE DE API** | DeepSeek | Pague por uso | Nenhum | Raciocínio barato | +| | Groq | Pague por uso | Nenhum | Inferência ultrarrápida | +| | xAI (Groque) | Pague por uso | Nenhum | Raciocínio Grok 4 | +| | Mistral | Pague por uso | Nenhum | Modelos hospedados na UE | +| | Perplexidade | Pague por uso | Nenhum | Pesquisa aumentada | +| | Juntos IA | Pague por uso | Nenhum | Modelos de código aberto | +| | IA de fogos de artifício | Pague por uso | Nenhum | Imagens FLUX rápidas | +| | Cérebros | Pague por uso | Nenhum | Velocidade em escala de wafer | +| | Coerente | Pague por uso | Nenhum | Comando R+ RAG | +| | NVIDIA NIM | Pague por uso | Nenhum | Modelos empresariais | +| **💰 BARATO** | GLM-4.7 | US$ 0,6/1 milhão | Diariamente 10h | Backup de orçamento | +| | MiniMax M2.1 | US$ 0,2/1 milhão | Rolamento de 5 horas | Opção mais barata | +| | Kimi K2 | $ 9 / mês fixo | 10 milhões de tokens/mês | Custo previsível | +| **🆓 GRÁTIS** | iFlow | $0 | Ilimitado | 8 modelos grátis | +| | Qwen | $0 | Ilimitado | 3 modelos grátis | +| | Kiro | $0 | Ilimitado | Cláudio grátis | + +**💡 Dica profissional:** Comece com Gemini CLI (180 mil grátis/mês) + combo iFlow (gratuito ilimitado) = custo de $ 0! + +--- + +## 🎯 Casos de uso + +### Caso 1: "Tenho assinatura do Claude Pro" + +**Problema:** A cota expira sem ser utilizada, limites de taxa durante codificação pesada + +``` +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: "Quero custo zero" + +**Problema:** Não posso pagar assinaturas, preciso de codificação de IA confiável + +``` +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: "Preciso de codificação 24 horas por dia, 7 dias por semana, sem interrupções" + +**Problema:** Prazos, não podemos arcar com o tempo de inatividade + +``` +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: "Quero IA GRATUITA no OpenClaw" + +**Problema:** Precisa de assistente de IA em aplicativos de mensagens, totalmente 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... +``` + +--- + +## 📖 Configuração do provedor + +### 🔐 Provedores de assinatura + +#### Código 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 +``` + +**Dica profissional:** Use o Opus para tarefas complexas e o Sonnet para velocidade. OmniRoute rastreia cota por modelo! + +#### 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 (GRÁTIS 180 mil/mês!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Melhor valor:** Grande nível gratuito! Use isso antes dos níveis pagos. + +#### GitHub Copiloto + +```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 +``` + +### 💰 Fornecedores baratos + +#### GLM-4.7 (redefinição diária, US$ 0,6/1 milhão) + +1. Inscreva-se: [Zhipu AI](https://open.bigmodel.cn/) +2. Obtenha a chave API do plano de codificação +3. Painel → Adicionar chave de API: Provedor: `glm`, chave de API: `your-key` + +**Usar:** `glm/glm-4.7` — **Dica profissional:** O plano de codificação oferece 3× cota a 1/7 de custo! Redefinir diariamente às 10h. + +#### MiniMax M2.1 (redefinição de 5h, US$ 0,20/1 milhão) + +1. Inscreva-se: [MiniMax](https://www.minimax.io/) +2. Obter chave de API → Painel → Adicionar chave de API + +**Use:** `minimax/MiniMax-M2.1` — **Dica profissional:** Opção mais barata para contexto longo (1 milhão de tokens)! + +#### Kimi K2 (US$ 9/mês fixo) + +1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/) +2. Obter chave de API → Painel → Adicionar chave de API + +**Uso:** `kimi/kimi-latest` — **Dica profissional:** Fixo US$ 9/mês para 10 milhões de tokens = US$ 0,90/1 milhão de custo efetivo! + +### 🆓 Provedores GRATUITOS + +#### iFlow (8 modelos GRATUITOS) + +```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 modelos GRATUITOS) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude GRÁTIS) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨Combos + +### Exemplo 1: Maximize a assinatura → Backup barato + +``` +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 +``` + +### Exemplo 2: somente gratuito (custo 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! +``` + +--- + +## 🔧 Integração CLI + +### Cursor IDE + +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from omniroute dashboard] + Model: cc/claude-opus-4-6 +``` + +### Código Cláudio + +Editar `~/.claude/config.json`: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### CLI do Codex + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +###OpenClaw + +Editar `~/.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" }] + } + } + } +} +``` + +**Ou use o Dashboard:** Ferramentas CLI → OpenClaw → Configuração automática + +### Cline / Continuar / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Implantação + +### Implantação 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 +``` + +### 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 +``` + +Para o modo integrado ao host com binários CLI, consulte a seção Docker na documentação principal. + +### Variáveis de Ambiente + +| Variável | Padrão | Descrição | +| --------------------- | ------------------------------------ | --------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | Segredo de assinatura do JWT (**mudança na produção**) | +| `INITIAL_PASSWORD` | `123456` | Senha do primeiro login | +| `DATA_DIR` | `~/.omniroute` | Diretório de dados (banco de dados, uso, logs) | +| `PORT` | padrão da estrutura | Porta de serviço (`20128` em exemplos) | +| `HOSTNAME` | padrão da estrutura | Host de vinculação (o padrão do Docker é `0.0.0.0`) | +| `NODE_ENV` | padrão de tempo de execução | Definir `production` para implantação | +| `BASE_URL` | `http://localhost:20128` | URL base interna do lado do servidor | +| `CLOUD_URL` | `https://omniroute.dev` | URL base do endpoint de sincronização em nuvem | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Segredo HMAC para chaves de API geradas | +| `REQUIRE_API_KEY` | `false` | Aplicar chave de API do portador em `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Habilita registros de solicitação/resposta | +| `AUTH_COOKIE_SECURE` | `false` | Forçar cookie de autenticação `Secure` (atrás do proxy reverso HTTPS) | + +Para obter a referência completa da variável de ambiente, consulte [README](../README.md). + +--- + +## 📊 Modelos Disponíveis + +
+Ver todos os modelos disponíveis + +**Código Claude (`cc/`)** — Pro/Máx: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Códice (`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` + +**Copiloto do GitHub (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**GLM (`glm/`)** — US$ 0,6/1 milhão: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — US$ 0,2/1 milhão: `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` + +**Mistral (`mistral/`)**: `mistral/mistral-large-2501`, `mistral/codestral-2501` + +**Perplexidade (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Juntos AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**IA do Fireworks (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Cérebros (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Coerente (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Recursos avançados + +### Modelos personalizados + +Adicione qualquer ID de modelo a qualquer provedor sem esperar por uma atualização do aplicativo: + +```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" +``` + +Ou use o Dashboard: **Provedores → [Provedor] → Modelos personalizados**. + +### Rotas de provedores dedicados + +Encaminhe solicitações diretamente para um provedor específico com validação de modelo: + +```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 +``` + +O prefixo do provedor é adicionado automaticamente se estiver ausente. Modelos incompatíveis retornam `400`. + +### Configuração de proxy de rede + +```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"}}' +``` + +**Precedência:** Específico da chave → Específico do combo → Específico do provedor → Global → Ambiente. + +### API de catálogo de modelos + +```bash +curl http://localhost:20128/api/models/catalog +``` + +Retorna modelos agrupados por provedor com tipos (`chat`, `embedding`, `image`). + +### Sincronização na nuvem + +- Sincronize provedores, combos e configurações entre dispositivos +- Sincronização automática em segundo plano com tempo limite + falha rápida +- Prefira `BASE_URL`/`CLOUD_URL` do lado do servidor na produção + +### LLM Gateway Intelligence (Fase 9) + +- **Cache Semântico** — Armazena automaticamente em cache sem streaming, temperatura = 0 respostas (ignorar com `X-OmniRoute-No-Cache: true`) +- **Idempotência de solicitação** — Desduplica solicitações em 5s por meio do cabeçalho `Idempotency-Key` ou `X-Request-Id` +- **Acompanhamento de progresso** — Eventos SSE `event: progress` de aceitação por meio do cabeçalho `X-OmniRoute-Progress: true` + +--- + +### Parque do Tradutor + +Acesso via **Painel → Tradutor**. Depure e visualize como o OmniRoute traduz solicitações de API entre provedores. + +| Modo | Finalidade | +| ------------------------- | ----------------------------------------------------------------------------------------------------------- | +| **Parque Infantil** | Selecione os formatos de origem/destino, cole uma solicitação e veja o resultado traduzido instantaneamente | +| **Testador de bate-papo** | Envie mensagens de chat ao vivo através do proxy e inspecione todo o ciclo de solicitação/resposta | +| **Banco de testes** | Execute testes em lote em múltiplas combinações de formatos para verificar a exatidão da tradução | +| **Monitoramento ao vivo** | Assista às traduções em tempo real enquanto as solicitações fluem pelo proxy | + +**Casos de uso:** + +- Depure por que uma combinação específica de cliente/provedor falha +- Verifique se as tags de pensamento, as chamadas de ferramentas e os prompts do sistema são traduzidos corretamente +- Compare as diferenças de formato entre os formatos OpenAI, Claude, Gemini e Responses API + +--- + +### Estratégias de roteamento + +Configure via **Painel → Configurações → Roteamento**. + +| Estratégia | Descrição | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| **Preencha primeiro** | Usa contas em ordem de prioridade – a conta principal lida com todas as solicitações até ficar indisponível | +| **Round Robin** | Percorre todas as contas com um limite fixo configurável (padrão: 3 chamadas por conta) | +| **P2C (Poder de Duas Escolhas)** | Escolhe 2 contas aleatórias e direciona para a mais saudável — equilibra a carga com a consciência da saúde | +| **Aleatório** | Seleciona aleatoriamente uma conta para cada solicitação usando o embaralhamento Fisher-Yates | +| **Menos usado** | Roteia para a conta com o carimbo de data/hora `lastUsedAt` mais antigo, distribuindo o tráfego uniformemente | +| **Custo Otimizado** | Rotas para a conta com menor valor de prioridade, otimizando para provedores de menor custo | + +#### Aliases de modelo curinga + +Crie padrões curinga para remapear nomes de modelos: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +Os curingas suportam `*` (qualquer caractere) e `?` (caractere único). + +#### Cadeias substitutas + +Defina cadeias de fallback globais que se aplicam a todas as solicitações: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Resiliência e Disjuntores + +Configure via **Painel → Configurações → Resiliência**. + +OmniRoute implementa resiliência em nível de provedor com quatro componentes: + +1. **Perfis de Provedores** — Configuração por provedor para: + - Limite de falha (quantas falhas antes da abertura) + - Duração do resfriamento + - Sensibilidade de detecção de limite de taxa + - Parâmetros de espera exponencial + +2. **Limites de taxa editáveis** — Padrões de nível de sistema configuráveis no painel: + - **Solicitações por minuto (RPM)** — Máximo de solicitações por minuto por conta + - **Tempo mínimo entre solicitações** — Intervalo mínimo em milissegundos entre solicitações + - **Máximo de solicitações simultâneas** — Máximo de solicitações simultâneas por conta + - Clique em **Editar** para modificar e depois em **Salvar** ou **Cancelar**. Os valores persistem por meio da API de resiliência. + +3. **Disjuntor** — Rastreia falhas por provedor e abre automaticamente o circuito quando um limite é atingido: + - **FECHADO** (Saudável) — As solicitações fluem normalmente + - **OPEN** — O provedor é bloqueado temporariamente após falhas repetidas + - **HALF_OPEN** — Testando se o provedor se recuperou + +4. **Políticas e identificadores bloqueados** — Mostra o status do disjuntor e identificadores bloqueados com capacidade de desbloqueio forçado. + +5. **Detecção automática de limite de taxa** — Monitora os cabeçalhos `429` e `Retry-After` para evitar proativamente atingir os limites de taxa do provedor. + +**Dica profissional:** Use o botão **Redefinir tudo** para limpar todos os disjuntores e resfriamentos quando um provedor se recupera de uma interrupção. + +--- + +### Exportação/Importação de banco de dados + +Gerencie backups de banco de dados em **Painel → Configurações → Sistema e armazenamento**. + +| Ação | Descrição | +| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Exportar banco de dados** | Baixa o banco de dados SQLite atual como um arquivo `.sqlite` | +| **Exportar tudo (.tar.gz)** | Baixa um arquivo de backup completo, incluindo: banco de dados, configurações, combos, conexões de provedor (sem credenciais), metadados de chave API | +| **Importar banco de dados** | Faça upload de um arquivo `.sqlite` para substituir o banco de dados atual. Um backup de pré-importação é criado automaticamente | + +```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" +``` + +**Validação de importação:** O arquivo importado é validado quanto à integridade (verificação de pragma SQLite), tabelas necessárias (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) e tamanho (máximo de 100 MB). + +**Casos de uso:** + +- Migrar OmniRoute entre máquinas +- Crie backups externos para recuperação de desastres +- Compartilhe configurações entre membros da equipe (exportar tudo → compartilhar arquivo) + +--- + +### Painel de configurações + +A página de configurações está organizada em 5 guias para facilitar a navegação: + +| Guia | Conteúdo | +| --------------- | ----------------------------------------------------------------------------------------------------------------- | +| **Segurança** | Configurações de login/senha, controle de acesso IP, autenticação de API para `/models` e bloqueio de provedor | +| **Roteamento** | Estratégia de roteamento global (6 opções), aliases de modelo curinga, cadeias de fallback, padrões de combinação | +| **Resiliência** | Perfis de provedores, limites de taxas editáveis, status de disjuntores, políticas e identificadores bloqueados | +| **IA** | Pensando na configuração do orçamento, injeção de prompt do sistema global, estatísticas de cache de prompt | +| **Avançado** | Configuração de proxy global (HTTP/SOCKS5) | + +--- + +### Gestão de Custos e Orçamento + +Acesso via **Painel → Custos**. + +| Guia | Finalidade | +| ------------- | -------------------------------------------------------------------------------------------------------------- | +| **Orçamento** | Defina limites de gastos por chave de API com orçamentos diários/semanais/mensais e rastreamento em tempo real | +| **Preços** | Visualize e edite entradas de preços de modelo — custo por 1 mil tokens de entrada/saída por provedor | + +```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 +``` + +**Acompanhamento de custos:** cada solicitação registra o uso do token e calcula o custo usando a tabela de preços. Veja detalhes em **Painel → Uso** por provedor, modelo e chave de API. + +--- + +### Transcrição de áudio + +OmniRoute oferece suporte à transcrição de áudio por meio do endpoint compatível com 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" +``` + +Provedores disponíveis: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Formatos de áudio suportados: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + +--- + +### Estratégias de balanceamento de combinação + +Configure o balanceamento por combo em **Painel → Combos → Criar/Editar → Estratégia**. + +| Estratégia | Descrição | +| ------------------- | ----------------------------------------------------------------------------------------- | +| **Round-Robin** | Gira pelos modelos sequencialmente | +| **Prioridade** | Tenta sempre o primeiro modelo; recorre apenas ao erro | +| **Aleatório** | Escolhe um modelo aleatório do combo para cada solicitação | +| **Ponderada** | Rotas proporcionalmente com base nos pesos atribuídos por modelo | +| **Menos usado** | Rotas para o modelo com o menor número de solicitações recentes (usa métricas combinadas) | +| **Custo Otimizado** | Rotas para o modelo mais barato disponível (usa tabela de preços) | + +Os padrões de combinação global podem ser definidos em **Painel → Configurações → Roteamento → Padrões de combinação**. + +--- + +### Painel de saúde + +Acesso via **Painel → Saúde**. Visão geral da integridade do sistema em tempo real com 6 cartões: + +| Cartão | O que mostra | +| -------------------------- | ----------------------------------------------------------------------- | +| **Status do sistema** | Tempo de atividade, versão, uso de memória, diretório de dados | +| **Provedor de Saúde** | Estado do disjuntor por fornecedor (Fechado/Aberto/Meio-aberto) | +| **Limites de Tarifas** | Cooldowns de limite de taxa ativa por conta com tempo restante | +| **Bloqueios ativos** | Prestadores bloqueados temporariamente pela política de lockout | +| **Cache de Assinaturas** | Estatísticas do cache de desduplicação (chaves ativas, taxa de acertos) | +| **Telemetria de latência** | Agregação de latência p50/p95/p99 por provedor | + +**Dica profissional:** a página Saúde é atualizada automaticamente a cada 10 segundos. Use a placa do disjuntor para identificar quais provedores estão enfrentando problemas. diff --git a/docs/i18n/ro/API_REFERENCE.md b/docs/i18n/ro/API_REFERENCE.md new file mode 100644 index 0000000000..604e68dc2c --- /dev/null +++ b/docs/i18n/ro/API_REFERENCE.md @@ -0,0 +1,441 @@ +# Referință 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) + +Referință completă pentru toate punctele finale API OmniRoute. + +--- + +## Cuprins + +- [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) + +--- + +## Finalizări de 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 +} +``` + +### Anteturi personalizate + +| Antet | Direcție | Descriere | +| ------------------------ | -------- | ----------------------------------------------- | +| `X-OmniRoute-No-Cache` | Cerere | Setați la `true` pentru a ocoli memoria cache | +| `X-OmniRoute-Progress` | Cerere | Setați la `true` pentru evenimentele de progres | +| `Idempotency-Key` | Cerere | Tasta Dedup (fereastră 5s) | +| `X-Request-Id` | Cerere | Cheie alternativă de deducție | +| `X-OmniRoute-Cache` | Răspuns | `HIT` sau `MISS` (non-streaming) | +| `X-OmniRoute-Idempotent` | Răspuns | `true` dacă este deduplicat | +| `X-OmniRoute-Progress` | Răspuns | `enabled` dacă urmărirea progresului pe | + +--- + +## Înglobări + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Furnizori disponibili: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## Generare de imagini + +```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" +} +``` + +Furnizori disponibili: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## Listează modele + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## Puncte finale de compatibilitate + +| Metoda | Calea | Format | +| ------ | --------------------------- | ------------------------ | +| POST | `/v1/chat/completions` | OpenAI | +| POST | `/v1/messages` | antropic | +| POST | `/v1/responses` | Răspunsuri OpenAI | +| POST | `/v1/embeddings` | OpenAI | +| POST | `/v1/images/generations` | OpenAI | +| GET | `/v1/models` | OpenAI | +| POST | `/v1/messages/count_tokens` | antropic | +| GET | `/v1beta/models` | Gemeni | +| POST | `/v1beta/models/{...path}` | Gemeni genereazăConținut | +| POST | `/v1/api/chat` | Ollama | + +### Rute de furnizori dedicate + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +Prefixul furnizorului este adăugat automat dacă lipsește. Modelele nepotrivite revin `400`. + +--- + +## Cache semantic + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +Exemplu de răspuns: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Tabloul de bord și managementul + +### Autentificare + +| Punct final | Metoda | Descriere | +| ----------------------------- | ------- | ------------------------------- | +| `/api/auth/login` | POST | Autentificare | +| `/api/auth/logout` | POST | Deconectare | +| `/api/settings/require-login` | GET/PUT | Comutare autentificare necesară | + +### Managementul furnizorilor + +| Punct final | Metoda | Descriere | +| ---------------------------- | --------------- | ---------------------------------- | +| `/api/providers` | GET/POST | Listează / creează furnizori | +| `/api/providers/[id]` | GET/PUT/DELETE | Gestionați un furnizor | +| `/api/providers/[id]/test` | POST | Testează conexiunea furnizorului | +| `/api/providers/[id]/models` | GET | Listați modele de furnizori | +| `/api/providers/validate` | POST | Validați configurația furnizorului | +| `/api/provider-nodes*` | Diverse | Gestionarea nodurilor furnizorului | +| `/api/provider-models` | GET/POST/DELETE | Modele personalizate | + +### Fluxuri OAuth + +| Punct final | Metoda | Descriere | +| -------------------------------- | ------- | --------------------------- | +| `/api/oauth/[provider]/[action]` | Diverse | OAuth specific furnizorului | + +### Rutare și configurare + +| Punct final | Metoda | Descriere | +| --------------------- | -------- | ---------------------------------- | +| `/api/models/alias` | GET/POST | Aliasuri de model | +| `/api/models/catalog` | GET | Toate modelele după furnizor + tip | +| `/api/combos*` | Diverse | Combo management | +| `/api/keys*` | Diverse | Gestionarea cheilor API | +| `/api/pricing` | GET | Prețul modelului | + +### Utilizare și analiză + +| Punct final | Metoda | Descriere | +| --------------------------- | ------ | ---------------------------- | +| `/api/usage/history` | GET | Istoricul utilizării | +| `/api/usage/logs` | GET | Jurnalele de utilizare | +| `/api/usage/request-logs` | GET | Jurnalele la nivel de cerere | +| `/api/usage/[connectionId]` | GET | Utilizare per conexiune | + +### Setări + +| Punct final | Metoda | Descriere | +| ------------------------------- | ------- | ------------------------------ | +| `/api/settings` | GET/PUT | Setări generale | +| `/api/settings/proxy` | GET/PUT | Configurare proxy de rețea | +| `/api/settings/proxy/test` | POST | Testați conexiunea proxy | +| `/api/settings/ip-filter` | GET/PUT | Lista IP permisă/lista blocată | +| `/api/settings/thinking-budget` | GET/PUT | Bugetul simbol de raționament | +| `/api/settings/system-prompt` | GET/PUT | Sistem global prompt | + +### Monitorizare + +| Punct final | Metoda | Descriere | +| ------------------------ | ---------- | -------------------------- | +| `/api/sessions` | GET | Urmărire activă a sesiunii | +| `/api/rate-limits` | GET | Limitele ratei per cont | +| `/api/monitoring/health` | GET | Verificarea sănătății | +| `/api/cache` | GET/DELETE | Cache stats / clear | + +### Backup & Export/Import + +| Punct final | Metoda | Descriere | +| --------------------------- | ------ | -------------------------------------------------------- | +| `/api/db-backups` | GET | Listează copiile de rezervă disponibile | +| `/api/db-backups` | PUNE | Creați o copie de rezervă manuală | +| `/api/db-backups` | POST | Restaurare dintr-o anumită copie de rezervă | +| `/api/db-backups/export` | GET | Descărcați baza de date ca fișier .sqlite | +| `/api/db-backups/import` | POST | Încărcați fișierul .sqlite pentru a înlocui baza de date | +| `/api/db-backups/exportAll` | GET | Descărcați backup complet ca arhivă .tar.gz | + +### Cloud Sync + +| Punct final | Metoda | Descriere | +| ---------------------- | ------- | ----------------------------------- | +| `/api/sync/cloud` | Diverse | Operațiuni de sincronizare în cloud | +| `/api/sync/initialize` | POST | Inițializați sincronizarea | +| `/api/cloud/*` | Diverse | Management cloud | + +### Instrumente CLI + +| Punct final | Metoda | Descriere | +| ---------------------------------- | ------ | -------------------------- | +| `/api/cli-tools/claude-settings` | GET | Starea Claude CLI | +| `/api/cli-tools/codex-settings` | GET | Status CLI Codex | +| `/api/cli-tools/droid-settings` | GET | Stare CLI Droid | +| `/api/cli-tools/openclaw-settings` | GET | Stare CLI OpenClaw | +| `/api/cli-tools/runtime/[toolId]` | GET | Timp de rulare CLI generic | + +Răspunsurile CLI includ: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### Reziliență și limite de rată + +| Punct final | Metoda | Descriere | +| ----------------------- | ------- | ------------------------------------------- | +| `/api/resilience` | GET/PUT | Obține/actualizează profiluri de rezistență | +| `/api/resilience/reset` | POST | Resetați întrerupătoarele | +| `/api/rate-limits` | GET | Starea limitei ratei per cont | +| `/api/rate-limit` | GET | Configurație globală a limitei ratei | + +### Evaluări + +| Punct final | Metoda | Descriere | +| ------------ | -------- | ---------------------------------------------- | +| `/api/evals` | GET/POST | Lista suitelor de evaluare / evaluarea rulării | + +### Politici + +| Punct final | Metoda | Descriere | +| --------------- | --------------- | ------------------------------- | +| `/api/policies` | GET/POST/DELETE | Gestionați politicile de rutare | + +### Conformitate + +| Punct final | Metoda | Descriere | +| --------------------------- | ------ | ------------------------------------------- | +| `/api/compliance/audit-log` | GET | Jurnal de audit de conformitate (ultimul N) | + +### v1beta (compatibil cu Gemini) + +| Punct final | Metoda | Descriere | +| -------------------------- | ------ | ------------------------------------ | +| `/v1beta/models` | GET | Listează modele în format Gemeni | +| `/v1beta/models/{...path}` | POST | Punct final Gemeni `generateContent` | + +Aceste puncte finale reflectă formatul API al Gemini pentru clienții care se așteaptă la compatibilitate nativă cu SDK Gemini. + +### API-uri interne/de sistem + +| Punct final | Metoda | Descriere | +| --------------- | ------ | ---------------------------------------------------------------- | +| `/api/init` | GET | Verificarea inițializării aplicației (utilizată la prima rulare) | +| `/api/tags` | GET | Etichete de model compatibile cu Ollama (pentru clienții Ollama) | +| `/api/restart` | POST | Declanșează repornirea grațioasă a serverului | +| `/api/shutdown` | POST | Declanșează închiderea grațioasă a serverului | + +> **Notă:** Aceste puncte finale sunt utilizate intern de sistem sau pentru compatibilitatea clientului Ollama. De obicei, acestea nu sunt apelate de utilizatorii finali. + +--- + +## Transcriere audio + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Transcrie fișiere audio folosind Deepgram sau AssemblyAI. + +**Solicitare:** + +```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" +``` + +**Răspuns:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**Furnizori acceptați:** `deepgram/nova-3`, `assemblyai/best`. + +**Formate acceptate:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, **OMNI*TOKEN***EN.\_11_TO\_\_ + +--- + +## Compatibilitate Ollama + +Pentru clienții care folosesc formatul API al Ollama: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +Cererile sunt traduse automat între Ollama și formatele interne. + +--- + +## Telemetrie + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Răspuns:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## Buget + +```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" +} +``` + +--- + +## Disponibilitatea modelului + +```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" +} +``` + +--- + +## Procesarea cererii + +1. Clientul trimite cererea către `/v1/*` +2. Apelurile de gestionare a rutei `handleChat`, `handleEmbedding`, `handleAudioTranscription` sau `handleImageGeneration` +3. Modelul este rezolvat (furnizor direct/model sau alias/combo) +4. Acreditări selectate din DB local cu filtrarea disponibilității contului +5. Pentru chat: `handleChatCore` — detectarea formatului, traducerea, verificarea memoriei cache, verificarea idempotității +6. Executorul furnizorului trimite cererea în amonte +7. Răspunsul tradus înapoi în formatul client (chat) sau returnat așa cum este (încorporare/imagini/audio) +8. Utilizare/înregistrare înregistrată +9. Fallback se aplică erorilor conform regulilor combinate + +Referință completă a arhitecturii: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## Autentificare + +- Rutele tabloului de bord (`/dashboard/*`) folosesc `auth_token` cookie +- Conectarea folosește hash-ul parolei salvate; alternativă la `INITIAL_PASSWORD` +- `requireLogin` comutabil prin `/api/settings/require-login` +- Rutele `/v1/*` necesită opțional cheia API Bearer când `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ro/ARCHITECTURE.md b/docs/i18n/ro/ARCHITECTURE.md new file mode 100644 index 0000000000..0754c2828e --- /dev/null +++ b/docs/i18n/ro/ARCHITECTURE.md @@ -0,0 +1,781 @@ +# Arhitectura 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) + +_Ultima actualizare: 2026-02-18_ + +## Rezumat executiv + +OmniRoute este un gateway local de rutare AI și un tablou de bord construit pe Next.js. +Acesta oferă un singur punct final compatibil cu OpenAI (`/v1/*`) și direcționează traficul către mai mulți furnizori din amonte cu traducere, alternativă, reîmprospătare token și urmărire a utilizării. + +Capacitățile de bază: + +- Suprafață API compatibilă cu OpenAI pentru CLI/instrumente (28 de furnizori) +- Traducerea cererii/răspunsurilor între formatele furnizorilor +- Alternativ combo de model (secvență cu mai multe modele) +- Rezervă de rezervă la nivel de cont (cu mai multe conturi pentru fiecare furnizor) +- Gestionarea conexiunii furnizorului OAuth + cheie API +- Generare de încorporare prin `/v1/embeddings` (6 furnizori, 9 modele) +- Generare de imagini prin `/v1/images/generations` (4 furnizori, 9 modele) +- Gândiți-vă la analizarea etichetelor (`...`) pentru modele de raționament +- Sanitizarea răspunsului pentru compatibilitate strictă cu OpenAI SDK +- Normalizarea rolurilor (dezvoltator→sistem, sistem→utilizator) pentru compatibilitate între furnizori +- Conversie de ieșire structurată (json_schema → Gemini responseSchema) +- Persistență locală pentru furnizori, chei, aliasuri, combo-uri, setări, prețuri +- Urmărirea utilizării/costurilor și înregistrarea cererilor +- Sincronizare cloud opțională pentru sincronizare multi-dispozitiv/state +- Lista permisă/lista blocată IP pentru controlul accesului API +- Gândire la managementul bugetului (passthrough/auto/personalizat/adaptativ) +- Sistem global de injectare promptă +- Urmărirea sesiunii și amprentarea +- Limitare îmbunătățită a ratei per cont cu profiluri specifice furnizorului +- Model de întrerupător pentru rezistența furnizorului +- Protectie anti-tunet cu blocare mutex +- Cache de deduplicare a cererilor bazate pe semnătură +- Nivelul domeniului: disponibilitatea modelului, regulile de cost, politica de rezervă, politica de blocare +- Persistența stării domeniului (cache-ul de scriere SQLite pentru rezervări, bugete, blocări, întreruptoare de circuit) +- Motor de politici pentru evaluarea centralizată a cererilor (blocare → buget → rezervă) +- Solicitați telemetrie cu agregarea latenței p50/p95/p99 +- ID de corelare (X-Request-Id) pentru urmărirea de la capăt la capăt +- Înregistrare de audit de conformitate cu renunțare pentru fiecare cheie API +- Cadrul de evaluare pentru asigurarea calității LLM +- Tabloul de bord Resilience UI cu starea întreruptorului în timp real +- Furnizori OAuth modulari (12 module individuale sub `src/lib/oauth/providers/`) + +Model de rulare principal: + +- Rutele aplicației Next.js sub `src/app/api/*` implementează atât API-uri de tablou de bord, cât și API-uri de compatibilitate +- Un nucleu SSE/rutare partajat în `src/sse/*` + `open-sse/*` se ocupă de execuția furnizorului, traducerea, transmiterea în flux, alternativă și utilizare + +## Domeniul de aplicare și limitele + +### În domeniul de aplicare + +- Timp de rulare gateway local +- API-uri de gestionare a tabloului de bord +- Autentificarea furnizorului și reîmprospătarea simbolului +- Solicitați traducere și streaming SSE +- Stare locală + persistență de utilizare +- Orchestrare opțională de sincronizare în cloud + +### În afara domeniului de aplicare + +- Implementarea serviciului cloud în spatele `NEXT_PUBLIC_CLOUD_URL` +- Furnizor SLA/plan de control în afara procesului local +- Binarele CLI externe în sine (Claude CLI, Codex CLI etc.) + +## Context de sistem la nivel înalt + +```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 +``` + +## Componente Core Runtime + +## 1) API și stratul de rutare (Rute pentru aplicații Next.js) + +Directoare principale: + +- `src/app/api/v1/*` și `src/app/api/v1beta/*` pentru API-uri de compatibilitate +- `src/app/api/*` pentru API-uri de gestionare/configurare +- Următoarea rescrie în harta `next.config.mjs` `/v1/*` în `/api/v1/*` + +Rute importante de compatibilitate: + +- `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 modele personalizate cu `custom: true` +- `src/app/api/v1/embeddings/route.ts` — generare de încorporare (6 furnizori) +- `src/app/api/v1/images/generations/route.ts` — generare de imagini (4+ furnizori inclusiv Antigravity/Nebius) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` — chat dedicat pentru fiecare furnizor +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` — încorporare dedicate pentru fiecare furnizor +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` — imagini dedicate pentru fiecare furnizor +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Domenii de management: + +- Autentificare/setări: `src/app/api/auth/*`, `src/app/api/settings/*` +- Furnizori/conexiuni: `src/app/api/providers*` +- Noduri furnizor: `src/app/api/provider-nodes*` +- Modele personalizate: `src/app/api/provider-models` (GET/POST/DELETE) +- Catalog de modele: `src/app/api/models/catalog` (GET) +- Configurare proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Chei/alias-uri/combo/preț: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Utilizare: `src/app/api/usage/*` +- Sincronizare/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- Ajutor de instrumente CLI: `src/app/api/cli-tools/*` +- Filtru IP: `src/app/api/settings/ip-filter` (GET/PUT) +- Buget de gândire: `src/app/api/settings/thinking-budget` (GET/PUT) +- prompt de sistem: `src/app/api/settings/system-prompt` (GET/PUT) +- Sesiuni: `src/app/api/sessions` (GET) +- Limite de rate: `src/app/api/rate-limits` (GET) +- Reziliență: `src/app/api/resilience` (GET/PATCH) — profiluri furnizor, întrerupător, stare limită a ratei +- Resetare rezistență: `src/app/api/resilience/reset` (POST) — resetare întrerupătoare + cooldowns +- Statistici cache: `src/app/api/cache/stats` (GET/DELETE) +- Disponibilitatea modelului: `src/app/api/models/availability` (GET/POST) +- Telemetrie: `src/app/api/telemetry/summary` (GET) +- Buget: `src/app/api/usage/budget` (GET/POST) +- Lanțuri de rezervă: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Audit de conformitate: `src/app/api/compliance/audit-log` (GET) +- Evaluări: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Politici: `src/app/api/policies` (GET/POST) + +## 2) SSE + Translation Core + +Module principale de flux: + +- Intrare: `src/sse/handlers/chat.ts` +- Orchestrare de bază: `open-sse/handlers/chatCore.ts` +- Adaptoare de execuție furnizor: `open-sse/executors/*` +- Format de detectare/configurare furnizor: `open-sse/services/provider.ts` +- Analiza/rezolvarea modelului: `src/sse/services/model.ts`, `open-sse/services/model.ts` +- Logica de rezervă a contului: `open-sse/services/accountFallback.ts` +- Registrul traducerilor: `open-sse/translator/index.ts` +- Transformări de flux: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Extragerea/normalizarea utilizării: `open-sse/utils/usageTracking.ts` +- Analizator de etichete de gândire: `open-sse/utils/thinkTagParser.ts` +- Manager de încorporare: `open-sse/handlers/embeddings.ts` +- Încorporarea registrului furnizorului: `open-sse/config/embeddingRegistry.ts` +- Manager de generare a imaginii: `open-sse/handlers/imageGeneration.ts` +- Registrul furnizorului de imagini: `open-sse/config/imageRegistry.ts` +- igienizare răspuns: `open-sse/handlers/responseSanitizer.ts` +- Normalizare rol: `open-sse/services/roleNormalizer.ts` + +Servicii (logica de afaceri): + +- Selectarea/punctarea contului: `open-sse/services/accountSelector.ts` +- Gestionarea ciclului de viață a contextului: `open-sse/services/contextManager.ts` +- Aplicarea filtrului IP: `open-sse/services/ipFilter.ts` +- Urmărirea sesiunii: `open-sse/services/sessionManager.ts` +- Solicitați deduplicarea: `open-sse/services/signatureCache.ts` +- Injectarea promptă a sistemului: `open-sse/services/systemPrompt.ts` +- Gândirea bugetului: `open-sse/services/thinkingBudget.ts` +- rutare model wildcard: `open-sse/services/wildcardRouter.ts` +- Gestionarea limitei ratei: `open-sse/services/rateLimitManager.ts` +- Întrerupător: `open-sse/services/circuitBreaker.ts` + +Module de nivel de domeniu: + +- Disponibilitatea modelului: `src/lib/domain/modelAvailability.ts` +- Reguli de cost/bugete: `src/lib/domain/costRules.ts` +- Politica de rezervă: `src/lib/domain/fallbackPolicy.ts` +- Soluție combinată: `src/lib/domain/comboResolver.ts` +- Politica de blocare: `src/lib/domain/lockoutPolicy.ts` +- Motor de politici: `src/domain/policyEngine.ts` — blocare centralizată → buget → evaluare alternativă +- Catalog coduri de eroare: `src/lib/domain/errorCodes.ts` +- ID cerere: `src/lib/domain/requestId.ts` +- Timeout pentru preluare: `src/lib/domain/fetchTimeout.ts` +- Solicitați telemetrie: `src/lib/domain/requestTelemetry.ts` +- Conformitate/audit: `src/lib/domain/compliance/index.ts` +- Runner de evaluare: `src/lib/domain/evalRunner.ts` +- Persistența stării domeniului: `src/lib/db/domainState.ts` — SQLite CRUD pentru lanțuri de rezervă, bugete, istoricul costurilor, starea de blocare, întrerupătoarele de circuit + +Module de furnizor OAuth (12 fișiere individuale sub `src/lib/oauth/providers/`): + +- Index de registru: `src/lib/oauth/providers/index.ts` +- Furnizori individuali: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, **OMNI_TOKEN**, **OMNI_TOKEN**, **OMNI_TOKEN**, `kimi-coding.ts`, `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Ambalaj subțire: `src/lib/oauth/providers.ts` — reexporturi din module individuale + +## 3) Stratul de persistență + +DB de stat primar: + +- `src/lib/localDb.ts` +- fișier: `${DATA_DIR}/db.json` (sau `$XDG_CONFIG_HOME/omniroute/db.json` când este setat, altfel `~/.omniroute/db.json`) +- entități: providerConnections, providerNodes, modelAliases, combo-uri, apiKeys, setări, prețuri, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +DB de utilizare: + +- `src/lib/usageDb.ts` +- fișiere: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- urmează aceeași politică de bază de director ca `localDb` (`DATA_DIR`, apoi `XDG_CONFIG_HOME/omniroute` când este setat) +- descompus în sub-module focalizate: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +DB Stare Domeniu (SQLite): + +- `src/lib/db/domainState.ts` — Operații CRUD pentru starea domeniului +- Tabele (create în `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, `domain_circuit_breakers`\_ +- Model de cache de scriere: hărțile din memorie sunt autorizate în timpul execuției; mutațiile sunt scrise sincron cu SQLite; starea este restabilită din DB la pornirea la rece + +## 4) Autentificare + Suprafețe de securitate + +- Autentificare cookie pentru tabloul de bord: `src/proxy.ts`, `src/app/api/auth/login/route.ts` +- Generarea/verificarea cheii API: `src/shared/utils/apiKey.ts` +- Secretele furnizorului au persistat în intrările `providerConnections` +- Suport proxy de ieșire prin `open-sse/utils/proxyFetch.ts` (env vars) și `open-sse/utils/networkProxy.ts` (configurabil per furnizor sau global) + +## 5) Cloud Sync + +- Inițierea planificatorului: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Sarcină periodică: `src/shared/services/cloudSyncScheduler.ts` +- Rută de control: `src/app/api/sync/cloud/route.ts` + +## Ciclul de viață al solicitării (`/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 + Flux de rezervă pentru cont + +```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] +``` + +Deciziile de rezervă sunt conduse de `open-sse/services/accountFallback.ts` folosind coduri de stare și euristică mesaj de eroare. + +## Ciclul de viață OAuth Onboarding și Token Refresh + +```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 +``` + +Reîmprospătarea în timpul traficului live este executată în interiorul `open-sse/handlers/chatCore.ts` prin intermediul executorului `refreshCredentials()`. + +## Ciclul de viață Cloud Sync (Activare / Sincronizare / Dezactivare) + +```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 +``` + +Sincronizarea periodică este declanșată de `CloudSyncScheduler` când cloud este activat. + +## Model de date și hartă de stocare + +```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 + } +``` + +Fișiere de stocare fizică: + +- starea principală: `${DATA_DIR}/db.json` (sau `$XDG_CONFIG_HOME/omniroute/db.json` când este setat, altfel `~/.omniroute/db.json`) +- statistici de utilizare: `${DATA_DIR}/usage.json` +- linii de jurnal de solicitare: `${DATA_DIR}/log.txt` +- sesiuni opționale de traducător/cerere de depanare: `/logs/...` + +## Topologie de implementare + +```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 +``` + +## Maparea modulului (decizie critică) + +### Rută și module API + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: API-uri de compatibilitate +- `src/app/api/v1/providers/[provider]/*`: rute dedicate pentru fiecare furnizor (chat, încorporare, imagini) +- `src/app/api/providers*`: furnizor CRUD, validare, testare +- `src/app/api/provider-nodes*`: gestionarea nodurilor compatibile personalizate +- `src/app/api/provider-models`: management personalizat model (CRUD) +- `src/app/api/models/catalog`: API de catalog de model complet (toate tipurile grupate după furnizor) +- `src/app/api/oauth/*`: fluxuri OAuth/cod dispozitiv +- `src/app/api/keys*`: ciclul de viață local al cheii API +- `src/app/api/models/alias`: gestionare alias +- `src/app/api/combos*`: gestionarea combo de rezervă +- `src/app/api/pricing`: înlocuirea prețurilor pentru calcularea costurilor +- `src/app/api/settings/proxy`: configurație proxy (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: test de conectivitate proxy de ieșire (POST) +- `src/app/api/usage/*`: API-uri de utilizare și jurnal +- `src/app/api/sync/*` + `src/app/api/cloud/*`: sincronizare în cloud și asistență orientată către nor +- `src/app/api/cli-tools/*`: scriitori/verificatori de configurare CLI locale +- `src/app/api/settings/ip-filter`: lista IP permisă/lista blocată (GET/PUT) +- `src/app/api/settings/thinking-budget`: configurația bugetului simbolului de gândire (GET/PUT) +- `src/app/api/settings/system-prompt`: prompt de sistem global (GET/PUT) +- `src/app/api/sessions`: listarea sesiunii active (GET) +- `src/app/api/rate-limits`: starea limită a ratei per cont (GET) + +### Core de rutare și execuție + +- `src/sse/handlers/chat.ts`: analizarea cererii, gestionarea combinațiilor, bucla de selecție a contului +- `open-sse/handlers/chatCore.ts`: traducere, expediere executor, reîncercare/reîmprospătare manipulare, configurare flux +- `open-sse/executors/*`: comportamentul de rețea și format specific furnizorului + +### Registrul de traduceri și convertoare de format + +- `open-sse/translator/index.ts`: registru și orchestrare a traducătorilor +- Solicitați traducători: `open-sse/translator/request/*` +- Traducători de răspuns: `open-sse/translator/response/*` +- Formatare constante: `open-sse/translator/formats.ts` + +### Persistență + +- `src/lib/localDb.ts`: config/stare persistentă +- `src/lib/usageDb.ts`: istoricul utilizării și jurnalele de solicitare continuă + +## Acoperire Executor Furnizor (Model de strategie) + +Fiecare furnizor are un executor specializat care extinde `BaseExecutor` (în `open-sse/executors/base.ts`), care oferă crearea URL, construcția antetului, reîncercarea cu backoff exponențial, cârlige de reîmprospătare a acreditărilor și metoda de orchestrare `execute()`. + +| Executant | Furnizor(i) | Manipulare specială | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Configurare URL dinamică/antet per furnizor | +| `AntigravityExecutor` | Google Antigravity | ID-uri personalizate de proiect/sesiune, Reîncercați-După analizare | +| `CodexExecutor` | OpenAI Codex | Injectează instrucțiuni de sistem, forțează efortul de raționament | +| `CursorExecutor` | Cursor IDE | Protocolul ConnectRPC, codificarea Protobuf, semnarea cererii prin suma de control | +| `GithubExecutor` | GitHub Copilot | Reîmprospătare jeton Copilot, anteturi care imită VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | Format binar AWS EventStream → conversie SSE | +| `GeminiCLIExecutor` | Gemeni CLI | Ciclul de reîmprospătare a simbolului OAuth Google | + +Toți ceilalți furnizori (inclusiv noduri compatibile personalizate) folosesc `DefaultExecutor`. + +## Matricea de compatibilitate a furnizorilor + +| Furnizor | Format | Auth | Flux | Non-Stream | Token Refresh | Utilizare API | +| ---------------- | ---------------- | ----------------------------- | ---------------- | ---------- | ------------- | ---------------------- | +| Claude | claude | Cheie API / OAuth | ✅ | ✅ | ✅ | ⚠️ Doar administrator | +| Gemeni | gemeni | Cheie API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Gemeni CLI | gemeni-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloud Console | +| Antigravitație | antigravitație | OAuth | ✅ | ✅ | ✅ | ✅ Cota completă API | +| OpenAI | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Codex | openai-responses | OAuth | ✅ forțat | ❌ | ✅ | ✅ Limite de tarif | +| GitHub Copilot | deschis | OAuth + Token Copilot | ✅ | ✅ | ✅ | ✅ Instantanee de cotă | +| Cursor | cursor | Sumă de control personalizată | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Limite de utilizare | +| Qwen | deschis | OAuth | ✅ | ✅ | ✅ | ⚠️ La cerere | +| iFlow | deschis | OAuth (de bază) | ✅ | ✅ | ✅ | ⚠️ La cerere | +| OpenRouter | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | Cheie API | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Groq | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Mistral | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Nedumerire | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Împreună AI | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Artificii AI | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Cerebre | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| Cohere | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | deschis | Cheie API | ✅ | ✅ | ❌ | ❌ | + +## Format Acoperire traducere + +Formatele sursă detectate includ: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Formatele țintă includ: + +- Chat/Răspunsuri OpenAI +- Claude +- Plic Gemeni/Gemeni-CLI/Antigravity +- Kiro +- Cursor + +Traducerile folosesc **OpenAI ca format hub** — toate conversiile trec prin OpenAI ca intermediar: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +Traducerile sunt selectate dinamic pe baza formei încărcăturii sursei și a formatului țintă al furnizorului. + +Straturi de procesare suplimentare în conducta de traducere: + +- **Sanitizarea răspunsurilor** — Elimina câmpurile nestandard din răspunsurile în format OpenAI (atât în flux, cât și în non-streaming) pentru a asigura conformitatea strictă cu SDK +- **Normalizarea rolurilor** — Convertește `developer` → `system` pentru ținte non-OpenAI; îmbină `system` → `user` pentru modelele care resping rolul de sistem (GLM, ERNIE) +- **Think tag extraction** — Analizează blocurile `...` din conținut în câmpul `reasoning_content` +- **Ieșire structurată** — Convertește OpenAI `response_format.json_schema` în `responseMimeType` al lui Gemini + `responseSchema` + +## Puncte finale API acceptate + +| Punct final | Format | Manipulator | +| -------------------------------------------------- | ---------------------- | -------------------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Mesaje | Același handler (detectat automat) | +| `POST /v1/responses` | Răspunsuri OpenAI | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | Încorporare OpenAI | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Lista de modele | Rută API | +| `POST /v1/images/generations` | Imagini OpenAI | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Lista de modele | Rută API | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Dedicat pentru fiecare furnizor cu validare a modelului | +| `POST /v1/providers/{provider}/embeddings` | Încorporare OpenAI | Dedicat pentru fiecare furnizor cu validare a modelului | +| `POST /v1/providers/{provider}/images/generations` | Imagini OpenAI | Dedicat pentru fiecare furnizor cu validare a modelului | +| `POST /v1/messages/count_tokens` | Claude Token Count | Rută API | +| `GET /v1/models` | Lista de modele OpenAI | Rută API (chat + încorporare + imagine + modele personalizate) | +| `GET /api/models/catalog` | Catalog | Toate modelele grupate după furnizor + tip | +| `POST /v1beta/models/*:streamGenerateContent` | nativ Gemeni | Rută API | +| `GET/PUT/DELETE /api/settings/proxy` | Configurare proxy | Configurare proxy de rețea | +| `POST /api/settings/proxy/test` | Conectivitate proxy | Punct final de testare de sănătate/conectivitate proxy | +| `GET/POST/DELETE /api/provider-models` | Modele personalizate | Gestionare model personalizat per furnizor | + +## Handler de ocolire + +Managerul de ocolire (`open-sse/utils/bypassHandler.ts`) interceptează cererile cunoscute „de aruncat” de la Claude CLI — ping-uri de încălzire, extrageri de titluri și numărătoare de jetonuri — și returnează un **răspuns fals** fără a consuma jetoane de furnizor în amonte. Aceasta este declanșată numai atunci când `User-Agent` conține `claude-cli`. + +## Solicitați Conducta Logger + +Loggerul de solicitare (`open-sse/utils/requestLogger.ts`) oferă o conductă de înregistrare a depanării în 7 etape, dezactivată implicit, activată prin `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 +``` + +Fișierele sunt scrise în `/logs//` pentru fiecare sesiune de solicitare. + +## Moduri de eșec și rezistență + +## 1) Disponibilitatea contului/furnizorului + +- cooldown contului furnizorului pentru erori tranzitorii/rate/auth +- rezervă de cont înainte de cererea eșuată +- alternativă model combo atunci când modelul curent/calea furnizorului este epuizată + +## 2) Expirarea simbolului + +- preverificare și reîmprospătare cu reîncercare pentru furnizorii care pot fi reîmprospătați +- 401/403 reîncercați după încercarea de reîmprospătare în calea de bază + +## 3) Siguranța fluxului + +- controler de flux conștient de deconectare +- flux de traducere cu spălare la sfârșitul fluxului și gestionarea `[DONE]` +- estimarea utilizării de rezervă atunci când metadatele de utilizare ale furnizorului lipsesc + +## 4) Degradarea Cloud Sync + +- apar erori de sincronizare, dar timpul de execuție local continuă +- planificatorul are o logică capabilă să reîncerce, dar execuția periodică apelează în mod implicit sincronizarea cu o singură încercare + +## 5) Integritatea datelor + +- Migrare/reparare forme DB pentru cheile lipsă +- garanții de resetare JSON corupte pentru localDb și usageDb + +## Observabilitate și semnale operaționale + +Surse de vizibilitate la runtime: + +- jurnalele consolei de la `src/sse/utils/logger.ts` +- agregate de utilizare la cerere în `usage.json` +- autentificarea stării cererii textuale `log.txt` +- jurnalele opționale de solicitare profundă/traducere sub `logs/` când `ENABLE_REQUEST_LOGS=true` +- puncte finale de utilizare a tabloului de bord (`/api/usage/*`) pentru consumul UI + +## Limite sensibile la securitate + +- Secretul JWT (`JWT_SECRET`) securizează verificarea/semnarea cookie-urilor sesiunii de bord +- Parola de rezervă inițială (`INITIAL_PASSWORD`, implicit `123456`) trebuie să fie înlocuită în implementările reale +- Secretul HMAC cheie API (`API_KEY_SECRET`) securizează formatul cheii API locale generate +- Secretele furnizorului (chei/token-uri API) sunt păstrate în DB local și ar trebui protejate la nivel de sistem de fișiere +- Punctele finale de sincronizare în cloud se bazează pe semantica de autentificare a cheii API + ID-ul mașinii + +## Mediu și matrice de rulare + +Variabilele de mediu utilizate în mod activ de cod: + +- Aplicație/autentificare: `JWT_SECRET`, `INITIAL_PASSWORD` +- Stocare: `DATA_DIR` +- Comportamentul nodului compatibil: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Suprascriere opțională a bazei de stocare (Linux/macOS când `DATA_DIR` dezactivat): `XDG_CONFIG_HOME` +- Hashing de securitate: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Înregistrare: `ENABLE_REQUEST_LOGS` +- URL sincronizare/cloud: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` +- Proxy de ieșire: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` și variante cu litere mici +- Indicatori de caracteristică SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` +- Ajutor platformă/execuție (configurație nu specifică aplicației): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Note arhitecturale cunoscute + +1. `usageDb` și `localDb` au acum aceeași politică de bază de director (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) cu migrarea fișierelor moștenite. +2. `/api/v1/route.ts` returnează o listă de modele statice și nu este sursa principală de modele utilizată de `/v1/models`. +3. Loggerul solicitărilor scrie anteturi/corp complet atunci când este activat; tratați directorul de jurnal ca fiind sensibil. +4. Comportamentul în cloud depinde de `NEXT_PUBLIC_BASE_URL` corect și de accesibilitatea punctului final din cloud. +5. Directorul `open-sse/` este publicat ca pachetul `@omniroute/open-sse` **npm workspace**. Codul sursă îl importă prin `@omniroute/open-sse/...` (rezolvat de Next.js `transpilePackages`). Căile fișierelor din acest document folosesc în continuare numele directorului `open-sse/` pentru consecvență. +6. Diagramele din tabloul de bord utilizează **Recharts** (bazate pe SVG) pentru vizualizări analitice accesibile, interactive (diagrame cu bare de utilizare a modelelor, tabele de defalcare a furnizorilor cu rate de succes). +7. Testele E2E folosesc **Playwright** (`tests/e2e/`), rulat prin `npm run test:e2e`. Testele unitare folosesc **Node.js test runner** (`tests/unit/`), rulează prin `npm run test:plan3`. Codul sursă sub `src/` este **TypeScript** (`.ts`/`.tsx`); spațiul de lucru `open-sse/` rămâne JavaScript (`.js`). +8. Pagina Setări este organizată în 5 file: Securitate, Rutare (6 strategii globale: fill-first, round-robin, p2c, aleatoriu, cel mai puțin utilizat, optimizat pentru cost), Reziliență (limite ale ratei editabile, întrerupător de circuit, politici), AI (buget de gândire, prompt de sistem, cache prompt), Avansat (proxy). + +## Lista de verificare a verificării operaționale + +- Construire din sursă: `npm run build` +- Creați imaginea Docker: `docker build -t omniroute .` +- Porniți serviciul și verificați: +- `GET /api/settings` +- `GET /api/v1/models` +- Adresa URL de bază țintă CLI ar trebui să fie `http://:20128/v1` când `PORT=20128` diff --git a/docs/i18n/ro/CODEBASE_DOCUMENTATION.md b/docs/i18n/ro/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..c1078cdeca --- /dev/null +++ b/docs/i18n/ro/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute — Documentația de bază de cod + +🌐 **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) + +> Un ghid cuprinzător, prietenos pentru începători, pentru routerul proxy AI cu mai mulți furnizori **omniroute**. + +--- + +## 1. Ce este omniroute? + +omniroute este un **router proxy** care se află între clienții AI (Claude CLI, Codex, Cursor IDE etc.) și furnizorii AI (Anthropic, Google, OpenAI, AWS, GitHub etc.). Rezolvă o mare problemă: + +> **Diferiți clienți AI vorbesc diferite „limbi” (formate API), iar diferiți furnizori de AI se așteaptă și ei la „limbi” diferite.** Omniroute se traduce automat între ele. + +Gândiți-vă la asta ca la un traducător universal la Națiunile Unite - orice delegat poate vorbi orice limbă, iar traducătorul o convertește pentru orice alt delegat. + +--- + +## 2. Privire de ansamblu asupra arhitecturii + +```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 +``` + +### Principiul de bază: Traducerea hub-and-spoke + +Toată traducerea formatului trece prin **formatul OpenAI ca hub**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +Aceasta înseamnă că aveți nevoie doar de **N traducători** (unul pentru fiecare format) în loc de **N²** (fiecare pereche). + +--- + +## 3. Structura proiectului + +``` +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. Defalcare modul cu modul + +### 4.1 Configurare (`open-sse/config/`) + +**Sursa unică de adevăr** pentru configurația tuturor furnizorilor. + +| Fișier | Scop | +| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `constants.ts` | `PROVIDERS` obiect cu adrese URL de bază, acreditări OAuth (implicite), anteturi și solicitări implicite de sistem pentru fiecare furnizor. De asemenea, definește `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` și `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Încarcă acreditările externe de la `data/provider-credentials.json` și le îmbină peste valorile implicite codificate în `PROVIDERS`. Păstrează secretele sub controlul sursei, menținând în același timp compatibilitatea cu versiunea inversă. | +| `providerModels.ts` | Registrul central de modele: hărți aliasuri furnizori → ID-uri model. Funcții precum `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | Instrucțiuni de sistem injectate în cererile Codex (constrângeri de editare, reguli sandbox, politici de aprobare). | +| `defaultThinkingSignature.ts` | Semnături implicite „de gândire” pentru modelele Claude și Gemini. | +| `ollamaModels.ts` | Definirea schemei pentru modelele locale Ollama (nume, dimensiune, familie, cuantizare). | + +#### Flux de încărcare a acreditărilor + +```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 Executori (`open-sse/executors/`) + +Executorii încapsulează **logica specifică furnizorului** utilizând **Modelul de strategie**. Fiecare executant anulează metodele de bază după cum este necesar. + +```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 +``` + +| Executant | Furnizor | Specializări cheie | +| ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Bază abstractă: crearea adresei URL, anteturi, logica reîncercării, reîmprospătarea acreditărilor | +| `default.ts` | Claude, Gemeni, OpenAI, GLM, Kimi, MiniMax | Reîmprospătare generică a jetonului OAuth pentru furnizorii standard | +| `antigravity.ts` | Cod Google Cloud | Generarea ID-ului de proiect/sesiune, alternativă cu mai multe adrese URL, reîncercare personalizată de analiză din mesajele de eroare („resetare după 2h7m23s”) | +| `cursor.ts` | Cursor IDE | **Cel mai complex**: SHA-256 checksum auth, codificare cerere Protobuf, binar EventStream → analiza răspuns SSE | +| `codex.ts` | OpenAI Codex | Injectează instrucțiuni de sistem, gestionează nivelurile de gândire, elimină parametrii neacceptați | +| `gemini-cli.ts` | Google Gemini CLI | Creare URL personalizată (`streamGenerateContent`), reîmprospătare jeton OAuth Google | +| `github.ts` | GitHub Copilot | Sistem dual token (GitHub OAuth + token Copilot), imitarea antetului VSCode | +| `kiro.ts` | AWS CodeWhisperer | Analiza binară AWS EventStream, cadre de evenimente AMZN, estimare token | +| `index.ts` | — | Fabrică: numele furnizorului de hărți → clasa executorului, cu fallback implicit | + +--- + +### 4.3 Handlers (`open-sse/handlers/`) + +**Stratul de orchestrare** — coordonează traducerea, execuția, transmiterea în flux și gestionarea erorilor. + +| Fișier | Scop | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `chatCore.ts` | **Orchestrator central** (~600 de linii). Se ocupă de ciclul de viață complet al cererii: detectarea formatului → traducerea → expedierea executorului → răspunsul în flux/non-streaming → reîmprospătarea simbolului → gestionarea erorilor → înregistrarea utilizării. | +| `responsesHandler.ts` | Adaptor pentru API-ul OpenAI Responses: convertește formatul de răspunsuri → Terminări de chat → trimite la `chatCore` → convertește SSE înapoi în formatul de răspunsuri. | +| `embeddings.ts` | Managerul de generare de încorporare: rezolvă modelul de încorporare → furnizor, trimite către API-ul furnizorului, returnează un răspuns de încorporare compatibil OpenAI. Suportă peste 6 furnizori. | +| `imageGeneration.ts` | Managerul de generare a imaginii: rezolvă modelul de imagine → furnizor, acceptă modurile compatibile cu OpenAI, Gemini-image (antigravitație) și modurile de rezervă (Nebius). Returnează imagini base64 sau URL. | + +#### Ciclul de viață al cererii (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 Servicii (`open-sse/services/`) + +Logica de afaceri care sprijină manipulatorii și executanții. + +| Fișier | Scop | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Detecție format** (`detectFormat`): analizează structura corpului cererii pentru a identifica formatele Claude/OpenAI/Gemini/Antigravity/Responses (include `max_tokens` euristica pentru Claude). De asemenea: construirea URL, construirea antetului, normalizarea configurației gândirii. Acceptă furnizorii dinamici `openai-compatible-*` și `anthropic-compatible-*`. | +| `model.ts` | Analizarea șirurilor de model (`claude/model-name` → `{provider: "claude", model: "model-name"}`), rezoluția aliasului cu detectarea coliziunilor, dezinfectarea intrării (respinge caracterele de parcurgere/control al căii) și rezoluția informațiilor despre model cu suport pentru obținerea de alias asincron. | +| `accountFallback.ts` | Gestionarea limitelor de rată: retragere exponențială (1s → 2s → 4s → max 2 min), gestionarea timpului de răcire a contului, clasificarea erorilor (care declanșează erorile de rezervă vs. nu). | +| `tokenRefresh.ts` | Actualizare jeton OAuth pentru **fiecare furnizor**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (OAuth + Copilot dual-token), Kiro (AWS SSO OIDC + Social Auth). Include memoria cache de deduplicare a promisiunii în timpul zborului și reîncercarea cu backoff exponențial. | +| `combo.ts` | **Modele combinate**: lanțuri de modele de rezervă. Dacă modelul A eșuează cu o eroare eligibilă pentru rezervă, încercați modelul B, apoi C etc. Returnează codurile reale de stare din amonte. | +| `usage.ts` | Preia datele de cotă/utilizare de la API-urile furnizorului (cote GitHub Copilot, cote model antigravitație, limite ale ratei Codex, defalcări de utilizare Kiro, setări Claude). | +| `accountSelector.ts` | Selecția inteligentă a contului cu algoritm de punctare: ia în considerare prioritatea, starea de sănătate, poziția round-robin și starea de cooldown pentru a alege contul optim pentru fiecare solicitare. | +| `contextManager.ts` | Gestionarea ciclului de viață a contextului solicitării: creează și urmărește obiecte de context per-cerere cu metadate (ID-ul cererii, marcaje temporale, informații despre furnizor) pentru depanare și înregistrare. | +| `ipFilter.ts` | Controlul accesului bazat pe IP: acceptă modurile liste de permise și liste de blocare. Validează IP-ul clientului în raport cu regulile configurate înainte de a procesa solicitările API. | +| `sessionManager.ts` | Urmărirea sesiunilor cu amprenta clientului: urmărește sesiunile active folosind identificatori de client hashing, monitorizează numărul de solicitări și oferă valori ale sesiunii. | +| `signatureCache.ts` | Cache de deduplicare bazată pe semnături de solicitare: previne cererile duplicate prin memorarea în cache a semnăturilor de cereri recente și returnarea răspunsurilor memorate în cache pentru cereri identice într-o fereastră de timp. | +| `systemPrompt.ts` | Injectarea globală a promptului de sistem: adaugă sau adaugă un prompt de sistem configurabil la toate solicitările, cu gestionarea compatibilității pentru fiecare furnizor. | +| `thinkingBudget.ts` | Gestionarea bugetului token-ului de raționament: acceptă modurile passthrough, automate (configurație de gândire strip), personalizate (buget fix) și adaptive (scalate la complexitate) pentru controlul simbolurilor de gândire/raționament. | +| `wildcardRouter.ts` | Dirijarea modelului cu caractere wildcard: rezolvă modelele wildcard (de exemplu, `*/claude-*`) în perechi concrete furnizor/model în funcție de disponibilitate și prioritate. | + +#### Deduplicare de reîmprospătare a simbolului + +```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 +``` + +#### Mașină de stat de rezervă a contului + +```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 + } +``` + +#### Lanț de modele combinate + +```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 Traducător (`open-sse/translator/`) + +**Motorul de traducere a formatului** utilizând un sistem de pluginuri cu auto-înregistrare. + +#### Arhitectură + +```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 +``` + +| Director | Fișiere | Descriere | +| ------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `request/` | 8 traducători | Convertiți corpurile de solicitare între formate. Fiecare fișier se auto-înregistrează prin `register(from, to, fn)` la import. | +| `response/` | 7 traducători | Conversia fragmentelor de răspuns în flux între formate. Se ocupă de tipurile de evenimente SSE, blocurile de gândire, apelurile de instrumente. | +| `helpers/` | 6 ajutoare | Utilitare partajate: `claudeHelper` (extracția promptului sistemului, configurația gândirii), `geminiHelper` (matarea părților/conținutului), `openaiHelper` (filtrarea formatului), `toolCallHelper` (generarea ID-ului, injectarea răspunsului TOKEN_8 lipsă, \_\_8 NI_EN) `responsesApiHelper`. | +| `index.ts` | — | Motor de traducere: `translateRequest()`, `translateResponse()`, management de stat, registru. | +| `formats.ts` | — | Formatare constante: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, **OMNI_TOKEN_92_NI**, `CURSOR`, \_\_OMNI_OM | + +#### Design cheie: pluginuri cu auto-înregistrare + +```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ăți (`open-sse/utils/`) + +| Fișier | Scop | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | Crearea răspunsului la erori (format compatibil cu OpenAI), analizarea erorilor în amonte, extragerea timpului de reîncercare antigravitație din mesajele de eroare, transmiterea erorilor SSE. | +| `stream.ts` | **SSE Transform Stream** — canalul de streaming de bază. Două moduri: `TRANSLATE` (traducere în format complet) și `PASSTHROUGH` (normalizare + extragere utilizare). Se ocupă de stocarea în tampon, estimarea utilizării, urmărirea duratei conținutului. Instanțele de codificator/decodor per-stream evită starea partajată. | +| `streamHelpers.ts` | Utilitare SSE de nivel scăzut: `parseSSELine` (tolerant la spații albe), `hasValuableContent` (filtrează bucăți goale pentru OpenAI/Claude/Gemini), `fixInvalidId`, \__OMNI_TOKEN_TOKEN_(serializare SSE_103_ware) `perf_metrics` curățare). | +| `usageTracking.ts` | Extragerea utilizării jetoanelor din orice format (Claude/OpenAI/Gemini/Responses), estimare cu rapoarte separate pentru instrumente/mesaj, adăugare de buffer (marja de siguranță de 2000 de jetoane), filtrare câmp specific formatului, înregistrare în consolă cu culori ANSI. | +| `requestLogger.ts` | Înregistrarea cererilor pe bază de fișier (înregistrare prin `ENABLE_REQUEST_LOGS=true`). Creează foldere de sesiune cu fișiere numerotate: `1_req_client.json` → `7_res_client.txt`. Toate I/O sunt asincrone (foc și uitare). Mască anteturile sensibile. | +| `bypassHandler.ts` | Interceptează modele specifice din Claude CLI (extragere titlu, încălzire, numărare) și returnează răspunsuri false fără a apela niciun furnizor. Acceptă atât streaming, cât și non-streaming. Limitat intenționat la domeniul Claude CLI. | +| `networkProxy.ts` | Rezolvă URL-ul proxy de ieșire pentru un anumit furnizor cu prioritate: configurație specifică furnizorului → configurație globală → variabile de mediu (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Acceptă excluderile `NO_PROXY`. Memorează în cache configurația pentru 30 de secunde. | + +#### 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 +``` + +#### Solicitați structura sesiunii de înregistrare + +``` +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 Stratul de aplicație (`src/`) + +| Director | Scop | +| ------------- | --------------------------------------------------------------------------------------- | +| `src/app/` | Interfață de utilizare web, rute API, middleware Express, handlere de apel invers OAuth | +| `src/lib/` | Acces la baza de date (`localDb.ts`, `usageDb.ts`), autentificare, partajat | +| `src/mitm/` | Utilități proxy Man-in-the-middle pentru interceptarea traficului furnizorului | +| `src/models/` | Definițiile modelului bazei de date | +| `src/shared/` | Învelișuri în jurul funcțiilor open-sse (furnizor, flux, eroare etc.) | +| `src/sse/` | Managerii de puncte finale SSE care conectează biblioteca open-sse la rutele Express | +| `src/store/` | Managementul stării aplicației | + +#### Rute API notabile + +| Traseu | Metode | Scop | +| --------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | +| `/api/provider-models` | GET/POST/DELETE | CRUD pentru modele personalizate per furnizor | +| `/api/models/catalog` | GET | Catalog agregat al tuturor modelelor (chat, încorporare, imagine, personalizat) grupate după furnizor | +| `/api/settings/proxy` | GET/PUT/DELETE | Configurație ierarhică de ieșire proxy (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | POST | Validează conectivitatea proxy și returnează IP/latența publică | +| `/v1/providers/[provider]/chat/completions` | POST | Finalizări de chat dedicate pentru fiecare furnizor cu validare a modelului | +| `/v1/providers/[provider]/embeddings` | POST | Înglobări dedicate pentru fiecare furnizor cu validare a modelului | +| `/v1/providers/[provider]/images/generations` | POST | Generare de imagini dedicată pentru fiecare furnizor cu validarea modelului | +| `/api/settings/ip-filter` | GET/PUT | Gestionarea listei de permise/liste de blocare IP | +| `/api/settings/thinking-budget` | GET/PUT | Configurarea bugetului simbolului de raționament (passthrough/auto/custom/adaptive) | +| `/api/settings/system-prompt` | GET/PUT | Sistem global de injectare promptă pentru toate solicitările | +| `/api/sessions` | GET | Urmărirea sesiunii active și valorile | +| `/api/rate-limits` | GET | Starea limitei ratei per cont | + +--- + +## 5. Modele de design cheie + +### 5.1 Traducere hub-and-spoke + +Toate formatele se traduc prin **formatul OpenAI ca hub**. Adăugarea unui furnizor nou necesită doar scrierea **o pereche** de traducători (la/de la OpenAI), nu N perechi. + +### 5.2 Modelul Strategiei Executorului + +Fiecare furnizor are o clasă de executor dedicată care moștenește de la `BaseExecutor`. Fabrica din `executors/index.ts` îl selectează pe cel potrivit în timpul rulării. + +### 5.3 Sistem de pluginuri cu auto-înregistrare + +Modulele de traducător se înregistrează la import prin `register()`. Adăugarea unui nou traducător înseamnă doar crearea unui fișier și importarea acestuia. + +### 5.4 Retragerea contului cu retragere exponențială + +Atunci când un furnizor returnează 429/401/500, sistemul poate trece la următorul cont, aplicând perioade de răcire exponențiale (1s → 2s → 4s → max 2min). + +### 5.5 Lanțuri de modele combinate + +Un „combo” grupează mai multe șiruri `provider/model`. Dacă primul eșuează, reveniți automat la următorul. + +### 5.6 Traducere în flux cu stat + +Traducerea răspunsurilor menține starea în bucățile SSE (urmărirea blocurilor de gândire, acumularea apelurilor de instrumente, indexarea blocurilor de conținut) prin mecanismul `initState()`. + +### 5.7 Utilizare tampon de siguranță + +Un buffer de 2000 de jetoane este adăugat la utilizarea raportată pentru a preveni clienții să atingă limitele ferestrei de context din cauza supraîncărcării de la solicitările de sistem și traducerea formatului. + +--- + +## 6. Formate acceptate + +| Format | Direcție | Identificator | +| ------------------------- | ------------- | ------------------ | +| Finalizări de chat OpenAI | sursa + tinta | `openai` | +| OpenAI Responses API | sursa + tinta | `openai-responses` | +| Claude antropic | sursa + tinta | `claude` | +| Google Gemeni | sursa + tinta | `gemini` | +| Google Gemini CLI | doar țintă | `gemini-cli` | +| Antigravitație | sursa + tinta | `antigravity` | +| AWS Kiro | doar țintă | `kiro` | +| Cursor | doar țintă | `cursor` | + +--- + +## 7. Furnizori acceptați + +| Furnizor | Metoda de autentificare | Executant | Note cheie | +| ------------------------ | ----------------------------- | -------------- | ----------------------------------------------------------------------- | +| Claude antropic | Cheia API sau OAuth | Implicit | Utilizează antetul `x-api-key` | +| Google Gemeni | Cheia API sau OAuth | Implicit | Utilizează antetul `x-goog-api-key` | +| Google Gemini CLI | OAuth | GeminiCLI | Utilizează punctul final `streamGenerateContent` | +| Antigravitație | OAuth | Antigravitație | Alternativ cu mai multe adrese URL, reîncercare personalizată analizare | +| OpenAI | Cheia API | Implicit | Autoritatea purtătorului standard | +| Codex | OAuth | Codex | Injectează instrucțiuni de sistem, gestionează gândirea | +| GitHub Copilot | OAuth + Jeton Copilot | Github | Jeton dublu, imitație antet VSCode | +| Kiro (AWS) | AWS SSO OIDC sau Social | Kiro | Analiza binar EventStream | +| Cursor IDE | Autentificare sumă de control | Cursor | Codificare Protobuf, sume de control SHA-256 | +| Qwen | OAuth | Implicit | Autentificare standard | +| iFlow | OAuth (de bază + purtător) | Implicit | Antet de autentificare dublă | +| OpenRouter | Cheia API | Implicit | Autoritatea purtătorului standard | +| GLM, Kimi, MiniMax | Cheia API | Implicit | Compatibil cu Claude, utilizați `x-api-key` | +| `openai-compatible-*` | Cheia API | Implicit | Dinamic: orice punct final compatibil OpenAI | +| `anthropic-compatible-*` | Cheia API | Implicit | Dinamic: orice punct final compatibil cu Claude | + +--- + +## 8. Rezumatul fluxului de date + +### Solicitare de 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()"] +``` + +### Solicitare 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 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/ro/FEATURES.md b/docs/i18n/ro/FEATURES.md new file mode 100644 index 0000000000..abd4b2b5fc --- /dev/null +++ b/docs/i18n/ro/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — Galeria de funcții din tabloul de bord + +🌐 **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) + +Ghid vizual pentru fiecare secțiune a tabloului de bord OmniRoute. + +--- + +## 🔌 Furnizori + +Gestionați conexiunile furnizorilor AI: furnizori OAuth (Claude Code, Codex, Gemini CLI), furnizori de chei API (Groq, DeepSeek, OpenRouter) și furnizori gratuiti (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨 Combo + +Creați combinații de modele de rutare cu 6 strategii: umplere mai întâi, round-robin, putere a două alegeri, aleatoriu, cel mai puțin utilizat și optimizat din punct de vedere al costurilor. Fiecare combo înlănțuiește mai multe modele cu fallback automat. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Analytics + +Analiză cuprinzătoare a utilizării cu consum de simboluri, estimări de costuri, hărți termice ale activității, diagrame de distribuție săptămânală și defalcări pentru fiecare furnizor. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Sănătatea sistemului + +Monitorizare în timp real: timp de funcționare, memorie, versiune, percentile de latență (p50/p95/p99), statistici cache și stări întrerupătoarelor furnizorului. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Loc de joacă pentru traducător + +Patru moduri de depanare a traducerilor API: **Playground** (convertor de format), **Chat Tester** (cereri live), **Test Bench** (testare în lot) și **Live Monitor** (stream în timp real). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Setări + +Setări generale, stocare de sistem, management de backup (bază de date de export/import), aspect (mod întunecat/luminos), securitate (include protecția punctelor terminale API și blocarea furnizorilor personalizați), rutare, reziliență și configurație avansată. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Instrumente CLI + +Configurare cu un singur clic pentru instrumentele de codare AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code și Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Solicitați jurnalele + +Înregistrare în timp real a cererilor cu filtrare în funcție de furnizor, model, cont și cheie API. Afișează codurile de stare, utilizarea simbolurilor, latența și detaliile răspunsului. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 API Endpoint + +Punctul final API unificat cu defalcarea capacităților: Terminări de chat, încorporare, Generare de imagini, Reclasificare, Transcriere audio și chei API înregistrate. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/ro/TROUBLESHOOTING.md b/docs/i18n/ro/TROUBLESHOOTING.md new file mode 100644 index 0000000000..f623fe176f --- /dev/null +++ b/docs/i18n/ro/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Depanare + +🌐 **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) + +Probleme și soluții comune pentru OmniRoute. + +--- + +## Remedieri rapide + +| Problemă | Soluție | +| -------------------------------------------- | ----------------------------------------------------------------------------- | +| Prima conectare nu funcționează | Verificați `INITIAL_PASSWORD` în `.env` (implicit: `123456`) | +| Tabloul de bord se deschide pe portul greșit | Setați `PORT=20128` și `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Niciun jurnal de solicitare sub `logs/` | Setați `ENABLE_REQUEST_LOGS=true` | +| EACCES: permisiunea refuzată | Setați `DATA_DIR=/path/to/writable/dir` să înlocuiască `~/.omniroute` | +| Strategia de rutare nu se salvează | Actualizare la v1.4.11+ (remedierea schemei Zod pentru persistența setărilor) | + +--- + +## Probleme cu furnizorii + +### „Modelul de limbă nu a furnizat mesaje” + +**Cauza:** Cota de furnizor epuizată. + +**Remediere:** + +1. Verificați instrumentul de urmărire a cotelor din tabloul de bord +2. Utilizați un combo cu niveluri de rezervă +3. Treceți la nivelul mai ieftin/gratuit + +### Limitarea ratei + +**Cauza:** Cota de abonament epuizată. + +**Remediere:** + +- Adăugați alternativă: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Utilizați GLM/MiniMax ca rezervă ieftină + +### Token OAuth a expirat + +OmniRoute reîmprospătează automat jetoanele. Dacă problemele persistă: + +1. Tabloul de bord → Furnizor → Reconectare +2. Ștergeți și adăugați din nou conexiunea la furnizor + +--- + +## Probleme cu cloudul + +### Erori de sincronizare în cloud + +1. Verificați `BASE_URL` puncte către instanța dvs. care rulează (de exemplu, `http://localhost:20128`) +2. Verificați `CLOUD_URL` puncte către punctul final de cloud (de exemplu, `https://omniroute.dev`) +3. Păstrați valorile `NEXT_PUBLIC_*` aliniate cu valorile de pe server + +### Cloud `stream=false` Returnează 500 + +**Simptom:** `Unexpected token 'd'...` pe punctul final cloud pentru apeluri care nu sunt transmise în flux. + +**Cauza:** Upstream returnează sarcina utilă SSE în timp ce clientul așteaptă JSON. + +**Soluție:** utilizați `stream=true` pentru apelurile directe în cloud. Timpul de rulare local include SSE→JSON fallback. + +### Cloud spune Conectat, dar „Cheie API nevalidă” + +1. Creați o cheie nouă din tabloul de bord local (`/api/keys`) +2. Rulați sincronizarea în cloud: Activați Cloud → Sincronizare acum +3. Cheile vechi/nesincronizate pot reveni în continuare `401` pe cloud + +--- + +## Probleme cu Docker + +### Instrumentul CLI arată că nu este instalat + +1. Verificați câmpurile de rulare: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Pentru modul portabil: utilizați imaginea țintă `runner-cli` (CLI-uri incluse) +3. Pentru modul de montare gazdă: setați `CLI_EXTRA_PATHS` și montați directorul bin gazdă ca doar citire +4. Dacă `installed=true` și `runnable=false`: binarul a fost găsit, dar verificarea de sănătate a eșuat + +### Validare rapidă de rulare + +```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}' +``` + +--- + +## Probleme de cost + +### Costuri ridicate + +1. Verificați statisticile de utilizare în Tabloul de bord → Utilizare +2. Comutați modelul principal la GLM/MiniMax +3. Utilizați nivelul gratuit (Gemini CLI, iFlow) pentru sarcini necritice +4. Setați bugete de cost pentru fiecare cheie API: Tabloul de bord → Chei API → Buget + +--- + +## Depanare + +### Activați jurnalele de solicitări + +Setați `ENABLE_REQUEST_LOGS=true` în fișierul dvs. `.env`. Jurnalele apar în directorul `logs/`. + +### Verificați sănătatea furnizorului + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Spațiu de rulare + +- Stare principală: `${DATA_DIR}/db.json` (furnizori, combo-uri, aliasuri, chei, setări) +- Utilizare: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Jurnalele de solicitare: `/logs/...` (când `ENABLE_REQUEST_LOGS=true`) + +--- + +## Probleme cu întrerupătorul de circuit + +### Furnizor blocat în stare DESCHIS + +Când întrerupătorul unui furnizor este DESCHIS, cererile sunt blocate până la expirarea perioadei de răcire. + +**Remediere:** + +1. Accesați **Tabloul de bord → Setări → Reziliență** +2. Verificați cardul întreruptorului pentru furnizorul afectat +3. Faceți clic pe **Reset All** pentru a șterge toate întrerupătoarele sau așteptați ca perioada de răcire să expire +4. Verificați că furnizorul este efectiv disponibil înainte de resetare + +### Furnizorul continuă să declanșeze întrerupătorul + +Dacă un furnizor intră în mod repetat în starea DESCHIS: + +1. Verificați **Tabloul de bord → Sănătate → Sănătatea furnizorului** pentru modelul de eșec +2. Accesați **Setări → Reziliență → Profiluri furnizor** și creșteți pragul de eșec +3. Verificați dacă furnizorul a modificat limitele API sau dacă necesită re-autentificare +4. Examinați telemetria latenței — latența mare poate cauza eșecuri bazate pe timeout + +--- + +## Probleme cu transcrierea audio + +### Eroare „Model neacceptat”. + +- Asigurați-vă că utilizați prefixul corect: `deepgram/nova-3` sau `assemblyai/best` +- Verificați că furnizorul este conectat în **Tabloul de bord → Furnizori** + +### Transcrierea revine goală sau eșuează + +- Verificați formatele audio acceptate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Verificați că dimensiunea fișierului este în limitele furnizorului (de obicei < 25 MB) +- Verificați valabilitatea cheii API a furnizorului în cardul furnizorului + +--- + +## Depanare a traducătorului + +Utilizați **Tabloul de bord → Traducător** pentru a depana problemele de traducere de format: + +| Modul | Când să utilizați | +| ------------------- | ----------------------------------------------------------------------------------------------------------------- | +| **Teren de joacă** | Comparați formatele de intrare/ieșire una lângă alta — inserați o solicitare eșuată pentru a vedea cum se traduce | +| **Tester de chat** | Trimiteți mesaje live și inspectați întreaga sarcină de solicitare/răspuns, inclusiv antetele | +| **Banc de testare** | Rulați teste în loturi în combinații de formate pentru a afla ce traduceri sunt întrerupte | +| **Monitor live** | Urmăriți fluxul de solicitări în timp real pentru a detecta problemele intermitente de traducere | + +### Probleme frecvente de format + +- **Nu apar etichete de gândire** — Verificați dacă furnizorul țintă acceptă gândirea și setarea bugetului de gândire +- **Scăderea apelurilor de instrumente** — Unele traduceri în format pot elimina câmpurile neacceptate; verificați în modul Playground +- **Lipsește promptul de sistem** — Claude și Gemini gestionează prompturile în mod diferit; verificați rezultatul traducerii +- **SDK returnează șir brut în loc de obiect** — Remediat în v1.1.0: dezinfectantul de răspuns acum elimină câmpurile nestandard (`x_groq`, `usage_breakdown` etc.) care cauzează eșecuri de validare OpenAI SDK Pydantic +- **GLM/ERNIE respinge rolul `system`** — Remediat în v1.1.0: normalizatorul de roluri îmbină automat mesajele de sistem în mesajele utilizatorului pentru modele incompatibile +- **`developer` rol nerecunoscut** — Remediat în v1.1.0: convertit automat în `system` pentru furnizorii non-OpenAI +- **`json_schema` nu funcționează cu Gemini** — Remediat în v1.1.0: `response_format` este acum convertit în `responseMimeType` + `responseSchema` al lui Gemini + +--- + +## Setări de rezistență + +### Limita automată a ratei nu se declanșează + +- Limita automată a ratei se aplică numai furnizorilor de chei API (nu OAuth/abonament) +- Verificați că **Setări → Reziliență → Profiluri furnizorului** are limita de rata automată activată +- Verificați dacă furnizorul returnează codurile de stare `429` sau anteturile `Retry-After` + +### Reglarea retragerii exponențiale + +Profilurile furnizorilor acceptă aceste setări: + +- **Întârziere de bază** — Timp de așteptare inițial după prima defecțiune (implicit: 1s) +- **Întârziere maximă** — Limită maximă a timpului de așteptare (implicit: 30s) +- **Multiplicator** — Cât de mult se mărește întârzierea pentru fiecare defecțiune consecutivă (implicit: 2x) + +### Turma anti-tunet + +Când multe solicitări concurente ajung la un furnizor cu o rată limitată, OmniRoute folosește mutex + limitarea automată a ratei pentru a serializa cererile și a preveni eșecurile în cascadă. Acest lucru este automat pentru furnizorii de chei API. + +--- + +## Încă blocat? + +- **Probleme GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Arhitectură**: Consultați [**OMNI_TOKEN_55**](ARCHITECTURE.md) pentru detalii interne +- **Referință API**: Consultați [**OMNI_TOKEN_56**](API_REFERENCE.md) pentru toate punctele finale +- **Tabloul de bord pentru sănătate**: verificați **Tabloul de bord → Sănătate** pentru starea sistemului în timp real +- **Translator**: utilizați **Tabloul de bord → Translator** pentru a depana problemele de format diff --git a/docs/i18n/ro/USER_GUIDE.md b/docs/i18n/ro/USER_GUIDE.md new file mode 100644 index 0000000000..a3b8565386 --- /dev/null +++ b/docs/i18n/ro/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Ghidul utilizatorului + +🌐 **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) + +Ghid complet pentru configurarea furnizorilor, crearea combo-urilor, integrarea instrumentelor CLI și implementarea OmniRoute. + +--- + +## Cuprins + +- [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) + +--- + +## 💰 Prețurile dintr-o privire + +| Nivelul | Furnizor | Cost | Resetare cotă | Cel mai bun pentru | +| ---------------- | ----------------- | ------------------ | --------------------------- | ------------------------- | +| **💳 ABONARE** | Claude Code (Pro) | 20 USD/lună | 5h + săptămânal | Deja abonat | +| | Codex (Plus/Pro) | 20-200 USD/lună | 5h + săptămânal | Utilizatori OpenAI | +| | Gemeni CLI | **GRATIS** | 180K/lună + 1K/zi | Toată lumea! | +| | GitHub Copilot | 10-19 USD/lună | Lunar | utilizatorii GitHub | +| **🔑 CHEIA API** | DeepSeek | Plată pe utilizare | Niciuna | Raționament ieftin | +| | Groq | Plată pe utilizare | Niciuna | Inferență ultra-rapidă | +| | xAI (Grok) | Plată pe utilizare | Niciuna | Grok 4 raționament | +| | Mistral | Plată pe utilizare | Niciuna | Modele găzduite de UE | +| | Nedumerire | Plată pe utilizare | Niciuna | Căutare sporită | +| | Împreună AI | Plată pe utilizare | Niciuna | Modele open-source | +| | Artificii AI | Plată pe utilizare | Niciuna | Imagini Fast FLUX | +| | Cerebre | Plată pe utilizare | Niciuna | Viteza la scara plachetei | +| | Cohere | Plată pe utilizare | Niciuna | Comanda R+ RAG | +| | NVIDIA NIM | Plată pe utilizare | Niciuna | Modele de întreprindere | +| **💰 IEFTIN** | GLM-4.7 | 0,6 USD/1 milion | Zilnic 10:00 | Backup buget | +| | MiniMax M2.1 | 0,2 USD/1 milion | rulare de 5 ore | Cea mai ieftină opțiune | +| | Kimi K2 | 9 USD/lună plat | 10 milioane de jetoane/lună | Cost previzibil | +| **🆓 GRATUIT** | iFlow | $0 | Nelimitat | 8 modele gratuite | +| | Qwen | $0 | Nelimitat | 3 modele gratuite | +| | Kiro | $0 | Nelimitat | Claude liber | + +**💡 Sfat profesionist:** Începeți cu Gemini CLI (180K gratuit/lună) + iFlow (gratuit nelimitat) combo = cost 0 USD! + +--- + +## 🎯 Cazuri de utilizare + +### Cazul 1: „Am abonament Claude Pro” + +**Problemă:** Cota expiră neutilizată, limitele ratei în timpul codării grele + +``` +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 +``` + +### Cazul 2: „Vreau cost zero” + +**Problemă:** Nu-mi permit abonamente, au nevoie de codare AI de încredere + +``` +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 +``` + +### Cazul 3: „Am nevoie de codare 24/7, fără întreruperi” + +**Problemă:** Termenele limită, nu-mi permit timpi de nefuncționare + +``` +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) +``` + +### Cazul 4: „Vreau AI GRATUIT în OpenClaw” + +**Problemă:** Aveți nevoie de asistent AI în aplicațiile de mesagerie, complet gratuit + +``` +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... +``` + +--- + +## 📖 Configurarea furnizorului + +### 🔐 Furnizori de abonament + +#### Cod 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 +``` + +**Sfat profesionist:** Folosiți Opus pentru sarcini complexe, Sonnet pentru viteză. OmniRoute urmărește cota per model! + +#### 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 (GRATIS 180K/lună!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Cea mai bună valoare:** Nivel gratuit imens! Utilizați acest lucru înainte de nivelurile plătite. + +#### GitHub Copilot + +```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 +``` + +### 💰 Furnizori ieftini + +#### GLM-4.7 (Resetare zilnică, 0,6 USD/1 milion) + +1. Înscrieți-vă: [Zhipu AI](https://open.bigmodel.cn/) +2. Obțineți cheia API din Coding Plan +3. Tabloul de bord → Adăugați cheie API: Furnizor: `glm`, Cheie API: `your-key` + +**Utilizați:** `glm/glm-4.7` — **Sfat profesionist:** Planul de codare oferă cotă de 3 ori la 1/7 cost! Resetați zilnic la 10:00. + +#### MiniMax M2.1 (resetare în 5 ore, 0,20 USD/1 milion) + +1. Înscrieți-vă: [MiniMax](https://www.minimax.io/) +2. Obțineți cheia API → Tabloul de bord → Adăugați cheia API + +**Utilizați:** `minimax/MiniMax-M2.1` — **Sfat profesionist:** Cea mai ieftină opțiune pentru context lung (1 milion de jetoane)! + +#### Kimi K2 (9 USD/lună fix) + +1. Abonați-vă: [Moonshot AI](https://platform.moonshot.ai/) +2. Obțineți cheia API → Tabloul de bord → Adăugați cheia API + +**Utilizați:** `kimi/kimi-latest` — **Sfat pro:** Fix 9 USD/lună pentru 10 milioane de jetoane = 0,90 USD/1 milion cost efectiv! + +### 🆓 Furnizori GRATUITI + +#### iFlow (8 modele GRATUITE) + +```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 modele GRATUITE) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude GRATUIT) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨 Combo + +### Exemplul 1: Maximizați abonamentul → Backup ieftin + +``` +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 +``` + +### Exemplul 2: Numai gratuit (cost 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! +``` + +--- + +## 🔧 Integrare CLI + +### Cursor 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 Cod + +Editați `~/.claude/config.json`: + +```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 + +Editați `~/.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" }] + } + } + } +} +``` + +**Sau utilizați Dashboard:** CLI Tools → OpenClaw → Auto-config + +### Cline / Continuare / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Desfășurare + +### Implementare 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 +``` + +### 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 +``` + +Pentru modul integrat în gazdă cu binare CLI, consultați secțiunea Docker din documentele principale. + +### Variabile de mediu + +| Variabila | Implicit | Descriere | +| --------------------- | ------------------------------------ | -------------------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | Secret de semnare JWT (**schimbarea producției**) | +| `INITIAL_PASSWORD` | `123456` | Prima parolă de conectare | +| `DATA_DIR` | `~/.omniroute` | Director de date (db, utilizare, jurnale) | +| `PORT` | cadru implicit | Port de serviciu (`20128` în exemple) | +| `HOSTNAME` | cadru implicit | Leagă gazdă (Docker este implicit la `0.0.0.0`) | +| `NODE_ENV` | implicit de rulare | Setați `production` pentru implementare | +| `BASE_URL` | `http://localhost:20128` | Adresa URL de bază internă pe partea serverului | +| `CLOUD_URL` | `https://omniroute.dev` | Adresa URL de bază a punctului final de sincronizare în cloud | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Secret HMAC pentru cheile API generate | +| `REQUIRE_API_KEY` | `false` | Aplicați cheia API Bearer pe `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Activează jurnalele cereri/răspuns | +| `AUTH_COOKIE_SECURE` | `false` | Forțați cookie-ul de autentificare `Secure` (în spatele proxy-ului invers HTTPS) | + +Pentru referința completă a variabilei de mediu, consultați [README](../README.md). + +--- + +## 📊 Modele disponibile + +
+Vedeți toate modelele disponibile + +**Cod Claude (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` + +**CLI Gemini (`gc/`)** — GRATUIT: `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 USD/1 milion: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — 0,2 USD/1 milion: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** — GRATUIT: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` + +**Qwen (`qw/`)** — GRATUIT: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` + +**Kiro (`kr/`)** — GRATUIT: `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` + +**Perplexitate (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**Focuri de artificii AI (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Cerebre (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Funcții avansate + +### Modele personalizate + +Adăugați orice ID de model oricărui furnizor fără a aștepta o actualizare a aplicației: + +```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" +``` + +Sau utilizați Tabloul de bord: **Furnizori → [Furnizor] → Modele personalizate**. + +### Rute de furnizori dedicate + +Dirijați cererile direct către un anumit furnizor cu validarea modelului: + +```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 +``` + +Prefixul furnizorului este adăugat automat dacă lipsește. Modelele nepotrivite revin `400`. + +### Configurare proxy de rețea + +```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"}}' +``` + +**Precedență:** Specific cheie → Specific combo → Specific furnizor → Global → Mediu. + +### Model Catalog API + +```bash +curl http://localhost:20128/api/models/catalog +``` + +Returnează modele grupate după furnizor cu tipuri (`chat`, `embedding`, `image`). + +### Cloud Sync + +- Sincronizați furnizorii, combo-urile și setările pe dispozitive +- Sincronizare automată în fundal cu timeout + fail-rapid +- Prefer partea serverului `BASE_URL`/`CLOUD_URL` în producție + +### LLM Gateway Intelligence (Faza 9) + +- **Cache semantic** — Memorează automat în cache non-streaming, temperatură=0 răspunsuri (ocolire cu `X-OmniRoute-No-Cache: true`) +- **Solicitare Idempotency** — Deduplică cererile în 5s prin antetul \_\_OMNI_TOKEN_1 sau `X-Request-Id` +- **Urmărirea progresului** — Opt-in SSE `event: progress` evenimente prin antetul `X-OmniRoute-Progress: true` + +--- + +### Translator Playground + +Acces prin **Tabloul de bord → Translator**. Depanați și vizualizați modul în care OmniRoute traduce cererile API între furnizori. + +| Modul | Scop | +| ------------------- | ----------------------------------------------------------------------------------------------------- | +| **Teren de joacă** | Selectați formatele sursă/țintă, inserați o solicitare și vedeți instantaneu rezultatul tradus | +| **Tester de chat** | Trimiteți mesaje de chat live prin proxy și inspectați întregul ciclu de solicitare/răspuns | +| **Banc de testare** | Rulați teste în loturi în mai multe combinații de formate pentru a verifica corectitudinea traducerii | +| **Monitor live** | Urmăriți traducerile în timp real pe măsură ce solicitările curg prin proxy | + +**Cazuri de utilizare:** + +- Depanați de ce o anumită combinație client/furnizor eșuează +- Verificați dacă etichetele de gândire, apelurile de instrumente și instrucțiunile de sistem se traduc corect +- Comparați diferențele de format dintre formatele OpenAI, Claude, Gemini și Responses API + +--- + +### Strategii de rutare + +Configurați prin **Tablou de bord → Setări → Rutare**. + +| Strategie | Descriere | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **Umpleți mai întâi** | Utilizează conturile în ordine de prioritate — contul principal gestionează toate solicitările până când nu sunt disponibile | +| **Round Robin** | Parcurge toate conturile cu o limită stabilă configurabilă (implicit: 3 apeluri per cont) | +| **P2C (Puterea a două opțiuni)** | Alege 2 conturi aleatorii și rute către cel mai sănătos — echilibrează sarcina cu conștientizarea sănătății | +| **La întâmplare** | Selectează aleatoriu un cont pentru fiecare solicitare folosind Fisher-Yates shuffle | +| **Cel mai puțin folosit** | Rute către contul cu cea mai veche amprentă temporală `lastUsedAt`, distribuind traficul uniform | +| **Cost optimizat** | Rute către contul cu cea mai mică valoare de prioritate, optimizare pentru furnizorii cu cel mai mic cost | + +#### Aliasuri de model cu caractere wildcard + +Creați modele de metacară pentru a remapa numele modelelor: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +Wildcard-urile acceptă `*` (orice caractere) și `?` (un singur caracter). + +#### Lanțuri de rezervă + +Definiți lanțuri globale de rezervă care se aplică tuturor solicitărilor: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Reziliență și întrerupătoare de circuit + +Configurați prin **Tabloul de bord → Setări → Reziliență**. + +OmniRoute implementează rezistența la nivel de furnizor cu patru componente: + +1. **Profiluri de furnizor** — Configurație per furnizor pentru: + - Pragul de eșec (cate defecțiuni înainte de deschidere) + - Durata de răcire + - Sensibilitatea de detectare a limitei ratei + - Parametrii de backoff exponenţial + +2. **Limite de rată editabile** — Setări implicite la nivel de sistem configurabile în tabloul de bord: + - **Solicitări pe minut (RPM)** — Numărul maxim de solicitări pe minut per cont + - **Timp minim între solicitări** — Intervalul minim în milisecunde între solicitări + - **Max. de solicitări simultane** — Maxim de solicitări simultane per cont + - Faceți clic pe **Editați** pentru a modifica, apoi pe **Salvați** sau **Anulați**. Valorile persistă prin intermediul API-ului de rezistență. + +3. **Circuit Breaker** — Urmărește defecțiunile pentru fiecare furnizor și deschide automat circuitul când este atins un prag: + - **ÎNCHIS** (sănătos) — Solicitările curg normal + - **DESCHIS** — Furnizorul este blocat temporar după eșecuri repetate + - **HALF_OPEN** — Se testează dacă furnizorul și-a revenit + +4. **Politici și identificatori blocați** — Afișează starea întrerupătorului și identificatorii blocați cu capacitatea de deblocare forțată. + +5. **Detecție automată a limitei ratei** — Monitorizează anteturile `429` și `Retry-After` pentru a evita în mod proactiv atingerea limitelor ratei furnizorului. + +**Sfat profesionist:** Folosiți butonul **Reset All** pentru a șterge toate întreruptoarele de circuit și perioadele de răcire atunci când un furnizor își revine după o întrerupere. + +--- + +### Export/Import baze de date + +Gestionați copiile de rezervă ale bazei de date în **Tabloul de bord → Setări → Sistem și stocare**. + +| Acțiune | Descriere | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Exportați baza de date** | Descarcă baza de date SQLite curentă ca fișier `.sqlite` | +| **Exportați toate (.tar.gz)** | Descărcă o arhivă de rezervă completă, inclusiv: bază de date, setări, combinații, conexiuni la furnizor (fără acreditări), metadatele cheii API | +| **Importă baza de date** | Încărcați un fișier `.sqlite` pentru a înlocui baza de date curentă. O copie de rezervă pre-import este creată automat | + +```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" +``` + +**Validare import:** Fișierul importat este validat pentru integritate (verificare pragma SQLite), tabelele necesare (`provider_connections`, `provider_nodes`, `combos`, `api_keys`) și dimensiune (max. 100 MB). + +**Cazuri de utilizare:** + +- Migrați OmniRoute între mașini +- Creați copii de rezervă externe pentru recuperarea în caz de dezastru +- Partajați configurațiile între membrii echipei (exportați toate → partajați arhiva) + +--- + +### Tabloul de bord pentru setări + +Pagina de setări este organizată în 5 file pentru o navigare ușoară: + +| Tab | Cuprins | +| -------------- | ----------------------------------------------------------------------------------------------------------------------- | +| **Securitate** | Setări de conectare/parolă, control acces IP, autentificare API pentru `/models` și blocare furnizor | +| **Dirutare** | Strategie globală de rutare (6 opțiuni), aliasuri de model cu wildcard, lanțuri de rezervă, valori implicite combo | +| **Reziliență** | Profilurile furnizorilor, limitele de rată modificabile, starea întrerupătorului, politicile și identificatorii blocați | +| **AI** | Gândire la configurația bugetului, injectarea promptă a sistemului global, statisticile cache prompte | +| **Avansat** | Configurație globală proxy (HTTP/SOCKS5) | + +--- + +### Costuri și management bugetar + +Acces prin **Tabloul de bord → Costuri**. + +| Tab | Scop | +| ----------- | ------------------------------------------------------------------------------------------------------------------ | +| **Buget** | Setați limite de cheltuieli pentru fiecare cheie API cu bugete zilnice/săptămânale/lunare și urmărire în timp real | +| **Prețuri** | Vizualizați și editați intrările de prețuri ale modelului — cost pe 1K jetonuri de intrare/ieșire per furnizor | + +```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 +``` + +**Urmărirea costurilor:** Fiecare solicitare înregistrează utilizarea simbolurilor și calculează costul utilizând tabelul de prețuri. Vedeți defalcări în **Tabloul de bord → Utilizare** în funcție de furnizor, model și cheie API. + +--- + +### Transcriere audio + +OmniRoute acceptă transcrierea audio prin punctul final compatibil cu 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" +``` + +Furnizori disponibili: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Formate audio acceptate: `mp3`, `wav`, `m4a`, `flac`, `ogg`, **OMNI_TOKEN**14. + +--- + +### Strategii de echilibrare combinate + +Configurați echilibrarea per-combo în **Tabloul de bord → Combo → Creare/Editare → Strategie**. + +| Strategie | Descriere | +| ----------------------------------------------- | ------------------------------------------------------------------------------------- | +| **Round-Robin** | Se rotește succesiv prin modele | +| **Prioritate** | Încearcă întotdeauna primul model; cade înapoi numai pe eroare | +| **La întâmplare** | Alege un model aleatoriu din combo pentru fiecare cerere | +| **Ponderat** | Rute proporționale pe baza greutăților atribuite per model | +| **Cel mai puțin folosit** | Rute către modelul cu cele mai puține solicitări recente (folosește valori combinate) | +| **Optimizat din punct de vedere al costurilor** | Rute către cel mai ieftin model disponibil (folosește tabelul de prețuri) | + +Valorile implicite globale ale combo pot fi setate în **Tabloul de bord → Setări → Rutare → Setări implicite combo**. + +--- + +### Tabloul de bord pentru sănătate + +Acces prin **Tabloul de bord → Sănătate**. Prezentare generală a stării sistemului în timp real cu 6 carduri: + +| Card | Ce arată | +| -------------------------- | ------------------------------------------------------------------------------- | +| **Stare sistem** | Uptime, versiune, utilizare a memoriei, director de date | +| **Sănătatea furnizorului** | Stare întrerupător pentru fiecare furnizor (Închis/Deschis/Pe jumătate deschis) | +| **Limite de rate** | Reduceri de reducere a limitei ratei active per cont cu timpul rămas | +| **Blocari active** | Furnizori blocați temporar de politica de blocare | +| **Cache pentru semnături** | Statistici cache de deduplicare (chei active, rata de accesare) | +| **Telemetrie de latență** | agregarea latenței p50/p95/p99 per furnizor | + +**Sfat profesional:** Pagina Sănătate se reîmprospătează automat la fiecare 10 secunde. Utilizați cardul de întrerupător pentru a identifica furnizorii care se confruntă cu probleme. diff --git a/docs/i18n/ru/API_REFERENCE.md b/docs/i18n/ru/API_REFERENCE.md new file mode 100644 index 0000000000..0c1643e7ca --- /dev/null +++ b/docs/i18n/ru/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) + +Полный справочник по всем конечным точкам API OmniRoute. + +--- + +## Содержание + +- [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` | Запрос | Ключ дедупликации (окно 5s) | +| `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, Together 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), Together 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` | ОпенАИ | +| ПОСТ | `/v1/messages` | Антропный | +| ПОСТ | `/v1/responses` | Ответы OpenAI | +| ПОСТ | `/v1/embeddings` | ОпенАИ | +| ПОСТ | `/v1/images/generations` | ОпенАИ | +| ПОЛУЧИТЬ | `/v1/models` | ОпенАИ | +| ПОСТ | `/v1/messages/count_tokens` | Антропный | +| ПОЛУЧИТЬ | `/v1beta/models` | Близнецы | +| ПОСТ | `/v1beta/models/{...path}` | Близнецы создают контент | +| ПОСТ | `/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` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Переключить требуется вход | + +### Управление поставщиками + +| Конечная точка | Метод | Описание | +| ---------------------------- | -------------------------- | --------------------------------- | +| `/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` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Общие настройки | +| `/api/settings/proxy` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Конфигурация сетевого прокси | +| `/api/settings/proxy/test` | ПОСТ | Проверить прокси-соединение | +| `/api/settings/ip-filter` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Список разрешенных/блокированных IP-адресов | +| `/api/settings/thinking-budget` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Обоснование бюджета жетона | +| `/api/settings/system-prompt` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Глобальная системная подсказка | + +### Мониторинг + +| Конечная точка | Метод | Описание | +| ------------------------ | ---------------- | --------------------------------------- | +| `/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` | ПОЛУЧИТЬ | Статус 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` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Получить/обновить профили устойчивости | +| `/api/resilience/reset` | ПОСТ | Сброс автоматических выключателей | +| `/api/rate-limits` | ПОЛУЧИТЬ | Статус ограничения ставки для каждого аккаунта | +| `/api/rate-limit` | ПОЛУЧИТЬ | Конфигурация глобального ограничения скорости | + +### Оценки + +| Конечная точка | Метод | Описание | +| -------------- | ------------------ | ----------------------------------------------- | +| `/api/evals` | ПОЛУЧИТЬ/ОТПРАВИТЬ | Получение списка пакетов оценки / запуск оценки | + +### Политики + +| Конечная точка | Метод | Описание | +| --------------- | -------------------------- | ----------------------------------- | +| `/api/policies` | ПОЛУЧИТЬ/ОТПРАВИТЬ/УДАЛИТЬ | Управление политиками маршрутизации | + +### Соответствие + +| Конечная точка | Метод | Описание | +| --------------------------- | -------- | ---------------------------------------- | +| `/api/compliance/audit-log` | ПОЛУЧИТЬ | Журнал аудита соответствия (последний N) | + +### v1beta (совместимость с Близнецами) + +| Конечная точка | Метод | Описание | +| -------------------------- | -------- | --------------------------------------- | +| `/v1beta/models` | ПОЛУЧИТЬ | Список моделей в формате Gemini | +| `/v1beta/models/{...path}` | ПОСТ | Конечная точка Gemini `generateContent` | + +Эти конечные точки отражают формат API Gemini для клиентов, которым требуется встроенная совместимость с Gemini SDK. + +### Внутренние/системные 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`. + +--- + +## Совместимость с Олламой + +Для клиентов, использующих формат API Ollama: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +Запросы автоматически переводятся между Олламой и внутренними форматами. + +--- + +## Телеметрия + +```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. Учетные данные, выбранные из локальной базы данных с фильтрацией доступности учетной записи. +5. Для чата: `handleChatCore` — определение формата, трансляция, проверка кеша, проверка идемпотентности +6. Исполнитель провайдера отправляет восходящий запрос. +7. Ответ переводится обратно в формат клиента (чат) или возвращается в исходном виде (встраивания/изображения/аудио). +8. Запись использования/регистрации +9. Резервный вариант применяется при ошибках в соответствии с правилами комбо. + +Полная ссылка на архитектуру: [**OMNI_TOKEN_119**](ARCHITECTURE.md). + +--- + +## Аутентификация + +- Маршруты информационной панели (`/dashboard/*`) используют файл cookie `auth_token`. +- Для входа используется сохраненный хеш пароля; возврат к `INITIAL_PASSWORD` +- `requireLogin` переключается через `/api/settings/require-login` +- Маршруты `/v1/*` дополнительно требуют ключ API носителя, когда `REQUIRE_API_KEY=true` diff --git a/docs/i18n/ru/ARCHITECTURE.md b/docs/i18n/ru/ARCHITECTURE.md new file mode 100644 index 0000000000..a3d5f9bb79 --- /dev/null +++ b/docs/i18n/ru/ARCHITECTURE.md @@ -0,0 +1,782 @@ +# Архитектура 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) + +_Последнее обновление: 18 февраля 2026 г._ + +## Резюме + +OmniRoute — это локальный шлюз и панель маршрутизации AI, созданные на основе Next.js. +Он предоставляет единую конечную точку, совместимую с OpenAI (`/v1/*`), и маршрутизирует трафик между несколькими вышестоящими поставщиками с трансляцией, резервным копированием, обновлением токена и отслеживанием использования. + +Основные возможности: + +- OpenAI-совместимая поверхность API для CLI/инструментов (28 поставщиков) +- Трансляция запроса/ответа в форматах провайдера. +- Резервный вариант комбо-модели (последовательность из нескольких моделей) +- Резервный вариант на уровне учетной записи (несколько учетных записей для каждого провайдера) +- Управление подключением к поставщику OAuth + API-ключей +- Генерация встраивания через `/v1/embeddings` (6 провайдеров, 9 моделей) +- Генерация изображения через `/v1/images/generations` (4 провайдера, 9 моделей) +- Подумайте о разборе тегов (`...`) для моделей рассуждений. +- Очистка ответов для строгой совместимости OpenAI SDK. +- Нормализация ролей (разработчик→система, система→пользователь) для совместимости между поставщиками. +- Преобразование структурированного вывода (json_schema → Gemini responseSchema) +- Локальное сохранение поставщиков, ключей, псевдонимов, комбинаций, настроек, цен. +- Отслеживание использования/расходов и регистрация запросов +- Дополнительная облачная синхронизация для синхронизации нескольких устройств/состояний. +- Список разрешенных/блокированных IP-адресов для контроля доступа к API. +- Продуманное управление бюджетом (сквозное/автоматическое/настраиваемое/адаптивное) +- Оперативное внедрение глобальной системы +- Отслеживание сеансов и снятие отпечатков пальцев +- Расширенное ограничение скорости для каждой учетной записи с помощью профилей для конкретного поставщика. +- Схема автоматического выключателя для устойчивости поставщика +- Анти-громовая защита стада с блокировкой мьютекса +- Кэш дедупликации запросов на основе сигнатур. +- Уровень домена: доступность модели, правила затрат, резервная политика, политика блокировки. +- Сохранение состояния домена (кэш сквозной записи SQLite для резервных копий, бюджетов, блокировок, автоматических выключателей) +- Механизм политики для централизованной оценки запросов (блокировка → бюджет → резервный вариант) +- Запрос телеметрии с агрегацией задержек p50/p95/p99. +- Идентификатор корреляции (X-Request-Id) для сквозной трассировки. +- Ведение журнала аудита соответствия с возможностью отказа для каждого ключа API. +- Система оценки для обеспечения качества LLM +- Панель управления устойчивостью пользовательского интерфейса с отображением состояния автоматического выключателя в реальном времени. +- Модульные поставщики OAuth (12 отдельных модулей под `src/lib/oauth/providers/`) + +Основная модель времени выполнения: + +- Маршруты приложений Next.js в `src/app/api/*` реализуют как API панели мониторинга, так и API совместимости. +- Общее ядро SSE/маршрутизации в `src/sse/*` + `open-sse/*` управляет выполнением поставщика, трансляцией, потоковой передачей, резервным копированием и использованием. + +## Область применения и границы + +### В объеме + +- Среда выполнения локального шлюза +- API-интерфейсы управления информационной панелью +- Аутентификация поставщика и обновление токена +- Запросить перевод и потоковую передачу SSE +- Локальное состояние + постоянство использования +- Дополнительная оркестровка облачной синхронизации. + +### Выходит за рамки + +- Реализация облачного сервиса на базе `NEXT_PUBLIC_CLOUD_URL`. +- Соглашение об уровне обслуживания поставщика/плоскость управления вне локального процесса. +- Сами внешние двоичные файлы 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` — генерация изображений (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) +- Оценки: `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` +- Идентификатор запроса: `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 (12 отдельных файлов под `src/lib/oauth/providers/`): + +- Индекс реестра: `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) Уровень сохранения + +Первичное состояние БД: + +- `src/lib/localDb.ts` +- файл: `${DATA_DIR}/db.json` (или `$XDG_CONFIG_HOME/omniroute/db.json`, если установлен, иначе `~/.omniroute/db.json`) +- сущности: поставщики Connections, поставщикNodes, modelAliases, комбо, apiKeys, настройки, цены, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Использование БД: + +- `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` + +БД состояний домена (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) Поверхности аутентификации и безопасности + +– Аутентификация файлов 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 +``` + +Обновление во время живого трафика выполняется внутри `open-sse/handlers/chatCore.ts` через исполнителя `refreshCredentials()`. + +## Жизненный цикл облачной синхронизации (включить/синхронизировать/отключить) + +```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`: история использования и журналы повторяющихся запросов. + +## Покрытие поставщика-исполнителя (шаблон стратегии) + +У каждого поставщика есть специализированный исполнитель, расширяющий `BaseExecutor` (в `open-sse/executors/base.ts`), который обеспечивает построение URL-адреса, построение заголовка, повторную попытку с экспоненциальной отсрочкой, перехватчики обновления учетных данных и метод оркестрации `execute()`. + +| Исполнитель | Поставщик(и) | Специальная обработка | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Динамическая конфигурация URL/заголовка для каждого провайдера | +| `AntigravityExecutor` | Google Антигравитация | Пользовательские идентификаторы проекта/сеанса, повторная попытка после анализа | +| `CodexExecutor` | Кодекс OpenAI | Вводит системные инструкции, заставляет мыслить | +| `CursorExecutor` | Курсор IDE | Протокол ConnectRPC, кодировка Protobuf, подпись запроса через контрольную сумму | +| `GithubExecutor` | Второй пилот GitHub | Обновление токена Copilot, заголовки, имитирующие VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Киро | Бинарный формат AWS EventStream → Преобразование SSE | +| `GeminiCLIExecutor` | Близнецы CLI | Цикл обновления токена Google OAuth | + +Все остальные поставщики (включая пользовательские совместимые узлы) используют `DefaultExecutor`. + +## Матрица совместимости поставщиков + +| Провайдер | Формат | Авторизация | Поток | Непоток | Обновление токена | API использования | +| ------------------- | -------------- | ---------------------------------- | ----------------- | ------- | ----------------- | ---------------------------- | +| Клод | Клод | Ключ API / OAuth | ✅ | ✅ | ✅ | ⚠️ Только администратор | +| Близнецы | близнецы | Ключ API / OAuth | ✅ | ✅ | ✅ | ⚠️ Облачная консоль | +| Близнецы CLI | Близнецы-кли | ОАутент | ✅ | ✅ | ✅ | ⚠️ Облачная консоль | +| Антигравитация | антигравитация | ОАутент | ✅ | ✅ | ✅ | ✅ API с полной квотой | +| ОпенАИ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Кодекс | openai-ответы | ОАутент | ✅ принудительный | ❌ | ✅ | ✅ Ограничения ставок | +| Второй пилот GitHub | опенай | OAuth + токен второго пилота | ✅ | ✅ | ✅ | ✅ Снимки квот | +| Курсор | курсор | Пользовательская контрольная сумма | ✅ | ✅ | ❌ | ❌ | +| Киро | Киро | AWS SSO OIDC | ✅ (EventStream) | ❌ | ✅ | ✅ Ограничения использования | +| Квен | опенай | ОАутент | ✅ | ✅ | ✅ | ⚠️ По запросу | +| iFlow | опенай | OAuth (базовый) | ✅ | ✅ | ✅ | ⚠️ По запросу | +| OpenRouter | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| ГЛМ/Кими/МиниМакс | Клод | API-ключ | ✅ | ✅ | ❌ | ❌ | +| ДипСик | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Грок | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| xAI (Грок) | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Мистраль | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Растерянность | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Вместе ИИ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Фейерверк ИИ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Церебра | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| Согласовано | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | +| NVIDIA НИМ | опенай | API-ключ | ✅ | ✅ | ❌ | ❌ | + +## Охват перевода формата + +Обнаруженные исходные форматы включают: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Целевые форматы включают: + +- Чат OpenAI/Ответы +- Клод +- Оболочка Gemini/Gemini-CLI/Антигравитация +- Киро +- Курсор + +В переводах используется **OpenAI в качестве хаб-формата** — все преобразования проходят через OpenAI как промежуточный формат: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +Переводы выбираются динамически на основе формы исходной полезной нагрузки и целевого формата поставщика. + +Дополнительные уровни обработки в конвейере перевода: + +- **Обеззараживание ответов** — удаляет нестандартные поля из ответов формата OpenAI (как потоковых, так и непотоковых) для обеспечения строгого соответствия SDK. +- **Нормализация ролей** — преобразует `developer` → `system` для целей, отличных от OpenAI; объединяет `system` → `user` для моделей, отвергающих системную роль (GLM, ERNIE) +- **Извлечение тегов** — анализирует блоки `...` из содержимого в поле `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 — пинги прогрева, извлечение заголовков и подсчет токенов — и возвращает **поддельный ответ** без использования токенов вышестоящего поставщика. Это срабатывает только тогда, когда `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) Целостность данных + +- Миграция/восстановление формы БД для отсутствующих ключей. +- повреждены средства защиты сброса JSON для localDb и useDb. + +## Наблюдаемость и оперативные сигналы + +Источники видимости во время выполнения: + +- логи консоли от `src/sse/utils/logger.ts` +- агрегаты использования по запросу в `usage.json` +- журнал статуса текстового запроса в `log.txt` +- дополнительные журналы глубоких запросов/трансляций под `logs/`, когда `ENABLE_REQUEST_LOGS=true` +- конечные точки использования информационной панели (`/api/usage/*`) для использования пользовательского интерфейса. + +## Границы, чувствительные к безопасности + +- Секрет JWT (`JWT_SECRET`) обеспечивает проверку/подпись файлов cookie сеанса информационной панели. +- Первоначальный резервный пароль (`INITIAL_PASSWORD`, по умолчанию `123456`) должен быть переопределен в реальных развертываниях. +- Секрет HMAC ключа API (`API_KEY_SECRET`) защищает сгенерированный формат локального ключа API. +- Секреты поставщика (ключи/токены API) сохраняются в локальной базе данных и должны быть защищены на уровне файловой системы. +- Конечные точки облачной синхронизации полагаются на аутентификацию по ключу API + семантику идентификатора машины. + +## Матрица среды и времени выполнения + +Переменные среды, активно используемые кодом: + +- Приложение/авторизация: `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` +- Целевой базовый URL-адрес CLI должен быть `http://:20128/v1`, когда `PORT=20128`. diff --git a/docs/i18n/ru/CODEBASE_DOCUMENTATION.md b/docs/i18n/ru/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..16f253f574 --- /dev/null +++ b/docs/i18n/ru/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# 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) + +> Подробное руководство для начинающих по **omniroute** прокси-маршрутизатору с искусственным интеллектом, работающим от нескольких поставщиков. + +--- + +## 1. Что такое омнирут? + +omniroute — это **прокси-маршрутизатор**, который находится между клиентами ИИ (Claude CLI, Codex, Cursor IDE и т. д.) и поставщиками ИИ (Anthropic, Google, OpenAI, AWS, GitHub и т. д.). Это решает одну большую проблему: + +> **Различные клиенты ИИ говорят на разных «языках» (форматах API), и разные поставщики ИИ тоже ожидают разных «языков».** omniroute автоматически переводит между ними. + +Думайте об этом как об универсальном переводчике в Организации Объединенных Наций: любой делегат может говорить на любом языке, а переводчик переводит его для любого другого делегата. + +--- + +## 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²** (каждая пара). + +--- + +## 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` | «Мыслящие» подписи по умолчанию для моделей Claude и Gemini. | +| `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` | — | Абстрактная база: построение URL-адресов, заголовки, логика повторов, обновление учетных данных | +| `default.ts` | Клод, Близнецы, OpenAI, GLM, Кими, МиниМакс | Обновление общего токена OAuth для стандартных поставщиков | +| `antigravity.ts` | Облачный код Google | Генерация идентификатора проекта/сеанса, резервное копирование нескольких URL-адресов, настраиваемый повторный анализ сообщений об ошибках («сброс через 2 часа 7 минут 23 секунды») | +| `cursor.ts` | Курсор IDE | **Самое сложное**: проверка подлинности по контрольной сумме SHA-256, кодирование запроса Protobuf, двоичный поток событий → анализ ответа SSE | +| `codex.ts` | Кодекс OpenAI | Вводит системные инструкции, управляет уровнями мышления, удаляет неподдерживаемые параметры | +| `gemini-cli.ts` | Интерфейс командной строки Google Gemini | Создание собственного 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` | Адаптер для API ответов OpenAI: преобразует формат ответов → Завершения чата → отправляет в `chatCore` → преобразует SSE обратно в формат ответов. | +| `embeddings.ts` | Обработчик генерации внедрения: разрешает модель внедрения → поставщик, отправляет в API поставщика, возвращает ответ на внедрение, совместимый с OpenAI. Поддерживает 6+ провайдеров. | +| `imageGeneration.ts` | Обработчик генерации изображений: определяет модель изображения → поставщик, поддерживает режимы OpenAI-совместимый, Gemini-image (Антигравитация) и резервный режим (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 (включая эвристику `max_tokens` для Claude). А также: построение 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). Включает в себя кэш дедупликации обещаний в реальном времени и повторные попытки с экспоненциальной задержкой. | +| `combo.ts` | **Комбо-модели**: цепочки резервных моделей. Если модель A дает сбой из-за ошибки, допускающей возврат, попробуйте модель B, затем C и т. д. Возвращает фактические коды состояния восходящего потока. | +| `usage.ts` | Извлекает данные о квотах/использовании из API-интерфейсов провайдера (квоты GitHub Copilot, квоты модели Antigravity, ограничения скорости Кодекса, разбивка использования Kiro, настройки Claude). | +| `accountSelector.ts` | Интеллектуальный выбор учетной записи с алгоритмом оценки: учитывает приоритет, состояние здоровья, позицию циклического перебора и состояние перезарядки, чтобы выбрать оптимальную учетную запись для каждого запроса. | +| `contextManager.ts` | Управление жизненным циклом контекста запроса: создает и отслеживает объекты контекста каждого запроса с метаданными (идентификатор запроса, временные метки, информация о поставщике) для отладки и журналирования. | +| `ipFilter.ts` | Контроль доступа на основе IP: поддерживает режимы белого и черного списка. Проверяет IP-адрес клиента на соответствие настроенным правилам перед обработкой запросов API. | +| `sessionManager.ts` | Отслеживание сеансов с помощью снятия отпечатков пальцев клиентов: отслеживает активные сеансы с использованием хешированных идентификаторов клиентов, отслеживает количество запросов и предоставляет метрики сеансов. | +| `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` (генерация идентификатора, вставка отсутствующего ответа), `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** — основной конвейер потоковой передачи. Два режима: `TRANSLATE` (полноформатный перевод) и `PASSTHROUGH` (нормализация + использование извлечения). Управляет буферизацией фрагментов, оценкой использования, отслеживанием длины контента. Экземпляры попоточного кодировщика/декодера избегают общего состояния. | +| `streamHelpers.ts` | Утилиты SSE низкого уровня: `parseSSELine` (толерантный к пробелам), `hasValuableContent` (фильтрует пустые фрагменты для OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (сериализация SSE с учетом формата с очисткой `perf_metrics`). | +| `usageTracking.ts` | Извлечение использования токенов из любого формата (Claude/OpenAI/Gemini/Responses), оценка с помощью отдельных соотношений инструмента/сообщения на токен, добавление буфера (запас безопасности 2000 токенов), фильтрация полей для конкретного формата, ведение журнала консоли с цветами ANSI. | +| `requestLogger.ts` | Ведение журнала запросов на основе файлов (согласие через `ENABLE_REQUEST_LOGS=true`). Создает папки сеансов с пронумерованными файлами: `1_req_client.json` → `7_res_client.txt`. Весь ввод-вывод является асинхронным (выстрелил и забыл). Маскирует чувствительные заголовки. | +| `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/` | Веб-интерфейс, маршруты API, промежуточное ПО Express, обработчики обратного вызова OAuth | +| `src/lib/` | Доступ к базе данных (`localDb.ts`, `usageDb.ts`), аутентификация, общий доступ | +| `src/mitm/` | Прокси-утилиты «Человек посередине» для перехвата трафика провайдера | +| `src/models/` | Определения модели базы данных | +| `src/shared/` | Обертки вокруг функций open-sse (поставщик, поток, ошибка и т. д.) | +| `src/sse/` | Обработчики конечных точек SSE, которые подключают библиотеку open-sse к маршрутам Express | +| `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` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Управление списком разрешенных/черных IP-адресов | +| `/api/settings/thinking-budget` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Конфигурация бюджета токена обоснования (сквозной/автоматический/пользовательский/адаптивный) | +| `/api/settings/system-prompt` | ПОЛУЧИТЬ/ПОСТАВИТЬ | Глобальная система быстрого внедрения для всех запросов | +| `/api/sessions` | ПОЛУЧИТЬ | Отслеживание активных сессий и метрики | +| `/api/rate-limits` | ПОЛУЧИТЬ | Статус ограничения ставки для каждого аккаунта | + +--- + +## 5. Ключевые шаблоны проектирования + +### 5.1 Координатный перевод + +Все форматы преобразуются через **формат OpenAI в качестве концентратора**. Для добавления нового провайдера требуется написать только **одну пару** трансляторов (в/из OpenAI), а не N пар. + +### 5.2 Шаблон стратегии исполнителя + +У каждого поставщика есть выделенный класс исполнителя, унаследованный от `BaseExecutor`. Фабрика в `executors/index.ts` выбирает правильный вариант во время выполнения. + +### 5.3 Система саморегистрации плагинов + +Модули переводчика регистрируются при импорте через `register()`. Добавление нового переводчика — это просто создание файла и его импорт. + +### 5.4 Резервный аккаунт с экспоненциальным откатом + +Когда провайдер возвращает 429/401/500, система может переключиться на следующую учетную запись, применяя экспоненциальное время восстановления (1 с → 2 с → 4 с → максимум 2 минуты). + +### 5.5 Цепочки комбо-моделей + +«Комбо» группирует несколько строк `provider/model`. Если первое не удалось, автоматически переходите к следующему. + +### 5.6 Потоковая трансляция с сохранением состояния + +Трансляция ответов поддерживает состояние блоков SSE (отслеживание мыслительных блоков, накопление вызовов инструментов, индексирование блоков контента) с помощью механизма `initState()`. + +### 5.7 Использование буфера безопасности + +К сообщаемому использованию добавляется буфер на 2000 токенов, чтобы клиенты не превышали ограничения контекстного окна из-за накладных расходов на системные подсказки и преобразование формата. + +--- + +## 6. Поддерживаемые форматы + +| Формат | Направление | Идентификатор | +| ---------------------------------------- | --------------- | ------------------ | +| Завершения чата OpenAI | источник + цель | `openai` | +| API ответов OpenAI | источник + цель | `openai-responses` | +| Антропный Клод | источник + цель | `claude` | +| Google Близнецы | источник + цель | `gemini` | +| Интерфейс командной строки Google Gemini | только цель | `gemini-cli` | +| Антигравитация | источник + цель | `antigravity` | +| AWS Киро | только цель | `kiro` | +| Курсор | только цель | `cursor` | + +--- + +## 7. Поддерживаемые провайдеры + +| Провайдер | Метод аутентификации | Исполнитель | Ключевые примечания | +| ---------------------------------------- | -------------------------- | -------------- | ------------------------------------------------------------------------ | +| Антропный Клод | Ключ API или OAuth | По умолчанию | Использует заголовок `x-api-key` | +| Google Близнецы | Ключ API или OAuth | По умолчанию | Использует заголовок `x-goog-api-key` | +| Интерфейс командной строки Google Gemini | ОАутент | БлизнецыCLI | Использует конечную точку `streamGenerateContent` | +| Антигравитация | ОАутент | Антигравитация | Резервный вариант нескольких URL-адресов, индивидуальный анализ повторов | +| ОпенАИ | API-ключ | По умолчанию | Проверка подлинности стандартного носителя | +| Кодекс | ОАутент | Кодекс | Вводит системные инструкции, управляет мышлением | +| Второй пилот GitHub | OAuth + токен Copilot | Гитхаб | Двойной токен, имитация заголовка VSCode | +| Киро (AWS) | AWS SSO OIDC или Social | Киро | Анализ двоичного потока событий | +| Курсор IDE | Проверка контрольной суммы | Курсор | Кодирование Protobuf, контрольные суммы SHA-256 | +| Квен | ОАутент | По умолчанию | Стандартная аутентификация | +| iFlow | OAuth (базовый + носитель) | По умолчанию | Заголовок двойной аутентификации | +| OpenRouter | API-ключ | По умолчанию | Проверка подлинности стандартного носителя | +| ГЛМ, Кими, МиниМакс | API-ключ | По умолчанию | Совместимость с Claude, используйте `x-api-key` | +| `openai-compatible-*` | API-ключ | По умолчанию | Динамический: любая конечная точка, совместимая с OpenAI | +| `anthropic-compatible-*` | API-ключ | По умолчанию | Динамический: любая конечная точка, совместимая с Claude | + +--- + +## 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/ru/FEATURES.md b/docs/i18n/ru/FEATURES.md new file mode 100644 index 0000000000..9d070fec4b --- /dev/null +++ b/docs/i18n/ru/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. + +--- + +## 🔌 Провайдеры + +Управляйте соединениями с поставщиками ИИ: поставщиками OAuth (Claude Code, Codex, Gemini CLI), поставщиками ключей API (Groq, DeepSeek, OpenRouter) и бесплатными поставщиками (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨 Комбо + +Создавайте комбинации маршрутизации моделей с помощью шести стратегий: «сначала заполнить», «циклический», «степень двух вариантов», «случайный», «наименее используемый» и «оптимизированный по затратам». Каждая комбинация объединяет несколько моделей с автоматическим возвратом. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Аналитика + +Комплексная аналитика использования с использованием токенов, оценками затрат, тепловыми картами активности, еженедельными диаграммами распределения и разбивкой по каждому провайдеру. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Состояние системы + +Мониторинг в режиме реального времени: время безотказной работы, память, версия, процентили задержки (p50/p95/p99), статистика кэша и состояния автоматического выключателя поставщика. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Игровая площадка переводчика + +Четыре режима отладки переводов API: **Игровая площадка** (конвертер форматов), **Тестер чата** (живые запросы), **Тестовый стенд** (пакетные тесты) и **Живой монитор** (поток в реальном времени). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Настройки + +Общие настройки, системное хранилище, управление резервным копированием (экспорт/импорт базы данных), внешний вид (темный/светлый режим), безопасность (включая защиту конечных точек API и блокировку настраиваемых провайдеров), маршрутизация, устойчивость и расширенная настройка. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Инструменты CLI + +Конфигурация инструментов искусственного кодирования одним щелчком мыши: 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/ru/TROUBLESHOOTING.md b/docs/i18n/ru/TROUBLESHOOTING.md new file mode 100644 index 0000000000..6bb2da47e7 --- /dev/null +++ b/docs/i18n/ru/TROUBLESHOOTING.md @@ -0,0 +1,219 @@ +# Устранение неполадок + +🌐 **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. + +--- + +## Быстрые исправления + +| Проблема | Решение | +| --------------------------------------------- | ------------------------------------------------------------------------------ | +| Первый вход в систему не работает | Проверьте `INITIAL_PASSWORD` в `.env` (по умолчанию: `123456`) | +| Панель управления открывается не на тот порт | Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Никакие запросы не регистрируются под `logs/` | Установите `ENABLE_REQUEST_LOGS=true` | +| EACCES: в разрешении отказано | Установите `DATA_DIR=/path/to/writable/dir` для переопределения `~/.omniroute` | +| Стратегия маршрутизации не сохраняется | Обновление до версии 1.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'...` на конечной точке облака для вызовов без потоковой передачи. + +**Причина:** Восходящий поток возвращает полезные данные SSE, хотя клиент ожидает JSON. + +**Решение:** используйте `stream=true` для прямых вызовов из облака. Локальная среда выполнения включает резервный вариант SSE→JSON. + +### Облако сообщает о подключении, но «неверный ключ API» + +1. Создайте новый ключ на локальной панели управления (`/api/keys`). +2. Запустите облачную синхронизацию: Включить «Облако» → «Синхронизировать сейчас». +3. Старые/несинхронизированные ключи по-прежнему могут возвращать `401` в облаке. + +--- + +## Проблемы с докером + +### Инструмент 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 → Бюджет. + +--- + +## Отладка + +### Включить журналы запросов + +Установите `ENABLE_REQUEST_LOGS=true` в файле `.env`. Журналы отображаются в каталоге `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 + +Когда автоматический выключатель провайдера разомкнут, запросы блокируются до истечения времени восстановления. + +**Исправлено:** + +1. Перейдите в **Панель управления → Настройки → Устойчивость**. +2. Проверьте карту автоматического выключателя соответствующего поставщика. +3. Нажмите **Сбросить все**, чтобы очистить все выключатели, или подождите, пока истечет время восстановления. +4. Перед сбросом убедитесь, что поставщик действительно доступен. + +### Поставщик продолжает отключать автоматический выключатель + +Если провайдер неоднократно переходит в состояние OPEN: + +1. Проверьте **Панель управления → Состояние → Состояние поставщика**, чтобы узнать о шаблоне сбоя. +2. Перейдите в **Настройки → Устойчивость → Профили поставщиков** и увеличьте порог отказа. +3. Проверьте, не изменил ли провайдер лимиты API или требует повторной аутентификации. +4. Проверьте телеметрию задержки — высокая задержка может привести к сбоям из-за тайм-аута. + +--- + +## Проблемы с транскрипцией аудио + +### Ошибка «Неподдерживаемая модель» + +– Убедитесь, что вы используете правильный префикс: `deepgram/nova-3` или `assemblyai/best`. +– Убедитесь, что провайдер подключен в **Панель управления → Провайдеры**. + +### Транскрипция возвращает пустое значение или завершается с ошибкой + +- Проверьте поддерживаемые аудиоформаты: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. + – Убедитесь, что размер файла находится в пределах ограничений поставщика (обычно < 25 МБ). +- Проверьте действительность ключа API провайдера в карточке провайдера. + +--- + +## Отладка переводчика + +Используйте **Панель управления → Переводчик** для устранения проблем с переводом формата: + +| Режим | Когда использовать | +| ----------------------- | ------------------------------------------------------------------------------------------------------------- | +| **Детская площадка** | Сравните форматы ввода/вывода параллельно — вставьте ошибочный запрос, чтобы посмотреть, как он преобразуется | +| **Тестер чата** | Отправляйте живые сообщения и проверяйте всю полезную нагрузку запроса/ответа, включая заголовки | +| **Испытательный стенд** | Запустите пакетное тестирование комбинаций форматов, чтобы определить, какие переводы повреждены | +| **Живой монитор** | Наблюдайте за потоком запросов в режиме реального времени, чтобы выявить периодические проблемы с переводом | + +### Распространенные проблемы с форматами + +- **Теги «Мышление» не отображаются** — проверьте, поддерживает ли целевой поставщик мышление и настройку бюджета на мышление. +- **Отказ от вызовов инструментов** — Некоторые преобразования форматов могут удалять неподдерживаемые поля; проверить в режиме игровой площадки +- **Отсутствует системное приглашение** — Клод и Близнецы по-разному обрабатывают системные приглашения; проверить вывод перевода +- **SDK возвращает необработанную строку вместо объекта** — Исправлено в версии 1.1.0: средство очистки ответов теперь удаляет нестандартные поля (`x_groq`, `usage_breakdown` и т. д.), которые вызывают сбои проверки OpenAI SDK Pydantic. +- **GLM/ERNIE отклоняет роль `system`** — Исправлено в версии 1.1.0: нормализатор ролей автоматически объединяет системные сообщения с пользовательскими сообщениями для несовместимых моделей. +- **`developer` роль не распознана** — исправлено в версии 1.1.0: автоматически преобразуется в `system` для поставщиков, не поддерживающих OpenAI. +- **`json_schema` не работает с Gemini** — Исправлено в версии 1.1.0: `response_format` теперь преобразуется в `responseMimeType` Gemini + `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/ru/USER_GUIDE.md b/docs/i18n/ru/USER_GUIDE.md new file mode 100644 index 0000000000..e17941f7c9 --- /dev/null +++ b/docs/i18n/ru/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Руководство пользователя + +🌐 **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 | **БЕСПЛАТНО** | 180 тыс./мес + 1 тыс./день | Каждый! | +| | Второй пилот GitHub | 10–19 долларов в месяц | Ежемесячно | Пользователи GitHub | +| **🔑 КЛЮЧ API** | ДипСик | Плата за использование | Нет | Дешевое рассуждение | +| | Грок | Плата за использование | Нет | Сверхбыстрый вывод | +| | xAI (Грок) | Плата за использование | Нет | рассуждения Грока 4 | +| | Мистраль | Плата за использование | Нет | Модели, размещенные в ЕС | +| | Растерянность | Плата за использование | Нет | Расширенный поиск | +| | Вместе ИИ | Плата за использование | Нет | Модели с открытым исходным кодом | +| | Фейерверк ИИ | Плата за использование | Нет | Изображения Fast FLUX | +| | Церебра | Плата за использование | Нет | Скорость пластинчатого масштаба | +| | Согласовано | Плата за использование | Нет | Команда R+ ТРЯПКА | +| | NVIDIA НИМ | Плата за использование | Нет | Модели предприятия | +| **💰 ДЕШЕВО** | ГЛМ-4.7 | 0,6 долл. США/1 млн | Ежедневно в 10:00 | Резервное копирование бюджета | +| | МиниМакс М2.1 | 0,2 долл. США/1 млн | 5-часовой прокат | Самый дешевый вариант | +| | Кими К2 | 9 долларов в месяц за квартиру | 10 миллионов токенов в месяц | Предсказуемая стоимость | +| **🆓 БЕСПЛАТНО** | 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: «Я хочу нулевую стоимость» + +**Проблема:** Не могу позволить себе подписку, нужно надежное кодирование с использованием искусственного интеллекта. + +``` +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/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: «Мне нужен БЕСПЛАТНЫЙ ИИ в OpenClaw» + +**Проблема:** Нужен ИИ-помощник в приложениях для обмена сообщениями, совершенно бесплатно. + +``` +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 +``` + +**Совет для профессионалов.** Используйте Opus для сложных задач и Sonnet для скорости. OmniRoute отслеживает квоту на каждую модель! + +#### Кодекс OpenAI (Плюс/Про) + +```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/1 миллион) + +1. Зарегистрируйтесь: [Zhipu AI](https://open.bigmodel.cn/) +2. Получите ключ API из плана кодирования. +3. Панель управления → Добавить ключ API: Поставщик: `glm`, Ключ API: `your-key`. + +**Используйте:** `glm/glm-4.7` — **Совет для профессионалов:** План кодирования предлагает 3-кратную квоту за 1/7 стоимости! Сброс ежедневно в 10:00. + +#### MiniMax M2.1 (5 часов сброса, 0,20 доллара США/1 миллион долларов США) + +1. Зарегистрируйтесь: [MiniMax](https://www.minimax.io/) +2. Получите ключ API → Панель управления → Добавить ключ API. + +**Используйте:** `minimax/MiniMax-M2.1` — **Совет для профессионалов:** Самый дешевый вариант для длинного контекста (1 млн токенов)! + +#### Кими К2 (фиксированная цена 9 долларов в месяц) + +1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/) +2. Получите ключ API → Панель управления → Добавить ключ API. + +**Используйте:** `kimi/kimi-latest` — **Совет для профессионалов:** Фиксированная 9 долларов США в месяц за 10 миллионов токенов = эффективная стоимость 0,90 долларов США/1 миллион долларов США! + +### 🆓 БЕСПЛАТНЫЕ провайдеры + +#### 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 +``` + +#### Квен (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" +} +``` + +### Интерфейс командной строки Кодекса + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +### OpenClaw + +Отредактируйте `~/.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` | Секрет HMAC для сгенерированных ключей API | +| `REQUIRE_API_KEY` | `false` | Принудительно использовать ключ API носителя на `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Включает журналы запросов/ответов | +| `AUTH_COOKIE_SECURE` | `false` | Принудительно использовать файл cookie аутентификации `Secure` (за обратным прокси-сервером 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/`)** — Plus/Pro: `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 долларов США/1 миллион долларов США: `glm/glm-4.7` + +**MiniMax (`minimax/`)** — 0,2 доллара США/1 миллион долларов: `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` + +**DeepSeek (`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` + +**Вместе ИИ (`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 NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Расширенные функции + +### Пользовательские модели + +Добавьте любой идентификатор модели к любому поставщику, не дожидаясь обновления приложения: + +```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 Gateway Intelligence (этап 9) + +- **Семантический кеш** — автоматически кэширует непоточные ответы с температурой = 0 (обход с помощью `X-OmniRoute-No-Cache: true`) +- **Идемпотентность запросов** — дедупликация запросов в течение 5 секунд через заголовок `Idempotency-Key` или `X-Request-Id`. +- **Отслеживание прогресса** — включите события SSE `event: progress` через заголовок `X-OmniRoute-Progress: true`. + +--- + +### Игровая площадка переводчика + +Доступ через **Личный кабинет → Переводчик**. Отладка и визуализация того, как OmniRoute преобразует запросы API между поставщиками. + +| Режим | Цель | +| ----------------------- | -------------------------------------------------------------------------------------------------- | +| **Детская площадка** | Выберите исходный/целевой формат, вставьте запрос и мгновенно просмотрите переведенный результат | +| **Тестер чата** | Отправляйте сообщения в чате через прокси и проверяйте полный цикл запросов/ответов | +| **Испытательный стенд** | Запустите пакетные тесты для нескольких комбинаций форматов, чтобы проверить правильность перевода | +| **Живой монитор** | Наблюдайте за переводами в реальном времени, пока запросы проходят через прокси | + +**Случаи использования:** + +- Отладка причины сбоя конкретной комбинации клиента/провайдера. +- Убедитесь, что теги мышления, вызовы инструментов и системные подсказки переводятся правильно. +- Сравните различия форматов между форматами API OpenAI, Claude, Gemini и Responses. + +--- + +### Стратегии маршрутизации + +Настройте через **Панель управления → Настройки → Маршрутизация**. + +| Стратегия | Описание | +| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| **Сначала заполните** | Использует учетные записи в порядке приоритета — основная учетная запись обрабатывает все запросы, пока они не станут недоступны | +| **Круговая система** | Циклически перебирает все учетные записи с настраиваемым фиксированным лимитом (по умолчанию: 3 вызова на учетную запись) | +| **P2C (Сила двух вариантов)** | Выбирает 2 случайных аккаунта и направляется к более здоровому — балансирует нагрузку с осознанием здоровья | +| **Случайный** | Случайным образом выбирает учетную запись для каждого запроса, используя перемешивание Фишера-Йейтса | +| **Наименее используемый** | Маршруты к аккаунту с самой старой меткой времени `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 реализует устойчивость на уровне поставщика с помощью четырех компонентов: + +1. **Профили поставщиков** — конфигурация каждого поставщика для: + - Порог отказа (сколько отказов до открытия) + - Продолжительность перезарядки + - Чувствительность определения ограничения скорости + - Параметры экспоненциальной отсрочки + +2. **Редактируемые ограничения скорости** — настройки по умолчанию на уровне системы, которые можно настроить на панели управления: + - **Запросов в минуту (RPM)** — максимальное количество запросов в минуту на аккаунт. + - **Min Time Between Requests** — Минимальный промежуток в миллисекундах между запросами. + - **Максимальное количество одновременных запросов** — максимальное количество одновременных запросов на одну учетную запись. + – Нажмите **Изменить**, чтобы изменить, затем **Сохранить** или **Отменить**. Значения сохраняются через 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`) и размер (максимум 100 МБ). + +**Примеры использования:** + +- Миграция OmniRoute между компьютерами +- Создание внешних резервных копий для аварийного восстановления. +- Делитесь конфигурациями между членами команды (экспортировать все → поделиться архивом) + +--- + +### Панель настроек + +Страница настроек разделена на 5 вкладок для удобной навигации: + +| Вкладка | Содержание | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Безопасность** | Настройки логина/пароля, контроль доступа по IP, аутентификация API для `/models` и блокировка провайдера | +| **Маршрутизация** | Глобальная стратегия маршрутизации (6 вариантов), псевдонимы моделей с подстановочными знаками, резервные цепочки, комбинированные значения по умолчанию | +| **Устойчивость** | Профили провайдеров, редактируемые ограничения скорости, статус автоматического выключателя, политики и заблокированные идентификаторы | +| **ИИ** | Обдумывание конфигурации бюджета, глобальная системная инъекция подсказок, статистика кэша подсказок | +| **Расширенный** | Глобальная конфигурация прокси (HTTP/SOCKS5) | + +--- + +### Управление затратами и бюджетом + +Доступ через **Личный кабинет → Расходы**. + +| Вкладка | Цель | +| ---------- | ------------------------------------------------------------------------------------------------------------------------- | +| **Бюджет** | Установите лимиты расходов на ключ API с ежедневными/еженедельными/месячными бюджетами и отслеживанием в реальном времени | +| **Цены** | Просмотр и редактирование записей цен модели — стоимость за 1 тыс. токенов ввода/вывода на одного поставщика | + +```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 секунд. Используйте карту автоматического выключателя, чтобы определить, у каких поставщиков возникли проблемы. diff --git a/docs/i18n/sk/API_REFERENCE.md b/docs/i18n/sk/API_REFERENCE.md new file mode 100644 index 0000000000..9586f2d300 --- /dev/null +++ b/docs/i18n/sk/API_REFERENCE.md @@ -0,0 +1,441 @@ +# Referencia 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) + +Kompletná referencia pre všetky koncové body rozhrania OmniRoute API. + +--- + +## Obsah + +- [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) + +--- + +## Dokončenia četu + +```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 +} +``` + +### Vlastné hlavičky + +| Hlavička | Smer | Popis | +| ------------------------ | ------- | ------------------------------------------------------ | +| `X-OmniRoute-No-Cache` | Žiadosť | Ak chcete obísť vyrovnávaciu pamäť, nastavte na `true` | +| `X-OmniRoute-Progress` | Žiadosť | Nastaviť na `true` pre udalosti postupu | +| `Idempotency-Key` | Žiadosť | Deup kľúč (okno 5s) | +| `X-Request-Id` | Žiadosť | Alternatívny dedup kľúč | +| `X-OmniRoute-Cache` | Odpoveď | `HIT` alebo `MISS` (bez streamovania) | +| `X-OmniRoute-Idempotent` | Odpoveď | `true` v prípade deduplikácie | +| `X-OmniRoute-Progress` | Odpoveď | `enabled` ak sledovanie pokroku na | + +--- + +## Vloženie + +```bash +POST /v1/embeddings +Authorization: Bearer your-api-key +Content-Type: application/json + +{ + "model": "nebius/Qwen/Qwen3-Embedding-8B", + "input": "The food was delicious" +} +``` + +Dostupní poskytovatelia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. + +```bash +# List all embedding models +GET /v1/embeddings +``` + +--- + +## Generovanie obrázkov + +```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" +} +``` + +Dostupní poskytovatelia: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. + +```bash +# List all image models +GET /v1/images/generations +``` + +--- + +## Zoznam modelov + +```bash +GET /v1/models +Authorization: Bearer your-api-key + +→ Returns all chat, embedding, and image models + combos in OpenAI format +``` + +--- + +## Koncové body kompatibility + +| Metóda | Cesta | Formát | +| --------- | --------------------------- | --------------------- | +| Zverejniť | `/v1/chat/completions` | OpenAI | +| Zverejniť | `/v1/messages` | Antropický | +| Zverejniť | `/v1/responses` | Odpovede OpenAI | +| Zverejniť | `/v1/embeddings` | OpenAI | +| Zverejniť | `/v1/images/generations` | OpenAI | +| ZÍSKAJTE | `/v1/models` | OpenAI | +| Zverejniť | `/v1/messages/count_tokens` | Antropický | +| ZÍSKAJTE | `/v1beta/models` | Blíženci | +| Zverejniť | `/v1beta/models/{...path}` | Gemini generovaťObsah | +| Zverejniť | `/v1/api/chat` | Ollama | + +### Vyhradené trasy poskytovateľa + +```bash +POST /v1/providers/{provider}/chat/completions +POST /v1/providers/{provider}/embeddings +POST /v1/providers/{provider}/images/generations +``` + +Ak chýba predpona poskytovateľa, automaticky sa pridá. Nezhodné modely vrátia `400`. + +--- + +## Sémantická vyrovnávacia pamäť + +```bash +# Get cache stats +GET /api/cache + +# Clear all caches +DELETE /api/cache +``` + +Príklad odpovede: + +```json +{ + "semanticCache": { + "memorySize": 42, + "memoryMaxSize": 500, + "dbSize": 128, + "hitRate": 0.65 + }, + "idempotency": { + "activeKeys": 3, + "windowMs": 5000 + } +} +``` + +--- + +## Dashboard & Management + +### Autentifikácia + +| Koncový bod | Metóda | Popis | +| ----------------------------- | --------- | --------------------------------- | +| `/api/auth/login` | Zverejniť | Prihlásiť sa | +| `/api/auth/logout` | Zverejniť | Odhlásiť sa | +| `/api/settings/require-login` | GET/PUT | Vyžaduje sa prepnutie prihlásenia | + +### Správa poskytovateľa + +| Koncový bod | Metóda | Popis | +| ---------------------------- | --------------------- | ---------------------------------- | +| `/api/providers` | ZÍSKAŤ/POSLAŤ | Zoznam / vytvorenie poskytovateľov | +| `/api/providers/[id]` | GET/PUT/DELETE | Spravovať poskytovateľa | +| `/api/providers/[id]/test` | Zverejniť | Test pripojenia poskytovateľa | +| `/api/providers/[id]/models` | ZÍSKAJTE | Zoznam modelov poskytovateľov | +| `/api/providers/validate` | Zverejniť | Overiť konfiguráciu poskytovateľa | +| `/api/provider-nodes*` | Rôzne | Správa uzla poskytovateľa | +| `/api/provider-models` | ZÍSKAŤ/POSLAŤ/VYMAZAŤ | Vlastné modely | + +### Toky OAuth + +| Koncový bod | Metóda | Popis | +| -------------------------------- | ------ | ---------------------------------- | +| `/api/oauth/[provider]/[action]` | Rôzne | OAuth špecifické pre poskytovateľa | + +### Smerovanie a konfigurácia + +| Koncový bod | Metóda | Popis | +| --------------------- | ------------- | --------------------------------------- | +| `/api/models/alias` | ZÍSKAŤ/POSLAŤ | Modelové aliasy | +| `/api/models/catalog` | ZÍSKAJTE | Všetky modely podľa poskytovateľa + typ | +| `/api/combos*` | Rôzne | Kombinovaný manažment | +| `/api/keys*` | Rôzne | Správa kľúčov API | +| `/api/pricing` | ZÍSKAJTE | Cena modelu | + +### Použitie a analýza + +| Koncový bod | Metóda | Popis | +| --------------------------- | -------- | ---------------------------- | +| `/api/usage/history` | ZÍSKAJTE | História používania | +| `/api/usage/logs` | ZÍSKAJTE | Denníky používania | +| `/api/usage/request-logs` | ZÍSKAJTE | Protokoly na úrovni žiadosti | +| `/api/usage/[connectionId]` | ZÍSKAJTE | Použitie na pripojenie | + +### Nastavenia + +| Koncový bod | Metóda | Popis | +| ------------------------------- | --------- | --------------------------------- | +| `/api/settings` | GET/PUT | Všeobecné nastavenia | +| `/api/settings/proxy` | GET/PUT | Konfigurácia sieťového proxy | +| `/api/settings/proxy/test` | Zverejniť | Test pripojenia proxy | +| `/api/settings/ip-filter` | GET/PUT | Zoznam povolených/blokovaných IP | +| `/api/settings/thinking-budget` | GET/PUT | Zdôvodnenie symbolického rozpočtu | +| `/api/settings/system-prompt` | GET/PUT | Výzva globálneho systému | + +### Monitorovanie + +| Koncový bod | Metóda | Popis | +| ------------------------ | ---------- | ---------------------------------------- | +| `/api/sessions` | ZÍSKAJTE | Sledovanie aktívnej relácie | +| `/api/rate-limits` | ZÍSKAJTE | Limity sadzieb na účet | +| `/api/monitoring/health` | ZÍSKAJTE | Zdravotná prehliadka | +| `/api/cache` | GET/DELETE | Štatistiky vyrovnávacej pamäte / vymazať | + +### Zálohovanie a export/import + +| Koncový bod | Metóda | Popis | +| --------------------------- | --------- | --------------------------------------------- | +| `/api/db-backups` | ZÍSKAJTE | Zoznam dostupných záloh | +| `/api/db-backups` | PUT | Vytvorte manuálnu zálohu | +| `/api/db-backups` | Zverejniť | Obnoviť z konkrétnej zálohy | +| `/api/db-backups/export` | ZÍSKAJTE | Stiahnuť databázu ako súbor .sqlite | +| `/api/db-backups/import` | Zverejniť | Nahrajte súbor .sqlite na nahradenie databázy | +| `/api/db-backups/exportAll` | ZÍSKAJTE | Stiahnite si úplnú zálohu ako archív .tar.gz | + +### Cloud Sync + +| Koncový bod | Metóda | Popis | +| ---------------------- | --------- | --------------------------------- | +| `/api/sync/cloud` | Rôzne | Operácie synchronizácie s cloudom | +| `/api/sync/initialize` | Zverejniť | Inicializovať synchronizáciu | +| `/api/cloud/*` | Rôzne | Správa cloudu | + +### Nástroje CLI + +| Koncový bod | Metóda | Popis | +| ---------------------------------- | -------- | ------------------- | +| `/api/cli-tools/claude-settings` | ZÍSKAJTE | Claude CLI status | +| `/api/cli-tools/codex-settings` | ZÍSKAJTE | Status Codex CLI | +| `/api/cli-tools/droid-settings` | ZÍSKAJTE | Stav CLI Droid | +| `/api/cli-tools/openclaw-settings` | ZÍSKAJTE | Stav OpenClaw CLI | +| `/api/cli-tools/runtime/[toolId]` | ZÍSKAJTE | Generic CLI runtime | + +Odpovede CLI zahŕňajú: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. + +### Odolnosť a limity rýchlosti + +| Koncový bod | Metóda | Popis | +| ----------------------- | --------- | ------------------------------------- | +| `/api/resilience` | GET/PUT | Získať/aktualizovať profily odolnosti | +| `/api/resilience/reset` | Zverejniť | Resetujte ističe | +| `/api/rate-limits` | ZÍSKAJTE | Stav limitu sadzby na účet | +| `/api/rate-limit` | ZÍSKAJTE | Konfigurácia globálneho limitu sadzby | + +### Evals + +| Koncový bod | Metóda | Popis | +| ------------ | ------------- | -------------------------------------------------- | +| `/api/evals` | ZÍSKAŤ/POSLAŤ | Vypísať vyhodnocovacie sady / spustiť vyhodnotenie | + +### Zásady + +| Koncový bod | Metóda | Popis | +| --------------- | --------------------- | ----------------------------- | +| `/api/policies` | ZÍSKAŤ/POSLAŤ/VYMAZAŤ | Spravovať pravidlá smerovania | + +### Súlad + +| Koncový bod | Metóda | Popis | +| --------------------------- | -------- | ----------------------------------- | +| `/api/compliance/audit-log` | ZÍSKAJTE | Protokol auditu súladu (posledné N) | + +### v1beta (kompatibilné s Gemini) + +| Koncový bod | Metóda | Popis | +| -------------------------- | --------- | -------------------------------------- | +| `/v1beta/models` | ZÍSKAJTE | Zoznam modelov vo formáte Gemini | +| `/v1beta/models/{...path}` | Zverejniť | Blíženci `generateContent` koncový bod | + +Tieto koncové body odzrkadľujú formát API Gemini pre klientov, ktorí očakávajú natívnu kompatibilitu Gemini SDK. + +### Interné / systémové rozhrania API + +| Koncový bod | Metóda | Popis | +| --------------- | --------- | ---------------------------------------------------------------- | +| `/api/init` | ZÍSKAJTE | Kontrola inicializácie aplikácie (používa sa pri prvom spustení) | +| `/api/tags` | ZÍSKAJTE | Modelové štítky kompatibilné s Ollamou (pre klientov Ollamy) | +| `/api/restart` | Zverejniť | Spustenie elegantného reštartu servera | +| `/api/shutdown` | Zverejniť | Spustiť elegantné vypnutie servera | + +> **Poznámka:** Tieto koncové body sú používané interne systémom alebo kvôli kompatibilite klienta Ollama. Koncoví používatelia ich zvyčajne nevolajú. + +--- + +## Prepis zvuku + +```bash +POST /v1/audio/transcriptions +Authorization: Bearer your-api-key +Content-Type: multipart/form-data +``` + +Prepisujte zvukové súbory pomocou Deepgram alebo AssemblyAI. + +**Žiadosť:** + +```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" +``` + +**Odpoveď:** + +```json +{ + "text": "Hello, this is the transcribed audio content.", + "task": "transcribe", + "language": "en", + "duration": 12.5 +} +``` + +**Podporovaní poskytovatelia:** `deepgram/nova-3`, `assemblyai/best`. + +**Podporované formáty:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, \_\_12_TOKEN_1_TO + +--- + +## Kompatibilita s Ollamou + +Pre klientov, ktorí používajú formát Ollama's API: + +```bash +# Chat endpoint (Ollama format) +POST /v1/api/chat + +# Model listing (Ollama format) +GET /api/tags +``` + +Žiadosti sa automaticky prekladajú medzi Ollama a internými formátmi. + +--- + +## Telemetria + +```bash +# Get latency telemetry summary (p50/p95/p99 per provider) +GET /api/telemetry/summary +``` + +**Odpoveď:** + +```json +{ + "providers": { + "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, + "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } + } +} +``` + +--- + +## Rozpočet + +```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" +} +``` + +--- + +## Dostupnosť modelu + +```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" +} +``` + +--- + +## Spracovanie žiadosti + +1. Klient odošle požiadavku na `/v1/*` +2. Volania obslužného programu trasy `handleChat`, `handleEmbedding`, `handleAudioTranscription` alebo `handleImageGeneration` +3. Model je vyriešený (priamy poskytovateľ/model alebo alias/kombo) +4. Prihlasovacie údaje vybrané z lokálnej databázy s filtrovaním dostupnosti účtu +5. Pre chat: `handleChatCore` — detekcia formátu, preklad, kontrola vyrovnávacej pamäte, kontrola idempotencie +6. Exekútor poskytovateľa odošle upstream požiadavku +7. Odpoveď preložená späť do formátu klienta (chat) alebo vrátená tak, ako je (vložené/obrázky/audio) +8. Používanie/protokolovanie zaznamenané +9. Záložný postup sa vzťahuje na chyby podľa pravidiel komba + +Odkaz na úplnú architektúru: [**OMNI_TOKEN_119**](ARCHITECTURE.md) + +--- + +## Autentifikácia + +- Trasy hlavného panela (`/dashboard/*`) používajú súbor cookie `auth_token` +- Prihlásenie používa uložený hash hesla; návrat k `INITIAL_PASSWORD` +- `requireLogin` prepínateľné cez `/api/settings/require-login` +- trasy `/v1/*` voliteľne vyžadujú kľúč API nosiča, keď `REQUIRE_API_KEY=true` diff --git a/docs/i18n/sk/ARCHITECTURE.md b/docs/i18n/sk/ARCHITECTURE.md new file mode 100644 index 0000000000..7573f74d88 --- /dev/null +++ b/docs/i18n/sk/ARCHITECTURE.md @@ -0,0 +1,783 @@ +# Architektúra 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) + +_Posledná aktualizácia: 2026-02-18_ + +## Zhrnutie + +OmniRoute je lokálna AI smerovacia brána a dashboard postavená na Next.js. +Poskytuje jeden koncový bod kompatibilný s OpenAI (`/v1/*`) a smeruje prevádzku medzi viacerých upstream poskytovateľov s prekladom, záložným, obnovovaním tokenov a sledovaním používania. + +Základné schopnosti: + +- OpenAI kompatibilný povrch API pre CLI/nástroje (28 poskytovateľov) +- Požiadavka / odpoveď na preklad medzi formátmi poskytovateľov +- Záložná kombinácia modelov (sekvencia viacerých modelov) + – Záložný režim na úrovni účtu (viac účtov na poskytovateľa) +- Správa pripojenia poskytovateľa s kľúčom OAuth + API +- Generovanie vkladania prostredníctvom `/v1/embeddings` (6 poskytovateľov, 9 modelov) +- Generovanie obrázkov prostredníctvom `/v1/images/generations` (4 poskytovatelia, 9 modelov) +- Myslite na analýzu značiek (`...`) pre modely uvažovania +- Dezinfekcia odozvy pre prísnu kompatibilitu OpenAI SDK +- Normalizácia rolí (vývojár→systém, systém→používateľ) pre kompatibilitu medzi poskytovateľmi +- Konverzia štruktúrovaného výstupu (json_schema → Gemini responseSchema) +- Miestna perzistencia pre poskytovateľov, kľúče, aliasy, kombá, nastavenia, ceny +- Sledovanie používania / nákladov a zaznamenávanie žiadostí +- Voliteľná cloudová synchronizácia pre synchronizáciu viacerých zariadení/stavov +- Zoznam povolených/blokovaných IP adries pre riadenie prístupu k API +- Myslenie na správu rozpočtu (priechodový/automatický/vlastný/adaptívny) +- Rýchle vstrekovanie globálneho systému +- Sledovanie relácií a snímanie odtlačkov prstov +- Rozšírené obmedzenie sadzieb na účet s profilmi špecifickými pre poskytovateľov +- Vzor ističa pre odolnosť poskytovateľa +- Ochrana stáda proti hromu s blokovaním mutex +- Cache deduplikácie požiadaviek na základe podpisu +- Doménová vrstva: dostupnosť modelu, cenové pravidlá, záložná politika, politika blokovania +- Stálosť stavu domény (vyrovnávacia pamäť SQLite pre záložné zdroje, rozpočty, blokovania, ističe) +- Modul politiky pre centralizované vyhodnocovanie požiadaviek (uzamknutie → rozpočet → záložné) +- Požiadajte o telemetriu s agregáciou latencie p50/p95/p99 +- ID korelácie (X-Request-Id) pre end-to-end sledovanie +- Protokolovanie auditu súladu s odhlásením podľa kľúča API +- Hodnotný rámec pre zabezpečenie kvality LLM +- Prístrojová doska UI Resilience so stavom ističa v reálnom čase +- Modulárni poskytovatelia OAuth (12 samostatných modulov pod `src/lib/oauth/providers/`) + +Primárny runtime model: + +– Trasy aplikácie Next.js pod `src/app/api/*` implementujú rozhrania API hlavného panela aj rozhrania API kompatibility +– Zdieľané jadro SSE/smerovanie v `src/sse/*` + `open-sse/*` sa stará o vykonávanie poskytovateľa, preklad, streamovanie, záložné zdroje a používanie + +## Rozsah a hranice + +### V rozsahu + +- Runtime lokálnej brány +- Rozhrania API na správu informačných panelov +- Overenie poskytovateľa a obnovenie tokenu +- Požiadajte o preklad a streamovanie SSE +- Miestny stav + pretrvávanie používania +- Voliteľná orchestrácia synchronizácie s cloudom + +### Mimo rozsah + +- Implementácia cloudovej služby za `NEXT_PUBLIC_CLOUD_URL` +- Poskytovateľ SLA/riadiaca rovina mimo lokálneho procesu +- Samotné externé binárne súbory CLI (Claude CLI, Codex CLI atď.) + +## Kontext systému na vysokej úrovni + +```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 +``` + +## Základné komponenty runtime + +## 1) API a Routing Layer (Next.js App Routes) + +Hlavné adresáre: + +- `src/app/api/v1/*` a `src/app/api/v1beta/*` pre rozhrania API kompatibility +- `src/app/api/*` pre spravovanie/konfiguráciu API +- Ďalšie prepisy na `next.config.mjs` mape `/v1/*` na `/api/v1/*` + +Dôležité cesty kompatibility: + +- `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` – zahŕňa vlastné modely s `custom: true` +- `src/app/api/v1/embeddings/route.ts` – generovanie vkladania (6 poskytovateľov) +- `src/app/api/v1/images/generations/route.ts` — generovanie obrázkov (4+ poskytovatelia vrátane Antigravity/Nebius) +- `src/app/api/v1/messages/count_tokens/route.ts` +- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` – vyhradený chat pre jednotlivých poskytovateľov +- `src/app/api/v1/providers/[provider]/embeddings/route.ts` – vyhradené vloženia podľa jednotlivých poskytovateľov +- `src/app/api/v1/providers/[provider]/images/generations/route.ts` – vyhradené obrázky podľa jednotlivých poskytovateľov +- `src/app/api/v1beta/models/route.ts` +- `src/app/api/v1beta/models/[...path]/route.ts` + +Manažérske domény: + +- Autorizácia/nastavenia: `src/app/api/auth/*`, `src/app/api/settings/*` + – Poskytovatelia/pripojenia: `src/app/api/providers*` + – Uzly poskytovateľa: `src/app/api/provider-nodes*` + – Vlastné modely: `src/app/api/provider-models` (GET/POST/DELETE) +- Katalóg modelov: `src/app/api/models/catalog` (GET) +- Konfigurácia proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` + – Kľúče/aliasy/kombá/ceny: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Použitie: `src/app/api/usage/*` + – Synchronizácia/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- Pomocníci nástrojov CLI: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Rozpočet: `src/app/api/settings/thinking-budget` (GET/PUT) +- Systémová výzva: `src/app/api/settings/system-prompt` (GET/PUT) +- Relácie: `src/app/api/sessions` (GET) +- Limity sadzby: `src/app/api/rate-limits` (GET) +- Odolnosť: `src/app/api/resilience` (GET/PATCH) – profily poskytovateľa, istič, medzný stav rýchlosti +- Resetovanie odolnosti: `src/app/api/resilience/reset` (POST) - resetovanie ističov + cooldowny +- Štatistiky vyrovnávacej pamäte: `src/app/api/cache/stats` (GET/DELETE) +- Dostupnosť modelu: `src/app/api/models/availability` (GET/POST) +- Telemetria: `src/app/api/telemetry/summary` (GET) +- Rozpočet: `src/app/api/usage/budget` (GET/POST) +- Záložné reťazce: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Audit súladu: `src/app/api/compliance/audit-log` (GET) +- Hodnoty: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) + – Zásady: `src/app/api/policies` (GET/POST) + +## 2) SSE + jadro prekladu + +Hlavné prietokové moduly: + +- Vstup: `src/sse/handlers/chat.ts` +- Základná orchestrácia: `open-sse/handlers/chatCore.ts` +- Spúšťacie adaptéry poskytovateľa: `open-sse/executors/*` +- Detekcia formátu/konfigurácia poskytovateľa: `open-sse/services/provider.ts` +- Analýza/rozlíšenie modelu: `src/sse/services/model.ts`, `open-sse/services/model.ts` + – Logika záložného účtu: `open-sse/services/accountFallback.ts` +- Register prekladov: `open-sse/translator/index.ts` +- Transformácie streamu: `open-sse/utils/stream.ts`, `open-sse/utils/streamHandler.ts` +- Extrakcia/normalizácia použitia: `open-sse/utils/usageTracking.ts` + – Analyzátor značiek Think: `open-sse/utils/thinkTagParser.ts` +- Obslužný nástroj vkladania: `open-sse/handlers/embeddings.ts` + – Register poskytovateľov vkladania: `open-sse/config/embeddingRegistry.ts` + – Obslužný program generovania obrázkov: `open-sse/handlers/imageGeneration.ts` + – Register poskytovateľa obrázkov: `open-sse/config/imageRegistry.ts` +- Dezinfekcia odozvy: `open-sse/handlers/responseSanitizer.ts` +- Normalizácia rolí: `open-sse/services/roleNormalizer.ts` + +Služby (obchodná logika): + +- Výber účtu/bodovanie: `open-sse/services/accountSelector.ts` +- Kontextová správa životného cyklu: `open-sse/services/contextManager.ts` +- Vynútenie filtra IP: `open-sse/services/ipFilter.ts` + – Sledovanie relácií: `open-sse/services/sessionManager.ts` +- Žiadosť o deduplikáciu: `open-sse/services/signatureCache.ts` +- Okamžité vloženie do systému: `open-sse/services/systemPrompt.ts` +- Myslenie na správu rozpočtu: `open-sse/services/thinkingBudget.ts` +- Smerovanie modelu so zástupným znakom: `open-sse/services/wildcardRouter.ts` +- Správa limitu sadzieb: `open-sse/services/rateLimitManager.ts` +- Istič: `open-sse/services/circuitBreaker.ts` + +Moduly vrstvy domény: + +- Dostupnosť modelu: `src/lib/domain/modelAvailability.ts` +- Cenové pravidlá/rozpočty: `src/lib/domain/costRules.ts` + – Záložné pravidlá: `src/lib/domain/fallbackPolicy.ts` +- Kombinovaný prekladač: `src/lib/domain/comboResolver.ts` + – Zásady blokovania: `src/lib/domain/lockoutPolicy.ts` +- Modul politiky: `src/domain/policyEngine.ts` – centralizované uzamknutie → rozpočet → záložné hodnotenie + – Katalóg kódov chýb: `src/lib/domain/errorCodes.ts` + – ID žiadosti: `src/lib/domain/requestId.ts` + – Časový limit načítania: `src/lib/domain/fetchTimeout.ts` +- Vyžiadať telemetriu: `src/lib/domain/requestTelemetry.ts` +- Súlad/audit: `src/lib/domain/compliance/index.ts` +- Hodnotný bežec: `src/lib/domain/evalRunner.ts` +- Trvalosť stavu domény: `src/lib/db/domainState.ts` — SQLite CRUD pre záložné reťazce, rozpočty, históriu nákladov, stav uzamknutia, ističe + +Moduly poskytovateľa OAuth (12 samostatných súborov pod `src/lib/oauth/providers/`): + +- Index registra: `src/lib/oauth/providers/index.ts` + – Jednotliví poskytovatelia: `claude.ts`, `codex.ts`, `gemini.ts`, `antigravity.ts`, `iflow.ts`, \_\_OMNI_TOKEN_1_TOKNI_10 `github.ts`, `kiro.ts`, `cursor.ts`, `kilocode.ts`, `cline.ts` +- Tenký obal: `src/lib/oauth/providers.ts` – reexporty z jednotlivých modulov + +## 3) Vrstva perzistencie + +Primárny stav DB: + +- `src/lib/localDb.ts` +- súbor: `${DATA_DIR}/db.json` (alebo `$XDG_CONFIG_HOME/omniroute/db.json`, ak je nastavený, inak `~/.omniroute/db.json`) +- entity: providerConnections, providerNodes, modelAliases, kombá, apiKeys, nastavenia, ceny, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Použitie DB: + +- `src/lib/usageDb.ts` +- súbory: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- dodržiava rovnakú zásadu základného adresára ako `localDb` (`DATA_DIR`, potom `XDG_CONFIG_HOME/omniroute`, keď je nastavené) +- rozložené do zameraných podmodulov: `migrations.ts`, `usageHistory.ts`, `costCalculator.ts`, `usageStats.ts`, `callLogs.ts` + +DB stavu domény (SQLite): + +- `src/lib/db/domainState.ts` — operácie CRUD pre stav domény + – Tabuľky (vytvorené v `src/lib/db/core.ts`): `domain_fallback_chains`, `domain_budgets`, `domain_cost_history`, `domain_lockout_state`, \_\_14_TOKEN +- Vzor vyrovnávacej pamäte pre zápis: mapy v pamäti sú autoritatívne za behu; mutácie sa zapisujú synchrónne do SQLite; stav sa obnoví z DB pri studenom štarte + +## 4) Auth + Security Surfaces + +– Overenie súboru cookie informačného panela: `src/proxy.ts`, `src/app/api/auth/login/route.ts` + +- Generovanie/overenie kľúča API: `src/shared/utils/apiKey.ts` +- Tajomstvá poskytovateľa sa zachovali v `providerConnections` záznamoch +- Podpora odchádzajúceho proxy cez `open-sse/utils/proxyFetch.ts` (env vars) a `open-sse/utils/networkProxy.ts` (konfigurovateľné podľa poskytovateľa alebo globálne) + +## 5) Cloud Sync + +- Spustenie plánovača: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Pravidelná úloha: `src/shared/services/cloudSyncScheduler.ts` +- Kontrolná trasa: `src/app/api/sync/cloud/route.ts` + +## Životný cyklus žiadosti (`/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 +``` + +## Kombinovaný tok + záložný tok účtu + +```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] +``` + +Záložné rozhodnutia riadi `open-sse/services/accountFallback.ts` pomocou stavových kódov a heuristiky chybových správ. + +## Registrácia OAuth a životný cyklus obnovenia tokenu + +```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 +``` + +Obnovenie počas živej prevádzky sa vykonáva vo vnútri `open-sse/handlers/chatCore.ts` prostredníctvom spúšťača `refreshCredentials()`. + +## Životný cyklus cloudovej synchronizácie (povoliť / synchronizovať / zakázať) + +```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 +``` + +Pravidelnú synchronizáciu spúšťa `CloudSyncScheduler`, keď je povolený cloud. + +## Dátový model a mapa úložiska + +```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 + } +``` + +Súbory fyzického úložiska: + +- hlavný stav: `${DATA_DIR}/db.json` (alebo `$XDG_CONFIG_HOME/omniroute/db.json`, keď je nastavený, inak `~/.omniroute/db.json`) +- štatistiky používania: `${DATA_DIR}/usage.json` +- riadky denníka žiadostí: `${DATA_DIR}/log.txt` +- voliteľné relácie ladenia prekladateľa/požiadavky: `/logs/...` + +## Topológia nasadenia + +```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 +``` + +## Mapovanie modulov (kritické rozhodnutie) + +### Moduly trasy a API + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: rozhrania API pre kompatibilitu +- `src/app/api/v1/providers/[provider]/*`: vyhradené trasy podľa jednotlivých poskytovateľov (čet, vkladanie, obrázky) +- `src/app/api/providers*`: poskytovateľ CRUD, validácia, testovanie +- `src/app/api/provider-nodes*`: správa vlastných kompatibilných uzlov +- `src/app/api/provider-models`: správa vlastného modelu (CRUD) +- `src/app/api/models/catalog`: API úplného katalógu modelov (všetky typy zoskupené podľa poskytovateľa) +- `src/app/api/oauth/*`: toky OAuth/kódu zariadenia +- `src/app/api/keys*`: životný cyklus lokálneho kľúča API +- `src/app/api/models/alias`: správa aliasov +- `src/app/api/combos*`: správa náhradných kombinácií +- `src/app/api/pricing`: prepísanie cien pre výpočet nákladov +- `src/app/api/settings/proxy`: konfigurácia proxy (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: test outbound proxy konektivity (POST) +- `src/app/api/usage/*`: použitie a protokoly API +- `src/app/api/sync/*` + `src/app/api/cloud/*`: synchronizácia s cloudom a pomocníci s orientáciou na cloud +- `src/app/api/cli-tools/*`: miestne zapisovače/kontroly konfigurácie CLI +- `src/app/api/settings/ip-filter`: zoznam povolených/blokovaných adries IP (GET/PUT) +- `src/app/api/settings/thinking-budget`: konfigurácia rozpočtu tokenu myslenia (GET/PUT) +- `src/app/api/settings/system-prompt`: výzva globálneho systému (GET/PUT) +- `src/app/api/sessions`: zoznam aktívnej relácie (GET) +- `src/app/api/rate-limits`: stav limitu sadzby na účet (GET) + +### Jadro smerovania a vykonávania + +- `src/sse/handlers/chat.ts`: analýza požiadaviek, spracovanie komb, slučka výberu účtu +- `open-sse/handlers/chatCore.ts`: preklad, odoslanie vykonávateľa, spracovanie opakovania/obnovenia, nastavenie streamu +- `open-sse/executors/*`: správanie siete a formátu špecifické pre poskytovateľa + +### Register prekladov a konvertory formátov + +- `open-sse/translator/index.ts`: register prekladateľov a orchestrácia + – Žiadosť prekladateľov: `open-sse/translator/request/*` +- Prekladatelia odpovedí: `open-sse/translator/response/*` +- Formátové konštanty: `open-sse/translator/formats.ts` + +### Vytrvalosť + +- `src/lib/localDb.ts`: trvalá konfigurácia/stav +- `src/lib/usageDb.ts`: história používania a priebežné protokoly požiadaviek + +## Pokrytie poskytovateľa vykonávateľa (vzor stratégie) + +Každý poskytovateľ má špecializovaný spúšťač rozširujúci `BaseExecutor` (v `open-sse/executors/base.ts`), ktorý poskytuje vytváranie URL, konštrukciu hlavičky, opakovanie s exponenciálnym stiahnutím, háky obnovenia poverení a metódu orchestrácie `execute()`. + +| Exekútor | Poskytovatelia | Špeciálna manipulácia | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, iFlow, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Konfigurácia dynamickej adresy URL/hlavičky podľa poskytovateľa | +| `AntigravityExecutor` | Google Antigravity | Vlastné ID projektu/relácie, Opakovať po analýze | +| `CodexExecutor` | Kódex OpenAI | Vkladá pokyny systému, vynucuje úsilie na uvažovanie | +| `CursorExecutor` | Kurzor IDE | Protokol ConnectRPC, kódovanie Protobuf, podpis požiadavky cez kontrolný súčet | +| `GithubExecutor` | GitHub Copilot | Obnovenie tokenu kopilota, hlavičky napodobňujúce VSCode | +| `KiroExecutor` | AWS CodeWhisperer/Kiro | Binárny formát AWS EventStream → Konverzia SSE | +| `GeminiCLIExecutor` | Gemini CLI | Cyklus obnovenia tokenu Google OAuth | + +Všetci ostatní poskytovatelia (vrátane vlastných kompatibilných uzlov) používajú `DefaultExecutor`. + +## Matica kompatibility poskytovateľa + +| Poskytovateľ | Formát | Auth | Stream | Nestreamovať | Obnovenie tokenu | Použitie API | +| ---------------- | ---------------- | ----------------------- | -------------------- | ------------ | ---------------- | ------------------- | +| Claude | claude | Kľúč API / OAuth | ✅ | ✅ | ✅ | ⚠️ Len správca | +| Blíženci | Blíženci | Kľúč API / OAuth | ✅ | ✅ | ✅ | ⚠️ Cloudová konzola | +| Gemini CLI | gemini-cli | OAuth | ✅ | ✅ | ✅ | ⚠️ Cloudová konzola | +| Antigravitácia | antigravitácia | OAuth | ✅ | ✅ | ✅ | ✅ Plná kvóta API | +| OpenAI | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Kódex | openai-responses | OAuth | ✅ nútený | ❌ | ✅ | ✅ Sadzobné limity | +| GitHub Copilot | openai | OAuth + token Copilot | ✅ | ✅ | ✅ | ✅ Snímky kvóty | +| Kurzor | kurzor | Vlastný kontrolný súčet | ✅ | ✅ | ❌ | ❌ | +| Kiro | kiro | AWS SSO OIDC | ✅ (Stream udalostí) | ❌ | ✅ | ✅ Limity použitia | +| Qwen | openai | OAuth | ✅ | ✅ | ✅ | ⚠️ Na požiadanie | +| iFlow | openai | OAuth (základné) | ✅ | ✅ | ✅ | ⚠️ Na požiadanie | +| OpenRouter | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| GLM/Kimi/MiniMax | claude | API kľúč | ✅ | ✅ | ❌ | ❌ | +| DeepSeek | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Groq | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| xAI (Grok) | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Mistral | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Zmätok | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Spolu AI | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Ohňostroje AI | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Cerebras | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| Cohere | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | +| NVIDIA NIM | openai | API kľúč | ✅ | ✅ | ❌ | ❌ | + +## Pokrytie formátu prekladu + +Medzi zistené zdrojové formáty patria: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Cieľové formáty zahŕňajú: + +- OpenAI chat/reakcie +- Claude +- Gemini/Gemini-CLI/Antigravitačná obálka +- Kiro +- Kurzor + +Preklady používajú **OpenAI ako formát centra** — všetky konverzie prechádzajú cez OpenAI ako medziprodukt: + +``` +Source Format → OpenAI (hub) → Target Format +``` + +Preklady sa vyberajú dynamicky na základe tvaru zdroja a cieľového formátu poskytovateľa. + +Ďalšie vrstvy spracovania v reťazci prekladu: + +– **Dezinfekcia odpovedí** – Odstráni neštandardné polia z odpovedí vo formáte OpenAI (streamovaných aj nestreamovaných), aby sa zabezpečila prísna zhoda so súpravou SDK + +- **Normalizácia rolí** – Konvertuje `developer` → `system` pre ciele mimo OpenAI; zlučuje `system` → `user` pre modely, ktoré odmietajú systémovú rolu (GLM, ERNIE) + – **Think tagextrakcia** – analyzuje `...` bloky z obsahu do poľa `reasoning_content` + – **Štruktúrovaný výstup** – Konvertuje OpenAI `response_format.json_schema` na Gemini `responseMimeType` + `responseSchema` + +## Podporované koncové body API + +| Koncový bod | Formát | Psovod | +| -------------------------------------------------- | --------------------- | ------------------------------------------------------- | +| `POST /v1/chat/completions` | OpenAI Chat | `src/sse/handlers/chat.ts` | +| `POST /v1/messages` | Claude Správy | Rovnaký handler (automaticky detekovaný) | +| `POST /v1/responses` | Odpovede OpenAI | `open-sse/handlers/responsesHandler.ts` | +| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | +| `GET /v1/embeddings` | Zoznam modelov | Cesta API | +| `POST /v1/images/generations` | Obrázky OpenAI | `open-sse/handlers/imageGeneration.ts` | +| `GET /v1/images/generations` | Zoznam modelov | Cesta API | +| `POST /v1/providers/{provider}/chat/completions` | OpenAI Chat | Vyhradené pre každého poskytovateľa s overením modelu | +| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | Vyhradené pre každého poskytovateľa s overením modelu | +| `POST /v1/providers/{provider}/images/generations` | Obrázky OpenAI | Vyhradené pre každého poskytovateľa s overením modelu | +| `POST /v1/messages/count_tokens` | Počet tokenov Claude | Cesta API | +| `GET /v1/models` | Zoznam modelov OpenAI | Cesta API (chat + vkladanie + obrázok + vlastné modely) | +| `GET /api/models/catalog` | Katalóg | Všetky modely zoskupené podľa poskytovateľa + typ | +| `POST /v1beta/models/*:streamGenerateContent` | Rodák Blíženci | Cesta API | +| `GET/PUT/DELETE /api/settings/proxy` | Konfigurácia proxy | Konfigurácia sieťového proxy | +| `POST /api/settings/proxy/test` | Pripojenie proxy | Koncový bod testu stavu proxy/konektivity | +| `GET/POST/DELETE /api/provider-models` | Vlastné modely | Správa vlastného modelu podľa poskytovateľa | + +## Obchádzka + +Obídená obsluha (`open-sse/utils/bypassHandler.ts`) zachytí známe požiadavky na „zahodenie“ od Claude CLI – zahrievacie pingy, extrakcie titulov a počty tokenov – a vráti **falošnú odpoveď** bez spotrebovania tokenov poskytovateľa upstream. Toto sa spustí iba vtedy, keď `User-Agent` obsahuje `claude-cli`. + +## Request Logger Pipeline + +Záznamník požiadaviek (`open-sse/utils/requestLogger.ts`) poskytuje 7-stupňový kanál zaznamenávania ladenia, ktorý je predvolene vypnutý, povolený prostredníctvom `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 +``` + +Súbory sa zapisujú do `/logs//` pre každú reláciu požiadavky. + +## Režimy zlyhania a odolnosť + +## 1) Dostupnosť účtu/poskytovateľa + +- Ochladenie účtu poskytovateľa pri prechodných chybách/chybách rýchlosti/autorizácie +- záložný účet pred neúspešnou žiadosťou +- záložný kombinovaný model, keď je vyčerpaná aktuálna cesta modelu/poskytovateľa + +## 2) Vypršanie platnosti tokenu + +- predbežná kontrola a obnovenie s opätovným pokusom pre poskytovateľov obnoviteľných zdrojov +- 401/403 zopakovanie po pokuse o obnovenie v základnej ceste + +## 3) Bezpečnosť toku + +- regulátor prúdu s vedomím odpojenia +- tok prekladu s vyprázdnením konca toku a spracovaním `[DONE]` +- záložný odhad použitia, keď chýbajú metadáta používania poskytovateľa + +## 4) Degradácia cloudovej synchronizácie + +- Objavia sa chyby synchronizácie, ale lokálny runtime pokračuje +- plánovač má logiku schopnú opakovania, ale pravidelné vykonávanie v súčasnosti štandardne volá synchronizáciu na jeden pokus + +## 5) Integrita údajov + +- Migrácia/oprava tvaru DB pre chýbajúce kľúče +- poškodené ochranné prvky obnovenia JSON pre localDb a useDb + +## Pozorovateľnosť a prevádzkové signály + +Zdroje viditeľnosti pri spustení: + +- protokoly konzoly z `src/sse/utils/logger.ts` +- súhrny využitia na žiadosť v `usage.json` +- prihlásenie stavu textovej požiadavky `log.txt` +- voliteľné protokoly hlbokých požiadaviek/prekladov pod `logs/`, keď `ENABLE_REQUEST_LOGS=true` + – koncové body používania dashboardu (`/api/usage/*`) pre spotrebu používateľského rozhrania + +## Hranice citlivé na bezpečnosť + +- Tajný kľúč JWT (`JWT_SECRET`) zabezpečuje overenie/podpísanie súboru cookie relácie dashboardu +- Počiatočné záložné heslo (`INITIAL_PASSWORD`, predvolené `123456`) musí byť v reálnych nasadeniach prepísané +- Tajný kľúč API HMAC (`API_KEY_SECRET`) zabezpečuje vygenerovaný formát lokálneho kľúča API +- Tajomstvá poskytovateľa (kľúče/tokeny API) sú uložené v lokálnej databáze a mali by byť chránené na úrovni súborového systému +- Koncové body cloudovej synchronizácie sa spoliehajú na sémantiku kľúča API + ID stroja + +## Prostredie a Runtime Matrix + +Premenné prostredia aktívne používané kódom: + +- Aplikácia/autorizácia: `JWT_SECRET`, `INITIAL_PASSWORD` +- Úložisko: `DATA_DIR` +- Kompatibilné správanie uzla: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` +- Voliteľné prepísanie základne úložiska (Linux/macOS, keď `DATA_DIR` nie je nastavené): `XDG_CONFIG_HOME` + – Bezpečnostné hashovanie: `API_KEY_SECRET`, `MACHINE_ID_SALT` +- Prihlásenie: `ENABLE_REQUEST_LOGS` + – Synchronizácia/cloudové URL: `NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_CLOUD_URL` + – Outbound proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` a varianty s malými písmenami +- Príznaky funkcie SOCKS5: `ENABLE_SOCKS5_PROXY`, `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` + – Pomocníci platformy/behu (nie konfigurácia špecifická pre aplikáciu): `APPDATA`, `NODE_ENV`, `PORT`, `HOSTNAME` + +## Známe architektonické poznámky + +1. `usageDb` a `localDb` teraz zdieľajú rovnakú politiku základného adresára (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) s migráciou starších súborov. +2. `/api/v1/route.ts` vracia statický zoznam modelov a nie je hlavným zdrojom modelov, ktorý používa `/v1/models`. +3. Požiadavka zapisovača zapíše úplné hlavičky/telo, keď je povolené; považovať adresár denníka za citlivý. +4. Správanie cloudu závisí od správneho `NEXT_PUBLIC_BASE_URL` a dostupnosti koncového bodu cloudu. +5. Adresár `open-sse/` je publikovaný ako balík pracovného priestoru `@omniroute/open-sse` **npm**. Zdrojový kód ho importuje cez `@omniroute/open-sse/...` (vyriešené Next.js `transpilePackages`). Cesty k súborom v tomto dokumente stále používajú názov adresára `open-sse/` kvôli konzistencii. +6. Grafy na ovládacom paneli používajú **Recharts** (založené na SVG) na prístupné interaktívne analytické vizualizácie (stĺpcové grafy používania modelov, tabuľky rozdelenia poskytovateľov s mierou úspešnosti). +7. E2E testy používajú **Playwright** (`tests/e2e/`), prebiehajú cez `npm run test:e2e`. Testy jednotiek používajú **Node.js test runner** (`tests/unit/`), spúšťajú sa cez `npm run test:plan3`. Zdrojový kód pod `src/` je **TypeScript** (`.ts`/`.tsx`); pracovný priestor `open-sse/` zostáva JavaScriptom (`.js`). +8. Stránka s nastaveniami je usporiadaná do 5 záložiek: Zabezpečenie, Smerovanie (6 globálnych stratégií: fill-first, round-robin, p2c, náhodné, najmenej používané, nákladovo optimalizované), Resilience (upraviteľné limity sadzieb, istič, politiky), AI (rozpočet na myslenie, systémová výzva, prompt cache), Advanced (proxy). + +## Kontrolný zoznam overenia prevádzky + +- Zostavte zo zdroja: `npm run build` +- Vytvoriť obrázok Docker: `docker build -t omniroute .` +- Spustite službu a overte: +- `GET /api/settings` +- `GET /api/v1/models` +- Základná adresa URL cieľového CLI by mala byť `http://:20128/v1`, keď `PORT=20128` diff --git a/docs/i18n/sk/CODEBASE_DOCUMENTATION.md b/docs/i18n/sk/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..c8c77ce839 --- /dev/null +++ b/docs/i18n/sk/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,589 @@ +# omniroute — dokumentácia kódovej základne + +🌐 **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) + +> Komplexný sprievodca **omniroute** multi-poskytovateľa AI proxy routera pre začiatočníkov. + +--- + +## 1. Čo je omniroute? + +omniroute je **proxy router**, ktorý sedí medzi klientmi AI (Claude CLI, Codex, Cursor IDE atď.) a poskytovateľmi AI (Anthropic, Google, OpenAI, AWS, GitHub atď.). Rieši jeden veľký problém: + +> **Rôzni klienti AI hovoria rôznymi „jazykmi“ (formáty API) a rôzni poskytovatelia AI tiež očakávajú rôzne „jazyky“.** omniroute medzi nimi automaticky prekladá. + +Predstavte si to ako univerzálny prekladateľ v Organizácii Spojených národov – každý delegát môže hovoriť akýmkoľvek jazykom a prekladateľ ho prevedie na akéhokoľvek iného delegáta. + +--- + +## 2. Prehľad architektúry + +```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 +``` + +### Základný princíp: Hub-and-Spoke Translation + +Celý preklad formátu prechádza cez **formát OpenAI ako centrum**: + +``` +Client Format → [OpenAI Hub] → Provider Format (request) +Provider Format → [OpenAI Hub] → Client Format (response) +``` + +To znamená, že potrebujete iba **N prekladateľov** (jeden na formát) namiesto **N²** (každý pár). + +--- + +## 3. Štruktúra projektu + +``` +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. Rozdelenie podľa jednotlivých modulov + +### 4.1 Config (`open-sse/config/`) + +**Jediný zdroj pravdy** pre všetky konfigurácie poskytovateľov. + +| Súbor | Účel | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `constants.ts` | `PROVIDERS` objekt so základnými adresami URL, povereniami OAuth (predvolené), hlavičkami a predvolenými systémovými výzvami pre každého poskytovateľa. Definuje tiež `HTTP_STATUS`, `ERROR_TYPES`, `COOLDOWN_MS`, `BACKOFF_CONFIG` a `SKIP_PATTERNS`. | +| `credentialLoader.ts` | Načíta externé poverenia z `data/provider-credentials.json` a zlúči ich s pevne zakódovanými predvolenými nastaveniami v `PROVIDERS`. Udržuje tajomstvá mimo kontroly zdroja pri zachovaní spätnej kompatibility. | +| `providerModels.ts` | Centrálny register modelov: mapuje aliasy poskytovateľa → ID modelov. Funkcie ako `getModels()`, `getProviderByAlias()`. | +| `codexInstructions.ts` | Systémové pokyny vložené do požiadaviek kódexu (obmedzenia úprav, pravidlá karantény, zásady schvaľovania). | +| `defaultThinkingSignature.ts` | Predvolené „mysliace“ podpisy pre modely Claude a Gemini. | +| `ollamaModels.ts` | Definícia schémy pre lokálne modely Ollama (názov, veľkosť, rodina, kvantizácia). | + +#### Tok načítania poverení + +```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 Vykonávatelia (`open-sse/executors/`) + +Vykonávatelia zapuzdrujú **logiku špecifickú pre poskytovateľa** pomocou **Strategy Pattern**. Každý exekútor podľa potreby prepíše základné metódy. + +```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 +``` + +| Exekútor | Poskytovateľ | Kľúčové špecializácie | +| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `base.ts` | — | Abstraktný základ: vytváranie URL, hlavičky, logika opakovania, obnovenie poverení | +| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Obnovenie všeobecného tokenu OAuth pre štandardných poskytovateľov | +| `antigravity.ts` | Google Cloud Code | Generovanie ID projektu/relácie, záložné riešenie s viacerými adresami URL, vlastná opätovná analýza chybových hlásení ("resetovať po 2h7m23s") | +| `cursor.ts` | Kurzor IDE | **Najkomplexnejšie**: overenie kontrolného súčtu SHA-256, kódovanie požiadavky Protobuf, binárny prúd udalostí → analýza odpovede SSE | +| `codex.ts` | Kódex OpenAI | Vkladá systémové pokyny, riadi úrovne myslenia, odstraňuje nepodporované parametre | +| `gemini-cli.ts` | Google Gemini CLI | Vytvorenie vlastnej adresy URL (`streamGenerateContent`), obnovenie tokenu Google OAuth | +| `github.ts` | GitHub Copilot | Systém duálneho tokenu (GitHub OAuth + token Copilot), napodobňovanie hlavičky VSCode | +| `kiro.ts` | AWS CodeWhisperer | Binárne analyzovanie AWS EventStream, rámce udalostí AMZN, odhad tokenu | +| `index.ts` | — | Továreň: názov poskytovateľa máp → trieda vykonávateľa, s predvolenou rezervou | + +--- + +### 4.3 obslužné nástroje (`open-sse/handlers/`) + +**orchestačná vrstva** – koordinuje preklad, vykonávanie, streamovanie a spracovanie chýb. + +| Súbor | Účel | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `chatCore.ts` | **Central orchestrator** (~600 lines). Zvláda celý životný cyklus požiadavky: detekcia formátu → preklad → odoslanie vykonávateľa → odozva streamovania/nestreamovania → obnovenie tokenu → spracovanie chýb → protokolovanie používania. | +| `responsesHandler.ts` | Adaptér pre API Responses API OpenAI: konvertuje formát odpovedí → Dokončenia chatu → odosiela do `chatCore` → konvertuje SSE späť na formát odpovedí. | +| `embeddings.ts` | Obslužný program generovania vkladania: rieši model vkladania → poskytovateľ, odošle poskytovateľovi API, vracia odpoveď na vkladanie kompatibilnú s OpenAI. Podporuje 6+ poskytovateľov. | +| `imageGeneration.ts` | Obslužný program generovania obrázkov: rieši obrazový model → poskytovateľ, podporuje režimy kompatibilné s OpenAI, Gemini-image (Antigravity) a núdzový režim (Nebius). Vráti base64 alebo obrázky URL. | + +#### Životný cyklus žiadosti (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 Služby (`open-sse/services/`) + +Obchodná logika, ktorá podporuje manipulátory a vykonávateľov. + +| Súbor | Účel | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider.ts` | **Detekcia formátu** (`detectFormat`): analyzuje štruktúru tela požiadavky na identifikáciu formátov Claude/OpenAI/Gemini/Antigravity/Responses (zahŕňa heuristiku `max_tokens` pre Claude). Tiež: vytváranie adries URL, vytváranie hlavičiek, normalizácia konfigurácie myslenia. Podporuje dynamických poskytovateľov `openai-compatible-*` a `anthropic-compatible-*`. | +| `model.ts` | Analýza reťazca modelu (`claude/model-name` → `{provider: "claude", model: "model-name"}`), rozlíšenie alias s detekciou kolízií, dezinfekcia vstupu (odmietne prechádzanie cesty/riadiace znaky) a rozlíšenie informácií o modeli s podporou asynchrónneho získavania aliasov. | +| `accountFallback.ts` | Spracovanie limitu rýchlosti: exponenciálne stiahnutie (1s → 2s → 4s → max 2min), správa ochladzovania účtu, klasifikácia chýb (ktoré chyby spúšťajú záložné riešenie a nie). | +| `tokenRefresh.ts` | Obnovenie tokenu OAuth pre **každého poskytovateľa**: Google (Gemini, Antigravity), Claude, Codex, Qwen, iFlow, GitHub (dvojitý token OAuth + Copilot), Kiro (AWS SSO OIDC + Social Auth). Zahŕňa vyrovnávaciu pamäť na deduplikáciu sľubov počas letu a opakovanie s exponenciálnym sťahovaním. | +| `combo.ts` | **Kombinované modely**: reťazce záložných modelov. Ak model A zlyhá s chybou, ktorá je vhodná pre záložné riešenie, vyskúšajte model B, potom C atď. Vráti aktuálne stavové kódy proti prúdu. | +| `usage.ts` | Načítava údaje o kvótach/využívaní z rozhraní API poskytovateľa (kvóty GitHub Copilot, kvóty antigravitačného modelu, limity rýchlosti kódexu, rozpisy používania Kiro, nastavenia Claude). | +| `accountSelector.ts` | Inteligentný výber účtu s algoritmom hodnotenia: zohľadňuje prioritu, zdravotný stav, priebežnú pozíciu a stav chladenia, aby sa vybral optimálny účet pre každú požiadavku. | +| `contextManager.ts` | Správa životného cyklu kontextu požiadavky: vytvára a sleduje kontextové objekty pre každú požiadavku s metadátami (ID požiadavky, časové pečiatky, informácie o poskytovateľovi) na ladenie a protokolovanie. | +| `ipFilter.ts` | Riadenie prístupu na základe IP: podporuje režimy zoznamu povolených a blokovaných. Pred spracovaním požiadaviek API overí IP klienta podľa nakonfigurovaných pravidiel. | +| `sessionManager.ts` | Sledovanie relácií pomocou odtlačkov prstov klienta: sleduje aktívne relácie pomocou hashovaných identifikátorov klienta, monitoruje počet žiadostí a poskytuje metriky relácie. | +| `signatureCache.ts` | Vyrovnávacia pamäť pre deduplikáciu založenú na podpisoch: zabraňuje duplicitným požiadavkám tým, že ukladá do vyrovnávacej pamäte posledné podpisy požiadaviek a vracia odpovede uložené vo vyrovnávacej pamäti pre identické požiadavky v rámci časového okna. | +| `systemPrompt.ts` | Globálne vloženie systémovej výzvy: predpíše alebo pridá konfigurovateľnú systémovú výzvu ku všetkým požiadavkám so spracovaním kompatibility jednotlivých poskytovateľov. | +| `thinkingBudget.ts` | Správa rozpočtu tokenu uvažovania: podporuje režimy passthrough, auto (konfigurácia uvažovania v pásme), vlastné (pevný rozpočet) a adaptívne (škálované na komplexnosť) na riadenie tokenov myslenia/uvažovania. | +| `wildcardRouter.ts` | Smerovanie vzoru zástupných znakov: rozdeľuje vzory zástupných znakov (napr. `*/claude-*`) na konkrétne páry poskytovateľ/model na základe dostupnosti a priority. | + +#### Deduplikácia obnovenia tokenu + +```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 +``` + +#### Stav záložného účtu + +```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 + } +``` + +#### Kombinovaný modelový reťazec + +```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 Translator (`open-sse/translator/`) + +**Formátový prekladový nástroj** využívajúci samoregistračný systém doplnkov. + +#### Architektúra + +```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 +``` + +| Adresár | Súbory | Popis | +| ------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `request/` | 8 prekladateľov | Prevod tela požiadaviek medzi formátmi. Každý súbor sa pri importe sám zaregistruje prostredníctvom `register(from, to, fn)`. | +| `response/` | 7 prekladateľov | Konvertujte časti odozvy streamovania medzi formátmi. Zvláda typy udalostí SSE, bloky myslenia, volania nástrojov. | +| `helpers/` | 6 pomocníkov | Zdieľané nástroje: `claudeHelper` (extrakcia systémového promptu, konfigurácia myslenia), `geminiHelper` (mapovanie častí/obsahu), `openaiHelper` (filtrovanie formátu), `toolCallHelper` (generovanie ID**OMNI_TOKEN), 1**OMNI_TOKEN1 `responsesApiHelper`. | +| `index.ts` | — | Prekladový stroj: `translateRequest()`, `translateResponse()`, správa štátu, registratúra. | +| `formats.ts` | — | Formátové konštanty: `OPENAI`, `CLAUDE`, `GEMINI`, `ANTIGRAVITY`, `KIRO`, **OMNI*TOKEN_92_TOKEN*, **OMNI*TOKEN_92_TOKEN* | + +#### Kľúčový dizajn: Samoregistračné doplnky + +```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/`) + +| Súbor | Účel | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `error.ts` | Vytváranie odozvy na chyby (formát kompatibilný s OpenAI), analyzovanie chýb upstream, extrakcia opakovania antigravitácie z chybových správ, streamovanie chýb SSE. | +| `stream.ts` | **SSE Transform Stream** – hlavný streamingový kanál. Dva režimy: `TRANSLATE` (preklad plného formátu) a `PASSTHROUGH` (normalizácia + extrahovanie). Rieši ukladanie kúskov do vyrovnávacej pamäte, odhad využitia, sledovanie dĺžky obsahu. Inštancie kódovača/dekodéra podľa prúdu sa vyhýbajú zdieľanému stavu. | +| `streamHelpers.ts` | Nízkoúrovňové nástroje SSE: `parseSSELine` (tolerujúce biele miesta), `hasValuableContent` (filtruje prázdne časti pre OpenAI/Claude/Gemini), `fixInvalidId`, `formatSSE` (sériový formát so SformatSE\_) `perf_metrics` čistenie). | +| `usageTracking.ts` | Extrakcia použitia tokenov z ľubovoľného formátu (Claude/OpenAI/Gemini/Responses), odhad so samostatnými pomermi znakov na token/nástroje/správy, pridanie do vyrovnávacej pamäte (bezpečnostná rezerva 2000 tokenov), filtrovanie polí podľa formátu, protokolovanie konzoly s farbami ANSI. | +| `requestLogger.ts` | Protokolovanie žiadostí na základe súborov (prihlásenie cez `ENABLE_REQUEST_LOGS=true`). Vytvára priečinky relácie s očíslovanými súbormi: `1_req_client.json` → `7_res_client.txt`. Všetky I/O sú asynchrónne (fire-and-forget). Maskuje citlivé hlavičky. | +| `bypassHandler.ts` | Zachytáva špecifické vzory z Claude CLI (extrakcia titulov, zahrievanie, počet) a vracia falošné odpovede bez volania akéhokoľvek poskytovateľa. Podporuje streamovanie aj nestreamovanie. Zámerne obmedzené na rozsah Claude CLI. | +| `networkProxy.ts` | Vyrieši adresu URL odchádzajúcej proxy pre daného poskytovateľa s prioritou: konfigurácia špecifická pre poskytovateľa → globálna konfigurácia → premenné prostredia (`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`). Podporuje `NO_PROXY` vylúčenia. Konfiguráciu vyrovnávacej pamäte na 30 sekúnd. | + +#### Streamovací kanál 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 +``` + +#### Požiadať o štruktúru relácie zapisovača + +``` +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 Aplikačná vrstva (`src/`) + +| Adresár | Účel | +| ------------- | --------------------------------------------------------------------------------------------- | +| `src/app/` | Web UI, API routes, Express middleware, OAuth obslužné programy pre spätné volania | +| `src/lib/` | Prístup k databáze (`localDb.ts`, `usageDb.ts`), overenie, zdieľané | +| `src/mitm/` | Man-in-the-middle proxy nástroje na zachytenie prevádzky poskytovateľa | +| `src/models/` | Definície databázových modelov | +| `src/shared/` | Obal okolo funkcií open-sse (poskytovateľ, stream, chyba atď.) | +| `src/sse/` | Obslužné nástroje koncových bodov SSE, ktoré prepájajú knižnicu open-sse s expresnými cestami | +| `src/store/` | Správa stavu aplikácie | + +#### Pozoruhodné trasy API + +| Trasa | Metódy | Účel | +| --------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------- | +| `/api/provider-models` | ZÍSKAŤ/POSLAŤ/VYMAZAŤ | CRUD pre vlastné modely podľa poskytovateľa | +| `/api/models/catalog` | ZÍSKAJTE | Súhrnný katalóg všetkých modelov (chat, embedding, image, custom) zoskupený podľa poskytovateľa | +| `/api/settings/proxy` | GET/PUT/DELETE | Hierarchická konfigurácia outbound proxy (`global/providers/combos/keys`) | +| `/api/settings/proxy/test` | Zverejniť | Overí pripojenie proxy a vráti verejnú IP/latenciu | +| `/v1/providers/[provider]/chat/completions` | Zverejniť | Vyhradené dokončenia chatu podľa poskytovateľa s overením modelu | +| `/v1/providers/[provider]/embeddings` | Zverejniť | Vyhradené vloženia podľa jednotlivých poskytovateľov s overením modelu | +| `/v1/providers/[provider]/images/generations` | Zverejniť | Vyhradené generovanie obrázkov podľa poskytovateľa s overením modelu | +| `/api/settings/ip-filter` | GET/PUT | Správa zoznamu povolených/blokovaných IP | +| `/api/settings/thinking-budget` | GET/PUT | Konfigurácia rozpočtu tokenu odôvodnenia (priechodový/automatický/vlastný/adaptívny) | +| `/api/settings/system-prompt` | GET/PUT | Globálna systémová okamžitá injekcia pre všetky požiadavky | +| `/api/sessions` | ZÍSKAJTE | Sledovanie aktívnych relácií a metriky | +| `/api/rate-limits` | ZÍSKAJTE | Stav limitu sadzby na účet | + +--- + +## 5. Kľúčové dizajnové vzory + +### 5.1 Hub-and-Spoke preklad + +Všetky formáty sa prekladajú cez **formát OpenAI ako centrum**. Pridanie nového poskytovateľa vyžaduje iba napísanie **jedného páru** prekladateľov (do/z OpenAI), nie N párov. + +### 5.2 Vzor stratégie vykonávateľa + +Každý poskytovateľ má vyhradenú triedu spúšťača, ktorá zdedí z `BaseExecutor`. Továreň v `executors/index.ts` vyberie ten správny za behu. + +### 5.3 Systém zásuvných modulov s automatickou registráciou + +Moduly prekladateľov sa pri importe zaregistrujú prostredníctvom `register()`. Pridanie nového prekladača je len vytvorenie súboru a jeho importovanie. + +### 5.4 Zálohovanie účtu s exponenciálnym spätným odkladom + +Keď poskytovateľ vráti 429/401/500, systém sa môže prepnúť na ďalší účet, pričom použije exponenciálne cooldowny (1s → 2s → 4s → max 2min). + +### 5.5 Kombinované modelové reťaze + +„Komba“ zoskupuje viacero reťazcov `provider/model`. Ak prvý zlyhá, automaticky sa vráťte k ďalšiemu. + +### 5.6 Stavový preklad streamovania + +Preklad odozvy udržiava stav naprieč kúskami SSE (sledovanie blokov myslenia, akumulácia volaní nástrojov, indexovanie blokov obsahu) prostredníctvom mechanizmu `initState()`. + +### 5.7 Bezpečnostná vyrovnávacia pamäť používania + +K nahlásenému použitiu je pridaná vyrovnávacia pamäť s 2000 tokenmi, aby sa klientom zabránilo naraziť na limity kontextového okna kvôli réžii systémových výziev a prekladu formátu. + +--- + +## 6. Podporované formáty + +| Formát | Smer | Identifikátor | +| ----------------------- | ------------ | ------------------ | +| Dokončenia chatu OpenAI | zdroj + cieľ | `openai` | +| OpenAI Responses API | zdroj + cieľ | `openai-responses` | +| Antropický Claude | zdroj + cieľ | `claude` | +| Google Gemini | zdroj + cieľ | `gemini` | +| Google Gemini CLI | iba cieľ | `gemini-cli` | +| Antigravitácia | zdroj + cieľ | `antigravity` | +| AWS Kiro | iba cieľ | `kiro` | +| Kurzor | iba cieľ | `cursor` | + +--- + +## 7. Podporovaní poskytovatelia + +| Poskytovateľ | Spôsob overenia | Exekútor | Kľúčové poznámky | +| ------------------------ | --------------------------------- | -------------- | -------------------------------------------------------------- | +| Antropický Claude | API kľúč alebo OAuth | Predvolené | Používa hlavičku `x-api-key` | +| Google Gemini | API kľúč alebo OAuth | Predvolené | Používa hlavičku `x-goog-api-key` | +| Google Gemini CLI | OAuth | GeminiCLI | Používa koncový bod `streamGenerateContent` | +| Antigravitácia | OAuth | Antigravitácia | Záložná ochrana viacerých adries URL, vlastná opätovná analýza | +| OpenAI | API kľúč | Predvolené | Štandardné overenie nosiča | +| Kódex | OAuth | Kódex | Vkladá systémové pokyny, riadi myslenie | +| GitHub Copilot | OAuth + token Copilot | Github | Dvojitý token, hlavička VSCode napodobňujúca | +| Kiro (AWS) | AWS SSO OIDC alebo sociálne siete | Kiro | Analýza binárneho EventStreamu | +| Kurzor IDE | Overenie kontrolného súčtu | Kurzor | Kódovanie Protobuf, kontrolné súčty SHA-256 | +| Qwen | OAuth | Predvolené | Štandardné overenie | +| iFlow | OAuth (základný + nosič) | Predvolené | Hlavička s dvojitým overením | +| OpenRouter | API kľúč | Predvolené | Štandardné overenie nosiča | +| GLM, Kimi, MiniMax | API kľúč | Predvolené | Kompatibilné s Claude, použite `x-api-key` | +| `openai-compatible-*` | API kľúč | Predvolené | Dynamický: akýkoľvek koncový bod kompatibilný s OpenAI | +| `anthropic-compatible-*` | API kľúč | Predvolené | Dynamický: akýkoľvek koncový bod kompatibilný s Claude | + +--- + +## 8. Zhrnutie toku údajov + +### Žiadosť o streamovanie + +```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()"] +``` + +### Žiadosť o nestreamovanie + +```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"] +``` + +### Obtokový tok (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/sk/FEATURES.md b/docs/i18n/sk/FEATURES.md new file mode 100644 index 0000000000..bc9623e64d --- /dev/null +++ b/docs/i18n/sk/FEATURES.md @@ -0,0 +1,77 @@ +# OmniRoute — Galéria funkcií ovládacieho panela + +🌐 **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álny sprievodca každou sekciou ovládacieho panela OmniRoute. + +--- + +## 🔌 Poskytovatelia + +Spravujte pripojenia poskytovateľov AI: poskytovatelia OAuth (Claude Code, Codex, Gemini CLI), poskytovatelia kľúčov API (Groq, DeepSeek, OpenRouter) a bezplatní poskytovatelia (iFlow, Qwen, Kiro). + +![Providers Dashboard](screenshots/01-providers.png) + +--- + +## 🎨 Kombinácie + +Vytvorte kombá smerovania modelov pomocou 6 stratégií: vyplňte ako prvé, s každým ďalším, s možnosťou dvoch možností, náhodné, najmenej používané a nákladovo optimalizované. Každé kombo spája viacero modelov s automatickým vrátením. + +![Combos Dashboard](screenshots/02-combos.png) + +--- + +## 📊 Analytics + +Komplexná analýza používania so spotrebou tokenov, odhadmi nákladov, teplotnými mapami aktivít, týždennými distribučnými grafmi a rozpismi podľa poskytovateľov. + +![Analytics Dashboard](screenshots/03-analytics.png) + +--- + +## 🏥 Zdravie systému + +Monitorovanie v reálnom čase: dostupnosť, pamäť, verzia, percentily latencie (p50/p95/p99), štatistiky vyrovnávacej pamäte a stavy ističov poskytovateľa. + +![Health Dashboard](screenshots/04-health.png) + +--- + +## 🔧 Ihrisko pre prekladateľov + +Štyri režimy ladenia prekladov API: **Playground** (konvertor formátov), **Chat Tester** (živé požiadavky), **Test Bench** (dávkové testy) a **Live Monitor** (stream v reálnom čase). + +![Translator Playground](screenshots/05-translator.png) + +--- + +## ⚙️ Nastavenia + +Všeobecné nastavenia, systémové úložisko, správa záloh (export/import databázy), vzhľad (tmavý/svetlý režim), bezpečnosť (zahŕňa ochranu koncového bodu API a blokovanie vlastného poskytovateľa), smerovanie, odolnosť a pokročilú konfiguráciu. + +![Settings Dashboard](screenshots/06-settings.png) + +--- + +## 🔧 Nástroje CLI + +Konfigurácia nástrojov na kódovanie AI jedným kliknutím: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code a Antigravity. + +![CLI Tools Dashboard](screenshots/07-cli-tools.png) + +--- + +## 📝 Vyžiadanie denníkov + +Protokolovanie požiadaviek v reálnom čase s filtrovaním podľa poskytovateľa, modelu, účtu a kľúča API. Zobrazuje stavové kódy, využitie tokenu, latenciu a podrobnosti o odozve. + +![Usage Logs](screenshots/08-usage.png) + +--- + +## 🌐 Koncový bod API + +Váš zjednotený koncový bod API s rozdelením schopností: Dokončenia chatu, Vloženie, Generovanie obrázkov, Zmena poradia, Prepis zvuku a registrované kľúče API. + +![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/sk/TROUBLESHOOTING.md b/docs/i18n/sk/TROUBLESHOOTING.md new file mode 100644 index 0000000000..f16dd6bbcc --- /dev/null +++ b/docs/i18n/sk/TROUBLESHOOTING.md @@ -0,0 +1,221 @@ +# Riešenie problémov + +🌐 **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) + +Bežné problémy a riešenia pre OmniRoute. + +--- + +## Rýchle opravy + +| Problém | Riešenie | +| ----------------------------------------------- | ----------------------------------------------------------------------- | +| Prvé prihlásenie nefunguje | Skontrolujte `INITIAL_PASSWORD` v `.env` (predvolené: `123456`) | +| Prístrojová doska sa otvára na nesprávnom porte | Nastaviť `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| Žiadne záznamy žiadostí pod `logs/` | Nastaviť `ENABLE_REQUEST_LOGS=true` | +| EACCES: povolenie zamietnuté | Nastaviť `DATA_DIR=/path/to/writable/dir` na prepísanie `~/.omniroute` | +| Stratégia smerovania sa neukladá | Aktualizácia na v1.4.11+ (Oprava schémy Zod pre pretrvávanie nastavení) | + +--- + +## Problémy s poskytovateľom + +### „Jazykový model neposkytol správy“ + +**Príčina:** Kvóta poskytovateľa je vyčerpaná. + +**Oprava:** + +1. Skontrolujte sledovanie kvót palubnej dosky +2. Použite kombináciu so záložnými vrstvami +3. Prejdite na lacnejšiu/bezplatnú úroveň + +### Obmedzenie sadzieb + +**Príčina:** Kvóta odberov je vyčerpaná. + +**Oprava:** + +– Pridať záložnú: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` + +- Použite GLM/MiniMax ako lacnú zálohu + +### Platnosť tokenu OAuth vypršala + +OmniRoute automaticky obnovuje tokeny. Ak problémy pretrvávajú: + +1. Dashboard → Provider → Reconnect +2. Odstráňte a znova pridajte pripojenie poskytovateľa + +--- + +## Problémy s cloudom + +### Chyby synchronizácie cloudu + +1. Overte `BASE_URL` body na vašu spustenú inštanciu (napr. `http://localhost:20128`) +2. Overte `CLOUD_URL` bodov do vášho koncového bodu cloudu (napr. `https://omniroute.dev`) +3. Ponechajte hodnoty `NEXT_PUBLIC_*` zarovnané s hodnotami na strane servera + +### Cloud `stream=false` Vrátenie 500 + +**Príznak:** `Unexpected token 'd'...` na koncovom bode cloudu pre hovory bez streamovania. + +**Príčina:** Upstream vracia užitočné zaťaženie SSE, zatiaľ čo klient očakáva JSON. + +**Náhradné riešenie:** Na priame hovory v cloude použite `stream=true`. Miestne prostredie runtime zahŕňa záložnú verziu SSE→JSON. + +### Cloud hovorí Pripojené, ale „neplatný kľúč API“ + +1. Vytvorte nový kľúč z miestneho informačného panela (`/api/keys`) +2. Spustite synchronizáciu s cloudom: Povoliť cloud → Synchronizovať teraz +3. Staré/nesynchronizované kľúče môžu stále vrátiť `401` v cloude + +--- + +## Problémy s Dockerom + +### Nástroj CLI zobrazuje, že nie je nainštalované + +1. Skontrolujte polia runtime: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` +2. Pre prenosný režim: použite cieľový obrázok `runner-cli` (pribalené CLI) +3. Pre režim pripojenia hostiteľa: nastavte `CLI_EXTRA_PATHS` a pripojte adresár hostiteľského bin ako len na čítanie +4. Ak sa našli `installed=true` a `runnable=false`: binárne súbory, ale neprešli kontrolou stavu + +### Rýchla prevádzková validácia + +```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}' +``` + +--- + +## Problémy s nákladmi + +### Vysoké náklady + +1. Skontrolujte štatistiky používania v Dashboard → Usage +2. Prepnite primárny model na GLM/MiniMax +3. Na nekritické úlohy používajte bezplatnú vrstvu (Gemini CLI, iFlow). +4. Nastavte rozpočty nákladov na kľúč API: Dashboard → API Keys → Budget + +--- + +## Ladenie + +### Povoliť protokoly požiadaviek + +Nastavte `ENABLE_REQUEST_LOGS=true` vo svojom súbore `.env`. Protokoly sa zobrazujú v adresári `logs/`. + +### Skontrolujte zdravie poskytovateľa + +```bash +# Health dashboard +http://localhost:20128/dashboard/health + +# API health check +curl http://localhost:20128/api/monitoring/health +``` + +### Runtime Storage + +- Hlavný stav: `${DATA_DIR}/db.json` (poskytovatelia, kombá, aliasy, kľúče, nastavenia) +- Použitie: `${DATA_DIR}/usage.json`, `${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/` +- Denníky žiadostí: `/logs/...` (keď `ENABLE_REQUEST_LOGS=true`) + +--- + +## Problémy s ističom + +### Poskytovateľ je zaseknutý v stave OPEN + +Keď je istič poskytovateľa OTVORENÝ, požiadavky sú zablokované, kým nevyprší cooldown. + +**Oprava:** + +1. Prejdite na **Hlavný panel → Nastavenia → Odolnosť** +2. Skontrolujte kartu ističa príslušného poskytovateľa +3. Kliknite na **Reset All**, aby ste vymazali všetky ističe, alebo počkajte, kým uplynie cooldown +4. Pred resetovaním skontrolujte, či je poskytovateľ skutočne dostupný + +### Poskytovateľ neustále vypína istič + +Ak poskytovateľ opakovane prejde do stavu OTVORENÉ: + +1. Vzor zlyhania nájdete v **Dashboard → Health → Provider Health** +2. Prejdite na **Nastavenia → Odolnosť → Profily poskytovateľa** a zvýšte prah zlyhania +3. Skontrolujte, či poskytovateľ zmenil limity API alebo či nevyžaduje opätovné overenie +4. Skontrolujte telemetriu latencie – vysoká latencia môže spôsobiť zlyhania súvisiace s časovým limitom + +--- + +## Problémy s prepisom zvuku + +### Chyba „Nepodporovaný model“. + +- Uistite sa, že používate správnu predponu: `deepgram/nova-3` alebo `assemblyai/best` + – Overte, či je poskytovateľ pripojený v **Dashboard → Providers** + +### Prepis sa vráti prázdny alebo zlyhá + +- Skontrolujte podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm` +- Overte, či je veľkosť súboru v rámci limitov poskytovateľa (zvyčajne < 25 MB) +- Skontrolujte platnosť kľúča API poskytovateľa na karte poskytovateľa + +--- + +## Ladenie prekladača + +Na ladenie problémov s prekladom formátu použite **Dashboard → Translator**: + +| Režim | Kedy použiť | +| --------------------- | --------------------------------------------------------------------------------------------------------------- | +| **Ihrisko** | Porovnajte vstupné/výstupné formáty vedľa seba — prilepte neúspešnú požiadavku, aby ste videli, ako sa prekladá | +| **Tester chatu** | Posielajte živé správy a skontrolujte celý obsah žiadosti/odpovede vrátane hlavičiek | +| **Testovacia lavica** | Spustite dávkové testy kombinácií formátov, aby ste zistili, ktoré preklady sú poškodené | +| **Živý monitor** | Sledujte tok žiadostí v reálnom čase, aby ste zachytili občasné problémy s prekladom | + +### Bežné problémy s formátom + +- **Značky myslenia sa nezobrazujú** — Skontrolujte, či cieľový poskytovateľ podporuje myslenie a nastavenie rozpočtu na myslenie +- **Volania nástrojov klesajú** – Niektoré preklady formátov môžu odstrániť nepodporované polia; overiť v režime Playground +- **Chýba systémová výzva** – Claude a Gemini riešia výzvy systému odlišne; skontrolujte výstup prekladu + – **SDK vracia nespracovaný reťazec namiesto objektu** – Opravené vo verzii 1.1.0: nástroj na dezinfekciu odpovede teraz odstraňuje neštandardné polia (`x_groq`, `usage_breakdown` atď.), ktoré spôsobujú zlyhania overenia OpenAI SDK Pydantic +- **GLM/ERNIE odmieta rolu `system`** — Opravené vo verzii 1.1.0: normalizátor rolí automaticky zlučuje systémové správy do používateľských správ pre nekompatibilné modely + – **`developer` rola nebola rozpoznaná** – Opravené vo verzii 1.1.0: automaticky konvertované na `system` pre poskytovateľov, ktorí nie sú OpenAI + – **`json_schema` nefunguje s Gemini** – Opravené vo verzii 1.1.0: `response_format` je teraz prevedené na `responseMimeType` + `responseSchema` Gemini + +--- + +## Nastavenia odolnosti + +### Automatický limit rýchlosti sa nespustí + +- Automatický limit sadzby sa vzťahuje len na poskytovateľov kľúčov API (nie OAuth/predplatné) +- Skontrolujte, či je v **Nastaveniach → Odolnosť → Profily poskytovateľov** povolený automatický limit rýchlosti + – Skontrolujte, či poskytovateľ vracia `429` stavové kódy alebo hlavičky `Retry-After` + +### Ladenie exponenciálneho ústupu + +Profily poskytovateľov podporujú tieto nastavenia: + +- **Základné oneskorenie** — Počiatočná doba čakania po prvom zlyhaní (predvolené: 1 s) + – **Maximálne oneskorenie** – Obmedzenie maximálnej doby čakania (predvolené: 30 s) +- **Násobiteľ** – o koľko sa má predĺžiť oneskorenie pri následnom zlyhaní (predvolené: 2x) + +### Protihromové stádo + +Keď mnoho súbežných požiadaviek zasiahne poskytovateľa s obmedzenou rýchlosťou, OmniRoute použije mutex + automatické obmedzenie rýchlosti na serializáciu požiadaviek a zabránenie kaskádovým zlyhaniam. Toto je automatické pre poskytovateľov kľúčov API. + +--- + +## Stále ste uviazli? + +– **Problémy s GitHub**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) + +- **Architektúra**: Interné podrobnosti nájdete v [**OMNI_TOKEN_55**](ARCHITECTURE.md) +- **Referencia API**: Všetky koncové body nájdete na stránke [**OMNI_TOKEN_56**](API_REFERENCE.md) +- **Hlavný panel zdravia**: Skontrolujte stav systému v reálnom čase v časti **Hlavný panel → Zdravie** +- **Prekladač**: Na ladenie problémov s formátom použite **Dashboard → Translator** diff --git a/docs/i18n/sk/USER_GUIDE.md b/docs/i18n/sk/USER_GUIDE.md new file mode 100644 index 0000000000..2fcfde4600 --- /dev/null +++ b/docs/i18n/sk/USER_GUIDE.md @@ -0,0 +1,698 @@ +# Používateľská príručka + +🌐 **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) + +Kompletný sprievodca pre konfiguráciu poskytovateľov, vytváranie komb, integráciu nástrojov CLI a nasadenie OmniRoute. + +--- + +## Obsah + +- [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) + +--- + +## 💰 Prehľad cien + +| Úroveň | Poskytovateľ | Náklady | Obnovenie kvóty | Najlepšie pre | +| ----------------- | ----------------- | ------------------- | ---------------------------- | --------------------------- | +| **💳 PREDPLATNÉ** | Claude Code (Pro) | 20 USD/mesiac | 5h + týždenne | Už prihlásené | +| | Codex (Plus/Pro) | 20 – 200 USD/mesiac | 5h + týždenne | Používatelia OpenAI | +| | Gemini CLI | **ZADARMO** | 180 tis./mesiac + 1 tis./deň | Všetci! | +| | GitHub Copilot | 10 – 19 USD/mes. | Mesačne | Používatelia GitHubu | +| **🔑 API KEY** | DeepSeek | Platba za použitie | Žiadne | Lacné uvažovanie | +| | Groq | Platba za použitie | Žiadne | Ultra-rýchle odvodenie | +| | xAI (Grok) | Platba za použitie | Žiadne | Grok 4 zdôvodnenie | +| | Mistral | Platba za použitie | Žiadne | Modely hostené v EÚ | +| | Zmätok | Platba za použitie | Žiadne | Rozšírené vyhľadávanie | +| | Spolu AI | Platba za použitie | Žiadne | Modely s otvoreným zdrojom | +| | Ohňostroje AI | Platba za použitie | Žiadne | Fast FLUX obrázky | +| | Cerebras | Platba za použitie | Žiadne | Rýchlosť plátkovej stupnice | +| | Cohere | Platba za použitie | Žiadne | Príkaz R+ RAG | +| | NVIDIA NIM | Platba za použitie | Žiadne | Podnikové modely | +| **💰 LACNO** | GLM-4,7 | 0,6 USD/1 milión | Denne 10:00 | Záloha rozpočtu | +| | MiniMax M2.1 | 0,2 USD/1 milión | 5-hodinové valcovanie | Najlacnejšia možnosť | +| | Kimi K2 | 9 USD/mesiac byt | 10 miliónov tokenov/mesiac | Predvídateľné náklady | +| **🆓 ZDARMA** | iFlow | 0 USD | Neobmedzené | 8 modelov zadarmo | +| | Qwen | 0 USD | Neobmedzené | 3 modely zadarmo | +| | Kiro | 0 USD | Neobmedzené | Claude zadarmo | + +**💡 Tip pre profesionálov:** Začnite s kombináciou Gemini CLI (180 000 zadarmo/mesiac) + iFlow (neobmedzene zadarmo) = cena 0 $! + +--- + +## 🎯 Prípady použitia + +### Prípad 1: „Mám predplatné Claude Pro“ + +**Problém:** Platnosť kvóty vyprší nevyužitá, obmedzenia sadzieb počas náročného kódovania + +``` +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 +``` + +### Prípad 2: „Chcem nulové náklady“ + +**Problém:** Nemôžem si dovoliť predplatné, potrebujem spoľahlivé kódovanie 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 +``` + +### Prípad 3: „Potrebujem kódovanie 24/7, žiadne prerušenia“ + +**Problém:** Termíny, nemôžem si dovoliť prestoje + +``` +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) +``` + +### Prípad 4: „Chcem AI ZDARMA v OpenClaw“ + +**Problém:** Potrebujete asistenta AI v aplikáciách na odosielanie správ, úplne zadarmo + +``` +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... +``` + +--- + +## 📖 Nastavenie poskytovateľa + +### 🔐 Poskytovatelia predplatného + +#### 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 +``` + +**Tip pre profesionálov:** Používajte Opus na zložité úlohy, Sonnet na rýchlosť. OmniRoute sleduje kvótu na model! + +#### 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 (ZADARMO 180 000/mesiac!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Najlepšia hodnota:** Obrovská bezplatná úroveň! Použite to pred platenými úrovňami. + +#### GitHub Copilot + +```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 +``` + +### 💰 Lacní poskytovatelia + +#### GLM-4,7 (denný reset, 0,6 $/1 milión) + +1. Zaregistrujte sa: [Zhipu AI](https://open.bigmodel.cn/) +2. Získajte kľúč API z plánu kódovania +3. Dashboard → Pridať kľúč API: Poskytovateľ: `glm`, kľúč API: `your-key` + +**Použite:** `glm/glm-4.7` — **Tip pre profesionálov:** Kódovací plán ponúka 3× kvótu za 1/7 cenu! Resetovať denne o 10:00. + +#### MiniMax M2.1 (5h reset, $0.20/1M) + +1. Zaregistrujte sa: [MiniMax](https://www.minimax.io/) +2. Získať kľúč API → Dashboard → Pridať kľúč API + +**Použitie:** `minimax/MiniMax-M2.1` — **Tip pre profesionálov:** Najlacnejšia možnosť pre dlhý kontext (1 milión tokenov)! + +#### Kimi K2 (9 USD/mesiac) + +1. Prihlásiť sa na odber: [Moonshot AI](https://platform.moonshot.ai/) +2. Získať kľúč API → Dashboard → Pridať kľúč API + +**Použitie:** `kimi/kimi-latest` — **Tip pre profesionálov:** Pevné 9 $/mesiac za 10 miliónov tokenov = 0,90 $/1 milión efektívnych nákladov! + +### 🆓 BEZPLATNÍ poskytovatelia + +#### iFlow (8 modelov ZDARMA) + +```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 modely ZDARMA) + +```bash +Dashboard → Connect Qwen → Device code auth → Unlimited usage + +Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash +``` + +#### Kiro (Claude FREE) + +```bash +Dashboard → Connect Kiro → AWS Builder ID or Google/GitHub → Unlimited + +Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 +``` + +--- + +## 🎨 Kombinácie + +### Príklad 1: Maximalizujte predplatné → Lacné zálohovanie + +``` +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 +``` + +### Príklad 2: Iba zadarmo (nulové náklady) + +``` +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! +``` + +--- + +## 🔧 Integrácia CLI + +### IDE kurzora + +``` +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 + +Upraviť `~/.claude/config.json`: + +```json +{ + "anthropic_api_base": "http://localhost:20128/v1", + "anthropic_api_key": "your-omniroute-api-key" +} +``` + +### Kódex CLI + +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" +codex "your prompt" +``` + +### OpenClaw + +Upraviť `~/.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" }] + } + } + } +} +``` + +**Alebo použite Dashboard:** Nástroje CLI → OpenClaw → Automatická konfigurácia + +### Cline / Pokračovať / RooCode + +``` +Provider: OpenAI Compatible +Base URL: http://localhost:20128/v1 +API Key: [from dashboard] +Model: cc/claude-opus-4-6 +``` + +--- + +## 🚀 Nasadenie + +### Nasadenie 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 +``` + +### 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 +``` + +Informácie o režime integrovanom s hostiteľom s binárnymi súbormi CLI nájdete v časti Docker v hlavných dokumentoch. + +### Premenné prostredia + +| Premenná | Predvolené | Popis | +| --------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | +| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajomstvo podpisu JWT (**zmena vo výrobe**) | +| `INITIAL_PASSWORD` | `123456` | Prvé prihlasovacie heslo | +| `DATA_DIR` | `~/.omniroute` | Adresár údajov (db, využitie, protokoly) | +| `PORT` | štandardný rámec | Servisný port (v príkladoch `20128`) | +| `HOSTNAME` | štandardný rámec | Bind host (Docker predvolene `0.0.0.0`) | +| `NODE_ENV` | runtime default | Nastaviť `production` na nasadenie | +| `BASE_URL` | `http://localhost:20128` | Interná základná adresa URL na strane servera | +| `CLOUD_URL` | `https://omniroute.dev` | Základná adresa URL koncového bodu synchronizácie v cloude | +| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Tajný kľúč HMAC pre vygenerované kľúče API | +| `REQUIRE_API_KEY` | `false` | Vynútiť kľúč rozhrania Bearer API na `/v1/*` | +| `ENABLE_REQUEST_LOGS` | `false` | Povolí protokoly požiadaviek/odpovedí | +| `AUTH_COOKIE_SECURE` | `false` | Vynútiť `Secure` autorizačný súbor cookie (za HTTPS reverzným proxy serverom) | + +Úplnú referenciu premenných prostredia nájdete v [README](../README.md). + +--- + +## 📊 Dostupné modely + +
+Zobraziť všetky dostupné modely + +**Claude Code (`cc/`)** — Pro/Max: `cc/claude-opus-4-6`, `cc/claude-sonnet-4-5-20250929`, `cc/claude-haiku-4-5-20251001` + +**Codex (`cx/`)** — Plus/Pro: `cx/gpt-5.2-codex`, `cx/gpt-5.1-codex-max` + +**Gemini CLI (`gc/`)** — ZDARMA: `gc/gemini-3-flash-preview`, `gc/gemini-2.5-pro` + +**GitHub Copilot (`gh/`)**: `gh/gpt-5`, `gh/claude-4.5-sonnet` + +**GLM (`glm/`)** – 0,6 USD/1 milión: `glm/glm-4.7` + +**MiniMax (`minimax/`)** – 0,2 USD/1 milión: `minimax/MiniMax-M2.1` + +**iFlow (`if/`)** — ZDARMA: `if/kimi-k2-thinking`, `if/qwen3-coder-plus`, `if/deepseek-r1` + +**Qwen (`qw/`)** – ZDARMA: `qw/qwen3-coder-plus`, `qw/qwen3-coder-flash` + +**Kiro (`kr/`)** – ZDARMA: `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` + +**Zmätok (`pplx/`)**: `pplx/sonar-pro`, `pplx/sonar` + +**Together AI (`together/`)**: `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` + +**Umelá inteligencia ohňostrojov (`fireworks/`)**: `fireworks/accounts/fireworks/models/deepseek-v3p1` + +**Cerebras (`cerebras/`)**: `cerebras/llama-3.3-70b` + +**Cohere (`cohere/`)**: `cohere/command-r-plus-08-2024` + +**NVIDIA NIM (`nvidia/`)**: `nvidia/nvidia/llama-3.3-70b-instruct` + +
+ +--- + +## 🧩 Pokročilé funkcie + +### Vlastné modely + +Pridajte akékoľvek ID modelu k akémukoľvek poskytovateľovi bez čakania na aktualizáciu aplikácie: + +```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" +``` + +Alebo použite Dashboard: **Poskytovatelia → [Poskytovateľ] → Vlastné modely**. + +### Vyhradené trasy poskytovateľa + +Smerujte požiadavky priamo ku konkrétnemu poskytovateľovi s overením modelu: + +```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 +``` + +Ak chýba predpona poskytovateľa, automaticky sa pridá. Nezhodné modely vrátia `400`. + +### Konfigurácia sieťového proxy + +```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"}}' +``` + +**Prednosť:** Špecifické pre kľúč → Špecifické pre kombináciu → Špecifické pre poskytovateľa → Globálne → Prostredie. + +### API katalógu modelov + +```bash +curl http://localhost:20128/api/models/catalog +``` + +Vráti modely zoskupené podľa poskytovateľa s typmi (`chat`, `embedding`, `image`). + +### Cloud Sync + +- Synchronizujte poskytovateľov, kombinácie a nastavenia medzi zariadeniami +- Automatická synchronizácia na pozadí s časovým limitom + rýchle zlyhanie +- Vo výrobe uprednostňujete `BASE_URL`/`CLOUD_URL` na strane servera + +### LLM Gateway Intelligence (9. fáza) + +- **Sémantická vyrovnávacia pamäť** – Automatické ukladanie do vyrovnávacej pamäte bez streamovania, teplota = 0 odoziev (obíďte pomocou `X-OmniRoute-No-Cache: true`) + – **Idempotencia žiadosti** – Deduplikuje žiadosti do 5 s prostredníctvom hlavičky `Idempotency-Key` alebo `X-Request-Id` + – **Sledovanie pokroku** – Prihláste sa do udalostí SSE `event: progress` prostredníctvom hlavičky `X-OmniRoute-Progress: true` + +--- + +### Ihrisko pre prekladateľov + +Prístup cez **Dashboard → Translator**. Laďte a vizualizujte, ako OmniRoute prekladá požiadavky API medzi poskytovateľmi. + +| Režim | Účel | +| --------------------- | ------------------------------------------------------------------------------------------ | +| **Ihrisko** | Vyberte zdrojové/cieľové formáty, vložte požiadavku a okamžite si pozrite preložený výstup | +| **Tester chatu** | Posielajte správy živého chatu cez proxy a skontrolujte celý cyklus žiadostí/odpovedí | +| **Testovacia lavica** | Spustite dávkové testy vo viacerých kombináciách formátov na overenie správnosti prekladu | +| **Živý monitor** | Sledujte preklady v reálnom čase, keď požiadavky prechádzajú cez server proxy | + +**Prípady použitia:** + +- Odlaďte, prečo konkrétna kombinácia klient/poskytovateľ zlyhá +- Overte, či sa značky myslenia, volania nástrojov a systémové výzvy prekladajú správne +- Porovnajte rozdiely medzi formátmi OpenAI, Claude, Gemini a Responses API + +--- + +### Stratégie smerovania + +Konfigurujte cez **Dashboard → Nastavenia → Smerovanie**. + +| Stratégia | Popis | +| ----------------------------- | ------------------------------------------------------------------------------------------------------ | +| **Vyplňte ako prvé** | Používa účty v poradí podľa priority – primárny účet spracováva všetky požiadavky, kým nie je dostupný | +| **Round Robin** | Prechádza cez všetky účty s konfigurovateľným fixným limitom (predvolené: 3 hovory na účet) | +| **P2C (sila dvoch možností)** | Vyberie 2 náhodné účty a cesty k zdravšiemu — vyrovnáva záťaž s uvedomením si zdravia | +| **Náhodné** | Náhodne vyberie účet pre každú požiadavku pomocou Fisher-Yates shuffle | +| **Najmenej používané** | Smeruje na účet s najstaršou časovou pečiatkou `lastUsedAt`, rovnomerne rozdeľuje návštevnosť | +| **Costovo optimalizované** | Smeruje na účet s najnižšou prioritou, optimalizácia pre poskytovateľov s najnižšou cenou | + +#### Aliasy modelu so zástupnými znakmi + +Vytvorte vzory zástupných znakov na premapovanie názvov modelov: + +``` +Pattern: claude-sonnet-* → Target: cc/claude-sonnet-4-5-20250929 +Pattern: gpt-* → Target: gh/gpt-5.1-codex +``` + +Zástupné znaky podporujú `*` (ľubovoľné znaky) a `?` (jeden znak). + +#### Záložné reťazce + +Definujte globálne záložné reťazce, ktoré platia pre všetky požiadavky: + +``` +Chain: production-fallback + 1. cc/claude-opus-4-6 + 2. gh/gpt-5.1-codex + 3. glm/glm-4.7 +``` + +--- + +### Odolnosť a ističe + +Konfigurujte cez **Dashboard → Nastavenia → Odolnosť**. + +OmniRoute implementuje odolnosť na úrovni poskytovateľa so štyrmi komponentmi: + +1. **Profily poskytovateľa** — Konfigurácia podľa jednotlivých poskytovateľov pre: + - Prah zlyhania (koľko porúch pred otvorením) + - Trvanie chladenia + - Citlivosť detekcie limitu rýchlosti + - Exponenciálne parametre backoff + +2. **Upraviteľné limity rýchlosti** — Predvolené nastavenia na úrovni systému konfigurovateľné na paneli: + - **Požiadavky za minútu (RPM)** – Maximálny počet žiadostí za minútu na účet + - **Min Time Between Requests** – Minimálna medzera v milisekundách medzi požiadavkami + - **Max Concurrent Requests** – Maximálny počet simultánnych požiadaviek na účet + - Kliknite na **Upraviť** a upravte, potom na **Uložiť** alebo **Zrušiť**. Hodnoty pretrvávajú prostredníctvom rozhrania API odolnosti. + +3. **Circuit Breaker** – Sleduje zlyhania podľa poskytovateľa a automaticky otvára okruh, keď sa dosiahne prah: + - **ZATVORENÉ** (zdravé) – požiadavky prebiehajú normálne + - **OPEN** — Poskytovateľ je po opakovaných zlyhaniach dočasne zablokovaný + - **HALF_OPEN** – Testuje sa, či sa poskytovateľ zotavil + +4. **Policies & Locked Identifiers** – Zobrazuje stav ističa a uzamknuté identifikátory s možnosťou vynútenia odomknutia. + +5. **Automatická detekcia limitu sadzby** — Monitoruje hlavičky `429` a `Retry-After`, aby sa proaktívne vyhlo prekročeniu limitov sadzby poskytovateľa. + +**Tip pre profesionálov:** Pomocou tlačidla **Resetovať všetko** vymažte všetky ističe a chladenia, keď sa poskytovateľ zotaví z výpadku. + +--- + +### Export/Import databázy + +Spravujte zálohy databázy v **Dashboard → Nastavenia → Systém a úložisko**. + +| Akcia | Popis | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| **Exportovať databázu** | Stiahne aktuálnu databázu SQLite ako súbor `.sqlite` | +| **Exportovať všetko (.tar.gz)** | Stiahne celý záložný archív vrátane: databázy, nastavení, kombinácií, pripojení poskytovateľa (bez poverení), metadát kľúča API | +| **Importovať databázu** | Ak chcete nahradiť aktuálnu databázu, nahrajte súbor `.sqlite`. Automaticky sa vytvorí záloha pred importom | + +```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" +``` + +**Overenie importu:** Overí sa integrita importovaného súboru (kontrola SQLite pragma), požadované tabuľky (`provider_connections`, `provider_nodes`, `combos`, \__OMNI_TOKEN_136_1_) a veľkosť (max. 0 MB). + +**Prípady použitia:** + +- Migrujte OmniRoute medzi strojmi +- Vytvorte externé zálohy na obnovu po havárii +- Zdieľanie konfigurácií medzi členmi tímu (exportovať všetko → zdieľať archív) + +--- + +### Panel nastavení + +Stránka nastavení je usporiadaná do 5 kariet pre jednoduchú navigáciu: + +| Tab | Obsah | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| **Bezpečnosť** | Nastavenia prihlasovacieho mena/hesla, riadenie prístupu IP, overenie API pre `/models` a blokovanie poskytovateľa | +| **Smerovanie** | Globálna stratégia smerovania (6 možností), aliasy modelu so zástupnými znakmi, záložné reťazce, predvolené nastavenia komba | +| **Odolnosť** | Profily poskytovateľov, upraviteľné limity sadzieb, stav ističa, zásady a zamknuté identifikátory | +| **AI** | Konfigurácia rozpočtu myslenia, rýchle vloženie globálneho systému, rýchle štatistiky vyrovnávacej pamäte | +| **Pokročilé** | Globálna konfigurácia proxy (HTTP/SOCKS5) | + +--- + +### Správa nákladov a rozpočtu + +Prístup cez **Dashboard → Náklady**. + +| Tab | Účel | +| ------------ | ---------------------------------------------------------------------------------------------------------- | +| **Rozpočet** | Nastavte limity výdavkov na kľúč API s dennými/týždennými/mesačnými rozpočtami a sledovaním v reálnom čase | +| **Ceny** | Zobrazenie a úprava položiek cien modelu – cena za 1 000 vstupných/výstupných tokenov na poskytovateľa | + +```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 +``` + +**Sledovanie nákladov:** Každá požiadavka zaznamenáva používanie tokenu a vypočítava náklady pomocou cenovej tabuľky. Pozrite si rozpisy v **Dashboard → Použitie** podľa poskytovateľa, modelu a kľúča API. + +--- + +### Zvukový prepis + +OmniRoute podporuje prepis zvuku cez koncový bod kompatibilný s 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" +``` + +Dostupní poskytovatelia: **Deepgram** (`deepgram/`), **AssemblyAI** (`assemblyai/`). + +Podporované zvukové formáty: `mp3`, `wav`, `m4a`, `flac`, `ogg`, \_\_OMNI_TOKEN_1. + +--- + +### Kombinované stratégie vyvažovania + +Nakonfigurujte vyváženie jednotlivých kombinácií v **Dashboard → Combos → Create/Edit → Strategy**. + +| Stratégia | Popis | +| ---------------------------- | --------------------------------------------------------------------------------------- | +| **Round-Robin** | Postupne rotuje medzi modelmi | +| **Priorita** | Vždy vyskúšajte prvý model; vracia sa len pri chybe | +| **Náhodné** | Vyberie náhodný model z kombinácie pre každú požiadavku | +| **Vážený** | Trasy proporcionálne na základe pridelených hmotností na model | +| **Najmenej používané** | Smeruje k modelu s najmenším počtom nedávnych požiadaviek (používa kombinovanú metriku) | +| **Nákladovo optimalizované** | Trasy k najlacnejšiemu dostupnému modelu (používa cenovú tabuľku) | + +Globálne predvolené nastavenia pre kombináciu je možné nastaviť v **Dashboard → Settings → Routing → Combo Defaults**. + +--- + +### Informačný panel zdravia + +Prístup cez **Dashboard → Health**. Prehľad stavu systému v reálnom čase so 6 kartami: + +| Karta | Čo ukazuje | +| ------------------------------- | ---------------------------------------------------------------------------- | +| **Stav systému** | Uptime, verzia, využitie pamäte, dátový adresár | +| **Zdravie poskytovateľa** | Stav ističa podľa poskytovateľa (zatvorené/otvorené/polootvorené) | +| **Obmedzenia sadzieb** | Aktívne zníženia rýchlosti limitu na účet so zostávajúcim časom | +| **Aktívne blokovania** | Poskytovatelia dočasne zablokovaní politikou uzamknutia | +| **Vyrovnávacia pamäť podpisov** | Štatistiky vyrovnávacej pamäte deduplikácie (aktívne kľúče, počet prístupov) | +| **Telemetria latencie** | p50/p95/p99 agregácia latencie podľa poskytovateľa | + +**Tip pre profesionálov:** Stránka Zdravie sa automaticky obnovuje každých 10 sekúnd. Pomocou karty ističa identifikujte, ktorí poskytovatelia majú problémy.