HuggingFace 大模型下载

来自个人维基
Hovercool​（留言 | 贡献）2026年6月24日 (三) 09:36的版本
(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)
跳转到导航 跳转到搜索

HuggingFace 大模型下载完全指南(实战版)

以下载 CalamitousFelicitousness/Qwen2.5-72B-Instruct-fp8-dynamic(73GB)为例, 总结从工具选择、镜像配置、断点续传、后台运行到速度优化的完整流程与避坑经验。

📋 目录

1. 工具与命令演进

旧版 新版 说明
huggingface-cli download hf download 新版 CLI
HF_HUB_ENABLE_HF_TRANSFER=1 HF_XET_HIGH_PERFORMANCE=1 加速协议升级
hf_transfer 库 Xet 协议(内置) 内置 Rust 高性能传输 
# 升级到最新版
pip install -U huggingface_hub
which hf   # 确认新版 CLI 存在

2. 环境准备

# 创建虚拟环境(可选但推荐)
python -m venv ~/hf-env
source ~/hf-env/bin/activate

# 安装
pip install -U huggingface_hub

# 装 tmux(后台保活必备)
sudo apt install -y tmux

# 装 aria2(备选高速下载工具)
sudo apt install -y aria2

3. 选择正确的模型仓库

⚠️ 坑:Neural Magic 已并入 Red Hat,旧仓库可能下架

# ❌ 失败:模型已迁移
hf download neuralmagic/Qwen2.5-72B-Instruct-FP8 ...
# → Error: Model not found

# ✅ 正确做法:用 API 搜索
curl -s "https://huggingface.co/api/models?search=Qwen2.5-72B-Instruct-FP8&limit=20" \
    | python -m json.tool | grep '"id"'

# 或浏览器搜:
# https://huggingface.co/models?search=Qwen2.5-72B-Instruct-FP8

选模型的建议

  • 优先选下载量高的(社区已验证)
  • 优先选 Dynamic 量化(精度更高,vLLM 推荐)
  • 看模型卡片确认 quantization_config 字段

4. 镜像 vs 直连:别盲信镜像

坑:hf-mirror.com 没缓存的仓库会 308 重定向回原站

$ curl -I https://hf-mirror.com/<冷门仓库>/resolve/main/config.json
HTTP/2 308
location: https://huggingface.co/...   # ← 踢回原站

判断逻辑

# 测试直连
curl -I --max-time 10 https://huggingface.co

# 能通 → 直接 unset HF_ENDPOINT,用官方源
# 不通 → 用镜像或代理
情况 配置
能直连 HF unset HF_ENDPOINT
不能直连,有代理 export HTTPS_PROXY=...
不能直连,要国内源 export HF_ENDPOINT=https://hf-mirror.com
镜像也不行 用 ModelScope 魔搭社区

5. 保活下载:必备 tmux

不用 tmux 的后果

关闭 WindTerm / SSH → 终端收到 SIGHUP → 下载进程被杀

标准用法

# 创建会话
tmux new -s hf

# 在 tmux 里跑下载...
hf download ...

# 关 WindTerm 前:分离会话
Ctrl + B,然后按 D
# 看到 [detached (from session hf)] 即成功

# 下次回来:重连
tmux attach -t hf

# 列出所有会话
tmux ls

# 杀掉会话
tmux kill-session -t hf

tmux 快捷键速查

