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

适用场景

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

详细操作

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

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

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

适用场景

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

详细命令/操作

1. 安装工具

# 基础版（满足核心下载）
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相关库均生效

补充说明

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

3. 代码下载（核心）

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

  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函数，执行方式同上

  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. 安装工具

pip install hf-downloader

2. 核心下载命令

# 基础下载（指定模型、输出目录、镜像源，推荐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. 后台运行（避免断网/锁屏中断，推荐）

# 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+）	命令行一键操作、后台运行、多镜像择优