查看“︁HuggingFace 大模型下载”︁的源代码

<markdown style="gemini">
# HuggingFace 大模型下载完全指南(实战版)

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

---

## 📋 目录

- [1. 工具与命令演进](#1-工具与命令演进)
- [2. 环境准备](#2-环境准备)
- [3. 选择正确的模型仓库](#3-选择正确的模型仓库)
- [4. 镜像 vs 直连:别盲信镜像](#4-镜像-vs-直连别盲信镜像)
- [5. 保活下载:必备 tmux](#5-保活下载必备-tmux)
- [6. 设置 HF_TOKEN 解除限速](#6-设置-hf_token-解除限速)
- [7. Xet 协议踩坑](#7-xet-协议踩坑)
- [8. 速度优化与监控](#8-速度优化与监控)
- [9. 完整推荐流程](#9-完整推荐流程)
- [10. 常见错误对照表](#10-常见错误对照表)

---

## 1. 工具与命令演进

| 旧版 | 新版 | 说明 |
|------|------|------|
| `huggingface-cli download` | `hf download` | 新版 CLI |
| `HF_HUB_ENABLE_HF_TRANSFER=1` | `HF_XET_HIGH_PERFORMANCE=1` | 加速协议升级 |
| `hf_transfer` 库 | **Xet** 协议(内置) | 内置 Rust 高性能传输 |

```bash
# 升级到最新版
pip install -U huggingface_hub
which hf   # 确认新版 CLI 存在
```

---

## 2. 环境准备

```bash
# 创建虚拟环境(可选但推荐)
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,旧仓库可能下架

```bash
# ❌ 失败:模型已迁移
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 重定向回原站

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

### 判断逻辑

```bash
# 测试直连
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 → **下载进程被杀**

### 标准用法

```bash
# 创建会话
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)

```bash
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

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

# 验证
hf auth whoami
```

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

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

---

## 7. Xet 协议踩坑

### Xet 是什么?

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

### 实战中遇到的问题

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

### 解决方案:禁用 Xet

```bash
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. 速度优化与监控

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

```bash
# 看下载目录大小增长
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
```

### 测试真实带宽

```bash
# 测 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 备选方案

```bash
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. 完整推荐流程

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

```bash
# === 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
```

</markdown>