Docker 部署 llama.cpp 文档(硬件 A100 40G显卡 + 256G ECC内存 + 双路6348 CPU)

适用硬件：NVIDIA A100 SXM4 40GB
系统：Ubuntu 22.04
镜像：ghcr.io/ggml-org/llama.cpp:server-cuda
场景：Qwen3.6-35B MoE 超大上下文推理，单人独占优化方案

前置条件：服务器全新Ubuntu22.04系统，拥有root/sudo权限；模型GGUF文件提前放置 /home/wangyu/Models/

一、宿主机基础环境部署

1.1 更新系统软件源

sudo apt update && sudo apt upgrade -y

1.2 安装A100 NVIDIA数据中心驱动

A100仅支持数据中心驱动，推荐595版本，兼容CUDA12.4

# 安装内核依赖
sudo apt install linux-headers-$(uname -r) build-essential -y

# 添加NVIDIA容器软件源
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update

# 安装驱动
sudo apt install nvidia-driver-595

安装完成重启服务器

sudo reboot

重启后验证驱动：

nvidia-smi

正常输出A100显卡信息代表驱动部署成功。

1.3 安装Docker与NVIDIA容器工具链

# 安装docker
sudo apt install docker.io -y
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
# 重新登录终端，用户docker组权限生效

# 安装GPU容器透传组件
sudo apt install nvidia-container-toolkit -y

# 配置Docker默认GPU运行时
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

GPU透传验证

docker run --rm --gpus all nvidia/cuda:12.4-base nvidia-smi

命令正常打印A100信息，代表容器可以正常调用显卡。

1.4 宿主机内核&GPU调优（推荐执行，提升推理稳定性）

作用说明：

vm.swappiness=10：降低系统使用swap交换分区积极性，尽量把模型保留在物理内存，避免swap磁盘读写造成推理卡顿；不建议设置0，防止触发系统OOM机制。
vm.min_free_kbytes=4194304：强制预留4GB空闲内存，抑制系统突发内存回收引发性能抖动，适配大内存服务器长文本连续推理场景。
nvidia-smi -pm 1：开启A100持久模式，驱动常驻GPU不卸载，消除空闲后再次推理的CUDA硬件初始化延迟；重启服务器后失效。

临时生效命令：

sudo sysctl -w vm.swappiness=10
sudo sysctl -w vm.min_free_kbytes=4194304
sudo nvidia-smi -pm 1

永久写入内核配置（重启保留）：

echo "vm.swappiness=10" | sudo tee -a /etc/sysctl.conf
echo "vm.min_free_kbytes=4194304" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

备注：nvidia-smi -pm 1 重启失效，如需永久生效可配置开机自启任务；内存小于64GB服务器建议下调vm.min_free_kbytes。

二、Docker启动脚本

新建启动脚本 start_llama.sh

#!/bin/bash
docker rm -f llama-cpp

docker run -d \
  --gpus all \
  --ulimit memlock=-1:-1 \
  -p 11534:11534 \
  -v /home/wangyu/Models:/models \
  --name llama-cpp \
  --restart unless-stopped \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m /models/Qwen3.6-35B-A3B-Claude-4.7-Opus-Reasoning-Distilled-APEX-MTP-I-Balanced.gguf \
  --port 11534 \
  --host 0.0.0.0 \
  --n-gpu-layers 99 \
  --ctx-size 262144 \
  --cache-type-k q4_0 \
  --cache-type-v q4_0 \
  --batch-size 1024 \
  --parallel 1 \
  --threads 40 \
  --threads-batch 20 \
  --load-mode mlock \
  --flash-attn on

赋予执行权限并启动服务

chmod +x start_llama.sh
./start_llama.sh

三、基础运维命令

# 实时查看运行日志
docker logs -f llama-cpp

# 停止服务
docker stop llama-cpp

# 重启服务
docker restart llama-cpp

# 销毁容器
docker rm -f llama-cpp

✅ 启动成功标志：日志输出 server listening on http://0.0.0.0:11534
访问地址：http://服务器IP:11534

四、全部参数详细解释

4.1 Docker容器层参数

