Hugging Faceとは｜使い方・料金とhf CLIの取得を実行結果で

Hugging Face は「AI の部品置き場（Hub）」と「部品を取り出して使う道具（ライブラリ）」の組み合わせです。モデルを作る人が Hub に置き、使う人は CLI や Python から取り出します。

flowchart TD
    A[作る人] -->|upload| H[(Hugging Face Hub)]
    H --> M[Models・Datasets]
    H --> S[Spaces<br>デモアプリ]
    M -->|hf download| U[使う人の PC]
    M --> I[Inference<br>Providers]
    I -->|API| U

よく調べられることの答えを先にまとめます。

確認環境：Ubuntu 24.04.5 LTS の上で、作業用フォルダーに Python 3.13.18 の venv を作り、huggingface_hub 2.4.0（hf CLI・hf-xet 1.7.1）と datasets 5.1.0（pyarrow 26.0.0・pandas 3.1.0）を入れました。HF_HUB_DISABLE_TELEMETRY=1 と HF_HOME（キャッシュとトークンの置き場所）は、最初の import より前に作業用フォルダーへ向けています。この環境から huggingface.co への接続は、通信の中継（プロキシ）で 403 Forbidden として止められました。止められた原文はそのまま載せ、回り込みはしていません。代わりに、Hub と同じ URL の形で応答する小さな模擬サーバー（読み取り専用）を 127.0.0.1 に自作し、HF_ENDPOINT でそこへつないで、本物の huggingface_hub・datasets が行う取得・キャッシュ・エラー処理を動かしました。表示されたエラー文はライブラリが出した原文で、模擬サーバーが付けた補足の行は省いています。アカウント作成・トークン作成・アップロード・Spaces の作成など、Hub への書き込みは一切していません。画面の手順・料金・制限は Hugging Face の公式ドキュメントと料金ページで確かめました。図は mermaid で描画を確かめています（確認日 2026年10月29日）。

Hugging Faceとは（Hub・ライブラリ・会社）

この節では、Hugging Face という名前が指す3つのもの（サービス・ライブラリ・会社）と、GitHub との違いが分かります。

「Hugging Face」は、ふつう Hugging Face Hub（huggingface.co）というサービスを指します。公式ドキュメントは Hub を「オープンな機械学習の基準となる AI プラットフォーム」と説明し、200万を超えるモデル、150万のデータセット、150万の AI アプリ（Spaces）を置いている、としています（2026年10月29日時点の記載）。

会社の成り立ちと2026年の動き

英語版 Wikipedia によると、Hugging Face は2016年に Clément Delangue・Julien Chaumond・Thomas Wolf の3人がニューヨークで創業し、最初は10代向けのチャットボットのアプリでした。その土台のモデルを公開したあと、機械学習のプラットフォームへ方向を変えています。2026年9月3日には、NVIDIA が公式ブログ「NVIDIA to Acquire Hugging Face」で、129億3,030万ドルでの買収を発表しました。同じ発表は「Hugging Face は AI のエコシステム全体に開かれたプラットフォームであり続ける」とし、NVIDIA の計算資源を使わなくても Hub で開発・公開できる、としています。手続きが完了したかどうかは、2026年10月29日時点で本記事では確かめていません。

GitHub との違い

transformers との関係：transformers は、Hub に置かれたモデルを読み込んで動かすライブラリの1つです。この記事は Hub というサービス全体の入口で、pipeline() でモデルを動かす書き方は、関連記事「Hugging Face transformers入門｜pipelineとタスク一覧」で扱っています。

Hugging Face Hubでできること（Models・Datasets・Spaces）

この節では、Hub の各機能が何のためにあり、アカウントが要るのはどこからかが分かります。

見る・探す・取得する（読み取り）は、公開されているものならアカウントなしでできます。置く・作る・ゲート付きのものを取る・有料の計算資源を使うときに、アカウントとトークンが要ります。

Hub と一緒に使う主なライブラリ

huggingface_hub（取得・検索・アップロード・キャッシュ管理の土台。hf コマンドもここ）、transformers（文章・画像・音声のモデルの推論と学習）、datasets（データセットの読み込みと変換）、tokenizers（トークン分割を速く行う）、diffusers（画像生成などの拡散モデル）、accelerate（CPU・GPU・複数 GPU の違いを吸収）が主なものです。

Hub の GGUF 形式の LLM を取って手元の PC で動かす方法は、関連記事「llama.cppとは｜使い方・ビルド・GGUF量子化とllama-server」と関連記事「Ollamaの使い方｜ローカルLLMのコマンド一覧とAPIの呼び方」で扱っています。

Hugging Faceの料金（無料でどこまで・PRO・Team・Enterprise）

