huggingface-spaces

Hugging Face Spaces

Hugging Face Spaces は機械学習アプリケーションをホストします。現在は 100 万件以上あり、各 Space は Git リポジトリです。このスキルでは、Space の作成、ビルド、デバッグ、メンテナンスについて説明します。

0. 準備

まず、次のことを確認します。

1. hf CLI がインストールされているか確認します：which hf。インストールされていない場合は、pip install -U huggingface_hub を実行します。
2. ユーザーがログイン済みか確認します：hf auth whoami。ログインしていない場合は、hf auth login を実行します。URL とワンタイムコードが表示されるので、ユーザーに URL を開いてコードを入力するよう伝えます。その後、自動的にログインが完了します（OAuth のため、トークンは不要です）。または、書き込みスコープのトークンを https://huggingface.co/settings/tokens から取得し、--token とともに指定します。
3. whoami の canPay フラグと isPro フラグを確認します。これらは、後述するハードウェアの選択に関わります。無料（isPro=False）アカウントでホストできるのは、Static Spaces と最大 2 つの ZeroGPU Spaces のみです。

hf-cli スキルでは、すべての hf コマンドについてエージェントに説明しています。このスキルと併用することをおすすめします。hf skills add hf-cli でインストールできます（Claude Code にもユーザーレベルでインストールするには、--claude --global を追加します）。

1. Space とは

Space は、次の 3 種類の SDK のいずれかを使う Git リポジトリです。

• Gradio — 最も一般的な Space です。Python を使い、反復が速く、ZeroGPU をサポートします。
• Docker — 任意のコンテナを使用します。Python 以外のスタックや、ビルド済みのテンプレート（Streamlit、Argilla、Shiny など。完全な一覧は https://huggingface.co/docs/hub/spaces-sdks-docker を参照）が必要な場合に使用します。ZeroGPU はサポートしません。
• Static — プレーンな HTML、またはデプロイ時にビルドされる React／Svelte／Vue プロジェクトです。ブラウザー内での ML（transformers.js／WebGPU／WebAssembly／onnxruntime-web）、プロジェクトページ、インタラクティブなレポート、ほかの Spaces を連携させる Space に使用します。ハードウェアは不要です。

ハードウェアのプラン

Static Spaces は誰でも無料で利用でき、ハードウェアも必要ありません。Gradio と Docker の Spaces はコンピューティングリソース上で実行されるため、作成には有料プランが必要です。個人アカウントでは PRO、組織では Team または Enterprise が必要です。ただし、良好な状態にある無料の個人アカウント（メールアドレスの確認済みで、アカウント作成から 30 日以上経過）なら、最大 2 つの ZeroGPU Spaces をホストできます。

つまり、無料アカウントで Gradio Space をホストする唯一の方法は ZeroGPU です。cpu-basic は以前のような安全な代替手段ではなく、こちらも利用に制限があります。

ZeroGPU（zero-a10g） — NVIDIA RTX PRO 6000 Blackwell（sm_120）で、リクエストごとに動的に GPU を割り当てます。サイズは large（MIG の半分、48 GB、クォータ 1 倍）と xlarge（全体、96 GB、クォータ 2 倍）の 2 種類です。Space の作成者は無料で利用できます。Space の訪問者は、自分の日次クォータを消費します（無料プランは約 5 分／Pro は 40 分／Enterprise は 60 分）。Gradio 専用で、PyTorch を優先します。アカウントごとのホスト数上限は、無料の個人アカウントで 2、PRO で 10、Team／Enterprise の組織で 50 です。

cpu-basic — 2 vCPU／16 GB で、時間単位の料金はかかりませんが、有料プランが必要です。データ可視化、API プロキシの Spaces、小規模な CPU バウンドモデルに適しています。

専用 GPU（T4、L4、A10G、L40S、A100、H200）— Space の作成者に時間単位で課金されます。一覧と料金は hf spaces hardware で確認できます。これらを割り当てられるのは作成者のみで、canPay=True の場合に限られます。ZeroGPU が本当に適さない場合に使用します。たとえば、初期化に時間がかかる PyTorch 以外のメインモデルや、非常に大規模なモデルでの長いコンテキストの推論などです。

