Hugging Face 技能

该技能全面暴露 Hugging Face Hub 的能力 —— 同时支持 huggingface-cli 命令行工具和 huggingface_hub Python 库 —— 供每次助手交互调用。它从环境变量中读取 HF_TOKEN 以执行需认证的操作；公共只读操作无需 token 即可运行。

Token 权限范围：HF_TOKEN 仅在下载私有/受控模型、执行任意上传、创建/删除仓库，以及管理 Space 时必需。所有公开模型/数据集的浏览与下载均无需 token。

安全须知

• 请将 HF_TOKEN 设置于 Shell 环境或 .env 文件中 —— 切勿在脚本中硬编码。
• 尽可能使用细粒度 token（如只读权限或限定于特定仓库），而非全写权限 token。可在 https://huggingface.co/settings/tokens 创建。
• 受控模型（如 Llama、Gemma 等）不仅需要有效 token，还需在 Hub 网页界面中接受对应模型条款。
• HF_HUB_OFFLINE=1 将禁用全部网络请求 —— 适用于已预填充缓存的离线环境或 CI 场景，安全可靠。

安装

最小化安装

pip install huggingface_hub

推荐安装（含全部扩展组件）

pip install "huggingface_hub[cli,torch,tensorflow,fastai,dev]"

启用高速下载（可选）

pip install hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1

验证安装

huggingface-cli version
huggingface-cli whoami       # 需要设置 HF_TOKEN

认证

登录（token 将写入 ~/.cache/huggingface/token）

huggingface-cli login
# 或非交互式登录：
huggingface-cli login --token $HF_TOKEN

登出

huggingface-cli logout

查看当前身份

huggingface-cli whoami

环境变量方式（CI/脚本场景首选）

export HF_TOKEN=hf_...

库会自动读取 HF_TOKEN —— 当该环境变量已设置时，无需显式执行 login。

下载模型与数据集

下载完整模型仓库

huggingface-cli download 
# 示例：
huggingface-cli download google/gemma-2b

下载单个文件

huggingface-cli download  
huggingface-cli download openai/whisper-large-v3 config.json

下载至指定目录

huggingface-cli download  --local-dir ./models/mymodel

下载数据集仓库

huggingface-cli download  --repo-type dataset

下载指定版本（分支、标签或提交 SHA）

huggingface-cli download  --revision v1.0
huggingface-cli download  --revision abc1234

按通配符模式下载特定文件

huggingface-cli download  --include "*.safetensors"
huggingface-cli download  --exclude "*.bin" --include "*.safetensors"

下载受控模型（需 token + 已接受条款）

HF_TOKEN=hf_... huggingface-cli download meta-llama/Llama-3-8B

上传至 Hub

上传单个文件

huggingface-cli upload   
huggingface-cli upload myorg/mymodel weights.safetensors model/weights.safetensors

上传整个文件夹

huggingface-cli upload   
huggingface-cli upload myorg/mymodel ./model_dir .

上传至数据集仓库

huggingface-cli upload myorg/mydataset ./data . --repo-type dataset

上传至 Space

huggingface-cli upload myorg/myspace ./app . --repo-type space

带提交信息上传

huggingface-cli upload myorg/mymodel ./weights . --commit-message "Add fp16 weights"

上传大型文件夹（多段、可断点续传）

huggingface-cli upload-large-folder myorg/mymodel --repo-type model ./large_model_dir

仓库管理

创建仓库

huggingface-cli repo create 
huggingface-cli repo create my-model --type model
huggingface-cli repo create my-dataset --type dataset
huggingface-cli repo create my-space --type space

删除仓库

huggingface-cli repo delete 

获取仓库信息

huggingface-cli repo info 
huggingface-cli repo info google/gemma-2b

标签（Tags）

huggingface-cli tag create         --message "Release v1.0"
huggingface-cli tag list    
huggingface-cli tag delete   

缓存管理

扫描缓存（查看本地已存储内容）

huggingface-cli scan-cache

交互式清理未使用缓存项

huggingface-cli delete-cache

显示缓存大小摘要

huggingface-cli scan-cache --verbose

Python API — 快速使用模式

完整可复制粘贴代码见 templates/python_patterns.txt。核心入口如下：

import os
from huggingface_hub import HfApi

api = HfApi(token=os.environ.get("HF_TOKEN"))

可将 scripts/hf_helper.py 作为 Python API 的 CLI 封装，在不依赖浏览器的前提下完成搜索、信息查询及缓存操作。

环境变量

最佳实践

1. 生产环境中优先使用 --local-dir，避免依赖默认缓存路径以确保可复现性

默认缓存采用内容寻址符号链接。当应用需稳定、自包含的模型目录时，请使用 --local-dir ./models/name。

2. 生产环境下载务必固定版本（revision）

始终在生产环境中通过 --revision 显式指定版本。类似 main 的分支是可变的，可能在两次运行之间静默更新。

3. 使用 --include/--exclude 跳过无关权重文件

大型模型通常同时提供 .bin 和 .safetensors 格式。仅下载当前框架所需格式：

huggingface-cli download  --include "*.safetensors" --exclude "*.bin"

4. 离线前预先填充缓存

huggingface-cli download         # 填充本地缓存
export HF_HUB_OFFLINE=1                 # 后续加载将仅使用缓存

5. 使用最小权限的细粒度 token

请在 https://huggingface.co/settings/tokens 为各项目单独创建 token —— 只读 token 不可能误删或覆盖仓库。

6. 权重上传时同步提交模型卡片（Model Card）

每次上传即一次 Git 提交。请在上传目录中包含 README.md（即模型卡片），确保仓库在 Hub 上立即具备可浏览性。

7. 对超过 ~50 GB 的模型使用 upload-large-folder

upload-large-folder 采用多段上传机制，支持自动重试与去重 —— 相比普通 upload，对超大检查点（checkpoints）更可靠。

故障排查