HuggingFace模型下载全攻略：多种方法任你选

关注 GPUStack，一起探索 AI、GPU 管理与大模型技术的实践之旅。在 AI 开发、测试及模型推理过程中，Hugging Face 成为了一个不可或缺的资源库。从官方到第三方，提供了众多下载模型的方法，让人应接不暇。本文将为您详细解析这些方法，包括镜像加速功能，助您根据实际需求灵活选择。

Hugging Face 提供了多种下载模型的方式，如命令行的 huggingface-cli 和 snapshot_download，Python 脚本的 hf_hub_download，以及 Git 克隆和 Bash 脚本等。接下来，我们将逐一介绍这些方法的使用指令和适用场景。

首先，确保您已准备好使用这些官方下载方法。这些方法都依赖于 huggingface_hub 库，因此您需要先安装该库。

使用 Conda 创建 Python 虚拟环境，并激活后，执行以下命令进行安装：

conda create -n huggingface python=12 -yconda activate huggingfacepip install -U huggingface_hub

安装完成后，您就可以根据需要选择相应的下载方法了。无论是命令行的便捷操作，还是 Python 脚本的强大功能，亦或是 Git 克隆的灵活性，都能满足您的需求。同时，不要忘了镜像加速功能，它能在一定程度上提升下载速度。 huggingface-cli 是 Hugging Face 提供的命令行工具，其 download 指令支持多线程下载，默认使用8线程，并封装了 hf_hub_download 和 snapshot_download 方法，使得操作简单易懂，非常适合日常使用。

要下载 Qwen/Qwen5-5B-Instruct 模型库，只需在命令行中输入：

huggingface-cli download Qwen/Qwen5-5B-Instruct

需要注意的是，由于 Hugging Face 的访问可能受到某些上网条件的影响，你可以选择设置镜像源进行下载，例如：

export HF_ENDPOINT=https://hf-mirror.comhuggingface-cli download Qwen/Qwen5-5B-Instruct

下载完成后，模型默认会存放在 ~/.cache/huggingface/hub/ 目录下，你可以通过以下命令查看下载的模型：

