跳转到正文

使用存储:本地目录、NFS 与 NFS 加本地缓存

本文目录

本文说明怎样添加模型存储、导入已有模型库,以及选择部署使用的存储和管理本地缓存。

添加存储前准备好路径;试挂、扫描或部署前,先接入可访问该存储的在线节点。已有模型目录须对 agent 可读,下载或复制目标须可写。添加、修改、扫描导入和清理存储需要管理员权限。按文件位置和读取方式选择存储类型:

存储路径与缓存目录可以是任意绝对路径,不必位于 server.yaml 的 storage_probe_roots 内。路径不能是 /,不能含 .、.. 段或控制字符;也不能位于禁用目录下,默认禁用 /etc、/proc、/sys、/dev、/boot、/bin、/sbin、/lib、/lib64、/usr、/run、/var/run、/var/lib/docker、/var/lib/containerd 及其子目录。禁用目录由主机管理员在 server.yaml 的 storage_denied_paths 中整体替换,重启 server 生效,管理 API 与设置页不能修改,见配置参考。节点挂载和试挂时还要求路径是规范目录,不能经符号链接指向别处。违反这些规则的新建、修改或试挂会被拒绝:格式不对返回 STORAGE_PATH_INVALID,位于禁用目录下返回 STORAGE_PATH_DENIED,两者都在错误里给出被拒的路径;已保存的路径后来落入禁用目录时,不改路径的编辑仍可保存。

类型模型文件在哪节点怎么读适合
本地存储每个节点自己的目录直接读,每节点各一份节点数少,或要求不依赖网络存储
NFSNFS 导出,agent 负责挂载挂载后直接读,所有节点共用一份链路快、模型多而本地盘小
NFS 加本地缓存NFS 导出先拷到节点的缓存目录,再从缓存读链路慢、长期服务、要求 NFS 掉线时不受影响
已挂好的共享目录节点上已经挂好的目录(CephFS、Lustre、自己挂的 NFS)直接读,agent 不挂载agent 不是 root、或不是 NFS 的共享文件系统

新装平台带一个名为 default 的本地存储,默认目录为 /opt/gpuworks/models,可以改名、改路径或删除。

添加其他本地存储或已挂好的共享目录时,在存储 → 添加存储选择相应类型,填写目录和适用节点。本地存储可直接保存;已挂好的共享目录必须先点试挂,确认目录可读、试挂通过后再保存。保存后检查节点可用状态。已挂好的目录由你维护挂载,agent 不负责挂载或卸载。

本地存储必须填目录;NFS 加本地缓存未填缓存目录时使用 /opt/gpuworks/cache/<存储名>。非 root agent 首次接入时,默认本地存储会为它记录可写的状态目录下 models 路径;可在存储详情和编辑框中查看、修改,之后不会被自动覆盖。节点提示目录不可用时,在存储的适用节点中为该节点设置目录;选择全部节点时也能单独覆盖。目录不随 agent 安装位置改变,从旧版升级也保留各节点原来使用的位置。设计说明见 ADR 0034。

添加一个 NFS 存储

由 agent 挂载 NFS 时,节点上的 agent 需以 root 运行、已安装 NFS 客户端(nfs-common 或 nfs-utils),且能访问导出地址。非 root 或自行维护挂载时,使用已挂好的共享目录,或为相应节点选择使用已有挂载。

  1. 打开存储页,点添加存储,类型选 NFS 或 NFS 加本地缓存。
  2. 填导出地址(主机:/路径)。挂载点默认 /mnt/gpuworks/<存储名>,各节点一致;挂载选项默认 rw,noatime, 其余交给内核协商,只接受白名单里的选项。
  3. 选这个存储用在哪些节点:全部、按标签(新节点带上标签就自动挂载),或逐台(逐台时可以给某台单独设挂载点, 或勾选使用已有挂载让 agent 不挂载也不卸载)。选择 NFS 加本地缓存时,继续填写缓存策略:缓存目录、每节点默认上限及节点例外,然后到确认页核对;上限默认不限,不是磁盘预留或集群总配额。
  4. 点试挂,检查读写结果。由 agent 管理挂载时,会在一台节点上临时挂载、读根目录、在 .gpuworks/ 下试写,然后卸载;选择使用已有挂载时直接检查现有目录。失败时按原因检查客户端、网络、权限或导出路径;通过一台的试挂不代表所有节点都可用。
  5. 保存后检查存储卡片的 N/M 可用,查看并处理有问题的节点。需要部署的节点应处于可用状态。

