モデルを手に入れる

モデルはどこにあり、どこへ落ちるのか

Hugging Face（= 機械学習モデルの置き場を集めた公開サイト。ハギングフェイス）には、モデルが「リポジトリ」という単位で置かれています。リポジトリの名前は <作った人または組織>/<モデル名> の 2 段で、例えば HuggingFaceH4/zephyr-7b-beta のように書きます。この 2 段の名前がそのままダウンロードコマンドの引数になります。

リポジトリの中身は 1 個のファイルではありません。重みファイル（= 学習の結果である巨大な数値の塊）が複数に分割されて入り、config.json のような設定ファイルやトークナイザ（= 文章を数値に変換する規則）のファイルが同居しています。公式ドキュメントの例では hf download HuggingFaceH4/zephyr-7b-beta の出力が Fetching 23 files: です。「モデルを 1 つ落とす」は、実際には「23 個のファイルを落とす」作業です。

落ちる先は、既定ではキャッシュディレクトリ（= 一度落としたファイルを、次に同じものを要求されたときに落とし直さず済むよう貯めておくフォルダ）です。公式は「The recommended (and default) way to download files from the Hub is to use the cache-system.」と書いており、キャッシュに落とすのが推奨であり既定でもあります。キャッシュの中は次のような入れ子になっています。

キャッシュのルート / models--組織名--モデル名 / snapshots / コミットのハッシュ / 実ファイル

公式ドキュメントに載っている実例では、hf download gpt2 config.json の出力の最終行が /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json です。wauplin はドキュメントを書いた人のユーザー名なので、ここは実行するユーザーによって変わります。借りたインスタンスには root ユーザーで入る（公式の scp の例が root@IPADDR になっています）ので、同じコマンドの最終行は /root/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5…/config.json の形で出ます。このコマンドは必ず最終行に、そのマシン上のファイルパスを表示します（公式の明言）。どこに置かれたか分からなくなったら、まず最終行を読んでください。

キャッシュの位置は環境変数（= そのマシンで動くコマンドが共通で読む設定値。Linux では export 名前=値 で決める）とコマンドのオプションで動かせます。vast.ai では「借りたインスタンスのどこにモデルを置くか」が確保するディスク量、つまり課金に直結するので、次の 4 つは覚えて損がありません。

HF_HOME と HF_HUB_CACHE について「前者の下に後者がある」と明文で書かれた公式記述はありません。hf env の実出力（HF_HOME が ~/.cache/huggingface、HF_HUB_CACHE が ~/.cache/huggingface/hub）からそう読めるだけです。操作としては「HF_HOME を変えるとトークンの保存先も含めてキャッシュ全体が移る」「HF_HUB_CACHE を変えるとモデル本体の置き場だけが移る」の 2 点を押さえれば足ります。なお --local-dir を使うと、そのフォルダの直下に .cache/huggingface/ というメタデータ用のフォルダが作られ、再実行時に最新のファイルを落とし直さずに済みます。

公式が明示的に警告していることが 1 つあります。「返されたファイルパスは HF ローカルキャッシュへのポインタである。したがって、キャッシュを壊さないためにファイルを変更しないことが重要」。キャッシュの中のファイルを手で書き換えたり移動したりしてはいけません。加工したいときは --local-dir で別に落とします。

コマンドの名前は hf

Hugging Face からファイルを取る公式のコマンドラインツールは hf です。公式ガイドの第 1 文が「The huggingface_hub Python package comes with a built-in CLI called hf.」です。注意が 1 つあります。他の記事や他社のドキュメントには huggingface-cli download ... という古い書き方が残っていますが、現行の公式 CLI ガイドに huggingface-cli という文字列は一度も登場しません。実例として、vLLM の公式ドキュメントは今も #huggingface-cli-download という旧アンカー付きの URL でこの公式ページへリンクしています。旧名が今も動くのか、いつ廃止されたのかは公式には書かれていません。これから打つときは hf download と決めておけば混乱しません。

