Workbuddy 的适配器架构是怎么让一套调用同时兼容多种模型接口的?新增一个模型要改多少代码?

Workbuddy 用统一契约加模型注册表来兼容多模型接口:上层业务只依赖标准的请求、响应、流式事件、工具调用和错误语义,各模型在参数命名、分块格式、工具协议上的差异由对应适配器在内部翻译。它适用于差异能被契约描述的模型;模型独有且无法抽象的私有能力不能自动兼容,需要另开透传扩展点。

Workbuddy 的适配器架构之所以能兼容多种模型接口,是因为它把不同模型之间的差异统一交给一层可替换的适配器来处理,上层业务只依赖统一的行为约定,不直接面向某个厂商的接口;前提是这些差异能被约定描述清楚,模型独有的、无法抽象的私有能力不在自动兼容范围内,需要单独开透传通道。 适配器架构能扩展的前提是先定义一份与具体模型无关的调用约定。这份约定至少要覆盖请求结构、响应结构、流式事件、工具调用、错误语义五类内容,把“问什么、怎么回、中间过程怎么推、工具怎么调、失败了算哪类错”固定下来,各模型接口的字段名、嵌套层级和取值范围都只在适配器内部出现。只有先有这份约定,新增模型才是一次适配器实现,而不是一次全链路改造。 每个模型对应一个适配器实现,适配器只做两件事:把上层请求翻译成该模型认识的格式,再把模型返回翻译回统一结构。适配器通过模型注册表按标识查找,上层拿到的是同一个接口对象,不需要知道背后是哪个模型。这样做的代价是适配器数量会随模型增加而增长,收益是调用方代码几乎不变,问题也被限制在单个适配器里。 能力声明要写进适配器,不能等调用时才暴露差异。适配器应向注册表上报所支持的上下文长度、流式输出、工具调用、结构化输出、多模态输入等能力,上层在发起请求前先做能力协商,请求了不支持的能力就直接拒绝或走降级分支。缺少这一步,系统会在运行时才暴露不支持的参数,表现为静默忽略或报错,排查成本远高于入口处的一次校验。 流式输出的差异必须在适配器内部统一成事件模型。不同模型的分块粒度、结束标记、事件类型命名并不一致,有的按增量文本推送,有的把工具调用和文本混在同一事件流里。适配器应把原始分块整理成统一事件,再交给上层拼接,避免业务侧为每个模型写一套分块解析;这一层做不好,前端体验和用量统计都会对不上。 工具调用的兼容重点在参数模式转换和结果回填。适配器要把统一的工具描述转换成目标模型接受的格式,校验模型返回的参数是否符合模式,并在多轮调用中把执行结果按该模型期望的结构回填。参数名不一致、嵌套方式不同、同一轮返回多个工具调用,这些都是常见分歧点,应该在适配器内处理完,不让上层的编排逻辑感知具体模型。 错误归一化决定多模型切换是否可用。适配器要把各模型的错误响应映射到统一错误分类,至少区分鉴权失败、请求不合法、限流、超时、服务端异常和内容拦截,并标明哪些可重试。只有分类统一,上层的重试、退避和告警策略才能跨模型复用;否则每个模型都要配一套异常处理,切换模型等于重写容错逻辑。 路由与降级要建立在适配器提供的能力信息和健康状态之上。注册表可以记录每个模型适配器的可用性、限流余量和失败率,路由层据此在主模型不可用时切到备用适配器,并按比例灰度新接入的模型。这里的前提是各适配器对请求和响应的语义理解一致,否则灰度对比失去意义;不满足这个前提时,应先补齐约定测试再开灰度。 新增模型的成本应主要集中在配置和适配器实现,而不是改动上层。模型注册表通常以配置形式声明模型标识、适配器类型、能力项和路由权重,接入同协议的新模型可能只需加一条注册记录;协议差异较大的模型则要写新的适配器实现,但改动边界仍限定在该实现与注册项内。这条边界一旦被打破,适配器层就会逐渐退化成散落在各处的条件判断,维护成本迅速上升。 约定测试和录制回放是防止适配器腐化的必要手段。每个适配器都应对照同一套约定用例验证请求翻译、响应解析、流式事件顺序、工具调用参数和错误映射,并用真实响应录制做回放,保证模型接口变更能被及时发现。只靠人工点测,问题往往在上层业务表现为空结果或格式错误,定位链路长;把约定测试纳入接入流程,能显著缩短排查时间。 适配器架构有明确的适用边界。它适合差异可被统一约定表达的模型接口,不适合需要直接使用模型私有参数、私有事件或私有协议的场景,这类能力只能通过透传扩展点开放,并由业务自行承担兼容和版本跟进。同时要注意抽象泄漏:当某个模型的能力无法用现有约定描述时,要么扩展约定并评估对所有适配器的影响,要么承认该能力不进入统一层,不能靠隐式特判掩盖。 评估一套适配器架构是否真的兼容多模型接口,看四点就够了:上层是否存在按模型分支的判断,约定测试是否覆盖所有适配器,错误分类是否跨模型一致,新增模型时改动是否落在注册表和一个适配器实现内。四点都成立,说明适配器层真正起到了隔离作用;任何一点不成立,兼容就是表面的,切换模型时仍要回到业务代码里做修改。