UncommonRoute 深度研究报告：开源智能 LLM 路由系统

> 研究日期：2026-03-20 | 项目地址：GitHub - CommonstackAI/UncommonRoute

TL;DR

UncommonRoute 是一个本地运行的 LLM 智能路由器，通过分析请求复杂度自动选择最合适的模型——简单任务用便宜模型，复杂任务用强模型。它使用一个基于 Averaged Perceptron 的本地分类器（39 维特征，0.5ms 延迟），配合多维候选评分系统（成本、延迟、可靠性、cache 亲和度、用户反馈），实现了 92.3% 的路由准确率和约 67% 的成本节省。项目采用 MIT 协议，代码质量高（281 个测试），但仍处于早期阶段，核心价值在于"本地优先"的设计理念和与 Commonstack AI API 网关的协同推广。

1. 项目概述与团队背景

1.1 什么是 UncommonRoute

UncommonRoute 是一个 Python 编写的本地 LLM 路由代理（proxy），部署在用户本机，拦截来自 AI 客户端（Codex、Claude Code、Cursor、OpenAI SDK 等）的请求，分析请求难度后自动将其路由到最合适的上游模型。

核心理念用项目自己的话说就是："按难度路由，不按习惯路由"。"what is 2+2?" 和 "设计一个容错分布式数据库" 不应该走同一个模型。

你的客户端 (Codex / Claude Code / Cursor)
            |
            v
      UncommonRoute (本机 proxy, 端口 8403)
            |
            v
      上游模型 API (Commonstack / OpenAI / Ollama / ...)

1.2 Commonstack AI 是谁

Commonstack (文档) 是一个统一的 LLM API 网关服务，类似于 OpenRouter：一个 API Key 就能访问 OpenAI、Anthropic、Google、DeepSeek、MiniMax、智谱、xAI 等多家供应商的模型。

关键信息：

• 官网：commonstack.ai
• 文档：docs.commonstack.ai
• 商业模式：按 token 计费，无月费，支持 Stripe 和支付宝
• 团队成员：@anjieyang (Anjie Yang) 是主要开发者，同时也是 @0xViviennn / @realanjieyang 的 Twitter 账号
• 特色：双协议支持（OpenAI 兼容 + Anthropic 兼容），新用户首充 20% 额外赠送（最高 $500）

重要背景：UncommonRoute 和 Commonstack 是同一团队的产品。UncommonRoute 开源做路由器，Commonstack 做付费的统一 API 网关——前者自然会推荐后者作为默认 upstream，形成"开源获客 → 商业变现"的闭环。这并不是坏事，但使用者需要意识到这一点。

1.3 项目基本数据

2. 技术架构深度分析

2.1 整体架构

UncommonRoute 的路由决策分为三个核心阶段：

请求到达
   |
   v
[Classifier] → 分析 prompt 复杂度，输出 tier + complexity score
   |
   v
[Selector] → 结合成本/延迟/可靠性/反馈等多维度打分，选择最优模型
   |
   v
[Proxy] → 转发请求到上游，处理 fallback、stream、格式转换

2.2 Difficulty Scoring：本地神经网络分类器

源码位置：uncommon_route/router/classifier.py 和 uncommon_route/router/learned.py

三级分类架构

分类器采用级联设计：

Level 0 — Trivial Override（正则规则）

• 识别问候语（多语言：英/中/俄/西/日/韩/印地/土耳其语）
• Token 数 ≤ 2 → SIMPLE
• Token 数 > 100,000 → COMPLEX
• 零延迟，零成本

Level 1 — 本地 Averaged Perceptron 模型（主力）

• 输入：39 维特征向量
• 输出：连续的 complexity 分数 (0.0 ~ 1.0) + 离散 tier (SIMPLE/MEDIUM/COMPLEX)

Level 2 — Rule-based Fallback（当模型不可用时）

• 手工调参的权重 + sigmoid 置信度

39 维特征向量详解

这是整个分类器最核心的创新——完全脚本无关（Script-Agnostic），不依赖特定语言的关键词：

12 个结构特征 (s_*)：

15 个 Unicode Block 特征 (u_*)：

latin, cjk, hangul, arabic, cyrillic, devanagari,
thai, tibetan, ethiopic, georgian, armenian,
greek, hebrew, myanmar, tamil

每个维度表示该文字系统字符的占比，让模型自动学习"高 CJK + 问号 + 短文本 = SIMPLE"这样的跨语言模式。

