WSL 2 编译 llama.cpp

在 WSL 2 中编译支持 CUDA 的 llama.cpp，用于加载 gguf 格式的模型。

---

环境准备

WSL 2 内 CUDA 程序调用显卡的流程如下：

---
config:
  theme: 'base'
  themeVariables:
    darkMode: true
    fontSize: 16px
    primaryColor: '#000'
    primaryTextColor: '#fff'
    primaryBorderColor: '#02d7f2'
    lineColor: '#fcee09'
    tertiaryColor: '#0d0d0d'
    tertiaryBorderColor: '#cdcdcd'
---
flowchart TB
  subgraph WSL
    direction TB
    A
    B
    C
  end
  subgraph Windows
    direction TB
    D
    E
  end
  A["`CUDA Application
  (PyTorch/vLLM/llama.cpp/...)`"] e1@--> B["`CUDA Runtime
  (libcudart.so/libcublas.so/libcublasLt.so/...)`"] e2@--> C["libcuda.so"] e3@-- 转发 --> D["NVIDIA Driver"] e4@--> E["NVIDIA GPU"]
  e1@{ animate: true }
  e2@{ animate: true }
  e3@{ animate: true }
  e4@{ animate: true }

从图中可以看出来，运行 llama.cpp 等 CUDA 程序需要显卡驱动和 CUDA Runtime，下面介绍如何准备上述环境。

显卡驱动

原生 Linux 系统想要使用显卡需要下载并安装 NVIDIA 显卡驱动，但在 WSL 2 中需要跳过此步骤，因为 WSL 2 会将 Windows 上的显卡驱动能力映射到 WSL 2 内：

# 查看 wsl 通过文件映射复用的 Windows 硬件驱动资源
$ ls -lh /usr/lib/wsl/lib/
-r-xr-xr-x 4 root root 184K Jun 12 09:41 libcuda.so
...
-r-xr-xr-x 2 root root 840K Jun 12 09:41 nvidia-smi

文件	说明
libcuda.so	显卡驱动。但 WSL 2 内的 libcuda.so 文件比较特殊，它只负责将请求转发给 Windows 上真正的显卡驱动，相当于一个代理。
nvidia-smi	NVIDIA 系统管理界面，用于查询和管理 GPU 的运行状态。

查看显卡信息：

# 使用 nvidia-smi 查看显卡状态
# Windows 上更新显卡驱动，这里显示的版本信息也会随之变化
$ nvidia-smi
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 610.43.02              KMD Version: 610.62        CUDA UMD Version: 13.3     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 5080        On  |   00000000:01:00.0  On |                  N/A |
| 30%   39C    P0             43W /  360W |    1645MiB /  16303MiB |      5%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

注意：nvidia-smi 命令显示 CUDA UMD Version: 13.3 的意思是显卡驱动支持的 CUDA Runtime API 版本最高为 13.3，不代表 WSL 2 中存在 CUDA Runtime。

CUDA Toolkit

CUDA Runtime 以及编译 llama.cpp 需要用到的 CUDA 编译器 nvcc，都需要通过安装 CUDA Toolkit 来得到：

# 下载并安装 NVIDIA CUDA 软件源
$ wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
$ sudo dpkg -i cuda-keyring_1.1-1_all.deb

# 更新软件包列表
$ sudo apt-get update

# 安装 CUDA Toolkit 12.9
$ sudo apt-get -y install cuda-toolkit-12-9

# 确认安装结果
$ nvcc --version
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2025 NVIDIA Corporation
Built on Tue_May_27_02:21:03_PDT_2025
Cuda compilation tools, release 12.9, V12.9.86
Build cuda_12.9.r12.9/compiler.36037853_0

注意：CUDA Toolkit 应选择 llama.cpp 支持的版本，我之前使用 13.3 版本编译出来的 llama-cli 运行时报错 munmap_chunk(): invalid pointer 无法运行，降级到 12.9 版本后正常。

编译 llama.cpp

准备编译工具

确认编译工具是否存在：

# 查看 cmake 版本
# 它用于生成构建文件，并调用编译工具执行编译
$ cmake --version
cmake version 3.28.3

# 查看 cc 版本
# 它用于将 .c/.cpp 源代码编译成机器码
$ cc --version
cc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0

# 如果上面的命令不存在，可以安装 cc 和 cmake
$ sudo apt install -y build-essential
$ sudo apt install -y cmake

编译步骤

编译适配本机的 llama.cpp 参考以下流程：

# 1. 拉取代码并进入项目目录
$ git clone https://github.com/ggml-org/llama.cpp
$ cd llama.cpp/

# 2.a 根据本机环境生成构建文件，启用 CUDA 后端支持
# -DGGML_CUDA=ON：启用 GGML 张量计算库的 CUDA 后端支持
$ cmake -B build -DGGML_CUDA=ON

# 3. 执行编译
$ cmake --build build --config Release

# 编译得到的可执行文件存放在 build/bin 下面
$ cd build/bin/ 
# 测试 llama-cli 命令
$ ./llama-cli --version
version: 9859 (4fc4ec554)
built with GNU 13.3.0 for Linux x86_64

如果想让编译出来的可执行文件支持多种型号的显卡，需要知道目标显卡的计算能力（Compute Capability），并在生成构建文件时写入该值。计算能力可以在 计算能力列表 查到，也可以使用 nvidia-smi 命令查询到：

# 查询本机显卡的计算能力
$ nvidia-smi --query-gpu=name,compute_cap 
name, compute_cap
NVIDIA GeForce RTX 5080, 12.0

# 在不同 GPU 服务器执行
$ nvidia-smi --query-gpu=name,compute_cap --format=csv
name, compute_cap
Tesla V100-PCIE-16GB, 7.0
Tesla V100-PCIE-16GB, 7.0
Tesla V100-PCIE-16GB, 7.0
Tesla V100-PCIE-16GB, 7.0
$ nvidia-smi --query-gpu=name,compute_cap --format=csv
name, compute_cap
Tesla T4, 7.5
Tesla T4, 7.5
Tesla T4, 7.5
Tesla T4, 7.5

# 2.b 生成构建文件，支持 GPU 服务器上的两种显卡
$ cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="70;75"

加载模型

llama.cpp/build/bin/

# 加载模型
$ ./llama-cli -m /mnt/c/Users/ThinkLong/.lmstudio/models/HauhauCS/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-Q4_K_P.gguf --mmproj /mnt/c/Users/ThinkLong/.lmstudio/models/HauhauCS/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive/mmproj-Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-f16.gguf --jinja -c 131072 -ngl 40 -t 16 -b 2048 -ub 512  -fa on --no-mmap --n-cpu-moe 28

---

参考资料

Qwen - llama.cpp 编译指南