架构决策记录
ADR 0021: 平台参数与引擎参数分离——展示的命令必须复制即用
本文目录
日期: 2026-09-16 · 状态: 已接受(补充 ADR 0020 决策 1;不改变其余决策)
背景
KV 磁盘卸载需要一个"磁盘缓存容量上限"参数,消费方是 agent 的清理协程,vLLM 没有对应 flag。参数字典(deploy/param_specs.go)目前只发布带引擎 flag 的键:engineParams 对无 flag 的行直接跳过,Engines 由 flag 所在列推导。于是出现一个省代码的诱惑:给这个键填上磁盘层复合 flag --kv-transfer-config,借"同 flag 即伴随键"的推导让它自动落到磁盘层字段里,再让发射函数悄悄不把它写进 JSON。
这样做的后果是 flag 列不再是真话:/engines 会宣称某个键由 --kv-transfer-config 承载,而引擎从未收到它;"同 flag"推导从此有两种含义;下一个平台参数要么照抄这个例外,要么那时再加正经机制。更根本的是它动摇了一条产品承诺:部署页展示的命令用户复制粘贴到机器上就能跑,里面不能混进任何 vLLM 不认识的东西。
决策
- flag 列只表示真实的引擎 flag。 字典行的
VLLMFlag/SGLangFlag及其关闭形态,含义固定为"引擎命令行上承载该键的 flag"。不允许为了归组、联动或表单布局而填写引擎不接受的 flag。复合 flag(如--kv-transfer-config)的成员键必须全部真实写入该 flag 的值。 - 平台参数是字典的一等成员,但永远不进命令。 字典行以显式标记声明"平台消费",并显式列出适用引擎;
engineParams发布它们,Materialize把它们收进LaunchConfig,argv 组装、ReverseArgs、命令预览、模板偏差比对一律看不见它们。API 与表单对它们的处理与普通参数相同(显式值 > 字典默认;标为Automatic的由服务端从模型事实推导,不发明数字)。 - 展示的命令即可执行的命令。 命令预览与实例详情里的启动命令,逐 token 等于容器实际收到的 argv;这一点由用例钉住:任何平台参数的键名与值都不得出现在预览文本里。
- 平台参数不与引擎参数联动。 平台参数各自独立成立:用户填了容量上限但没开磁盘层,值照常保存、不报错、不产生任何副作用;平台只在相关引擎参数真正生效时才消费它(目录只在
shared_kv_dir存在时创建与监控)。表单不做"开了 A 才显示 B"的耦合,避免再造一份键关系的副本。
后果
- 正面:
/engines的每一个 flag 都可信;命令预览复制即用的承诺可测;新增平台参数只改字典一行加一个标记。 - 负面与约束:
ParamDefinition增加一个平台标记与显式引擎列表(新增结构,因为"该键不发给引擎"与"适用哪些引擎"无法从任何现有数据推导);前端不能再靠"同 flag"把平台参数归到某个层下,平台参数按其Group正常渲染。 - 首个实例:
kv_disk_limit_gib(磁盘 KV 缓存容量上限,GiB),Automatic,未设时取模型权重所占显存的两倍,用户可手填。
这篇文档有帮助吗?