この節では、月額のプランと、使った分だけかかる料金の区別、無料で使える範囲が分かります。

料金は「月額のプラン」と「計算資源の従量課金」の2本立てです。次の表は、2026年10月29日に料金ページ（huggingface.co/pricing）と公式ドキュメントで確かめた値で、米ドル・税別です。

従量課金になるもの

ZeroGPU の1日の枠

ZeroGPU は、GPU を使う関数が動いている間だけ GPU を割り当てる仕組みです。公式ドキュメントの枠は次のとおりで、枠は「最初に GPU を使ってからちょうど24時間後」に戻ります。

ZeroGPU の Spaces を置ける数は、無料の個人アカウントが2つ（メール確認済みで、作ってから30日を超えたアカウント）、PRO が10、Team・Enterprise の組織が50です。

無料で十分に試せるのは「公開モデルを手元に取って動かす」使い方です。月額がかかり始めるのは、Gradio・Docker の Spaces を自分で作るとき（PRO 以上）、推論 API を使うとき（クレジット）、GPU を時間で借りるときです。手元で LLM を動かすときの GPU メモリの見積もりは、関連記事「VRAMとは｜確認方法・必要量の目安とLLMの計算式をPythonで解説」で扱っています。

モデルの探し方とモデルカードの読み方

この節では、Hub でモデルを探すときの絞り込みと、モデルカードのどこを見ればよいかが、手元で読み取ったメタデータの実物で分かります。

モデルのページの「Model card」タブは、リポジトリの README.md です。先頭の --- で囲まれた YAML（メタデータ）が、ライセンス・言語・タスクの絞り込みや、ページ上部の表示に使われます。

メタデータの主な項目

手元の模擬 Hub に置いた README.md（YAML つき）を、huggingface_hub の ModelCard・DatasetCard で読み取った結果です。Hub がページに出す情報は、この YAML から来ています。

---
license: apache-2.0
language:
- ja
- en
library_name: transformers
pipeline_tag: text-classification
tags:
- demo
datasets:
- rjc-demo/tiny-dataset
base_model: rjc-demo/base-model
---
# tiny-model

from huggingface_hub import ModelCard, DatasetCard, hf_hub_download

card = ModelCard.load(hf_hub_download("rjc-demo/tiny-model", "README.md"))
d = card.data
print("card :", d.license, d.language, d.library_name, d.pipeline_tag, d.base_model, d.datasets)
dc = DatasetCard.load(hf_hub_download("rjc-demo/tiny-dataset", "README.md", repo_type="dataset"))
print("dcard:", dc.data.license, dc.data.task_categories, dc.data.size_categories)

card : apache-2.0 ['ja', 'en'] transformers text-classification rjc-demo/base-model ['rjc-demo/tiny-dataset']
dcard: cc-by-4.0 ['text-classification'] ['n<1K']

ライセンス・商用利用・ゲート付きモデルとトークン

この節では、Hugging Face のモデルを商用で使えるかの見分け方、ゲート付きモデルの取得の流れ、アクセストークンの作り方（公式の手順）が分かります。

Hugging Face のモデルを商用で使えるかどうかは、Hub ではなく、モデルごとのライセンスで決まります。ライセンスはモデルカードの license に識別子で書かれ、ページ上部にも表示されます。

• 派生モデルは、元のモデル（base_model）のライセンスも見ます。量子化版・ファインチューニング版のカードに license が書かれていない場合は、元のモデルの条件を引き継いでいると考えて確かめます。
• 学習データのライセンスは別です。データセットカードの license と、データの出どころを見ます。

ゲート付きモデル（Gated model）とは

ゲート付きモデルは、ファイルを取る前に「利用条件への同意と申請」が要るモデルです。公式ドキュメントによると、申請はブラウザからだけ行え、ログインしている必要があります。申請すると、ユーザー名とメールアドレスがモデルの作者に共有されます（作者が集めない設定にした場合を除く）。

1. 1ブラウザでログインし、モデルのページを開くゲート付きなら、利用条件と申請のフォームが出る
2. 2フォームに記入し「Agree and send request to access repo」を押す会社名・用途などを聞かれることがある
3. 3承認を待つ既定は自動承認。作者が手動承認にしていると時間がかかる
4. 4スクリプトから取るときはトークンでログインするhf auth login か、環境変数 HF_TOKEN か、token 引数

作者は承認後でも予告なくアクセスを止められ、IP アドレスで EU からの利用を制限するモデルもあります（公式ドキュメント）。申請を断られた場合は「Your request to access this repo has been rejected by the repo's authors.」と表示され、もう一度申請することはできません。

アクセストークンの作り方（公式の手順）

