huggingface-cli

Hugging Face CLI 模型与数据集管理

补充说明

huggingface-cli（新版为 hf CLI）用于登录、下载和上传模型、数据集与 Space。AI 环境排障经常需要确认模型是否完整、缓存位置和访问令牌权限。

常用示例

登录：

huggingface-cli login
# 或使用环境变量
export HF_TOKEN=hf_***

下载模型：

huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --local-dir ./models/qwen2.5-7b

只下载指定文件：

huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --include '*.safetensors' 'config.json' 'tokenizer*'

查看缓存：

huggingface-cli scan-cache
du -sh ~/.cache/huggingface

上传模型：

huggingface-cli upload my-org/my-model ./model \
  --repo-type model

使用镜像站：

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

易错点与排错

• 没有登录或 token 权限不足，私有仓库返回 401/403。
• 下载中断后没有断点续传，模型文件不完整。
• --local-dir 与缓存目录混用，重复占用磁盘。
• 只下载了权重，漏了 tokenizer、config 或 generation config。
• 代理和 HF_ENDPOINT 同时配置，请求走错地址。
• 大模型下载占满磁盘，提前检查可用空间。
• 上传时没有使用 --repo-type dataset，文件传到错误仓库。
• 令牌泄露在脚本或日志中，及时撤销并重新生成。