跳转到正文

架构决策记录(ADR)

本索引记录 GPUWorks 的架构决策、状态和取代关系。已移出的决策保留原编号。

编号决策日期状态
0001镜像校验采用「tag 拉取 + 事后比对」而非 digest 不可变引用2026-08-22校验部分已全部废止(image ID 三态 2026-08-23 移除,离线包 blob 比对 2026-10-08 随离线导入删除);ref 强制带 tag 仍有效
0002RunSpec 覆盖采用「字段级编辑体验 + 实例整体快照存储」2026-08-22已移出(RunSpec 已删除,原则见 0020、0022)
0003压测引擎内置于二进制,不依赖外部工具与容器2026-08-23有效
0004空 revision 表示跟随平台默认分支,不回填 main2026-08-23有效
0005蓝图为一等实体,两级结构(蓝图×档位),manifest 同构分发2026-08-24已移出(被 0007、0009 取代)
0006保存加密 SSH 凭证以支持带外恢复2026-08-24有效;认证材料部分由 0035 修订
0007推理模板 schema v2:更名、镜像下沉芯片层、参数字典化反解、证据分级2026-08-28已移出(被 0009、0020 取代)
0008芯片类与目录约定式量化门控,匹配从点名改为分班2026-08-30已移出(被 0009 取代)
0009扁平档位目录取代五层证据模型2026-09-01有效;args 列的内部拆分见 0020
0010推理目录采用模型同目录的可执行多文件包2026-09-01镜像不可变条款被 0017 取代;ImageDefaults 层被 0031 删除
0011同一原始模型的档位按来源隔离身份2026-09-01有效
0012PublicURL 解析优先级2026-08-23被 0025 取代
0013容器命令拼装按镜像来源分「命令模式」三档2026-08-24三种模式仍有效,manual 为 0020 的唯一例外通道;按镜像来源给默认值已被 0022、0031 取代
0014切分能力 ready 等于容器级探针通过2026-08-25有效
0015试验场请求四层组合(协议定义×目录声明×引擎发现×用户覆盖)与专家模式2026-09-05已接受
0016模型分类为 operation 与输入模态的投影2026-09-06已移出(kinds 机制已删除)
0017内置目录镜像引用改为纯 tag,不再要求 digest 不可变引用2026-09-07已接受
0018部署来源显式化,服务端只校验不替换用户选择2026-09-07已接受;部署显式获取方式由 0048 取代
0019镜像目录只维护运行时事实,兼容性采用排序告警2026-09-14已接受
0020启动配置单一事实源:一套字典化参数,命令模式是唯一特殊通道2026-09-15已接受;2026-11-02 修订:字典解不出的模板参数透传并告警,不再拒绝导入
0021平台参数与引擎参数分离,展示的命令必须复制即用2026-09-16已接受
0022部署启动配置归模板与显式选择,镜像不再提供可编辑默认层2026-09-19已接受;存量兼容与 launch_contract 标记被 0031 取代
0023多副本推理网关默认负载均衡,连接级失败重试2026-09-23已接受
0024数据面 lane 断开时不回退控制面,等待重连或返回可重试 5032026-09-24已接受;取代 artifacts/archive/2026-09-08-tunnel-bandwidth/plan.md §3.2
0025server 不管理自己的对外地址,地址由拿到它的一方给出2026-09-27已接受;取代 0012
0026网络决策集中在纯叶子包与一个服务,网络目录经接口注入2026-09-27已接受
0027RDMA 网络由推断加节点固定代替选择器,测试工具优先宿主机、其次内置2026-09-28已接受;修订 0030 决策 1
0028PD 分离部署是一个部署加实例角色,两阶段由现有网关编排2026-09-29已接受
0029每个部署都按 unit 对账:角色 → unit → rank,一套重试、整组失败与排空2026-09-29已接受
0030节点网络是可附加的对象,每节点每角色的解析结果按需计算2026-09-25已接受;原编号 0024,与 0024 数据面 lane 撞号,2026-09-30 改为 0030
0031镜像目录不承载启动配置,所有部署按同一套启动语义解释2026-10-01已接受;取代 0022 存量兼容部分
0032持久化事实默认用带类型的列,JSON 列只做整体读写的不透明快照2026-10-01已接受
0033生命周期操作落到副本:排空状态、默认滚动重启、多个多机副本、睡眠意图在实例上2026-09-30已接受
0034模型文件属于存储,共享存储上的模型文件只记一行2026-10-02已接受;修改 0018 的获取候选
0035server 持有一对平台 SSH 密钥,带外恢复优先用它,不再保存节点密码2026-10-03已接受;修改 0006 的认证材料
0036callable 的命令行归模板,平台事实以模板变量给出2026-10-08已接受
0037试验场 HTML 预览在不透明源沙箱里运行,网络默认禁止、由管理员开关放开2026-10-08已接受
0038推理模板声明镜像来源,系统改写规则只作用于系统镜像2026-10-08已接受;补充 0018 的镜像候选来源;决策 5 由 0048 取代
0039推理指标的来源分层,观察配置由 server 唯一解析、运行中原地更新2026-10-10已接受
0040服务端升级与官方目录走签名索引的多源发布通道,官方目录最后一次导入生效2026-10-11已接受
0041平台 API 令牌与 MCP 服务共用一种凭证2026-10-11已接受
0042网关为流式请求向 vLLM / SGLang 要 usage 并剥离多出的块,逐请求记录写独立的 ux.db2026-10-12已接受;修订推理指标计划 D4
0043服务健康由探测请求判断,监控不再用规则与阈值下结论2026-10-13已接受
0044Mac 节点的引擎以宿主机进程运行,镜像是 darwin 环境包2026-10-14已接受
0045公网入口的连接器跑在独立的连接器服务里,不随 server 启停2026-10-14已接受
0046网关为每个请求建立 W3C trace context,trace id 写进请求记录,逐请求记录按 OTLP 导出2026-10-15已接受;决策 3 由 0047 修订
0047PD 请求的 prefill 阶段由网关实测并单列,KV 传输只给聚合统计2026-10-15已接受;修订 0046 决策 3
0048镜像从哪里拉由节点的拉取设置决定,部署不再选来源2026-10-16已接受;取代 0018 的部署显式获取方式与 0038 决策 5
0049公网入口启用期间,server 信任来自本机的转发头2026-10-17已接受;补充 0045
0050来源规则同时覆盖模型站点,代理按标签配置,凭据按 host 统一2026-10-17已接受;取代 0048「后果」中模型下载规则留待后续的一条
0051agent 的启动配置记在 <state>/gpuworks-agent.conf,所有启动方式都只是 run --state2026-10-19已接受
0052Kubernetes 是一种节点来源加一种运行时,卡按需向 kubelet 借用2026-10-19已接受
0053整个存储可浏览,只有 files/ 与 .gpuworks/apps/ 可写;上传先落暂存、成功后才回报,下载边打包边传2026-10-21已接受
0054用户体验改进计划默认加入,日报发往托管日志服务;发布方通知走签名发布通道2026-10-22已接受;修订 0040 补充的开关取舍
0055长期统计与原始观测分开存储:一对象一行、在入库路径上累加、增量写入;Token 用量放主库,其余放 stats.db2026-10-22已接受
0056runveil 镜像拉取的连接数由按仓库 host 的预算自适应,慢连接按同伴相对判断2026-10-27已接受
0057多机与 PD 的单元由平台自动放置,做法是把挑选结果写回单元2026-10-28已接受;补充 0028、0029 的放置方式
0058调度中心只执行运维事先下达的指令,休眠让出到每实例残留,节点失联重调度按运维改放置的方式进行2026-10-25已接受;补充 0033;决策 1 的“不抢占、不挂起请求”由 0059 修改
0059按服务等级共用 GPU:网关挂起请求等唤醒,驻留仲裁按一条让卡规则抢占2026-10-28已接受;修改 0058;2026-10-29 修订:出让策略取代服务等级与闲置休眠,再修订:出让策略是唯一的选择,预设与自动休眠取消;2026-10-29 修订:新部署作为等卡方
0060卡的健康只由硬件事实判定;事件类错误要有恢复的证据,人工干预优先2026-11-01已接受;补充 0043
0061推理档位的显示名由人写在目录里,不再由前端拼出2026-11-02已接受;修改 0009
0062模板组件跟随主模型落到它所在的共享存储2026-11-11已接受;补充 0034
0063从云账号接入的托管集群,经用户确认后由 server 用现发的短期 kubeconfig 应用接入 manifest,不保存凭据2026-10-22已接受
0064指标与日志批次走数据通道上的遥测流(server 宣告能力位才启用),日志在 agent 侧有界缓冲、重连后补发2026-11-13已接受;补充 0024
0065官方推理目录包按模型和档位容错读取:读不懂的跳过并报告,已有的记录保持原样;用户自己的导入保持严格2026-11-15已接受;补充 0040、0010
0066agent 的状态按所有者与生命周期成组,组合根只做接线2026-11-15已接受

说明:0012–0014 原分别与 0004、0004、0006 撞号,2026-09-03 整理时按创建顺序重新编号;历史提交信息与 MR 描述中的旧编号不再准确。原 0024(节点网络对象)同理,因与数据面 lane 的 0024 撞号,2026-09-30 改为 0030;此前引用「ADR 0024」指网络对象的文字已随之更新,CLAUDE.md 与 todo.md 中的「ADR 0024」指数据面 lane。

这篇文档有帮助吗?