ユーザーが料金を支払えないハードウェア（専用 GPU、または無料プランの ZeroGPU 2 個の上限を超える Gradio Space）が必要な場合でも、無料で利用できる Static Space を作成し、そこにアプリをプッシュして、コミュニティ助成を申請できます。references/grants.md を参照してください。

正式なリファレンス：https://huggingface.co/docs/hub/spaces-overview

2. まず既存のデモを探す

何かをどう構築するか決める前に、先行事例を検索します。

hf spaces search "<model name or task>" --sdk gradio --limit 10

似た Space がすでに作られている場合は、その app.py と requirements.txt を確認します。動作する実装パターンを参考にでき、手探りでの試行錯誤を大幅に減らせます。方針を決める前に、見つけたものをユーザーに伝えてください。

3. SDK とハードウェアを決める

まず、ユーザーの明示的なリクエストに従ってください。内容が曖昧な場合は、次の方針を使います。

• 公開 ML デモのデフォルト：Gradio + ZeroGPU。以下の条件に当てはまらない限り、これを使います。
• モデルの推論経路が PyTorch 以外のみ（メインモデルに ONNX／TF／JAX／vLLM を使い、初期化が重い）：専用 GPU。
  • ただし、PyTorch がメインのパイプライン内で、小規模な ONNX 前処理や TF ユーティリティなど、PyTorch 以外のツールを補助的に使う程度であれば ZeroGPU で問題ありません。フックによる置き換えが行われるのは PyTorch のみです。@spaces.GPU 内で PyTorch 以外のライブラリを初期化し、呼び出しごとに短時間の初期化コストを負担してください。
• 小規模／CPU バウンドのモデル、または API プロキシの Space：cpu-basic。ただし、有料プランが必要です。無料アカウントでは、実際の処理を関数の外に置いたまま、何もしないデコレート済み関数を用意して zero-a10g に配置してください（ZeroGPU には少なくとも 1 つ必要です）。GPU をリクエストすることはないため、クォータは消費されません。references/inference-providers.md を参照してください。
• ブラウザー側で動作する ML またはプロジェクトページ：Static。
• Python 以外のスタックを使うコンテナー：Docker。

モデルの入手元

• GitHub リポジトリ — ローカルにクローンして、構成を確認します。すでに Gradio デモがある場合は、ZeroGPU に適応させるのが最小限の実用的な方法です（references/zerogpu.md を参照）。それ以外の場合は、README と推論コードを読み、PyTorch の経路を優先し、VRAM を見積もります（bf16 の場合は約 params_B × 2 GB。48 GB なら bf16 で最大 24B パラメーター、量子化すればさらに大規模なモデルに対応できます。ZeroGPU での量子化については references/zerogpu.md を参照してください）。
• HF モデルリポジトリ — README を読み、リンク先に GitHub があれば確認します。
• 論文／ブログ記事 — 公式または非公式の実装を探します。簡単な内容である場合や、ユーザーから明示的に依頼された場合を除き、再実装はしないでください。
• 曖昧なリクエスト — まず Spaces を検索し、結果を提示します。

モデルが実際に収まらない場合は、代替案として Inference Providers を確認してください。references/inference-providers.md を参照してください。これならモデルをホストせずに済みます。

4. Space を作成する

hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> \
    [--flavor zero-a10g|cpu-basic|<paid-flavor>] \
    [--secrets KEY=val] [--env KEY=val] \
    --public|--private|--protected \
    --exist-ok

