※画像はイメージです。本文と直接の関係はありません

llama.cpp 自前ビルドガイド（改訂版）

1. 結論 ― ソースからビルドすれば自分の環境に最適化できる

公式サイトが配布している実行ファイルは、サイズを抑えることと、さまざまな OS・CPU・GPU の組み合わせで動作させることを前提に、オプションが固定された形で提供されています。そのため、環境に合わせて設定を変えたい場合は、ソースからビルドし直す必要があります。

GPU バックエンド（CUDA、Vulkan、Metal、ROCm、SYCL など）
ハードウェア加速オプション（例：AVX512、CUDA コア利用）
ネットワーク機能（curl） の有無

これらをビルド時に自由に切り替えることで、ハードウェア構成や使用目的に最も適した実行ファイルを作成できます。

注：llama.cpp は推論専用エンジンです。モデルの学習（トレーニング）は対象外であり、ビルドはあくまで推論性能や機能拡張のために行います。

2. llama.cpp とは

概要：C++ で実装された軽量な大規模言語モデル（LLM）推論エンジンです。

主な特徴
- CPU だけでも実用的な速度で動作します。
- NVIDIA の CUDA、Vulkan、Apple の Metal、AMD の ROCm、SYCL など、複数の GPU バックエンドに対応しています。
- モデルは GGUF という量子化フォーマットで提供され、4 ビット量子化（Q4KM）にすれば 7 B（70 億パラメータ）モデルを約 4 GB に圧縮できます。

公式リリースは OS × CPU × GPU の組み合わせごとに多数のビルドが配布されていますが、独自の最適化や拡張はソースからビルドしなければ実現できません。
※ macOS ではデフォルトで Metal が有効になるため、特別な設定は不要です。

3. カスタマイズできるビルドオプションとその効果

・GPU バックエンド：使用したい GPU ライブラリを選択・ハードウェア加速：AVX512 や CUDA コア利用などの最適化を有効化・curl の有無：モデルの URL 直接取得機能の有無・半精度演算：GPU 上で 16 ビット浮動小数点演算を有効化

注：上記はすべて CMake に渡すオプションです。まず「何を有効にするか」を日本語で説明し、次の行に実際のオプションを書き出す形にしています。なお、llama.cpp のバージョンによっては LLAMA_CUDA という名前が使われていることがあります。使用中のリポジトリでオプション名を確認し、適切なものを選んでください。

4. ビルドが有効になるシーン

GPU をフル活用したい
→ CUDA・Vulkan・SYCL など、GPU に最適化されたバックエンドを選択できます。
モデルの量子化やカスタムオプションが必要
→ curl を無効化したり、半精度演算を有効にしたりできます。
デバッグや内部挙動の確認
→ ソースコードにブレークポイントを設定すれば、main.cpp の実行フローをステップ実行できます。
公式バイナリに無い機能を組み込みたい
例：llama‑server に独自の起動オプション（--host など）やログ出力フラグを追加できます。

5. ベンチマーク例（目安）

CPU のみ（例：1 B〜2 B の軽量モデル）：Q4KM 量子化で実行
RTX 3060（12 GB VRAM）でフルオフロード：Q4KM 量子化モデルを使用

測定条件：同一の Q4KM 量子化モデル、プロンプト長 4096、llama-cli のデフォルト設定で測定した目安です。CPU クロック数や GPU の VRAM 容量、-ngl（GPU オフロード層数）や -c（コンテキスト長）の設定により実際の数値は変動します。自分のハードウェアに合わせて -ngl と -c を調整すれば、同様の感覚で速度を確認できます。

6. Ubuntu（Linux）でのビルド手順

必要なパッケージ

sudo apt update && sudo apt install git git-lfs cmake g++ libcurlpp-dev
# Vulkan を利用する場合は追加で
sudo apt install vulkan-tools libvulkan-dev glslc

git と git-lfs：ソースコード取得用です。
cmake：ビルド設定生成ツールです。
libcurlpp-dev：C++ 用 curl ライブラリです。不要ならビルド時に -DLLAMA_CURL=OFF で除外できます。

ソース取得とデフォルト（CPU）ビルド

mkdir -p ~/git && cd ~/git
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release -j8

この手順だけで CPU 用の実行ファイルが build/bin に生成されます。

Vulkan ビルド（AMD GPU など）

Ubuntu の標準 gcc では Vulkan ビルドでエラーが出ることがあります。その場合は clang に切り替えてビルドします。

rm -rf build
CC=clang cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release -j8

vulkaninfo がエラーなく実行できれば GPU が正しく認識されています。

ビルド成果物

build/bin ディレクトリに以下が生成されます。
- llama-cli：コマンドラインインタフェース
- llama-server：サーバーモード
- llama-quantize：量子化ツール

7. Windows でのビルド手順

必要なツール

Visual Studio 2022（Community）＋ C++ デスクトップ開発 ワークロード（コンパイラが含まれます）
Visual Studio Build Tools（コマンドラインで cl を使用したい場合）
CMake（ビルド設定生成ツール）
Git for Windows（バージョン管理システム）
CUDA ツールキット（GPU を使う場合）
vcpkg（任意、libcurlpp など依存ライブラリの管理に使用）

vcpkg で curlpp をインストール（curl が不要なら省略可）

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg install curl[core,ssl]:x64-windows

curlpp を有効にすると、モデルの自動ダウンロード等のネットワーク機能が利用可能です。

ビルドディレクトリ作成と CMake 実行

