Model Router — Enrutamiento Multi-LLM con Conciencia de Costos y Cadena de Reintentos Gratuita Primero

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

📥 Descarga Inmediata (Paquetes de Instalación para Tres Plataformas, Haga Doble Clic para Usar)

💡 Versión Ligera = tkinter, biblioteca estándar pura (cero dependencias, inicio más rápido) · Versión Completa = interfaz moderna pywebview (incluye análisis de enrutamiento, estadísticas de historial, visualización de costos) 🔗 Todas las versiones: Página de Lanzamientos

Related MCP server: Robot Resources Router

Introducción en Inglés

Qué es

Model Router es un enrutador multi-LLM con conciencia de costos que envía automáticamente cada tarea al mejor modelo para ella — proveedores gratuitos primero, proveedores de pago solo como respaldo. Viene con un cliente gráfico sin código (descargar, hacer doble clic, listo), además de una CLI, una API de Python, un servidor MCP y un demonio de vigilancia de archivos.

La mayoría del código de integración de LLM codifica de forma rígida un solo modelo o un solo proveedor de API, lo que significa:

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

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

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

Model Router resuelve los tres problemas con un diseño simple y de dependencia ligera: aproximadamente el 90% de las tareas cotidianas pueden ser atendidas por modelos gratuitos, mientras que las tareas difíciles aún obtienen calidad de modelo fronterizo mediante un respaldo automático.

Características Clave

• ✅ 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 Reintentos Gratuita Primero: cada nivel de ruta define una cadena de candidatos ordenada — los proveedores gratuitos (Zhipu, SiliconFlow, modelos gratuitos de OpenRouter) se prueban primero; ante cualquier fallo, el siguiente candidato (eventualmente DeepSeek/Qwen/GLM/Kimi de pago) se prueba automáticamente