12 个关键词特征 (k_*)：

code_presence, reasoning_markers, technical_terms,
creative_markers, simple_indicators, imperative_verbs,
constraint_count, output_format, domain_specificity,
analytical_verbs, agentic_task, multi_step_patterns

Averaged Perceptron 模型

源码：learned.py 中的 ScriptAgnosticClassifier

• 算法：Averaged Perceptron（而非深度学习，刻意选择的轻量方案）
• 3 个类别：SIMPLE / MEDIUM / COMPLEX
• 额外的 char n-gram 特征（3-5 gram，hash trick 到 4096 维，权重缩放 0.3x）
• 在线学习：支持 update() 方法做增量 Perceptron 更新
• Softmax 输出 → 连续 complexity：不是直接取 argmax，而是用概率加权锚点值计算连续分数：

`

SIMPLE=0.0, MEDIUM=0.40, COMPLEX=0.90

complexity = Σ P(tier) × anchor(tier)

`

• 模型大小：JSON 文件（权重 dict），几十 KB，推理延迟 < 1ms
• Ordinal-aware tiebreaking：当两个 tier 概率接近时（差 < 0.10），优先选择离 MEDIUM 更近的

为什么选 Perceptron 而不是 Transformer？

这是一个深思熟虑的设计决策：

1. 延迟要求：路由器本身不能成为瓶颈，0.5ms 是硬约束

2. 本地运行：不能依赖 GPU 或外部推理服务

3. 在线学习：Perceptron 天然支持增量更新

4. 可解释性：39 个命名特征 + 线性权重，完全可审计

重要设计决策：只看 User Prompt

分类器只从用户 prompt 提取特征，刻意忽略 system prompt。原因是：

> "Agentic frameworks (Claude Code, Cursor, etc.) inject massive system prompts full of tool definitions, code examples, and instructions that inflate every complexity signal and cause nearly all queries to route to COMPLEX."

这是一个很有工程洞察力的决策——如果把 system prompt 也算进去，大部分 agent 场景的请求都会被错误地标为 COMPLEX。

2.3 路由算法：多维候选评分系统

源码：uncommon_route/router/selector.py

选择器支持两种模式：

• Tier-based（旧版）：每个 tier 有预配置的候选模型列表
• Pool-based（v2，当前主推）：所有发现的模型统一竞争，complexity 分数动态调整权重

候选模型综合评分公式

每个候选模型的最终得分由多个加权维度组成：

total = (
    weights.editorial × editorial           # 编辑排序偏好
  + weights.cost × cost_score              # 成本（反向归一化）
  + weights.latency × latency_score        # 延迟
  + weights.reliability × reliability      # 可靠性
  + weights.feedback × feedback_score      # 用户反馈
  + weights.cache_affinity × cache_score   # Cache 亲和度
  + weights.byok × byok_bonus             # BYOK 模型加成
  + weights.free_bias × free_bonus         # 免费模型偏好
  + weights.local_bias × local_bonus       # 本地模型偏好
  + weights.reasoning_bias × reasoning_bonus  # 推理能力
)

当 Bandit 探索模式激活时，还会加上：

total += bandit_config.reward_weight × (bandit_mean - 0.5)
total += exploration_bonus  # UCB 风格的探索奖励

各维度的具体计算

延迟评分（latency_score）：

ttft_score = 1.0 / (1.0 + ttft_ms_ewma / 1500.0)  # TTFT 越低越好
tps_score = min(1.0, tps_ewma / 80.0)               # TPS 越高越好
latency = ttft_score × 0.6 + tps_score × 0.4         # 加权组合

• TTFT（Time to First Token）：1500ms 作为参考基准线
• TPS（Tokens Per Second）：80 TPS 作为满分阈值
• TTFT 权重更高（0.6），因为用户体感更敏感

Cache 亲和度（cache_affinity）：

cache_affinity = 0.45 + cache_hit_ratio × 0.75 - cache_write_ratio × 0.20

• Cache 命中率越高越好
• Cache 写入率有小幅惩罚（写入意味着首次成本高）
• 基线 0.45，对新模型不过分惩罚

成本计算：

cost = (input_tokens / 1M) × input_price × effective_multiplier
     + (output_tokens / 1M) × output_price

• effective_multiplier 基于实际 cache 命中率动态调整
• 节省率对比 baseline model（默认 Claude Opus，$5/$25 per MT）

Reward 函数（综合奖励）：