この記事ではトークンを作っていません。次は公式ドキュメント「User access tokens」で確かめた手順です。

手元ではトークンを保存していないため、ログイン状態を確かめるコマンドは次のとおりになりました。

$ hf auth whoami
Error: Not logged in. Run `hf auth login` first.

hf CLIの使い方（huggingface_hubのインストールと実行結果）

この節では、Hugging Face の公式 CLI（hf コマンド）の入れ方と、モデル・データセットを取得したときの実際の出力が分かります。

以前の huggingface-cli は、今は hf という名前のコマンドです。pip で huggingface_hub を入れると一緒に入ります。公式ドキュメントは、pip・Homebrew（brew install hf）・単体のインストーラーの3通りを案内しています。ここでは、作業用フォルダーの venv に入れました。

export HF_HUB_DISABLE_TELEMETRY=1       # import より前に設定する
export HF_HOME=/path/to/work/hf         # キャッシュとトークンの置き場所
python3 -m venv venv
./venv/bin/pip install huggingface_hub
./venv/bin/hf version

✓ hf version
  version: 2.4.0

hf env を実行すると、どこにキャッシュとトークンを置くか、テレメトリーが止まっているかを確かめられます（抜粋）。

$ hf env
- huggingface_hub version: 2.4.0
- Python version: 3.13.18
- Token path ?: /path/to/work/hf/token
- Has saved token ?: False
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /path/to/work/hf/hub
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: True
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10

huggingface.co への取得は中継で止められた（原文）

この環境から本物の Hub へ hf models info を送った結果です。Python の例外の最後の行と、同じ URL へ curl で送った結果を載せます。

$ hf models info openai-community/gpt2
...
httpcore2.ProxyError: 403 Forbidden
...
httpx2.ProxyError: 403 Forbidden

$ curl -sS https://huggingface.co/api/models/openai-community/gpt2
curl: (56) CONNECT tunnel failed, response 403

これは Hugging Face 側のエラーではなく、この作業環境の中継が接続を断ったものです。会社のネットワークで同じ ProxyError: 403 が出るときは、huggingface.co（とファイルの配信元）への通信が社内の規則で許可されているかを、ネットワークの管理者に確かめます。

模擬 Hub で動かした hf のサブコマンド

以降は、127.0.0.1 の模擬 Hub に HF_ENDPOINT=http://127.0.0.1:47171 でつないだ結果です。リポジトリ名の rjc-demo/… は手元で作ったもので、Hub には存在しません。

$ hf models info rjc-demo/tiny-model
{
  "id": "rjc-demo/tiny-model",
  "downloads": 42,
  "gated": false,
  "library_name": "transformers",
  "pipeline_tag": "text-classification",
  "private": false,
  "sha": "a3f9c2e8d47b51e0c6d2f8a9b7e4c1d0f5a6b8c2",
  "siblings": [
    { "rfilename": ".gitattributes", "size": 50 },
    { "rfilename": "README.md", "size": 368 },
    { "rfilename": "config.json", "size": 58 },
    { "rfilename": "model.safetensors", "size": 123 }
  ],
  "tags": [ "demo", "license:apache-2.0" ]
}

$ hf download rjc-demo/tiny-model
Fetching 4 files: 100%|██████████| 4/4 [00:00<00:00, 52.07it/s]
✓ Downloaded
  path: /path/to/work/hf/hub/models--rjc-demo--tiny-model/snapshots/a3f9c2e8d47b51e0c6d2f8a9b7e4c1d0f5a6b8c2

$ hf download rjc-demo/tiny-model config.json --revision v1.0
✓ Downloaded
  path: /path/to/work/hf/hub/models--rjc-demo--tiny-model/snapshots/1111111111111111111111111111111111111111/config.json

$ hf download rjc-demo/tiny-model --include "*.json" --local-dir ./tiny
Fetching 1 files: 100%|██████████| 1/1 [00:00<00:00, 134.55it/s]
✓ Downloaded
  path: /path/to/work/tiny

$ hf download rjc-demo/tiny-dataset --repo-type dataset
Fetching 3 files: 100%|██████████| 3/3 [00:00<00:00, 53.56it/s]
✓ Downloaded
  path: /path/to/work/hf/hub/datasets--rjc-demo--tiny-dataset/snapshots/a3f9c2e8d47b51e0c6d2f8a9b7e4c1d0f5a6b8c2

$ hf download rjc-demo/tiny-model --dry-run
[dry-run] Will download 0 files (out of 4) totalling 0.0.

最後の --dry-run は、すでにキャッシュにあるため「0 files」になりました。大きなモデルを取る前に、件数と合計サイズを確かめるのに使えます。

