LLMRouter / notes

实践笔记 · AGENT INTEGRATION

从省钱到懂你:为日常 AI 助手定制模型路由

用 LLMRouter 连接 WorkBuddy 与 Codex,选择策略,训练自己的路由

把开源模型路由接入熟悉的办公与编程助手:从第一条请求,到完整的工具调用。

Zijie Lei · Zhongjie Dai · Tao Feng · Kunlun Zhu · Fangxu Yu · Haozhen Zhang · Ge Liu · Jiaxuan You

·约 24 分钟阅读·论文 PDF ↗·GitHub ↗

从日常工作出发

同一个助手,一会儿帮你改写邮件,一会儿解释一段代码,接着又要定位一个跨文件的 bug。我们通常在开始工作时选好模型,然后把这些不同的任务都交给它。另一种做法是手动切换模型,但这会把“该用哪个模型”的判断反复推回给用户。

这正是把 LLMRouter 接入日常助手的出发点:让助手继续负责对话、文件和工具,把后端模型的选择放到一个独立的路由层。办公时仍然打开 WorkBuddy,编程时仍然使用 Codex;变化发生在助手发出模型请求之后。

本文围绕这两个接入案例展开。我们先看这层连接如何工作,再走过一次办公请求和一次编程请求,最后讨论怎样确认接入成功,以及怎样判断它是否真的改善了工作体验。

接入的目标,是让模型路由进入已有的工作流程。能连通只是第一步;选对模型、完成任务,才是后续需要验证的事情。

不只选模型,还能为自己的工作定制路由

你可能希望邮件改写更快,代码调试更可靠,也可能愿意为重要任务多花一点预算。另一个人对速度、表达风格和成本的取舍未必相同。LLMRouter 的价值,是让这些取舍有机会进入模型选择过程:先选择适合的路由方法,再用自己的任务数据和偏好信号逐步调整。

你既可以选择现成策略,也可以训练自己的 router。这里训练的是“为请求选择哪个模型”的决策器,通常不需要重新训练所有后端大模型。下面这张表把不同程度的定制放在一起:

你希望助手怎样工作可选择的方法你提供什么它怎样更贴合你
先按自己的分工选模型Rules关键词、候选模型、默认规则把明确的任务分工写成规则;由你更新,不会自动学习。
根据任务描述灵活选择LLM routing决策模型、候选能力描述;按需修改路由提示由 LLM 判断请求适合哪个候选;标准配置不是完整的用户偏好系统。
让模型选择更适合自己的任务分布KNN、SVM、MLP代表性任务、候选模型的评测结果、匹配的 embeddings 与训练产物从你的任务样本学习模型选择;这是面向任务的定制,不等于按用户个性化。
让不同用户获得不同选择PersonalizedRouter带用户信息的路由评测数据、候选元数据、训练好的 GNN;推理时的 user_id将用户身份纳入选择。当前助手适配器未传入 user_id,需补齐输入映射。
研究用户与会话偏好GMTRouter符合其格式的用户 / 会话 / query / LLM / response 数据、训练配置与 checkpoint提供用户偏好学习方向;完整会话信息如何接入此服务仍需专门适配与验证。
参考相似任务的历史选择LLM routing + 可选 memory启用 memory,积累 query → model 记录;按用户检索还需传入用户标识把历史选择作为提示参考;这些记录本身不是满意度反馈,也不会自动更新学习型 router 的权重。

“越来越懂你”,需要一个反馈过程

可以从你经常做的任务开始,记录最终是否完成、耗时、费用,以及你更喜欢哪个模型的结果。将这些信号整理成所选算法需要的监督数据;对需要训练的方法,定期训练并在留出的任务上与旧策略比较。确认效果后再更新线上产物。

真实任务 → 结果与偏好反馈 → 整理训练数据 → 训练 / 更新策略 → 留出任务评估 → 部署新版本

这是让路由逐步贴合个人或团队的可行工作方式,不是当前接入自动具备的在线学习功能。如果只是使用原来的模型和不变的规则,使用次数增加并不会自动让策略更懂你。成本节省与体验改善也需要实际评测;反馈量少、候选变化或任务分布改变时,都应重新检查效果。

接下来,我们先把模型请求接到同一层路由,再展示可以直接选择的策略和 KNN 的具体准备过程。PersonalizedRouter、GMTRouter 代表可继续扩展的个性化方向,不作为本文已完成的助手接入演示。