来自 model_experience.py 的观测，综合考虑成功率、延迟、TPS、cache 命中率和成本乘数的加权奖励。

Multi-Armed Bandit 探索

选择器内置了 UCB 风格的探索机制：

def _bandit_bonus(...):
    if samples < warmup_pulls:
        return exploration_weight  # 冷启动期给满探索奖励
    return exploration_weight × sqrt(log(bucket_pulls + 1) / (samples + 1))

带有安全护栏：

• 候选成本超过最便宜选项的 max_cost_ratio 倍时，不给探索奖励
• 可靠性低于 min_reliability 且样本足够时，不给探索奖励

Model Experience Store：自适应学习记忆

源码：uncommon_route/model_experience.py

系统维护一个持久化的模型体验记忆，使用 EWMA（指数加权移动平均） 跟踪每个模型在每个 (mode, tier) 组合下的表现：

@dataclass
class ModelExperienceRecord:
    success_ewma: float = 0.5        # 成功率
    ttft_ms_ewma: float = 0.0        # 首 token 延迟
    tps_ewma: float = 0.0            # 吞吐量
    preference_ewma: float = 0.0     # 用户偏好
    cache_hit_ratio_ewma: float = 0.0  # Cache 命中率
    input_cost_multiplier_ewma: float = 1.0  # 实际成本乘数
    reward_ewma: float = 0.5         # 综合奖励

• EWMA 的 alpha 默认 0.25（可调，范围 0.05~0.9）
• 用户反馈信号：ok (+0.14)、weak (-0.22)、strong (-0.10)
• 支持文件存储和内存存储两种后端

2.4 其他重要组件

Spend Control（花费控制）：

• 支持 per_request / hourly / daily / session 四个维度的限额
• 触发限制时返回 HTTP 429 + reset_in_seconds

Composition Pipeline（大输出压缩）：

• 超长工具输出自动压缩
• Artifact 存储机制（artifact://...）
• Semantic side-channel summary
• 长历史 checkpoint

Model Discovery：

• 自动拉取上游 /v1/models
• 构建 live model pool
• 内部模型名到上游模型名的映射 + learned alias

2.5 与其他 Routing 方案对比

核心差异化：

1. 完全本地：请求分析和路由决策都在本机完成，不会把 prompt 发给任何第三方路由服务。这对企业场景是硬需求。

2. 脚本无关的特征工程：不依赖特定语言的关键词检测，而是用结构化特征 + Unicode block 分布，理论上对任何语言都有效。

3. 自适应学习：在线 Perceptron 更新 + EWMA 体验记忆 + Bandit 探索，系统会随使用逐渐改善。

相比 RouteLLM 的区别：RouteLLM 使用训练好的 BERT 或 random forest 做二分类（strong model vs weak model），而 UncommonRoute 做三分类，并且引入了连续 complexity 分数和完整的候选评分系统。

3. 代码质量评估

3.1 代码结构

项目结构清晰，模块化程度高：

uncommon_route/
├── router/
│   ├── classifier.py      # 级联分类器
│   ├── selector.py         # 模型选择器
│   ├── structural.py       # 结构特征提取
│   ├── keywords.py         # 关键词特征提取
│   ├── learned.py          # Perceptron 模型
│   ├── config.py           # 路由配置
│   ├── types.py            # 类型定义
│   └── model.json          # 预训练权重
├── model_experience.py     # 自适应学习记忆
├── spend_control.py        # 花费控制
├── composition.py          # 大输出压缩
├── semantic.py             # 语义压缩
├── feedback.py             # 用户反馈
├── stats.py                # 统计
├── session.py              # 会话管理
├── providers.py            # BYOK provider 管理
├── openclaw.py             # OpenClaw 插件集成
└── __init__.py             # 导出 80+ 公开 API

3.2 优点

1. 类型标注完整：全面使用 Python dataclass、type hints、Literal 类型，代码可读性极好

2. 抽象设计合理：存储层有清晰的 ABC 抽象（ModelExperienceStorage、SpendControlStorage），方便测试和扩展

3. 测试覆盖扎实：281 个测试用例全部通过，从 README 的 badge 来看是认真维护的

4. 数值稳定：到处可见 max(), min() 的 clamp 操作，防止极端值

5. 防御性编程：JSON 加载有完整的异常处理，文件权限设置合理（0o700 目录，0o600 文件）

6. 良好的文档：每个模块都有 docstring，关键设计决策有内联注释说明"为什么"

