通过镜像站下载模型到云主机

🦄

本文面向在共绩算力云主机上部署开源模型的开发者，介绍如何借助 Hugging Face 镜像站，将模型权重直接拉取到云主机的指定目录，便于后续推理、微调或打包为自定义镜像。

示例模型：Tongyi-MAI/Z-Image-Turbo —— 通义 MAI 团队开源的高性能文生图 Turbo 模型，单卡 16G 显存即可运行，非常适合在共绩 RTX 4090 / L20 / H20 等卡型上快速体验。

加速镜像：<https://hf-mirror.com&gt;（第三方公益节点，不承诺 100% 可用、不保证带宽、不保证长期稳定运行）

适用场景

• 云主机实例在国内网络环境下直连 Hugging Face 速度慢或失败
• 需要把模型权重下载到云主机的固定目录（本地盘或共享存储卷），供后续本地加载
• 需要在下载完成后把整套环境打包成自定义镜像，用于弹性部署服务一键启动

前置准备

1. 启动一台云主机实例

在共绩控制台创建云主机实例，镜像可选官方 PyTorch 基础镜像或任意预装 Python 环境的镜像。实例启动后通过浏览器 Console 或 SSH 进入调试终端。

2. 规划模型存放目录

建议提前规划模型权重的落盘路径，避免散落在系统盘。常见两种选择：

• 本地盘（一次性调试）：直接放在实例本地目录，例如 /root/models/。实例销毁后数据会丢失。
• 共享存储卷（推荐用于长期复用）：挂载共绩的共享存储卷（PVC），例如 /mnt/shared/models/。多个实例、弹性部署服务可共用同一份权重，避免反复下载。共享存储卷的挂载方式参考 云主机中使用共享存储卷。

本文后续示例统一使用 /root/models/Z-Image-Turbo，实际使用时按需替换。

mkdir -p /root/models
cd /root/models

3. 获取并配置 Hugging Face Token（重要）

虽然 Z-Image-Turbo 是完全公开的模型，但强烈建议始终配置 HF Token 再发起下载，原因：

• 未登录状态下匿名下载有较低的速率上限，容易在大模型仓库触发限流
• 后续一旦需要下载 gated（需申请访问）或 private 模型（如 Llama、Gemma 系列），流程完全一致，不必临时改脚本
• Token 对镜像站同样有效，不会因为切换镜像失效

Token 获取地址：<https://huggingface.co/settings/tokens>

创建 Token 时选择 Read 权限即可。拿到形如 hf_xxxxxxxxxxxxxxxxxxxxxxxx 的字符串后，在终端中通过环境变量注入：

export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxx"

⚠️ Token 属于敏感凭证，不要硬编码在脚本、Dockerfile 或打包成的自定义镜像中，推荐每次在终端临时 export，或写入 ~/.bashrc 个人环境。若需在弹性部署服务中使用，通过环境变量在部署配置中单独注入。

核心流程：下载 Z-Image-Turbo

步骤 1：安装 huggingface_hub

pip install -U huggingface_hub

安装完成后验证命令可用：

hf --version

步骤 2：设置镜像站与 Token 环境变量

export HF_ENDPOINT="https://hf-mirror.com"
export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxx"
export HF_HUB_DOWNLOAD_TIMEOUT=30

三个变量的作用：

• HF_ENDPOINT：把默认请求转向镜像站
• HF_TOKEN：随请求携带身份，提高速率上限并解锁受限仓库
• HF_HUB_DOWNLOAD_TIMEOUT：网络波动时延长单次分片超时，降低中断概率

步骤 3：执行下载命令

hf download Tongyi-MAI/Z-Image-Turbo \
  --local-dir /root/models/Z-Image-Turbo

命令含义：

• Tongyi-MAI/Z-Image-Turbo：Hugging Face 上的仓库 ID，格式为 作者/仓库名
• --local-dir：指定权重落盘目录，hf 工具会把仓库内的所有文件完整镜像到该路径

下载过程支持断点续传，如果中途网络中断，重新执行同一条命令即可继续。

步骤 4：验证下载结果

ls -lh /root/models/Z-Image-Turbo
du -sh /root/models/Z-Image-Turbo

正常情况下可以看到 model_index.json、各子目录（transformer/、vae/、text_encoder/ 等）以及若干 .safetensors 权重文件，总大小约 12 GB 左右。

进阶用法

仅下载部分文件