--local-dir を付けると、指定したフォルダーに実物のファイルが置かれ、その中に .cache/huggingface/ という管理用のフォルダーができました（公式ドキュメントの説明どおり）。アップロードの hf upload・リポジトリ作成の hf repos create は Hub への書き込みなので、この記事では実行していません。

Pythonでモデル・データセットを取得する（hf_hub_download・load_dataset）

この節では、Python の huggingface_hub と datasets でファイルとデータセットを取る書き方と、実行結果が分かります。

環境変数は import のときに読まれるため、HF_HUB_DISABLE_TELEMETRY や HF_HOME は import より前に設定します。公式ドキュメントも、import より前に os.environ を書く例を載せています。

import os
assert os.environ.get("HF_HUB_DISABLE_TELEMETRY") == "1"  # import より前に設定済みか確かめる
from huggingface_hub import HfApi, hf_hub_download

api = HfApi()
info = api.model_info("rjc-demo/tiny-model")
print("id:", info.id, "| sha:", info.sha[:7], "| pipeline:", info.pipeline_tag, "| tags:", info.tags)
print("files:", [s.rfilename for s in info.siblings])
print("search:", [m.id for m in api.list_models(search="tiny", limit=5)])

p = hf_hub_download("rjc-demo/tiny-model", "config.json")
print("main  :", open(p).read().strip())
p = hf_hub_download("rjc-demo/tiny-model", "config.json", revision="v1.0")
print("v1.0  :", open(p).read().strip())

id: rjc-demo/tiny-model | sha: a3f9c2e | pipeline: text-classification | tags: ['demo', 'license:apache-2.0']
files: ['.gitattributes', 'README.md', 'config.json', 'model.safetensors']
search: ['rjc-demo/tiny-model']
main  : {"model_type": "demo", "hidden_size": 2, "num_labels": 3}
v1.0  : {"model_type": "demo", "hidden_size": 2, "num_labels": 2}

同じ config.json でも、main と v1.0 で中身が違いました（num_labels が3と2）。main は作者が更新すると変わるため、本番で使うモデルは revision にタグかコミットのハッシュを書いて固定します。

データセットを load_dataset で読む

datasets の load_dataset は、データセットカードの configs（どのファイルが train・test か）を読み、表の形で返します。模擬 Hub のデータセット（CSV 2つ）を読んだ結果です。

from datasets import load_dataset

ds = load_dataset("rjc-demo/tiny-dataset")
print(ds)
print(ds["train"][0])
print(ds["train"].to_pandas())

DatasetDict({
    train: Dataset({
        features: ['text', 'label'],
        num_rows: 3
    })
    test: Dataset({
        features: ['text', 'label'],
        num_rows: 1
    })
})
{'text': 'とても良い', 'label': 1}
    text  label
0  とても良い      1
1  最悪だった      0
2   普通です      1

データセットの README の YAML に、train と test のファイルを書いておくと、この分け方になります。

configs:
- config_name: default
  data_files:
  - split: train
    path: data/train.csv
  - split: test
    path: data/test.csv

Hub に送られるリクエストの中身

模擬 Hub のログには、取得のたびに次の順でリクエストが届きました（コミットのハッシュは <sha> と略しています）。

GET  /api/models/rjc-demo/tiny-model/revision/main                 200
GET  /api/models/rjc-demo/tiny-model/tree/<sha>?recursive=true     200
HEAD /rjc-demo/tiny-model/resolve/<sha>/config.json                200
GET  /rjc-demo/tiny-model/resolve/<sha>/config.json                200
User-Agent: huggingface-cli/None; hf_hub/2.4.0; python/3.13.18
User-Agent: datasets/5.1.0; hf_hub/2.4.0; python/3.13.18; pyarrow/26.0.0

• 最初に「main が今どのコミットか」を聞き、以降はそのコミットのハッシュでファイルを取ります。途中で作者が更新しても、1回の取得の中で版が混ざりません。
• ファイルごとに HEAD で大きさと ETag（中身の指紋）を確かめ、キャッシュにあれば本体の GET を省きます。
• User-Agent には、ライブラリと Python の版が入りました。テレメトリーを止めた状態では、torch の版や、AI エージェントから動かしているかの情報は付きません（huggingface_hub のソースコード）。なお hf CLI は起動時に、エージェントの一覧（/api/agent-harnesses）を読み取りで1回取りに行きました（1日1回までキャッシュする作り）。

キャッシュの場所と中身（HF_HOME・blobs・snapshots・オフライン）

この節では、ダウンロードしたモデルがどこに、どんな形で置かれるかと、ネットにつながらないときの挙動が、実物で分かります。