3.3 可以改进的地方

1. 单人项目风险：从 git 记录来看，主要是 Anjie Yang 一个人在开发。对于要在生产环境使用的路由器，bus factor = 1 是个风险。

2. Benchmark 自我评测：92.3% 的准确率是在自己手写的 763 条评测集上测的，没有使用第三方标准 benchmark。ClawRouter 和 NotDiamond 的对比数据也是他们自己跑的。

3. 部分 TODO：Commonstack 文档中 "Routing and fallback: Coming soon" 的标注暗示这个能力还在建设中。

4. Online model 偏移风险：在线 Perceptron 更新如果被持续错误反馈驱动，可能会逐渐偏离——虽然有 rollback_online_model() 作为安全阀。

3.4 代码风格评价

代码风格成熟、一致，明显不是随便写的。命名清晰（_blend_metric、_normalize_tier_label、_check_trivial），函数单一职责，没有 God Class。整体感觉像一个有经验的工程师写的生产级代码，而不是周末 hack。

4. 实验结果分析

4.1 路由准确率

项目宣称的 benchmark 结果：

评测集：763 条手写 prompt，覆盖 15 种语言和 35 个类别。

分析：

• 92.3% 的准确率在自评 benchmark 上是很好的数字
• 但需注意这是自己标注的数据集，没有第三方验证
• MEDIUM F1 (88.7%) 比 SIMPLE 和 COMPLEX 低，说明中等复杂度的界限确实模糊
• NotDiamond 在 COMPLEX F1 上得 0.0% 很可能是因为它做的是二分类（cost 优先模式）而不是三分类

4.2 成本模拟

基于 131 个请求的 agent coding session 模拟：

200 请求的扩展模拟可以在 bench/cost_simulation.py 中找到，模拟了真实 OpenClaw agent 编码会话中的请求分布：

• ~30% SIMPLE（记忆查询、文件操作、工具调用）
• ~45% MEDIUM（代码生成、调试、解释、review）
• ~20% COMPLEX（架构设计、系统重构、算法分析）
• ~5% REASONING（数学证明、正确性验证）

4.3 MiniMax m2.7 为什么能排第一？

根据项目提供的信息和外部数据，MiniMax m2.7 在 200+ 组实验中综合排名第一，原因主要是极致的性价比：

定价优势：

• MiniMax m2.7：$0.30/MT 输入，$1.20/MT 输出（来源）
• 对比 Claude Opus：$5.00/$25.00
• 对比 GPT-5.2：$1.75/$14.00
• 约为 Opus 的 1/17，GPT 的 1/6

质量不差：

• SWE-Pro 准确率 56.22%，匹配 GPT-5.3-Codex（来源）
• Chatbot Arena 得分 86.2%，仅落后 GLM-5 和 GPT-5.4 0.2 个百分点（来源）
• VentureBeat 评价其为"世界上最实惠的前沿 AI 模型之一"（来源）

在路由场景中的关键逻辑：

在 UncommonRoute 的评分体系中，MiniMax m2.7 受益于：

1. 极低成本：在成本维度上几乎满分

2. 质量够用：对 SIMPLE/MEDIUM 任务，质量足以胜任

3. 路由覆盖面广：大部分请求是 SIMPLE/MEDIUM，m2.7 可以覆盖这些场景

4. 综合评分占优：当 cost weight 较高时（这在多数使用场景中是默认的），m2.7 的综合得分最高

但需要注意：

• "200+ 组实验"的具体细节没有公开（实验设置、评测指标、对比基线不完全透明）
• MiniMax 通过 Commonstack 可以访问，这恰好是 UncommonRoute 的推荐上游——存在利益关联
• m2.7 刚发布几天（2026-03-18），这个排名声明的时效性还需观察

4.4 成本模拟中的模型阵容

从 cost_simulation.py 可以看到项目用于对比的完整模型池：

5. 实际应用场景与局限性

5.1 最佳适用场景

1. AI Coding Agent 工作流：Codex、Claude Code、Cursor 等工具的长会话中，大量简单请求（文件读取、状态查询）不需要旗舰模型

2. 企业内部部署：对数据隐私有要求，不希望 prompt 经过第三方路由服务

3. 多模型探索：同时接入多个 provider，让系统自动发现最优组合

4. 预算敏感场景：内置 spend control，适合个人开发者或小团队控制开支

5.2 局限性

