Workbuddy 的模型路由该怎么配置？Base URL、API Key、模型 ID 映射和回退顺序要按什么步骤填？

Workbuddy 的模型路由配置，本质是把「客户端 → 接入地址 → 模型标识」这三层拆开分别填：Base URL 指向 OpenAI 兼容的 /v1 入口，API Key 决定鉴权与额度归属，模型映射表把界面里显示的名字翻译成上游真实模型 ID；三者任一错位，现象都不是「模型变笨」，而是 401、404 或 429 这类明确的协议错误。这套步骤适用于允许自定义 OpenAI 兼容端点的版本；如果客户端把接入地址写死为官方端点，就只能改模型下拉框，改不了路由本身。 先确定路由目标，再动手填表。单模型直连只需要一组 Base URL、Key 和模型 ID；多模型分工则要先写清哪类任务走哪个模型，比如长上下文走大窗口模型、批量简单任务走便宜的快速模型；带故障降级才需要额外配置备选模型和触发条件。目标没定就配路由，最常见的后果是备选模型继承了主模型不支持的参数，请求被上游以 400 拒绝。 Base URL 要填到版本入口，不要填成完整的对话接口。多数客户端要求填写以 /v1 结尾的地址，由程序自己拼接 /chat/completions；如果把整条接口路径填进去，最终请求会变成 /v1/chat/completions/chat/completions，返回 404。同一套客户端里，官方直连与经 API 中转聚合的地址通常是两个不同的 Base URL，切换时 Key 也必须一起换，混用会直接 401。 API Key 必须与接入地址来自同一个后台。用甲服务的 Key 打乙服务的地址，鉴权环节就被拒，后面所有路由规则都不会被执行；这类错误在日志里表现为鉴权失败而非路由失败，很容易被误判成配置没生效。生产环境建议按环境拆 Key，开发、灰度、正式各一套，任何一套泄露时只吊销那一套，不至于让整条链路停摆。 模型 ID 映射是路由配置里最容易被跳过的一步。Workbuddy 界面里给出的模型名往往是可读别名，而 OpenAI 兼容接口要求的是上游真实标识，大小写、厂商前缀、版本后缀任一不符都会返回 model not found。稳妥做法是先查询接入方提供的可用模型清单，把别名与真实 ID 一一对照写进映射表，再让界面选项只引用映射表中的键，避免有人手填一个不存在的名字。 路由规则要写清「什么条件下切换」，而不是只写「有备选」。可执行的规则通常是：主模型返回 429 或 5xx 时切备选，请求超时超过设定阈值时切备选，返回 400 参数错误时不切换而是直接报错——因为参数错误换模型同样错。回退链不宜超过两级，每级都要单独设超时；无限重试只会把一次失败放大成一批失败，并在按量计费下重复产生费用。 超时、重试与并发要按链路特征分开设置。连接超时反映网络可达性，通常几十秒内就能判定；读取超时取决于生成长度，长上下文或长输出任务要放宽，否则会把正常的长回答误判为超时并触发切换。并发上限要看两端：客户端自身的并发限制和接入侧的限流策略叠加，客户端放开而接入侧收紧，结果仍是大面积 429，此时应降并发而不是加机器。 按量计费下，路由配置直接决定成本结构。同一个请求在主模型失败后重试到备选模型，两次调用都可能计费，因此重试次数应当收紧；把批量任务误路由到高价模型，单次差异看不出，量上来之后账单会明显偏离预算。可用的观测手段是按模型维度记录请求数、失败码分布和 token 用量，让每条路由规则都有对应的成本归属，而不是月底对账时才发现某条备选链从未被真正启用。 验证要按「先链路、后客户端」的顺序做。先用一条最小对话请求直接打 Base URL，确认返回 200 和正常的 JSON 结构；再在 Workbuddy 里发一条最短提示词，看客户端日志里的实际请求地址与模型 ID 是否与映射表一致；最后拿一个真实业务任务灰度，观察状态码分布是否出现集中性的 401 或 404。跳过前两步直接上业务，往往要花更久才能判断问题出在网络、鉴权还是模型标识。 常见错误码可以按层定位，不必逐个猜。401 是 Key 与地址不同源或 Key 已失效；403 多为该 Key 无权访问目标模型；404 集中在 Base URL 少了版本段或模型 ID 不存在；429 是限流或额度耗尽，需要看是客户端并发过高还是接入侧配额不足；400 通常是请求体参数不被该模型接受，例如最大输出长度超限或不支持的采样参数。把这张对照表写进团队文档，能省掉大量重复排查。 路由配置属于会随版本变化的设置，需要做变更管理。客户端升级后字段位置、默认超时、可用参数集都可能调整，原先能跑通的映射表可能因为新增校验而失效；建议把 Base URL、模型映射和回退规则作为配置项纳入版本记录，每次升级后用最小请求回归一次。另有一条边界值得提前确认：如果业务对数据留存或出境有要求，选哪条路由不只取决于延迟和价格，还要看接入侧是否记录请求内容、日志保留多久。