Windows 下 llama-cpp-python CUDA 本地编译实战指南

在 Windows 构建本地大模型推理环境时，直接使用 pip install llama-cpp-python 往往只能获得 CPU 版本（速度仅 2 token/s）。为了激活 NVIDIA 显卡的 Tensor Cores 加速，必须进行本地编译。

遇到的核心问题

本次遭遇的特殊困难在于系统同时安装了多个 Visual Studio 版本（2019, 2022, 2026 Preview）。CMake 默认自动调用最新的 VS 2026 Preview，但 CUDA 13.1 的编译脚本尚未适配该预览版 IDE，导致 CMake 找不到 CUDA 工具链，从而静默回退到 CPU 模式。这会造成'安装成功但无加速'的假象，排查起来非常隐蔽。

编译实施步骤

1. 净化环境与预备

确保虚拟环境纯净，安装必要的编译辅助工具。这一步很关键，防止 pip 复用旧的 CPU 版缓存。

REM 1. 激活虚拟环境
.venv\Scripts\activate

REM 2. 在环境中安装 torch+cuda
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

REM 3. 清理可能存在的错误缓存
pip cache purge
pip uninstall llama-cpp-python -y

REM 4. 安装构建依赖
pip install scikit-build-core cmake ninja setuptools wheel

2. 配置精确编译参数

这是解决多 VS 版本冲突的关键。我们通过环境变量强制 CMake 使用 VS 2022 生成器，而不是默认的 VS 2026。

REM 设置 CMake 参数
REM -DGGML_CUDA=on : 开启 CUDA 加速
REM -G "Visual Studio 17 2022" : 强制指定 VS 2022 生成器 (避开 Preview 版 BUG)
REM -A x64 : 强制构建 64 位版本
set CMAKE_ARGS=-DGGML_CUDA=on -G "Visual Studio 17 2022" -A x64

3. 执行源码编译

让 pip 下载源码并调用本地编译器构建 Wheel。

REM --no-cache-dir : 禁用缓存，强制重编
REM --force-reinstall : 强制重装
REM --upgrade : 确保最新版
pip install llama-cpp-python --no-cache-dir --force-reinstall --upgrade

预期耗时 3-10 分钟。若看到滚屏日志中出现 Successfully installed ... llama-cpp-python-0.3.16 ... 即代表成功。

Windows 下 llama-cpp-python CUDA 本地编译实战指南