インストール方法は 4 通りあり、公式が Recommended と書いているのはスタンドアロンインストーラです。

• スタンドアロンインストーラ（推奨）: curl -LsSf https://hf.co/cli/install.sh | bash（macOS / Linux）。借りたインスタンスは Linux なのでこれが使えます
• uv 経由: uvx hf download ... のように毎回呼ぶ。公式の説明は「最も簡単。常に最新版を隔離環境で実行し、インストール不要」
• pip: pip install -U "huggingface_hub"。CLI はコアパッケージに同梱されています
• Homebrew: brew install hf（手元の Mac に入れる場合）

入ったかどうかは hf --help で確かめます。もう 1 つ、hf env は最初に必ず 1 回叩いてください。キャッシュの実際の場所・トークンが保存されているか・高速化ライブラリが入っているかが 20 行あまりで全部出ます。この出力は「遅い」「ダウンロードできない」の切り分けにそのまま使えます。

curl -LsSf https://hf.co/cli/install.sh | bash
hf --help
hf env
hf download openai-community/gpt2 --dry-run

[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
...
model.safetensors                 548.1M

落とす — 全部か、絞るか

hf download の書式は 4 通り覚えれば足ります。

# リポジトリ全体
hf download HuggingFaceH4/zephyr-7b-beta

# ファイルを指定する（リポジトリ内のパスは / 区切り。並べて複数指定してもよい）
hf download gpt2 config.json
hf download gpt2 config.json model.safetensors
hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors

# パターンで絞る（公式の例。safetensors だけ落として fp16 版は除く）
hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"

# 版を固定する（コミットのハッシュ・ブランチ名・タグが使える）
hf download bigcode/the-stack --repo-type dataset --revision v1.1

--revision に渡す「リビジョン」は、そのリポジトリのある時点の中身を指す名前です。コミットのハッシュ（= 変更 1 回ごとに振られる長い英数字の ID）・ブランチ名・タグのどれでも書けます。公式が Note で釘を刺しているのは 1 点で、コミットのハッシュを使うときは 7 文字の短縮形ではなく完全長のハッシュを書かなければなりません。

--repo-type を省略するとモデルのリポジトリとして扱われます。データセットや Space を落とすときだけ --repo-type dataset / --repo-type space を付けます。全部を 1 つの引数で書く hf:// という記法もあり、文法は hf://[<種別>/]<ID>[@<リビジョン>][/<パス>] です。この記法を使ったときは --repo-type と --revision を併用できません（既に URI に含まれているため、併用するとエラーになります）。ブランチ名に / が入るときは %2F に置き換える必要があります。

絞る話が実務では一番効きます。量子化（= 重みの数値を粗い刻みで表し直し、精度と引き換えにファイルを小さくする加工。第 3 章）済みモデルのリポジトリには、同じモデルの複数の精度が同居していることがよくあります。「Q4_K_M」「Q5_K_M」「Q8_0」のような版がまとめて置かれているので、リポジトリ全体を落とすと欲しいファイルの何倍ものディスクを食います。--include "*Q4_K_M*" のようにパターンで 1 つに絞るのが常道です。公式ドキュメントが挙げている --include の例は safetensors（= 重みを保存するファイル形式の 1 つ）のもので、量子化ファイルを絞る例そのものは載っていません。公式の使い方をそのまま応用している、という位置づけで読んでください。

落としたパスを別のコマンドに渡したいときは --quiet を付けます。公式の説明は「全部黙らせるには --quiet。最終行（= ダウンロードしたファイルのパス）だけが表示される」です。

gated モデルとトークン

gated（= ページは誰でも見られるが、ダウンロードは作者の承認を得た人だけに許された状態）のリポジトリがあります。Llama 系がその代表で、vast.ai の公式ガイドも Llama3 のテンプレートの説明で「You will also need to apply to have access to Llama3 on huggingface in order to access this gated repository.」と書いています。gated モデルは「Hub 上で申請 → 承認 → トークンで認証」の 3 段が必要で、トークンだけ持っていても承認がなければ落ちません。承認は即時とは限らないので、GPU を借りる前に手元のブラウザで申請だけ済ませます。申請の待ち時間に GPU 課金を払う理由はありません。

トークン（= 自分の Hugging Face アカウントの代わりにコマンドが使う文字列）は Hugging Face の Access Tokens ページで発行します。公式の説明は「private または gated のリポジトリにアクセスするにはトークンを使わなければならない。既定では hf auth login でローカルに保存されたトークンが使われる」です。明示的に渡すなら --token を付けます。

# 対話でログインする（URL と短いコードが表示される。
# ブラウザでその URL を開いてコードを入れ、承認するとトークンがマシンに保存される）
hf auth login

# サーバー上で非対話にやるなら、環境変数に入れておく
export HF_TOKEN=<自分のトークン>
hf auth whoami

# コマンド 1 回だけ明示的に渡す
hf download gpt2 config.json --token=<自分のトークン>

<自分のトークン> は、Access Tokens ページで発行した hf_ で始まる文字列に置き換えます（山括弧ごと消して貼り付けます）。

公式は「より安全にするため、コマンド履歴に貼り付けるのを避けるよう、トークンは環境変数として渡すことを推奨する」と書いています。借りたインスタンスでの実務は HF_TOKEN に入れる形になります。vast.ai 側ではテンプレートの環境変数として渡すのが定石で、公式の Llama3 テンプレートの手順も「HuggingFace トークンを追加して Select & Save ボタンを押す」です。

そして公式が明示的に警告している挙動が 1 つあります。「hf auth logout は、HF_TOKEN 環境変数でログインしている場合はログアウトしない。その場合はマシンの設定で環境変数を unset しなければならない」。vast.ai では HF_TOKEN をテンプレートの環境変数で渡すのが普通なので、この挙動は正面から当たります。

export HF_TOKEN=<自分のトークン>
hf auth whoami
hf download meta-llama/Meta-Llama-3-8B-Instruct --dry-run

ディスクをいくら確保するか

ディスク容量は借りるときに決め、後から変更できません（第 7 章）。公式の助言は「Storage is cheap, so err on the side of more space.」の一言です。この章で足す視点は 1 つだけ、--dry-run が出した合計サイズが、そのままディスクの下限になるということです。イメージ本体と作業領域を別に積む必要があるので、モデル分ぴったりでは足りません。

当てが無いと決められないので、公式ドキュメントが実例として挙げている割り当てを並べます。いずれも「そのモデルを動かすために公式が指定した値」で、モデルのファイルサイズそのものではありません。

• DeepSeek R1 70B（Ollama + Open WebUI テンプレート）: ディスク 50 GB。あわせて VRAM が最低 43 GB 必要なので GPU Total Ram のスライダーを 44 GB に合わせる、と書かれています
• Llama 3 8B Instruct（HuggingFace TGI テンプレート）: テンプレート側のフィルタがディスク 100 GB 以上・GPU RAM 16 GB 以上を要求します
• Oobabooga（text-generation-webui）: 「既定のストレージ量では LLM のダウンロードに足りない。100 GB あれば十分」
• MiniMax-M2（vLLM）: モデルだけで約 460 GB。公式のトラブルシュートは No space left on device の対処を「ディスク割り当てを少なくとも 500 GB に増やす」としています

ディスクは GUI のスライダーでも CLI の --disk <GB> でも指定でき（<GB> は確保したい容量を数字で書く）、指定しなかったときの既定は 10 GB です。10 GB はイメージを展開したら終わる量なので、モデルを落とすなら必ず自分で上げます。上限はホストが積んでいる容量次第で、2026-08-24 時点の実測では 1× RTX 5090 の offer 64 件が申告する disk_space は最小 12 GB / 中央値 612 GB / 最大 3203 GB でした。数百 GB 取れるホストは普通に見つかりますので、ここでケチる理由はほとんどありません。

課金は確保したサイズに対して発生します。「You are charged the storage cost (which depends on the size of your storage allocation) for every second your instance exists and is online」と書かれており、df -h で 3 GB しか使っていなくても 200 GB 確保していれば 200 GB 分です。加えて起点が 2 つに分かれています。ストレージ課金はインスタンスを作った瞬間から、GPU 課金は running になってからです。

ストレージ月額 = 確保した GB × storage_cost（USD/GB/月）

2026-08-24 時点の実測（1× RTX 5090 の on-demand offer 64 件）では storage_cost は最小 0.133 / 中央値 0.200 / 最大 0.867 USD/GB/月で、ホストによって 6 倍以上の開きがあります。中央値で計算例を出すと、40 GB を 1 か月確保して 40 × 0.20 = 月 8 USD（1 USD = 150 円として約 1,200 円）。GPU 側は中央値 0.4037 USD/時なので、1 時間だけ GPU を使うより、止めっぱなしのディスクの方が高くつくことがあります。

もう 1 つ払うのが時間です。ダウンロードが終わるまで GPU は 1 回も計算しませんが、課金は動いています。所要時間はモデルのサイズを回線速度で割れば出ます。offer カードに出ている回線速度の単位 Mbps は「1 秒あたり何百万ビット運べるか」、ファイルサイズの GB はバイトの単位です。1 バイト = 8 ビットなので、GB を 8 倍して Mbps で割ると秒数になります。

この見積りは理論値です。実際にはこれより遅くなります。vast.ai の公式ガイドが「HuggingFace がダウンロード速度を制限しているため、非常に速いインスタンスでも最大 1 時間かかることがある」と明記しています。公式の実例でも、約 60 GB のモデルの初回デプロイで 8〜10 分、別の例では「モデルのダウンロード（初回）15〜20 分」という内訳が出ています。「借りてすぐ推論できる」ではなく「借りてから 10 分から 30 分は準備」だと思って予定を組んでください。

2 回目以降にこの時間と帯域料を払わない方法が 3 つあります。先に言葉を決めておきます。volume は「インスタンスに付け外しできる永続ストレージ」で、インスタンスを destroy しても消えません。オブジェクトストレージは Amazon S3 や Google Drive のような、インターネット越しにファイルを預けるクラウドの保管庫です。判断の軸は「モデルの大きさ」と「使う頻度」の 2 つです。

volume を使う場合の注意を 2 つ。volume は作られた物理マシンに紐づき、他のマシンへは持っていけません。そのマシンの GPU が全部埋まっていれば、空くまで待つしかありません。そして 200 GB の volume は 2026-08-24 時点の中央値単価で 200 × 0.20 = 月 40 USD（計算例）です。一方で 15 GB のモデルを毎回落とす帯域料は約 0.04 USD。金額だけ見れば毎回落とす方が圧倒的に安く、volume は「時間を金で買う」選択です。そこを取り違えないでください。

df -h
export HF_HOME=/workspace/hf
hf download HuggingFaceH4/zephyr-7b-beta --dry-run
hf download HuggingFaceH4/zephyr-7b-beta
hf cache ls
df -h

ID                          SIZE     LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue          157.4M 2 days ago    2 days ago    main script
model/LiquidAI/LFM2-VL-1.6B     3.2G 4 days ago    4 days ago    main
model/microsoft/UserLM-8b      32.1G 4 days ago    4 days ago    main

Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.

遅い・止まった・壊れた

ダウンロードは失敗します。回線が細いホストを引いたとき、HF 側の制限に当たったとき、ディスクが尽きたときです。症状ごとに叩くコマンドを決めておけば、慌てて destroy して落とし直す必要はありません。

「再開」については、--resume のようなフラグは存在しません。公式が明言しているのは 2 点だけです。中断されたダウンロードは .incomplete という部分ファイルを残す。そしてそれはリビジョン単位で動く hf cache ls / hf cache rm の管理対象外なので、hf cache prune が自動で削除する。途中のバイトを引き継ぐのか先頭から落とし直すのかは公式ドキュメントに書かれていません。操作としては「同じコマンドを再実行する」で正しく、キャッシュ済みのファイルは落とし直されません。

高速化には落とし穴があります。HF_HUB_ENABLE_HF_TRANSFER=1 を設定して速くする方法が広く出回っていますが、公式は hf_transfer を「now deprecated; use hf_xet instead」と明記しています。そもそも HF_HUB_ENABLE_HF_TRANSFER という名前は、現行の CLI ガイドにもダウンロードガイドにも、hf env の出力にも出てきません。現行の高速化は hf_xet（= ファイルを小さな塊に分け、既に持っている塊は落とし直さない仕組み）が担い、huggingface_hub 0.32.0 以降なら一緒に入ります。設定は不要です。今ある関連の環境変数は逆向きの HF_HUB_DISABLE_XET（= Xet を切る。既定は False）だけで、これを触る理由は普通ありません。

なお、ディスクが尽きて起動すらできなくなっても、インスタンスを起動せずに vastai execute でファイルを消せます（= GPU 課金を発生させずに掃除できる。第 7 章）。落とし直す前に、まずそこを試してください。

つまずきポイント

理解度チェック

まとめ

• コマンドは hf。落ちる先は既定でキャッシュ、パス構造は models--組織--名前/snapshots/<ハッシュ>/ で、最終行に実際のパスが必ず出る。場所は HF_HOME（全体）と HF_HUB_CACHE（モデル本体の層）で動かせる
• 落とす前に --dry-run。「何ファイル・合計何 GB」が出るので、ディスクと時間の見積りはここから取る。大きいリポジトリは --include で絞る
• gated は申請 → 承認 → トークンの 3 段。申請は借りる前にブラウザで済ませる。HF_TOKEN でログインしていると hf auth logout は効かない
• ディスクは作成時に決めた容量から増やせず、課金は確保サイズに対して発生する。ストレージ課金は作成の瞬間から、GPU 課金は running から。公式の実例は R1 70B で 50 GB、TGI テンプレで 100 GB 以上、MiniMax-M2 で 500 GB
• ダウンロード時間はまるごと GPU 課金の対象。15 GB は 752 Mbps なら約 3 分、48 Mbps なら約 42 分（計算例、速度は 2026-08-24 時点の実測）。HF 側の制限で最大 1 時間かかることがある
• 止まったら同じコマンドを再実行、残骸は hf cache prune、壊れた疑いは hf cache verify、細い回線は HF_HUB_DOWNLOAD_TIMEOUT=30。高速化のために設定する環境変数はない

次章では、ここで手に入れたモデルを最短ルートで動かします。Ollama を使って 1 コマンドでモデルを落とし、会話が返ってくるところまで通します。

参考リンク

• Hugging Face Hub — Command Line Interface（hf の全サブコマンド・認証・hf cache）
• Hugging Face Hub — Download files from the Hub（--include / --dry-run / --local-dir / hf_xet）
• Hugging Face — Access Tokens（トークンの発行）
• vast.ai — HuggingFace TGI with Llama3（gated の申請とトークンの渡し方）
• vast.ai — Ollama + Open WebUI（ディスクと VRAM の割り当て例）
• vast.ai — Oobabooga LLM WebUI（stop と destroy の違い）
• vast.ai — Storage Types（リサイズ不可・停止中も課金）
• vast.ai — Volumes（destroy を跨ぐ永続ストレージ）
• vast.ai — Billing FAQ（確保サイズに対する課金・課金の起点）
• vast.ai — Docker Execution Environment（環境変数と /etc/environment）
• vast.ai — MiniMax-M2（No space left on device と 500 GB）
• vast.ai — Quantized GGUF Models（HF 側の速度制限で最大 1 時間）