Hugging Face Spaces とは何か、どう使うか ?

#Hugging Face Spacesとは、正確には何でしょうか？

Space は、Hugging Face がホストする小さな Web アプリケーションです。技術的には、Hub 上のモデルやデータセットのリポジトリと同じく git リポジトリであり、アプリケーションのコード、依存関係ファイル、そして YAML ヘッダーで設定を記述した README が含まれています。このリポジトリにコミットがプッシュされるたびに、Hugging Face はアプリケーションを再ビルドして再起動します。一方、訪問者に見えるのは、入力欄、ボタン、結果が表示されたページだけです。

Hugging Face を初めて使う方は、モデルページとの違いを押さえておいてください。モデルページには、ダウンロードして使うファイル（重み、トークナイザー、設定）が置かれています。一方、Space はサーバー上でコードを実行し、モデルに何ができるかを見せてくれます。Hub 全般については「Hugging Face とは何か、どう使うか」のガイドで解説しています。ここでは Spaces のみを扱います。

公式ドキュメントでは、SDKと呼ばれる三種類のSpacesが用意されており、作成時に選択します。

Gradio

最も一般的なケースです。Gradioは、関数からWebインターフェースを生成するPythonライブラリです。入力にはテキストボックス、出力には画像、といった具合です。LLMや画像モデルのデモの多くはGradioのSpacesです。

Docker

この Space は Dockerfile からビルドされます。そのため、完全なチャットインターフェース、API サーバー、Python 以外の言語で書かれたツールなど、どのような Web アプリケーションでも実行できます。

Static HTML

計算サーバーを使わない、シンプルなHTML・CSS・JavaScriptのページです。ドキュメント、可視化、またはブラウザ内だけで完結するデモに便利です。

各 Space には、huggingface.co/spaces/所有者/名前 という形式の Hub 上のアドレスと、所有者-名前.hf.space という形式のアプリケーションへの直接アドレスがあります。Space は、公開（コードもアプリケーションも誰でも閲覧可能）、保護（コードは非公開、アプリケーションはアクセス可能）、非公開（所有者とその共同作業者のみ）のいずれかに設定できます。

#ステップ 1：ブラウザでデモを使う

Spaceを試すだけなら、ほとんどの場合アカウントは不要です。Spacesのトップページ（huggingface.co/spaces）では、キーワードやタスクで検索でき、トレンドや「いいね」の数で並べ替えることもできます。多くのモデルページでも、右側のカラムにそのモデルを使用しているSpacesの一覧が表示されます。

1. 01
   適切なSpaceを見つける

   モデルの提供元（組織の公式アカウント）が公開しているSpace、または多くのユーザーにフォローされているSpaceを優先してください。無名のアカウントによる新しいSpaceでも問題なく動作することはありますが、送信したデータをそのコードがどう扱うかはわかりません。
2. 02
   表示された状態を読み取る

   ページ上部のバッジに状態が表示されます：実行中（Running）、ビルド中（Building）、スリープ中（Sleeping）、一時停止中、またはエラーです。スリープ中のSpaceはアクセスすると起動しますが、アプリケーションが再起動するまでしばらく時間がかかることがあります。
3. 03
   リクエストを実行する

   各フィールドに入力して送信します。すべての訪問者でGPUを共有しているSpaceでは、処理の前に待機キューが表示されることがあります。
4. 04
   何をテストしているかを確認する

   Filesタブを開き、メインファイル（多くの場合app.py）とREADMEを確認します。どのモデルが、どの精度（FP16、4ビット量子化など）で、どのパラメーターで読み込まれているかがわかります。デモが、告知されているモデルの完全版であるとは限りません。

#ステップ2：Gradio SpaceをAPI経由で呼び出す

Gradio Spaceは単なるWebページではなく、APIも公開しています。アプリケーション下部の「Use via API」リンクから、利用可能なエンドポイントとコード例を確認できます。Pythonでは、公式ライブラリgradio_clientを使うとSpaceを関数のように呼び出せるため、手作業でクリックすることなく一連のサンプルでモデルをテストするのに便利です。

pip install gradio_client

from gradio_client import Client

# Remplacez par l'identifiant du Space (propriétaire/nom)
client = Client("proprietaire/nom-du-space")

# Affiche les points d'entrée et leurs paramètres
client.view_api()

パラメーターがわかったら、client.predict() メソッドで、必要な引数と view_api() が示す api_name を指定してリクエストを送信します。Space の利用上限や待ち行列は、ブラウザーからのアクセスと同様にこれらの呼び出しにも適用されます。そのため、大量の処理には向きません。プライベートな Space を使う場合や、認証を受ける場合（アカウントの ZeroGPU 利用枠を活用する場合）は、Client() に Hugging Face のアクセストークンを渡してください。

#ステップ3：Spaceを複製する

Space を複製すると、ご自身のアカウントに完全なコピーが作成されます。既存のデモをベースに改変したい場合や、すべての訪問者と待ち行列を共有せずに自分専用のインスタンスを使いたい場合に便利です。操作は、ページ右上の三点メニューから「Duplicate this Space」を選んで行います。

