🚀 LLMRouter：开源的大型语言模型路由库

✨ 简介

LLMRouter 是一个智能路由系统，旨在通过动态选择最适合每个查询的模型来优化大型语言模型的推理过程。为了实现智能路由，它定义了以下功能：

1. 🚀 智能路由：根据任务复杂度、成本和性能要求，自动将查询路由到最优的大型语言模型。
2. 📊 多种路由模型：支持 超过16种路由模型，分为四大类——单轮路由、多轮路由、代理式路由和个性化路由——涵盖了广泛的策略，如KNN、SVM、MLP、矩阵分解、Elo评分、基于图的路由、BERT-based路由、混合概率方法、转换分数路由等。
3. 🛠️ 统一的命令行界面：完整的命令行接口，用于训练、推理以及通过Gradio构建的交互式聊天界面。
4. 📈 数据生成流水线：从11个基准数据集自动生成训练数据的完整流水线，具备自动API调用和评估功能。

📰 最新消息

• 🖥️ [2026-02]：ComfyUI界面——我们发布了LLMRouter的可视化界面！现在你可以直观地构建数据生成和路由流水线，拖拽节点来训练路由模型，并实时监控性能。详情请参见 ComfyUI界面。

• 🔗 [2026-02]：OpenClaw路由器——兼容OpenAI的服务器，集成OpenClaw！我们还发布了llmrouter-lib v0.3.1。你可以将LLMRouter部署为生产级API服务器，通过 OpenClaw 与Slack、Discord等消息平台无缝对接。该版本新增了多模态理解（图像/音频/视频）、检索增强型路由记忆、流式传输支持，以及所有16+种LLMRouter路由策略。详情请参见 OpenClaw路由器集成。若需在Slack等社交平台上部署，请参考 入门指南，获取详细的设置步骤。

• ⭐ [2026-01]：LLMRouter 刚刚突破1000颗GitHub星！我们还发布了llmrouter-lib v0.2.0。此次更新包括针对不同服务的字典配置（如OpenAI、Anthropic等），以及在Geometry3K、MathVista和Charades-Ego数据集上实现的多模态路由（视频/图像+文本）。这是首个统一的开源LLM路由库，内置16+种路由模型、统一的CLI、Gradio UI和11个数据集。可通过 pip install llmrouter-lib 进行安装。更多更新即将发布！🚀

• 🚀 [2025-12]：LLMRouter 正式发布——以更智能的思维🧠、更具成本意识的方式💸，利用16+种路由模型🧭、统一的 llmrouter CLI 🛠️，以及用于自定义路由的插件工作流 🧩，实现高效的大型语言模型路由。

🔗 链接

• 支持的路由模型
• 安装指南
• 使用自有数据集
• 训练路由模型
• 通过路由模型进行推理
• 与路由模型的交互式聊天界面
• ComfyUI界面
• 创建自定义路由模型
• 添加自定义任务
• OpenClaw路由器（OpenClaw集成）
• 致谢
• 引用

🧭 支持的路由模型

单轮路由模型

路由模型	训练	推理	描述	教程
knnrouter	✅	✅	基于K近邻的路由	📖
svmrouter	✅	✅	基于支持向量机的路由	📖
mlprouter	✅	✅	基于多层感知器的路由	📖
mfrouter	✅	✅	基于矩阵分解的路由	📖
elorouter	✅	✅	基于Elo评分的路由	📖
routerdc	✅	✅	基于双对比学习的路由	📖
automix	✅	✅	自动模型混合	📖
hybrid_llm	✅	✅	混合LLM路由策略	📖
graphrouter	✅	✅	基于图的路由	📖
causallm_router	✅	✅	因果语言模型路由	📖
smallest_llm	N/A	✅	始终路由到最小模型	📖
largest_llm	N/A	✅	始终路由到最大模型	📖

多轮路由模型

路由模型	训练	推理	描述	教程
router_r1	LINK	✅	预训练的Router-R1模型，适用于多轮对话	📖

个性化路由

路由器	训练	推理	描述	教程
gmtrouter	✅	✅	基于图的个性化路由，支持用户偏好学习	📖
personalizedrouter	✅	✅	基于 GNN 的个性化路由，结合用户特征	📖

智能体路由

路由器	训练	推理	描述	教程
knnmultiroundrouter	✅	✅	基于 KNN 的智能体路由，适用于复杂任务	📖
llmmultiroundrouter	N/A	✅	基于 LLM 的智能体路由，适用于复杂任务	📖

🚀 开始使用

安装

从源码安装

克隆仓库并使用虚拟环境（例如 anaconda3）以可编辑模式安装：

