Model Router — Маршрутизация между LLM с учётом стоимости и цепочкой отката с бесплатными моделями в приоритете

Автоматически направляйте каждую задачу лучшей модели — сначала бесплатные провайдеры, платные — как запасной вариант.

📥 Скачать сейчас (установщики для трёх платформ, двойной щелчок для запуска)

💡 Лёгкая версия = tkinter, чистая стандартная библиотека (ноль зависимостей, самый быстрый запуск) · Полная версия = pywebview, современный интерфейс (включает анализ маршрутизации, историю статистики, отображение стоимости) 🔗 Все версии: Страница релизов

Related MCP server: Robot Resources Router

Введение на английском

Что это такое

Model Router — это маршрутизатор между несколькими LLM с учётом стоимости, который автоматически отправляет каждую задачу лучшей для неё модели — сначала бесплатные провайдеры, платные только как запасной вариант. Он поставляется с графическим клиентом без кода (скачать, дважды щёлкнуть, готово), а также CLI, Python API, MCP-сервером и демоном, отслеживающим файлы.

Большинство кода интеграции LLM жёстко зашивает одну модель или одного провайдера API, что означает:

• ❌ Дорого: каждый запрос (даже тривиальный) отправляется платной фронтирной модели

• ❌ Хрупко: сбой одного провайдера = полный отказ

• ❌ Негибко: нет возможности сопоставить возможности модели со сложностью задачи

Model Router решает все три проблемы с помощью простого, легковесного дизайна: примерно 90% повседневных задач могут обслуживаться бесплатными моделями, в то время как сложные задачи всё равно получают качество фронтирных моделей благодаря автоматическому откату.

Ключевые особенности

• ✅ Классификация сложности задачи: 5 уровней (vision / long / complex / medium / simple) с помощью эвристики по ключевым словам + длине содержимого — нулевая стоимость, без участия LLM

• ✅ Цепочка отката с приоритетом бесплатных моделей (Free-First Fallback Chain): каждый уровень маршрутизации определяет упорядоченную цепочку кандидатов — сначала пробуются бесплатные провайдеры (Zhipu, SiliconFlow, бесплатные модели OpenRouter); при любом сбое автоматически пробуется следующий кандидат (в конечном итоге платные DeepSeek/Qwen/GLM/Kimi)

• ✅ Нулевые сторонние зависимости: основная библиотека требует только requests; MCP-сервер реализован на чистой стандартной библиотеке (JSON-RPC 2.0 через stdio)

• ✅ Несколько интерфейсов: Python API · CLI · MCP-сервер (любой MCP-клиент: Claude, Qoder, Cursor…) · Демон, отслеживающий файлы

• ✅ Графический клиент без кода: настольное приложение для Windows / macOS / Linux — введите вопрос, нажмите «Ответить», маршрутизация происходит автоматически в фоне

Установщики

Программирование не требуется — скачайте установщик и дважды щёлкните:

Возможности GUI:

• 🎯 Введите вопрос → сложность определяется автоматически → лучшая бесплатная модель выбирается автоматически

• 🧭 Информация о маршрутизации в реальном времени (какая модель отвечает)

• 💬 Тёмная профессиональная тема, интерфейс в стиле чата

• ⚙️ Настраиваемая роль / системный промпт

Вся логика маршрутизации выполняется автоматически в фоне. Пользователю нужно только ввести вопрос и нажать «Ответить».

Режим разработчика:

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

🖥 Настольное приложение (Windows / macOS / Linux)

Скачайте установщик для вашей платформы из Релизов:

Возможности: анализ маршрутизации (нулевая стоимость) · автоматический вызов с приоритетом бесплатных моделей и откатом · просмотр конфигурации провайдеров (ключи скрыты) · не требуется терминал.

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

🚀 Быстрый старт

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

Архитектура

                ┌─────────────────────────────────────────────┐
                │              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 для каждого провайдера — полная наблюдаемость.

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"}
    }
  }
}

Демон, запускаемый по задаче (режим отслеживания файлов)

# 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

Конфигурация

Структура config.json (см. config.example.json):

• providers: конечные точки, совместимые с OpenAI, с tier (free / paid) и необязательным enabled: false

• routing: упорядоченные цепочки candidates для каждого уровня — сначала бесплатные, платные как страховочная сеть

• levels: человекочитаемые описания для каждого уровня

Добавляйте или удаляйте провайдеров свободно — маршрутизатор полностью управляется данными.

Лицензия

MIT — бесплатно для личного и коммерческого использования. См. 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): каждый уровень маршрутизации определяет упорядоченную цепочку кандидатов — сначала пробуются бесплатные провайдеры (Zhipu, SiliconFlow, бесплатные модели OpenRouter); при любом сбое автоматически пробуется следующий кандидат (в конечном итоге платные DeepSeek / Qwen / GLM / Kimi)

• ✅ Нулевые сторонние зависимости: основная библиотека требует только requests; MCP-сервер реализован на чистой стандартной библиотеке (JSON-RPC 2.0 через stdio)

• ✅ Множество интерфейсов: 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_config.json для Claude Desktop):

{
  "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% повседневных задач могут быть выполнены бесплатными моделями, а сложные задачи по-прежнему получают качество фронтирных моделей благодаря автоматическому откату.