Windowsでllama.cppをCUDA対応で使う方法｜GGUFの起動まで解説

Windows + NVIDIA環境でllama.cppを使う場合、最初からsource buildする必要はない。公式releaseに目的のCUDA対応バイナリがあれば、まずそれで小さなGGUFを起動する方が環境を切り分けやすい。

確認すべきなのは、CUDA対応バイナリを用意できたか、GGUFを読めたか、実際にGPUへモデルが配置されたかの三つだ。どれか一つが成功しても、残りまで自動的に成功したことにはならない。

図を拡大して見る

図: 処理や設定の流れを1枚に整理。実際の操作条件は本文で確認する。

まず公式配布バイナリを確認する

公式releaseにWindows向けの適切な配布物があるなら、最初はprebuilt binaryを使う。

取得後は、使っているllama.cppのバージョンとCLIを確認する。

./llama-cli.exe --version
./llama-cli.exe --help

実際のファイル配置はreleaseによって変わるため、llama-cli.exeの場所は取得したパッケージ内で確認する。

ここでCUDA対応の配布物を使っているか、NVIDIA GPUが認識されるかを確認する。GGUFの互換性問題とGPUバックエンドの問題を同時に疑わないため、小さく一般的なGGUFから試すと切り分けやすい。

source buildではGGML_CUDA=ONを使う

公式配布では足りない機能がある、新しい修正を含む特定commitを使いたい、といった理由がある場合はsource buildを選べる。

Windowsでの公式build手順ではMSVC/CMakeの経路が案内されている。CUDA buildでは、その時点のbuild docsが求めるVisual Studio環境、CMake、CUDA Toolkitなどをそろえる。

git clone https://github.com/ggml-org/llama.cpp.git
cd ./llama.cpp
git checkout <release-or-commit>
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

GGML_CUDA=ONはCUDAバックエンドをビルドへ含める指定だ。モデルをGPUへ全量配置する指定ではない。

ビルドオプションやCLIは更新される可能性があるため、上の例を古いreleaseへそのまま当てはめず、使うreleaseまたはcommitのdocs/build.mdを優先する。

ビルド後は実行ファイルとCUDA認識を確認する

ビルドが通ったら、生成されたllama-cli.exeの場所を確認する。

Get-ChildItem ./build -Recurse -Filter llama-cli.exe

続いて、その実行ファイルの--versionと--helpを確認する。

重要なのは、別の古いllama-cli.exeをPATHから誤って起動していないことだ。CUDA付きで作ったバイナリと、実際に実行しているファイルを一致させる必要がある。

GGUFを読み込んで短い生成を試す

次にモデルパスを指定してGGUFを起動する。GPUへ載せる層数のflagはバージョン依存なので、現在の--helpを確認してから指定する。

./llama-cli.exe -m C:/models/small-model.gguf -ngl 99 -p "短いテストを一文で返してください"

-ngl 99のような大きな値を指定しても、VRAMやモデル構造の条件から実際に全層がGPUへ載るとは限らない。ログでGPUへの配置を確認する必要がある。

成功は3段階に分けて見る

1. GGUFを読み込めたか

ファイルパスが正しく、現在のllama.cppがそのモデルアーキテクチャを扱えるかを見る。

読み込み段階でunsupported architectureなどのエラーが出るなら、CUDA設定よりモデル互換性を先に確認する。

2. CUDAデバイスを認識したか

CUDA対応バイナリでNVIDIA GPUが列挙されているかを見る。GPUが認識されない場合は、実行しているバイナリ、NVIDIAドライバー、build設定などを確認する。

3. モデルがGPUへどこまで配置されたか

CUDAデバイスが見えていても、モデルがCPU中心で動いている場合はある。ログでGPUへ載った層やメモリ配置を確認する。

全量GPU配置とpartial offloadは別の実行条件だ。モデルが起動したという結果だけで「VRAMに全部収まった」と判断しない。

配布版とsource buildの選び方

状況	選びやすい方法
まずWindows + NVIDIAでGGUFを試したい	公式releaseのCUDA対応バイナリ
必要なbackendや修正がreleaseにない	source build
特定の新アーキテクチャ対応を試したい	対応commitを記録してsource build
GPUが使われない	buildし直す前に実行バイナリ・device認識・配置ログを確認

source buildでは、llama.cppだけでなくCUDA Toolkit、compiler、ドライバーも再現条件になる。別PCへバイナリを移せば常に同じ結果になるとは限らない。

エラーの種類を混ぜない

GGUF自体を読めない場合は、CUDA buildをやり直す前にモデルアーキテクチャとランタイム対応を確認する。詳しくはGGUFはLM Studio・Ollama・llama.cppでどこまで互換？で整理できる。

モデルは読めるがVRAM不足になる場合は、量子化、コンテキスト、GPU layers、partial offloadの問題として切り分ける。画像入力を使うモデルならprojector/mmprojなども別の条件になる。

Windowsでllama.cppをCUDA対応で使うときは、ビルド成功そのものをゴールにせず、正しいバイナリ → CUDA認識 → GGUF読み込み → GPU配置 → 短い生成まで順に確認するのが確実だ。