# 克隆仓库
git clone https://github.com/ulab-uiuc/LLMRouter.git
cd LLMRouter

# 创建并激活虚拟环境
conda create -n llmrouter python=3.10
conda activate llmrouter

# 安装基础包
pip install -e .

# 可选：安装 RouterR1 支持（需要 GPU）
# RouterR1 已在 vllm==0.6.3 (torch==2.4.0) 上测试过；额外固定这些版本。
pip install -e ".[router-r1]"

# 可选：安装所有可选依赖
pip install -e ".[all]"

从 PyPI 安装

pip install llmrouter-lib

🔑 设置 API 密钥

LLMRouter 需要 API 密钥来进行推理、聊天和数据生成等 LLM API 调用。请使用以下格式之一设置 API_KEYS 环境变量：

💡 免费 NVIDIA API 密钥：LLMRouter 目前使用的 NVIDIA 端点提供免费的 API 密钥。要开始使用，请访问 https://build.nvidia.com/ 创建一个账户，然后即可免费生成您的 API 密钥。

服务特定字典格式（推荐用于多个提供商）

当您拥有来自不同服务提供商（如 NVIDIA、OpenAI、Anthropic）的模型，并希望为每个提供商使用不同的 API 密钥时，可以使用此格式：

export API_KEYS='{"NVIDIA": "nvidia-key-1,nvidia-key-2", "OpenAI": ["openai-key-1", "openai-key-2"], "Anthropic": "anthropic-key-1"}'

字典格式详情：

• 键：服务提供商名称（必须与 LLM 候选者 JSON 中的 service 字段匹配）
• 值：可以是：
  • 逗号分隔的字符串：“key1,key2,key3”
  • JSON 数组：“[“key1”, “key2”, “key3”]”
  • 单个字符串：“key1”
• 服务匹配：系统会自动匹配 LLM 候选者 JSON 中的 service 字段，以选择相应的 API 密钥
• 轮询机制：每个服务都会维护自己的轮询计数器，用于负载均衡
• 错误处理：如果字典中未找到某项服务，系统将抛出明确的错误信息，并列出可用的服务。

带有 service 字段的 LLM 候选者 JSON 示例：

{
  "qwen2.5-7b-instruct": {
    "service": "NVIDIA",
    "model": "qwen/qwen2.5-7b-instruct",
    "api_endpoint": "https://integrate.api.nvidia.com/v1"
  },
  "gpt-4": {
    "service": "OpenAI",
    "model": "gpt-4",
    "api_endpoint": "https://api.openai.com/v1"
  }
}

旧版格式（适用于单个提供商或向后兼容）

JSON 数组格式（适用于同一提供商的多个密钥）：

export API_KEYS='["your-key-1", "your-key-2", "your-key-3"]'

逗号分隔格式（多个密钥的另一种方式）：

export API_KEYS='key1,key2,key3'

单个密钥（仅有一个 API 密钥时）：

export API_KEYS='your-api-key'

注意事项：

• API 密钥用于 推理、聊天界面 和 数据生成（管道中的第 3 步）
• 多个密钥可以实现 API 调用的自动负载均衡
• 使用 字典格式 时，请确保 LLM 候选者 JSON 中的 service 字段与 API_KEYS 字典中的密钥相匹配
• 必须在运行推理、聊天或数据生成命令之前设置该环境变量
• 为了持久化设置，可将 export 命令添加到您的 shell 配置文件中（例如 ~/.bashrc 或 ~/.zshrc）。

🌐 配置 API 端点

API 端点可以在两个层级指定（按优先级顺序解析）：

1. 每模型级别（最高优先级）：LLM 候选者 JSON 中的 api_endpoint 字段（default_llm.json）
2. 路由器级别（备用）：路由器 YAML 配置中的 api_endpoint 字段
3. 错误：如果两者均未指定，则会抛出描述性错误。

LLM 候选者 JSON（每模型端点）：

{
  "qwen2.5-7b-instruct": {
    "model": "qwen/qwen2.5-7b-instruct",
    "api_endpoint": "https://integrate.api.nvidia.com/v1",
    ...
  },
  "custom-model": {
    "model": "custom/model-name",
    "api_endpoint": "https://api.customprovider.com/v1",
    ...
  }
}

路由器 YAML（默认端点）：

api_endpoint: 'https://integrate.api.nvidia.com/v1'  # 所有模型的备用端点

优点：不同模型可以使用不同的提供商；易于迁移；与路由器配置向后兼容。

有关详细信息，请参阅 数据生成管道文档。

🖥️ 使用本地 LLM 模型