• --space-sdk は必須です。
• --flavor でハードウェアを選択します。zero-a10g は ZeroGPU の（レガシーな）識別子です。省略すると cpu-basic になりますが、有料プランが必要なため、無料アカウントでは --flavor zero-a10g を明示的に指定してください。有料プランで選択できるハードウェアと料金の一覧は hf spaces hardware を実行して確認してください。
• 公開範囲：--public（誰でも閲覧可能）、--private（自分のみ）、--protected（アプリにはアクセスできますが、git リポジトリ／Files タブは非公開）。
• --secrets KEY=val は Space 内の環境変数になり、訪問者には表示されません。API キーやアクセス制限付きリポジトリのトークン（HF_TOKEN=hf_…）などに使用します。後から hf spaces secrets set <id> KEY=val で設定することもできます。
• --env KEY=val は訪問者に表示されます。機密性のない設定（GRADIO_SSR_MODE=false、PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True など）にのみ使用してください。

注：README の YAML に記載した hardware: は黙って無視されます。ハードウェアは作成時の --flavor、または作成後の hf spaces settings <id> --hardware <name> でのみ設定できます。

5. アプリを構築する

Space は https://huggingface.co/spaces/<namespace>/<name> に作成されますが、まだ空の状態です。

README.md のフロントマター

常に必須です。

---
title: ...
emoji: 🚀                # pick something representative
colorFrom: blue          # red|yellow|green|blue|indigo|purple|pink|gray (only these)
colorTo: indigo
sdk: gradio              # gradio | docker | static
sdk_version: 6.15.1      # latest stable unless you have a reason*
app_file: app.py         # gradio only (docker / static use Dockerfile / index.html)
short_description: ...   # ≤ 60 chars (server rejects longer)
python_version: "3.12"   # ZeroGPU officially supports 3.10.13 and 3.12.12
startup_duration_timeout: 30m   # default; bump to 1h for big LLMs / heavy downloads
---

* 現時点で最新の安定版をデフォルトとし、必ず現在のバージョンを確認してください（pip index versions gradio、または新規作成した Space でデフォルト設定されているバージョンを確認します）。上記の番号は古くなるプレースホルダーなので、使い回さないでください。最新バージョンでこの Space が実際に動作しない場合に限り、古いバージョンを固定します。カスタムコンポーネントを使う場合や、既存のデモを適応させる際に 5.x から 6.x への破壊的変更に対応したくない場合は、古いバージョンを使ってください。5.x が必要な場合は、シリーズの最新である 5.50.0 を選んでください（カスタムコンポーネントも引き続きサポートされます）。

フロントマターのすべてのオプション：https://huggingface.co/docs/hub/spaces-config-reference

最小構成の ZeroGPU Gradio アプリ

import spaces           # MUST come before torch / diffusers / transformers
import torch
import gradio as gr
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained("<repo>", torch_dtype=torch.bfloat16).to("cuda")

@spaces.GPU(duration=60)
def generate(prompt: str):
    """Generate an image from a text prompt."""   # docstring → API / MCP tool description
    return pipe(prompt).images[0]

gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch(mcp_server=True)

3 つのルールについて詳しくは、references/zerogpu.md をご覧ください。

1. torch や CUDA に触れるインポートより前に import spaces を記述します。 torch.cuda.* にモンキーパッチを適用するため、メインプロセスで CUDA が初期化された後では手遅れです。
2. モデルはモジュールスコープで読み込み、すぐに .to("cuda") を実行します。 ZeroGPU はこの呼び出しをインターセプトし、重みをディスクに格納して、最初の @spaces.GPU 呼び出し時に VRAM へストリーミングします。デコレーター内で遅延読み込みすると、ユーザーごとに読み込みが発生します。
3. Gradio がバインドする関数にデコレーターを適用します。 duration は現実的な最悪ケースを見積もって設定してください（値を小さくするとキューの優先度が上がり、クォータチェックが厳しくなります）。実行時間が入力に依存する場合は、呼び出し可能オブジェクトを渡してください。

例、docstring、MCP