既定の置き場所は ~/.cache/huggingface/hub で、環境変数 HF_HOME（または HF_HUB_CACHE）で変えられます。ホームの容量が小さい PC や、共有サーバーで人ごとに分けたいときは、最初に HF_HOME を大きなディスクへ向けておきます。

hub/
├── models--rjc-demo--tiny-model/
│   ├── blobs/                 ← ファイルの実体（名前は中身のハッシュ）5個
│   ├── refs/
│   │   ├── main               ← 中身は a3f9c2e8d47b51e0c6d2f8a9b7e4c1d0f5a6b8c2
│   │   └── v1.0               ← 中身は 1111111111111111111111111111111111111111
│   └── snapshots/
│       ├── a3f9c2e8.../       ← main の版（4ファイル）
│       │   ├── config.json -> ../../blobs/5c9a9a2a...
│       │   └── model.safetensors -> ../../blobs/34171aff...
│       └── 1111.../           ← v1.0 の版
└── datasets--rjc-demo--tiny-dataset/
    └── snapshots/a3f9c2e8.../data/train.csv -> ../../../blobs/9ae8f8ee...

hf cache で一覧・削除する

出力は列の幅をそろえて一部の行を省いています。

$ hf cache ls
ID                           SIZE LAST_ACCESSED     LAST_MODIFIED     REFS
--------------------------- ----- ----------------- ----------------- ----------
dataset/rjc-demo/tiny-da... 336.0 a few seconds ago a few seconds ago main
model/rjc-demo/tiny-model   657.0 a few seconds ago a few seconds ago main, v1.0

Found 2 repo(s) for a total of 3 revision(s) and 993.0 on disk.

$ hf cache ls --revisions
ID                          REVISION                     SIZE LAST_MODIFIED REFS
model/rjc-demo/tiny-model   111111111111111111111111...  58.0 4 minutes ago v1.0
model/rjc-demo/tiny-model   a3f9c2e8d47b51e0c6d2f8a9... 599.0 4 minutes ago main

$ hf cache rm model/rjc-demo/tiny-model --dry-run
About to delete 1 repo(s) totalling 657.0.
  - model/rjc-demo/tiny-model (entire repo)
✓ Dry run: no files were deleted.

キャッシュを消すときは、フォルダーを直接 rm するより hf cache rm を使うと、リンクと実体の対応を崩さずに消せます。--dry-run で消える量を先に見て、確認の質問を省くとき（自動化のスクリプトなど）は --yes を付けます。

オフラインのときの挙動（実測）

模擬 Hub を止めた状態で、キャッシュにある config.json と、キャッシュに無い tokenizer.json を取りに行きました。

### Hub に接続できない（HF_HUB_OFFLINE なし）
'[Errno 111] Connection refused' thrown while requesting HEAD http://127.0.0.1:47171/rjc-demo/tiny-model/resolve/main/tokenizer.json
Retrying in 1s [Retry 1/5].
Retrying in 2s [Retry 2/5].
Retrying in 4s [Retry 3/5].
Retrying in 8s [Retry 4/5].
Retrying in 8s [Retry 5/5].
config.json OK 202 ms
tokenizer.json LocalEntryNotFoundError 23199 ms
 An error happened while trying to locate the file on the Hub and we cannot find the requested files in the local cache. Please check your connection and try again or make sure your Internet connection is on.

### HF_HUB_OFFLINE=1
config.json OK 68 ms
tokenizer.json LocalEntryNotFoundError 0 ms

ネットにつながらない環境で動かすときは、先に必要なファイルを取っておき、本番では HF_HUB_OFFLINE=1 を付けます。付けないと、キャッシュに無いファイルを探すたびに再試行で20秒以上待つことになりました。CLI で同じことをすると、次の文言になりました。

$ HF_HUB_OFFLINE=1 hf download openai-community/gpt2 config.json
Error: Local entry not found. Cannot reach https://huggingface.co/openai-community/gpt2/resolve/main/config.json: offline mode is enabled. To disable it, please unset the `HF_HUB_OFFLINE` environment variable.

Hugging Face Spacesとは（Gradio・Docker・Streamlit・ZeroGPU）

この節では、Spaces で何ができ、作成するときに何を選ぶのか、無料でどこまで使えるのかが分かります。

Spaces は、機械学習のデモアプリを Hub の上で動かして公開する仕組みです。Space の中身は Git のリポジトリで、コミットするたびに自動で作り直され、再起動します（公式ドキュメント）。