LLMRouter 支持提供 OpenAI 兼容 API 的本地 LLM 推理服务器（例如 Ollama、vLLM、SGLang）。对于本地提供商，您可以将 API 密钥值设为空字符串 ""——系统会自动检测 localhost 端点并相应地处理身份验证。

Ollama 示例：

export API_KEYS='{"Ollama": ""}'

{
  "gemma3": {
    "size": "3B",
    "feature": "Gemma 3B 模型通过 Ollama 在本地托管",
    "input_price": 0.0,
    "output_price": 0.0,
    "model": "gemma3",
    "service": "Ollama",
    "api_endpoint": "http://localhost:11434/v1"
  }
}

重要提示：请使用 /v1 端点（OpenAI 兼容），而不是原生 API 端点。空字符串会被自动检测为 localhost 端点（localhost 或 127.0.0.1）。

🧪 测试模型可用性

您可以使用以下 curl 命令测试不同候选模型的可用性。这对于验证您的 API 密钥是否正常工作以及特定模型是否可访问非常有用：

注意：如果您使用的是 API_KEYS 的字典格式，请先提取 NVIDIA 密钥（例如，使用 echo $API_KEYS | python3 -c "import sys, json; print(json.load(sys.stdin)['NVIDIA'].split(',')[0])"），或者临时设置一个包含 NVIDIA API 密钥的变量。

# export API_KEYS=...

# 示例 API 端点 - 根据您的配置调整
# 此示例使用 NVIDIA 的端点，但您应使用 LLM 候选者 JSON 或路由器配置中指定的端点
API_ENDPOINT="https://integrate.api.nvidia.com/v1/chat/completions"

# 示例模型列表 - 根据您的 LLM 候选者配置调整

# 这些是示例模型；请替换为您 LLM 候选 JSON 文件中的实际模型名称/ID
MODELS=(
  "qwen/qwen2.5-7b-instruct"
  "meta/llama-3.1-8b-instruct"
  "mistralai/mistral-7b-instruct-v0.3"
  "nvidia/llama-3.3-nemotron-super-49b-v1"
  "mistralai/mixtral-8x7b-instruct-v0.1"
  "mistralai/mixtral-8x22b-instruct-v0.1"
)

SYSTEM_PROMPT="你好。"
PROMPT="你好。"

for MODEL in "${MODELS[@]}"; do
  echo "===== $MODEL ====="

  curl "$API_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEYS" \
    -d "{
      \"model\": \"$MODEL\",
      \"messages\": [
        {
          \"role\": \"system\",
          \"content\": \"$SYSTEM_PROMPT\"
        },
        {
          \"role\": \"user\",
          \"content\": \"$PROMPT\"
        }
      ],
      \"temperature\": 0.8,
      \"max_tokens\": 200
    }"

  echo
done

此脚本将测试列表中的每种模型并显示响应，帮助您验证哪些模型可用以及是否能与您的 API 密钥正常工作。

📊 准备训练数据

LLMRouter 包含一个完整的数据生成管道，可将原始基准测试数据集转换为带有嵌入的格式化路由数据。该管道支持 11 种多样化的基准测试数据集，包括自然问答、琐事问答、MMLU、GPQA、MBPP、HumanEval、GSM8K、常识问答、数学、OpenbookQA 和 ARC-Challenge。

💡 多模态集成：请查看我们的 多模态任务指南，了解如何将复杂的多模态任务（视频/图像 + 文本）纳入 LLMRouter。目前我们支持 3 个数据集中的 5 项多模态任务（Geometry3K、MathVista、Charades-Ego）。

管道概述

数据生成管道包含三个主要步骤：

1. 生成查询数据 - 从基准测试数据集中提取查询，并创建训练/测试分割的 JSONL 文件
2. 生成 LLM 嵌入 - 根据 LLM 候选者的元数据为其创建嵌入
3. API 调用与评估 - 调用 LLM API，评估响应，并生成统一的嵌入和路由数据

快速入门

首先使用示例配置文件：

# 第一步：生成查询数据
python llmrouter/data/data_generation.py --config llmrouter/data/sample_config.yaml

# 第二步：生成 LLM 嵌入
python llmrouter/data/generate_llm_embeddings.py --config llmrouter/data/sample_config.yaml

# 第三步：API 调用与评估（需要 API_KEYS - 参见上面的“设置 API 密钥”部分）
python llmrouter/data/api_calling_evaluation.py --config llmrouter/data/sample_config.yaml --workers 100

输出文件

管道会生成以下文件：

