实践笔记 · AGENT INTEGRATION
从省钱到懂你:为日常 AI 助手定制模型路由
用 LLMRouter 连接 WorkBuddy 与 Codex,选择策略,训练自己的路由
把开源模型路由接入熟悉的办公与编程助手:从第一条请求,到完整的工具调用。
从日常工作出发
同一个助手,一会儿帮你改写邮件,一会儿解释一段代码,接着又要定位一个跨文件的 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。只提供前一种接口的服务,不能直接完成后一种接入。
| 接入点 | WorkBuddy | Codex |
|---|---|---|
| 客户端配置 | 自定义模型 | 自定义 provider |
| 协议 | Chat Completions | Responses |
| 关键验证 | 请求命中预期规则 | 文本与工具调用都能完成 |
还有两类凭据需要区分:助手访问路由服务时可能需要的 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 或更新版本的独立环境中,从仓库源码安装。下面的命令面向本次核对的仓库实现;算法的额外依赖按其文档补充。
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。
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 到自己的训练 / 推理配置,逐项确认路径。
- 准备候选和监督数据。候选元数据、query 数据、路由评估记录及 query embeddings 要来自同一个候选池和一致的数据流程。KNN 代码按每条 query 的最高 performance 选出训练标签,使用 embedding_id 找到对应向量;标签不是随意填写的“简单 / 困难”等级。
- 保持名称一致。训练标签中的 model_name、候选元数据的 key,以及服务
llms的 key 应一致。例如训练标签是qwen2.5-7b-instruct,服务端就应提供同名候选;不能直接换成lightweight并期待自动识别。候选的 model 字段才填写上游实际模型 ID。优先精确匹配,不依赖适配器的模糊匹配。 - 准备 embedding 模型。当前 KNN 推理调用
allenai/longformer-base-4096,首次使用可能下载模型。训练向量必须使用一致的编码与预处理;有需要可通过LLMROUTER_EMBEDDING_DEVICE=cpu指定设备。随仓库的数据仅用于演示,不代表适合你的办公或代码任务。 - 训练或加载已有产物。训练配置的 save_model_path 和推理配置的 load_model_path 要指向同一份产物。为避免不同组件的相对路径解析差异,自己的配置优先使用绝对路径。构造 router 时也会读取 data_path 下的数据,因此部署时不能只复制一个 pkl 文件。
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 段替换为:
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、个性化等方法的数据需求不同,应按各自文档准备,并先核对是否满足这个文本输入、模型名称输出的适配契约。
启动服务,再接回原来的助手
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 明确请求路由:
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。这三个名称是配置中的候选别名,不是模型能力的保证。规则从上到下匹配,第一条命中即生效,没有命中时使用默认项。
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 启动;只有迁移代码中确实包含该脚本时才使用它。修改策略后,需要按该演示的加载方式重启服务。
启动后,先检查服务,再连接客户端。服务提供以下检查端点;如果你的版本不同,以实际部署文档为准。
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。
跟着一次请求看结果
保存并选中该自定义模型,然后开启新对话,发送下面的请求。刻意保留英文关键词,是为了让它与示例规则准确对应。中文表达“帮我翻译”并不在这组关键词里,不能假设它也会命中。
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 路径。这里验证的是路由行为,不是比较这几个模型的真实能力。
编程场景:把 Codex 接到同一层路由
到了编程场景,接入要求又多了一层。助手可能先读取文件,再调用模型,再运行工具,最后解释修改。只让模型返回一句话,并不能说明这个工作循环已经兼容。Codex 案例因此要同时检查 Responses 接口和工具调用往返。
开始前,确认路由服务支持 Codex 所需的 Responses 接口,并获取可用于当前 Codex 客户端的模型 profile。这个 profile 与上游候选别名是不同概念:前者要与客户端的工具能力兼容,后者用于后端选择。不要直接把示例别名当成可用的 Codex 模型。
配置自定义 provider
备份后编辑用户级 ~/.codex/config.toml,将以下配置合并到现有文件中,避免重复定义同一个 TOML 表。自定义 provider 配置应放在用户级文件;官方配置参考说明,项目级文件中的相关 provider 设置会被忽略。
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 读取该文件并解释一个函数的作用。这个任务既需要模型参与,也需要助手完成一次真实的工具操作。
- 在日志中确认请求进入 Responses 路径,并记录选中的后端。
- 确认读取文件的工具调用被客户端执行,结果返回后模型能继续处理。
- 确认助手给出最终回答,没有停在工具调用中间。
如果迁移版本启用了模型后缀,最终文本应只标注当前回答的模型。不要要求每个工具协议消息都带后缀;额外文本可能破坏协议结构。重复的后缀则值得检查历史消息的归属标签清理逻辑。
翻译、总结、写 Two Sum 可以作为不同工作负载,但不能直接等同于 quick、moderate、strong 等后端分配。实际选择取决于这份 Codex 部署的策略,仍要通过日志确认。
接通之后,怎样判断是否有用
一次成功回答只能证明某条路径可用。要让路由进入日常工作,还需要分别回答两个问题:请求是否按预期经过路由,以及经过路由之后,任务完成得是否更好。
先排除接入问题
| 现象 | 优先检查 |
|---|---|
| 无法连接 | 服务是否运行,host、port 和 /v1 是否一致。 |
| 始终选择一个后端 | 是否误用了候选别名;默认规则是否吞掉了请求;日志实际命中了哪条规则。 |
| 修改规则后没有变化 | 演示服务是否已重新加载配置或重启。 |
| 401 / 403 | 区分路由入口鉴权失败与上游 provider 鉴权失败。 |
| 文本可用,工具失败 | Responses 兼容性、模型 profile、工具定义与返回格式。 |
再比较工作结果
选一组你真实会做的任务:几封邮件改写、几次翻译、几个文件解释任务和几个调试任务。对同一组任务分别使用固定模型和路由方案,记录任务是否完成、总耗时、费用,以及需要人工纠正的次数。涉及工具的任务,要把整个工作回合计入,而不是只看一次模型响应。
规则路由适合起步,因为它容易解释和排查,但也会错过同义表达,或者被同时包含多个关键词的请求影响。它没有理解任务难度的天然保证。LLMRouter 提供的更广泛路由方法可以作为后续实验方向;是否值得替换规则策略,需要用自己的任务数据判断。
本文的演示没有提供对照实验,因此不声称接入后一定省钱、提速或提高质量。它展示的是一条可以检查的接入路径:先把请求送到正确的位置,再把路由决策和最终任务结果连起来。
让模型选择成为工作流程的一部分
WorkBuddy 和 Codex 的接入入口不同,但目标相同:让日常助手保留熟悉的交互方式,同时把后端模型选择变成可以配置、观察和迭代的独立环节。
一个务实的起点,是先接好一个助手、跑通一个真实任务,再扩展候选模型和路由策略。当你能够解释“这次为什么选它”以及“它有没有把任务做完”,LLMRouter 才真正从一个开源项目进入了日常工作。
资料与延伸阅读
- LLMRouter: Unified Infrastructure for Developing, Evaluating, and Deploying LLM Routers — arXiv:2608.06867 (PDF).
- LLMRouter — GitHub
项目源码与路由方法。具体接入能力应以所用版本为准。
- Codex — Configuration reference
自定义 provider、Responses 协议与配置作用域。
- LLMRouter — Project documentation
客户端版本和模型能力会影响兼容性;请按文中的步骤验证实际部署。