• ✅ Cero Dependencias de Terceros: la biblioteca principal solo necesita requests; el servidor MCP es puramente stdlib (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

• ✅ Cliente GUI Sin Código: aplicación de escritorio para Windows / macOS / Linux — escriba una pregunta, haga clic en Responder, el enrutamiento ocurre automáticamente en segundo plano

Instaladores

Sin necesidad de programación — descargue el instalador y haga doble clic:

Características de la GUI:

• 🎯 Escriba una pregunta → la dificultad se detecta automáticamente → el mejor modelo gratuito se elige automáticamente

• 🧭 Información de enrutamiento en vivo (qué modelo está respondiendo)

• 💬 Tema profesional oscuro, interfaz tipo chat

• ⚙️ Rol configurable / mensaje del sistema

Toda la lógica de enrutamiento se ejecuta automáticamente en segundo plano. El usuario solo necesita escribir una pregunta y hacer clic en Responder.

Modo desarrollador:

pip install -r requirements.txt
python gui_app.py        # launch the GUI
python auto_router.py    # or use the CLI

🖥 Aplicación de Escritorio (Windows / macOS / Linux)

Descargue el instalador para su plataforma desde Lanzamientos:

Características: análisis de ruta (costo cero) · llamada automática con primer intento gratuito · visor de configuración de proveedores (claves enmascaradas) · sin necesidad de terminal.

# Build locally (requires Python 3.8+)
pip install -r requirements-desktop.txt
bash scripts/build_client.sh        # auto-detects platform

🚀 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"]

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 reintento: los candidatos se prueban en orden; la respuesta informa tier (gratuito/pago), attempts, fallback_used y errors por proveedor para una observabilidad completa.

Servidor MCP (para cualquier cliente MCP)

python mcp_server.py

Regístrelo en su cliente MCP (por ejemplo, claude_desktop_config.json de Claude Desktop):

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

Demonio Activado por Tareas (modo de 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 (consulte config.example.json):

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

• routing: cadenas de candidates ordenadas por nivel — gratuitos primero, pagos como red de seguridad

• levels: descripciones legibles por humanos por nivel

Agregue o elimine proveedores libremente — el enrutador está completamente impulsado por datos.

Licencia

MIT — libre para uso personal y comercial. Consulte LICENSE.

🇨🇳 中文版介绍

这是什么？

Model Router（模型路由器） 是一个「按任务难度自动路由到最优免费模型」的开源工具：免费模型优先，付费模型兜底。它附带一个无需编程、双击即用的图形化客户端，同时提供命令行（CLI）、Python API、MCP 服务器和文件监听守护进程。

大多数 LLM 集成代码都写死单一模型或单一 API 供应商，导致：

• ❌ 贵：每次请求（哪怕是最简单的问题）都打到付费的顶级模型上

• ❌ 脆弱：一家供应商宕机 = 全线瘫痪

• ❌ 不灵活：无法让模型能力匹配任务难度

Model Router 用一套轻量、无依赖的设计同时解决这三个问题：日常任务中约 90% 都可以由免费模型完成，而困难任务通过自动降级链依然能获得顶级模型的质量。

🎯 为什么做这个项目？

因为市面上大多数方案都在「杀鸡用牛刀」：

1. 简单问答也调用付费大模型，成本浪费严重；

2. 单一供应商一旦故障，整个服务就不可用；

3. 模型能力与任务难度完全不匹配，体验和成本双输。

Model Router 的答案是：先分类、再路由、免费优先、失败自动降级——让每一分钱都花在刀刃上，同时保证服务的稳定性。

✨ 核心特性

• ✅ 任务难度五级分类：vision（图像）/ long（长文）/ complex（复杂）/ medium（中等）/ simple（简单），通过关键词 + 内容长度启发式判断——零成本，不调用任何 LLM

• ✅ 免费优先的降级链（Free-First Fallback Chain）：每个路由级别定义一条有序候选链——先尝试免费供应商（智谱、SiliconFlow、OpenRouter 免费模型），任一环节失败自动尝试下一个候选（最终兜底为付费的 DeepSeek / Qwen / GLM / Kimi）

• ✅ 零第三方依赖：核心库只需 requests；MCP 服务器纯标准库实现（stdio 上的 JSON-RPC 2.0）

• ✅ 多接口：Python API · CLI · MCP 服务器（可接入任意 MCP 客户端：Claude、Qoder、Cursor……）· 文件监听守护进程

• ✅ 免编程图形化客户端：Windows / macOS / Linux 桌面应用——输入问题、点击回答，路由全部在后台自动完成

💻 图形化客户端（傻瓜式，拿来就用）

无需编程，下载安装包双击即用：

界面功能：

• 🎯 输入问题 → 自动识别任务难度 → 自动选择最优免费模型

• 🧭 实时显示路由信息（哪个模型在回答）

• 💬 深色专业主题，对话式界面

• ⚙️ 可设置角色提示词

专业的路由逻辑全部在后台自动完成，用户只需输入问题、点击回答。

开发者模式

pip install -r requirements.txt
python gui_app.py        # 启动图形界面
python auto_router.py    # 或命令行

🏗 架构

                ┌─────────────────────────────────────────────┐
                │              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)

路由级别

降级语义：按顺序依次尝试候选；响应中会报告 tier（free/paid）、attempts、fallback_used 以及每个供应商的 errors，实现全程可观测。

🚀 快速开始

# 1. 安装（只需 requests）
pip install requests

# 2. 配置
cp config.example.json config.json
#    → 填入你的 API Key

# 3. 命令行 —— 仅分析（零成本，不调用模型）
python router_core.py analyze "分析这份气象数据"

# 4. 命令行 —— 路由并调用
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"])           # 第一个候选
print(result["candidates"])        # 完整降级链
text = route_and_call("总结要点", "long text...")["content"]

🖥 MCP 服务器（供任意 MCP 客户端使用）

python mcp_server.py

在 MCP 客户端中注册（例如 Claude Desktop 的 claude_desktop_config.json）：

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

⏱ 任务触发守护进程（文件监听模式）

# 单次执行
python auto_router.py "任务描述" -c "内容" --image photo.png

# 守护进程：把任务文件丢进 inbox/，结果自动出现在 outbox/
python auto_router.py --watch --dir ./tasks

🔧 配置说明

config.json 结构（参见 config.example.json）：

• providers：OpenAI 兼容端点，含 tier（free / paid）和可选的 enabled: false

• routing：每个级别按顺序排列的 candidates 候选链——免费在前，付费兜底

• levels：每个级别的人类可读描述

可以自由增删供应商——路由器完全由数据驱动。

📄 许可证

MIT —— 个人与商业使用均免费。详见 LICENSE.

灵感来自真实世界的成本优化：日常任务中约 90% 可以由免费模型完成，而困难任务通过自动降级依然能获得顶级模型的质量。