name: hugging-face-cli description: 使用 `hf` CLI 执行 Hugging Face Hub 操作。当用户需要下载模型/数据集/空间、上传文件到 Hub 仓库、创建仓库、管理本地缓存或在 HF 基础设施上运行计算作业时使用。涵盖认证、文件传输、仓库创建、缓存操作和云计算。

Hugging Face CLI

hf CLI 提供对 Hugging Face Hub 的直接终端访问，用于下载、上传和管理仓库、缓存和计算资源。

快速命令参考

任务	命令
登录	`hf auth login`
下载模型	`hf download <repo_id>`
下载到文件夹	`hf download <repo_id> --local-dir ./path`
上传文件夹	`hf upload <repo_id> . .`
创建仓库	`hf repo create <name>`
创建标签	`hf repo tag create <repo_id> <tag>`
删除文件	`hf repo-files delete <repo_id> <files>`
列出缓存	`hf cache ls`
从缓存移除	`hf cache rm <repo_or_revision>`
列出模型	`hf models ls`
获取模型信息	`hf models info <model_id>`
列出数据集	`hf datasets ls`
获取数据集信息	`hf datasets info <dataset_id>`
列出空间	`hf spaces ls`
获取空间信息	`hf spaces info <space_id>`
列出端点	`hf endpoints ls`
运行 GPU 作业	`hf jobs run --flavor a10g-small <image> <cmd>`
环境信息	`hf env`

核心命令

认证

hf auth login                    # 交互式登录
hf auth login --token $HF_TOKEN  # 非交互式
hf auth whoami                   # 检查当前用户
hf auth list                     # 列出存储的令牌
hf auth switch                   # 切换令牌
hf auth logout                   # 登出

下载

hf download <repo_id>                              # 完整仓库到缓存
hf download <repo_id> file.safetensors             # 特定文件
hf download <repo_id> --local-dir ./models         # 到本地目录
hf download <repo_id> --include "*.safetensors"    # 按模式过滤
hf download <repo_id> --repo-type dataset          # 数据集
hf download <repo_id> --revision v1.0              # 特定版本

上传

hf upload <repo_id> . .                            # 当前目录到根目录
hf upload <repo_id> ./models /weights              # 文件夹到路径
hf upload <repo_id> model.safetensors              # 单个文件
hf upload <repo_id> . . --repo-type dataset        # 数据集
hf upload <repo_id> . . --create-pr                # 创建 PR
hf upload <repo_id> . . --commit-message="msg"     # 自定义消息

仓库管理

hf repo create <name>                              # 创建模型仓库
hf repo create <name> --repo-type dataset          # 创建数据集仓库
hf repo create <name> --private                    # 私有仓库
hf repo create <name> --repo-type space --space_sdk gradio  # Gradio 空间
hf repo delete <repo_id>                           # 删除仓库
hf repo move <from_id> <to_id>                     # 移动仓库到新命名空间
hf repo settings <repo_id> --private true          # 更新仓库设置
hf repo list --repo-type model                     # 列出仓库
hf repo branch create <repo_id> release-v1         # 创建分支
hf repo branch delete <repo_id> release-v1         # 删除分支
hf repo tag create <repo_id> v1.0                  # 创建标签
hf repo tag list <repo_id>                         # 列出标签
hf repo tag delete <repo_id> v1.0                  # 删除标签

从仓库删除文件

hf repo-files delete <repo_id> folder/             # 删除文件夹
hf repo-files delete <repo_id> "*.txt"             # 按模式删除

缓存管理

hf cache ls                      # 列出缓存的仓库
hf cache ls --revisions          # 包括单个修订版本
hf cache rm model/gpt2           # 移除缓存的仓库
hf cache rm <revision_hash>      # 移除缓存的修订版本
hf cache prune                   # 移除分离的修订版本
hf cache verify gpt2             # 从缓存验证校验和

浏览 Hub

# 模型
hf models ls                                        # 列出热门模型
hf models ls --search "MiniMax" --author MiniMaxAI  # 搜索模型
hf models ls --filter "text-generation" --limit 20  # 按任务过滤
hf models info MiniMaxAI/MiniMax-M2.1               # 获取模型信息

# 数据集
hf datasets ls                                      # 列出热门数据集
hf datasets ls --search "finepdfs" --sort downloads # 搜索数据集
hf datasets info HuggingFaceFW/finepdfs             # 获取数据集信息

# 空间
hf spaces ls                                        # 列出热门空间
hf spaces ls --filter "3d" --limit 10               # 按 3D 建模空间过滤
hf spaces info enzostvs/deepsite                    # 获取空间信息

作业（云计算）

hf jobs run python:3.12 python script.py           # 在 CPU 上运行
hf jobs run --flavor a10g-small <image> <cmd>      # 在 GPU 上运行
hf jobs run --secrets HF_TOKEN <image> <cmd>       # 带 HF 令牌
hf jobs ps                                         # 列出作业
hf jobs logs <job_id>                              # 查看日志
hf jobs cancel <job_id>                            # 取消作业

推理端点

hf endpoints ls                                     # 列出端点
hf endpoints deploy my-endpoint \
  --repo openai/gpt-oss-120b \
  --framework vllm \
  --accelerator gpu \
  --instance-size x4 \
  --instance-type nvidia-a10g \
  --region us-east-1 \
  --vendor aws
hf endpoints describe my-endpoint                   # 显示端点详情
hf endpoints pause my-endpoint                      # 暂停端点
hf endpoints resume my-endpoint                     # 恢复端点
hf endpoints scale-to-zero my-endpoint              # 缩放到零
hf endpoints delete my-endpoint --yes               # 删除端点

GPU 规格: cpu-basic, cpu-upgrade, cpu-xl, t4-small, t4-medium, l4x1, l4x4, l40sx1, l40sx4, l40sx8, a10g-small, a10g-large, a10g-largex2, a10g-largex4, a100-large, h100, h100x8

常见模式

下载并在本地使用模型

# 下载到本地目录用于部署
hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./model

# 或使用缓存并获取路径
MODEL_PATH=$(hf download meta-llama/Llama-3.2-1B-Instruct --quiet)

发布模型/数据集

hf repo create my-username/my-model --private
hf upload my-username/my-model ./output . --commit-message="初始发布"
hf repo tag create my-username/my-model v1.0

同步空间与本地

hf upload my-username/my-space . . --repo-type space \
  --exclude="logs/*" --delete="*" --commit-message="同步"

检查缓存使用情况

hf cache ls                      # 查看所有缓存的仓库和大小
hf cache rm model/gpt2           # 从缓存移除仓库

关键选项

--repo-type: model (默认), dataset, space
--revision: 分支、标签或提交哈希
--token: 覆盖认证
--quiet: 仅输出基本信息（路径/URL）

参考

完整命令参考: 见 references/commands.md
工作流示例: 见 references/examples.md