--- 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 ` | | 下载到文件夹 | `hf download --local-dir .\/path` | | 上传文件夹 | `hf upload . .` | | 创建仓库 | `hf repo create ` | | 创建标签 | `hf repo tag create ` | | 删除文件 | `hf repo-files delete ` | | 列出缓存 | `hf cache ls` | | 从缓存中移除 | `hf cache rm ` | | 列出模型 | `hf models ls` | | 获取模型信息 | `hf models info ` | | 列出数据集 | `hf datasets ls` | | 获取数据集信息 | `hf datasets info ` | | 列出空间 | `hf spaces ls` | | 获取空间信息 | `hf spaces info ` | | 列出端点 | `hf endpoints ls` | | 运行 GPU 作业 | `hf jobs run --flavor a10g-small ` | | 环境信息 | `hf env` | ## 核心命令 ### 身份验证 ```bash hf auth login # 交互式登录 hf auth login --token $HF_TOKEN # 非交互式登录 hf auth whoami # 检查当前用户 hf auth list # 列出存储的令牌 hf auth switch # 在令牌之间切换 hf auth logout # 登出 ``` ### 下载 ```bash hf download # 完整仓库到缓存 hf download file.safetensors # 特定文件 hf download --local-dir .\/models # 到本地目录 hf download --include "*.safetensors" # 按模式过滤 hf download --repo-type dataset # 数据集 hf download --revision v1.0 # 特定版本 ``` ### 上传 ```bash hf upload . . # 当前目录到根目录 hf upload .\/models \/weights # 文件夹到路径 hf upload model.safetensors # 单个文件 hf upload . . --repo-type dataset # 数据集 hf upload . . --create-pr # 创建 PR hf upload . . --commit-message="msg" # 自定义消息 ``` ### 仓库管理 ```bash hf repo create # 创建模型仓库 hf repo create --repo-type dataset # 创建数据集 hf repo create --private # 私有仓库 hf repo create --repo-type space --space_sdk gradio # Gradio 空间 hf repo delete # 删除仓库 hf repo move # 将仓库移动到新命名空间 hf repo settings --private true # 更新仓库设置 hf repo list --repo-type model # 列出仓库 hf repo branch create release-v1 # 创建分支 hf repo branch delete release-v1 # 删除分支 hf repo tag create v1.0 # 创建标签 hf repo tag list # 列出标签 hf repo tag delete v1.0 # 删除标签 ``` ### 从仓库删除文件 ```bash hf repo-files delete folder\/ # 删除文件夹 hf repo-files delete "*.txt" # 按模式删除 ``` ### 缓存管理 ```bash hf cache ls # 列出缓存的仓库 hf cache ls --revisions # 包含单个修订版本 hf cache rm model\/gpt2 # 移除缓存的仓库 hf cache rm # 移除缓存的修订版本 hf cache prune # 移除分离的修订版本 hf cache verify gpt2 # 从缓存验证校验和 ``` ### 浏览 Hub ```bash # 模型 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 # 获取空间信息 ``` ### 作业（云计算） ```bash hf jobs run python:3.12 python script.py # 在 CPU 上运行 hf jobs run --flavor a10g-small # 在 GPU 上运行 hf jobs run --secrets HF_TOKEN # 使用 HF 令牌 hf jobs ps # 列出作业 hf jobs logs # 查看日志 hf jobs cancel # 取消作业 ``` ### 推理端点 ```bash 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` ## 常见模式 ### 下载并本地使用模型 ```bash # 下载到本地目录用于部署 hf download meta-llama\/Llama-3.2-1B-Instruct --local-dir .\/model # 或使用缓存并获取路径 MODEL_PATH=$(hf download meta-llama\/Llama-3.2-1B-Instruct --quiet) ``` ### 发布模型\/数据集 ```bash hf repo create my-username\/my-model --private hf upload my-username\/my-model .\/output . --commit-message="Initial release" hf repo tag create my-username\/my-model v1.0 ``` ### 将空间与本地同步 ```bash hf upload my-username\/my-space . . --repo-type space \ --exclude="logs\/*" --delete="*" --commit-message="Sync" ``` ### 检查缓存使用情况 ```bash hf cache ls # 查看所有缓存的仓库和大小 hf cache rm model\/gpt2 # 从缓存中移除仓库 ``` ## 关键选项 - `--repo-type`: `model`（默认）, `dataset`, `space` - `--revision`: 分支、标签或提交哈希 - `--token`: 覆盖身份验证 - `--quiet`: 仅输出基本信息（路径\/URL） ## 参考 - **完整命令参考**：参见 [references\/commands.md](references\/commands.md) - **工作流示例**：参见 [references\/examples.md](references\/examples.md)