【実践】llama.cpp と GGUF で動かす

GGUF は「重み 1 ファイル」、llama-server はそれを配る HTTP サーバー

量子化（= 重みの数値を粗く丸めてファイルを小さくする加工）済みのモデルは、GGUF という形式の .gguf ファイルとして配布されています。llama.cpp はそれを読んで動かすプログラム群で、この章で使う llama-server はそのうちの 1 つです。公式の自己紹介は「httplib・nlohmann::json・llama.cpp をベースにした、高速・軽量・純粋な C/C++ の HTTP サーバー」。OpenAI API 互換の chat completions / responses / embeddings のルートを持ち、Anthropic の Messages API 互換のルートも持ちます。連続バッチング（= 複数のリクエストをまとめて同時に処理する仕組み）と Web UI は既定で有効です。

vast.ai の公式ドキュメントが GGUF を扱うときに llama.cpp を推す理由は 1 つで、「多数の分割ファイル（split GGUF）をマージせずに直接ロードできる」からです。大きなモデルは DeepSeek-R1.Q8_0-00001-of-00015.gguf のように 15 分割で配布されることがありますが、--model に渡すのは 先頭の -00001-of-00015 だけで、残りは自動で読まれます。結合作業もそのための空きディスクも要りません。

ファイルの置き方には決まりがあります。--models-dir にディレクトリを渡す場合、単一ファイルのモデルは直下に置き、マルチモーダルやマルチシャード（分割）のモデルはサブディレクトリに入れます。画像を扱うための projector ファイルは、名前が mmproj で始まっている必要があります。

models_directory
 ├─ Qwen3-8B-Q4_K_M.gguf
 ├─ gemma-3-4b-it-Q8_0/
 │    ├─ gemma-3-4b-it-Q8_0.gguf
 │    └─ mmproj-F16.gguf
 └─ Kimi-K2-Thinking-UD-IQ1_S/
      ├─ Kimi-K2-Thinking-UD-IQ1_S-00001-of-00006.gguf
      └─ ... -00006-of-00006.gguf

なお vast.ai の GGUF ガイドが例に使っている DeepSeek-R1 の Q8_0 は、公式が「VRAM 800 GB 以上・ストレージ 700 GB・推奨は 8×H200」と明記しているモデルです。1 枚の RTX 5090（32 GB）ではまったく動きません。本章は同じ手順を、32 GB に入るサイズのモデルで踏みます。

では「32 GB に入るサイズ」をどう見分けるか。目安は GGUF ファイルの合計サイズです。いま挙げた DeepSeek-R1 Q8_0 が「ストレージ 700 GB／VRAM 800 GB」だったように、全レイヤーを GPU に載せる構成では、ファイルサイズと同程度かそれより少し多い VRAM が要ります（必要 VRAM の計算式そのものは llama.cpp の公式ドキュメントにありません。この目安は vast.ai が挙げた 2 つの数値の関係から読み取ったものです）。計算例: 5090 の VRAM は 32607 MB（2026-08-24 時点の実測値）で、ここから後述する --fit の余白（既定 1024 MiB）と、会話が伸びるほど増える KV キャッシュ（= 入力と生成済みトークンぶんの計算結果を取っておく領域）のぶんを引く必要があります。ファイルが 30 GB を超える GGUF は、1 枚では全レイヤーを載せきれないと考えてください。

Hugging Face の GGUF リポジトリには Q4_K_M・Q5_K_M・Q8_0 といった量子化違いが同じ場所に同居していることが多く、リポジトリ全体を落とすと数百 GB になります。第 11 章でやったとおり、hf download <ユーザー名>/<リポジトリ名> --include "*Q4_K_M*" のように欲しい 1 種類だけを名指しで落とし、その前に --dry-run を付けて何 GB になるかを見てから実行してください（<ユーザー名>/<リポジトリ名> は Hugging Face のモデルページの URL に出ている 2 語です）。ディスクは借りるときに決めた容量ぶん課金されます。単価は 2026-08-24 時点の実測で中央値 0.200 USD/GB/月 なので、計算例として 40 GB を 1 か月確保すると 40 × 0.200 = 月 8 USD です。

手に入れる道は 3 つ

vast.ai が推しているのは A です。Open WebUI テンプレートには、プリコンパイル済みで CUDA 対応の llama-server と llama-cli が最初から入っています。モデルの置き場所は /workspace/llama.cpp/models で、同梱スクリプト llama-dl.sh --repo <ユーザー名>/<リポジトリ名> --version <量子化タイプ> で落とせます（<...> は Hugging Face 上のモデルの持ち主・名前・Q4_K_M のような量子化タイプ）。

