Workbuddy 的模型路由怎么配置?中转 Base URL、模型名和回退顺序分别填在哪一步
Workbuddy 的模型路由按四步配置:新增 OpenAI 兼容供应商并填 Base URL 与 API Key、登记真实模型 ID、设定默认模型与回退顺序、用一条最小请求验证连通。该流程只适用于走 OpenAI 协议的端点,私有协议或本地推理需先经中转转换。
Workbuddy 的模型路由配置分四步走:在模型供应商里新增一个 OpenAI 兼容端点并填入中转 Base URL 与 API Key,登记要用的模型 ID,在路由规则里指定默认模型和回退顺序,最后用一条最小请求验证连通性和计费归属。这套流程只适用于走 chat/completions 这类 OpenAI 协议的端点;如果上游是私有协议或需要本地推理,就得先经过一层协议转换,界面菜单名随版本略有差异,以当前设置页为准。
协议兼容性要在填表之前确认,否则地址填对了也会在第一次请求就返回 400。原因是 Workbuddy 按 OpenAI 的 messages 数组和 choices 结构解析响应,中转如果只暴露原生格式,字段对不上就直接失败。做法是先请求一次上游的模型列表接口,确认能列出模型 ID,再用一条带 system 和 user 消息的最小请求看返回结构是否为标准 choices。
Base URL 应该填到 /v1 这一层,而不是完整的 /v1/chat/completions。客户端会自己在后面拼接具体路径,填成完整接口地址就会出现双 /v1 或重复路径,表现为 404 而不是鉴权错误。常见写法是域名加 /v1,不带结尾斜杠;如果中转给了多个接入点,优先选与 Workbuddy 所在网络延迟最低的那个。
一个路由环境配一个独立 Key,比所有任务共用一个 Key 更容易定位超额和异常。开发、测试、生产分开建 Key,在中转侧给每个 Key 设额度上限,某个环境跑飞了只吊销那一个,不影响其他业务。Key 不要写进配置文件或代码仓库,用环境变量注入,轮换时先加新 Key 再删旧 Key,避免切换窗口内全部请求 401。
模型名必须写上游真实 ID,别名应该在路由层做映射,而不是把别名直接填进模型名字段。模型名会原样透传给上游,写错就是 model not found;带日期后缀的版本号尤其容易漏字。做法是从模型列表里复制粘贴,再在 Workbuddy 的显示名里改成团队看得懂的业务名,这样日志里记录的是真实 ID,界面里显示的是业务名。
按任务把模型分成默认、重推理、低成本三组,比只设一个全局默认模型更能控制成本。日常对话和代码补全走默认组,长文档理解和复杂推理走重推理组,批量摘要、打标签这类高并发低难度任务走低成本组。每组都要单独配一条回退,不要三组共用同一个备用模型,否则低成本组的流量暴涨时会把高端模型的额度吃光。
回退链控制在两级以内,且备用模型必须与主模型同协议、同参数结构。每多一级回退就多一次网络往返,用户侧感知到的延迟是累加的;参数不兼容时上游返回的是 400 而不是自动降级。触发条件建议只设限流、服务端 5xx 和超时三类,业务类错误不要触发回退,否则一个格式写错的提示词会在所有模型上各失败一次。
超时时间要略大于上游的 P99 延迟,重试次数不要超过两次,否则限流时会把排队放大成雪崩。Workbuddy 侧和中转侧最好只保留一层重试,两层都开等于重试次数相乘,一次抖动会变成几十个并发请求。只有幂等的补全类请求适合重试,涉及流式输出已经吐字的请求不要重试,否则前端会收到重复片段。
中转侧的 RPM、TPM 配额要和 Workbuddy 的并发设置匹配,两边都设了小值,实际吞吐会被最小的那一项卡住。做法是先按套餐给的配额算出单请求平均 token 量对应的可并发数,再把 Workbuddy 的并发压到略低于这个值;出现 429 时先看响应头里的剩余配额,调并发比反复加重试更有效。
路由配置完成后要按模型维度对账,因为同一份提示词路由到不同模型,输入输出单价和输出长度都不一样,只看总账单看不出钱花在哪。做法是在日志里记录实际命中的模型 ID 和输入输出 token 数,按天汇总到组,再和账单核对;如果某组的实际用量远高于预估,通常是回退被频繁触发,主模型在限流而非备用模型更便宜。
配置完成后遇到报错,按 401、404、429、400 的顺序排查比逐项猜要快。401 是 Key 无效或没带 Bearer 前缀,404 是路径拼错或模型 ID 不存在,429 是配额或并发超限,400 才是参数结构问题;把鉴权和路径先排除掉,剩下的大多能在请求体里找到原因。每次改完配置先发一条固定测试请求,确认返回正常再切流量。
需要私有化部署、专属微调权重或非 OpenAI 协议的多模态端点时,这套配置流程不适用,应改为直连自建网关或让中转先做一层格式适配。灰度上建议先在测试环境用少量流量跑一周,观察回退触发率和平均延迟,再逐步把生产流量切过去,切的过程中保留旧配置一周以便回滚。