--gpus all
将宿主机全部NVIDIA显卡透传至容器；可选：--gpus 0 仅使用0号显卡。
--ulimit memlock=-1:-1
解除容器内存锁定上限，保证--load-mode mlock正常工作，消除failed to mlock警告；环境不支持该参数时删除此条，同时加载模式切换为none。
-p 11534:11534
端口映射，格式：宿主机端口:容器内部端口，用于WebUI与OpenAI兼容API访问。
-v /home/wangyu/Models:/models
目录挂载，宿主机模型文件夹映射到容器内/models；模型路径变更时同步修改。
--name llama-cpp
自定义容器名称，简化运维操作。
--restart unless-stopped
容器重启策略：手动停止容器不会自动重启；服务器意外断电、崩溃自动拉起推理服务。
ghcr.io/ggml-org/llama.cpp:server-cuda
llama.cpp官方预编译CUDA镜像，提供GPU硬件加速推理后端。

4.2 llama.cpp 推理核心参数

-m /models/xxx.gguf
指定GGUF模型文件路径，必填参数。
--port 11534
服务监听端口，必须与Docker端口映射保持一致。
--host 0.0.0.0
网络监听地址
- 0.0.0.0：允许局域网/外部IP访问
- 127.0.0.1：仅本机访问，安全性更高
--n-gpu-layers 99
GPU卸载层数，数值大于模型总层数=全部网络层加载至A100显存；
调小参数可将部分网络层放入内存，降低显存占用（代价：推理速度下降）。
--ctx-size 262144
上下文窗口大小，单位token；数值越大KV缓存显存占用越高，A100 40GB存在显存上限，显存溢出时按需下调。
--cache-type-k q4_0
K键缓存量化方案；可选：f16 / q8_0 / q5_1 / q4_0；q4_0显存占用最低，长上下文场景首选。
--cache-type-v q4_0
V值缓存量化方案，建议与K缓存保持一致。
--batch-size 1024
Prefill预填充批大小；大批量导入长文本、文档时，更大batch可以提升文本灌入速度。
--parallel 1
最大并发会话数量；超大上下文场景，多会话极易耗尽40GB显存，固定1适配单人独占场景。
--threads 40
CPU主线程数，用于文本预处理、采样、任务调度；可测试40/48两组线程对比性能。
--threads-batch 20
Prefill阶段专用线程池，优化长文本编码速度。
--load-mode mlock
模型加载模式，可选值：
- mmap：内存映射懒加载，启动快，运行中可能触发磁盘缺页卡顿（默认模式）
- none：一次性完整读取模型，不使用mmap，不尝试锁定内存
- mlock：一次性完整读取模型，尝试锁定物理内存（本文档使用方案）
- mmap+mlock：mmap映射 + 锁定内存
- dio：DirectIO直读磁盘模式
  容器ulimit不支持锁内存时，切换为none消除警告。
--flash-attn on
FlashAttention优化开关；可选值：on / off / auto；开启后大幅降低超长上下文KV显存占用，A100环境推荐启用。

4.3 可选安全增强参数（公网暴露务必添加）

在启动命令末尾追加：

--api-key 自定义高强度密钥

开启身份校验，WebUI、API请求必须携带密钥，防止算力被他人滥用。

4.4 当前镜像不支持参数（禁止添加）

--cuda-stream、--pin-mem、--graph-pool、--kv-cache-prealloc
加入会触发参数解析错误、容器启动失败，属于新版本主干新增特性，当前官方镜像未内置。

五、常见故障排查

警告 failed to mlock
方案：保留--ulimit memlock=-1:-1；无法修改ulimit时，--load-mode mlock改为--load-mode none。
CUDA out of memory 显存溢出
方案①：下调--ctx-size；方案②：降低--n-gpu-layers，少量网络层放到内存运行。
网页无法访问
放行防火墙端口：
```
sudo ufw allow 11534/tcp
```
GPU利用率持续为0
属于正常空闲状态；发送对话请求后，负载会立刻上升。

六、性能调优建议

线程两组对比测试：threads=40 threads-batch=20 VS threads=48 threads-batch=24，保留token生成速度更高的配置；
性能观测指标：长文本灌入看 prompt eval tokens/sec；回答生成看 eval tokens/sec；
显存压力大时，优先缩小上下文ctx-size，其次降低GPU卸载层数。

Linux || Docker 部署 llama.cpp 文档(硬件 A100 40G显卡 + 256G ECC内存 + 双路6348 CPU)