B を選ぶときは、タグ（= イメージの版を表す名札）の選び方が 1 か所だけ重要です。NVIDIA GPU で使うのは server-cuda（CUDA 12 版）か server-cuda13（CUDA 13 版）で、バックエンド名の付かない server は GPU 向けにコンパイルされていない版です（公式ドキュメントもこのタグを CPU の例として載せています）。--gpus all は「ホストの GPU を全部コンテナに渡す」という Docker への指示で、GPU 対応のクラウドを使っているなら、これで cuBLAS（= NVIDIA が配っている行列計算のライブラリ）がコンテナの中から使えるようになります。

docker run -p 8080:8080 -v <モデルを置いたフォルダ>:/models --gpus all \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m /models/<モデルファイル名>.gguf -c 2048 --host 0.0.0.0 --port 8080

<モデルを置いたフォルダ> はインスタンス側で .gguf を置いたディレクトリの絶対パス（例: /workspace/models）、<モデルファイル名>.gguf はその中のファイル名（分割されているなら -00001-of-... の 1 本目）です。-v の左がホスト側、右がコンテナの中から見えるパスなので、-m に渡すのはコンテナ側の /models/... になります。-v を付け忘れるとコンテナの中にモデルが無く、コンテナを消すとダウンロードしたモデルも一緒に消えます。なお公式の例には --n-gpu-layers 99 が付いていますが、いまの -ngl の既定は auto なので省いてあります（次節）。

C を選ぶなら、Blackwell 向けの指定を 1 つ覚えます。llama.cpp は既定で「いまつながっている GPU 向け」にビルドされ、nvcc が GPU を見つけられないと nvcc warning : Cannot find valid GPU for '-arch=native', default arch is used と警告します。対処は CUDA アーキテクチャを明示することです。公式が載せている例は -DCMAKE_CUDA_ARCHITECTURES="86;89" で、これは Compute Capability（= GPU の世代・機能水準を表す番号。NVIDIA が製品ごとに公表しています）8.6 と 8.9 を並べたもの。つまり小数点を取って書き、複数あればセミコロンで区切るという規則がここから読み取れます。NVIDIA の一覧表は GeForce RTX 5090 を Compute Capability 12.0 に分類しているので、指定は "120" になります（vast.ai の offer が返す 5090 のフィールドも全件 compute_cap = 1200 でした。2026-08-24 時点の実測）。この "120" という値自体は llama.cpp の公式ドキュメントには載っていません。公式の例から読み取れる規則と、NVIDIA の表を突き合わせて出した値です。

cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="120"
cmake --build build --config Release -t llama-server

できあがるのは ./build/bin/llama-server です。-DGGML_NATIVE=OFF を付ければ全 CUDA GPU 向けの汎用バイナリになりますが、公式が「バイナリが大きくなり、コンパイルに長時間かかる」と書いているとおり代償があります。借りるたびにホストが変わる vast.ai では、そのインスタンスの上でビルドして、そのインスタンスで使い切るのが素直です。古い CUDA の環境では cospi などの宣言が衝突してビルドが壊れる既知の問題もあるため、新しい CUDA のホストを選ぶこと自体が対策になります（5090 のホストは実測で cuda_max_good が 12.8〜13.3 に分布し、12.8 未満は 1 件もありませんでした。2026-08-24 時点）。なお Blackwell に必要な最低 CUDA バージョンは llama.cpp の公式ドキュメントに明記がありません。手がかりは、公式 Docker イメージのビルド既定値が CUDA_VERSION=12.8.1 であることと、この実測分布の 2 つだけです。

vast.ai のドキュメントが載せている自前ビルドのレシピは、公式の手順に 1 つだけ足しています。apt-get install libcurl4-openssl-dev を先に実行し、-DLLAMA_CURL=ON を付けてビルドする形です。この curl 関連の指定は llama.cpp 公式の docs/build.md には出てきません。後述する -hf（ネットワーク越しにモデルを取る指定）が curl 無しで動くかどうかも公式ドキュメントに明記がないので、-hf を使いたいならテンプレート同梱の既製バイナリか公式 Docker イメージを選ぶのが確実です。

apt-get install libcurl4-openssl-dev
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="120" -DLLAMA_CURL=ON
cmake --build build --config Release -j 8 -t llama-server

この 3 行は、1 つ前の 2 行と入れ替えて使います（-hf を使うつもりが無いなら、前の 2 行のままで構いません）。-j 8 は「8 並列でコンパイルする」という指定で、公式が例示している書き方です。数字は借りたマシンの CPU コア数に合わせてください。vast.ai のインスタンスには root で入るので sudo は要りません。ビルドしている間も GPU の時間課金は走っています。