1. 01
   所有者と名前を選ぶ

   コピー先は、個人アカウント、または書き込み権限を持つ組織のいずれかにできます。
2. 02
   公開範囲を設定する

   コピーはデフォルトで非公開です。ご自身のデータを処理する予定であれば、非公開のままにしてください。
3. 03
   ハードウェアを選択する

   デフォルトでは、複製はCPU Basicで動作します。有料のGPUは、この時点で選択することも、後から設定（Settings）で選択することもできます。
4. 04
   シークレットを設定する

   元の Space の公開変数は自動的にコピーされます。シークレット（トークン、API キー）は決してコピーされません。入力が必要な場合はインターフェースに警告が表示されます。シークレットがないと、アプリケーションは起動しても最初のリクエストで失敗することがあります。

CPU Basic を超えるハードウェアは時間単位で課金されます。たとえばドキュメントでは、2026年10月26日時点で NVIDIA T4 small が1時間あたり 0.40 ドルとされています。最新の料金表全体は Hugging Face の料金ページに掲載されています。有料の Space は設定から一時停止でき、一時停止中の時間には課金されません。

#ステップ4：Hugging Face Spaceをローカルで実行する

公開 Space のコードは閲覧もクローンもできるため、ご自身のマシンで実行できます。方法は二つあります。Hugging Face がビルドした Docker イメージを取得する方法と、リポジトリをクローンしてアプリケーションをご自身で起動する方法です。

#方法 A：Space の Docker イメージ

ドキュメントによると、ほとんどのSpaceはDockerで実行できます。Spaceページ右上のメニューにある「Run with Docker」ボタンを押すと、コピーすべき正確なコマンドが表示されます。通常は次のような形式で、イメージはレジストリregistry.hf.spaceでホストされています：

docker run -it -p 7860:7860 --platform=linux/amd64 \
  registry.hf.space/proprietaire-nom-du-space:latest python app.py

コマンドは自分で組み立て直さず、必ずボタンで表示されるものをコピーしてください。イメージ名、起動コマンド、必要に応じて指定する変数（-e オプション。たとえば HF_TOKEN トークン用）は Space ごとに異なります。Space によっては、Hugging Face のユーザー名と、パスワード代わりのアクセストークンを使ってレジストリにログインする必要があります。

docker login registry.hf.space

コンテナでNVIDIAのグラフィックカードを使用するには、ホストマシンにNVIDIA Container Toolkitが必要で、docker runコマンドに--gpus allオプションを追加する必要があります。イメージはx86_64アーキテクチャ（linux/amd64）向けにビルドされているため、Apple Silicon搭載のMacではエミュレーション経由で動作し、MacのGPUにはアクセスできません。この場合は、一般的に方法Bのほうが適しています。

#方法 B：リポジトリをクローンしてアプリケーションを起動する

Space のメニューには、HTTPS または SSH による「Clone repository」もあります。Gradio の Space の場合、一般的な手順は、クローンし、独立した Python 環境を作成し、requirements.txt に記載された依存関係をインストールしてから、メインファイルを起動するというものです：

git clone https://huggingface.co/spaces/proprietaire/nom-du-space
cd nom-du-space
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gradio
python app.py

続いて Gradio がインターフェースのローカルアドレス（デフォルトは http://127.0.0.1:7860）を表示します。起動前に確認すべき点がいくつかあります。

README のヘッダー

sdk_version、app_file、場合によっては python_version の各キーは、オンラインで使用されている Gradio のバージョン、起動するファイル、Python のバージョンを示します。同じバージョンの Gradio をインストールする（pip install "gradio==X.Y.Z"）ことで、インターフェース関連の多くのエラーを回避できます。

大容量ファイル

Spaceには、Hubのストレージシステムで保存された大容量ファイルが含まれている場合があります。クローン後にファイルが小さなテキストのポインターとして表示される場合は、Hugging Faceが推奨するgit拡張機能（git-xetまたはGit LFS）をインストールし、ダウンロードをやり直してください。

@spaces.GPU デコレーター

ZeroGPU の Space は spaces モジュールをインポートし、関数を @spaces.GPU でデコレートしています。ドキュメントによると、このデコレーターは ZeroGPU 以外では何の効果もありません。spaces パッケージをインストール（pip install spaces）するだけで、コードはご自身の GPU で実行されます。

Secrets

コードが環境変数（os.getenv）を読み込む場合は、app.py を起動する前にターミナルで設定してください。アクセス条件付きのモデルには、ライセンスに同意したアカウントに紐づく Hugging Face トークンが必要です。

Docker Spaceの場合、クローンしたリポジトリにDockerfileが含まれています。docker buildに続けてdocker runを実行すれば十分です。その際、READMEのapp_portで宣言されたポート（デフォルトは7860）を公開してください。

#Hugging Face Spaces の制限：計算リソースと機密性

