Xrouter

Xrouter 是一个开源推理路由组件，部署在 OpenClaw 与您的大语言模型（LLM）服务商之间。它采用快速、硬件感知的分类器，为每个请求选择既能胜任任务又最具成本效益的模型。

本项目采用 MIT 许可协议。详见 MIT License。

核心功能

• 在 POST /v1/chat/completions 提供 OpenAI 兼容的反向代理服务。
• 三级分类器（0 = 低成本，1 = 中等成本，2 = 前沿模型），支持流式响应早期截断（early stream cutoff）。
• 硬件检测辅助工具，用于推荐本地推理引擎。
• 服务商选择向导，支持交互式配置本地及云端端点。
• 缓存层，支持 Redis 或内存内 LRU 回退策略。
• 当本地推理不可行时，自动启用纯云端模式。
• 令牌用量看板，访问地址为 /dashboard。

工作流程

flowchart TD
  A["客户端 / OpenClaw 请求"] --> B["路由器（OpenAI 兼容）"]
  B --> C{"是否启用分类器？"}
  C -->|否| F["路由至前沿服务商"]
  C -->|是| D["分类器（0 / 1 / 2）"]
  D --> E{"决策结果"}
  E -->|0| G["路由至低成本服务商"]
  E -->|1| M["路由至中等成本服务商"]
  E -->|2| F
  G --> H["服务商适配器（自动或显式指定）"]
  M --> H
  F --> H
  H --> I["上游 API 调用"]
  I --> J["流式响应 / 完整响应返回客户端"]

代码仓库结构

• src/server.js：路由器主逻辑与流式代理实现。
• src/classifier.js：分类器调用及重试逻辑。
• src/config.js：配置加载与环境变量解析。
• src/cache.js：Redis 缓存 + 内存 LRU 回退实现。
• src/token_tracker.js：令牌用量追踪逻辑。
• scripts/check_hw.js：硬件检测脚本。
• scripts/configure_providers.js：交互式服务商配置向导。

运行要求

• Node.js 20 或更高版本。
• 本地分类器引擎（可选）。
• 前沿服务商端点（必需）。

快速上手

1. 安装依赖。
2. （可选）启动本地模型服务器。
3. 运行配置向导。
4. 启动路由器。

npm install
npm run configure
npm run dev

使用方法

1. 启动本地模型服务器（可选，但强烈推荐）。
2. 运行向导以配置服务商与模型。
3. 启动路由器。
4. 向路由器发送 OpenAI 兼容格式的请求。
5. 通过响应头或看板检查路由决策结果。

本地示例配置（Ollama）：

ollama pull llama3.1
ollama run llama3.1

运行配置向导：

npm run configure

启动路由器：

npm run dev

测试请求示例：

curl -i http://localhost:3000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model":"any","messages":[{"role":"user","content":"Fix this sentence: I has a apple."}]}'

关注以下响应头字段：

• X-Xrouter-decision：值为 0、1 或 2。
• X-Xrouter-upstream：值为 cheap、medium 或 frontier。

打开看板页面：

• http://localhost:3000/dashboard

原始用量数据 JSON 接口：

• http://localhost:3000/usage

服务商选择（终端向导）
执行命令：

npm run configure

该向导将：

• 扫描硬件信息并推荐合适的本地引擎。
• 建议本地分类器模型。
• 允许您为低成本 / 中等成本 / 前沿路由分别指定服务商基础 URL、API 密钥及模型覆盖项。
• 生成 upstreams.json 文件，并可选择性更新 .env 文件。

快速启动模式

• 若您的设备支持运行本地模型，可选择“快速启动”模式。
• 快速启动将自动完成本地分类器配置。
• 低成本路由始终复用分类器所用的同一本地模型，避免 Ollama 模型切换开销。
• 您仅需手动选择中等成本和前沿路由对应的服务商与模型。
• 在 Apple Silicon 平台（Ollama 环境）下，向导会列出已安装的 Ollama 模型，并支持自动下载推荐模型。

路由行为

• 对每个未命中缓存的请求均调用分类器。
• 分类器返回的第一个 token（0、1 或 2）即决定最终路由路径。
• 若分类失败，路由器默认回退至前沿路由。
• 启用分类器时，必须配置低成本、中等成本与前沿路由三类服务商。

兼容性

• 路由器接收 OpenAI 风格请求，并在必要时进行协议转换。
• 服务商类型可显式指定（xrouter、openai_compatible、openai、anthropic、gemini、cohere、azure_openai、mistral、groq、together、perplexity），亦可设为 auto。
• auto 模式将基于基础 URL 或 API 密钥自动推断服务商适配器类型。
• 暴露 OpenAI 兼容端点的服务商使用 openai_compatible 适配器。
• Anthropic / Gemini / Cohere 的流式响应将被转换为 OpenAI 风格的 SSE 数据块。
• 非 OpenAI 类型的适配器当前仅支持纯文本消息及基础采样参数（temperature / top_p / stop）。

令牌用量看板

• GET /usage：返回 cheap、medium 和 frontier 三类路由的累计令牌用量。
• GET /dashboard：可视化 UI，展示各路由令牌用量分布与总量。
• 当低成本路由使用本地模型时，其用量计入 cheap 分类。

环境变量概览

