官網： https://hf-mirror.com/
網站域名 hf-mirror.com，用于鏡像 huggingface.co 域名。作為一個公益項目，致力于幫助國內AI開發者快速、穩定的下載模型、數據集。

---

如何使用HF-Mirror

方法一：網頁下載

在https://hf-mirror.com/搜索，并在模型主頁的Files and Version中下載文件

方法二：huggingface-cli

huggingface-cli 是 Hugging Face 官方提供的命令行工具，自帶完善的下載功能。

1. 安裝依賴

pip install -U huggingface_hub

注意：huggingface_hub 依賴于 Python>=3.8，此外需要安裝 0.17.0 及以上的版本，推薦0.19.0+。

2. 設置環境變量

Linux

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

Windows Powershell

$env:HF_ENDPOINT = "https://hf-mirror.com"

建議將上面這一行寫入 ~/.bashrc。

3.1 下載模型

huggingface-cli download --resume-download gpt2 --local-dir gpt2

3.2 下載數據集

huggingface-cli download --repo-type dataset --resume-download wikitext --local-dir wikitext

值得注意的是，有個--local-dir-use-symlinks False 參數可選，因為huggingface的工具鏈默認會使用符號鏈接來存儲下載的文件，導致--local-dir指定的目錄中都是一些“鏈接文件”，真實模型則存儲在~/.cache/huggingface下，如果不喜歡這個可以用 --local-dir-use-symlinks False取消這個邏輯。

方法三：使用 hfd （推薦）

hfd 是https://hf-mirror.com/開發的 huggingface 專用下載工具，基于成熟工具 git+aria2，可以做到穩定下載不斷線。

1. 下載hfd

wget https://hf-mirror.com/hfd/hfd.sh
chmod a+x hfd.sh

2. 設置環境變量

HF_ENDPOINT 該變量是 HF 相關庫官方支持的一個環境變量，設置后，相關庫會尊重該變量指定的主機名，替換 huggingface.co 域名進行模型、數據集的下載和上傳，從而做到無需修改python的transformers代碼，即可利用上鏡像站來加載模型。具體支持以下庫：

• huggingface-cli
• snapshot_download
• from_pretrained
• hf_hub_download
• timm.create_model

Linux

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

Linux 寫入到~/.bashrc中：

echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.bashrc

Windows Powershell

$env:HF_ENDPOINT = "https://hf-mirror.com"

Windows 寫入到 ~\Documents\WindowsPowerShellMicrosoft.PowerShell_profile.ps1 中：

Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://hf-mirror.com"'

Python

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

3.1 下載模型（例子： gpt2）

./hfd.sh gpt2 --tool aria2c -x 4

3.2 下載數據集 (例子： wikitext )

./hfd.sh wikitext --dataset --tool aria2c -x 4

方法四：使用環境變量（非侵入式）

非侵入式，能解決大部分情況。huggingface 工具鏈會獲取HF_ENDPOINT環境變量來確定下載文件所用的網址，所以可以使用通過設置變量來解決。

HF_ENDPOINT=https://hf-mirror.com python your_script.py

不過有些數據集有內置的下載腳本，那就需要手動改一下腳本內的地址來實現了。

---

補充：
如何快速下載huggingface模型——全方法總結
stackoverflow：how-to-download-a-model-from-huggingface

常見錯誤問答

0, 有些項目需要登錄，如何下載？

部分 Gated Repo 需登錄申請許可。為保障賬號安全，本站不支持登錄，需先前往 Hugging Face 官網登錄、申請許可，在官網這里獲取 Access Token 后回鏡像站用命令行下載。

部分工具下載 Gated Repo 的方法：

huggingface-cli： 添加–token參數

huggingface-cli download --token hf_*** --resume-download meta-llama/Llama-2-7b-hf --local-dir Llama-2-7b-hf

hfd： 添加–hf_username–hf_token參數

hfd meta-llama/Llama-2-7b --hf_username YOUR_HF_USERNAME --hf_token hf_***

其余如from_pretrained、wget、curl如何設置認證 token，詳見上面第一段提到的教程。

1, huggingface-cli: error: invalid choice: ‘download’

版本問題。huggingface-hub>=0.17.0 && Python>=3.8。

huggingface-cli 需安裝 0.17.0 及以上的版本才支持download子命令，但如果你pip顯示的可安裝的最新版本都低于0.17.0，可能是你的Python版本沒有達到huggingface_hub要求的3.8+的要求。

2, Error downloading … https://cdn-lfs.huggingface.co/xxx…

報錯中有出現http://huggingface.co這個域名的，多半是因為沒有正確設置鏡像斷點環境變量，導致走的仍然是hf官方服務器出現的網絡錯誤。請正確設置 HF_ENDPOINT

3, 429 Client Error: Too Many Requests

網站訪問量過大，達到速率上限，過五分鐘會重置限制。