服务器下载 Hugging Face 模型笔记：以 Qwen2.5-Coder-7B-CL 为例

前言

在服务器上部署大模型时，第一步通常是把 Hugging Face 上的模型下载到服务器本地。

这件事看起来只是一个下载命令：

1
hf download xxx/xxx

但实际操作中经常会遇到几个问题：

  1. 服务器磁盘很多，不知道模型该放哪里
  2. huggingface-cli / hf 命令找不到
  3. 服务器访问 Hugging Face 慢，需要镜像源
  4. 目录权限不够，下载时 Permission denied
  5. 下载完成后不知道如何检查文件是否完整

本文以下载模型：

1
czlll/Qwen2.5-Coder-7B-CL

到服务器目录：

1
/data2/like/models/Qwen2.5-Coder-7B-CL

为例，完整整理一次服务器下载 Hugging Face 模型的过程。

一、先选择正确的磁盘目录

1.1 为什么不能随便下载到 /home/user

服务器上通常有多个磁盘目录，比如：

不能看到一个目录就直接用，必须先看它所在磁盘还有多少空间,，通常一个数据集或者模型占据的空间比较大。

查看磁盘空间：

1
df -h

命令含义：

1
2
df = disk free，查看磁盘剩余空间
-h = human-readable，用人容易读懂的单位显示，比如 G、T

如果看到类似：

1
2
3
/dev/sdb4       388G  357G   11G  98% /
/dev/sda        1.8T  1.7T   15G 100% /ssd_data
/dev/sdc1       3.6T  2.5T  942G  73% /data2

说明：

1
2
3
/        只剩 11G，不适合放模型
/ssd_data 只剩 15G，也不适合
/data2   还剩 942G，适合放大模型

所以模型、代码、实验输出都应该放到：

1
/data2

而不是：

1
/home/user

1.2 建议的目录规划

进入大数据盘：

1
cd /data2

命令含义：

1
cd = change directory，切换目录

创建自己的工作目录：

1
2
3
4
mkdir -p /data2/like/models
mkdir -p /data2/like/loccode
mkdir -p /data2/like/outputs
mkdir -p /data2/like/hf-cache

命令含义：

1
2
mkdir = make directory，创建目录
-p = parents，父目录不存在就一起创建，目录已存在也不报错

建议用途：

二、处理目录权限问题

2.1 为什么会出现 Permission denied

如果执行：

1
mkdir models

报错：

1
mkdir: cannot create directory ‘models’: Permission denied

说明当前用户没有权限在这个目录下创建文件夹。

有些时候会直接用：

1
sudo mkdir models

这虽然能创建成功，但会带来一个新问题：这个目录可能属于 root 用户。

后面普通用户执行：

1
hf download ...

时，就可能写不进去，报错：

1
PermissionError: [Errno 13] Permission denied

2.2 正确做法：把自己的工作目录改回当前用户

如果 /data2/like 是自己的工作目录，可以执行：

1
sudo chown -R user:user /data2/like

命令含义：

1
2
3
4
5
sudo = superuser do，用管理员权限执行
chown = change owner，修改文件或目录的所有者
-R = recursive，递归修改目录里面的所有文件和子目录
user:user = 用户名:用户组
/data2/like = 要修改权限的目录

这条命令的意思是：

1
把 /data2/like 以及里面所有内容的拥有者改成 user。

执行后检查权限：

1
2
ls -ld /data2/like
ls -ld /data2/like/models

命令含义：

1
2
3
ls = list，列出文件
-l = long format，显示详细信息
-d = directory，只显示目录本身，不展开目录内容

如果看到：

1
2
drwxr-xr-x 4 user user 4096 ... /data2/like
drwxr-xr-x 2 user user 4096 ... /data2/like/models

重点看这里：

1
user user

说明目录已经属于当前用户，后面可以正常下载模型。

三、安装 Hugging Face 命令行工具

3.1 安装 huggingface_hub

如果服务器没有 hf 或 huggingface-cli 命令，可以安装：

1
pip install -U huggingface_hub -i https://pypi.tuna.tsinghua.edu.cn/simple

命令含义：

1
2
3
4
5
6
pip = Python 包管理工具
install = 安装
-U = upgrade，升级到较新版本
huggingface_hub = Hugging Face 官方 Python 工具包
-i = index-url，指定 Python 包下载源
https://pypi.tuna.tsinghua.edu.cn/simple = 清华 PyPI 镜像源

