在國內使用 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：實際復制文件而非軟鏈接。