在 Ubuntu 26.04 上编译与生产级部署 llama.cpp (支持 AMD ROCm 加速与 UMA 极致优化)

Mon, 01 Jun 2026 10:00:00 +0800

llama.cpp 是目前在本地设备上高效推理大语言模型（LLM）的最强利器之一。它不仅支持极致的纯 CPU 推理，还能完美适配各类硬件加速框架。随着硬件的发展，利用高性价比的高性能集显配合 BIOS 调配的大容量 UMA（统一内存架构）共享显存（如我们的 48GB 配置），在本地流畅运行中大型旗舰模型已成为现实。

本文将详细记录如何在最新的 Ubuntu 26.04 LTS 环境下，从底层驱动安装、系统依赖打通、源码编译、Python 生态构建，到最终通过 systemd 守护进程实现企业级安全、高可用部署的完整全栈指南。

1. 系统环境与基础依赖准备

在正式开始底层编译与环境配置之前，必须确保系统处于最新状态，并准备好完整的 C++ 构建工具链以及网络通信相关的核心开发包。

# 更新系统软件源与已安装的软件包
sudo apt update && sudo apt upgrade -y

# 安装基础编译环境及常用命令行工具
sudo apt install build-essential cmake git wget curl gnupg2 -y

# 安装网络及加密相关的核心开发库
sudo apt install libssl-dev libcurl4-openssl-dev -y

2. 打通 AMD GPU 底层驱动层 (ROCm 安装)

为了完全释放 AMD 硬件的算力，我们需要部署 AMD ROCm 深度学习框架。以下采用最新的自动化包管理配置流程（以 ROCm 7.2.3 为例）。

2.1 配置 APT 仓库与密钥

# 创建密钥存放目录
sudo mkdir -p /etc/apt/keyrings

# 下载并导入 AMD 官方 GPG 密钥
wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \
gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null

# 添加软件源
sudo tee /etc/apt/sources.list.d/rocm.list << EOF
deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/7.2.3 noble main
deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/graphics/7.2.3/ubuntu noble main
EOF

# 设置 APT Pin 优先级，防止后续系统更新时遭遇非官方包覆盖冲突
sudo tee /etc/apt/preferences.d/rocm-pin-600 << EOF
Package: *
Pin: release o=repo.radeon.com
Pin-Priority: 600
EOF

2.2 安装驱动与运行时

sudo apt update
# 完整安装 ROCm 运行时环境（包含 HIP SDK、OpenCL 等全套开发工具）
sudo apt install rocm -y

2.3 权限分配与架构环境变量配置

要让非 root 用户能够直接调用硬件算力，必须分配相应的硬件设备组权限：

# 将当前用户加入 render 和 video 用户组
sudo usermod -a -G render,video $USER

注意： 执行完权限分配后，必须重启系统或注销重新登录才能生效。

针对特定的核显架构（如 Radeon 890M 对应的 gfx1150），官方运行时默认白名单可能未完全覆盖。建议向全局环境中注入以下覆盖变量，强制指定兼容的硬件架构：

echo 'export HSA_OVERRIDE_GFX_VERSION=11.5.0' >> ~/.bashrc
echo 'export ROCR_VISIBLE_DEVICES=0' >> ~/.bashrc
source ~/.bashrc

3. 避坑指北：解决动态链接库 (libxml2) 报错

在最新的 Ubuntu 26.04 LTS 系统中，许多底层系统库进行了主版本升级（例如默认自带 libxml2.so.16）。然而，部分预编译的 AI 组件或驱动程序可能仍顽固地链接旧版本的 libxml2.so.2。若遇到 Shared object file not found 报错，请执行以下标准运维方案：

# 1. 确保已安装新版的 libxml2 及开发包
sudo apt install libxml2-16 libxml2-dev -y

# 2. 创建向后兼容的动态库软链接
sudo ln -s /usr/lib/x86_64-linux-gnu/libxml2.so.16 /usr/lib/x86_64-linux-gnu/libxml2.so.2

# 3. 刷新系统动态链接库缓存（关键！确保系统立刻识别到新的软链接）
sudo ldconfig

4. 获取 llama.cpp 源码与进行编译

准备好底层环境后，即可从官方 GitHub 仓库克隆最新的源码，并通过 CMake 开启 HIP (ROCm) 后端加速构建。

# 克隆官方最新源码仓库
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# 创建并进入构建目录
mkdir build && cd build

# 运行 CMake 配置 (通过 -DGGML_HIP=ON 激活 AMD GPU 加速，并指定目标架构)
cmake .. -DGGML_HIP=ON -DAMDGPU_TARGETS=gfx1150

# 开始多线程并行编译
make -j$(nproc)

4.1 全局安装部署