实现参考:PersonalizedRouter · personalized training config · GMTRouter config · routing memory & adapter.

把路由层放到助手背后

可以把一轮交互分成三个角色。助手接收你的任务,组织上下文,并执行获准的工具操作;LLMRouter根据配置的策略选择后端模型;模型生成回答或工具调用,结果再沿原路径返回助手。

图 1 · 请求向右发送,模型结果返回助手。工具由助手执行,随后可能产生新的模型请求。

这里有一个容易混淆的地方:使用同一个路由层,不等于使用同一种 API。WorkBuddy 接入走 Chat Completions,Codex 接入走 Responses。只提供前一种接口的服务,不能直接完成后一种接入。

接入点WorkBuddyCodex
客户端配置自定义模型自定义 provider
协议Chat CompletionsResponses
关键验证请求命中预期规则文本与工具调用都能完成

还有两类凭据需要区分:助手访问路由服务时可能需要的 token,以及路由服务访问上游模型时需要的 API key。上游密钥保留在路由端;本地演示里的占位 key,只适用于没有开启入口鉴权的路由服务。

不止规则:准备并切换路由策略

接入助手和选择路由算法,是两件可以分开配置的事。WorkBuddy / Codex 连接的是服务端 API;在地址、协议和入口模型保持兼容的前提下,切换路由策略通常只需修改服务端配置并重启,助手无需重新接入。后面的 rules 示例是便于观察的起点,不是接入能力的上限。

先选策略,再准备它需要的东西

策略需要准备接入边界
rules关键词、默认规则、候选模型与上游凭据。无需训练;只匹配配置里的关键词。
random / round_robin候选模型;random 可配权重。无需训练,适合检查分发链路;不会判断任务能力需求。
llm负责做路由决策的 LLM、它的 endpoint / key,以及每个候选的 description。无需训练本地分类器,但每次决策可能增加模型调用和延迟。
llmrouter + KNN / SVM / MLP算法配置、训练数据和 embeddings、训练产物、候选名称映射、运行依赖。通过统一适配器调用;需验证实际模型选择。
MF、Elo、Graph、其他注册或自定义算法各算法文档要求的数据、参数、权重及可选依赖。可通过注册表或插件尝试加载;列在注册表里不等于已验证助手端兼容。
多轮、RouterR1、需要用户或多模态输入的方法方法专有的输入和执行流程。需单独适配,不应承诺替换一个名称即可完整运行。

当前适配器只向算法传入 {"query": 文本},并从结果的 model_name、predicted_llm 或 predicted_llm_name 中取一个模型名称。它不会自动转发用户画像、原始图片或完整多轮状态给学习型 router。部分多轮方法直接返回完整回答,CLI 为它们设置了独立执行路径;这与此处“选出一个后端,再由助手继续工作”的契约不同。

共同底座:一份服务配置、一组可调用的模型

在 Python 3.10 或更新版本的独立环境中,从仓库源码安装。下面的命令面向本次核对的仓库实现;算法的额外依赖按其文档补充。

Shell
git clone https://github.com/ulab-uiuc/LLMRouter.git
cd LLMRouter
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

准备一份自己的 assistant-router.yaml:保留 serve、api_keys 和 llms,只替换其中的 router 段。可以从仓库 openclaw_router/config.yaml 复制修改,但要把演示 provider、模型和密钥改成真实可用的配置。以下片段均不包含完整候选模型定义,不能单独作为服务配置启动。

每个 llms 项需要一个稳定的候选名称,以及真实 provider、model、base_url 等连接信息。候选模型还必须支持助手实际用到的工具调用和上下文长度。若要比较策略,至少配置两个可用候选;过滤后仅剩一个候选时,代码会直接选择它。

路径一:用 LLM 做路由决策

在服务 YAML 中合并以下字段,并在启动服务的终端设置 OPENAI_API_KEY。这里的 model 是“做选择的模型”,不是被选中的最终回答模型;后者仍来自 llms。为候选写清楚 description,路由提示会使用这些说明。也可按服务支持的配置更换决策模型 provider。

YAML · 合并到服务配置
router:
  strategy: llm
  provider: openai
  base_url: https://api.openai.com/v1
  model: "<routing-model-id>"