• 適切な場合は gr.Examples を追加します（アプリが入力を受け取り、代表的な入力がある場合）。モデルやリポジトリの公式例を優先してください。例の行には、ユーザーが実際に変更する入力（プロンプト、画像）だけを含め、それ以外（ステップ数、シード、ガイダンス）はハンドラーのデフォルト値にして、入力が多すぎる行ではなく ["a prompt"] のようにします。cache_examples=True, cache_mode="lazy" を使用してください。references/gradio.md をご覧ください。
• API 経由で呼び出されるすべての関数に、docstring と型ヒントを付けます。 Gradio の各イベントハンドラーは API 経由で公開されるため、呼び出し元や MCP ツールのスキーマに表示されるのは docstring とシグネチャです。
• demo.launch(mcp_server=True) で起動します（Gradio 5 以降）。Space が MCP サーバーとしても機能し、各 API 関数が docstring と型ヒントで説明された MCP ツールになります。

requirements.txt

要点：

• 記載しないもの：gradio、spaces、huggingface_hub（プリインストール済みでプラットフォームが管理しています。バージョンを固定すると依存関係の解決に失敗したり、ZeroGPU のランタイムが気付かないうちに壊れたりするためです）。
• 使用する場合に記載するもの：torchvision、torchaudio（プリインストールされていません）、およびその他すべて（diffusers、transformers、accelerate、sentencepiece など）。
• ZeroGPU が受け付ける torch のバージョンは 2.8.0、2.9.1、2.10.0、2.11.0 のみです。デフォルトでは torch のバージョンを固定しないでください（ランタイムには最新バージョンがプリインストールされています）。依存関係によって必要な場合に限り、バージョンを固定します。
• ビルド済みの CUDA 拡張ホイール（flash_attn、xformers、pytorch3d、nvdiffrast、diff_gaussian_rasterization、torchmcubes）には、https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels にあるビルド済みの Blackwell ホイールを使用してください。対応表と注意事項の詳細は、references/requirements.md をご覧ください。

SDK ごとの詳細

• Gradio のパターン（テーマ、gr.Examples、ストリーミング、カスタム HTML コンポーネント、gr.Server）：references/gradio.md。
• Docker：https://huggingface.co/docs/hub/spaces-sdks-docker。例：`hf spaces list --filter docker`。
• Static：https://huggingface.co/docs/hub/spaces-sdks-static。ビルド済みの SPA では、フロントマターに app_build_command: npm run build と app_file: dist/index.html を設定します。
• ZeroGPU の詳細（デコレーターの動作、サイズ指定、AoTI、ジェネレーター、同時実行、ワーカー境界をまたぐ pickle / gr.State）：references/zerogpu.md。Space が ZeroGPU を対象とする場合は、必ずお読みください。

6. Space 上で反復し、ローカルでは行わない

ユーザーの依頼に基づいて、リリース候補をローカルでビルドしてプッシュし、ライブ URL をテストループとして使います。重要なのは Space 環境だけです。ローカルでテストしないでください。プッシュ前に行うローカルチェックは、python3 -m py_compile app.py が上限です。

hf upload <namespace>/<name> . --repo-type space でファイルをプッシュします。--repo-type space は必須です。hf upload はデフォルトで model リポジトリを対象とするため、指定しないと同じ名前の model リポジトリにアップロードされ、気づかないまま作成されることもあります。--exclude "**/__pycache__/**" を追加して、ローカルのバイトコードキャッシュが Space にコミットされないようにします。

プッシュ後は、変更ごとに最も手軽な更新方法を選びます。純粋な Python の編集にはホットリロード、ホットリロードで更新できないコードのみのファイルには hf upload を使い、requirements.txt／Dockerfile／README のフロントマターに実際に変更があった場合に限ってフルビルドを行います。完全な手順と注意点（ホットリロードによる factory reboot の不具合、runtime.sha の遅延など）については、references/debugging.md を参照してください。

7. 検証

RUNNING だけを信頼しないでください。アプリが実行中でも、壊れていることがあります。次の 4 つの手順を順番に行います。

A. 稼働しているか？ ステージとハードウェアを確認します。

hf spaces info <ns>/<name> --expand runtime

B. 起動後のログは正常か？ 実行ログを読み、警告や暗黙のフォールバックなしに起動が完了したことを確認します。

hf spaces logs <ns>/<name> --tail 200