编译完成后，核心的可执行文件（如 llama-cli 和 llama-server）会生成在 build/bin/ 目录下。执行系统级规范安装：

# 将编译产物安装到系统路径 (通常位于 /usr/local/bin)
sudo cmake --install build

5. Hugging Face 镜像加速与模型获取

配置官方国内镜像站并使用更加简短高效的 hf 命令（huggingface-cli 的官方别名）能够提供极致且稳定的下载体验。这里我们以高性能的 Gemma-4-31B 模型的无限制版本为例：

# 1. 配置镜像环境变量（永久写入 .bashrc）
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

# 2. 安装 Python Hugging Face 官方客户端
pip3 install -U "huggingface_hub[cli]"

# 3. 使用极简 CLI 命令高速下载特定的 GGUF 格式大模型
hf download \
  HauhauCS/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive \
  --local-dir /home/siyuan \
  --local-dir-use-symlinks False

6. 拓展配置：构建完整的 Python AI 生态

为了执行模型量化转换或运行上层高阶深度学习框架，本地算力节点必须配置适配 ROCm 的原生 PyTorch 环境。

# 升级 pip 以避免老版本解析错误
pip install --upgrade pip

# 从 PyTorch 官方源安装适配 ROCm 7.2 的最新专属版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2

7. 进阶实战：企业级服务部署与极致显存优化

我们将挑战在一台 48GB 共享显存的主机上，全量加速运行刚才下载的 Gemma-4-31B 旗舰模型，并激进地开启 128K (131,072 Token) 超长上下文窗口：

/usr/local/bin/llama-server \
  -m Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-Q8_K_P.gguf \
  --mmproj mmproj-Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-f16.gguf \
  --jinja \
  -c 131072 \
  -ngl 99 \
  --temp 0.6 \
  --top-p 0.95 \
  --top-k 20 \
  --min-p 0 \
  --presence-penalty 0 \
  --flash-attn \
  --cache-type-k q8_0 \
  --cache-type-v q8_0 \
  --no-mmap \
  --api-key "你的自定义密码" \
  --host 0.0.0.0 \
  --port 8070

核心参数与极限榨干算力解析：

–no-mmap（UMA 核心调优）：对于共享系统内存的集显架构，禁用内存映射强制系统将巨型模型权重一次性锁死在物理内存中。这不仅防止了页面置换，还能大幅稳定首字延迟。
–flash-attn（闪电注意力）：处理 128K 超长上下文的绝对核心，显著降低长文本下的显存开销。
–cache-type-k q8_0 –cache-type-v q8_0：将巨大的 KV 缓存显存开销直接压缩近一倍，是 31B 级别模型在 48GB 物理边界内完美运转的底线。

8. 生产环境收尾：配置 systemd 守护进程与开机自启

8.1 创建 Service 配置文件

sudo nano /etc/systemd/system/gemma.service

将以下完全打磨好的工业级配置模板粘贴进去：

[Unit]
Description=Gemma 4 31B LLM Service (ROCm Accelerated & UMA Optimized)
After=network.target

[Service]
Type=simple
User=your_username
Group=your_username

# 极端重要：设置模型文件所在的绝对路径工作目录
WorkingDirectory=/home/siyuan/

# 注入 AMD 架构兼容环境变量
Environment="HSA_OVERRIDE_GFX_VERSION=11.5.0"
Environment="ROCR_VISIBLE_DEVICES=0"

# 启动命令
ExecStart=/usr/local/bin/llama-server \
  -m Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-Q8_K_P.gguf \
  --mmproj mmproj-Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-f16.gguf \
  --jinja \
  -c 131072 \
  -ngl 99 \
  --temp 0.6 \
  --top-p 0.95 \
  --top-k 20 \
  --min-p 0 \
  --presence-penalty 0 \
  --flash-attn \
  --cache-type-k q8_0 \
  --cache-type-v q8_0 \
  --no-mmap \
  --api-key "你的自定义密码" \
  --host 0.0.0.0 \
  --port 8070

Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

8.2 启动与状态监控

# 重新加载 systemd 守护进程配置
sudo systemctl daemon-reload

# 启用服务开机自启并立即启动
sudo systemctl enable --now gemma.service

# 查看实时日志
sudo journalctl -u gemma.service -f

总结与展望 通过在最新的 Ubuntu 26.04 环境下对 ROCm 底层驱动、编译链、KV 缓存及内存分配的细致调优，我们成功构建了一个具备工业级高可用性、支持 128K 超长上下文的本地算力节点。基于大容量统一内存（UMA）的极限压榨方案，让我们得以为复杂系统的核心开发、高性能量化回测等敏感数据业务，提供了一层彻底隔离于公网、绝对安全且成本极低的顶尖 AI 算力底座。

远思码技术实验室 远思为径，码动价值。

UMA调优 on 远思码技术实验室