📦 HuggingfaceFull — 全功能HF中心

Token 范围： HF_TOKEN 仅在下载私有/门控模型、任何上传、仓库创建/删除以及 Space 管理时才需要。所有公开模型/数据集的浏览与下载均可免 token 使用。 --- ## 安全提示 - 在 shell 环境或 .env 文件中设置 HF_TOKEN——切勿将其硬编码到脚本里。

• 尽可能使用细粒度 token（只读或仓库范围），而非全权限写入 token。在 https://huggingface.co/settings/tokens 创建。
• 门控模型（Llama、Gemma 等）需要 token 并在 Hub 网页端接受模型条款后方可下载。
• HF_HUB_OFFLINE=1 将阻止所有网络调用——适用于缓存已预置的隔离或 CI 环境。 --- ## 安装 ### 最小安装 ``bash pip install huggingface_hub ` ### 推荐安装（含全部 extras） `bash pip install "huggingface_hub[cli,torch,tensorflow,fastai,dev]" ` | Extra | 新增功能 | |-------|----------| | cli | huggingface-cli 命令 | | hf_transfer | 基于 Rust 的高速多段下载（pip install hf_transfer） | | torch | PyTorch 模型辅助工具 | | tensorflow | TF 模型辅助工具 | | fastai | fastai 辅助工具 | ### 启用高速下载（可选） `bash pip install hf_transfer export HF_HUB_ENABLE_HF_TRANSFER=1 ` ### 验证安装 `bash huggingface-cli version huggingface-cli whoami # 需要 HF_TOKEN ` --- ## 身份验证 ### 登录（将 token 写入 ~/.cache/huggingface/token） `bash huggingface-cli login # 或非交互式： huggingface-cli login --token $HF_TOKEN ` ### 登出 `bash huggingface-cli logout ` ### 查看当前身份 `bash huggingface-cli whoami ` ### 环境变量（CI/脚本推荐） `bash export HF_TOKEN=hf_... ` 当该变量存在时，库会自动读取 HF_TOKEN，无需显式登录。 --- ## 下载模型与数据集 ### 下载整个模型仓库 `bash huggingface-cli download # 示例： huggingface-cli download google/gemma-2b ` ### 下载单个文件 `bash huggingface-cli download huggingface-cli download openai/whisper-large-v3 config.json ` ### 下载到指定目录 `bash huggingface-cli download --local-dir ./models/mymodel ` ### 下载数据集仓库 `bash huggingface-cli download --repo-type dataset ` ### 下载特定修订（分支、标签或提交 SHA） `bash huggingface-cli download --revision v1.0 huggingface-cli download --revision abc1234 ` ### 按文件模式（glob）下载 `bash huggingface-cli download --include ".safetensors" huggingface-cli download --exclude ".bin" --include ".safetensors" ` ### 下载门控模型（需 token + 已接受条款） `bash HF_TOKEN=hf_... huggingface-cli download meta-llama/Llama-3-8B ` --- ## 上传到 Hub ### 上传单个文件 `bash huggingface-cli upload huggingface-cli upload myorg/mymodel weights.safetensors model/weights.safetensors ` ### 上传整个文件夹 `bash huggingface-cli upload huggingface-cli upload myorg/mymodel ./model_dir . ` ### 上传到数据集仓库 `bash huggingface-cli upload myorg/mydataset ./data . --repo-type dataset ` ### 上传到 Space `bash huggingface-cli upload myorg/myspace ./app . --repo-type space ` ### 带提交信息上传 `bash huggingface-cli upload myorg/mymodel ./weights . --commit-message "Add fp16 weights" ` ### 上传大文件夹（分片、可续传） `bash huggingface-cli upload-large-folder myorg/mymodel --repo-type model ./large_model_dir ` --- ## 仓库管理 ### 创建仓库 `bash 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 ` ### 删除仓库 `bash huggingface-cli repo delete ` ### 查看仓库信息 `bash huggingface-cli repo info huggingface-cli repo info google/gemma-2b ` --- ## 标签 `bash huggingface-cli tag create --message "Release v1.0" huggingface-cli tag list huggingface-cli tag delete ` --- ## 缓存管理 ### 扫描缓存（查看本地已存内容） `bash huggingface-cli scan-cache ` ### 交互式删除无用缓存 `bash huggingface-cli delete-cache ` ### 显示缓存大小摘要 `bash huggingface-cli scan-cache --verbose ` --- ## Python API — 速用模式 完整示例代码见 templates/python_patterns.txt。核心入口： `python import os from huggingface_hub import HfApi api = HfApi(token=os.environ.get("HF_TOKEN")) ` 使用 scripts/hf_helper.py 作为 Python API 的 CLI 封装，用于搜索、信息查询与缓存操作，无需浏览器。 --- ## 环境变量 | 变量 | 默认值 | 说明 | |------|--------|------| | HF_TOKEN | — | 访问 token；私有/门控/写操作必需 | | HF_HOME | ~/.cache/huggingface | 根缓存目录 | | HF_HUB_CACHE | $HF_HOME/hub | 模型/数据集缓存 | | HF_DATASETS_CACHE | $HF_HOME/datasets | datasets 库缓存 | | HF_HUB_OFFLINE | 0 | 设为 1 以禁用所有网络调用 | | HF_HUB_ENABLE_HF_TRANSFER | 0 | 设为 1 以启用高速 Rust 下载器 | | HF_ENDPOINT | https://huggingface.co | 企业/镜像部署时可覆盖 | | HF_HUB_DISABLE_PROGRESS_BARS | 0 | 设为 1 以隐藏 tqdm 进度条（适合 CI 日志） | | HF_HUB_VERBOSITY | warning | 日志级别：debug、info、warning、error | | HUGGINGFACE_HUB_VERBOSITY | — | HF_HUB_VERBOSITY 的旧别名 | --- ## 最佳实践 ### 1. 需要可复现路径时优先使用 --local-dir 默认缓存使用内容寻址的软链接。当应用需要稳定、自包含目录时，使用 --local-dir ./models/name。 ### 2. 生产环境固定修订版本 生产下载务必传入 --revision 。main 等分支可变，可能在运行间静默更新。 ### 3. 用 --include/--exclude 跳过无需的权重 大模型常同时提供 .bin 与 .safetensors 格式，仅下载框架所需： `bash huggingface-cli download --include ".safetensors" --exclude "*.bin" ` ### 4. 离线前预填充缓存 `bash huggingface-cli download # 填充缓存 export HF_HUB_OFFLINE=1 # 后续加载仅使用缓存 ` ### 5. 使用最小权限的细粒度 token 在 https://huggingface.co/settings/tokens 按项目创建 token——只读 token 无法意外删除或覆盖仓库。 ### 6. 上传时一并提交模型卡 每次上传即一次 git 提交。在上传文件夹中包含 README.md（模型卡），使仓库立即可在 Hub 浏览。 ### 7. 大于 ~50 GB 模型使用 upload-large-folder upload-large-folder 采用分片上传，自动重试与去重，对比普通 upload 在超大 checkpoint 上更可靠。 --- ## 故障排除 | 现象 | 解决方法 | |------|----------| | 401 Unauthorized | 设置 HF_TOKEN 或执行 huggingface-cli login | | 门控模型 403 Forbidden | 先在 huggingface.co 接受模型条款，再重试 | | huggingface-cli: command not found | pip install "huggingface_hub[cli]" 并确保 pip bin 目录在 PATH | | 下载缓慢 | pip install hf_transfer 并设置 HF_HUB_ENABLE_HF_TRANSFER=1 | | OSError: [Errno 28] No space left | 运行 huggingface-cli delete-cache 释放缓存空间 | | 下载续传偏移错误 | 使用 --local-dir —— 默认缓存可能存在陈旧的部分 blob | | RepositoryNotFoundError | 检查仓库名拼写及 token 是否有访问权限 | | RevisionNotFoundError | 确认分支/标签/SHA 在 Hub 上存在 | | EntryNotFoundError | 该修订中无此文件；检查 huggingface-cli repo info | | 企业防火墙环境 | 设置 HF_ENDPOINT=https://your-mirror.internal` |