Huggingface大模型下载方法总结_20260128084905

一、国内镜像站直接下载（小白首选）

适用场景

几G以内的小型模型，无需安装额外工具，浏览器即可操作

详细操作

常用镜像 ：推荐hf-mirror.com（通用、速度快）、modelscope.cn（阿里旗下，中文模型友好）
地址替换 ：原始仓库地址https://huggingface.co/模型ID → 镜像地址https://hf-mirror.com/模型ID（例：Qwen/Qwen2-7B-Instruct）
具体下载
- 单文件：打开镜像地址，点击目标文件（如pytorch_model.bin），浏览器自动高速下载；
- 大文件补充：复制文件下载链接，用wget命令下载（跨系统通用）：
  bash 复制代码
```
wget 镜像文件下载链接 -O 保存路径/文件名

# Win10 CMD原生可用，-o 指定保存路径/文件名（建议绝对路径）
curl 镜像文件下载链接 -o D:\models\pytorch_model.bin
```

二、huggingface-hub工具下载（进阶首选）

适用场景

几十G的大型模型，支持断点续传、后台运行，可灵活指定下载目录/过滤文件

详细命令/操作

1. 安装工具

bash 复制代码

# 基础版（满足核心下载）
pip install huggingface-hub
# 完整版（支持加速、压缩，推荐）
pip install huggingface-hub[full]

2.配置Hugging Face常用环境变量（关键）

变量说明

变量名	核心作用	推荐取值示例
`HF_ENDPOINT`	指定HF国内镜像端点，必配，所有HF工具均通过该地址下载	`https://hf-mirror.com`
`HF_HOME`	HF系列工具统一缓存根目录，统一管理模型/缓存文件，避免C盘爆满	Windows：`D:\hf_cache`；Mac/Linux：`~/.hf_cache`
`TRANSFORMERS_CACHE`	Transformers库专属缓存目录，指定模型、分词器的下载/缓存路径	与`HF_HOME`一致即可
`DIFFUSERS_CACHE`	Diffusers库专属缓存目录，指定扩散模型（如Stable Diffusion）的缓存路径	与`HF_HOME`一致即可

各系统配置命令

配置类型	Windows（CMD）	Windows（PowerShell）	Mac/Linux	生效范围
临时配置（仅当前终端）	1. `set HF_ENDPOINT=https://hf-mirror.com` 2. `set HF_HOME=D:\hf_cache` 3. `set TRANSFORMERS_CACHE=D:\hf_cache` 4. `set DIFFUSERS_CACHE=D:\hf_cache`	1. `$env:HF_ENDPOINT="https://hf-mirror.com"` 2. `$env:HF_HOME="D:\hf_cache"` 3. `$env:TRANSFORMERS_CACHE="D:\hf_cache"` 4. `$env:DIFFUSERS_CACHE="D:\hf_cache"`	1. `export HF_ENDPOINT=https://hf-mirror.com` 2. `export HF_HOME=~/.hf_cache` 3. `export TRANSFORMERS_CACHE=~/.hf_cache` 4. `export DIFFUSERS_CACHE=~/.hf_cache`	仅当前终端，关闭后失效
永久配置（所有终端/工具）	系统环境变量中新增以下4个变量，分别填写对应值：变量名：`HF_ENDPOINT`，值：`https://hf-mirror.com` 变量名：`HF_HOME`，值：`D:\hf_cache` 变量名：`TRANSFORMERS_CACHE`，值：`D:\hf_cache` 变量名：`DIFFUSERS_CACHE`，值：`D:\hf_cache`	同左（Windows系统环境变量为全局配置，CMD/PowerShell通用）	编辑配置文件（二选一）： 1. Bash：`vim ~/.bashrc` 2. Zsh：`vim ~/.zshrc` 添加以下内容： `bash<br>export HF_ENDPOINT=https://hf-mirror.com<br>export HF_HOME=~/.hf_cache<br>export TRANSFORMERS_CACHE=~/.hf_cache<br>export DIFFUSERS_CACHE=~/.hf_cache<br>` 执行生效： 1. Bash：`source ~/.bashrc` 2. Zsh：`source ~/.zshrc`	所有终端、Python工具、HF相关库均生效

补充说明

配置时路径不要包含中文/空格，避免出现路径识别错误；
若只需基础下载加速，仅配置HF_ENDPOINT即可；配置HF_HOME后，TRANSFORMERS_CACHE可省略（会默认继承HF_HOME路径）；
Windows配置系统环境变量后，需重启所有终端/IDE（如PyCharm、VS Code）才会生效；
Mac/Linux若修改~/.bashrc后生效失败，检查当前终端是否为Zsh（执行echo $SHELL查看），对应修改~/.zshrc即可。

3. 代码下载（核心）

单文件下载 ：新建download_model.py，写入以下代码并执行python download_model.py

python 复制代码

from huggingface_hub import hf_hub_download
# 配置参数
model_id = "Qwen/Qwen2-7B-Instruct"  # 模型仓库ID
filename = "pytorch_model.bin"       # 要下载的文件名
cache_dir = "./models"               # 本地保存目录
# 执行下载（开启断点续传、跳过已下载）
hf_hub_download(
    repo_id=model_id,
    filename=filename,
    cache_dir=cache_dir,
    force_download=False,  # 不重复下载已存在文件
    resume_download=True   # 开启断点续传（核心）
)

批量下载整个仓库 ：替换为snapshot_download函数，执行方式同上

python 复制代码

from huggingface_hub import snapshot_download
model_id = "Qwen/Qwen2-7B-Instruct"
cache_dir = "./models"
snapshot_download(
    repo_id=model_id,
    cache_dir=cache_dir,
    force_download=False,
    resume_download=True,
    local_dir_use_symlinks=False,  # 不使用符号链接，直接保存文件
    local_dir=f"./models/{model_id}"  # 本地最终保存路径
)

三、hf-downloader第三方工具下载（终极方案）

适用场景

几十G/上百G的超大模型，命令行一键操作，无需写Python脚本，支持多镜像自动择优、后台运行、限速/文件过滤

详细命令/操作

1. 安装工具

bash 复制代码

pip install hf-downloader

2. 核心下载命令

bash 复制代码

# 基础下载（指定模型、输出目录、镜像源，推荐hf-mirror.com）
hf-download --model 模型ID --output 本地保存路径 --mirror hf-mirror.com
# 示例：下载Qwen2-7B-Instruct到./models目录
hf-download --model Qwen/Qwen2-7B-Instruct --output ./models --mirror hf-mirror.com

3. 后台运行（避免断网/锁屏中断，推荐）

bash 复制代码

# Linux/Mac后台运行
nohup hf-download --model Qwen/Qwen2-7B-Instruct --output ./models --mirror hf-mirror.com &
# Windows后台运行
start /b python -m hf_download --model Qwen/Qwen2-7B-Instruct --output ./models --mirror hf-mirror.com

四、方案选择速查

下载方式	适用人群	模型大小	核心优势
镜像站直接下载	编程小白	几G以内	零配置、操作简单
huggingface-hub	开发进阶者	几十G	灵活可控、断点续传、Python生态兼容
hf-downloader	所有用户	超大模型（几十G+）	命令行一键操作、后台运行、多镜像择优