• 查询数据（JSONL）：query_data_train.jsonl 和 query_data_test.jsonl - 包含训练/测试分割的查询数据
• LLM 嵌入（JSON）：default_llm_embeddings.json - 包含嵌入的 LLM 元数据
• 查询嵌入（PyTorch）：query_embeddings_longformer.pt - 所有查询的统一嵌入
• 路由数据（JSONL）：default_routing_train_data.jsonl 和 default_routing_test_data.jsonl - 包含模型响应、性能评分和 token 使用情况的完整路由数据

路由数据条目示例：

{
  "task_name": "gsm8k",
  "query": "珍妮特有 4 个苹果。她给了鲍勃 2 个。她还剩多少个？",
  "ground_truth": "2",
  "metric": "GSM8K",
  "model_name": "llama3-chatqa-1.5-8b",
  "response": "珍妮特有 4 个苹果，给了鲍勃 2 个，所以她还剩下 4 - 2 = 2 个苹果。",
  "performance": 1.0,
  "embedding_id": 42,
  "token_num": 453
}

配置

所有路径和参数都通过 YAML 配置文件进行控制。示例配置文件 (llmrouter/data/sample_config.yaml) 引用了示例数据目录，您可以直接使用，也可以根据自己的设置进行自定义。

注意：第 3 步需要 API 密钥才能调用 LLM 服务。有关配置详情，请参阅上面的 设置 API 密钥 部分。

如需完整的文档，包括详细的文件格式、嵌入映射系统、配置选项和故障排除信息，请参阅 llmrouter/data/README.md。

训练路由器

在开始训练之前，请确保已使用 数据生成管道 准备好数据，或使用 data/example_data/ 中的示例数据。

使用您的配置训练各种路由器模型：

# 训练 KNN 路由器
llmrouter train --router knnrouter --config configs/model_config_train/knnrouter.yaml

# 使用 GPU 训练 MLP 路由器
CUDA_VISIBLE_DEVICES=2 llmrouter train --router mlprouter --config configs/model_config_train/mlprouter.yaml --device cuda

# 静默训练 MF 路由器
CUDA_VISIBLE_DEVICES=1 llmrouter train --router mfrouter --config configs/model_config_train/mfrouter.yaml --device cuda --quiet

运行推理

使用训练好的路由器进行推理（需要 API 密钥 - 参见 设置 API 密钥 部分）：

# 单个查询推理
llmrouter infer --router knnrouter --config config.yaml --query "什么是机器学习？"

# 从文件批量推理
llmrouter infer --router knnrouter --config config.yaml --input queries.txt --output results.json

# 仅路由（无需调用 LLM API - 不需要 API 密钥）
llmrouter infer --router knnrouter --config config.yaml --query "你好" --route-only

# 自定义生成参数
llmrouter infer --router knnrouter --config config.yaml --query "解释人工智能" --temp 0.7 --max-tokens 2048 --verbose

支持的输入文件格式：.txt（每行一个查询）、.json（字符串列表或包含 "query" 字段的对象）、.jsonl（每行一个 JSON 对象）。

交互式聊天界面

📱 快速预览： LLMRouter 聊天界面的动画概览，展示实时路由和模型选择。

启动聊天界面（需要 API 密钥 - 参见 设置 API 密钥 部分）：

# 基本聊天界面
llmrouter chat --router knnrouter --config config.yaml

# 自定义主机和端口
llmrouter chat --router knnrouter --config config.yaml --host 0.0.0.0 --port 7860

# 启用公开分享链接
llmrouter chat --router knnrouter --config config.yaml --share

# 指定查询模式
llmrouter chat --router knnrouter --config config.yaml --mode full_context --top_k 5

查询模式：

• current_only：仅根据当前查询进行路由（默认）
• full_context：将所有聊天历史与当前查询结合
• retrieval：检索 top-k 相似的历史查询以提供上下文

直接执行脚本

您也可以直接运行 CLI 脚本：

训练

python -m llmrouter.cli.router_train --router knnrouter --config config.yaml

推理

python -m llmrouter.cli.router_inference --router knnrouter --config config.yaml --query "Hello"

对话

python -m llmrouter.cli.router_chat --router knnrouter --config config.yaml

## 🎨 ComfyUI 界面

