📌

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: ビルドシステム生成ツール。
  • Git for Windows: ソースコードの取得に使います。
  • CUDA Toolkit: NVIDIA GPU を使う場合に必要。GPU ドライバと互換性のあるバージョンを選んでください。
  • 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):

  1. Windows 検索で「環境変数」と入力し、「システム環境変数の編集」を開く。
  2. 「環境変数」ボタンをクリック。
  3. 「ユーザー環境変数」か「システム環境変数」の Path を選んで「編集」。(システム環境変数だと全ユーザーで有効に)
  4. 「新規」で llama.cpp の実行ファイルがあるパス (例: C:\dev\llama.cpp\build\bin\Release) を追加。
  5. 「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