huggingface-hub

Hugging Face Hub 开发技能

何时使用此技能

当用户要求以下操作时，触发此技能：

• 向 Hugging Face API 发起 HTTP/curl 请求
• 使用 huggingface_hub Python 库上传或下载模型/数据集
• 使用 Inference Providers API（聊天补全、文本生成、图像生成）
• 创建或修改 Gradio 或 Docker Spaces 应用
• 使用 GGUF 模型、PEFT/LoRA 适配器或量化
• 使用 pandas、Polars 或 DuckDB 加载数据集
• 设置 Webhook、Jobs 或 CI/CD 自动化
• 配置模型卡、数据集卡或 Space YAML 元数据
• 使用 @huggingface/hub 或 Transformers.js JavaScript 包
• 设置身份验证、令牌或安全功能
• 在网站中嵌入 Spaces 或启用 OAuth 登录

快速参考

身份验证

# Python - Interactive login
from huggingface_hub import login
login()  # Opens browser or prompts for token

# Python - Programmatic login
login(token="hf_xxx")

# Environment variable (recommended for CI/production)
# export HF_TOKEN="hf_xxx"

# CLI login
huggingface-cli login

# Set token directly
huggingface-cli login --token hf_xxx

获取令牌：https://huggingface.co/settings/tokens

下载文件

from huggingface_hub import hf_hub_download, snapshot_download

# Single file
model_path = hf_hub_download(
    repo_id="user/model",
    filename="model.safetensors"
)

# Entire repository
local_dir = snapshot_download(repo_id="user/model")

# Specific revision
hf_hub_download(repo_id="user/model", filename="config.json", revision="v1.0")

# CLI download
huggingface-cli download HuggingFaceH4/zephyr-7b-beta
huggingface-cli download user/model model.safetensors

上传文件

from huggingface_hub import upload_file, upload_folder, HfApi

# Single file
upload_file(
    path_or_fileobj="model.safetensors",
    path_in_repo="model.safetensors",
    repo_id="user/model"
)

# Entire folder
upload_folder(
    folder_path="./my_model",
    repo_id="user/model"
)

# Using HfApi
api = HfApi()
api.create_repo(repo_id="user/new-model", repo_type="model")
api.upload_file(path_or_fileobj="model.pt", path_in_repo="model.pt", repo_id="user/new-model")

Inference Providers

import os
from huggingface_hub import InferenceClient

client = InferenceClient(api_key=os.environ["HF_TOKEN"])

# Chat completion (OpenAI-compatible)
response = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Text generation
response = client.text_generation(
    "The answer to the universe is",
    model="meta-llama/Llama-3.1-8B-Instruct"
)

# Image generation
image = client.text_to_image(
    "A serene mountain landscape at sunset",
    model="black-forest-labs/FLUX.1-schnell"
)

curl：

curl https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

加载数据集

import pandas as pd
import polars as pl

# Pandas with hf:// protocol
df = pd.read_parquet("hf://datasets/stanfordnlp/imdb/plain_text/train-00000-of-00001.parquet")

# Polars with hf:// protocol
df = pl.read_parquet("hf://datasets/stanfordnlp/imdb/plain_text/train-*.parquet")

# DuckDB
import duckdb
conn = duckdb.connect()
df = conn.execute("SELECT * FROM 'hf://datasets/stanfordnlp/imdb/plain_text/*.parquet' LIMIT 100").fetchdf()

Gradio Space（最简示例）

README.md：

---
title: My Space
emoji: 🚀
sdk: gradio
sdk_version: 5.0.0
app_file: app.py
---

app.py：

import gradio as gr
from transformers import pipeline

pipe = pipeline("text-classification", model="distilbert-base-uncased-finetuned-sst-2-english")

def classify(text):
    result = pipe(text)[0]
    return {result["label"]: result["score"]}

demo = gr.Interface(fn=classify, inputs="text", outputs="label")
demo.launch()