试挂能挂上但写不进去(例如 root_squash)时,存储以 只读(停用) 状态保存: 可以扫描导入和部署,不能往里下载或删除。

导入已有的模型库

NFS 上已经有按 <组织>/<仓库名>/ 存放的模型时:

  1. 在存储卡片上点扫描导入。一台挂载正常的节点遍历目录(默认最多 4 层),解析常见格式与清单,列出模型入口。找到一个模型后仍检查子目录,避免漏掉仓库中的其他入口。
  2. 检查模型格式、任务类型、身份依据和异常原因。只选择完整、可导入的模型入口;组件或适配器不能当作基础模型。缺片时补齐文件,元数据损坏时修复,层级过深或同目录多个模型时调整目录后重扫。
  3. 勾选后点击导入所选。平台重新检查目录,匹配已有登记或新建记录。导入只登记文件,不往存储写文件,也不会移动目录。
  4. 在模型页确认模型身份、所在存储与可用状态,再选择匹配的推理模板。识别为模型入口只证明目录结构符合规则,不保证任意引擎都支持它。

库变化后重新扫描:新目录标为新发现;已导入但消失的目录会标为缺失并阻止新的启动。完整识别需要新版 agent,旧 agent 使用兼容的文本元数据读取方式。

识别格式、任务类型与导入边界

核对格式与文件完整性

  • Transformers safetensors/bin(含索引分片)、Sentence Transformers、Diffusers 管线、ModelScope 标准配置与权重、Mistral 原生格式和 GGUF 都在识别范围内。

  • ONNX 当前要求同目录 config.json 与 model.onnx;SavedModel 要求 saved_model.pb 和 variables/variables.index。

  • GGUF 会区分模型与 mmproj/controlvector 组件,并组合标准命名的分片。不同量化放在不同子目录时分别列出;同目录多个独立模型会提示分目录导入,不把它们合成一个模型。

    没有关联清单时,不自动推断根目录组件与量化入口的运行依赖。

仓库内的独立子目录按本地模型及实际相对路径登记,不会自动与远程下载保留仓库层级的子目录制品混绑。管线中的 audio_vae、编码器等组件不会单独列为模型。

组合模型按组件的文件契约检查:

  • Sentence Transformers 的 Transformer、Dense 检查配置与权重,Pooling、LogitScore 只检查配置,Normalize 不要求独立目录。
  • Diffusers 的模型组件检查配置、权重及索引分片,scheduler 检查配置,常见 CLIP/T5 tokenizer 检查词表文件。

核对任务与 API 能力

新建模型的 API 能力来自结构化任务声明:text-ranking 对应 rerank,feature-extraction、sentence-similarity 对应 embeddings。模型卡支持单个任务或任务列表,ModelScope 的 configuration.json 和 Sentence Transformers 模块也提供任务证据。

判断任务时,注意以下优先关系和结果:

  • 声明优先于底层架构,目录名称和说明正文不作为类型规则。来源顺序参考 AIOS:模型卡明确声明优先,任务专用模块和模型卡标签优先于 ModelScope 的通用任务配置,底层架构只作兜底。
  • 同优先级的证据冲突时保留空能力并显示原因。未知类型不再默认 chat。
  • 本地目录注册使用同一个解析器;已存在模型保留其 API 能力,重扫、重导入和刷新不会自动改写旧记录。本期未增加人工覆盖识别规则的入口。

判断不能导入的原因

单模型登记与扫描导入都会拒绝已确认的组件目录、多模型目录,以及文件缺失或无法验证的已识别入口。两种入口都要求所选目录通过元数据恰好识别出一个完整模型入口;父目录、非模型目录和未知布局会被拒绝。

出现以下提示时,不要把入口当作已验证完整:

  • 组件文件布局尚未验证:未知自定义组件不会仅因目录存在就标为完整。当前权重检查覆盖标准默认文件名与分片;需要额外 variant 参数的布局不自动推断。
  • 识别未完成:达到读取上限,不作为文件损坏或缺片的证据。大型权重索引按块解析,只保留引用的分片路径;GGUF 可读取较大的 tokenizer 元数据。

部署时选存储

