llama.cpp 是本地运行大模型的首选推理引擎，但官方预编译版本在 Linux 上不提供 CUDA 支持。本文记录了在 Fedora 44 系统上，使用 Toolbox 容器从源码编译支持 CUDA 13.2 的 llama.cpp 的完整过程，包括环境配置、依赖解决和性能优化。

为什么选择自己编译？

在尝试了多种方案后，我决定从源码编译 llama.cpp，主要基于以下考虑：

方案 优点 缺点
llama.cpp 预编译 免编译 官方不提供 Linux CUDA 版本
Ollama 一键安装，自动 CUDA 封装层，略重
Vulkan 后端 无需 CUDA Toolkit 性能损失约 20-30%
源码编译 性能最优，可定制 需要解决依赖问题

关键发现：llama.cpp 官方发布的 Linux 版本只有 CPU、Vulkan、ROCm 和 SYCL 后端，没有 CUDA 后端。CUDA 预编译仅限 Windows。这意味着在 Linux 上用 NVIDIA GPU 跑 llama.cpp，要么从源码编译，要么接受 Vulkan 的性能损失。

本机配置

我的开发环境如下：

项目 配置
OS Fedora 44 Workstation（内核 7.0.9-204.fc44.x86_64）
CPU AMD Ryzen 7 7840HS（Zen 4 架构，8核16线程）
GPU NVIDIA GeForce RTX 4060 Laptop（8GB GDDR6）
内存 32GB DDR5
CUDA 驱动 595.71.05（支持 CUDA 13.2）

关键限制：8GB 显存决定了模型量化方案，CUDA 13.2 需要特定版本的编译器支持。

编译环境选择：为什么用 Toolbox？

直接在主机上编译会污染系统环境，而 Docker 容器又过于笨重。Fedora Toolbox 是完美的折衷方案：

  • 环境隔离：与主机系统完全隔离，避免依赖冲突
  • 文件共享：自动挂载主机 $HOME 目录，方便访问模型文件
  • GPU 透传：自动透传 NVIDIA 驱动，只需配置 CUDA 运行时
  • 轻量级：基于 Podman，启动快速，资源占用少

详细编译步骤

1. 创建 Toolbox 容器

1
2
3
4
5
# 创建 Fedora 44 工具箱容器
toolbox create --assumeyes --image registry.fedoraproject.org/fedora-toolbox:44 --container fedora-toolbox-44-cuda

# 进入容器
toolbox enter --container fedora-toolbox-44-cuda

2. 安装基础开发工具

1
2
3
4
5
# 更新包管理器
sudo dnf distro-sync

# 安装编译工具链
sudo dnf install @c-development @development-tools cmake

3. 配置 CUDA Toolkit 13.2

3.1 添加 NVIDIA CUDA 仓库
1
2
3
4
5
# 添加 Fedora 43 的 CUDA 仓库（兼容 Fedora 44）
sudo dnf config-manager addrepo --from-repofile=https://developer.download.nvidia.com/compute/cuda/repos/fedora43/x86_64/cuda-fedora43.repo

# 同步仓库元数据
sudo dnf distro-sync
3.2 处理 NVIDIA 驱动透传

由于主机已安装 NVIDIA 驱动，容器内会自动挂载 libcuda.so.1。为避免文件冲突，我们只更新 RPM 数据库而不实际安装驱动：

1
2
3
4
5
6
# 下载驱动 RPM 包
sudo dnf download --destdir=/tmp/nvidia-driver-libs --resolve --arch x86_64 \
    nvidia-driver-cuda nvidia-driver-libs nvidia-driver-cuda-libs nvidia-persistenced