立てる — 「起動した」と「使える」は別

最小の起動は llama-server -m <モデルファイルのパス> -c 2048 で、これで 既定では 127.0.0.1:8080 を listen するサーバーが立ちます。ただしコマンドを打った瞬間に使えるようになるわけではありません。モデルを読み込んでいる間、/health は 503 と {"error": {"code": 503, "message": "Loading model", "type": "unavailable_error"}} を返し続け、読み終えて初めて 200 と {"status": "ok" } になります。この /health だけは API キーのチェックがかからない公開エンドポイント（= URL の末尾に付ける、用途ごとの入り口のこと）なので、認証を設定した後でも待ち合わせに使えます。同じものが /v1/health でも叩けます。

nvidia-smi

llama-server --model <モデルファイルのパス> --ctx-size 8192 --port 20000

curl http://localhost:20000/health

curl -X POST http://localhost:20000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "自己紹介を 1 文で"}]}'

32 GB に収める — 回すつまみは 4 つ

VRAM（= GPU 自身のメモリ）に載り切らないモデルでも、llama.cpp は動きます。-ngl, --gpu-layers, --n-gpu-layers が「VRAM に置くレイヤーの最大数」を決めていて、そこに入らなかったレイヤー（= モデルを構成する層。トークンを 1 個作るたびに上から下まで順に通ります）は CPU 側のシステムメモリに置かれ、CPU が計算するからです。取れる値は「正確な数値」「auto」「all」で、既定は auto。古い記事に出てくる -ngl 99 は「全部載せろ」の慣用表現で、いまは必須ではありません。

ここで -ngl 0 にしても GPU が完全に切れるわけではない点に注意してください。公式は「-ngl 0 を使っていても、計算の一部を高速化するために GPU は依然として使われることがある。完全に無効化するには --device none を使う」と明記しています。

もう 1 つ、既定で勝手に働く仕組みがあります。-fit, --fit [on|off] は「指定しなかった引数を、デバイスメモリに収まるように調整する」機能で、既定は on です。つまり何も指定しなければ、llama.cpp のほうが値を勝手に下げて起動を通します。「動いたけれど、思っていたよりコンテキストが短かった」の正体はこれです。関連する引数が 2 つあり、空けておく余白は -fitt, --fit-target の既定で 1024 MiB（メビバイト。1024 MiB ≒ 1.07 GB）、--fit が下げてよいコンテキストの下限は -fitc, --fit-ctx の既定で 4096 です。逆に言えば、自分で明示した引数は調整の対象になりません。

ここで 1 つ、公式ドキュメントが答えていない点があります。--fit がどの引数を調整対象にするかの一覧は書かれていません。コンテキスト長（-c）が対象に入ることは、-fitc が「--fit が設定しうる最小 ctx サイズ」と定義されていることから確実です。-ngl も「未設定の引数を収まるように調整する」という説明の範囲に入ると読めますが、そこまでは明示されていません。だからこそ再現性が要る場面では -c と -ngl を自分で書くのが安全です。書いた値は動かされません。

それでも溢れたときの既定の挙動はクラッシュです。Linux では GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 を付けて起動すると、「GPU の VRAM を使い切ったときにクラッシュせずシステム RAM へスワップできる」ようになります。落ちるよりはましですが、遅くなることと引き換えである点は変わりません。MoE（= 層の一部だけを使い分ける構造）のモデルなら、-cmoe（その重みを全部 CPU へ）や -ncmoe N（先頭 N 層分だけ CPU へ）という逃がし方もあります。

llama-server --model <モデルファイルのパス> --port 20000 -c 4096 -ctk q8_0 -ctv q8_0

llama-server --model <モデルファイルのパス> --port 20000 -c 4096 -ngl <層数>

GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 llama-server --model <モデルファイルのパス> --port 20000

外から使う・Open WebUI に繋ぐ・速度を測る

--host の既定は 127.0.0.1 です。この既定のままでは、インスタンスの外からは 1 バイトも届きません。vast.ai のガイドの起動例に --host が出てこないのは、同じインスタンスの中で動く Open WebUI から localhost 経由で繋ぐ前提だからです。

Open WebUI 側の設定は ⚙️ Admin Settings → Connections → OpenAI → ➕ Add Connection で、入力欄は次の 3 つです（実際に埋めるのは上の 2 つだけ）。

