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

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

🎯 Зачем нужен Model Router?

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

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

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

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

Model Router решает все три проблемы с помощью простого дизайна с минимальными зависимостями:

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

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

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

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

🏗 Архитектура

                ┌─────────────────────────────────────────────┐
                │              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. 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"]

🖥 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.

Вдохновлено реальной оптимизацией затрат: ~90% повседневных задач могут быть обслужены моделями бесплатного уровня, в то время как сложные задачи получают качество передовых моделей через автоматический откат.