Developer PowerShell for VS 2022 を起動します。
ソース取得は Ubuntu と同様に git clone してください。

(a) CUDA 有効化ビルド例

$env:CUDA_PATH="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8"
$env:Path="$env:CUDA_PATH\bin;$env:Path"
cmake -B build `
  -DGGML_CUDA=ON -DGGML_CUDA_F16=ON `
  -DCUDAToolkit_ROOT="$env:CUDA_PATH" `
  -DCMAKE_TOOLCHAIN_FILE="C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake"
cmake --build build --config Release --target llama-cli

備考：リポジトリのバージョンによっては GGML_CUDA が LLAMA_CUDA に名称変更されていることがあります。利用中のソースでオプション名を確認してください。

(b) curl 無効化ビルド例

cmake -B build -DLLAMA_CURL=OFF
cmake --build build --config Release

必要な DLL の自動配置

CMake の install オプションを利用すれば、CUDA ランタイムの動的リンクライブラリが自動的に配置されます。

cmake --install build --prefix "C:\llama\install"

インストール先の bin フォルダに実行ファイルと必要な DLL がまとめられます。手動でコピーする手順は不要です。

C:\llama\install\bin\llama-cli.exe が生成されます。好きなフォルダに配置すれば、コマンドラインからすぐに呼び出せます。

8. GPU オフロードと量子化の実践ポイント

GPU オフロード層数（-ngl）
- -ngl 999（VRAM が 12 GB 以上）
- -ngl 20（8 GB 程度のカード）

多くの層を GPU に載せると推論が速くなりますが、VRAM が足りないとクラッシュします。カードに合わせて調整してください。

コンテキスト長（-c）
- -c 4096（標準）
- -c 8192（長文が必要なとき）

長くすると KV キャッシュが増え、VRAM 消費が約 0.5 GB〜1 GB 増加します。

量子化レベル
- Q4KM（4 ビット）で 7 B モデルは約 4 GB に圧縮
メモリ使用量が大幅に削減され、低スペック PC でも実行可能になりますが、生成テキストの品質は若干低下することがあります（公式ドキュメントに基づく）。

温度・サンプリング
- --temp 0.7 --top-p 0.8 --top-k 20
生成のランダム性と品質のバランスを調整できます。

実行例（GPU フルオフロード、Q4KM 量子化モデル）

llama-cli -m "Llama-3.1-Swallow-8B-Instruct-v0.5-Q4_K_M.gguf" -ngl 999 -c 4096 -p "こんにちは、自己紹介してください。"

CPU のみで走らせるときは -ngl 0 とすれば OK です。量子化モデルがあれば、GPU がなくても数秒で応答が返ります。

9. よくあるトラブルと対処法

gcc でビルドエラー
- 原因：デフォルトの gcc が CUDA/Vulkan に非対応
- 対処：CC=clang に切り替えて再ビルド（Linux）
DLL が見つからない（Windows）
- 原因：CUDA のランタイム DLL が PATH に入っていない
- 対処：CUDA_PATH を設定し、cmake --install で自動配置させる
文字化け（Windows コンソール）
- 原因：デフォルトコードページが CP932
- 対処：chcp 65001 と [Console]::OutputEncoding = [Text.UTF8Encoding]::new() を実行
curl 関連のリンクエラー
- 原因：libcurlpp がインストールされていない
- 対処：sudo apt install libcurlpp-dev（Ubuntu）または -DLLAMA_CURL=OFF でビルド
Vulkan が検出されない
- 原因：vulkaninfo が未インストール、または GPU ドライバが古い
- 対処：sudo apt install vulkan-tools でインストールし、ドライバを最新に更新

10. FAQ（具体的なエラーや設定に関する質問）

CUDA のバージョンが 11 系しか入っていません
-DCUDAToolkit_ROOT にインストール済みのパス（例：C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8）を指定すればビルド可能です。バージョンは 11 系でも 12 系でも、正しいパスさえ設定すれば問題ありません。
gcc でも Vulkan ビルドはできますか？
環境によっては gcc のバージョンが対応していることがあります。その場合は CC=gcc のままで -DGGML_VULKAN=ON を実行してください。エラーが出たら clang に切り替えるのが確実です。
公式バイナリと比べてビルドにどれくらい時間がかかりますか？
cmake --build の実行はマシンにもよりますが、概ね 2〜5 分で完了します。ビルドは一度だけ必要な作業です。
llama-server に独自オプションを追加したい
ソースコードの server.cpp に自分のフラグや設定項目を実装し、CMake で再ビルドすれば組み込めます。公式バイナリには含まれないカスタム機能は、ソースビルドが唯一の手段です。
ビルドしたのに速度が変わらない
-ngl（GPU オフロード層数）や -c（コンテキスト長）を適切に指定しているか確認してください。GPU が有効でもオフロード層数が 0 のままでは CPU 推論と変わりません。

11. まとめ

ソースからビルド すれば、GPU バックエンド、ハードウェア加速オプション、curl の有無などを自由にカスタマイズでき、Windows でも Ubuntu でもローカル LLM を高速に動作させられます。
GPU オフロード（-ngl）と量子化（Q4_K_M） の組み合わせで、RTX 3060 でも 7 B 以上のモデルが安定して動作します。
多くのトラブルは 環境変数の設定 と 依存ライブラリの有無 が原因です。エラーメッセージを注意深く確認し、上記の対処法を参考にしてください。

本ガイドに沿って自分の環境に最適化したビルドを行い、ローカル AI の活用をぜひお試しください。

雑記

2026/07/08