モデルの読み込み完了、インポート時の警告がないこと、「CPU にフォールバック」や dtype のダウングレードに関するメッセージがないこと、そしてアプリが半ば壊れた状態なのに RUNNING がそれを隠していないことを確認します。

C. API は実際に応答するか？ 別のターミナルでログを引き続き監視しながら（hf spaces logs <ns>/<name> --follow）、エンドポイントを呼び出します。

from gradio_client import Client, handle_file
import os
c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"], httpx_kwargs={"timeout": 600})
print(c.view_api())                    # discover endpoints — don't guess
result = c.predict(..., api_name="/generate")

D. 出力とログの両方を確認する。 HTTP 200 でも、出力が正しいとは限りません。両方を確認します。

head = open(result, "rb").read(16)
# glTF / \x89PNG / RIFF…WEBP / RIFF…WAVE / [4:8]==b"ftyp" → png/jpg/webp/wav/mp4

呼び出し中に出力された実行ログも確認してください。暗黙のフォールバック（モデルサイズが別のサイズに切り替わる、オプションの依存関係が見つからない、dtype がダウングレードされるなど）は、ログにしか現れません。

完全なスモークテストのパターン（ストリーミングエンドポイント、OAuth で保護された Spaces、gr.Server のカスタムルート）については、references/debugging.md を参照してください。

8. 永続ストレージ（バケット）

Spaces はステートレスであり、再起動すると /data は消去されます。Space でユーザーのアップロード、生成データ、ログを保持する必要がある場合や、長期利用するストアと連携する場合は、バケットをマウントします。

hf buckets create <ns>/<bucket-name>                                          # --private optional
hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data   # read-write at /data

バケットは有料ストレージです。canPay を確認し、ユーザーに確認してください。完全なパターン（高速な読み込み／永続性を重視した書き込み、公開バケット URL、モデルキャッシュに関するアンチパターン）については、references/buckets.md を参照してください。

9. 問題が発生した場合

次の順序で対応します。

1. ログを読みます。hf spaces logs <id> --build --follow（ビルドエラー）または hf spaces logs <id> --follow（実行時エラー）を使います。最後ではなく、最初のエラーを探してください。
2. references/known-errors.md でエラー文字列を検索します。独自の修正を試す前に、既知の問題かどうかを確認してください。よくある ZeroGPU／Gradio／依存関係のエラーの大半は、ここに 1～2 行の修正方法があります。
3. references/debugging.md にある最も手軽な段階から反復します。問題の大半は、ログの確認とスモークテストの繰り返しで解決します。対話型開発モードと SSH は、負荷の大きい最終手段です。

既知のエラー一覧にないエラーを解決した場合は、今後の実行にも役立つよう、ユーザーにこのスキルへ PR を送ることを提案してください。

---

リファレンス一覧

読むタイミング	ファイル
ZeroGPU の仕組みと適切なパターン（デコレーター、サイズ設定、pickle、ジェネレーター、リアルタイム、AoTI）	references/zerogpu.md
反復とデバッグ：ログ、段階的な手順、スモークテスト（および最後の手段としての開発モードと SSH）	references/debugging.md
エラー文字列の検索 — すべてのエラー症状（Spaces、ZeroGPU、Gradio、依存関係）をまとめた唯一の場所	references/known-errors.md
依存関係の固定、ホイールの選択、torch 系パッケージの整合	references/requirements.md
gr.Examples（適切な場合に追加）、テーマ、カスタム HTML コンポーネント、gr.Server、MCP サーバー（mcp_server=True）	references/gradio.md
永続ストレージ、公開バケット URL	references/buckets.md
コミュニティ助成金の申請（ユーザーが費用を負担できないハードウェア）	references/grants.md
プロバイダープロキシ（Cerebras / Fireworks / Together などを使った、VRAM を消費しない大規模 LLM）	references/inference-providers.md
3D Spaces：生成、CUDA 拡張、出力形式、モデルのレシピ（ガウシアンスプラッティングを含む）	references/3d-generation.md