1. 分类粒度有限：只有 SIMPLE/MEDIUM/COMPLEX 三档，而实际需求可能更细（比如"需要图像理解"、"需要长上下文"、"需要代码执行"等）

2. "质量保留 93.5%"的含义模糊：这个指标是模拟计算的，不是真实 A/B 测试。实际质量损失取决于具体任务

3. 冷启动问题：EWMA 体验记忆需要足够的请求才能准确，新模型或新用户初期路由可能不够准

4. 单上游依赖：虽然支持 BYOK 多 provider，但主要设计路径还是通过 Commonstack 这一个上游

5. 缺少 LLM-as-judge 路由：不像 Martian 那样可以用一个小模型先"预判"请求应该用什么级别的模型。纯特征工程的天花板在复杂场景下可能低于 LLM-based 路由

6. 没有 streaming routing：路由决策基于完整 prompt，不能对流式输入做渐进式路由

7. 评测不够独立：所有 benchmark 都是自评，缺少第三方验证

5.3 与 OpenClaw 的关系

项目有专门的 OpenClaw 插件集成：

openclaw plugins install @anjieyang/uncommon-route

这意味着 UncommonRoute 可以作为 OpenClaw 的 provider 注册，自动拦截和路由请求。对于已经使用 OpenClaw 的用户，这是一个非常自然的集成路径。

6. 对我们的启示

6.1 与 OpenRouter Model Explorer (models.jaylab.io) 的关系

models.jaylab.io 做的是模型发现和信息聚合（帮用户看清模型世界的全貌），而 UncommonRoute 做的是自动化决策（根据请求自动选模型）。两者是互补关系：

• Model Explorer：帮你"选哪几个模型值得用"
• UncommonRoute：帮你"这条请求该用哪个"

6.2 值得借鉴的设计

1. 39 维特征工程：结构特征 + Unicode block + 关键词的组合，是一个非常实用且可复用的 prompt 复杂度评估方案。可以在 models.jaylab.io 中加入"输入你的 prompt，看看它属于什么难度级别"的功能

2. 连续 complexity score：比离散分类更灵活，允许平滑的权重插值

3. EWMA 体验记忆：用简单但有效的方式追踪模型表现，适合本地场景

4. 本地优先理念：路由决策不依赖外部服务，延迟极低

6.3 是否值得集成？

短期：不建议直接集成。项目还比较新，单人维护，且与 Commonstack 商业利益绑定。

长期：值得关注以下方向：

• 如果 routing 准确率能在独立评测中验证，可以考虑在 models.jaylab.io 中借鉴其分类逻辑
• 39 维特征提取可以作为独立模块复用
• Spend Control 和 Experience Memory 的设计模式值得参考

6.4 需要警惕的

1. 选择性 benchmark：对比对象选的是 ClawRouter（52.6%，看起来很弱）和 NotDiamond cost 模式（46.1%，基本不 work）。没有和 RouteLLM 或其他更成熟的方案做对比

2. Commonstack 绑定：UncommonRoute 的默认体验路径指向 Commonstack，这是商业策略的一部分

3. MiniMax m2.7 "排名第一"的宣传：在未公开实验细节的情况下，这更像是营销话术

7. 总结

UncommonRoute 是一个技术实现扎实、设计理念清晰的本地 LLM 路由器。它最大的亮点是：

• 真正的本地优先：0.5ms 路由延迟，不泄露 prompt 到第三方
• 优雅的特征工程：39 维脚本无关特征 → Averaged Perceptron，简单有效
• 完整的自适应系统：在线学习 + EWMA 记忆 + Bandit 探索
• 工程质量过关：类型完备、测试充分、文档清晰

主要风险是：

• 单人项目，bus factor = 1
• 自评 benchmark，缺少独立验证
• 与 Commonstack 的商业关联需要使用者知情

对于正在使用多个 LLM 的开发者来说，UncommonRoute 的核心思想值得认真考虑——即使不用它，"不是所有请求都需要最贵的模型"这个理念本身就能帮你省钱。

参考链接

• GitHub 仓库：
• Commonstack 官网：
• Commonstack 文档：
• MiniMax m2.7 官方页面：
• MiniMax m2.7 发布公告：
• MiniMax m2.7 性能分析（Artificial Analysis）：
• VentureBeat MiniMax m2.7 报道：
• Reddit MiniMax m2.7 Benchmark 讨论：
• RouteLLM 论文：
• LLM Router 对比平台：
• Not-Diamond Awesome AI Model Routing：
• OpenRouter：