• Streamlit を組み込みの SDK として選ぶ方法は非推奨になりました。公式ドキュメントは「Docker SDK を選び、Streamlit のテンプレートを使う」ように案内しています。Streamlit の Space はポート8501だけが使えます。
• Space の公開範囲は、公開（public）・保護（protected。コードは非公開でアプリは公開。PRO 以上）・非公開（private。他人には404）の3つです。
• 既定のハードウェアは CPU Basic（2コア・16GB の RAM・50GB の消える保存領域）。無料のハードウェアでは、使われない時間が続くとスリープします。
• API キーなどの秘密の値は Settings の Secrets に入れます。Variables は公開されて複製先にもコピーされるため、秘密の値を入れません。

Space の設定は README の YAML

Space の名前・SDK・起動するファイルは、README.md の先頭の YAML で決まります。huggingface_hub の SpaceCard で読み取った結果です（Space は作成していません）。

from huggingface_hub import SpaceCard
card = SpaceCard("""---
title: 感情分析デモ
emoji: 🙂
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
license: apache-2.0
models:
- rjc-demo/tiny-model
---
# 感情分析デモ
""")
d = card.data
print(d.title, d.sdk, d.sdk_version, d.app_file, d.license, d.models)

感情分析デモ gradio 5.49.1 app.py apache-2.0 ['rjc-demo/tiny-model']

作成の流れは、公式ドキュメントでは「Spaces のページで Create new Space を押す→名前・ライセンス（任意）・公開範囲を決める→SDK を選ぶ」で、ハードウェアはあとから Settings で変えます。Gradio のアプリそのものの書き方と、Spaces への置き方は、関連記事「Gradioとは｜使い方・API呼び出し・Spaces公開をPythonで実演」で扱っています。

Inference Providersで推論APIを呼ぶ（料金・トークン・コード）

この節では、Hugging Face の推論 API（Inference Providers）の仕組み、料金のかかり方、呼び出しのコードが分かります。外部の API は呼んでいないため、公式ドキュメントで確かめた範囲です。

Inference Providers は、Groq・Together・Cerebras・Replicate など複数の推論事業者のモデルを、Hugging Face の1つの API から呼べるサービスです。OpenAI の Chat Completions と同じ形の口（https://router.huggingface.co/v1）があり、既存の OpenAI のクライアントのまま base_url を差し替えて使えます。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key=os.environ["HF_TOKEN"],      # fine-grained で「Make calls to Inference Providers」
)
completion = client.chat.completions.create(
    model="openai/gpt-oss-120b:fastest",  # :cheapest・:preferred・:groq などでも指定できる
    messages=[{"role": "user", "content": "How many 'G's in 'huggingface'?"}],
)
print(completion.choices[0].message)

• モデル名の後ろの :fastest は「1秒あたりのトークン数が最も多い事業者」、:cheapest は「出力トークンの単価が最も安い事業者」を選びます。何も付けないと :fastest と同じです。
• 料金は事業者の価格そのままで、Hugging Face は上乗せしない、と公式は書いています。自分の事業者のキーを登録する方式（Custom Provider Key）では、請求は事業者から直接来て、月の枠は使えません。
• 専用の推論サーバーを時間で借りる Inference Endpoints は別のサービスで、料金ページでは0.033ドル/時からです。

社内の情報を API に送る前に、送ってよい情報かを社内の規則で確かめます。手元で動かして外へ出さない方法を選ぶなら、Hub からモデルを取ってローカルで推論します。どちらを選ぶかの考え方は、関連記事「RAGとファインチューニングの違いと使い分け判断基準の早見表」も参考になります。

Hugging Faceを安全に使う（pickle・safetensors・トークン・テレメトリー）

この節では、Hub のモデルを取って使うときに気をつける点と、Hub 側の検査の範囲が分かります。

重みのファイルが pickle 形式（.bin・.pt・.pkl など）の場合、読み込むときにコードが実行される可能性があります。公式ドキュメントは「信頼できない出どころの pickle を読み込まない」と書き、代わりの形式として safetensors を挙げています。

safetensors の中身を見る

手元の model.safetensors の先頭を、Python の標準ライブラリだけで読みました。先頭8バイトが見出しの長さ、その後ろが JSON の見出しです。

import json, struct, sys
with open(sys.argv[1], "rb") as f:
    n = struct.unpack("<Q", f.read(8))[0]   # 見出しの長さ（リトルエンディアンの64ビット）
    print("header bytes:", n)
    print(json.dumps(json.loads(f.read(n))))

header bytes: 99
{"w": {"dtype": "F32", "shape": [2, 2], "data_offsets": [0, 16]}, "__metadata__": {"format": "pt"}}

テンソルの名前・型・形・位置しか入っていないことが分かります。大きなモデルでも、この見出しを読めば、どの層が何バイトかを、重みを読み込まずに確かめられます。

Hub 側の検査