ll ~/.cache/huggingface/hub/models--Qwen--Qwen5-5B-Instruct/snapshots/7ae557604adf67be50417f59c2c2f167def9a775 Hugging Face 采用了 Cache 系统来有序管理下载的模型，但其默认的文件存储结构可能不够直观。为提升使用体验，推荐利用 --local-dir 参数来指定自定义的下载路径。例如，若你希望下载 Qwen/Qwen5-5B-Instruct 模型库中的特定文件，如 qwen5-5b-instruct-q4_gguf 和 qwen5-5b-instruct-q8_gguf，你可以通过以下命令将它们下载到当前目录：```bashhuggingface-cli download Qwen/Qwen5-5B-Instruct qwen5-5b-instruct-q4_gguf qwen5-5b-instruct-q8_gguf --local-dir .

此外，huggingface-cli 还提供了 --include 和 --exclude 参数，允许你通过正则表达式来匹配或排除某些特定文件。例如，若你只想下载 Qwen/Qwen5-5B-Instruct-GGUF 仓库中除 fp16 精度模型文件外的所有内容，可以执行以下命令：

huggingface-cli download Qwen/Qwen5-5B-Instruct-GGUF --exclude "fp16.gguf" --local-dir .

需要注意的是，某些需要特殊授权才能访问的模型（通常被称为 Gated model），如下例中的 meta-llama/Llama-2-3B-Instruct，在下载前需要在 Hugging Face 平台上提交申请并确认获得授权。 接着，在 HuggingFace 平台的右上角，点击头像并选择“Access Tokens”来创建一个具有“Read”权限的Token。创建完成后，请务必妥善保存该Token。 现在，您可以开始下载meta-llama/Llama-2-3B-Instruct模型。在下载时，请使用之前创建的访问Token进行指定，以确保顺利下载。

使用huggingface-cli进行下载的命令如下：

huggingface-cli download meta-llama/Llama-2-3B-Instruct --local-dir . --token hf_abcdefghijklmnopqrstuvwxyz

如果您希望更便捷地使用Token，可以选择提前通过huggingface-cli login命令进行登录，这样在后续操作中就不必显式指定Token。

另外，如果您希望利用Hugging Face提供的加速库hf_transfer来提升下载速度（请注意，该加速库在高带宽条件下可能更为有效，但鲁棒性有待商榷），您可以通过以下步骤进行安装和使用：

首先，安装hf_transfer库：

pip install "huggingface_hub[hf_transfer]"

然后，在命令行中设置环境变量HF_HUB_ENABLE_HF_TRANSFER为1，并再次执行下载命令：

HF_HUB_ENABLE_HF_TRANSFER=1 huggingface-cli download Qwen/Qwen5-5B-Instruct-GGUF qwen5-5b-instruct-q8_gguf --local-dir .

请注意，使用加速库时可能存在一定的风险，请根据实际情况谨慎选择。 hf_hub_download是huggingface_hub库中的一个方法，专为下载模型库中的单个文件而设计，但并不支持多线程下载，因此使用场景相对有限。 在日常使用中，我们更推荐使用huggingface-cli。这个方法主要在Python项目中集成使用。

若要在Python交互式环境中使用hf_hub_download来下载Qwen/Qwen5-5B-Instruct-GGUF模型库的qwen5-5b-instruct-fpgguf文件，你可以按照以下步骤操作：

首先，进入Python交互式环境：

python

接着，通过以下Python脚本进行下载：

from huggingface_hub import hf_hub_downloadREPO_ID = "Qwen/Qwen5-5B-Instruct-GGUF"FILENAME = "qwen5-5b-instruct-fpgguf"model_path = hf_hub_download(repo_id=REPO_ID, filename=FILENAME)print(model_path)

默认情况下，模型将被下载到~/.cache/huggingface/hub/路径下。例如，你可以使用ll ~/.cache/huggingface/hub/models--Qwen--Qwen5-5B-Instruct-GGUF/snapshots/9217f5db79a29953eb74d5343926648285ec7e67/qwen5-5b-instruct-fpgguf来查看下载的文件。

有关hf_hub_download的更多可用参数，请参考Hugging Face的官方文档：https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.hf_hub_download。 同样支持从镜像源下载。例如，你可以通过设置HF_ENDPOINT环境变量为https://hf-mirror.com来指定使用镜像源。

在下载Gated model时，需要使用token参数，其值可以为True或实际Token。当token设为True时，将从本地Hugging Face配置中读取Token，这需要你提前通过huggingface-cli login命令提供。此外，还支持使用local_dir参数来指定下载目录。

例如，你可以这样下载模型：

from huggingface_hub import hf_hub_downloadmodel = hf_hub_download( repo_id="mistralai/Pixtral-12B-2409", filename="consolidated.safetensors", local_dir="./", token=True # 或提供实际Token)

或者，你可以先通过login方法提供认证Token，然后再进行下载：

from huggingface_hub import login, hf_hub_downloadHF_TOKEN = "hf_abcdefghijklmnopqrstuvwxyz" # 你的实际Tokenlogin(token=HF_TOKEN)model = hf_hub_download( repo_id="mistralai/Pixtral-12B-2409", filename="consolidated.safetensors", local_dir="./") snapshot_download是huggingface_hub库中的另一大功能，与hf_hub_download有所不同。它专为下载整个模型库而设计，并支持多线程下载（默认8线程，即1线程下载1文件）。这一特性使其在Python项目集成中尤为适用。在Python交互式环境中，你可以通过以下脚本轻松下载Qwen/Qwen5-5B-Instruct模型库：```pythonfrom huggingface_hub import snapshot_downloadmodel = snapshot_download(repo_id="Qwen/Qwen5-5B-Instruct")

默认情况下，模型将被下载至~/.cache/huggingface/hub/路径下。此外，snapshot_download还提供了丰富的参数选项，以满足不同的下载需求。

同样地，snapshot_download也支持从镜像源下载，你只需设置HF_ENDPOINT环境变量为镜像源地址即可。对于需要认证的Gated model下载，其认证方法与hf_hub_download一致，并支持allow_patterns和ignore_patterns参数，其中ignore_patterns的优先级高于allow_patterns，可结合使用。 login(token=HF_TOKEN)

model = snapshot_download( repo_id="mistralai/Ministral-8B-Instruct-2410", allow_patterns="*.safetensors", ignore_patterns="consolidated.safetensors", local_dir="./" )