这条命令的作用是：

1
从清华镜像源安装或升级 Hugging Face Hub 工具。

3.2 为什么安装后还是 command not found

安装成功后，可能看到提示：

1
The scripts hf, huggingface-cli and tiny-agents are installed in '/home/user/.local/bin' which is not on PATH.

意思是：

1
2
3
hf 和 huggingface-cli 命令已经安装了，
但是它们被放在 /home/user/.local/bin，
而当前终端的 PATH 没有包含这个目录。

PATH 可以理解为 Linux 的“命令搜索路径”。

当你输入：hf或者huggingface-cli命令

系统会去 PATH 记录的目录里找这个命令。如果 /home/user/.local/bin 不在 PATH 中，系统就找不到 hf。

临时解决：

1
export PATH="$HOME/.local/bin:$PATH"

命令含义：

1
2
3
4
export = 导出环境变量，让当前终端后续命令可以使用
PATH = 命令搜索路径
$HOME = 当前用户主目录，比如 /home/user
:$PATH = 保留原来的 PATH

这条命令的意思是：

1
把 /home/user/.local/bin 加到命令搜索路径最前面。

然后测试：

1
2
hf --help
huggingface-cli --help

如果能看到帮助信息，说明命令已经可用。

3.3 让 PATH 永久生效

临时 export 只对当前终端有效。为了以后每次登录都自动生效，可以写入 ~/.bashrc：

1
2
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

命令含义：

1
2
3
4
echo = 输出一段文本
>> = 追加写入文件末尾
~/.bashrc = Bash 终端启动时会读取的配置文件
source = 重新加载配置文件，让修改立即生效

执行后再检查：

1
2
which hf
which huggingface-cli

命令含义：

1
which = 查看某个命令实际来自哪个路径

正常输出类似：

1
2
/home/user/.local/bin/hf
/home/user/.local/bin/huggingface-cli

四、配置 Hugging Face 镜像源

4.1 为什么要配置镜像源

国内服务器访问 Hugging Face 官方站点可能比较慢，甚至失败。因此可以使用镜像源：

1
export HF_ENDPOINT=https://hf-mirror.com

命令含义：

1
2
HF_ENDPOINT = Hugging Face Hub 的访问入口
https://hf-mirror.com = Hugging Face 镜像站

这条命令的意思是：

1
后续 hf / huggingface-cli 下载模型时，优先从 hf-mirror.com 访问。

注意：

1
2
3
HF_ENDPOINT 只决定“从哪里下载模型”，
不能解决 hf command not found，
也不能解决本地目录权限问题。

五、正式下载模型

5.1 推荐使用新版 hf download

新版推荐命令是：

1
2
hf download czlll/Qwen2.5-Coder-7B-CL \
  --local-dir /data2/like/models/Qwen2.5-Coder-7B-CL

命令含义：

1
2
3
4
5
hf = Hugging Face 新版命令行工具
download = 下载模型或数据集文件
czlll/Qwen2.5-Coder-7B-CL = Hugging Face 上的模型仓库名
--local-dir = local directory，指定下载到本地哪个目录
/data2/like/models/Qwen2.5-Coder-7B-CL = 模型保存路径

完整意思是：

1
2
从 Hugging Face 下载 czlll/Qwen2.5-Coder-7B-CL 模型，
并保存到 /data2/like/models/Qwen2.5-Coder-7B-CL。

5.2 不建议继续使用 --resume-download

旧命令里经常会写：

1
--resume-download

它的意思是断点续传。

但是新版 Hugging Face 工具已经会尽可能自动续传，所以这个参数会提示 deprecated，也就是即将废弃。

因此推荐：

1
2
hf download czlll/Qwen2.5-Coder-7B-CL \
  --local-dir /data2/like/models/Qwen2.5-Coder-7B-CL

而不是：

1
huggingface-cli download ... --resume-download

5.3 如果仍然使用 huggingface-cli

旧命令也可以用，但会提示：

1
huggingface-cli download is deprecated. Use hf download instead.

意思是：

1
huggingface-cli download 已经不推荐使用了，请改用 hf download。

所以优先用：

1
hf download

六、下载完成后的检查

6.1 查看模型目录

1
ls -lh /data2/like/models/Qwen2.5-Coder-7B-CL

命令含义：

1
2
3
ls = list，列出文件
-l = long format，显示详细信息
-h = human-readable，文件大小用 G、M 这种好读的单位显示

正常应该看到：

