Workbuddy 的适配器架构怎么兼容多家模型接口,新增一家供应商要改哪几层?

Workbuddy 的适配器架构把模型调用拆成统一契约层与供应商适配层:业务侧只依赖一套内部协议,参数映射、流式解析、工具调用格式和错误码归一都收敛在适配器与能力表里,新增一家供应商通常只动这两处。它不能抹平厂商私有参数,这类差异需要走受控透传。

Workbuddy 的适配器架构把多模型兼容拆成两层:业务侧只面对一套统一的内部调用契约,供应商差异被收敛到独立适配器里,新增一家模型厂商时改的是适配器和能力表,不改上层业务代码;这套做法对已经纳入契约的供应商成立,对厂商私有的、未被契约覆盖的参数则需要走透传通道,不能指望一层抽象抹平全部差异。 统一契约层要先把请求、响应、流式事件、工具调用、错误五类对象定义清楚,否则适配器会越写越像逐家翻译脚本。多模型兼容的返工大多不在网络层,而在字段语义:同一个输出上限参数在不同厂商那里可能只算生成内容,也可能包含推理过程消耗;system 提示在不同接口里可能是一条消息、一个独立字段,或拼进首条用户消息。契约层把这些固化成内部字段后,适配器只做单向映射,业务代码不感知厂商。 一个可维护的模型适配器至少要暴露六个钩子:鉴权、端点与版本拼接、参数映射、流式解析、错误码归一、能力声明。鉴权负责把内部凭证换成厂商要求的请求头或签名;端点拼接处理不同区域与版本路径;参数映射负责字段改名与取值裁剪;流式解析把各家事件格式还原成统一增量;错误码归一让上层用一套判断做重试;能力声明告诉路由这一家支不支持工具调用、图像输入、结构化输出。少一个钩子,差异就会漏到业务层。 多模型兼容不该写成按厂商名分支的条件判断,而应做成注册表加工厂:供应商标识、适配器实例、能力表条目一起注册,调用方按策略取实例。分支写法的代价在回归——每加一家都要改动同一段判断逻辑,测试面随供应商数量增长;注册表写法把变更限制在新增文件和一个配置条目内,老供应商的行为不受影响。对需要长期跟进多家接口的客户端来说,扩展点设计比单次接通更重要。 参数映射的坑集中在采样参数与消息结构两处:温度、核采样阈值的默认值和合法区间各家不同,最大输出长度的计量方式也不一致,直接透传会出现同一提示词换模型后输出长度骤变。做法是在契约层定义中性参数,适配器按目标厂商的区间做夹取和默认值补齐,并在能力表里标明「不支持则忽略」还是「不支持则报错」。消息结构上,多模态内容块要拆成厂商要求的形态,system 消息位置要按目标接口重排,不能只做字符串替换。 流式兼容的关键不是把服务端推送事件读出来,而是把增量语义对齐:有的接口按词元推增量,有的按句子或事件推完整片段,结束原因也分正常结束、长度截断、内容过滤等多种取值。适配器要把它们统一成「增量文本加结束原因」两类事件,并处理心跳与空包,否则前端会出现半句话卡住或重复拼接。已经向外输出部分内容后再重试是不安全的,流式场景的重试边界应放在首包之前。 工具调用是各家接口差异最大的一块:函数描述放在请求的哪个字段、是否支持并行调用、调用标识如何回传、结果消息的角色名怎么命名,都没有完全统一。适配器的做法是把内部工具描述编译成目标格式,把返回的调用请求还原成统一结构,并在能力表里标出该模型是否支持工具调用。对不支持工具调用的模型,应降级为提示词约定并在结果解析层做校验,而不是假装支持后让上层拿到空调用。 错误处理要先把各家返回归一成有限几类:鉴权失败、限流、上下文超限、内容拦截、服务端错误、参数非法。归一之后重试策略才有意义——限流和服务端错误可以退避重试,鉴权失败和参数非法重试只会浪费配额,上下文超限应触发截断或换用更长上下文的模型,而不是原样重放。重试还要考虑幂等,只读的补全请求可以重放,带副作用的工具调用链路不能盲目重试。 能力表是适配器架构里最容易被低估的部分:它决定某个请求能不能路由到某家模型,而不只是能不能调通。把上下文长度、是否支持图像、是否支持工具调用、是否支持结构化输出写成声明式矩阵,路由层就能在候选模型里先过滤再排序,避免请求成功但能力缺失的静默错误。矩阵要随厂商接口变更同步维护,否则适配器会变成过期能力的缓存。 适配器的质量靠契约测试而不是手工点选:对每个适配器跑同一组输入,断言统一响应结构、流式事件序列和错误归类,接口变更时能在合并前暴露差异。上线阶段按供应商维度做开关和灰度,把新适配器先接到小流量或影子请求上比对输出,确认参数映射没有改变业务语义后再放量。把适配器当独立可测单元,才不会每次加模型都全量回归。 多模型兼容的成本主要不在首次接通,而在长期跟进:厂商改字段、下线旧版本、调整限流口径都会传导到适配器。把适配器、能力表、契约测试放在同一处维护,新增供应商的工作量可以压缩到写一个适配器文件、加一条能力表记录、补一组契约用例,业务侧零改动。反过来,如果差异散落在业务代码里,每接一家都是一次局部重构,维护成本会随模型数量累积。 适配器架构不能消除所有差异,它只保证差异有地方放:厂商私有的推理参数、特有的内容审核字段、非文本模态的专有结构,应通过受控的透传字段交给调用方显式使用,而不是塞进统一契约。判断标准是能被两家以上模型共同表达的进契约,只有一家支持的走透传并标注不可移植。这样换模型时才不会因为一个私有字段导致整条链路失效。