在国内使用 Hugging Face 下载模型时，经常遇到连接慢、断点续传失败等问题。本文记录一个稳定、快速下载模型的命令行脚本，并支持设置模型缓存路径和目标目录，方便后续统一管理。

---

1. 设置 Hugging Face 镜像站

为了提升国内访问速度，我们可以使用 Hugging Face 镜像站（hf-mirror）作为代理：

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

2. 设置自定义模型缓存目录

默认情况下，Hugging Face 会将所有模型缓存到 ~/.cache/huggingface/，这可能会迅速占满主盘空间。
我们可以通过设置环境变量 HF_HOME，将缓存目录更换到数据盘或其他大容量路径：

export HF_HOME=/data/models/hf_cache

3. 使用 huggingface-cli 下载模型到指定目录

以下载 OpenFLUX.1 模型 为例，bash脚本命令如下：

huggingface-cli download \ostris/OpenFLUX.1 \--local-dir /data/models/OpenFLUX.1 \--local-dir-use-symlinks False \--resume-download

参数说明：
• --local-dir：指定模型下载完成后的保存目录；
• --local-dir-use-symlinks False：避免只建立符号链接，而是实际复制文件；
• --resume-download：支持断点续传，适合下载大模型。

4. 文件下载路径结构说明

下载完成后，模型会被复制到你设置的目标目录，例如：

/data/models/OpenFLUX.1/
├── config.json
├── model.safetensors
├── tokenizer.json
└── …

而 Hugging Face 实际的下载缓存，会被保存在你设置的 HF_HOME 路径下，例如：

⚠️ 注意：Hugging Face 会先将文件下载到缓存目录，再复制到 --local-dir，所以缓存路径仍然很关键。

5. 注意事项

• Hugging Face CLI 会先将模型缓存到 HF_HOME 路径（或默认的 ~/.cache/huggingface/），然后才复制到 --local-dir；
• 如果不设置 HF_HOME，模型缓存会默认存储在系统盘，可能导致磁盘空间告急；
• 推荐使用数据盘或大容量路径来设置缓存目录，便于集中管理；
• 如果需要更灵活地控制下载行为，也可以使用 Python 代码中的 snapshot_download() 方法。

---

附：推荐完整脚本

export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/data/models/hf_cachehuggingface-cli download \ostris/OpenFLUX.1 \--local-dir /data/models/OpenFLUX.1 \--local-dir-use-symlinks False \--resume-download

执行以上脚本，即可稳定快速地将大模型下载到指定目录并支持断点续传。

6. 使用 Python 的 snapshot_download 下载模型

如果你想在 Python 脚本中下载模型，而不是用命令行，也可以使用 Hugging Face 提供的 snapshot_download() 方法，功能更灵活。

首先安装依赖（如果还没有的话）：

pip install huggingface_hub

然后使用如下代码进行下载：

from huggingface_hub import snapshot_downloadsnapshot_download(repo_id="ostris/OpenFLUX.1",local_dir="/data/models/OpenFLUX.1",local_dir_use_symlinks=False,resume_download=True,cache_dir="/data/models/hf_cache",  # 等价于设置 HF_HOMEendpoint="https://hf-mirror.com"  # 镜像加速
)

• repo_id：模型名称，格式为 <作者>/<模型名>；
• local_dir：模型保存目录；
• cache_dir：缓存目录（等价于环境变量 HF_HOME）；
• endpoint：镜像站地址（等价于环境变量 HF_ENDPOINT）；
• resume_download：支持断点续传；
• local_dir_use_symlinks=False：实际复制文件而非软链接。