Hugging Face上的所有模型库都采用Git存储库的形式进行管理，因此，使用git命令也可以实现模型的下载。但需要注意的是，git方式虽然简单直接，却不支持断点续传和多线程下载，因此在下载大型模型时可能效率较低。此外，如果不借助huggingface_hub库，git方式可能更适合临时下载小模型的场景。

在下载前，需要先安装Git LFS以管理大文件的下载。在macOS上，可以通过brew install git-lfs进行安装；而在Ubuntu上，则可以使用sudo apt update && sudo apt install git-lfs -y进行安装。安装完成后，通过git lfs install命令进行初始化。

克隆模型库时，可以使用git clone命令并指定仓库地址。对于需要认证的Gated model，需要在克隆时提供之前创建的Token。此外，还可以选择使用SSH协议进行更安全和自动化的克隆操作，但需要将SSH公钥添加到Hugging Face平台。 将本地环境的SSH公钥添加到HuggingFace平台，可以通过以下步骤完成：首先，查看或生成本地环境的SSH公钥。如果没有公钥，可以使用ssh-keygen -t rsa -b 4096命令生成一个。然后，在终端中输入cat ~/.ssh/id_rsa.pub查看公钥内容。

接下来，在HuggingFace平台的右上角点击头像，选择Settings - SSH and GPG Keys，将上述查看到的公钥添加到平台中，以便后续下载模型时的认证。

添加完成后，可以测试SSH连接是否能够成功连接到HuggingFace平台，输入ssh -T git@hf.co进行测试。

现在，你可以使用git命令克隆模型库了。例如，要克隆名为Qwen/Qwen5-3B-Instruct的模型库，可以输入git clone git@hf.co:Qwen/Qwen5-3B-Instruct。对于需要认证的Gated model，Git会自动使用你本地存储的SSH私钥进行认证，前提是你的公钥已经成功添加到HuggingFace平台。

另外，hfd是一个由https://hf-mirror.com/的作者开发的Hugging Face下载工具。它支持基于git + aria2或git + wget的下载方式，默认使用aria2进行多线程下载。如果你经常需要下载模型或下载大型模型，推荐使用hfd工具。在使用hfd之前，你需要先安装aria2依赖。在macOS上，可以通过brew install aria2进行安装；而在Ubuntu上，则可以使用sudo apt update && sudo apt install aria2 -y进行安装。安装完成后，你就可以通过hfd轻松下载Hugging Face上的模型了。 wgethttps://hf-mirror.com/hfd/hfd.sh-O /usr/local/bin/hfd chmod a+x /usr/local/bin/hfd

查看 hfd 用法： hfd -h

下载模型库，默认存储在当前目录，支持 --local-dir 参数： hfd Qwen/Qwen5-5B-Instruct

支持 --include 和 --exclude 参数正则匹配或排除某些文件，例如下载模型库中的指定模型文件，使用 -x 参数指定 8 线程下载（默认 4 线程）： export HF_ENDPOINT=https://hf-mirror.com hfd Qwen/Qwen5-5B-Instruct-GGUF --include 'fp16.gguf' -x 下载 Gated model： hfd meta-llama/Llama-2-1B-Instruct --hf_username gpustack --hf_token hf_abcdefghijklmnopqrstuvwxyz

总结 以上介绍了从Hugging Face下载模型的几种常见方法和相关指令。对于日常下载小模型的需求，建议使用huggingface-cli；若具备特定上网条件和高速带宽，可以考虑使用huggingface-cli配合hf_transfer，但需注意其稳定性。对于经常下载模型或需要下载大模型的情况，hfd则是一个不错的选择。此外，在Python项目中集成模型下载，可以使用hf_hub_download和snapshot_download。请根据实际需求选择合适的方法并参考相关指令进行操作。

关于Seal GPUStack是Seal团队推出的开源项目。Seal，成立于2022年，专注于Cloud与AI Infra解决方案的研发，已成功筹集5300万元种子轮融资。其创始团队成员均来自Rancher Labs等知名公司。特别值得一提的是，联合创始人及CTO梁胜博士，他曾在SUSE担任全球工程及创新总裁，并在创立Rancher Labs期间担任CEO。

我们的目标是助力企业在各种环境下运用人工智能，实现卓越的业务运营。GPUStack作为这一战略的重要组成部分，致力于帮助用户快速搭建LLMaaS平台，实现GPU集群的本地构建、大模型的运行与集成。