Model Router — Enrutamiento Multi-LLM con Conciencia de Costos y Cadena de Reemplazo Gratis-Primero

Enruta cada tarea al mejor modelo automáticamente: proveedores gratuitos primero, proveedores de pago como respaldo.

🎯 ¿Por qué Model Router?

La mayoría del código de integración de LLM codifica un único modelo o usa un único proveedor de API. Esto significa:

• ❌ Costoso: cada solicitud (incluso las triviales) va a un modelo frontera de pago

• ❌ Frágil: una interrupción del proveedor = fallo total

• ❌ Inflexible: no hay forma de igualar la capacidad del modelo con la dificultad de la tarea

Model Router resuelve los tres problemas con un diseño simple y de pocas dependencias:

• ✅ Clasificación de Dificultad de Tareas: 5 niveles (vision / long / complex / medium / simple) mediante heurísticas de palabras clave + longitud de contenido (costo cero, sin involucrar LLM)

• ✅ Cadena de Reemplazo Gratis-Primero: cada nivel de ruta define una cadena de candidatos ordenada — los proveedores gratuitos (Zhipu, SiliconFlow, modelos gratuitos de OpenRouter) se intentan primero; ante cualquier fallo, el siguiente candidato (finalmente DeepSeek/Qwen/GLM/Kimi de pago) se prueba automáticamente

• ✅ Cero Dependencias de Terceros: la biblioteca central solo necesita requests; el servidor MCP es stdlib puro (JSON-RPC 2.0 sobre stdio)

• ✅ Múltiples Interfaces: API de Python · CLI · servidor MCP (cualquier cliente MCP: Claude, Qoder, Cursor…) · Demonio de vigilancia de archivos

🏗 Arquitectura

                ┌─────────────────────────────────────────────┐
                │              router_core.py                 │
                │                                             │
   task_desc ──▶│  classify_task()  →  5 difficulty levels   │
   content   ──▶│  _get_candidates() → ordered provider chain│
   image ──────▶│  route_and_call()  → free-first, fallback  │
                │                                             │
                └──────────────┬──────────────────────────────┘
                               │
              ┌────────────────┼───────────────────┐
              ▼                ▼                   ▼
        auto_router.py    mcp_server.py       Python API
        (CLI + daemon)    (MCP tools)         (import router_core)

Niveles de Enrutamiento

Semántica de reemplazo: los candidatos se prueban en orden; la respuesta informa tier (free/paid), attempts, fallback_used y errores por proveedor errors para total observabilidad.

🚀 Inicio Rápido

# 1. Install (only requests is required)
pip install requests

# 2. Configure
cp config.example.json config.json
#    → fill in your API keys

# 3. CLI — analyze only (zero cost, no model call)
python router_core.py analyze "分析这份气象数据"

# 4. CLI — route and call
python router_core.py call "翻译以下段落" --content "Hello world" --system "你是专业翻译"

# 5. Python API
from router_core import route_and_call, analyze_task
result = analyze_task("写一份论文摘要", content_len=300)
print(result["primary"])           # first candidate
print(result["candidates"])        # full fallback chain
text = route_and_call("总结要点", "long text...")["content"]

🖥 Servidor MCP (para cualquier cliente MCP)

python mcp_server.py

Regístralo en tu cliente MCP (por ejemplo, Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "model-router": {
      "command": "python",
      "args": ["/path/to/model-router/mcp_server.py"],
      "env": {"PYTHONIOENCODING": "utf-8"}
    }
  }
}

⏱ Demonio Activado por Tarea (modo vigilancia de archivos)

# One-shot
python auto_router.py "任务描述" -c "内容" --image photo.png

# Daemon: drop task files into inbox/, results appear in outbox/
python auto_router.py --watch --dir ./tasks

🔧 Configuración

Estructura de config.json (consulta config.example.json):

• providers: endpoints compatibles con OpenAI con tier (free / paid) y opcionalmente enabled: false

• routing: cadenas de candidates ordenadas por nivel — gratis primero, pago como red de seguridad

• levels: descripciones legibles por humanos por nivel

Agrega o elimina proveedores libremente: el enrutador es completamente basado en datos.

📄 Licencia

MIT — gratuita para uso personal y comercial. Consulta LICENSE.

Inspirado en la optimización de costos del mundo real: ~90% de las tareas cotidianas pueden ser atendidas por modelos de nivel gratuito, mientras que las tareas difíciles aún obtienen calidad de modelo frontera mediante reemplazo automático.