Workbuddy 接入模型聚合平台 API 时,Base URL、模型 ID 和流式输出要怎么配才不会 404 或断流?

Workbuddy 接入模型聚合平台 API,关键是把 OpenAI 兼容的 Base URL、API Key 和模型 ID 填进自定义模型配置,并先用一条最小请求验证链路。聚合平台不兼容 /v1/chat/completions 时不适用;流式输出、上下文长度和工具调用需要单独验证,不能只凭一次问答成功就判定接入完成。

Workbuddy 接入模型聚合平台 API,核心是把聚合平台的 OpenAI 兼容端点、API Key 和模型 ID 三项填进 Workbuddy 的自定义模型配置,再用一次最小请求跑通链路;如果聚合平台只提供私有协议、不兼容 /v1/chat/completions,这套做法不成立。 接入前先确认聚合平台提供的是 OpenAI 兼容接口,这是 Workbuddy 自定义模型能否工作的前提。判断方法很直接:看文档里有没有 /v1/chat/completions 和 /v1/models 两个路径,是否支持 Authorization: Bearer 请求头。只给自家 SDK、不给标准 HTTP 端点的平台,Workbuddy 侧无法直接对接,只能换平台或走自建网关转一层。 Base URL 要填到版本号为止,不要填到具体接口路径。多数聚合平台给的地址形如 https://域名/v1,Workbuddy 会在其后自动拼接 /chat/completions;如果再手动补上 /v1/chat/completions,就会出现路径重复导致的 404。少数客户端要求地址不带 /v1,具体以 Workbuddy 当前版本输入框旁的提示为准,不要照搬别家客户端的填法。 API Key 建议单独创建、单独限额,不要直接复用主账号的 key。聚合平台一般支持多 key 管理,为 Workbuddy 建一个专用 key,设好日额度或月额度,出问题时可单独吊销,不影响其它应用。key 只存在客户端本地配置里,不要写进截图、日志或共享文档,否则一旦泄露,排查和止损都很被动。 模型 ID 必须与控制台里列出的字符串完全一致,不能用展示名称代替。控制台写的是带版本号的模型标识,就照抄完整字符串,不能只填系列名;填错的典型表现是 404 或 model not found,而不是 401,看到这类报错先回去核对模型 ID,别急着怀疑 key 失效。 三项填完后,先在 Workbuddy 之外做一次最小验证,再回来配客户端。用 curl 或聚合平台自带的调试台发一条最短的 chat 请求,确认返回 200 且带有 content 字段;这一步能把平台侧问题和客户端配置问题分开。跳过这步直接在 Workbuddy 里试,报错时很难判断是哪一端的问题,容易反复改配置。 流式输出是最容易出问题的一环,典型表现是请求成功但界面长时间不出字。Workbuddy 一般按 SSE 解析流式响应,如果中间经过代理、网关或公司网络,响应可能被缓冲成一次性返回,客户端就认为没有流。排查时先用 curl 带 stream 参数看是否逐块返回,再检查代理是否开启了响应缓冲,必要时给客户端调大首包超时。 上下文窗口和 max_tokens 要在 Workbuddy 里按模型实际能力设置,不能沿用默认值。聚合平台背后可能是上下文长度不同的模型,设置过大时请求会被上游拒绝并返回 400 或 413,设置过小则长文档对话会被提前截断。稳妥做法是按模型文档标注的上下文长度,减去预留输出长度后再填,长文本任务单独建一个模型配置。 工具调用和函数调用不是所有聚合平台都会透传,接入后要单独验证。如果 Workbuddy 侧开启了工具调用而平台不支持 tools 字段,常见现象是模型正常回话但从不触发工具,或者直接返回 400 参数错误。验证方法是在请求里带一个最简单的工具定义,看返回里有没有 tool_calls 结构;没有就关掉该能力,或换一个明确支持工具调用的模型。 多模型配置建议按任务分流,而不是把所有请求压在一个模型上。Workbuddy 支持配置多个自定义模型时,可以把长文本、代码、日常问答分给不同模型,同时保留一个备用模型应对限流。聚合平台侧通常按量计费,分流也便于观察每类请求的消耗,避免某一类任务把额度提前吃光,导致关键场景不可用。 错误码要有对应的处置动作,而不是每次重新填一遍配置。401 优先查 key 是否被吊销或额度用尽,404 查 Base URL 与模型 ID,429 查限流和并发,400 多为参数或上下文超限,5xx 则先看聚合平台的上游状态。把这几类响应对应到固定动作,排查时间能从小时级降到分钟级。 上线前跑一遍检查清单:最小请求通过、流式输出正常、长上下文不报错、工具调用符合预期、错误码有处置方案。五项都过才算接入完成,只跑通一次问答不算。接入后的日常维护主要是盯 401、429 和 5xx 三类响应,并在客户端设置重试次数上限,避免一次失败触发的循环重试在按量计费下放大消耗。