LLMRouter：UIUC开源的智能LLM路由框架深度解析声明：📝 作者：甜城瑞庄的核桃（ZMJ）原创学习笔记，欢迎分享，但请保留作者信息及原文链接哦～项目地址：https://github.com/ulab-uiuc/LLMRouter文档：https://ulab-uiuc.github.io/LLMRouter/License：MIT一、背景：为什么需要LLM路由？在大模型应用落地过程中，工程师面临一个核心矛盾：大模型（如 GPT-4o、Claude 3.5 Sonnet）能力强，但 API 成本高，响应延迟大小模型（如 Llama-3-8B、Qwen-7B）成本低、延迟小，但复杂任务性能欠佳一刀切地使用大模型浪费资源，一刀切使用小模型牺牲质量。LLM Router（LLM路由器）应运而生：根据输入查询的复杂度，动态决定将其分发给哪个模型处理，在成本、性能、延迟之间寻找最优平衡点。用户查询 → [路由器] → 判断复杂度 → 简单任务 → 小模型（低成本） → 复杂任务 → 大模型（高质量）LLMRouter 是 UIUC ulab 实验室开发的开源路由框架，集成了学术界主流的16+ 种路由算法，提供统一的训练、推理、评估和部署接口，是目前最全面的 LLM 路由研究与工程平台。二、核心设计理念：Route × Training 解耦架构在正式了解LLMRouter之前，有必要先理解其最核心的架构思想——Route与Training的明确解耦。研究团队在开源前对主流LLM Router研究进行了系统梳理，发现一个关键规律：绝大多数路由器都可以抽象拆解为两个相互独立的子模块。┌──────────────────────────────────────────────────────────┐ │ Route × Training 解耦架构 │ ├──────────────────────────┬───────────────────────────────┤ │ Route 模块 │ Training 模块 │ │ （Inference-Time） │ （Learning-Time） │ ├──────────────────────────┼───────────────────────────────┤ │ 推理阶段执行路由决策 │ 数据构建与监督学习目标 │ │ 读取Backbone输出 │ 偏好/排序损失函数 │ │ 决定调用哪个候选模型 │ 强化学习式优化 │ │ 管理多轮路由与聚合策略 │ 多轮credit assignment │ │ 分配计算预算/资源 │ 离线评测与在线反馈闭环 │ └──────────────────────────┴───────────────────────────────┘这种解耦带来三点核心价值：价值说明领域统一不同论文提出的Router对齐到统一抽象下，同一Route逻辑可搭配不同Training方案开发友好可聚焦创新：要么提出新路由决策机制（Route），要么提出新学习优化方法（Training）高扩展性模块边界清晰，新增路由器像"搭积木"：backbone + route规则 + training配方即可这正是LLMRouter能同时支持16+种路由算法、并保持统一CLI接口的根本原因。三、项目整体架构3.1 架构全景图┌─────────────────────────────────────────────────────────────┐ │ LLMRouter 系统架构 │ ├─────────────────────────────────────────────────────────────┤ │ 用户层 │ CLI (llmrouter) │ Gradio Chat UI │ REST API │ ├──────────┼────────────────────┼──────────────────┼──────────┤ │ 路由层 │ 单轮路由器 │ 多轮路由器 │ 个性化路由 │ │ │ KNN/SVM/MLP/MF │ Router-R1 │ GMT/GNN │ │ │ ELO/RouterDC/etc │ KNN-Multi │ │ ├──────────┼────────────────────┴──────────────────┴──────────┤ │ 数据层 │ 3步数据生成管道（Data Pipeline） │ │ │ Step1:查询提取 → Step2:LLM嵌入 → Step3:评估标注 │ ├──────────┼────────────────────────────────────────────────────┤ │ 模型层 │ LLM候选池（本地Ollama / 远程API / 开源模型） │ │ │ NVIDIA / OpenAI / Anthropic / Ollama / vLLM │ ├──────────┴────────────────────────────────────────────────────┤ │ 部署层 │ OpenClaw Router（OpenAI兼容API服务，生产就绪） │ └─────────────────────────────────────────────────────────────┘3.2 项目目录结构LLMRouter/ ├── llmrouter/ # 核心代码包 │ ├── cli/ # 命令行接口（train/infer/chat/serve） │ ├── data/ # 数据生成管道 │ │ ├── data_generation.py # Step1: 查询提取 │ │ ├── generate_llm_embeddings.py # Step2: LLM元数据嵌入 │ │ └── api_calling_evaluation.py # Step3: API调用+评估 │ ├── models/ # 路由器模型实现 │ │ └── meta_router.py # 路由器抽象基类 │ ├── evaluation/ # 评估指标模块 │ ├── utils/ # 工具函数（embedding、prompting等） │ └── prompts/ # 提示词模板 ├── configs/ # 路由器训练配置YAML │ └── model_config_train/ # 各路由器超参数配置 ├── custom_routers/ # 自定义路由器插件目录 ├── custom_tasks/ # 自定义任务定义 ├── data/ # 数据集和LLM候选列表 │ └── example_data/ │ └── llm_candidates/default_llm.json ├── ComfyUI/ # 可视化节点工作流（无代码操作） ├── openclaw_router/ # 生产环境部署集成（OpenAI兼容接口） ├── notebooks/ # Jupyter教程笔记本 └── scripts/ # 启动脚本四、核心技术：三步数据生成管道路由器的训练依赖高质量的标注数据。LLMRouter 设计了一个自动化的3步数据生成管道，从原始数据集到可用训练数据全流程自动化。Step 1：查询提取（data_generation.py）从标准基准数据集中提取查询，生成query_data_train.jsonl和query_data_test.jsonl。支持11个单模态基准数据集：数据集任务类型评估指标GSM8K数学推理精确匹配MATH高级数学精确匹配HumanEval代码生成pass@1MBPP代码生成pass@1MMLU多学科知识准确率GPQA科学推理准确率Natural QA开放问答F1/EMTrivia QA问答F1/EMCommonsenseQA常识推理准确率OpenbookQA开放书本问答准确率ARC-Challenge推理问答准确率支持多模态数据集（图像/视频+文本）：Geometry3K（几何图形推理）MathVista（视觉数学推理）Charades-Ego（视频动作理解）Step 2：LLM候选嵌入生成（generate_llm_embeddings.py）为候选LLM池中的每个模型生成元数据嵌入向量，捕获模型能力特征（模型规模、擅长任务、家族特征等），输出default_llm_embeddings.json。Llama-3-8B → [能力向量] ─┐ Qwen-72B → [能力向量] ─┤→ LLM候选嵌入矩阵 GPT-4o → [能力向量] ─┤ Claude-3.5 → [能力向量] ─┘关键技术：使用 Longformer 模型对 LLM 的描述文本进行编码，输出query_embeddings_longformer.pt（PyTorch张量格式）。Longformer 采用稀疏注意力机制（局部滑动窗口注意力 + 全局注意力），能够高效处理长文档，计算复杂度从 O(n²) 降至 O(n)，适合对 LLM 描述文档进行编码。Step 3：API调用与性能评估（api_calling_evaluation.py）对每条查询，并发调用候选LLM池中的所有模型，评估响应质量，生成路由训练数据。路由训练数据条目示例：{"task_name":"gsm8k","query":"Janet has 4 apples...","ground_truth":"2","metric":"GSM8K","model_name":"llama3-chatqa-1.5-8b","response":"...","performance":1.0,"embedding_id":42,"token_num":453}数据流示意图：原始数据集（GSM8K/MMLU/HumanEval...） ↓ Step1 query_data_train.jsonl + query_data_test.jsonl ↓ Step2 default_llm_embeddings.json（LLM能力向量） ↓ Step3（并发调用所有候选LLM） default_routing_train_data.jsonl default_routing_test_data.jsonl （每条记录：查询 + 对应模型 + 性能得分）补充：模型可用性测试脚本在开始数据生成前，可通过以下脚本批量测试所有候选模型的可用性：API_ENDPOINT="https://integrate.api.nvidia.com/v1/chat/completions"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-8x22b-instruct-v0.1")forMODELin"${MODELS[@]}";doecho"=====$MODEL====="curl"$API_ENDPOINT"\-H"Content-Type: application/json"\-H"Authorization: Bearer$API_KEYS"\-d"{\"model\":\"$MODEL\",\"messages