部署表单的「模型权重」一栏列出存储选项(部署不选择从哪里获取,节点按拉取设置自行决定):

  • 存储 X 上已有:每个已经有这个模型、目标节点能访问的存储一项。本地存储那项就是原来的「本地已存在」。 NFS 写「直接读」,NFS 加本地缓存写要先缓存多少;目标节点挂载不可用时这项置灰并写明原因。
  • 保存到:节点需要取模型时(同步组内复制,或下载)保存到哪个存储,预选默认存储;复制只保存到本地存储。

所选的存储只决定需要获取时保存到哪,部署不绑定存储。之后每台节点上的副本读它能读到的那份:

  • 节点自己盘上有(本地存储,或 NFS 加本地缓存已缓存的),就用它。
  • 否则节点挂载的 NFS 上有,就直接读。
  • 否则 NFS 加本地缓存的存储里有,先复制进这台节点的缓存。
  • 都没有才获取(同步组内复制,不行再下载),保存到部署时选的存储——它适用于这台节点时;否则保存到默认存储,再否则其他启用的本地存储。部署没选「保存到」时,如果节点读得到的某个共享存储正在写入这个模型、且这次写入是本部署发起的,就等那一份写完再读,不另下一份;别人发起的写入不等。

平台不会自动往 NFS 里下载。部署时选了"保存到"某个 NFS,而它里面没有这个模型(下载失败或被删了),副本会停下并说明原因, 不会改成在各节点各下一份。

唯一的例外是推理模板的组件(例如主模型之外单独的文本编码器):主模型已经在某个共享存储上、部署又没选"保存到"时,创建部署会把有目标节点读不到的组件下载一份到主模型所在的这个共享存储,由一个节点写入,各节点等它下完后直接读,不会各自下载到本地盘。部署本身仍记为没选"保存到"。

这个写入在部署前后都看得到:部署表单的"组件权重"逐个列出模板组件怎么获取(已就绪、写入哪个共享存储、或各节点自行下载),会写入共享存储的组件标出存储名、占用空间和避免的办法;创建后部署时间线记一条"组件开始下载到共享存储",写明写入节点。不想写入时,在节点条件里限定存储;表单显示"保存到"时,也可以在其中选本地存储。删除部署不会删除这份文件,需要时在存储的文件列表里删除。

要让部署只读某个存储(比如只想从 NFS 读),在部署的节点条件里加"存储: 名称"。不在该存储适用范围内的节点不会被选中; 在范围内但这会儿挂载不可用的节点仍是候选,放置原因里会写明。

部署启动后,在实例详情核对实际读取的存储及宿主机路径。保存到决定获取文件时的目标,存储节点条件限定可读取的存储,两者用途不同。

缓存准备进度与恢复

NFS 加本地缓存的模型在本地副本完成前不会启动实例。在推理服务页查看准备摘要;需要定位时打开详情,按节点、主模型与组件、所选存储查看检查源、复制、校验、安装或缓存淘汰阶段。单个权重文件未完成时也会更新已复制字节;总量未知时不显示百分比,速率稳定后才显示预计剩余时间。

部署填充缓存不限速。模型页手动复制可以为这一次复制设限速(MiB/s),留空或 0 即不限;重试失败的复制沿用它的限速,之后的新复制不继承。

连续两分钟没有实际进展会提示复制无进展;主动限速等待不算阻塞。该提示与存储健康检查报告的“NFS 无响应”、节点离线、磁盘不足分别显示。观测超过 15 秒未更新、节点断开或 server 重启后会回到等待更新,不沿用陈旧速率。

旧 agent 缺少完整阶段和安全停止确认时,先按升级指南升级 server,再升级 agent。显示等待更新不等于已确认 NFS 故障。

失败时先查看容量、节点和 NFS 状态,处理后在详情中重试。平台需确认旧任务退出才启动新复制;文件系统仍阻塞时,重复点击不会启动第二份复制。部分文件仅在源清单的路径、大小与修改时间一致时续传,不保证做过全文件校验和验证。

停止部署会撤销它的缓存准备引用;其他部署仍需要的复制继续进行。最后一个引用撤销后取消该缓存复制,保留部分文件;阻塞中的 I/O 退出前继续占有任务槽。已完成的缓存保留供后续使用。

本地缓存的容量