api_keys:
  openai: ${OPENAI_API_KEY}

用下面的服务命令启动后,先用几条不同任务检查日志。不要把已有的英文关键词测试结果直接当成 LLM 策略的预期结果:此时选择过程已变成一次模型判断。

路径二:准备一个 KNN router

KNN 是一个具体例子,能把学习型路由的准备过程讲完整。先复制 configs/model_config_train/knnrouter.yaml 和 configs/model_config_test/knnrouter.yaml 到自己的训练 / 推理配置,逐项确认路径。

  1. 准备候选和监督数据。候选元数据、query 数据、路由评估记录及 query embeddings 要来自同一个候选池和一致的数据流程。KNN 代码按每条 query 的最高 performance 选出训练标签,使用 embedding_id 找到对应向量;标签不是随意填写的“简单 / 困难”等级。
  2. 保持名称一致。训练标签中的 model_name、候选元数据的 key,以及服务 llms 的 key 应一致。例如训练标签是 qwen2.5-7b-instruct,服务端就应提供同名候选;不能直接换成 lightweight 并期待自动识别。候选的 model 字段才填写上游实际模型 ID。优先精确匹配,不依赖适配器的模糊匹配。
  3. 准备 embedding 模型。当前 KNN 推理调用 allenai/longformer-base-4096,首次使用可能下载模型。训练向量必须使用一致的编码与预处理;有需要可通过 LLMROUTER_EMBEDDING_DEVICE=cpu 指定设备。随仓库的数据仅用于演示,不代表适合你的办公或代码任务。
  4. 训练或加载已有产物。训练配置的 save_model_path 和推理配置的 load_model_path 要指向同一份产物。为避免不同组件的相对路径解析差异,自己的配置优先使用绝对路径。构造 router 时也会读取 data_path 下的数据,因此部署时不能只复制一个 pkl 文件。
Shell · 先训练,再只测路由
llmrouter train --router knnrouter \
  --config /absolute/path/to/knn-train.yaml

llmrouter infer --router knnrouter \
  --config /absolute/path/to/knn-inference.yaml \
  --query "Explain this Python function" --route-only

如果已有与候选池和特征一致的可信训练产物,可以跳过训练,直接做 route-only 验证。确认返回名称确实在服务的候选列表中,再把服务的 router 段替换为:

YAML · 合并到服务配置
router:
  strategy: llmrouter
  llmrouter_name: knnrouter
  llmrouter_config: "/absolute/path/to/knn-inference.yaml"
  llmrouter_model_path: "/absolute/path/to/knnrouter.pkl"

llmrouter_model_path 会覆盖算法配置中的模型加载路径;单独运行上面的 CLI 检查时,则使用推理 YAML 本身的 load_model_path。两处应指向同一份模型。

SVM / MLP 的准备顺序相同:使用各自的 train / test YAML、对应的训练命令和产物,再修改 llmrouter_name、llmrouter_config、llmrouter_model_path 三项。不要拿 KNN 的 pkl 直接给 MLP 使用。MF、Graph、个性化等方法的数据需求不同,应按各自文档准备,并先核对是否满足这个文本输入、模型名称输出的适配契约。

启动服务,再接回原来的助手

Shell · 从仓库根目录运行
python -m openclaw_router \
  --config /absolute/path/to/assistant-router.yaml \
  --host 127.0.0.1 --port 8000

显式指定 host / port,是因为这个入口会用命令行默认值覆盖 YAML 中的 host / port。服务地址保持不变时,WorkBuddy 的自定义模型设置和 Codex 的 provider 配置可以继续使用。请求的 model 应走路由入口;如果使用某个候选名称,可能直接固定后端。下面的无鉴权本地检查用 auto 明确请求路由:

Shell · 本地检查
curl -s http://127.0.0.1:8000/routers
curl -s http://127.0.0.1:8000/v1/models
curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"auto","messages":[{"role":"user","content":"Explain this Python function"}]}'

/routers 只是列出策略和当前配置,/v1/models 只是列出候选,都不能证明算法已正确运行。对学习型策略,要同时看到 Loaded LLMRouter: knnrouter 和实际请求的 Strategy=llmrouter(knnrouter) 日志,并检查前后是否出现异常或 fallback 提示。初始化成功也不代表训练文件在第一次推理时一定可读。

