Windows 11 で llama.cpp を構築する (CUDA サポート付き)🦙
Windows 11 で llama.cpp を構築する (CUDA)
はじめに
この記事では、Windows 11 環境で、LLM 推論エンジン llama.cpp
を NVIDIA GPU (CUDA) 対応でビルドし、動かすまでの手順を解説します。
Windows 特有のビルド時の注意点や、日本語プロンプトでよくある文字化け問題の解決策も紹介します。
こんな人におすすめ:
- Windows で
llama.cpp
を試してみたい方 -
llama.cpp
のビルドや実行で困っている方
この記事でわかること:
- CUDA を有効にした
llama.cpp
のビルド方法 -
vcpkg
を使った依存関係エラーの解決方法 - 日本語プロンプトでの基本的な使い方と文字化け対策
1. 環境準備
llama.cpp
のビルドには、以下のツールが必要です。事前にインストールしておきましょう。
- Visual Studio 2022: C++ コンパイラです。Community Edition でOK。「C++ によるデスクトップ開発」ワークロードを選んでインストールしてください。
-
CMake: ビルドシステム生成ツール。
- CMake ダウンロード
- インストール時に PATH を通すオプションを選ぶと後々楽です。
- Git for Windows: ソースコードの取得に使います。
-
CUDA Toolkit: NVIDIA GPU を使う場合に必要。GPU ドライバと互換性のあるバージョンを選んでください。
- CUDA Toolkit Archive (古いバージョンはこちら)
- Python (任意): モデルダウンロードなどで使うことがあるかもしれません。必須ではありませんが、入れておくと便利なことも。
動作確認:
インストール後、コマンドプロンプトや PowerShell を開いて、以下のコマンドが通るか確認します。バージョンが表示されれば大丈夫です。
cl /?
cmake --version
git --version
nvcc --version
python --version # Python を入れた場合
(cl /? は長いヘルプが出れば OK です。)
2. llama.cpp ソースコードの取得
適当な作業ディレクトリ (例: C:\dev) を作り、Git で llama.cpp のリポジトリをクローンします。
cd C:\dev
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
3. 依存関係の解決: vcpkg の利用
llama.cpp は、機能によっては curl のような外部ライブラリが必要です。Windows でこれらを手動で入れるのは少し面倒で、リンクエラーも起きがちです。ここでは、C++ ライブラリ管理ツールの vcpkg を使って、この問題を簡単に解決する方法を紹介します。
3.1. vcpkg のインストール
vcpkg を置きたいディレクトリ (例: C:\src) に移動します。
cd C:\src
vcpkg のリポジトリをクローン。
git clone https://github.com/microsoft/vcpkg.git
vcpkg ディレクトリに入り、セットアップ用のスクリプトを実行します。
cd vcpkg
.\bootstrap-vcpkg.bat
3.2. 依存ライブラリのインストール
vcpkg を使って curl (SSL対応版) をインストールします。vcpkg ディレクトリ内で以下を実行。
.\vcpkg install curl[core,ssl]:x64-windows --triplet x64-windows
curl[core,ssl]:x64-windows
: curl 本体と SSL 機能、64bit Windows 向けを指定。
--triplet x64-windows
: ターゲット環境の指定。
インストールには少し時間がかかります。
4. llama.cpp のビルド (CMake & MSBuild)
いよいよ llama.cpp をビルドします。llama.cpp のソースディレクトリ (C:\dev\llama.cpp など) にいることを確認してください。
4.1. ビルド用ディレクトリの作成
ソースコードとビルド成果物を分けるため、build ディレクトリを作ります。
# llama.cpp ディレクトリにいるか確認
# 例: cd C:\dev\llama.cpp
# もし build ディレクトリが既にあれば消す (推奨)
# PowerShell:
if (Test-Path build) { Remove-Item build -Recurse -Force }
# コマンドプロンプト:
# if exist build rmdir /s /q build
# build ディレクトリ作成
mkdir build
4.2. CMake の実行 (ビルド設定)
CMake でビルド設定ファイル (Visual Studio プロジェクトなど) を作ります。CUDA サポートを有効にし、vcpkg を使うよう指定します。
cmake -B build -DGGML_CUDA=ON -DGGML_CUDA_F16=ON -DCMAKE_TOOLCHAIN_FILE="C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake"
-B build
: 出力先を build ディレクトリに。
-DGGML_CUDA=ON
: CUDA (GPU) サポートを有効化。
-DGGML_CUDA_F16=ON
: CUDA で FP16 (半精度浮動小数点) 計算を有効化。対応 GPU なら高速化が期待できます。不要なら OFF でもOK。
-DCMAKE_TOOLCHAIN_FILE="C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake"
: vcpkg で入れたライブラリを探すための設定ファイルパス。C:/src/vcpkg は自分の環境に合わせて書き換えてください。パス区切りは \ ではなく / なので注意!
-- Configuring done, -- Generating done
と出れば成功です。
4.3. ビルドの実行
CMake を使ってコンパイルとリンクを実行します。
cmake --build build --config Release
--build build
: build ディレクトリの設定でビルド。
--config Release
: 最適化された Release モードでビルド。
ビルドには数分~数十分かかります。エラーが出なければ、build\bin\Release に llama-cli.exe などが作られます。
5. 実行ファイルの PATH 設定 (任意)
毎回 build\bin\Release まで移動するのが面倒な場合は、このディレクトリを環境変数 PATH に追加しておくと、どこからでも llama-cli.exe を実行できて便利です。
設定方法 (Windows GUI):
- Windows 検索で「環境変数」と入力し、「システム環境変数の編集」を開く。
- 「環境変数」ボタンをクリック。
- 「ユーザー環境変数」か「システム環境変数」の Path を選んで「編集」。(システム環境変数だと全ユーザーで有効に)
- 「新規」で llama.cpp の実行ファイルがあるパス (例: C:\dev\llama.cpp\build\bin\Release) を追加。
- 「OK」で閉じる。
6. モデルの準備
llama.cpp を動かすには、GGUF (GPT-Generated Unified Format) という形式のモデルファイルが必要です。これは llama.cpp 用に最適化されたフォーマットです。
Hugging Face Hub - GGUF モデル検索 などで、使いたいモデルの .gguf ファイルを探してダウンロードしましょう。
ダウンロードした .gguf ファイルは、llama.cpp ディレクトリの中に models フォルダを作って、そこに入れておくと管理しやすいです。
例: C:\dev\llama.cpp\models\gemma-3-4b-it-Q4_K_M.gguf
(この記事の後半では、例としてこの Gemma モデルを使用します)
7. 実行とトラブルシューティング
llama-cli.exe を使って、モデルに推論させてみましょう。
7.1. 基本的な実行コマンド
コマンドプロンプトや PowerShell で以下のように実行します (models フォルダに .gguf を置いた場合)。
llama-cli.exe -m ./models/gemma-3-4b-it-Q4_K_M.gguf -n-gpu-layers 99 -p "日本の首都はどこですか?"
-m <ファイルパス>
: 使う GGUF モデル (.gguf) を指定。
-n-gpu-layers <数値>
: GPU に処理させるレイヤー数。99 など大きい値を指定すると、できるだけ GPU を使おうとします。GPU メモリが足りなければ減らします。0 だと CPU のみ。
-p <プロンプト>
: モデルへの指示を直接入力。
他にも多くのオプションがあります。例えば --threads
(CPUスレッド数)、--ctx-size
(コンテキストサイズ)、--temp
(生成の多様性) などです。詳細は llama-cli.exe -h
で確認できます。
7.2. 日本語プロンプトの文字化け問題
Windows のコマンドラインで、-p オプションに直接日本語を入れると、文字化けすることがよくあります。
# 文字化けする例
llama-cli.exe -m ./models/model.gguf -p "日本の首都は?"
# → モデル側でプロンプトが正しく認識されず、おかしな応答になる
これは、コマンドラインからプログラムへ文字が渡される際のエンコーディングの問題が原因です。
7.3. 解決策: プロンプトをファイルから読み込む
この文字化けを避ける一番確実な方法は、プロンプトをファイルに書いて、-f オプションで読み込ませることです。
プロンプトファイル作成:
メモ帳などでプロンプトを書きます。
例: prompt.txt
として models フォルダに保存。
prompt.txt
の中身 (Gemma Instruct モデルの場合の例):
<start_of_turn>user
日本で高い山を10個ランキング形式で教えてください<end_of_turn>
<start_of_turn>model
(使うモデルの推奨形式に合わせてください。モデルによっては <start_of_turn>
のような特殊なトークンが必要です。)
-f オプションで実行:
-p の代わりに -f でファイルを指定します。モデルの応答だけをファイルに保存したいなら、リダイレクト (>) が便利です。以下は、より多くのオプションを指定した実行例です。
llama-cli.exe --model .\models\gemma-3-4b-it-Q4_K_M.gguf --threads 8 --ctx-size 16384 --n-gpu-layers 99 --seed 3407 --temp 1.0 -f prompt.txt > output.txt
--model ...
: 使用するモデルファイル。
--threads 8
: CPU スレッド数を 8 に。
--ctx-size 16384
: コンテキストサイズを 16384 に。
--n-gpu-layers 99
: 可能な限り GPU にオフロード。
--seed 3407
: 乱数シードを指定 (再現性のため)。
--temp 1.0
: 生成温度を指定 (デフォルトに近い値)。
-f prompt.txt
: UTF-8 で保存した prompt.txt を読み込む。
> output.txt
: モデルの応答 (標準出力) を output.txt に書き出す。
実行ログ (標準エラー出力) は画面に出ます。
7.4. 実行結果の確認
コマンドを実行すると、モデルの読み込みログなどが画面に表示されます。
# (ログの例 - gemma-3-4b-it-Q4_K_M.gguf 実行時の一部抜粋)
ggml_cuda_init: GGML_CUDA_FORCE_MMQ: no
ggml_cuda_init: GGML_CUDA_FORCE_CUBLAS: no
ggml_cuda_init: found 1 CUDA devices:
Device 0: NVIDIA GeForce RTX 2070 SUPER, compute capability 7.5, VMM: yes
build: 5190 (558a7647) with MSVC 19.43.34810.0 for x64
main: llama backend init
main: load the model and apply lora adapter, if any
llama_model_load_from_file_impl: using device CUDA0 (NVIDIA GeForce RTX 2070 SUPER) - 7123 MiB free
llama_model_loader: loaded meta data with 40 key-value pairs and 444 tensors from .\gemma-3-4b-it-Q4_K_M.gguf (version GGUF V3 (latest))
... (メタデータ詳細) ...
print_info: file format = GGUF V3 (latest)
print_info: file type = Q4_K - Medium
print_info: file size = 2.31 GiB (5.12 BPW)
... (モデルパラメータ詳細) ...
load_tensors: loading model tensors, this can take a while... (mmap = true)
load_tensors: offloading 34 repeating layers to GPU
load_tensors: offloading output layer to GPU
load_tensors: offloaded 35/35 layers to GPU
load_tensors: CUDA0 model buffer size = 2368.31 MiB
load_tensors: CPU_Mapped model buffer size = 525.13 MiB
.................................................................
llama_context: constructing llama_context
llama_context: n_seq_max = 1
llama_context: n_ctx = 16384
llama_context: n_ctx_per_seq = 16384
llama_context: n_batch = 2048
llama_context: n_ubatch = 512
...
init: kv_size = 16384, offload = 1, type_k = 'f16', type_v = 'f16', n_layer = 34, can_shift = 1
init: CUDA0 KV buffer size = 2176.00 MiB
llama_context: KV self size = 2176.00 MiB, K (f16): 1088.00 MiB, V (f16): 1088.00 MiB
llama_context: CUDA0 compute buffer size = 517.12 MiB
llama_context: CUDA_Host compute buffer size = 69.01 MiB
...
common_init_from_params: warming up the model with an empty run - please wait ... (--no-warmup to disable)
main: llama threadpool init, n_threads = 8
system_info: n_threads = 8 (n_threads_batch = 8) / 16 | CUDA : ARCHS = 750 | F16 = 1 | USE_GRAPHS = 1 | PEER_MAX_BATCH_SIZE = 128 | CPU : SSE3 = 1 | SSSE3 = 1 | AVX = 1 | AVX2 = 1 | F16C = 1 | FMA = 1 | LLAMAFILE = 1 | OPENMP = 1 | AARCH64_REPACK = 1 |
sampler seed: 3407
... (サンプラーパラメータ詳細) ...
generate: n_ctx = 16384, n_batch = 2048, n_predict = -1, n_keep = 1
output.txt
にリダイレクトした場合、モデルの応答はファイルに書かれています。PowerShell で中身を見るなら、-Encoding UTF8
を付けると文字化けしません。
Get-Content .\output.txt -Encoding UTF8
もちろん、VS Code やメモ帳など、UTF-8 が読めるエディタで output.txt を開いてもOKです。
以下は、Gemma の gemma-3-4b-it-Q4_K_M.gguf
モデルを使用し、上記のコマンド例 (--seed 3407
, --temp 1.0
など) で生成された応答の実際の出力結果です。使用するモデルやパラメータによって結果は異なります。
user
日本で高い山を10個ランキング形式で教えてください
model
はい、日本で最も標高の高い山をランキング形式でご紹介します。
1. **富士山** (標高3,776.24m) - 標高、知名度ともに日本一であり、信仰の対象としても重要な山です。
2. **槍ヶ岳** (標高3,178m) - 北アルプスに位置し、その険しさと雄大さで知られています。
3. **本ヶ岳** (標高3,190m) - 北アルプスに属し、百名山の一つです。
4. **大山** (標高3,068m) - 山形県にある火山であり、美しい景観が魅力です。
5. **立法山** (標高3,060m) - 北アルプスに位置し、難易度の高い登山道として知られています。
6. **守門岳** (標高3,026m) - 雄大な北アルプスの象徴的な山の一つです。
7. **笠ヶ岳** (標高3,009m) - 北アルプスに属し、美しい穂高連峰の一部を構成しています。
8. **牛岳** (標高3,006m) - 北アルプスに位置し、北穂高縦脊梁の起点となります。
9. **剱岳** (標高3,093m) - 北アルプスを代表する山で、その独特な岩稜が特徴です。
10. **城ヶ岳** (標高3,080m) - 北アルプスに位置し、難易度の高い登山道で知られています。
**注意点:**
* 標高は概算であり、測量方法や時期によって若干異なる場合があります。
* これらの山は、登山経験や体力が必要な山です。登山には十分な準備と注意が必要です。
* 登山道は年々変化する可能性がありますので、最新の情報を必ず確認してください。
より詳しい情報が必要な場合は、各山の詳細な情報や登山ルートなど、具体的な質問をしてください。 [end of text]
8. おわりに
これで、Windows 11 で CUDA を使って llama.cpp をビルドし、日本語で実行する準備が整ったはずです。ビルド時の依存関係エラーは vcpkg で、日本語の文字化けはプロンプトを UTF-8 ファイルで読み込むことで、うまく対処できることが多いです。
この記事が、Windows で llama.cpp を使いたい人の助けになれば嬉しいです。
Discussion