UncommonRoute
notes/research/github/2026-03-21-0716-uncommonroute.md
Port 8777
---
title: UncommonRoute - Local LLM Router for Cost Optimization
category: research
source_type: github
created_by: 小美虾
status: collected
tags: [llm, router, cost-optimization, openclaw, ai-infrastructure]
created_at: 2026-03-21T07:16:00+08:00
---
# UncommonRoute
**GitHub:** https://github.com/CommonstackAI/UncommonRoute
## 简介
一个轻量级的本地 LLM 路由器，自动为每个 AI 请求平衡成本和质量。
- **85%+ 成本节省**
- **92.3% 路由准确率**
- **<1ms 决策延迟**
适用于 OpenClaw、Codex、Claude Code、Cursor 和 OpenAI SDK。
## 核心价值
大多数 AI 工具的错误假设：每个请求都值得使用相同的模型。
UncommonRoute 在客户端和上游 API 之间添加一层本地路由：
```
你的客户端 (Codex / Claude Code / Cursor / OpenAI SDK / OpenClaw)
↓
UncommonRoute (在你的机器上运行)
↓
你的上游 API (Commonstack / OpenAI / Ollama / vLLM / Parallax / ...)
```
不托管模型，只做快速的本地路由决策，转发请求到选定的上游，并在上游模型名称或可用性不匹配时提供**回退逻辑（fallback chain）**。
## 重试与回退机制
UncommonRoute 内置智能回退链，当首选模型不可用或失败时自动切换到备选模型：
- **自动故障转移**：上游模型名称不匹配或 API 失败时自动重试
- **回退链配置**：可为每个路由决策配置多级备选模型
- **无缝恢复**：无需客户端重新发送请求
这种机制确保即使上游服务波动，请求也能成功完成。
## 性能数据
- **92.3%** 保持集路由准确率（763 个手写提示词，15 种语言，35 个类别）
- **86.4%** 模拟成本降低（131 请求编码会话 vs 始终使用 claude-opus-4.6）
- **~0.5ms** 平均路由延迟
- **281** 通过测试
### 成本对比示例
| 场景 | 总成本 |
|------|--------|
| 始终使用 anthropic/claude-opus-4.6 | $1.7529 |
| UncommonRoute | $0.238 |
## 快速开始
### 安装
```bash
pip install uncommon-route
```
或使用安装器：
```bash
curl -fsSL https://anjieyang.github.io/uncommon-route/install | bash
```
### 测试路由（无需真实上游）
```bash
uncommon-route route "write a Python function that validates email addresses"
uncommon-route debug "prove that sqrt(2) is irrational"
```
### 配置上游
```bash
# Commonstack: 一个 key，多个提供商
export UNCOMMON_ROUTE_UPSTREAM="https://api.commonstack.ai/v1"
export UNCOMMON_ROUTE_API_KEY="csk-..."
# OpenAI 直连
export UNCOMMON_ROUTE_UPSTREAM="https://api.openai.com/v1"
export UNCOMMON_ROUTE_API_KEY="sk-..."
# 本地 OpenAI 兼容服务器 (Ollama, vLLM 等)
export UNCOMMON_ROUTE_UPSTREAM="http://127.0.0.1:11434/v1"
# Parallax 调度器端点 (实验性)
export UNCOMMON_ROUTE_UPSTREAM="http://127.0.0.1:3001/v1"
```
### 启动服务
```bash
uncommon-route serve
```
启动横幅会显示：
- 上游主机
- 本地代理 URL
- 仪表板 URL
- 快速健康检查命令
### Codex 集成
```bash
uncommon-route setup codex
```
或手动配置：
```bash
export OPENAI_BASE_URL="http://localhost:8403/v1"
export OPENAI_API_KEY="not-needed"
uncommon-route serve
```
## 使用场景
适合将 premium-model 预算花在能改变答案的地方，而不是浪费在：
- 简单计算（"2+2 等于几？"）
- 工具选择
- 日志摘要
- Agent 循环中的普通中间轮次
## 相关链接
- [简体中文文档](https://github.com/CommonstackAI/UncommonRoute/blob/main/README.zh-CN.md)
- [OpenClaw 集成](https://openclaw.ai)