如果只需要特定子模块（例如只要 transformer 权重），可用 --include 精确指定：

hf download Tongyi-MAI/Z-Image-Turbo \
  --include "transformer/*" "model_index.json" \
  --local-dir /root/models/Z-Image-Turbo

反之，可用 --exclude 过滤掉不需要的文件（如 .bin 或 ONNX 子目录）：

hf download Tongyi-MAI/Z-Image-Turbo \
  --exclude "*.bin" "onnx/*" \
  --local-dir /root/models/Z-Image-Turbo

使用 hfd 提升大模型下载速度

对于几十 GB 以上的仓库，推荐使用多线程下载脚本 hfd，并发数更高、稳定性更好。详细用法参考 Hugging Face 加速配置指南 中的「hfd + 多线程下载工具加速」章节：

wget -O hfd.sh https://hf-cdn.sufy.com/hfd/hfd.sh
chmod +x hfd.sh
mv hfd.sh /usr/local/bin/hfd

export HF_ENDPOINT="https://hf-mirror.com"

hfd Tongyi-MAI/Z-Image-Turbo \
  --hf_token $HF_TOKEN \
  --local-dir /root/models/Z-Image-Turbo \
  -x 4 -j 3

-x 4 表示每个文件 4 线程分片，-j 3 表示同时下载 3 个文件。

后台下载，避免 SSH 断开中断

大模型下载耗时较长，通过 SSH 执行时建议使用 nohup 或 screen 防止会话断开导致任务终止：

nohup hf download Tongyi-MAI/Z-Image-Turbo \
  --local-dir /root/models/Z-Image-Turbo \
  > /root/models/download.log 2>&1 &

查看进度：

tail -f /root/models/download.log

更系统的后台托管方案参考 [守护进程（开后台）](https://www.gongjiyun.com/docs/cloud-hosting/best-practice/wyp7wfifcixzwfkhfkdc4mlxnrq/。

配合弹性部署：下载一次，多处复用

弹性部署服务不支持直接提供命令行终端，无法在部署实例内现场下载模型。推荐流程：

1. 在云主机中按上述步骤把 Z-Image-Turbo 下载到共享存储卷（例如 /mnt/shared/models/Z-Image-Turbo）。
2. 编写推理服务代码，通过本地路径加载模型（而非仓库 ID），例如：

pipe = ZImagePipeline.from_pretrained( “/mnt/shared/models/Z-Image-Turbo”, torch_dtype=torch.bfloat16, low_cpu_mem_usage=False, )

3. 将包含代码和依赖的云主机环境打包为自定义镜像。
4. 在弹性部署服务中使用该自定义镜像，同时挂载同一份共享存储卷，服务即可开箱加载权重，无需冷启动时再下载。

这样既节省冷启动时间，也避免多实例重复占用存储与带宽。



## 常见问题



<b>Q：下载提示 `401 Unauthorized` 或 `403 Forbidden`？</b>
A：Token 未配置或权限不足。确认 `HF_TOKEN` 已 `export`，且 Token 在 Hugging Face 账号下为 `Read` 及以上权限；若是 gated 模型，需先到仓库页面点击申请并等待通过。

<b>Q：下载一半卡住不动？</b>
A：镜像站节点负载波动所致。按 `Ctrl+C` 中断后重新执行同一条命令，`hf` 工具会自动断点续传。必要时调大 `HF_HUB_DOWNLOAD_TIMEOUT`。

<b>Q：磁盘空间不够？</b>
A：云主机系统盘容量有限，大模型务必下载到共享存储卷或数据盘。下载前先用 `df -h` 确认目标目录所在磁盘的剩余空间大于模型体积的 1.2 倍。

<b>Q：能否跳过镜像站直连？</b>
A：可以，将 `HF_ENDPOINT` 设回默认值即可：

```text
unset HF_ENDPOINT

注意事项

• 镜像站为第三方公益服务，稳定性取决于节点状态，不适合作为生产环境的强依赖
• 不要把 HF_TOKEN 硬编码到脚本、Dockerfile 或打包的自定义镜像中，始终通过环境变量注入
• 大模型下载过程中可能出现中断，重复执行命令即可续传
• 不建议在长期脚本或 CI/CD 中硬编码镜像地址，建议通过环境变量统一管理，便于后续替换
• 仅用于学术研究与个人学习用途，请勿用于商业用途或任何违法用途

祝模型下载与部署顺利～