更换策略后,按后文验证两个客户端的文本响应与工具调用。算法、训练产物和客户端版本需要配套配置。

实现依据(固定版本):adapter & strategies · registry & loader · KNN config · KNN implementation · server entry point.

办公场景:让 WorkBuddy 发出第一条路由请求

先从一个容易观察的任务开始:把一句英文翻译成中文。我们希望看到的,不只是 WorkBuddy 返回译文,而是这条请求确实到达了 LLMRouter,并按策略选择了一个后端。为了让这个过程可解释,这里使用了按关键词匹配的规则策略。

先让选择过程可见

下面的策略把翻译和改写分给 lightweight,把代码任务分给 coding,把特定推理请求分给 reasoning。这三个名称是配置中的候选别名,不是模型能力的保证。规则从上到下匹配,第一条命中即生效,没有命中时使用默认项。

YAML · 策略片段
serve:
  host: "127.0.0.1"
  port: 8000
  show_model_prefix: false
  show_model_suffix: true

router:
  strategy: rules
  rules:
    - keywords: ["math", "prove that", "calculus", "probability"]
      model: reasoning
    - keywords: ["code", "debug", "python", "api", "deploy"]
      model: coding
    - keywords: ["translate this", "proofread", "rewrite this"]
      model: lightweight
    - default: coding

  fallback_models:
    - coding
    - lightweight

这段 YAML 不是完整的部署配置。每个候选仍需要填写真实模型 ID、上游地址和凭据。视频中的部署使用 OPENROUTER_API_KEY,并通过 ./deploy/start-local-router.sh 启动;只有迁移代码中确实包含该脚本时才使用它。修改策略后,需要按该演示的加载方式重启服务。

启动后,先检查服务,再连接客户端。服务提供以下检查端点;如果你的版本不同,以实际部署文档为准。

Shell
curl -s http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/v1/models

把自定义模型指向路由入口

在视频演示的 WorkBuddy 版本中,打开 Settings → Model → Custom。URL 填 http://127.0.0.1:8000/v1,Model Name 填 LLMRouter,关闭 Custom Protocol,由客户端追加 /chat/completions。如果有 Tool Calling 开关,则开启它;此处的纯文本演示不需要启用 Vision/Image。

API Key 应与路由入口的鉴权方式一致。仅当本地路由不要求鉴权时,才可使用非空占位值。模型名称也有实际含义:在当前服务实现中,填写候选别名可能直接固定到某个后端,因此这里使用路由入口名 LLMRouter。

跟着一次请求看结果

保存并选中该自定义模型,然后开启新对话,发送下面的请求。刻意保留英文关键词,是为了让它与示例规则准确对应。中文表达“帮我翻译”并不在这组关键词里,不能假设它也会命中。

Prompt
translate this into Chinese: The train leaves at nine.

在这组规则下,translate this 应命中 lightweight。去路由日志中检查命中的规则和实际模型 ID,再检查助手是否完成翻译。服务开启 show_model_suffix 后,会在最终文本末尾附上 [model: <upstream-model-id>],可以辅助确认结果。

然后试试 debug this python function and explain the fix. 和 prove that the square root of 2 is irrational.,分别检查 coding 与 reasoning 路径。这里验证的是路由行为,不是比较这几个模型的真实能力。

WorkBuddy · 接入演示:客户端配置与路由请求。 MP4 ↓

编程场景:把 Codex 接到同一层路由

到了编程场景,接入要求又多了一层。助手可能先读取文件,再调用模型,再运行工具,最后解释修改。只让模型返回一句话,并不能说明这个工作循环已经兼容。Codex 案例因此要同时检查 Responses 接口和工具调用往返。

开始前,确认路由服务支持 Codex 所需的 Responses 接口,并获取可用于当前 Codex 客户端的模型 profile。这个 profile 与上游候选别名是不同概念:前者要与客户端的工具能力兼容,后者用于后端选择。不要直接把示例别名当成可用的 Codex 模型。

配置自定义 provider

备份后编辑用户级 ~/.codex/config.toml,将以下配置合并到现有文件中,避免重复定义同一个 TOML 表。自定义 provider 配置应放在用户级文件;官方配置参考说明,项目级文件中的相关 provider 设置会被忽略。