• 1pickle の import の検査アップロードされた pickle が参照する import の一覧を、実行せずに取り出してファイルの横に表示する。怪しい import は強調される
• 2ウイルス対策の検査（ClamAV）全ファイルが対象。ただし pickle を使った攻撃は対象外と公式は書いている
• 3検査は完全ではない公式も「100%確実ではない」としている。信頼できる作者・組織のものを選び、署名付きコミットも手がかりにする
• 4アップロード前に機密を確かめるリポジトリは既定で公開になりうる。社内データ・個人情報・キーを含めない。Spaces には秘密の値の検査もある

テレメトリーを止める

Hugging Face のライブラリ（transformers・datasets・gradio など）は、既定で利用状況の一部を送ります。公式ドキュメントによると、HF_HUB_DISABLE_TELEMETRY=1（または DO_NOT_TRACK=1）で、Hugging Face の Python ライブラリ全体のテレメトリーを止められます。この値は import のときに読まれるため、シェルの環境変数か、スクリプトの先頭（import より前）で設定します。手元の hf env でも HF_HUB_DISABLE_TELEMETRY: True になっていることを確かめました。

よくあるエラーと原因（Hugging Faceの取得エラー原文）

この節では、Hub からの取得で出るエラーの原文と、それぞれの原因・直し方が分かります。

huggingface_hub のエラーは、例外の名前で原因を見分けられます。Python の例外と、同じ状況での hf CLI の表示です（URL の部分は手元の模擬 Hub のもの）。

--- gated: GatedRepoError
401 Client Error.

Cannot access gated repo for url http://127.0.0.1:47171/rjc-demo/gated-model/resolve/main/config.json.

--- notfound: RepositoryNotFoundError
401 Client Error.

Repository Not Found for url: http://127.0.0.1:47171/rjc-demo/no-such-model/resolve/main/config.json.
Please make sure you specified the correct `repo_id` and `repo_type`.
If you are trying to access a private or gated repo, make sure you are authenticated and your token has the required permissions.
For more details, see https://huggingface.co/docs/huggingface_hub/authentication

--- revision: RevisionNotFoundError
404 Client Error.

Revision Not Found for url: http://127.0.0.1:47171/rjc-demo/tiny-model/resolve/v9.9/config.json.

--- entry: RemoteEntryNotFoundError
404 Client Error.

Entry Not Found for url: http://127.0.0.1:47171/rjc-demo/tiny-model/resolve/main/pytorch_model.bin.

--- badid: HFValidationError
Repo id must be in the form 'repo_name' or 'namespace/repo_name': 'https://huggingface.co/rjc-demo/tiny-model'. Use `repo_type` argument if needed.

$ hf download rjc-demo/gated-model config.json
Error: Access denied. Model 'rjc-demo/gated-model' requires approval.

$ hf download rjc-demo/tiny-model pytorch_model.bin
Error: File not found in model 'rjc-demo/tiny-model'.

$ hf download rjc-demo/tiny-model config.json --revision v9.9
Error: Revision not found in model 'rjc-demo/tiny-model'.

$ hf download rjc-demo/tiny-dataset README.md
Error: Model 'rjc-demo/tiny-dataset' not found.
If the repo is private, make sure you are authenticated and your token has the required permissions.
If the repo does not exist, create it with: hf repos create rjc-demo/tiny-dataset

「データセットを取ろうとして Model ... not found」になるのは、repo_type の付け忘れです。手元でも、データセットの名前を repo_type なしで指定すると、モデルとして探されて RepositoryNotFoundError になりました。CLI は --repo-type dataset、Python は repo_type="dataset" を付けます。

判断表：Hugging Faceのどの機能を使うか

この節では、やりたいことから、Hugging Face のどの機能・プランを選べばよいかが分かります。

よくある質問

Q. Hugging Face とは何ですか？ A. AI のモデル・データセット・デモアプリ（Spaces）を共有する Hub と、それを使うためのライブラリ、推論の有料サービスをまとめた名前です。運営は2016年創業の Hugging Face, Inc. です。

Q. Hugging Face は無料で使えますか？ A. 公開されているモデル・データセットの検索と取得は無料で、アカウントも要りません。PRO（月9ドル）などの有料プランは、Spaces の作成・GPU の枠・推論のクレジット・非公開の保存量を増やすためのものです（2026年10月29日時点）。

Q. アカウントは必要ですか？ A. 公開モデルを取るだけなら不要です。ゲート付きモデルの申請、非公開リポジトリ、アップロード、Spaces の作成、Inference Providers にはアカウントとトークンが要ります。

Q. Hugging Face のモデルは商用利用できますか？ A. モデルごとのライセンスで決まります。apache-2.0・mit は商用可、cc-by-nc-4.0 は非営利だけ、Llama・Gemma などは独自の条件があります。派生モデルは元のモデル（base_model）の条件も確かめます。

