跳转到正文

下载、缓存和节点间同步模型

本文目录

本文说明怎样登记模型、下载到指定存储,或采用节点已有的文件,使模型可以用于部署。

适用场景:从 Hugging Face、ModelScope 获取模型,登记离线目录,或复用其他节点已有的模型。HTTP 目录来源见从 HTTP 目录导入,节点间复制见同步模型和镜像。

前置条件:

  • 下载、登记节点路径或节点间复制时,相关节点在线,见接入节点。仅登记公网模型来源不要求已有目标节点。
  • 公网下载:节点能访问所选来源(Hugging Face 或 ModelScope),或在设置 → 镜像与模型拉取里为它配置了代理、站点规则(镜像站、内网代理),见配置镜像与模型拉取。
  • 节点间同步:至少有一台在线节点持有完整副本,并且两端网络可直连(自动复制还要求同在一个同步组),完整前置条件见在节点之间同步模型和镜像。

登记并下载模型

  1. 打开模型页,点击注册模型,选择 Hugging Face 或 ModelScope,填写来源 ID,例如 Qwen/Qwen3-8B。
  2. 需要指定版本时,在高级选项里填写版本指定;留空先解析平台默认分支,取得 commit 时会固定到该 commit,ModelScope 的 main 会归一为 master。点击确认注册,在列表中核对来源与实际版本。
  3. 在模型行点击下载到…,选择可写存储。本地存储还需选择在线目标节点,每台各下载一份;共享存储只下载一次,需选择一台可写的在线节点执行;节点必须能访问所选模型来源。更换正在执行下载的节点前,先取消当前下载,再选择新节点重新下载。
  4. 点击下载,在模型详情查看目标存储或节点的进度。目标副本显示 present 后,才能作为完整的下载副本使用;下载失败时先查看原因,再重试。

登记 Hugging Face / ModelScope 模型时,元数据读取失败可能只产生提示,并不等于权重已经下载。下载到…明确从登记来源下载;要利用其他节点的完整文件,使用复制到…。

在模型详情的存储或节点行中,进行中的公网下载可点击取消下载。取消后状态显示为 canceled,已下载的数据会保留,重新下载时可以续传。删除或停止推理服务会取消该服务发起、且其他活动服务不再使用的下载;模型页单独发起的下载会继续。节点离线时取消意图会保存,节点重连后执行;更换共享下载节点前,原节点必须确认已经停止写入。

下载支持续传、多连接和限速;所有文件存在、大小匹配且目录结构有效后才报告 present。 下载没有任务级截止时间。单个 HTTP 请求最长 15 分钟,超时后尝试从已下载的部分续传;重试次数和换址条件如下。

下载先尝试适用站点规则的替代地址,再尝试规则允许的原站点。获取文件列表时,地址不可达、HTTP 错误或列表无法解析会使当前地址冷却 30 分钟,并尝试下一个候选;源站限流(429、503)则与下载文件一样在原地址等待重试。

下载具体文件时,按失败类型处理:

  • 同地址重试:连接被拒绝或重置、TLS 握手超时、EOF 等可重试传输错误,以及源站限流(429、503),先在原地址尝试。限流时按应答里的 Retry-After 或 RateLimit 头给出的重置时间等待(RateLimit 的重置时间再多等 1 秒,免得重试恰好早于重置;至少按退避间隔,最多 5 分 1 秒,即一个限流窗口加这 1 秒),等待期间进度里显示「rate limited by the source」;限流的等待计入下面的尝试次数,最坏情况下一个文件在最后一个地址上可能等待约 75 分钟。后面还有候选时,每文件在该地址最多尝试 6 次;最后一个地址最多 16 次,均含首次。次数耗尽仍失败才冷却并切换;没有下一个候选时结束。
  • 立即切换:其他 HTTP 状态码错误(包括 404、401/403)或 TLS 证书验证失败等不可重试的来源错误,不在原地址重试,直接冷却 30 分钟并切换候选。
  • 连续卡住:连续 5 分钟没有响应头或新数据会切断请求并尝试续传。同一地址连续发生两次且还有候选时,冷却并切换;最后一个地址不再切换,仍受 16 次总尝试上限约束。
  • 换地址续传:版本固定为 commit 时,换地址可以接着续传;分支版本换地址时从头开始。源站不支持 Range 时,续传也会从头下载。

进度显示当前下载站点,切换地址时附原因。

完整规则见节点怎样依次尝试。

HTTP 目录来源只从自己的目录下载,不受站点规则改写,但会经节点代理。

登记节点已有目录

先按模型是否已经登记选择入口:

情况操作
平台还没有这个模型注册模型 → 计算节点本地路径,选择节点、填写目录,点击解析预览,确认模型信息后注册
已登记了模型来源,要为它补一份本地副本在该模型的操作中选择登记计算节点已有路径,选择节点并填写目录;不要另建一个无关模型

