110 lines
8.1 KiB
Markdown
110 lines
8.1 KiB
Markdown
# OmniRoute — Guía autorouting y combos `auto/*`
|
||
|
||
Fecha: 13-sep-2026 · Estado: documentación estable para replicar en cualquier equipo (sobremesa / portátil / VPS)
|
||
|
||
---
|
||
|
||
## 1. Qué es OmniRoute en este setup
|
||
|
||
OmniRoute es un **proxy/router de modelos** self-hosted que corre en local. Hace routing entre tus proveedores conectados con fallback automático, circuit breakers, y combos virtuales.
|
||
|
||
- **Servidor**: paquete npm global `omniroute`
|
||
- Comando: `omniroute serve` → lanza `node .../omniroute/dist/server-ws.mjs`
|
||
- Escucha en: `http://localhost:20128` (OpenAI-compatible `/v1`)
|
||
- **Datos**: `C:\Users\juanm\.omniroute\`
|
||
- `storage.sqlite` (estado, streaks, kv de combos)
|
||
- `call_logs\AAAA-MM-DD\*.json` (cada request ruteado: modelo real elegido, tokens, fallbacks)
|
||
- `logs\application\app.log` (routing trace: decisiones, fallbacks, límites)
|
||
- `.env` (config servidor, secretos — nunca exponer)
|
||
- `server\.pid` / `supervisor\.pid`
|
||
- **Supervisor**: `omniroute.mjs serve` es el padre; el worker real es `server-ws.mjs`
|
||
- **Sin autostart por tarea programada en sobremesa** (se lanza manualmente). Replicar igual en portátil.
|
||
|
||
## 2. Estado actual: bug de opencode y los 38 modelos manuales
|
||
|
||
**Problema raíz**: el plugin `@omniroute/opencode-plugin` no puede registrar providers fuera del catálogo models.dev de opencode → los `auto/*` NO aparecen en el picker por defecto.
|
||
- Issues: anomalyco/opencode **#38839** (provider hook skipped for non-catalog providers) y **#25630** (Regression: plugin provider.models() hook no longer populates custom providers, post #25167).
|
||
|
||
**Workaround aplicado (decisión: mantener hasta que se arregle el bug)**:
|
||
- Los **38 modelos `auto/*`** están declarados **a mano** en `~/.config/opencode/opencode.jsonc` → sección `provider.omniroute`,
|
||
con label amigable (`Auto ♟ Best Coding`, etc.) y `baseURL: http://localhost:20128/v1`, `npm: @ai-sdk/openai-compatible`.
|
||
- El plugin se carga con: `providerId: omniroute`, `baseURL: http://localhost:20128`.
|
||
- El **enrutado y el failover funcionan igual aunque los modelos estén a mano**: la lógica de routing vive 100% en el servidor OmniRoute, opencode solo manda el nombre `auto/...` a `localhost:20128`. El picker manual solo afecta al catálogo visible, NO al comportamiento de routing.
|
||
|
||
**Check automático del fix**:
|
||
- `scripts/check_omniroute_fix.ps1` (tarea programada `OmnirouteFixCheck`, diaria 09:00) consulta los issues #38839/#25630.
|
||
- Si alguno está cerrado → crea `documentacion/omniroute_fix_fixed.flag` y actualiza `documentacion/omniroute_fix_status.txt`.
|
||
- Cuando exista ese flag: avisar al usuario → reactivar catálogo dinámico del plugin y quitar los 38 modelos manuales de `opencode.jsonc`.
|
||
|
||
## 3. Cómo funciona el routing `auto/*` (mecánica por detrás)
|
||
|
||
Los `auto/*` **no son modelos reales**: son **alias virtuales de ruta**. OmniRoute los materializa al vuelo en cada request sin guardarlos en la BD (tabla `combos` vacía).
|
||
|
||
Flujo real (trace de `app.log`):
|
||
```
|
||
POST /v1/chat/completions | auto/best-coding | 28 msgs | 71 tools
|
||
Virtual auto-combo created: auto/best-coding (2 candidates) ← shortlist puntuada
|
||
Combo "auto/best-coding" [auto] with 13 models ← pool total (nested "auto")
|
||
auto with nested resolution: 13 total targets
|
||
Auto selection: oc/big-pickle | intent=medium task=default | strategy=lkgp | LKGP
|
||
Trying model 1/8: oc/big-pickle
|
||
ROUTING oc/big-pickle ⇒ opencode/big-pickle ← modelo REAL elegido
|
||
Model oc/big-pickle succeeded (880ms, 0 fallbacks)
|
||
```
|
||
|
||
- En cada request el **Auto-Combo Engine puntúa a los candidatos con 15 factores**: salud del provider, cuota restante, coste, latencia, task fit, calidad, disponibilidad de sesión, etc.
|
||
- **`lkgp` = Last-Known-Good**: sticky al último target que funcionó mientras siga OK (no cambia por aburrimiento).
|
||
- **Fallback automático**: si el elegido falla (429/5xx/timeout), re-engancha al siguiente candidato **dentro del mismo request** (sin que opencode se entere).
|
||
- **Recuperación**: circuit breakers/cooldowns auto-reset; el primer éxito limpia el estado de error. Un candidato agotado deja de ganar el scoring y vuelve cuando recupera cuota.
|
||
|
||
### Mapa de variantes (catalog real, `open-sse/services/autoCombo/builtinCatalog.ts`)
|
||
|
||
| Modelo | Variante | Optimiza |
|
||
|---|---|---|
|
||
| `auto` | default | Balanceado (LKGP) |
|
||
| `auto/best-coding` | `coding` | Quality-first para código |
|
||
| `auto/best-reasoning` | `smart` | Calidad + 10% exploración |
|
||
| `auto/best-fast` | `fast` | Menor latencia |
|
||
| `auto/best-vision` | `smart` (+filtro visión) | Calidad en inputs visuales |
|
||
| `auto/best-chat` | default | Chat general |
|
||
| `auto/best-coding-fast` | `fast` | Velocidad en código |
|
||
| `auto/best-free` | `cheap` | Solo tier free |
|
||
| `auto/best-chaos` | `chaos` | Despacho paralelo top-N |
|
||
| `auto/pro-*` | idem | Tier de pago forzado |
|
||
| `auto/coding`, `auto/fast`, `auto/cheap`, `auto/offline`, `auto/smart`, `auto/chat` | idem | Variantes básicas |
|
||
| `auto/coding:fast`, `auto/coding:pro`, `auto/vision`, `auto/multimodal`, `auto/reasoning` | sufijo | Categoría[:tier] |
|
||
| `auto/gemini`, `auto/llama`, `auto/glm`, `auto/claude-sonnet`, `auto/claude-opus`... | familia | Solo esa familia como candidatos |
|
||
|
||
Los 38 declarados a mano en opencode.jsonc son este catálogo `auto/*`.
|
||
|
||
## 4. Límites y quotas
|
||
|
||
- **Límite de contexto del combo `auto/*`: 200.000 tokens (`source=target`)** — confirmado en logs: `Combo context limit: 200000 (source=target)`.
|
||
- `source` = lo que opencode envía (conversación + tools)
|
||
- `target` = lo que el modelo de destino admite
|
||
- **Salida (out)**: sin tope fijo en el combo; depende del modelo real que rute en ese momento.
|
||
- **"¿Me bloquean por usarlo varios días?"**: NO. Los bloqueos (circuit breaker / model lockout) solo saltan ante fallos reales repetidos (429/5xx/timeout) y se auto-recuperan. El único bloqueo real sería agotar la cuota de TODOS los candidatos a la vez (cuenta opencode = `big-pickle` + reserva del pool).
|
||
|
||
## 5. Candidatos actuales para `auto/best-coding` (13-sep-2026)
|
||
|
||
- **Shortlist directa: 2 candidatos** (log: `2 candidates`). Ganador actual estable: `oc/big-pickle` → provider `opencode` (cuenta opencode, API key `OMNI-1`).
|
||
- **Pool anidado: 13 targets** (combo base `auto` con "nested resolution").
|
||
- **Intentos de fallback por request: hasta 8** (`Trying model 1/8`); si todos fallan → error al usuario.
|
||
- La identidad exacta del 2º candidato **no está persistida** en la BD: la construye el engine en runtime puntuando tus conexiones. Para verla en vivo: `call_logs` o `logs/application/app.log` (líneas con `Auto selection:`/`VRouting`).
|
||
|
||
## 6. Replicación en el portátil
|
||
|
||
Para que el asistente del portátil deje todo igual:
|
||
|
||
1. **Instalar servidor**: `npm i -g omniroute` (mismo paquete que en sobremesa).
|
||
2. **Config `.omniroute`**: copiar `C:\Users\juanm\.omniroute\.env` (secretos) y, si se quiere historial, `storage.sqlite` + `call_logs`.
|
||
3. **Lanzar**: `omniroute serve` (debe quedar escuchando en `http://localhost:20128`).
|
||
4. **Config opencode** (`~/.config/opencode/opencode.jsonc`):
|
||
- Plugin: `file:///C:/Users/juanm/AppData/Roaming/opencode/plugins/omniroute/dist/index.js` con `{ "providerId": "omniroute", "baseURL": "http://localhost:20128" }`
|
||
- Provider `omniroute`: `npm @ai-sdk/openai-compatible`, `baseURL http://localhost:20128/v1`, los 38 modelos `auto/*` (ver sección 3 para el catálogo; el JSON exacto está en el opencode.jsonc de la sobremesa).
|
||
5. **Fix checker**: copiar `scripts/check_omniroute_fix.ps1` + tarea `OmnirouteFixCheck` (diaria 09:00).
|
||
6. Comprobar en `logs/application/app.log` que aparece `Combo context limit: 200000 (source=target)`.
|
||
|
||
## 7. Origen de esta guía
|
||
|
||
Recopilado 13-sep-2026 en sesión RE (sobremesa): logs reales del servidor, `builtinCatalog.ts` del paquete npm, y verificación en vivo con requests de opencode bajo `omniroute/auto/best-coding`. Memoria Engram asociada (project `biblioteca_conocimiento_laboratorio`): "Cómo funcionan los modelos auto/* de OmniRoute (alias virtuales + routing)". Esta guía se sincroniza a todos los equipos vía git + Engram Cloud para que el asistente pueda aplicarla en el portátil. |