Q. ダウンロードしたモデルはどこにありますか？ A. 既定では ~/.cache/huggingface/hub の下の models--作者--名前 フォルダーです。実体は blobs に、版ごとのファイルは snapshots にリンクとして並びます。hf cache ls で一覧できます。

Q. huggingface-cli と hf の違いは？ A. 今の公式の CLI は hf です。ログインは hf auth login、取得は hf download、キャッシュの管理は hf cache です。以前の記事の huggingface-cli のコマンドは、hf の対応するサブコマンドに読み替えます。

Q. ゲート付きモデルが「Access denied」で取れません。 A. ブラウザでログインしてモデルのページから申請し、承認されているかを確かめます。承認後は、hf auth login か環境変数 HF_TOKEN でトークンを渡します。作者が手動承認にしていると、承認まで時間がかかります。

Q. Spaces は無料で作れますか？ A. 2026年10月29日時点の公式ドキュメントでは、静的 HTML の Space は誰でも無料で作れ、Gradio・Docker の Space の作成は PRO 以上です。無料の個人アカウントでも、ZeroGPU の Gradio の Space は2つまで置けます。

Q. 会社のネットワークで ProxyError: 403 Forbidden になります。 A. 社内の中継が huggingface.co への接続を通していない状態です。手元の環境でも同じ原文になりました。勝手に回避せず、ネットワークの管理者に、許可してよい通信先かを確かめます。

まとめ

• Hugging Face は、モデル・データセット・Spaces を共有する Hub と、transformers・datasets・huggingface_hub などのライブラリ、推論の有料サービスの集まり。公開モデルの検索と取得はアカウントなしで無料。
• 料金は、月額のプラン（PRO 9ドル・Team 1人20ドル・Enterprise 1人50ドル）と、Spaces の GPU・Inference Providers・Inference Endpoints の従量課金の2本立て（2026年10月29日時点）。
• 商用利用はモデルごとのライセンスで決まる。ゲート付きモデルはブラウザで申請し、承認後にトークンで取る。トークンは用途ごとに作り、本番は fine-grained。
• 手元では、取得のたびに main のコミットを確かめてから版を固定して取り、キャッシュは blobs（実体）と snapshots（リンク）に分かれ、7ファイルが5個の実体にまとまった。本番の版は revision で固定する。
• オフラインでキャッシュに無いファイルは、HF_HUB_OFFLINE なしだと再試行で23.2秒待って失敗した。ネットの無い本番は先に取得して HF_HUB_OFFLINE=1 を付ける。エラーは例外名（GatedRepoError・RepositoryNotFoundError など）で見分ける。

次に読むとよい記事です。取得したモデルを動かすなら関連記事「Hugging Face transformers入門｜pipelineとタスク一覧」、デモを作るなら関連記事「Gradioとは｜使い方・API呼び出し・Spaces公開をPythonで実演」で扱っています。

参考・出典

確認日はいずれも 2026年10月29日です。

• Hugging Face「Hugging Face Hub documentation」：https://huggingface.co/docs/hub/index
• Hugging Face「Pricing」：https://huggingface.co/pricing
• Hugging Face「Storage limits」：https://huggingface.co/docs/hub/storage-limits
• Hugging Face「Model Cards」：https://huggingface.co/docs/hub/model-cards
• Hugging Face「Licenses」：https://huggingface.co/docs/hub/repositories-licenses
• Hugging Face「Gated models」：https://huggingface.co/docs/hub/models-gated
• Hugging Face「User access tokens」：https://huggingface.co/docs/hub/security-tokens
• Hugging Face「Pickle Scanning」：https://huggingface.co/docs/hub/security-pickle
• Hugging Face「Spaces Overview」：https://huggingface.co/docs/hub/spaces-overview
• Hugging Face「Streamlit Spaces」：https://huggingface.co/docs/hub/spaces-sdks-streamlit
• Hugging Face「Spaces ZeroGPU」：https://huggingface.co/docs/hub/spaces-zerogpu
• Hugging Face「Inference Providers」：https://huggingface.co/docs/inference-providers/index
• Hugging Face「Pricing and Billing（Inference Providers）」：https://huggingface.co/docs/inference-providers/pricing
• Hugging Face「Command Line Interface (CLI)」：https://huggingface.co/docs/huggingface_hub/guides/cli
• Hugging Face「Environment variables」：https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables
• NVIDIA Blog「NVIDIA to Acquire Hugging Face」（2026年9月3日）：https://blogs.nvidia.com/blog/nvidia-to-acquire-hugging-face/
• Wikipedia（英語版）「Hugging Face」：https://en.wikipedia.org/wiki/Hugging_Face

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。