填写节点宿主机上的绝对目录路径;有多个本地存储时选择归属存储。路径可以在存储根目录之外,登记不会复制或移动文件。完成后在模型详情确认节点、路径和可用状态;registered(已登记)已经可用,无需等待它变成 present。

部署评估提示模型磁盘不足时,先核对提示中的节点、存储、目标目录和所需/可用空间。若该节点已有这份权重,可从提示进入当前模型详情,选择登记计算节点已有路径,登记后重新评估。平台按已登记的副本判断是否需要新增空间,磁盘上未登记的其他目录不会自动成为可用副本;请为部署实际使用的模型登记,避免另建同名模型后仍引用原来源。

模型副本下载或复制遇到磁盘不足时,详情会保留原始错误中的目录和容量信息。容器运行时磁盘不足需要处理镜像和容器所在的文件系统,登记模型目录不会解决这类空间不足。

节点会检查目录可读、有非空文件且没有未完成下载。缺失、空目录或包含未完成的 .part 文件时登记失败,已有登记保持原样;同名文件已完整(大小等于 .part.state 记录的大小)时,旁边的 .part / .part.state 视为残留,不影响登记。已识别为组件、多模型目录,或文件缺失、无法验证的模型入口也会被拒绝;所选目录必须通过元数据识别出恰好一个完整模型入口;父目录、非模型目录和未知布局会被拒绝。“已登记”不保证所选引擎能加载它。识别范围见导入已有的模型库,请求和状态码见 API 契约。

登记路径还会用该目录补齐模型缺失的元数据(config、README、大小),已有的元数据不覆盖。目录是用 huggingface-cli download --local-dir 下载的、.cache/huggingface/download/*.metadata 全部指向同一个 commit,并且这是该模型唯一的一份副本时,模型会固定到这个 commit。这是离线导入的做法,见离线导入模型。

本地目录或 HTTP 目录登记的模型,来源 ID 默认取目录名,可能和推理模板声明的仓库 ID(如 Qwen/Qwen3-0.6B)对不上,模板就认不出这个模型。在模型详情的来源 ID 旁点击编辑,改成仓库 ID 即可;Hugging Face / ModelScope 模型的来源 ID 就是仓库本身,不能修改,需要的话重新登记。已有副本的路径不变,之后新复制或下载的副本按新的来源 ID 命名目录;模型有进行中的复制、下载或删除,或者已有模型用了同一个来源 ID 时,修改会被拒绝。API 为 PATCH /api/v1/models/{id}。

部署时怎么取到模型和镜像

部署时确认两项:

  • 权重来源——模板声明了多个来源时,选运行 Hugging Face 还是 ModelScope 的权重,模板建议的那家预选。
  • 保存到——节点需要取模型时保存到哪个存储;已经有该模型的存储显示为已持有,不会重复下载。共享存储和限定读取存储的区别见部署时选存储。

每台节点在副本启动时自己决定怎么拿到模型:

  • 节点本地或它能读到的共享存储里已有完整副本,直接使用;
  • 同一同步组里有在线节点持有,就从它复制;
  • 否则按所选来源下载,下载地址受站点规则与节点代理影响;规则把所有候选都禁止时,部署的调度原因是 weights_fetch_forbidden,下载接口返回 409 WEIGHTS_FETCH_FORBIDDEN。

自动调度尚未选出节点时,页面提示“镜像和模型在调度后按拉取设置自动获取”。自动调度已选出节点,或手动放置、多机部署指定了节点时,逐节点显示预估:已有、从哪个节点复制、按什么顺序拉取镜像或下载模型。这是按当前状态算出的预估,节点启动时会重新判断。

“本地已有”按模型身份判定而非下载源:同 repo 且 revision 相同,或跨源 revision 不同但权重 字节、架构与上下文长度一致。

镜像走同一套判断:本地已有时直接使用;同步组内的其他在线节点已有时复制;否则按候选依次拉取,候选来自镜像的等价副本 (模板自己声明的 image_sources、镜像目录登记的来源、镜像自身的地址)和适用于该节点的来源规则,见 配置镜像拉取。模板声明的来源见 模板语法,使用它们不算偏离模板。 已缓存的镜像不再占用调度的运行时磁盘估算。

节点间同步

在模型页用复制到…选择完整来源、目标存储和节点,然后开始复制;镜像的同步弹窗需先完成测试直连。两者的手动操作都不受同步组限制,可单独限速。节点间传输由源、目标直连,server 不中转文件;共享存储复制则由平台选择可读取来源并写入目标的节点执行。

公网下载失败后,仍可从在线节点的完整副本复制。分别的操作、网络要求及恢复方式见在节点之间同步模型和镜像。

节点间同步失败后可重试,进行中的同步可取消;不要把部分文件登记为完整副本。删除节点本地副本需要管理员权限,API 为 DELETE /api/v1/models/{id}/nodes/{uuid},活动部署使用中的模型会返回 409。

这篇文档有帮助吗?