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

Leite jede Aufgabe automatisch an das beste Modell weiter – zuerst kostenlose Anbieter, kostenpflichtige als Fallback.

🎯 Warum Model Router?

Die meisten LLM-Integrationscodes verwenden ein fest codiertes Modell oder einen einzigen API-Anbieter. Das bedeutet:

• ❌ Teuer: Jede Anfrage (auch triviale) geht an ein kostenpflichtiges Spitzenmodell

• ❌ Anfällig: Ein Ausfall eines Anbieters = Totalausfall

• ❌ Unflexibel: Keine Möglichkeit, Modellfähigkeiten an die Aufgabenschwierigkeit anzupassen

Model Router löst alle drei Probleme mit einem einfachen, abhängigkeitsarmen Design:

• ✅ Aufgabenschwierigkeitsklassifizierung: 5 Stufen (vision / long / complex / medium / simple) mittels Schlüsselwort- und Inhaltslängen-Heuristiken (kostenlos, kein LLM beteiligt)

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

• ✅ Keine Drittanbieter-Abhängigkeiten: Die 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…) · File-Watch-Daemon

🏗 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 anbieterbezogene errors für vollständige Beobachtbarkeit.

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

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

python mcp_server.py

Registrieren Sie 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 (File-Watch-Modus)

# 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

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

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

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

• levels: Menschenlesbare Beschreibungen pro Stufe

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

📄 Lizenz

MIT – kostenlos für private und kommerzielle Nutzung. Siehe LICENSE.

Inspiriert von realer Kostenoptimierung: ~90% der alltäglichen Aufgaben können von kostenlosen Modellen bedient werden, während schwierige Aufgaben durch automatischen Fallback weiterhin Spitzenmodellqualität erhalten.