跳转到正文

ADR 0034: 模型文件属于存储,共享存储上的模型文件只记一行

本文目录

日期:2026-10-02 · 状态:已接受

依据:存储抽象与 NFS 计划。修改 ADR 0018 的获取候选:在"本地已存在 / 节点间同步 / 公网下载"之外增加"存储"这一维。

背景

模型文件原来是"节点的东西":model_files 每 (模型, 节点) 一行,Path 是该节点上的目录,模型根目录是节点属性, "存储"只是一个内建的下载开关。要让多个节点读同一份 NFS 上的模型,只能每个节点各登记一行;N 行指向同一份文件、互不知情, 删一行会删掉大家共用的目录,两个节点往同一目录下载会互相写坏,千节点下状态同步要逐台校验同一批共享目录。

决策

  1. 存储是一等对象,有类型。 local(各节点上的一个目录)、nfs(agent 挂载的 NFS 导出,所有节点共用一份)、 nfs_cache(NFS 导出加每个节点的本地缓存,启动读缓存)、shared_dir(节点上已挂好的共享目录,行为同 nfs)。 节点不信任"目录能读":已有挂载的 nfs/nfs_cache 必须在 mountinfo 里是 nfs 挂载点,shared_dir 必须是挂载点或位于网络文件系统上, 否则报 failed/not_mounted——掉挂后留下的空目录在根盘上,不能当共享存储写。 类型是"权威文件在哪"与"节点怎么拿到本地路径"两件事的组合;以后加 S3 加本地缓存只需新增一种后端,缓存层只依赖"列文件、读文件"。 本地存储不再内建:新装时自动添加一个普通的默认本地存储,升级时把原内建行迁成它,节点原来的模型根目录变成它的节点覆盖。
  2. 模型文件按 (模型, 存储, 节点) 唯一。 本地存储每节点一行;共享存储的权威文件是节点为 0 的一行,path 是存储内相对路径; nfs_cache 的节点缓存是同一存储下带节点的行。节点能不能读共享模型文件由 storage_node_states(节点上报、只在变化时写)推导, 不落每节点一行;节点为 0 的行不随期望状态下发,agent 不校验共享目录。
  3. 一个位置查询入口。 "模型 M 在节点 N 上从存储 S 读哪个宿主机路径"只由 store.ModelLocation 回答, 共享路径只在 store.SharedHostPath 里拼。启动、评估、模板解析、磁盘准入、评测读 tokenizer 都问它,不再直接读 ModelFile.Path。
  4. 每台节点读它能读到的那份,部署不绑定存储。 建部署时的来源仍是用户显式选择、服务端只校验不替换(ADR 0018): "本地已存在"推广为"某个存储上已有",节点间同步与公网下载多一个"保存到"。之后每台节点上读哪份由 store.ModelSourceOn 一条规则决定,调度准入、controller、预览都只问它: 节点能直接读的就用(节点自己盘上的——本地存储、已缓存的 nfs_cache——优先于直接读 NFS); NFS 加本地缓存里有的先填缓存;都没有才获取,保存到部署记下的存储(deployments.weight_storage_id, Go 里叫 SaveToStorageID;只记请求里明确选的存储,没选为 0;它适用于这台节点时用它),否则默认存储,否则其他启用的本地存储。共享存储从不被自动写入:选了"保存到"某个共享存储而它里面没有该模型, 就拒绝并给出原因,不退而在各节点各下一份。要"只从某存储读",给部署加节点条件 gpuworks.ai/storage (系统标签,值是存储 ID,节点带上所有适用于它的存储;挂载暂时不可用的节点仍是候选、准入时给出原因),平台从不自动加。 每个实例在创建时记下它读的模型文件行与宿主机路径(instance_model_files),"是否在用"(缓存淘汰、删除模型文件、 删除或移动存储、重启检查、存储页的部署数)都按这些记录判断。节点间同步只保存到本地存储;写入共享存储走下载或复制。
  5. 停用即只读。 停用的存储不再下载、复制进来或删除模型文件(部署触发的下载同样被挡),已有的仍可部署; nfs_cache 的节点缓存与心跳不受影响。镜像落在节点的容器运行时里,不归存储管,存储开关不再影响镜像同步。
  6. 写入共享存储由一个写入节点执行,先暂存再改名。 暂存在 <根>/.gpuworks/incoming/<控制面 ID>/ 下, 完成后 rename 到最终路径;目标已被别的写入方占用且是同一个模型就采用它,不同就失败、不覆盖。不用 NFS 文件锁。
  7. 多套 gpuworks 共用一个存储时写心跳,删除时提醒。 每套控制面在 <根>/.gpuworks/control-planes/<控制面 ID>.json 写心跳,新鲜判断用 NFS 服务器的文件修改时间;删除共享模型文件时发现别的控制面在用,要求显式强制。心跳只是提醒,不是锁。
  8. agent 碰共享存储的调用都有时限。 挂死的 hard NFS 不能拖住状态上报:健康检查、状态快照、RPC 都经有时限的调用, 超时报 unresponsive;创建容器前对模型路径做有时限的 stat,不存在就以 MODEL_PATH_UNAVAILABLE 失败, 避免 docker 把缺失的挂载源建成空目录。

后果

  • 迁移 122–125 把内建存储、节点模型根目录、旧模型文件与部署迁进新结构,并删除 nodes.models_root、storages.builtin。
  • 存储的目录不依赖 agent:本地存储必须有目录(新装默认 /opt/gpuworks/models),nfs_cache 不填缓存目录时取 /opt/gpuworks/cache/<名称>;某台节点用不了时给它单独设目录。在握手时报出自己实际模型目录的 agent(Hello.own_models_dir), 节点还没有单独目录时平台把它记成该节点的单独设置,一次性、可见、可改。2026-10-04 修订:上报者从"非 root agent"扩大为 "非 root agent + 状态目录不在 /opt/gpuworks 的 agent"——自定义 --state 的 root agent(云上装在数据盘、CI 容器)若不上报, 首帧期望状态会把模型目录静默搬到全局默认路径,正是本 ADR 要避免的"看不见也管不住",而且会落到本应避开的磁盘上; 标准 root 布局两条路径本就相同,上报与否无差别,维持原行为。迁移 126 把留空的存储改成明确目录,并把各节点之前 实际使用的目录记成它们的单独设置。理由:模型目录是用户的数据决策,而 agent 状态目录随安装方式变化 (/opt/gpuworks、自定义安装目录、非 root 时的用户配置目录),由它决定模型落在哪里既看不见也管不住。
  • 协议:DesiredState.storages(存储任务)、status.storage(节点的完整存储状态,变化时发送)、模型文件任务的 key 改为行 ID(f<id>,旧格式仍接受)并带存储、缓存、复制源与暂存目录;新增 storage.probe/scan/peers/remove 四个 RPC。
  • 缓存淘汰是纯函数(internal/server/modelcache),调度准入与 controller 淘汰共用,按最近使用从旧到新、只淘汰未被引用、 不在传输中、有共享副本兜底的缓存;单个模型超过缓存上限时拒绝,不改成直接读。
  • 迁移 127 建 instance_model_files,并按现有实例期望状态里实际挂载的路径回填。早先的版本曾让部署绑定一个存储、运行时不替换, 结果节点本地已有的模型文件被忽略、这个限制又不出现在节点条件里;改为上面的规则,原因见 设计稿。
  • 不做的:跨控制面的删除锁、周期扫描、内核 FS-Cache、docker 的 NFS volume driver、对象存储直读。

这篇文档有帮助吗?