末尾の /v1 は必須です。公式ドキュメントが「Note the /v1 at the end!!」と感嘆符 2 つで書いているほど、ここが最頻の失敗です。Open WebUI は接続を検証するときにプロバイダの /models を標準の Bearer トークンで呼びますが、この検証が赤くなっても会話は動くことがあります。公式も「/models を実装していない、または非標準の認証を使うプロバイダでは検証がエラーになるが、それは非互換を意味しない。chat completions は動く」と書いています。その場合は表の Model IDs (Filter) にモデル ID を手で足してください。サーバーの起動が遅くて検証がタイムアウトする場合は、Open WebUI 側の環境変数 AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30（既定は 10 秒）で窓を広げられます。モデル一覧に出てこないときは、まずページをリロードしてください。

インスタンスの外へ直接開くなら、まず第 10 章の手順でそのポートを外向きに公開したうえで、--host 0.0.0.0 にし、--api-key <自分で決めた長い文字列> をセットで付けます。認証に失敗したリクエストには 401 と Invalid API Key が返ります。CORS（= ブラウザが「どのサイトの JavaScript にこの API を叩かせてよいか」を判定する仕組み）の既定が緩い点も知っておいてください。公式は「既定ではサーバーは任意の Origin ヘッダをそのまま反射し、credentials を許可する」と明記しています。公式が挙げている推奨は 3 段階で、同じマシンからしか使わないなら --cors-origins localhost、社内 LAN なら使うフロントエンドの origin を書く、公開するなら API キーを設定したうえでリバースプロキシの背後に置く、です。Web UI の実験的な機能（--tools や MCP 関連）は「信頼できない環境で有効にするな」と公式が繰り返し警告しているので、公開 IP を持つ vast.ai のインスタンスでは触らないのが安全です。

llama-server --model <モデルファイルのパス> --port 20000 --metrics

ssh -p <ポート> root@<ホスト> -L 20000:localhost:20000

curl -s http://localhost:20000/metrics | grep llamacpp:predicted_tokens_seconds

つまずきポイント

理解度チェック

まとめ

• GGUF は量子化済みの重みのファイル形式で、llama-server はそれを OpenAI 互換 API と Web UI として配る HTTP サーバー。Web UI も連続バッチングも既定で有効
• 分割 GGUF は先頭ファイルだけを --model に渡せばよい。マージ不要が llama.cpp の実務上の強み
• 入手は 3 択。vast.ai では Open WebUI テンプレート同梱の既製バイナリが最短、次に公式 Docker の server-cuda、最後に自前ビルド（Blackwell は -DCMAKE_CUDA_ARCHITECTURES="120"）
• 起動の完了判定は /health。503 Loading model → 200 status ok に変わるまでが読み込み時間で、その間も課金は走る
• 32 GB に収めるつまみは -ngl（既定 auto）・--fit（既定 on）・-c（既定 0 は「モデルの値」）・-ctk／-ctv（既定 f16）。溢れた既定の挙動はクラッシュで、GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 が保険
• Open WebUI に繋ぐ値は http://localhost:20000/v1 と API Key none。末尾の /v1 を落とすのが最頻の失敗
• 外へ開くなら --host 0.0.0.0 と --api-key は必ずセット。--sleep-idle-seconds で寝かせてもレンタル料金は 1 円も止まらない
• 速度を語る根拠は --metrics の llamacpp:predicted_tokens_seconds（生成）と llamacpp:prompt_tokens_seconds（プロンプト処理）

次章では、ここまでに立てた API を手元の Mac / PC から日常的に使う形に落とします。SSH トンネル・Open WebUI・API クライアントの設定を通して、公開ポートを開けずに自分だけで使う経路を作ります。

参考リンク

• llama.cpp — llama-server README（全引数・既定値・エンドポイント・/health の応答）
• llama.cpp — build.md（-DGGML_CUDA=ON・CMAKE_CUDA_ARCHITECTURES・CUDA 環境変数）
• llama.cpp — docker.md（server-cuda タグ一覧・--gpus all・CI の但し書き）
• vast.ai — Quantized GGUF models（テンプレート同梱バイナリ・llama-dl.sh・--port 20000）
• NVIDIA — CUDA GPUs（GeForce RTX 5090 の Compute Capability 12.0）
• Open WebUI — Starting with llama.cpp（URL 末尾の /v1・AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST）
• Open WebUI — Starting with OpenAI-compatible（Admin Settings → Connections・host.docker.internal）
• Hugging Face — CLI ガイド（hf download・--include・HF_TOKEN）
• vast.ai — Open WebUI (Ollama) テンプレート（Instance Portal・OPEN_BUTTON_TOKEN・自己署名証明書）