ypollak2/llm-router

pip install llm-routing   # PyPI name is llm-routing; the CLI command is llm-router

• 为什么安装这个

• 在 RouterArena 上排名第 8

• 快速开始

• 路由示例

• 适用工具

• 工作原理

• 功能特性

• 命令行

• 提供商

• 路由策略

• MCP 工具

• 节省费用：原理说明

• 信任、隐私与本地优先设计

• 配置

• 文档

• 企业版

• 贡献

为什么安装这个

AI 编码工具默认会将过多提示词发送给高级模型。

这意味着：

• 你在简单问题上浪费了付费令牌

• 你消耗 Claude、Gemini 或 OpenAI 配额的速度比必要的更快

• 当某个提供商限流或宕机时，你就得停下工作

llm-router 位于你的编码工具和模型提供商之间。它会对每个提示词进行分类，先尝试最便宜且能胜任的模型，并在需要时自动回退。

你保持相同的工作流程。路由器在底层改变模型选择。

Related MCP server: MCP AI Router

在 RouterArena 上排名第 8

llm-router 在 RouterArena 上经过独立基准测试，排名 第 8 —— 这是一个社区排行榜，根据路由准确率、延迟、成本效益和回退可靠性来评估模型路由器。

快速开始

1. 安装

pip install llm-routing
llm-router install

PyPI 上的包名：llm-routing。命令行工具：llm-router。

2. 添加提供商（可选）

export OPENAI_API_KEY="sk-..."          # GPT-4o, o3
export GEMINI_API_KEY="AIza..."         # Gemini Flash/Pro (free tier available)
export OLLAMA_BASE_URL="http://localhost:11434"  # Local models (free)
export OPENROUTER_API_KEY="sk-or-v1-…"  # 343 OpenRouter models (qwen, deepseek, grok, …)

在 Claude Code Pro/Max 订阅上零 API 密钥即可使用 —— 路由通过 MCP 工具调用外部模型，仅在有益时才这样做。添加 OPENROUTER_API_KEY 可解锁 cost_aggressive 策略使用的开放权重主力模型池。

3. 验证

llm-router health            # Check provider connectivity

如果你已经在使用 Claude Code、Codex 或 Gemini CLI，请保持现有工作流程，让 llm-router 在底层为你选择模型。

路由示例

具体链路取决于你配置的提供商、预算配置文件和路由策略。

适用工具

• 全自动路由 意味着钩子会拦截提示词并自动路由，无需改变工作流程。

• 手动 MCP 工具 意味着可以通过 llm_query 等工具按需使用路由。

llm-router install                    # Claude Code (default)
llm-router install --host codex       # Codex CLI
llm-router install --host gemini-cli  # Gemini CLI
llm-router install --host vscode      # VS Code
llm-router install --host cursor      # Cursor

有关每个主机的完整详情，请参阅 guide/HOST_SUPPORT_MATRIX.md。

保护你的 Claude Code 5 小时配额

enforce: smart + mode: zero_claude 使提示词要么在外部完成，要么在原生 Claude 运行之前停止 —— 请参阅 guide/GETTING_STARTED.md。

工作原理

User prompt
    │
    ▼
┌──────────────────────┐
│ Complexity Classifier │  ← Heuristic (free, instant) or Ollama/Flash ($0.0001)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Free-First Router   │  ← Tries cheapest model first, walks up the chain
│                      │
│  Ollama (free)       │
│  → Codex (prepaid)   │
│  → Gemini Flash      │
│  → GPT-4o / Claude   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Guards (parallel)   │  ← Circuit breaker, budget pressure, quality check
└──────────┬───────────┘
           │
           ▼
      Response + cost logged to local SQLite

许多任务的分类是免费的（正则启发式可捕获约 70%），对于模糊提示词，在使用本地 Ollama 或 Gemini Flash 时也几乎免费。

功能特性

不仅仅是"将廉价提示词发送给廉价模型"：

• 密钥永远不会离开你的机器。 包含 API 密钥、令牌或私钥的提示词只会路由到本地模型 —— 故障关闭，因此无法到达外部提供商。

• 成本反转的订阅路由。 简单和中等提示词优先使用免费/本地模型，复杂提示词优先使用你的付费席位，当配额紧张时该席位会被降级。通过 LLM_ROUTER_SUBSCRIPTION_PROVIDER 选择启用。

• 带熔断器的自动回退。 失败或限流的提供商会跳过，而不是反复重试直到崩溃。