# 仅更新 RPM 数据库（不实际安装文件）
sudo rpm --install --verbose --hash --justdb /tmp/nvidia-driver-libs/*
3.3 安装 CUDA Toolkit
1
2
3
4
5
6
7
# 安装 CUDA Toolkit 元包
sudo dnf install cuda-toolkit

# 配置环境变量
sudo sh -c 'echo "export PATH=\$PATH:/usr/local/cuda/bin" >> /etc/profile.d/cuda.sh'
sudo chmod +x /etc/profile.d/cuda.sh
source /etc/profile.d/cuda.sh

验证安装：

1
2
nvcc --version
# 输出应显示：Cuda compilation tools, release 13.2

4. 解决 GCC 版本兼容性问题

CUDA 13.2 不支持默认的 GCC 16，需要安装 GCC 15：

1
2
3
4
5
6
# 安装 GCC 15 和 G++ 15
sudo dnf install gcc15 gcc15-c++

# 设置 NVCC 使用 GCC 15
export NVCC_CCBIN='g++-15'
echo 'export NVCC_CCBIN="g++-15"' >> ~/.bashrc

5. 获取并编译 llama.cpp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 克隆源码（使用浅克隆加速）
git clone --depth 1 https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# 创建构建目录
mkdir build && cd build

# 配置 CMake（启用 CUDA，禁用 WebUI）
cmake .. \
    -DGGML_CUDA=ON \
    -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc \
    -DLLAMA_BUILD_WEBUI=OFF

# 编译（使用所有 CPU 核心）
cmake --build . --config Release -j$(nproc)

WebUI 所需要的依赖下载很慢，我干脆禁用了 WebUI。

6. 验证安装

1
2
3
4
5
6
7
8
# 检查生成的二进制文件
ls -la ./bin/llama-*

# 测试 CUDA 支持
./bin/llama-cli --help | grep -i "gpu\|cuda"

# 验证 CUDA 库链接
ldd ./bin/libggml-cuda.so.0.11.1 | grep -i cuda

常见问题与解决方案

1. GCC 版本不兼容

错误：#error -- unsupported GNU version! gcc versions later than 15 are not supported!

解决：安装 GCC 15 并设置 NVCC_CCBIN='g++-15'

2. 驱动透传问题

现象：容器内无法访问 GPU

解决：确保主机 NVIDIA 驱动正常工作，重启容器：podman restart fedora-toolbox-44-cuda

3. WebUI 下载失败

错误：WebUI: failed to download assets from HF Bucket

解决：编译时添加 -DLLAMA_BUILD_WEBUI=OFF 禁用 WebUI

4. 模型加载错误

错误：missing tensor 'blk.32.ssm_conv1d.weight'

原因：某些模型（如 Qwopus3.5-9B-Coder-MTP）使用 MTP（多令牌预测）架构，需要特定版本的 llama.cpp。

解决：使用支持 MTP 的分支或选择非 MTP 版本的模型。

性能对比：容器内 vs 主机

指标 容器内编译 主机直接编译
环境隔离 ✅ 完全隔离 ❌ 依赖系统包
驱动兼容性 ✅ 自动透传 ✅ 原生支持
编译速度 略慢（容器开销） 快
系统影响 无 可能污染系统

使用建议

1. 模型推理

1
2
3
4
5
6
7
8
9
10
11
12
# 启动 API 服务器
./bin/llama-server \
    -m /path/to/model.gguf \
    -ngl 99 \
    --host 0.0.0.0 \
    --port 8080

# 命令行推理
./bin/llama-cli \
    -m /path/to/model.gguf \
    -p "你的提示词" \
    -ngl 99

2. 性能调优

  • 显存管理：根据显存调整 -ngl 参数（RTX 4060 8GB 建议 20-30 层）
  • 上下文长度：使用 -c 4096 设置合适的上下文长度
  • Flash Attention：启用 -fa on 提升推理速度
  • 量化选择：Q4_K_M 量化是 8GB 显存的最佳平衡点

3. 容器管理

1
2
3
4
5
6
7
8
# 退出容器后，快速进入
toolbox enter --container fedora-toolbox-44-cuda

# 停止容器
podman stop fedora-toolbox-44-cuda

# 重新启动
podman start fedora-toolbox-44-cuda

总结

通过本次编译，我获得了：

  1. 完全兼容的 CUDA 13.2 支持，充分发挥 RTX 4060 性能
  2. 干净隔离的开发环境，不影响主机系统稳定性
  3. 最新版本的 llama.cpp，支持所有新模型和功能
  4. 可复现的编译流程，便于后续更新和维护

关键收获：

  • 使用 Toolbox 容器是 Fedora 上进行 CUDA 开发的最佳实践
  • 版本兼容性问题（如 GCC 版本）需要提前解决
  • 自己编译虽然步骤较多，但能获得最佳性能和最新功能

对于希望在本机运行大模型的用户，我强烈推荐从源码编译 llama.cpp。虽然过程略显复杂，但带来的性能提升和灵活性是值得的。

参考资料：
llama.cpp 官方文档
NVIDIA CUDA 安装指南
Fedora Toolbox 文档
Multi-Token Prediction Tutorial