在服务器中下载 HuggingFace 模型：终极指南
在使用 Hugging Face 上的模型时，我们经常需要将模型下载到服务器上，尤其是在 GPU 服务器或集群中部署深度学习任务时。本文将详细介绍如何使用 huggingface_hub 工具在服务器中高效、安全地下载 Hugging Face 模型，包括命令行工具的安装、登录认证、下载命令的使用方式，以及常见问题说明和优化建议。
一、背景说明：huggingface-cli 的更新
过去，Hugging Face 提供了一个独立的命令行工具包 huggingface-cli，用于模型下载、登录等操作。但现在该功能已 集成进了 huggingface_hub 包中。因此，如果你尝试：
pip install huggingface-cli
会提示找不到该包。请使用以下命令安装最新版工具：
pip install huggingface_hub
二、登录 Hugging Face CLI 工具
在使用 Hugging Face 的命令行工具下载私有模型或需要认证的资源前，必须登录。登录支持两种命令：
huggingface-cli login
或
huggingface_hub-cli login
输入你的 Hugging Face access token 后即可完成登录。
建议使用非浏览器服务器（如 SSH 登录的远程服务器）时选择 token 登录模式，避免跳转浏览器验证的复杂流程。
三、模型下载命令详解
完成登录后，即可使用以下命令下载模型：
huggingface-cli download --resume-download (模型名称) --local-dir (模型存放位置) --local-dir-use-symlinks False --resume-download
参数解释：
-
<模型名称>：模型 ID，如THUDM/chatglm3-6b -
<模型存放路径>：本地文件夹路径，建议提前创建好，如/data1/models/chatglm3 -
--resume-download：支持断点续传（非常适合大模型） -
--local-dir-use-symlinks False：禁用符号链接，确保完整复制模型到指定
四、下载速度慢？试试这个技巧
相比直接在 Python 脚本或 Notebook 中加载模型，huggingface-cli download 命令 在服务器中更快更稳定。原因是它绕开了缓存机制、避免自动重定向，且支持多线程下载及断点续传。
如果你在中国大陆地区使用 Hugging Face，建议：
-
配置代理或科学上网
-
或尝试清华镜像（适用于开源模型）：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple huggingface_hub -
或使用 [Hugging Face 镜像工具如 hf-mirror（非官方）]
五、补充说明与建议
1. 如何查找模型名称？
访问 Hugging Face 模型页面（如 chatglm3-6b），复制 URL 中的模型 ID 即可。
2. 多人协作怎么办？
建议每位用户登录一次并配置自己的 token，也可配置环境变量：
export HUGGINGFACE_HUB_TOKEN=your_token_here
3. 下载多个模型怎么办？
你可以写一个简单的脚本，批量下载多个模型：
#!/bin/bash
MODELS=("THUDM/chatglm3-6b" "facebook/opt-2.7b")
for MODEL in "${MODELS[@]}"; do
huggingface-cli download --resume-download "$MODEL" --local-dir "./models/$(basename $MODEL)" --local-dir-use-symlinks False
done
六、总结
使用 huggingface_hub 提供的 CLI 工具，可以方便、安全、可控地在服务器中下载和管理 Hugging Face 模型资源。相比自动缓存方式，命令行工具支持断点续传、目录管理，并且更适合批量部署场景。合理配置登录和网络环境后，将大幅提升你的模型使用体验。
关键词：Hugging Face、模型下载、服务器部署、huggingface_hub、CLI、断点续传、模型加速、私有模型认证
如果你在使用过程中遇到问题，欢迎留言讨论或查阅 Hugging Face 官方文档：https://huggingface.co/docs/huggingface_hub