NFS 加本地缓存的存储有一个缓存上限:按每台节点计算,可按节点覆盖,默认不限。平台还为缓存盘保留一部分空闲空间,在存储页设置,默认取磁盘 10% 与 50 GiB 中较小的一个。

往某台节点缓存新模型而空间或上限不够时,平台按最近使用时间从旧到新淘汰缓存。只淘汰没有部署或实例在用、不在拷贝中、NFS 上还有权威文件的缓存;单个模型比缓存上限还大时直接拒绝并说明,不会悄悄改成从 NFS 直接读。

默认策略与节点例外

修改缓存配置时,打开存储详情的节点页,先核对默认目录、默认上限和各节点有效配置。降低上限前,检查已缓存、可回收和受保护数据。

改目录前还需确认:

  • 变更不会搬迁旧文件;旧文件不计入新目录预算,也不会被新目录的后台整理删除。
  • 新目录容量未上报、节点离线或缺少统计时,容量影响为未知。
  1. 选择修改默认策略,或为节点选择跟随默认、自定义上限、不限。自定义支持 GiB/TiB;不限仍受磁盘保留空间约束。默认上限只影响跟随默认的节点,恢复上限继承不会重置目录。

    节点范围与配置例外分开:给标签范围中的节点设置例外不会将其永久加入范围。节点失去标签后,例外保留为未适用,重新匹配时继续生效。历史显式选中的节点仍是范围成员。修改范围时,请检查已有混合标签与节点选择。

  2. 批量修改时,按名称、地址、配置来源或整理状态筛选,选择固定节点集合,再填写要修改的字段;保存只修改明确选择的字段。

  3. 保存后核对有效配置。若其他管理员已修改配置而提示冲突,重新打开最新配置后再改。

详情刷新失败会保留已有数据并提示可能过期,可点击重试。编辑中的草稿不会随轮询变化。

查看整理结果与清理缓存

保存后查看整理状态。整理只回收安全副本;部分数据暂时受保护时,会先回收安全部分,并显示待处理、整理中、受阻或失败等状态。离线节点等待恢复,失败的整理处理原因后重试。

需要主动回收时,在存储卡片点击清理缓存,手动淘汰所有可淘汰的缓存;在详情中选择节点后清理,只回收所选节点的可回收数据。不保证清空正在使用、传输中或缺少权威副本的数据。

处理整理受阻与删除待确认

缓存已被在用模型占满:磁盘够、但上限被在用的模型占满时,部署事件会写明这一原因。调高上限或停掉用这些模型的部署即可。

删除待确认:缓存删除超时或失败后,模型文件保留为这一状态,不会继续用于部署或重新复制。点击整理/清理重试会沿用原删除标识,先确认这次删除,再按最新容量重新规划。

确认前,删除模型、节点、存储或改变相关目录/作用域会被拒绝;调高缓存上限仍可保存。旧 agent 不支持删除确认时,先升级 agent,待确认记录会保留。

agent 状态目录中的 .gpuworks-evictions/ 是删除回执,用于避免断线、重启或迟到重试误删后来填充的模型,须随状态目录保留,不要当普通缓存清理。文件系统不支持目录同步或状态目录不可写时,删除会失败。

在 NFS 与 NFS 加本地缓存之间切换

存储详情的**更多 → 切换为 …**只在这两种类型之间切换,NFS 上的文件不动。

从 NFS 加本地缓存切换为 NFS 时,控制台先像清理缓存一样删除各节点上的缓存,再改类型。切换为 NFS 后节点不再管理缓存目录,留下的文件就没有途径再清理,所以只要还有节点缓存,服务端就拒绝切换,并说明还剩几项、分布在几个节点、其中几项还在复制或下载;具体是哪几项,在存储的文件列表里按节点查看。已清理的缓存不会恢复;切换没成功时,存储仍是 NFS 加本地缓存,缺的缓存在之后启动时重新复制。

常见的剩余项和处理办法:

  • 还在复制或下载:等它完成,或在部署或模型页取消,再切换。
  • 正被实例使用:停掉用这些模型的部署。
  • 复制没成功(失败、已取消、磁盘不足等):在存储的文件列表里,对该节点那一行选清除这台节点上的缓存。存储停用时也能这样做。
  • 模型只存在于节点缓存里、NFS 上没有副本:先把模型放回 NFS,或在该节点上删除这份文件。
  • 节点连不上:等它重新连上。节点离线但上面没有这个存储的缓存时,不影响切换。