操作 快捷键
分离会话 Ctrl+B 然后 D
新建窗口 Ctrl+B 然后 C
切换下个窗口 Ctrl+B 然后 N
滚动查看历史 Ctrl+B 然后 [(q 退出)
切割左右窗格 Ctrl+B 然后 %

应急方案(已经在跑没用 tmux)

Ctrl + Z      # 暂停
bg            # 后台运行
disown -h     # 脱离终端,关 SSH 也不死

6. 设置 HF_TOKEN 解除限速

匿名下载会被严重限速

Warning: You are sending unauthenticated requests to the HF Hub.
Please set a HF_TOKEN to enable higher rate limits and faster downloads.

创建并登录 Token

# 1. 浏览器打开 https://huggingface.co/settings/tokens
# 2. 创建 Read 权限 token,复制 hf_xxxxx
# 3. 命令行登录
hf auth login
# 粘贴 token,按回车(粘贴时不显示是正常的)
# 询问 git credential 时输入 n

# 验证
hf auth whoami

或用环境变量(写入 ~/.bashrc 持久化)

echo 'export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

7. Xet 协议踩坑

Xet 是什么?

HF 新推出的分块下载协议(替代 hf_transfer),默认开启,理论上更快。

实战中遇到的问题

症状 原因
卡死无 TCP 连接 Xet 连接全断但进程不退出
内存暴涨到 12GB+ Xet 缓存泄漏
镜像下载报错 Xet 不走 HF_ENDPOINT

解决方案:禁用 Xet

export HF_HUB_DISABLE_XET=1
export HF_HUB_DOWNLOAD_TIMEOUT=60

hf download <model> --local-dir <dir> --max-workers 4

关键环境变量速查

变量 作用
HF_ENDPOINT API 镜像地址
HF_TOKEN 鉴权 token
HF_HUB_DISABLE_XET=1 禁用 Xet(治卡死)
HF_HUB_DOWNLOAD_TIMEOUT=60 单请求超时(默认 10s)
HF_XET_HIGH_PERFORMANCE=1 Xet 高性能模式
HF_DEBUG=1 显示详细错误
HF_HOME 缓存目录

8. 速度优化与监控

监控真实速度(不信进度条以外的测速)

# 看下载目录大小增长
du -sh ./data/models/Qwen2.5-72B-Instruct-FP8
sleep 60
du -sh ./data/models/Qwen2.5-72B-Instruct-FP8

# 看进程状态
ps -o pid,stat,etime,cmd $(pgrep -f "hf download")
# S=正常等待,R=运行中,D=磁盘阻塞

# 看 TCP 连接(空连接=卡死)
sudo ss -tnp | grep python

测试真实带宽

# 测 HF 直连速度
curl -o /dev/null -w "速度: %{speed_download} B/s\n" --max-time 30 \
  https://huggingface.co/<repo>/resolve/main/<某权重文件>.safetensors

# 测国内源对比
curl -o /dev/null -w "%{speed_download} B/s\n" --max-time 20 \
  https://mirrors.aliyun.com/ubuntu/dists/jammy/main/binary-amd64/Packages.gz

# 测 Cloudflare
curl -o /dev/null -w "%{speed_download} B/s\n" --max-time 20 \
  https://speed.cloudflare.com/__down?bytes=104857600

提速手段(按效果排序)

方法 效果 难度
登录 HF_TOKEN 解除限速,5-10× ⭐
提高 --max-workers 1.5-2× ⭐
换 aria2c 多线程 2-5× ⭐⭐
换 ModelScope 国内 5-20× ⭐⭐
双网卡叠加 几乎无用 ❌ ⭐⭐⭐⭐⭐
升级带宽 取决于花钱 💰

aria2c 备选方案

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

~/hfd.sh CalamitousFelicitousness/Qwen2.5-72B-Instruct-fp8-dynamic \
    --local-dir ./data/models/Qwen2.5-72B-Instruct-FP8 \
    --tool aria2c -x 16 \
    --hf_username <你的用户名> \
    --hf_token <你的token>

9. 完整推荐流程

🎯 最佳实践命令(收藏即用)

# === Step 1: 环境准备 ===
source ~/hf-env/bin/activate              # 进虚拟环境
pip install -U huggingface_hub            # 升到最新版

# === Step 2: 登录 ===
hf auth login                              # 粘 token

# === Step 3: 设置稳定环境变量 ===
export HF_HUB_DISABLE_XET=1               # 禁用 Xet 防卡死
export HF_HUB_DOWNLOAD_TIMEOUT=60         # 单请求 60s 超时
unset HF_ENDPOINT                          # 直连官方(能直连的话)

# === Step 4: 进 tmux ===
tmux new -s hf

# === Step 5: 下载 ===
hf download <user>/<repo> \
    --local-dir ./data/models/<目录名> \
    --max-workers 4

# === Step 6: 分离 tmux 走人 ===
# 按 Ctrl+B,然后按 D
# 关 WindTerm

# === Step 7: 回来验收 ===
tmux attach -t hf
检索自“https://www.mywiki.cn/Hovercool/index.php?title=HuggingFace_大模型下载&oldid=163205”