LLMRouter 通过 [ComfyUI](https://github.com/Comfy-Org/ComfyUI) 提供了一个强大的 **可视化界面**，彻底改变了您与路由流程交互的方式。您不再需要编辑 YAML 文件或运行终端脚本，而是可以通过拖放节点来构建工作流。

<div align="center">
  <img src="https://oss.gittoolsai.com/images/ulab-uiuc_LLMRouter_readme_fb5775136849.png" alt="LLMRouter ComfyUI 界面" width="100%">
</div>

### 主要亮点

- **可视化配置**：告别复杂的 YAML 文件和终端命令。您可以在画布上直接调整参数（如样本大小、模型候选）并选择数据集。
- **端到端自动化**：无缝连接各个节点，构建完整的流程：数据生成 $\to$ 路由器训练 $\to$ 评估。
- **实时监控**：通过即时的视觉反馈，跟踪查询生成、嵌入提取和模型训练的状态。
- **模块化设计**：通过拖放和连接数据集、LLM 和路由器等节点，自定义构建您的工作流。

### 安装与设置

先决条件：您必须已安装 [ComfyUI](https://github.com/Comfy-Org/ComfyUI)。

要安装 LLMRouter 自定义节点，您需要创建两个符号链接（软链接）。

#### 1. 链接自定义节点
这使得 ComfyUI 能够在“Nodes”类别中加载 LLMRouter 的 Python 后端逻辑。

```bash
ln -s /path/to/LLMRouter/ComfyUI /path/to/ComfyUI/custom_nodes/LLMRouter

2. 链接工作流示例（可选）

这使您能够在 ComfyUI 的“Workflows”类别中查看预配置的工作流。

ln -s /path/to/LLMRouter/ComfyUI/workflows/llm_router_example.json /path/to/ComfyUI/user/default/workflows/llm_router_example.json

3. 运行应用程序

要启动带有 LLMRouter 节点的 ComfyUI 服务器：

python /path/to/ComfyUI/main.py

4. 远程访问与端口转发

如果您在远程服务器上运行 ComfyUI（例如计算集群），并希望在本地访问界面，可以使用 SSH 隧道。隧道建立后，您可以通过 http://127.0.0.1:8188 访问界面。

使用 ComfyUI 界面

查找节点

要使用这些节点：

1. 打开 ComfyUI 的网页界面。
2. 使用侧边栏中的 Node Library 或右键单击画布。
3. 导航到 LLMRouter 类别。
4. 您会发现按功能组织的节点：
   • 数据：Select Datasets、Select LLMs、Generate Data。
   • 单轮：KNN Router、SVM Router、MLP Router 等。
   • 多轮/代理式：专为复杂任务设计的路由器。

加载示例

要使用即用型示例：

1. 点击 Workflows 选项卡。
2. 选择 llm_router_example.json。
3. 这将加载一个完整的流程。

🔧 创建您自己的路由器

LLMRouter 支持 插件系统，允许您在不修改核心代码库的情况下添加自定义路由器实现。这使得尝试新的路由策略或特定领域的路由器变得非常容易。

快速入门

1. 创建您的路由器目录：

mkdir -p custom_routers/my_router

2. 实现您的路由器 (custom_routers/my_router/router.py)：

from llmrouter.models.meta_router import MetaRouter
import torch.nn as nn

class MyRouter(MetaRouter):
    """您的自定义路由器实现。"""

    def __init__(self, yaml_path: str):
        # 使用模型初始化（对于简单路由器可以使用 nn.Identity()）
        model = nn.Identity()
        super().__init__(model=model, yaml_path=yaml_path)

        # 从配置中获取可用的 LLM 名称
        self.llm_names = list(self.llm_data.keys())

    def route_single(self, query_input: dict) -> dict:
        """将单个查询路由到最佳 LLM。"""
        query = query_input['query']

        # 在这里编写您的自定义路由逻辑
        # 示例：根据查询长度进行路由
        selected_llm = (self.llm_names[0] if len(query) < 50
                       else self.llm_names[-1])

        return {
            "query": query,
            "model_name": selected_llm,
            "predicted_llm": selected_llm,
        }

    def route_batch(self, batch: list) -> list:
        """路由多个查询。"""
        return [self.route_single(q) for q in batch]

3. 创建配置文件 (custom_routers/my_router/config.yaml)：

data_path:
  llm_data: 'data/example_data/llm_candidates/default_llm.json'

hparam:
  # 您的超参数在这里

# 可选：默认 API 端点（当模型未指定自己的端点时作为备用）
# 单个模型可以通过在 llm_data JSON 文件中指定 api_endpoint 来覆盖此设置
api_endpoint: 'https://integrate.api.nvidia.com/v1'

4. 使用您的自定义路由器（与内置路由器相同！）：

# 推理
llmrouter infer --router my_router \
  --config custom_routers/my_router/config.yaml \
  --query "什么是机器学习？"

# 列出所有路由器（包括自定义路由器）
llmrouter list-routers

插件发现

自定义路由器会自动从以下路径中被发现：

• ./custom_routers/（推荐——项目目录）
• ~/.llmrouter/plugins/（用户主目录）
• $LLMROUTER_PLUGINS 环境变量（以冒号分隔的路径）

示例路由器

LLMRouter 包含一些您可以学习的自定义示例路由器：

RandomRouter —— 一个简单的基线，随机选择 LLM

llmrouter infer --router randomrouter \
  --config custom_routers/randomrouter/config.yaml \
  --query "你好，世界"

ThresholdRouter —— 一个高级可训练路由器，具备难度估计功能

# 训练路由器
llmrouter train --router thresholdrouter \
  --config custom_routers/thresholdrouter/config.yaml

# 推理
llmrouter infer --router thresholdrouter \
  --config custom_routers/thresholdrouter/config.yaml \
  --query "解释量子计算"

文档

有关创建自定义路由器的详细指南：

• 📖 快速入门：custom_routers/README.md
• 📖 实现概览：CUSTOM_ROUTER_SUMMARY.md

常见路由模式

基于规则的路由：

def route_single(self, query_input):
    query = query_input['query'].lower()
    if 'code' in query:
        return {"model_name": "code-specialist"}
    elif len(query) < 50:
        return {"model_name": "small-fast-model"}
    else:
        return {"model_name": "large-capable-model"}

基于嵌入的路由：

from llmrouter.utils import get_longformer_embedding

def route_single(self, query_input):
    embedding = get_longformer_embedding(query_input['query'])
    # 使用嵌入相似度选择最佳模型
    selected = self._find_best_model(embedding)
    return {"model_name": selected}

成本优化的路由：

def route_single(self, query_input):
    difficulty = self._estimate_difficulty(query_input)
    # 选择能够处理该难度且最便宜的模型
    for model_name, info in sorted(self.llm_data.items(),
                                   key=lambda x: x[1]['cost']):
        if info['capability'] >= difficulty:
            return {"model_name": model_name}

📝 添加您自己的任务

LLMRouter 支持自定义任务定义，允许您添加具有自定义提示模板和评估指标的新任务类型。自定义任务会自动被发现并集成到数据生成和评估流程中。

快速入门

1. 创建任务格式化器（custom_tasks/my_tasks.py）：

from llmrouter.utils.prompting import register_prompt
from llmrouter.prompts import load_prompt_template

@register_prompt('my_task', default_metric='my_metric')
def format_my_task_prompt(sample_data):
    system_prompt = load_prompt_template("task_my_task")
    user_query = f"问题: {sample_data.get('query', '')}"
    return {"system": system_prompt, "user": user_query}

2. 创建提示模板（custom_tasks/task_prompts/task_my_task.yaml）：

template: |
  你是一位[任务描述]方面的专家。[指令]。

3. 注册自定义指标（可选）：

from llmrouter.evaluation import evaluation_metric

@evaluation_metric('my_metric')
def my_metric(prediction: str, ground_truth: str, **kwargs) -> float:
    return 1.0 如果 prediction 等于 ground_truth，否则为 0.0

4. 使用您的自定义任务：

import custom_tasks.my_tasks  # 导入会触发注册

from llmrouter.utils import generate_task_query
from llmrouter.utils.evaluation import calculate_task_performance

# 生成提示
prompt = generate_task_query('my_task', {'query': '...'})

# 评估（指标会自动从任务中推断）
score = calculate_task_performance(
    prediction="...",
    ground_truth="...",
    task_name="my_task"
)

文档

有关创建自定义任务的详细指南：

• 📖 完整指南：custom_tasks/README.md

🎥 实战：多视角视频任务

请按照 Charades-Ego 集成指南 中的分步教程，处理成对的第一人称视角视频，生成基于 VLM 的特征，并训练用于活动、物体和动词识别的路由器。

🔌 OpenClaw 路由器（OpenClaw 集成）

OpenClaw 路由器是一个与 OpenAI 兼容的 API 服务器，可将 LLMRouter 的智能路由功能引入生产环境。它可与 OpenClaw 无缝集成，使您能够通过 Slack、Discord 等消息平台部署 LLM 路由。

为什么选择 OpenClaw 路由器？

特性	优势
与 OpenAI 兼容的 API	可作为任何 OpenAI 客户端的即插即用替代品（/v1/chat/completions）
所有路由策略	可使用 LLMRouter 的 16 种以上策略（KNN、SVM、MLP、基于 LLM 的等）
多模态理解	处理图像、音频和视频——将其转换为文本以进行路由决策
路由记忆	持久保存查询到模型的历史记录；检索类似的历史路由以做出更好的决策
流式支持	完整的流式响应，可选带 [model_name] 前缀
多提供商支持	可路由至 Together AI、NVIDIA、OpenAI、Anthropic 或本地模型

架构

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐
│  Slack/Discord  │────▶│   OpenClaw Gateway   │────▶│   OpenClaw Router    │
│  (移动/网页)   │     │   (Socket 模式)      │     │   (端口 8000)       │
└─────────────────┘     └──────────────────────┘     └──────────┬──────────┘
                                                                 │
                        ┌────────────────────────────────────────┼────────────────────────────────────────┐
                        │                                        │                                        │
                        ▼                                        ▼                                        ▼
              ┌─────────────────┐                      ┌─────────────────┐                      ┌─────────────────┐
              │   快速模型    │                      │ 平衡模型  │                      │ 强大模型  │
              │   （如 8B）     │                      │   （如 70B）    │                      │  （如 405B）    │
              └─────────────────┘                      └─────────────────┘                      └─────────────────┘

快速入门

1. 配置 OpenClaw 路由器（openclaw_router/config.yaml）：

serve:
  host: "0.0.0.0"
  port: 8000
  show_model_prefix: true

router:
  strategy: llm  # 或：random、round_robin、rules、llmrouter
  provider: together
  base_url: https://api.together.xyz/v1
  model: "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo"

api_keys:
  together: ${TOGETHER_API_KEY}

llms:
  llama-3.1-8b:
    provider: together
    model: "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo"
    base_url: https://api.together.xyz/v1
    description: "快速响应"

  llama-3.3-70b:
    provider: together
    model: "meta-llama/Llama-3.3-70B-Instruct-Turbo"
    base_url: https://api.together.xyz/v1
    description: "复杂推理"

2. 启动服务器：

# 使用启动脚本（推荐——也会启动 OpenClaw 网关）
./scripts/start-openclaw.sh

# 或直接通过命令行
llmrouter serve --config openclaw_router/config.yaml

# 使用基于机器学习的路由器
llmrouter serve --config openclaw_router/config.yaml --router knnrouter

3. 测试 API：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "解释量子计算"}]
  }'

可选功能

路由记忆（检索增强路由）：

memory:
  enabled: true
  path: "${HOME}/.llmrouter/openclaw_memory.jsonl"
  top_k: 10
  retriever_model: "facebook/contriever-msmarco"

媒体理解（多模态支持）：

media:
  enabled: true
  vision_model: "Qwen/Qwen3-VL-8B-Instruct"
  audio_model: "openai/whisper-large-v3"

文档

有关包括 Slack/Discord 集成在内的完整设置说明：

• 📖 完整指南：openclaw_router/README.md

🗺️ 待办事项

• 改进个性化路由器：更强大的用户画像、冷启动策略以及在线反馈更新。
• 集成多模态路由器：支持图像/音频输入，并根据模态和任务类型将请求路由到合适的多模态模型。
• 添加持续/在线学习功能，以适应领域漂移（例如定期重新训练 + 反馈循环）。

🙏 致谢

LLMRouter 建立在社区优秀研究的基础上。我们衷心感谢以下工作，它们启发了我们的路由器实现：

• RouteLLM - 使用偏好数据学习 LLM 路由（ICLR 2025）
• RouterDC - 基于查询的双对比学习路由器（NeurIPS 2024）
• AutoMix - 自动混合语言模型（NeurIPS 2024）
• Hybrid LLM - 成本高效且质量导向的查询路由（ICLR 2024）
• GraphRouter - 基于图的 LLM 选择路由器（ICLR 2025）
• GMTRouter - 基于多轮用户交互的个性化 LLM 路由器
• PersonalizedRouter - 基于图的用户偏好建模的个性化 LLM 路由
• Router-R1 - 通过强化学习教授 LLM 多轮路由与聚合（NeurIPS 2025）
• FusionFactory - 利用多 LLM 日志数据融合 LLM 能力

我们热烈欢迎社区的贡献！一个强大的开源路由器框架需要大家的共同努力。如果您开发了新的路由方法，请考虑提交 PR 将其添加到 LLMRouter 中。让我们携手共建最全面的 LLM 路由库！

🤝 贡献

我们热烈欢迎来自社区的贡献。LLMRouter 是一个不断发展的可扩展研究框架，其影响力随着贡献者的创造力和专业知识而不断增强。

如果您开发了新的路由策略、学习目标、训练范式或评估协议，我们强烈鼓励您提交拉取请求将其集成到 LLMRouter 中。所有被接受的贡献都会被明确署名，并记录在文档中，供广大的研究人员和从业者使用。

为 LLMRouter 做贡献不仅仅是添加代码，更是一个提升您在 LLM 系统社区中作品的可见性、采用率和长期影响力的机会。我们共同的目标是打造最全面、最具扩展性的 LLM 路由开源库。

杰出的贡献可能会在文档、示例、基准测试或未来的版本中得到重点展示。

星标历史

📚 引用

如果您发现 LLMRouter 对您的研究或项目有所帮助，请按以下方式引用：

@misc{llmrouter2025,
  title        = {LLMRouter：一个用于 LLM 路由的开源库},
  author       = {Tao Feng 和 Haozhen Zhang 和 Zijie Lei 和 Haodong Yue 和 Chongshan Lin 和 Ge Liu 和 Jiaxuan You},
  year         = {2025},
  howpublished = {\url{https://github.com/ulab-uiuc/LLMRouter}},
  note         = {GitHub 仓库}
}

LLMRouter 快速上手指南

LLMRouter 是一个智能路由系统，旨在通过为每个查询动态选择最合适的模型来优化大语言模型（LLM）的推理成本与性能。它支持超过 16 种路由策略（如 KNN、SVM、Elo 评级、图神经网络等），并提供统一的命令行工具和可视化界面。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 Linux)
• Python 版本: Python 3.10 (必须)
• 依赖管理: 推荐使用 conda 或 venv 创建虚拟环境
• 硬件要求:
  • 基础路由模型训练/推理：CPU 即可
  • 若使用 Router-R1 或多模态功能：需要 NVIDIA GPU

2. 安装步骤

您可以选择从源码安装（推荐，功能最全）或通过 PyPI 安装。

方式一：从源码安装（推荐）

此方式支持所有可选功能（包括 Router-R1）。

# 1. 克隆仓库
git clone https://github.com/ulab-uiuc/LLMRouter.git
cd LLMRouter

# 2. 创建并激活虚拟环境 (以 conda 为例)
conda create -n llmrouter python=3.10
conda activate llmrouter

# 3. 安装基础包
pip install -e .

# [可选] 如果需要支持 Router-R1 (需 GPU)，执行以下命令
# pip install -e ".[router-r1]"

# [可选] 安装所有可选依赖
# pip install -e ".[all]"

方式二：通过 PyPI 安装

仅包含核心库功能，适合快速集成。

pip install llmrouter-lib

💡 国内加速提示：如果下载速度较慢，建议使用国内镜像源安装： pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

第一步：配置 API Keys

LLMRouter 需要访问 LLM API 进行推理和数据生成。您需要设置 API_KEYS 环境变量。

推荐格式（多服务商支持）： 如果您同时使用 NVIDIA、OpenAI 等不同服务商，请使用 JSON 字典格式：

export API_KEYS='{"NVIDIA": "your-nvidia-key", "OpenAI": "your-openai-key"}'

简单格式（单服务商）：

export API_KEYS='your-api-key'

免费资源提示：LLMRouter 默认支持 NVIDIA 端点，您可以前往 NVIDIA Build 免费注册获取 API Key。

第二步：准备模型配置文件

创建一个 JSON 文件（例如 my_models.json）定义候选模型列表。LLMRouter 将根据路由策略从中选择最佳模型。

{
  "small-model": {
    "service": "NVIDIA",
    "model": "meta/llama3-8b-instruct",
    "api_endpoint": "https://integrate.api.nvidia.com/v1"
  },
  "large-model": {
    "service": "OpenAI",
    "model": "gpt-4o",
    "api_endpoint": "https://api.openai.com/v1"
  }
}

第三步：运行路由推理

使用统一的 llmrouter CLI 工具进行推理。以下示例展示了如何使用预训练的 knnrouter 对单个查询进行路由：

llmrouter infer \
    --router knnrouter \
    --config_path path/to/router_config.yaml \
    --llm_candidates path/to/my_models.json \
    --query "How to optimize a neural network?"

参数说明：

• --router: 指定路由算法（如 knnrouter, svmrouter, elorouter 等）。
• --config_path: 路由器的配置文件路径（包含训练好的权重或超参数）。
• --llm_candidates: 上一步创建的候选模型 JSON 文件路径。
• --query: 用户输入的具体问题。

进阶：启动交互式聊天界面

LLMRouter 内置了基于 Gradio 的 Web UI，方便实时测试路由效果：

llmrouter chat \
    --router knnrouter \
    --config_path path/to/router_config.yaml \
    --llm_candidates path/to/my_models.json

运行后，终端会输出一个本地网址（通常是 http://127.0.0.1:7860），在浏览器打开即可体验智能路由对话。