Model Router – Kostenbewusstes Multi-LLM-Routing mit Free-First-Fallback-Kette

Leiten Sie jede Aufgabe automatisch zum besten Modell – zuerst kostenlose Anbieter, kostenpflichtige als Fallback.

📥 立即下载（三平台安装包，双击即用）

💡 轻量版 = tkinter 纯标准库（零依赖，启动最快） · 完整版 = pywebview 现代界面（含路由分析/历史统计/成本显示） 🔗 全部版本：Releases 页面

Related MCP server: Robot Resources Router

Englische Einführung

Was es ist

Model Router ist ein kostenbewusster Multi-LLM-Router, der jede Aufgabe automatisch an das beste Modell sendet – zuerst kostenlose Anbieter, kostenpflichtige nur als Fallback. Er wird mit einem grafikbasierten Client ohne Code (herunterladen, doppelklicken, fertig) sowie einem CLI, einer Python-API, einem MCP-Server und einem Dateiüberwachungs-Daemon ausgeliefert.

Die meisten LLM-Integrationscodes verwenden ein einziges Modell oder einen einzigen API-Anbieter, was bedeutet:

• ❌ Teuer: jede Anfrage (selbst triviale) geht an ein kostenpflichtiges Spitzenmodell

• ❌ Anfällig: ein Anbieterausfall = Totalausfall

• ❌ Unflexibel: keine Möglichkeit, die Modellfähigkeit an die Aufgaben-Schwierigkeit anzupassen

Model Router löst alle drei Probleme mit einem einfachen, abhängigkeitsarmen Design: Etwa 90 % der alltäglichen Aufgaben können von kostenlosen Modellen bedient werden, während schwierige Aufgaben durch automatisches Fallback weiterhin Spitzenmodell-Qualität erhalten.

Hauptfunktionen

• ✅ Aufgaben-Schwierigkeitsklassifizierung: 5 Stufen (vision / long / complex / medium / simple) durch Schlüsselwort- und Inhaltslängen-Heuristiken – keine Kosten, kein LLM erforderlich

• ✅ Free-First-Fallback-Kette: jede Routing-Stufe definiert eine geordnete Kandidatenkette – kostenlose Anbieter (Zhipu, SiliconFlow, OpenRouter Free Models) werden zuerst versucht; bei Fehlschlag wird automatisch der nächste Kandidat (letztlich kostenpflichtige DeepSeek/Qwen/GLM/Kimi) probiert

• ✅ Keine Drittanbieter-Abhängigkeiten: Kernbibliothek benötigt nur requests; der MCP-Server ist reine Stdlib (JSON-RPC 2.0 über stdio)

• ✅ Mehrere Schnittstellen: Python-API · CLI · MCP-Server (jeder MCP-Client: Claude, Qoder, Cursor…) · Dateiüberwachungs-Daemon

• ✅ Grafikclient ohne Code: Desktop-App für Windows / macOS / Linux – Frage eingeben, auf Antwort klicken, Routing erfolgt automatisch im Hintergrund

Installationsprogramme

Keine Programmierkenntnisse erforderlich – Installer herunterladen und doppelklicken:

GUI-Funktionen:

• 🎯 Frage eingeben → Schwierigkeit wird automatisch erkannt → das beste kostenlose Modell wird automatisch gewählt

• 🧭 Live-Routing-Informationen (welches Modell antwortet)

• 💬 Dunkles professionelles Theme, Chat-Oberfläche

• ⚙️ Konfigurierbare Rolle / System-Prompt

Die gesamte Routing-Logik läuft automatisch im Hintergrund. Der Benutzer muss nur eine Frage eingeben und auf „Antworten" klicken.

Entwicklermodus:

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

🖥 Desktop-App (Windows / macOS / Linux)

Laden Sie den Installer für Ihre Plattform von Releases herunter:

Funktionen: Routenanalyse (kostenlos) · automatischer Aufruf mit Free-First-Fallback · Provider-Konfigurationsanzeige (Schlüssel maskiert) · kein Terminal erforderlich.

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

🚀 Schnellstart

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

Architektur

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

Routing-Stufen

Fallback-Semantik: Kandidaten werden der Reihe nach versucht; die Antwort meldet tier (free/paid), attempts, fallback_used und pro Anbieter errors für vollständige Beobachtbarkeit.

MCP-Server (für jeden MCP-Client)

python mcp_server.py

Registrieren Sie ihn in Ihrem MCP-Client (z. B. Claude Desktop claude_desktop_config.json):

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

Aufgabengetriggerter Daemon (Dateiüberwachungsmodus)

# 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

Konfiguration

Struktur von config.json (siehe config.example.json):

• providers: OpenAI-kompatible Endpunkte mit tier (free / paid) und optionalem enabled: false

• routing: pro Stufe geordnete candidates-Ketten – kostenlos zuerst, kostenpflichtig als Sicherheitsnetz

• levels: menschenlesbare Beschreibungen pro Stufe

Fügen Sie beliebig Anbieter hinzu oder entfernen Sie sie – der Router ist vollständig datengesteuert.

Lizenz

MIT – kostenlos für private und kommerzielle Nutzung. Siehe 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% 可以由免费模型完成，而困难任务通过自动降级依然能获得顶级模型的质量。