hf 命令的作用
huggingface-cli 的新一代命令名是 hf，用来把模型仓库里的权重、配置与分词器文件下载到本地目录，支持断点续传与只下载指定文件。大模型动辄几十 GB，下载环节的关键是三点：目录要落到数据盘、能续传、带宽要跑满。它同时是离线部署流程的第一步。
基本信息
| 命令 | huggingface-cli download 与新版 hf download，参数基本一致 |
|---|---|
| 安装 | pip install -U huggingface_hub；加速传输另需 hf_transfer |
| 断点续传 | 重复执行同一命令会跳过已完成的文件 |
| 缓存与目录 | 默认进缓存目录，--local-dir 直接落到指定路径 |
常用下载命令
常用下载命令
# 安装客户端
pip install -U huggingface_hub
# 下载整个仓库到本地目录（推荐：路径可控，便于挂进容器）
huggingface-cli download <组织>/<模型> --local-dir ./models/<模型>
hf download <组织>/<模型> --local-dir ./models/<模型> # 新版命令等价写法
# 只取需要的文件，例如补齐缺失的配置
huggingface-cli download <组织>/<模型> config.json tokenizer.json --local-dir ./models/<模型>
# 镜像站与加速传输（网络受限时使用）
export HF_ENDPOINT=https://hf-mirror.com
export HF_HUB_ENABLE_HF_TRANSFER=1常用参数
| 参数 | 作用 |
|---|---|
| --local-dir | 指定落盘目录，容器部署时挂载这个目录 |
| --revision | 锁定分支、标签或提交号，保证每次拿到同一份权重 |
| --include / --exclude | 按通配符筛选文件，避免下到不需要的格式 |
| --resume-download | 续传开关，新版默认支持断点续传 |
| HF_ENDPOINT | 切换下载源，企业内网通常指向自建镜像 |
| HF_HUB_ENABLE_HF_TRANSFER | 启用多线程高速传输，需先装 hf_transfer |
典型使用场景
- 首次准备本地权重：把模型落到数据盘目录，供引擎挂载或直接加载
- 补齐缺失文件：只缺分词器或配置文件时按文件名单独下载
- 锁定版本：按提交号下载，保证线上线下加载的是同一份权重
- 离线环境准备：在联网机器下载完整目录，再整体拷进内网
- 多机批量分发：先在共享盘下好，各节点从共享盘复制，避免重复占用公网带宽
下载中断后重复执行同一命令即可续传：换目录重下之前先确认磁盘剩余空间足够放下整份权重，几十 GB 的目录写到一半失败很常见。
镜像站是第三方服务：敏感或受限模型不要经镜像中转，优先官方源或企业自建镜像，并核对文件清单与大小。