• 你可以看到它在工作。 状态行、终端标题和系统通知显示最近路由的模型、节省费用和健康状况 —— 适用于没有原生状态栏的主机。

• 会话结束摘要。 与基线的节省对比、层级分布、各提供商成本、延迟 p50/p95/p99 和热门路由。

• 也支持媒体和流水线。 llm_image / llm_video / llm_audio，以及用于多步骤研究的 llm_orchestrate。

命令行

llm-router install      # wire up your host (Claude Code by default)
llm-router health       # provider connectivity
llm-router status       # savings + quota at a glance
llm-router doctor       # diagnose a broken setup

完整命令参考：guide/GETTING_STARTED.md

提供商

20+ 提供商，免费优先。Ollama（本地，免费）引领链路；OpenRouter（一个密钥背后 343 个模型）是最大的单一解锁；Gemini 和 Groq 有可用的免费层级。Anthropic 通过你现有的 Claude 订阅即可使用 —— 无需 API 密钥。

每个提供商、其模型、成本层级和环境变量：guide/PROVIDERS.md

路由策略

策略决定了路由器将提示词从你的高级模型转移出去的积极程度 —— 从 conservative（节省 10–15%）到 balanced（默认，节省 35–45%）再到 cost_aggressive（节省 70–85%，需要 OPENROUTER_API_KEY）。

llm-router policy set cost_aggressive

全部六种策略、阈值和 YAML 模式：guide/POLICIES.md

MCP 工具

60 个工具涵盖路由、分析、代码、媒体、预算和诊断 —— 对任何 MCP 主机开放。默认的 consolidated 界面显示 11 个前端工具；设置 LLM_ROUTER_SLIM=full 可查看全部 60 个。

每个工具及其签名：guide/TOOLS.md

节省费用：原理说明

节省费用是通过将实际支出与将每个任务路由到 Claude Sonnet/Opus 的基线进行比较来计算的。

方法论：

1. 每个路由任务记录：使用的模型、消耗的令牌、估算成本

2. 基线成本按相同令牌由链路中最昂贵的模型处理来计算

3. 节省 = (基线 - 实际) / 基线

假设和限制：

• 基线假设你本来会对所有任务使用 Opus/Sonnet（最坏情况）

• 令牌估算使用 len(text) / 4 近似值，而非精确的分词器计数

• 成本数据来自 LiteLLM 的定价表（可能滞后于提供商价格变动）

• 节省费用因工作负载而异 —— 代码密集型会话会更多路由到廉价模型

• 路由器本身会增加少量开销（每个模糊任务的分类成本约为 $0.0001）

观察范围： 根据策略和任务组合，节省 35–80%。某些文档中的"87%"数字代表单个用户在特定开发周期内的峰值，而非保证结果。

信任、隐私与本地优先设计

llm-router 完全在你的机器上运行。没有托管代理，没有遥测，无需账户。

我们做的事：

• 从结构化日志中清除 API 密钥

• 在安装前检测钩子死锁

• 将所有数据存储在本地 ~/.llm-router/

• 遵守提供商的速率限制和服务条款

你应该知道的：

• 提示词会发送至路由器选定的提供商——请查看你所用提供商的隐私政策

• 使用日志（SQLite）在静态存储时未加密——如有需要请使用全盘加密

• 路由器无法在提供商层面阻止模型越狱或提示注入

负责任披露政策请参阅 SECURITY.md。

配置

一切皆环境变量——无需配置文件即可启动：

export OPENROUTER_API_KEY="sk-or-v1-..."          # biggest single unlock
export OLLAMA_BASE_URL="http://localhost:11434"   # local, free
export LLM_ROUTER_POLICY="cost_aggressive"        # routing policy
export LLM_ROUTER_ENFORCE="smart"                 # off | advise | smart | hard

完整参考、配置文件模式及各主机覆盖项： guide/GETTING_STARTED.md

文档

完整索引：guide/README.md

企业版

llm-router 专为个人开发者和小型团队打造：本地节省成本、零运维开销、无需任何托管服务。如果你需要团队级策略执行、审计导出、SSO 或按组织预算，那正是 Chuzom 的用途。

贡献

欢迎贡献。完整指南请参阅 CONTRIBUTING.md。

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (1900+)
uv run ruff check src/ tests/   # Lint

-|-----------| | llm-routing | 当前 PyPI 包（pip install llm-routing） | | llm-router | CLI 命令及 GitHub 仓库名称 | | claude-code-llm-router | 已弃用的旧版包（重定向至 llm-routing） |