改过缓存目录后留在旧目录里的文件,平台本来就不再管理(见默认策略与节点例外),不会阻止切换,需要时在节点上手动删除。缓存目录和上限设置会保留,切回 NFS 加本地缓存时沿用。

多套 gpuworks 共用一个 NFS

每套 gpuworks 各自添加存储、各自扫描导入,互不影响。可写的存储上,每套控制面在 .gpuworks/control-planes/ 下写一个心跳文件, 存储卡片显示「还有哪几套 gpuworks 在用」。删除共享存储上的模型文件时,如果别的 gpuworks 5 分钟内出现过(各自每分钟刷新一次心跳),平台提醒并要求勾选 「强制删除」。心跳只是提醒,不是锁:被强制删除后,别的控制面再次扫描会把它标为缺失,正在从 NFS 直接读的实例重启时会失败。 约定一个库只有一套 gpuworks 往里写,其余只读或用「NFS 加本地缓存」。

浏览存储里的文件

管理员可以在存储详情里浏览整个存储,下载任意文件或目录,并在两个区域里放文件(ADR 0053):

  • 可写区域只有两个:files/(通用区,离线数据集、tokenizer、prompt 集之类放这里)和 .gpuworks/apps/(应用的数据目录)。 上传、新建目录、改名、删除只能在这两个目录之下进行,files 与 .gpuworks/apps 本身不能删除或改名;它们不存在时第一次写入会自动创建。 模型文件目录和 .gpuworks/ 的其余部分只读,模型文件仍只由模型管理改动。存储停用时整个存储只读,但仍可浏览和下载。
  • 节点:本地存储在每台节点上是各自的目录,先选节点再浏览;共享存储(NFS、NFS 加本地缓存、共享目录)由平台挑一台在线、 已就绪、数据通道已连接的节点代办。NFS 加本地缓存浏览的是 NFS 本身,不是节点缓存。节点上的 agent 需要升级到支持存储文件的版本。
  • 上传:一个文件一次请求,浏览器边读边传,平台不落盘。可选「上传后解压」(tar、tar.gz、zip):拒绝绝对路径、..、 符号链接、硬链接与设备文件,解压后的总大小与条目数有上限。文件先写到 .gpuworks/incoming/ 下的暂存位置,完整收到(并解压完)后才原子改名到目标, 中途失败或取消不会在目标处留下半个文件。不支持分块续传:中断后要重新上传整个文件。
  • 经 Cloudflare 等反向代理传大文件不支持:这类代理对请求体大小有上限(Cloudflare 免费与 Pro 套餐为 100 MB),超过时上传会被代理直接拒绝。 需要上传大文件时直连 gpuworks 的地址,或先把文件放到节点上再从那里拷进存储。
  • 下载:文件原样下载;目录边打包边传,默认 .zip,可选 .tar.gz,包内以目录名为顶层目录。符号链接不跟随:被跳过的链接列在包内 SKIPPED_SYMLINKS.txt 里。目录下载事先不知道总大小,浏览器只显示已下载量;中途出错时浏览器只显示「下载失败」。
  • 删除先把文件移进存储的回收目录,字节在后台删除,与删除模型文件相同。

停用

任何存储都可以停用。停用表示只读:不再下载、复制进来或删除模型文件(部署触发的下载同样被挡),已有的模型文件照常可以部署。 对于「NFS 加本地缓存」,停用保护的是 NFS 模型库;节点本地缓存仍可填充、清理和按容量策略整理。这同样适用于手动停用的存储,正在使用、传输中或缺少 NFS 源副本的缓存仍受保护。 镜像不在存储里(它们在各节点的容器运行时里),停用存储不影响镜像同步。

注意

  • NFS 掉线:hard 挂载下,已经加载完权重的实例通常能继续服务;重启、L2 唤醒要重新读权重,会卡住或失败。 需要不依赖 NFS 的部署请用「NFS 加本地缓存」。
  • 启动前检查:agent 创建容器前会检查模型目录是否存在(2 秒时限),不存在就以 MODEL_PATH_UNAVAILABLE 失败, 不会让引擎在空目录上启动。
  • 节点模型根目录已并入本地存储:要换盘,给本地存储改路径或添加一个新的本地存储,不再在节点上单独设置。

这篇文档有帮助吗?