Space は第一印象をつかむには最適です。ただし日常的に使うとなると、すぐに制約が見えてきます。以下の制約は、2026年10月26日に参照した公式ドキュメントに基づいています。

控えめな無料ハードウェア

デフォルトのハードウェアである CPU Basic は、2 vCPU、16 GB の RAM、50 GB のディスクを備え、GPU はありません。数十億パラメーター規模の LLM は、メモリに収まったとしても、動作は遅くなります。

非永続ディスク

50 GBのディスクは再起動時に消去されます。所有者が永続ストレージを設定していない限り、アップロードしたファイルや生成されたファイルは保持されません。

スリープ

無料のハードウェアでは、使われていないSpaceは一定時間後にスリープ状態になり、次回のアクセス時に再起動が必要です。また、所有者が一時停止したり、削除したりすることもあります。今日利用できるデモが、明日にはなくなっているかもしれません。

ZeroGPU のクォータ

1日あたりのGPU時間はアカウントごとに制限されており（上記参照）、1リクエストあたりのGPU時間は、作成者がより長い時間を設定していない限り、デフォルトで60秒に制限されています。クォータは最初の使用から24時間後にリセットされます。

制限されたネットワーク

Space から外部へ通信できるのは、ポート 80、443、8080 のみです。別のポートのサービスに接続する必要があるアプリケーションは、そのままでは動作しません。

プライバシーに関するルールは単純です。Space に入力した内容はすべて、他人のコードを実行するサーバーに送信されます。そのコードはリクエストを記録したり、サードパーティの API に転送したり、アップロードされたファイルをセッション中保持したりする可能性があります。公開 Space であれば app.py を読んで確認できますが、保護された Space ではコードを見ることができません。したがって、顧客の文書、個人データ、プロプライエタリなコード、認証情報はデモに貼り付けないでください。

#ローカル実行を選ぶべき場合

賢明なのは、Spacesを使って判断し、その後ローカルに移行して作業することです。ローカルが明らかに優れている状況をいくつか挙げます。

機密データ

契約書、医療記録、社内のコードなど、ローカルモデルを使えば、何もお使いのマシンの外に出ません。

日常的な利用または大量の利用

ZeroGPU のクォータと待ち行列があるため、Space は継続的な利用には向きません。ローカルでは、唯一の制約はお使いのハードウェアです。

安定性が必要な場合

Space は、モデルやバージョンが変わったり、消えてしまったりすることがあります。ダウンロードして固定したモデルなら、再現性のある結果が得られます。

お使いのツールへの統合

Ollama は http://localhost:11434 でローカル API を公開しており、リモートサービスに依存することなく、Open WebUI、スクリプト、自動化処理から利用できます。

なお、LLMの場合、ローカルへの移行は必ずしもSpaceをクローンして行うわけではありません。多くのデモはsafetensors形式・FP16で完全なモデルを読み込んでおり、その場合7Bモデルの重みは約14 GBを占め、一般向けのほとんどのグラフィックカードの容量を超えます。同じモデルをGGUF形式のQ4_K_Mで量子化したバージョンであれば、必要なVRAMは約5 GBで、RTX 3060 12 GBで動作します。多くの場合、最も簡単なのは、Spaceが使用しているモデル名を控えておき、HubでそのGGUF版を探してOllamaにインポートする方法です。

3BモデルをQ4で量子化

VRAM 約 2 GB

7BをQ4で

約5 GB

14BをQ4で量子化

約9 GB（RTX 4070 12 GB）

Q4の32B

約 19 GB（RTX 4090 24 GB、または 24〜48 GB のユニファイドメモリを搭載した Mac M4 Pro）

70BのQ4量子化

約40 GB

#トラブルシューティング

ページに「Runtime error」と表示される

Spaceが起動時にクラッシュしています。Logsタブにアクセスできる場合は、そこで原因を確認できます。他の人のSpaceであれば、待つか、別のSpaceを探すか、Communityタブで問題を報告するしかありません。

GPUクォータ超過のメッセージ

本日の ZeroGPU クォータを使い切りました。まだの場合はログインするか、リセットを待つか、モデルをローカルで実行してください。

import après pip install のエラー

GradioまたはいずれかのライブラリのバージョンがSpaceのものと異なっています。新しい仮想環境で、READMEのsdk_versionとpython_versionに合わせてください。

ローカルで CUDA が見つからない

コードは NVIDIA GPU を前提としています。PyTorch が CUDA 対応でインストールされているか確認するか、実行速度の低下と引き換えに CPU（Mac では mps）を使うようコードを修正してください。

Docker イメージが拒否される、または見つからない

docker login registry.hf.space でレジストリにログインし、イメージ名が「Run with Docker」ボタンで表示される名前と一致していることを確認してください。

#さらに詳しく

このガイドでは Space を扱います。Hub 全体を理解したい場合、ファイル形式の違いを知りたい場合、デモからご自身の環境で動くモデルへ移行したい場合は、以下のガイドをご覧ください。