mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-05 06:42:12 +03:00
docs: add multi-language i18n documentation translations
Add translated documentation (API Reference, Guide, README) for 30+ languages under docs/i18n/, including pt-BR, es, fr, de, it, ru, zh-CN, ja, ko, ar, and many others to improve international accessibility.
This commit is contained in:
diegosouzapw
441
docs/i18n/pt-BR/API_REFERENCE.md
Normal file
441
docs/i18n/pt-BR/API_REFERENCE.md
Normal file
@@ -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`
|
||||
781
docs/i18n/pt-BR/ARCHITECTURE.md
Normal file
781
docs/i18n/pt-BR/ARCHITECTURE.md
Normal file
@@ -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 (`<think>...</think>`) 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: `<repo>/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 `<think>...</think>` 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 `<repo>/logs/<session>/` 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://<host>:20128/v1` quando `PORT=20128`
|
||||
589
docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md
Normal file
589
docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md
Normal file
@@ -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<br/>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"]
|
||||
```
|
||||
77
docs/i18n/pt-BR/FEATURES.md
Normal file
77
docs/i18n/pt-BR/FEATURES.md
Normal file
@@ -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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 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.
|
||||
|
||||
|
||||
219
docs/i18n/pt-BR/TROUBLESHOOTING.md
Normal file
219
docs/i18n/pt-BR/TROUBLESHOOTING.md
Normal file
@@ -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: `<repo>/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
|
||||
698
docs/i18n/pt-BR/USER_GUIDE.md
Normal file
698
docs/i18n/pt-BR/USER_GUIDE.md
Normal file
@@ -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
|
||||
|
||||
<details>
|
||||
<summary><b>Ver todos os modelos disponíveis</b></summary>
|
||||
|
||||
**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`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧩 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.
|
||||
441
docs/i18n/pt/API_REFERENCE.md
Normal file
441
docs/i18n/pt/API_REFERENCE.md
Normal file
@@ -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`
|
||||
781
docs/i18n/pt/ARCHITECTURE.md
Normal file
781
docs/i18n/pt/ARCHITECTURE.md
Normal file
@@ -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 (`<think>...</think>`) 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: `<repo>/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 `<think>...</think>` 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 `<repo>/logs/<session>/` 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://<host>:20128/v1` quando `PORT=20128`
|
||||
589
docs/i18n/pt/CODEBASE_DOCUMENTATION.md
Normal file
589
docs/i18n/pt/CODEBASE_DOCUMENTATION.md
Normal file
@@ -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<br/>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"]
|
||||
```
|
||||
77
docs/i18n/pt/FEATURES.md
Normal file
77
docs/i18n/pt/FEATURES.md
Normal file
@@ -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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 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.
|
||||
|
||||
|
||||
219
docs/i18n/pt/TROUBLESHOOTING.md
Normal file
219
docs/i18n/pt/TROUBLESHOOTING.md
Normal file
@@ -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: `<repo>/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
|
||||
698
docs/i18n/pt/USER_GUIDE.md
Normal file
698
docs/i18n/pt/USER_GUIDE.md
Normal file
@@ -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
|
||||
|
||||
<details>
|
||||
<summary><b>Ver todos os modelos disponíveis</b></summary>
|
||||
|
||||
**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`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧩 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.
|
||||
441
docs/i18n/ro/API_REFERENCE.md
Normal file
441
docs/i18n/ro/API_REFERENCE.md
Normal file
@@ -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`
|
||||
781
docs/i18n/ro/ARCHITECTURE.md
Normal file
781
docs/i18n/ro/ARCHITECTURE.md
Normal file
@@ -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 (`<think>...</think>`) 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: `<repo>/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 `<think>...</think>` 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 `<repo>/logs/<session>/` 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://<host>:20128/v1` când `PORT=20128`
|
||||
589
docs/i18n/ro/CODEBASE_DOCUMENTATION.md
Normal file
589
docs/i18n/ro/CODEBASE_DOCUMENTATION.md
Normal file
@@ -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<br/>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"]
|
||||
```
|
||||
77
docs/i18n/ro/FEATURES.md
Normal file
77
docs/i18n/ro/FEATURES.md
Normal file
@@ -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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 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ă.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Instrumente CLI
|
||||
|
||||
Configurare cu un singur clic pentru instrumentele de codare AI: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code și Antigravity.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 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.
|
||||
|
||||
|
||||
219
docs/i18n/ro/TROUBLESHOOTING.md
Normal file
219
docs/i18n/ro/TROUBLESHOOTING.md
Normal file
@@ -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: `<repo>/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
|
||||
698
docs/i18n/ro/USER_GUIDE.md
Normal file
698
docs/i18n/ro/USER_GUIDE.md
Normal file
@@ -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
|
||||
|
||||
<details>
|
||||
<summary><b>Vedeți toate modelele disponibile</b></summary>
|
||||
|
||||
**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`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧩 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.
|
||||
441
docs/i18n/ru/API_REFERENCE.md
Normal file
441
docs/i18n/ru/API_REFERENCE.md
Normal file
@@ -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`
|
||||
782
docs/i18n/ru/ARCHITECTURE.md
Normal file
782
docs/i18n/ru/ARCHITECTURE.md
Normal file
@@ -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 моделей)
|
||||
- Подумайте о разборе тегов (`<think>...</think>`) для моделей рассуждений.
|
||||
- Очистка ответов для строгой совместимости 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`
|
||||
- дополнительные сеансы отладки переводчика/запроса: `<repo>/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)
|
||||
- **Извлечение тегов** — анализирует блоки `<think>...</think>` из содержимого в поле `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
|
||||
```
|
||||
|
||||
Файлы записываются в `<repo>/logs/<session>/` для каждого сеанса запроса.
|
||||
|
||||
## Режимы отказов и устойчивость
|
||||
|
||||
## 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://<host>:20128/v1`, когда `PORT=20128`.
|
||||
589
docs/i18n/ru/CODEBASE_DOCUMENTATION.md
Normal file
589
docs/i18n/ru/CODEBASE_DOCUMENTATION.md
Normal file
@@ -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<br/>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"]
|
||||
```
|
||||
77
docs/i18n/ru/FEATURES.md
Normal file
77
docs/i18n/ru/FEATURES.md
Normal file
@@ -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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Комбо
|
||||
|
||||
Создавайте комбинации маршрутизации моделей с помощью шести стратегий: «сначала заполнить», «циклический», «степень двух вариантов», «случайный», «наименее используемый» и «оптимизированный по затратам». Каждая комбинация объединяет несколько моделей с автоматическим возвратом.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 Аналитика
|
||||
|
||||
Комплексная аналитика использования с использованием токенов, оценками затрат, тепловыми картами активности, еженедельными диаграммами распределения и разбивкой по каждому провайдеру.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 Состояние системы
|
||||
|
||||
Мониторинг в режиме реального времени: время безотказной работы, память, версия, процентили задержки (p50/p95/p99), статистика кэша и состояния автоматического выключателя поставщика.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Игровая площадка переводчика
|
||||
|
||||
Четыре режима отладки переводов API: **Игровая площадка** (конвертер форматов), **Тестер чата** (живые запросы), **Тестовый стенд** (пакетные тесты) и **Живой монитор** (поток в реальном времени).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Настройки
|
||||
|
||||
Общие настройки, системное хранилище, управление резервным копированием (экспорт/импорт базы данных), внешний вид (темный/светлый режим), безопасность (включая защиту конечных точек API и блокировку настраиваемых провайдеров), маршрутизация, устойчивость и расширенная настройка.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Инструменты CLI
|
||||
|
||||
Конфигурация инструментов искусственного кодирования одним щелчком мыши: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code и Antigravity.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 Журналы запросов
|
||||
|
||||
Регистрация запросов в режиме реального времени с фильтрацией по поставщику, модели, учетной записи и ключу API. Показывает коды состояния, использование токена, задержку и сведения об ответе.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Конечная точка API
|
||||
|
||||
Ваша унифицированная конечная точка API с разбивкой возможностей: завершение чата, внедрение, создание изображений, изменение рейтинга, расшифровка аудио и зарегистрированные ключи API.
|
||||
|
||||
|
||||
219
docs/i18n/ru/TROUBLESHOOTING.md
Normal file
219
docs/i18n/ru/TROUBLESHOOTING.md
Normal file
@@ -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/`
|
||||
- Запрос журналов: `<repo>/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) для всех конечных точек.
|
||||
- **Панель состояния**: проверьте **Панель управления → Здоровье**, чтобы узнать состояние системы в режиме реального времени.
|
||||
- **Переводчик**: используйте **Панель управления → Переводчик** для устранения проблем с форматом.
|
||||
698
docs/i18n/ru/USER_GUIDE.md
Normal file
698
docs/i18n/ru/USER_GUIDE.md
Normal file
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
## 📊 Доступные модели
|
||||
|
||||
<details>
|
||||
<summary><b>Просмотреть все доступные модели</b></summary>
|
||||
|
||||
**Код Клауда (`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`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Расширенные функции
|
||||
|
||||
### Пользовательские модели
|
||||
|
||||
Добавьте любой идентификатор модели к любому поставщику, не дожидаясь обновления приложения:
|
||||
|
||||
```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 секунд. Используйте карту автоматического выключателя, чтобы определить, у каких поставщиков возникли проблемы.
|
||||
441
docs/i18n/sk/API_REFERENCE.md
Normal file
441
docs/i18n/sk/API_REFERENCE.md
Normal file
@@ -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`
|
||||
783
docs/i18n/sk/ARCHITECTURE.md
Normal file
783
docs/i18n/sk/ARCHITECTURE.md
Normal file
@@ -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 (`<think>...</think>`) 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: `<repo>/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 `<think>...</think>` 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 `<repo>/logs/<session>/` 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://<host>:20128/v1`, keď `PORT=20128`
|
||||
589
docs/i18n/sk/CODEBASE_DOCUMENTATION.md
Normal file
589
docs/i18n/sk/CODEBASE_DOCUMENTATION.md
Normal file
@@ -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<br/>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"]
|
||||
```
|
||||
77
docs/i18n/sk/FEATURES.md
Normal file
77
docs/i18n/sk/FEATURES.md
Normal file
@@ -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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🎨 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📊 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏥 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🌐 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.
|
||||
|
||||
|
||||
221
docs/i18n/sk/TROUBLESHOOTING.md
Normal file
221
docs/i18n/sk/TROUBLESHOOTING.md
Normal file
@@ -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í: `<repo>/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**
|
||||
698
docs/i18n/sk/USER_GUIDE.md
Normal file
698
docs/i18n/sk/USER_GUIDE.md
Normal file
@@ -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
|
||||
|
||||
<details>
|
||||
<summary><b>Zobraziť všetky dostupné modely</b></summary>
|
||||
|
||||
**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`
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🧩 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.
|
||||
Reference in New Issue
Block a user