Space 配置

---
title: My Application
emoji: 🤗
colorFrom: blue
colorTo: purple
sdk: gradio              # gradio, docker, or static
sdk_version: 5.0.0
python_version: "3.10"
app_file: app.py
app_port: 7860           # Docker only
suggested_hardware: t4-small  # or cpu-basic, a10g-small, etc.
pinned: true
models:
  - openai-community/gpt2
datasets:
  - mozilla-foundation/common_voice_13_0
hf_oauth: true           # Enable HF OAuth
preload_from_hub:
  - user/model config.json,model.safetensors
---

硬件选项：

• CPU：cpu-basic、cpu-upgrade
• GPU：t4-small、t4-medium、l4x1、l4x4、a10g-small、a10g-large、a100-large
• TPU：v5e-1x1、v5e-2x2、v5e-2x4

模型卡元数据

---
language:
  - en
license: apache-2.0
library_name: transformers
pipeline_tag: text-classification
tags:
  - nlp
  - sentiment
datasets:
  - stanfordnlp/imdb
base_model: bert-base-uncased
metrics:
  - accuracy
---

资源

按主题整理的详细文档：

references/

• api-http.md - 所有端点的 curl/HTTP API 示例
• python-sdk.md - huggingface_hub Python 用法（下载、上传、HfApi）
• javascript-sdk.md - @huggingface/hub 和 Transformers.js
• inference-providers.md - InferenceClient 和提供商选择
• models-advanced.md - GGUF、PEFT/LoRA、量化格式
• datasets-workflows.md - pandas、Polars、DuckDB 数据工作流
• spaces-config.md - 完整的 YAML 配置参考
• spaces-gradio.md - 构建 Gradio Spaces
• spaces-docker.md - 使用机密和权限的 Docker Spaces
• spaces-integration.md - 嵌入、OAuth、MCP 服务
• automation.md - Webhook、Jobs、GitHub Actions
• security.md - 令牌、访问门控、扫描、SSO
• models.md - 模型仓库、模型卡和上传
• datasets.md - 数据集仓库和配置
• enterprise.md - Enterprise Hub 功能
• doc-syntax.md - Doc-builder Markdown 语法

examples/

• inference-curl.sh - 所有 API 的 完整 curl 示例
• jupyter-pandas.py - Jupyter + pandas 工作流
• browser-transformersjs.html - 使用 Transformers.js 在 浏览器中进行推理
• lora-peft-workflow.py - LoRA 适配器查找/加载/合并工作流
• webhooks-auto-retrain.py - 用于重新训练的 Webhook 自动化
• collections-api.py - 集合的创建与管理
• offline-setup.py - 离线/隔离网络环境设置
• space-embed-iframe.html - 网站的 嵌入模式
• gradio-image-classifier.py - 使用 gr.Interface 进行图像分类
• gradio-chat-interface.py - 使用 HF 模型的聊天界面
• upload-model.py - PyTorchModelHubMixin 完整示例
• download-files.py - 各种下载模式
• model-card.md - 带元数据的模型卡模板
• dataset-card.md - 带元数据的数据集卡模板

patterns/

• missing-features.md - iOS、Next.js、完全离线的变通方案

最佳实践

1. 始终使用环境变量存储令牌 - 切勿将 hf_xxx 令牌硬编码
2. 使用 .safetensors 格式 - 相比 .bin，此格式更适合模型权重
3. 添加全面的模型卡 - 包含预期用途、限制和训练数据
4. 在 Spaces 中固定 SDK 版本 - 确保可复现性
5. 使用 preload_from_hub - 通过预加载模型加快 Space 启动速度
6. 设置合适的硬件 - 根据计算需求进行匹配，以避免 OOM 错误
7. 使用细粒度令牌 - 尽量缩小生产应用的令牌权限范围
8. 数据集使用 Parquet - 处理大型数据时，它比 CSV 快得多