• HOST：绑定主机地址，默认为 0.0.0.0。
• PORT：绑定端口，默认为 3000。
• ROUTER_API_KEY：启用认证，需携带 Authorization: Bearer 头部。
• LOG_LEVEL：日志级别（debug/info/warn/error）。
• LOG_TO_FILE：设为 true 时将日志写入文件。
• LOG_DIR：日志文件目录（默认 ./logs）。
• CLASSIFIER_ENABLED：设为 false 可禁用本地分类器。
• CLASSIFIER_BASE_URL：OpenAI 兼容的分类器端点地址。
• CLASSIFIER_MODEL：分类器模型名称。
• CLASSIFIER_SYSTEM_PROMPT：分类器系统提示词（单行字符串）。
• CLASSIFIER_TIMEOUT_MS：分类器调用超时时间（毫秒）。
• CLASSIFIER_FORCE_STREAM：强制以流式方式发起分类器请求。
• CLASSIFIER_WARMUP：服务启动时预热分类器。
• CLASSIFIER_WARMUP_DELAY_MS：预热请求前的延迟时间（毫秒）。
• CLASSIFIER_KEEP_ALIVE_MS：分类器预热期间的保活间隔（毫秒）。
• CLASSIFIER_LOADING_RETRY_MS：模型加载中时的重试间隔（毫秒）。
• CLASSIFIER_LOADING_MAX_RETRIES：模型加载中时的最大重试次数。
• CHEAP_BASE_URL：可选，若未设置则默认复用分类器基础 URL。
• CHEAP_API_KEY：低成本服务商 API 密钥。
• CHEAP_MODEL：可选，用于覆盖低成本路由的模型名称。
• CHEAP_PROVIDER：低成本路由的服务商类型（为空时默认为 auto）。
• CHEAP_HEADERS：可选，低成本服务商请求头（JSON 字符串化对象）。
• CHEAP_DEPLOYMENT：Azure 部署名称覆盖项（低成本路由）。
• CHEAP_API_VERSION：Azure API 版本覆盖项（低成本路由）。
• MEDIUM_BASE_URL：启用分类器时为必填项。
• MEDIUM_API_KEY：中等成本服务商 API 密钥。
• MEDIUM_MODEL：可选，用于覆盖中等成本路由的模型名称。
• MEDIUM_PROVIDER：中等成本路由的服务商类型（为空时默认为 auto）。
• MEDIUM_HEADERS：可选，中等成本服务商请求头（JSON 字符串化对象）。
• MEDIUM_DEPLOYMENT：Azure 部署名称覆盖项（中等成本路由）。
• MEDIUM_API_VERSION：Azure API 版本覆盖项（中等成本路由）。
• FRONTIER_BASE_URL：OpenAI 兼容的前沿服务商端点。
• FRONTIER_API_KEY：前沿服务商 API 密钥。
• FRONTIER_MODEL：可选，用于覆盖前沿路由的模型名称。
• FRONTIER_PROVIDER：前沿路由的服务商类型（为空时默认为 auto）。
• FRONTIER_HEADERS：可选，前沿服务商请求头（JSON 字符串化对象）。
• FRONTIER_DEPLOYMENT：Azure 部署名称覆盖项（前沿路由）。
• FRONTIER_API_VERSION：Azure API 版本覆盖项（前沿路由）。
• REDIS_URL：若设置该变量，则启用 Redis 缓存。

本地模型安装与运行指南
Ollama（Mac 最佳支持，跨平台最易上手）

• 安装：参考 Ollama Quickstart
• 拉取模型：ollama pull llama3.1
• 运行模型：ollama run llama3.1
• 基础 URL：http://localhost:11434
• 路由器配置： CLASSIFIER_BASE_URL=http://localhost:11434 CLASSIFIER_MODEL=llama3.1

vLLM（适用于 NVIDIA GPU）

• OpenAI 兼容服务端：vLLM OpenAI Server
• 示例命令：vllm serve NousResearch/Meta-Llama-3-8B-Instruct --dtype auto --api-key token-abc123
• 基础 URL：http://localhost:8000
• 路由器配置： CLASSIFIER_BASE_URL=http://localhost:8000 CLASSIFIER_MODEL=NousResearch/Meta-Llama-3-8B-Instruct

TensorRT-LLM（NVIDIA 平台，极致性能）

• 代码仓库：TensorRT-LLM
• 服务端命令：trtllm-serve
• 基础 URL：http://:
• 路由器配置： CLASSIFIER_BASE_URL=http://: CLASSIFIER_MODEL=

llama.cpp（CPU / AMD 平台备用方案）

• 代码仓库：llama.cpp
• 示例命令：llama-server -m model.gguf --port 8080
• 基础 URL：http://localhost:8080
• 路由器配置： CLASSIFIER_BASE_URL=http://localhost:8080 CLASSIFIER_MODEL=

Docker
使用 Redis 构建并运行路由器：

docker compose -f deploy/docker-compose.yml up --build

硬件检测
执行命令：

npm run check-hw

输出推荐的推理引擎：

• 大容量 NVIDIA GPU → tensorrt-llm
• 标准 NVIDIA GPU → vllm
• Apple Silicon → mlx
• CPU / AMD 平台 → llama.cpp

模型列表获取机制

• 向导在可能的情况下主动查询服务商的模型列表接口。
• OpenAI 兼容接口：/v1/models
• Anthropic 接口：/v1/models
• Gemini 接口：/v1beta/models
• Cohere 接口：/v1/models
• 若列表获取失败，向导将回退至 scripts/cloud_model_catalog.json 文件。

Star 历史