TOML · 配置示例
model = "<Codex-supported-tool-capable-model-slug>"
model_provider = "llmrouter"

[model_providers.llmrouter]
name = "LLMRouter"
base_url = "http://127.0.0.1:8000/v1"
wire_api = "responses"
supports_websockets = false
requires_openai_auth = false

把占位 model 替换成与你的客户端和路由部署兼容的实际 profile。wire_api = "responses" 指定接口;这里关闭 WebSocket,并假设本地路由不要求入口鉴权。若入口需要 token,按部署要求添加 env_key 并设置对应环境变量。上游模型密钥仍留在路由端。

保存后完整重启 Codex,在客户端支持的 provider/model 选择入口确认配置生效,并新建本地对话。具体界面随版本变化,最终以请求是否到达路由服务为准。

先测文本,再测一个完整工具回合

第一条请求可以仍然是翻译或简短总结,用它确认基本连通性。随后在测试工作区放一个简单的示例文件,请 Codex 读取该文件并解释一个函数的作用。这个任务既需要模型参与,也需要助手完成一次真实的工具操作。

  1. 在日志中确认请求进入 Responses 路径,并记录选中的后端。
  2. 确认读取文件的工具调用被客户端执行,结果返回后模型能继续处理。
  3. 确认助手给出最终回答,没有停在工具调用中间。

如果迁移版本启用了模型后缀,最终文本应只标注当前回答的模型。不要要求每个工具协议消息都带后缀;额外文本可能破坏协议结构。重复的后缀则值得检查历史消息的归属标签清理逻辑。

翻译、总结、写 Two Sum 可以作为不同工作负载,但不能直接等同于 quick、moderate、strong 等后端分配。实际选择取决于这份 Codex 部署的策略,仍要通过日志确认。

Codex · 接入演示:客户端配置与路由请求。 MP4 ↓

接通之后,怎样判断是否有用

一次成功回答只能证明某条路径可用。要让路由进入日常工作,还需要分别回答两个问题:请求是否按预期经过路由,以及经过路由之后,任务完成得是否更好。

先排除接入问题

现象优先检查
无法连接服务是否运行,host、port 和 /v1 是否一致。
始终选择一个后端是否误用了候选别名;默认规则是否吞掉了请求;日志实际命中了哪条规则。
修改规则后没有变化演示服务是否已重新加载配置或重启。
401 / 403区分路由入口鉴权失败与上游 provider 鉴权失败。
文本可用,工具失败Responses 兼容性、模型 profile、工具定义与返回格式。

再比较工作结果

选一组你真实会做的任务:几封邮件改写、几次翻译、几个文件解释任务和几个调试任务。对同一组任务分别使用固定模型和路由方案,记录任务是否完成、总耗时、费用,以及需要人工纠正的次数。涉及工具的任务,要把整个工作回合计入,而不是只看一次模型响应。

规则路由适合起步,因为它容易解释和排查,但也会错过同义表达,或者被同时包含多个关键词的请求影响。它没有理解任务难度的天然保证。LLMRouter 提供的更广泛路由方法可以作为后续实验方向;是否值得替换规则策略,需要用自己的任务数据判断。

本文的演示没有提供对照实验,因此不声称接入后一定省钱、提速或提高质量。它展示的是一条可以检查的接入路径:先把请求送到正确的位置,再把路由决策和最终任务结果连起来。

让模型选择成为工作流程的一部分

WorkBuddy 和 Codex 的接入入口不同,但目标相同:让日常助手保留熟悉的交互方式,同时把后端模型选择变成可以配置、观察和迭代的独立环节。

一个务实的起点,是先接好一个助手、跑通一个真实任务,再扩展候选模型和路由策略。当你能够解释“这次为什么选它”以及“它有没有把任务做完”,LLMRouter 才真正从一个开源项目进入了日常工作。

资料与延伸阅读

  1. LLMRouter: Unified Infrastructure for Developing, Evaluating, and Deploying LLM Routers — arXiv:2608.06867 (PDF).
  2. LLMRouter — GitHub

    项目源码与路由方法。具体接入能力应以所用版本为准。

  3. Codex — Configuration reference

    自定义 provider、Responses 协议与配置作用域。

  4. LLMRouter — Project documentation

客户端版本和模型能力会影响兼容性;请按文中的步骤验证实际部署。