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 よりもはるかに高速です