跳转到正文

ADR 0065: 官方推理目录包按模型和档位容错读取,读不懂的保持原样

本文目录

日期:2026-11-15 · 状态:已接受(补充 ADR 0040、ADR 0010)

背景

内置推理模板目录随每次发布放到发布通道(ADR 0040),所有 server 的「检查更新」读同一份。目录按最新的 server 编写,而 server 逐字段严格解析 model.yaml:包里只要有一个模型用了旧 server 不认识的字段,整包被拒绝,这台 server 就收不到任何模板更新。

包格式版本号(schema_version)本应拦住这种情况,但它靠人记得去提升。gpus.arch_id(2026-11-03)和 API 契约里的 tokenizer_ref(2026-11-10)加入目录时都没有提升版本号,已发布的 v26.11.x 读到这样的包只会报解析错误。

决策

  1. 官方目录包容错读取。「检查更新」和官方目录包上传读包时,这个构建解析不了或校验不过的 spec 被跳过;模型自己的字段读不懂、或它的 spec 单独都能通过却不能一起通过时,跳过整个模型。其余照常应用。跳过会沿组件引用传递:引用了被跳过模型的 spec 一并跳过,因此不再被任何 spec 引用的无 spec 模型也不保留。
  2. 包本身仍然严格。 文件布局、路径安全、清单里的模型数与 spec 数(按包里写的数,不按读懂的数)、保留下来的 spec 的 assets 摘要都照旧校验,任何一项不符整包拒绝。model.yaml 不是一个映射、清单读不出来、包格式版本高于本构建,同样整包拒绝。
  3. 包按发布的原样保存。 被跳过的内容不从包里删掉,包的 digest 仍是通道发布的那个,「是否有更新」的比较不受影响;升级 server 后再读同一个包即可读全。
  4. 被跳过的已有记录保持原样。 数据库里已有的 upstream 模型或 spec 如果在新包里被跳过,这次更新不改写也不删除它,它继续指向原来的包;新包里真正去掉的模型和 spec 仍被删除。当前生效的目录是最近一次写入 spec 的那个包。
  5. 结果告诉管理员。 应用结果列出每个被跳过的模型或 spec 及原因,设置页把它留在页面上。
  6. 用户自己的导入保持严格。「导入模板」无论是 YAML 还是目录包,遇到不认识的字段照旧报错并指出位置:那里的未知字段多半是写错了,静默跳过会让配置少一项而不被发现。
  7. 包格式版本提到 3,此后只为布局变化提升。 3 标记含 gpus.arch_id 与 tokenizer_ref 的目录,让只认 2 的 server 把它标为「需要先升级服务端」而不是报解析错误。认识 3 的 server 都容错读取,model.yaml 里新增字段或规则不再需要新版本号;包的文件布局或清单发生旧 server 无法跳过的变化时才提升。

结果

一个按新 server 编写的模板只影响它自己:旧 server 仍能收到其余全部更新,已经在用的档位不会因为更新而消失。

代价与不做的事

  • 部分应用之后,数据库里的 upstream 记录可能来自两个包。被保留的旧记录引用的旧包不会被清理,直到 server 升级后重放内嵌目录或再次完整应用。
  • 被跳过的新模型和新 spec 在旧 server 上不可见,只能从应用结果里知道它们存在。
  • 已发布、不含本决策的 server(v26.11.0–v26.11.3)不受益:它们看到版本 3 的目录会提示先升级服务端。不为它们另发一份降级的兼容包。
  • 跳过的原因取自解析器或校验器的报错原文,不翻译。

这篇文档有帮助吗?