Workbuddy 接入模型聚合平台 API 后频繁 401 和流式断流,问题出在密钥、Base URL 还是模型 ID?

401 优先查鉴权头格式与密钥是否混填,流式断流先看 Base URL 是否多写了一层路径、客户端读超时是否过短;模型 ID 必须与聚合平台模型列表里的大小写、后缀完全一致。这套排查只适用于走 OpenAI 兼容 Chat Completions 的接入方式,要求私有签名或非标准协议的平台不适用。

Workbuddy 接入模型聚合平台 API 后出现 401 与流式断流,多数情况不是平台侧故障,而是鉴权头格式、Base URL 拼接层级、模型 ID 映射这三处配置,与客户端读超时、SSE 透传这两项运行参数不匹配造成的;该结论适用于走 OpenAI 兼容 Chat Completions 协议的接入方式,对要求私有签名或自定义协议的平台不适用。 Base URL 只填到域名或只填到 /v1 中的一级,多写一层就会稳定返回 404。原因是多数客户端会在 Base URL 之后自动追加 /chat/completions,如果地址里已经带了完整路径,实际请求就变成重复拼接。做法是先按平台文档给出的根地址填写,再用一条最小请求验证:把同一个地址和密钥拿到命令行里请求一次,能返回模型列表或一句简短回复,说明地址层级是对的,此时再去检查 Workbuddy 里的表单。 鉴权失败要分清是密钥本身无效,还是密钥放错了位置。聚合平台的 Key 通过 Authorization: Bearer 头传递,不要同时塞进查询参数、自定义 header 或表单字段,否则网关可能取到空值并返回 401。Workbuddy 一类工具通常同时存在“供应商密钥”和“平台密钥”两个输入框,把上游厂商的 Key 填到聚合平台通道里,表现出来的同样是 401,但换 Key 并不能解决,需要改成平台签发的密钥。 模型 ID 必须与聚合平台模型列表里的写法逐字符一致,大小写、版本后缀、厂商前缀都算在内。聚合平台对外暴露的是映射后的模型名,不是上游厂商官网文档里的原始名称,直接照抄官方模型名通常会得到 400 或“model not found”。做法是先在平台侧拉一次模型清单,把要用到的两三个模型名原样复制进配置,再为每个模型单独发一条测试请求,确认返回里 model 字段与请求一致。 流式输出中途停止,优先怀疑读超时和网关缓冲,而不是模型能力问题。SSE 连接需要长连接保持,若客户端读超时设得偏短、或中间代理开启了响应缓冲,前端就会看到内容吐到一半突然结束。做法是把 stream 参数显式置为 true,把读超时放宽到 60 秒以上,确认反向代理关闭了缓冲与压缩,并观察服务端是否按固定间隔发送心跳行。 对接前应把计费口径算清楚,否则跑通后容易在成本上踩坑。模型聚合平台普遍按输入与输出 token 分别计量、按量计费,部分平台在注册时会赠送小额测试金,例如 5 元,足够跑通几十次短请求,但不足以支撑长上下文压测。做法是先用短 prompt 验证链路,再用真实业务里的最长 prompt 跑一轮,记录单次消耗,据此估算日成本;按套餐包月计费的通道不适用这套估算方式。 并发与限流需要单独做为一项配置对待。聚合平台通常对单个 Key 设置 QPS 或并发上限,超出后返回 429,而 Workbuddy 的批量任务和多轮会话容易在短时间内打满额度。做法是给客户端设置最大并发数,对 429 采用指数退避重试并加随机抖动,对 5xx 与超时同样重试,但 401、400 这类错误不应重试,重试只会放大失败次数。 多模型切换要预留降级路径。同一份 prompt 在不同模型上的表现差异,主要来自 system 提示处理方式、函数调用支持程度和上下文长度上限,直接切换可能出现工具调用失效或截断。做法是为每个任务配置主模型与备用模型,在错误码属于额度或限流类时自动回落,同时保证两套模型接收的消息结构一致;对不接受多轮 system 消息的模型,需要在适配层做一次消息合并。 密钥与日志的安全边界要在接入阶段就定好。平台的 Key 属于可直接产生费用的凭证,不能写进前端代码或提交到代码仓库,应该由服务端统一代理后再转发给模型聚合平台。做法是把 Key 放进环境变量或密钥管理服务,在 Workbuddy 侧只配置指向内部代理的地址,同时对请求日志中的 Authorization 头、用户输入与模型输出做脱敏,避免排障日志变成数据泄露渠道。 排错顺序建议由外向内,逐层收窄,而不是反复改配置。先确认网络可达与域名解析正常,再确认鉴权头格式,接着确认路径层级,然后确认模型 ID,最后才看参数与流式设置;这一顺序对应 401、404、400、429、5xx 与断流六类现象,能避免在错误层级上反复试错。做法是每次只改一个变量并保留单条可复现的最小请求,排障记录里固定保存时间、模型名、错误码与请求 ID。 选择聚合通道还是直连厂商,取决于是否需要统一账单与多模型兜底。当业务需要在多个模型之间做灰度、比对或临时切换,走聚合平台可以少维护几套密钥与计费关系;当业务只锁定单一模型、对延迟极其敏感,直连往往链路更短。做法是先用聚合平台跑通完整链路并量化延迟与成本,再根据实际数据决定是否把核心流量迁到直连,而不是一开始就把全部流量押在单一路径上。 接入完成的判定标准不是首页能对话,而是一份可复现的验收清单全部通过。清单至少包括:鉴权失败能被明确区分、模型清单与配置一致、流式输出完整结束、限流触发后能自动退避、单次请求的 token 消耗与账单对得上。达到这五点之后,再把 Workbuddy 接入模型聚合平台 API 的配置固化进部署脚本,避免下一次换人接手时又回到逐项试错。