Windows環境でllama-cpp-pythonをCUDA対応でビルドする完全ガイド
はじめに
Windows環境でllama-cpp-pythonをCUDA対応でビルドする際に遭遇する問題と、その解決方法を詳細にまとめました。特に「No CUDA toolset found」エラーに悩まされている方向けの実践的なガイドです。
環境情報
- OS: Windows 11
- Python: 3.11.7
- CUDA: 12.4
- Visual Studio: 2022
- GPU: NVIDIA RTX 4070 Ti Super
- CPU: AMD Ryzen 5 3600XT 6-Core
目標
llama-cpp-pythonをCUDA環境で利用し、NVIDIA GPUを使った高速なLLM（大規模言語モデル）推論を実現する。
前提条件の確認
1. 必要なソフトウェアのインストール
Visual Studio 2022
- Visual Studio 2022をインストール
-
重要:
C++ デスクトップ開発ワークロードを必ず選択 - 以下のコンポーネントが含まれていることを確認：
- MSVC v143 - VS 2022 C++ x64/x86 ビルド ツール
- Windows 11 SDK
- CMake tools for Visual Studio
CUDA Toolkit 12.4
- NVIDIA公式サイトからCUDA Toolkit 12.4をダウンロード
- カスタムインストールを選択
-
重要:
Visual Studio Integrationを必ず含める
Visual Studio Integrationを含めないと、後述のMSBuildExtensionsが配置されず、コンパイル時に「No CUDA toolset found」エラーが発生します。
遭遇した問題と解決過程
問題1: GPUが利用されない
症状: n_gpu_layersを設定してもCPUのみでモデルが実行される
# 設定例
llm = Llama(
model_path="path/to/model.gguf",
n_gpu_layers=-1, # 全レイヤーをGPUに
verbose=True
)
確認方法:
# NVIDIA GPU認識確認
nvidia-smi
# CUDA Toolkit確認
nvcc --version
問題2: ソースビルド時の「No CUDA toolset found」エラー
症状: CMakeでCUDAサポートを有効にしてビルドしようとすると失敗
# 失敗例
set CMAKE_ARGS=-DGGML_CUDA=ON
pip install llama-cpp-python --no-binary llama-cpp-python --verbose
エラーメッセージ:
No CUDA toolset found.
解決方法
核心的な解決策: MSBuildExtensionsの設定
根本原因: CUDA ToolkitのMSBuildExtensionsが正しく配置されていない
解決方法: 以下のパスが存在することを確認
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\extras\visual_studio_integration\MSBuildExtensions
このディレクトリにはCUDAコンパイラーの設定ファイルが含まれており、CMakeがCUDAツールセットを認識するために必要です。
解決手順
1. 仮想環境の準備
python -m venv venv
venv\Scripts\activate
2. 正しいコマンドプロンプトの使用
重要: 通常のコマンドプロンプトではなく、x64 Native Tools Command Prompt for VS 2022を管理者権限で起動
理由：
- llama.cppはAVX2、FMA命令セットを使用するためx64環境が必要
- CUDAツールセットとの連携にVisual Studioの開発者環境を指定するため
3. 環境変数の設定とビルド
# 仮想環境をアクティベート
.\venv\Scripts\activate
# CMAKE_ARGS環境変数を設定
set CMAKE_ARGS=-DGGML_CUDA=ON -DCMAKE_CUDA_COMPILER="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.4/bin/nvcc.exe" -DCUDA_TOOLKIT_ROOT_DIR="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.4" -DCUDA_ARCHITECTURES=native
# 設定確認
echo %CMAKE_ARGS%
# ソースからビルド
pip install llama-cpp-python --no-binary llama-cpp-python --force-reinstall --no-cache-dir --verbose
パラメータ説明
-
GGML_CUDA=ON: CUDA サポートを有効化（LLAMA_CUBLASは非推奨） -
CMAKE_CUDA_COMPILER: nvcc.exeの完全パス -
CUDA_TOOLKIT_ROOT_DIR: CUDA Toolkitのルートディレクトリ -
CUDA_ARCHITECTURES=native: 使用するGPUに最適化されたアーキテクチャを自動選択
動作確認
ビルド成功後、以下のコードで動作確認：
from llama_cpp import Llama
# verboseモードで詳細ログを確認
llm = Llama(
model_path="path/to/your/model.gguf",
n_gpu_layers=-1, #無制限割り当て
verbose=True
)
# ログで以下を確認
# - "CUDA device found"
# - "backend_ptrs.size() = 2" (CPU + GPU)
# - レイヤー割り当てで "dev = CUDA0"
トラブルシューティング
よくある問題
-
nvccが認識されない
- 環境変数PATHにCUDA\bin が含まれているか確認
- コマンドプロンプトを再起動
-
Visual Studio Integrationが不完全
- CUDA Toolkitを一度アンインストール
- Visual Studioが完全にインストールされた状態で再インストール
-
32ビット環境でビルドされる
- x64 Native Tools Command Promptを使用しているか確認
- 管理者権限で実行しているか確認
確認コマンド
# CUDA環境確認
nvidia-smi
nvcc --version
# Visual Studio確認
where cl.exe
# MSBuildExtensions確認
dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\extras\visual_studio_integration\MSBuildExtensions"
まとめ
Windows環境でllama-cpp-pythonをCUDA対応でビルドする際の最大のポイントは：
- Visual Studio Integrationを含めたCUDA Toolkitのインストール
- MSBuildExtensionsの正しい配置
- x64 Native Tools Command Promptの使用
- 管理者権限での実行
これらの条件を満たすことで、「No CUDA toolset found」エラーを回避し、GPUを活用した高速な推論が可能になります。
参考リンク
同じ問題で困っている方の参考になれば幸いです。