1
2
3
4
5
6
config.json
generation_config.json
tokenizer.json
tokenizer_config.json
model.safetensors.index.json
*.safetensors

6.2 查看模型目录大小

1
du -sh /data2/like/models/Qwen2.5-Coder-7B-CL

命令含义：

1
2
3
du = disk usage，查看磁盘占用
-s = summary，只显示总大小
-h = human-readable，用 G、M 等单位显示

如果输出类似：

1
15G    /data2/like/models/Qwen2.5-Coder-7B-CL

说明模型大约占 15GB。

6.3 查看所在磁盘剩余空间

1
df -h /data2

这一步很重要，防止模型下载到一半把磁盘塞满。

七、常见错误总结

7.1 huggingface-cli: command not found

原因：

1
2
没有安装 huggingface_hub，
或者命令安装到了 /home/user/.local/bin，但 PATH 没有包含这个目录。

解决：

1
2
pip install -U huggingface_hub -i https://pypi.tuna.tsinghua.edu.cn/simple
export PATH="$HOME/.local/bin:$PATH"

永久生效：

1
2
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

7.2 hf: command not found

原因同上：

1
hf 已经安装，但当前终端找不到。

解决：

1
2
export PATH="$HOME/.local/bin:$PATH"
hf --help

7.3 Permission denied

常见报错：

1
PermissionError: [Errno 13] Permission denied

原因：

1
目标目录属于 root，普通用户没有写权限。

典型来源是之前用了：

1
sudo mkdir models

导致 models 目录由 root 创建。

解决：

1
sudo chown -R user:user /data2/like

然后检查：

1
2
ls -ld /data2/like
ls -ld /data2/like/models

确认目录属于：

1
user user

7.4 Could not resolve host

原因：

1
服务器 DNS 或网络有问题，无法解析域名。

可以测试：

1
2
3
4
getent hosts hf-mirror.com
getent hosts huggingface.co
curl -I https://hf-mirror.com
curl -I https://huggingface.co

如果服务器网络一直不稳定，可以换成：

1
2
3
4
本地电脑下载模型
打包成 tar
scp 上传服务器
服务器解压

八、完整推荐流程

最终推荐命令如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 1. 进入大数据盘
cd /data2

# 2. 创建自己的工作目录
mkdir -p /data2/like/models
mkdir -p /data2/like/loccode
mkdir -p /data2/like/outputs
mkdir -p /data2/like/hf-cache

# 3. 如果之前 sudo 创建过目录，修复权限
sudo chown -R user:user /data2/like

# 4. 安装 Hugging Face 工具
pip install -U huggingface_hub -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 加入 PATH
export PATH="$HOME/.local/bin:$PATH"

# 6. 永久加入 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 7. 设置 Hugging Face 镜像源
export HF_ENDPOINT=https://hf-mirror.com

# 8. 下载模型
hf download czlll/Qwen2.5-Coder-7B-CL \
  --local-dir /data2/like/models/Qwen2.5-Coder-7B-CL

# 9. 检查模型文件
ls -lh /data2/like/models/Qwen2.5-Coder-7B-CL
du -sh /data2/like/models/Qwen2.5-Coder-7B-CL

总结

服务器下载 Hugging Face 模型的关键不是只记住一条 hf download 命令，而是要按顺序处理好四件事：

1
2
3
4
第一，选对磁盘目录，模型要放到大数据盘，比如 /data2。
第二，装好 huggingface_hub，并把 /home/user/.local/bin 加入 PATH。
第三，根据网络情况设置 HF_ENDPOINT 镜像源。
第四，保证目标目录属于当前用户，避免 Permission denied。

这次问题的本质是两层：

1
2
第一层：hf / huggingface-cli 安装成功了，但不在 PATH 里，所以 command not found。
第二层：models 目录最开始用 sudo 创建，属于 root，所以普通用户下载模型时 Permission denied。

最终修复思路是：

1
2
3
4
export PATH="$HOME/.local/bin:$PATH"
sudo chown -R user:user /data2/like
hf download czlll/Qwen2.5-Coder-7B-CL \
  --local-dir /data2/like/models/Qwen2.5-Coder-7B-CL

只要这三步处理好，服务器下载 Hugging Face 模型就会顺畅很多。

另外，旧命令 huggingface-cli download 仍可用，但日志已经提示它被弃用，推荐改用 hf download；--resume-download 也只是未来会废弃的提示，不是你这次失败的根因。