如何优雅地下载 Hugging Face 模型
Hugging Face 已经成为事实上的开源模型分发中心，无论是 NLP、CV 还是多模态模型，几乎都可以通过一个 model id 直接获取完整权重与配置文件。
本文将系统介绍 推荐的 Hugging Face 模型下载方式，并解释为什么有些方法不推荐，有些方法则更优雅、更工程化。
下载方法
直接在网页页面点击下载（不推荐）
很多人在第一次接触 Hugging Face 时，会直接打开模型页面，在 Files and versions 中逐个点击下载文件。
这种方式存在明显问题：
- 每次只能下载一个文件，大模型往往包含几十个文件
- 不支持断点续传，网络稍有波动就可能失败
- 容易遗漏关键文件（如 tokenizer、config）
- 完全不适合自动化与工程使用
因此，这种方式只适合临时查看模型的配置文件内容或下载极小文件，不推荐作为正式下载方案。
使用 git lfs clone 下载模型（不推荐作为常规方案）
在 Hugging Face 的模型页面中，官方仍然提供了如下方式：
bash
git lfs clone https://huggingface.co/Qwen/Qwen3-8B
但实际使用中并不推荐这样做。
git lfs clone 的适用场景
需要明确的是，Hugging Face 的模型仓库本质上是 Git + Git LFS ，因此 git lfs clone 在以下场景下仍然合理：
- 模型作者或维护者
- 需要查看、修改仓库结构
- 需要提交 PR 或管理分支
- 希望完整保留 Git 历史与版本控制
git lfs clone 的局限性
但对于绝大多数模型使用者来说，这种方式并不理想：
- 会下载完整仓库内容，而不仅是运行所需文件
- 与
from_pretrained的缓存体系不兼容 - 国内网络环境下 Git LFS 失败率较高
因此，git lfs clone 更适合作为开发者的模型维护工具 ，而不是用户的模型下载工具。
使用 hf 工具下载模型（推荐）
hf 工具简介
不少旧教程仍然在使用：
sh
huggingface-cli download ...但需要明确的是：
- huggingface-cli 已经进入维护期
- 命令结构不统一，可发现性差
- 新功能不会优先接入
2025 年起，官方推荐统一使用新的 hf 命令行工具。
hf 工具的命令按"资源"（hf auth, hf cache, hf repo 等）分组。HuggingFace还将 hf upload 和 hf download 放在根级别，因为它们预计是使用最频繁的命令
安装方式
hf 工具与旧 CLI 共用同一套依赖：
bash
pip install -U "huggingface_hub[cli]"使用 hf download 下载模型
bash
hf download Qwen/Qwen3-8B该命令会：
- 自动解析模型结构
- 下载所有必要文件
- 支持断点续传与校验
- 将模型存入 Hugging Face 全局缓存
如果希望下载到指定目录：
bash
hf download Qwen/Qwen3-8B --local-dir 指定目录的路径地址在代码中使用 from_pretrained 自动下载（推荐）
在实际工程中，最推荐的方式是让代码自行管理模型下载，使用AutoModel类的from_pretrained方法，在其中填入model id，即可自动下载模型：
python
from transformers import AutoModelForCausalLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B")这种方式具备以下优点：
- 代码即配置
- 自动复用缓存
- 天然支持镜像站
- 易于复现与部署
在大多数场景下，你甚至不需要关心模型是否已经下载。
模型存储位置
Hugging Face 模型的默认下载位置
无论使用 hf download，还是在代码中调用 from_pretrained，模型默认都会被存储在：
text
~/.cache/huggingface/hub这是 Hugging Face 统一的缓存目录，能够实现：
- 模型文件去重
- 多项目复用
- 避免重复下载
自定义模型下载目录
如果不想下载到默认目录下，可以通过环境变量HF_HOME修改HuggingFace的资源存储默认路径：
bash
export HF_HOME=/data/huggingface或仅修改模型缓存目录HF_HUB_CACHE：
bash
export HF_HUB_CACHE=/data/huggingface/hub设置后，所有 Hugging Face 相关工具都会自动使用新的路径。
配置镜像网站
在国内网络环境下，直接使用 huggingface.co 经常会遇到加载缓慢、下载失败等问题。
为此，可以通过设置环境变量HF_ENDPOINT的方式，使用 Hugging Face 镜像站点来加速下载，hf-mirror就是一个最常用的镜像站点：
bash
export HF_ENDPOINT=https://hf-mirror.com设置后：
hf命令行工具from_pretrainedhuggingface_hub
的所有下载行为
都会自动走镜像地址，对现有代码几乎没有影响。
具体用法可以查看 https://hf-mirror.com
身份认证
如果你需要下载：
- 私有模型
- 需要授权的模型（如部分 LLaMA 系列）
需要先使用以下命令登录你的HuggingFace账号：
sh
hf auth login登录成功后登录信息会被统一存储，并被 CLI 与 Python API 共享，之后无需再次登录。
小结
综合来看，下载 Hugging Face 模型的推荐实践是：
- 不使用网页手动下载
- 避免将
git lfs clone作为常规下载方式 - 使用新版
hf download命令 - 在工程中优先使用
from_pretrained方法 - 国内环境配置
HF_ENDPOINT