llama.cpp Docker 镜像实战指南：从 full/light/server 三镜像体系到 CUDA、MUSA、SYCL 本地构建

本文基于仓库官方文档 docs/docker.md 整理，系统讲解 llama.cpp 提供的 Docker 镜像体系（full / light / server 三类基础镜像及 CUDA、ROCm、MUSA、SYCL、Vulkan、OpenVino 等 GPU 变体），并结合 .devops/ 下的 Dockerfile 与 .github/workflows/docker.yml 剖析镜像的多阶段构建逻辑与入口脚本，帮助读者完成"拉取镜像 → 模型转换与量化 → CLI/Server 推理 → 本地定制构建"的完整 Docker 化推理流程。

一、前置条件

按照文档 docs/docker.md 的说明，使用 Docker 运行 llama.cpp 需要满足两个前提：

1. 系统中已安装并正在运行 Docker；
2. 准备一个文件夹用于存放大模型文件与中间产物，例如 /llama/models（文档中统一以 /path/to/models 指代该目录，后文命令需替换为真实路径）。

该目录稍后会被挂载进容器的 /models 路径，容器内所有模型读写都发生在这个挂载卷上，因此宿主机目录中的权重文件在容器外始终可见、可复用。

二、官方镜像体系：full / light / server 三个构建目标

llama.cpp 通过一套多阶段 Dockerfile（CPU 基线为 .devops/cpu.Dockerfile）构建出三类核心镜像，对应 Dockerfile 末尾的三个构建目标（full、light、server）：

镜像	内容	平台
ghcr.io/ggml-org/llama.cpp:full	同时包含 llama-cli 与 llama-completion 可执行文件，以及把 LLaMA 模型转换为 ggml 并量化为 4-bit 的工具链	linux/amd64、linux/arm64、linux/s390x
ghcr.io/ggml-org/llama.cpp:light	仅包含 llama-cli 与 llama-completion 可执行文件	linux/amd64、linux/arm64、linux/s390x
ghcr.io/ggml-org/llama.cpp:server	仅包含 llama-server 可执行文件	linux/amd64、linux/arm64、linux/s390x

在此基础上，官方还提供了一组与上述镜像功能相同、但编译了不同后端加速的变体（平台列表来自 docs/docker.md）：

• CUDA 12：full-cuda、light-cuda、server-cuda（linux/amd64、linux/arm64）
• CUDA 13：full-cuda13、light-cuda13、server-cuda13（linux/amd64、linux/arm64）
• ROCm：full-rocm、light-rocm、server-rocm（linux/amd64）
• MUSA（摩尔线程）：full-musa、light-musa、server-musa（linux/amd64）
• SYCL（Intel）：full-intel、light-intel、server-intel（linux/amd64）
• Vulkan：full-vulkan、light-vulkan、server-vulkan（linux/amd64、linux/arm64）
• OpenVino：full-openvino、light-openvino、server-openvino（linux/amd64）
• s390x 别名：full-s390x、light-s390x、server-s390x，与 full / light / server 完全相同，仅作为 s390x 平台的别名（linux/s390x）

文档同时给出一个重要提示：GPU 变体镜像目前除了被构建出来之外并不做 CI 功能测试，它们与 .devops/ 中定义的 Dockerfile 以及 .github/workflows/docker.yml 这个 GitHub Action 所构建的镜像没有任何差异。如果你需要不同的设置（例如不同的 CUDA、ROCm 或 MUSA 库版本），目前需要在本地自行构建镜像——这正是后文"本地构建"各节要解决的问题。

从 Dockerfile 看三类目标的内容差异

查看 .devops/cpu.Dockerfile 可以确认三类镜像的具体差异，它们全部来自同一个 build 阶段编译出的产物：

• full 目标（L81-L102）：把整个 /app/full 目录拷入镜像，该目录在 build 阶段（L46-L53）不仅包含 build/bin/* 全部编译产物，还包含根目录的 *.py 转换脚本、conversion/、gguf-py/、requirements/ 以及 tools.sh 入口脚本，并通过 pip install -r requirements.txt 安装了 Python 依赖——这就是它"能转换模型"的原因。
• light 目标（L104-L111）：仅拷贝 llama、llama-cli、llama-completion 三个文件，入口为 /app/llama-cli。
• server 目标（L113-L123）：仅拷贝 llama 与 llama-server，入口为 /app/llama-server，并预置了环境变量 LLAMA_ARG_HOST=0.0.0.0（因此容器默认监听所有网卡），还配置了健康检查：

HEALTHCHECK CMD [ "curl", "-f", "http://localhost:8080/health" ]

即 Docker 会周期性请求 llama-server 的 /health 端点来判断容器是否存活，这与 docs/docker.md 中 server 示例使用的 8080 端口一一对应。

此外值得注意的是，所有镜像的编译都开启了 -DGGML_BACKEND_DL=ON（如 .devops/cuda.Dockerfile 的 cmake 参数），从源码结构看这意味着 GPU 后端以动态库形式加载，light / server 镜像同样携带了 /app 下的 *.so 后端库。

三、日常使用：full / light / server 三类镜像的运行命令

以下命令完整继承自 docs/docker.md，执行前请把 /path/to/models 替换为你实际下载模型的目录。

1. full 镜像：一条命令完成转换 + 量化 + 推理

下载模型、转换为 ggml 并做 4-bit 量化最省事的方式，是使用 full 镜像的 --all-in-one 子命令：

docker run -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:full --all-in-one "/models/" 7B

从 tools.sh 的实现看，--all-in-one（-a）会遍历 $1/$2/ 目录下的 ggml-model-f16.bin* 文件，对每个尚未量化的权重调用 llama-quantize 生成对应的 q4_0 文件（若 q4_0 已存在则跳过），即参数格式为 --all-in-one "<模型根目录>/" <模型名>。

转换完成后即可直接运行：

docker run -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:full --run -m /models/7B/ggml-model-q4_0.gguf
docker run -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:full --run-legacy -m /models/32B/ggml-model-q8_0.gguf -no-cnv -p "Building a mobile app can be done in 15 steps:" -n 512

full 镜像的入口是 tools.sh，它按第一个参数分发到真实可执行文件，完整命令映射如下（源码 L10-L33）：

子命令	短选项	实际执行
--run	-r	./llama-cli
--run-legacy	-l	./llama-completion
--bench	-b	./llama-bench
--perplexity	-p	./llama-perplexity
--convert	-c	python3 ./convert_hf_to_gguf.py
--quantize	-q	./llama-quantize
--all-in-one	-a	依次执行转换与 q4_0 量化
--server	-s	./llama-server

传错第一个参数时脚本会打印上述帮助信息；这也解释了为什么 full 镜像可以"不指定 entrypoint 直接跑子命令"。

2. light 镜像：显式指定 entrypoint

light 镜像只有两个 CLI 可执行文件，运行时需要通过 --entrypoint 指定入口：

docker run -v /path/to/models:/models --entrypoint /app/llama-cli ghcr.io/ggml-org/llama.cpp:light -m /models/7B/ggml-model-q4_0.gguf
docker run -v /path/to/models:/models --entrypoint /app/llama-completion ghcr.io/ggml-org/llama.cpp:light -m /models/32B/ggml-model-q8_0.gguf -no-cnv -p "Building a mobile app can be done in 15 steps:" -n 512

文档特别提醒：上面示例中 --entrypoint /app/llama-cli 只是为了表述清晰，/app/llama-cli 本就是该镜像的默认入口（见 .devops/cpu.Dockerfile 的 ENTRYPOINT [ "/app/llama-cli" ]），可以安全省略。若要跑 llama-completion，则必须像第二条命令那样显式覆盖 entrypoint。

参数含义参考：-m 指定模型文件；-no-cnv 禁用 conversation 格式、走旧式 completion 接口；-p 指定提示词；-n 512 限制最多生成 512 个 token。

3. server 镜像：暴露 OpenAI 兼容服务

docker run -v /path/to/models:/models -p 8080:8080 ghcr.io/ggml-org/llama.cpp:server -m /models/7B/ggml-model-q4_0.gguf --port 8080 --host 0.0.0.0 -n 512

-p 8080:8080 把容器内 8080 端口映射到宿主机；--port 8080 --host 0.0.0.0 对应 llama-server 的监听端口与地址（其实 server 镜像已预置 LLAMA_ARG_HOST=0.0.0.0 环境变量，--host 亦可省略）。

四、Docker + CUDA：使用官方 CUDA 镜像与本地构建

使用前提

假设宿主机是 Linux 并已正确安装 NVIDIA 官方的 nvidia-container-toolkit（或使用提供 GPU 能力的云主机），容器内即可访问 cuBLAS——GPU 透传依赖该 toolkit 自动注入 --gpus 支持，无需手工挂载驱动。

本地构建 CUDA 镜像

如需自定义 CUDA 版本或 GPU 架构，用 .devops/cuda.Dockerfile 本地构建：

docker build -t local/llama.cpp:full-cuda --target full -f .devops/cuda.Dockerfile .
docker build -t local/llama.cpp:light-cuda --target light -f .devops/cuda.Dockerfile .
docker build -t local/llama.cpp:server-cuda --target server -f .devops/cuda.Dockerfile .

--target 参数选中 Dockerfile 末尾的三个目标之一，与官方 full-cuda / light-cuda / server-cuda 镜像内容等价。构建时可以按需传入不同的 ARGS，关键构建参数（见 .devops/cuda.Dockerfile）：

• CUDA_VERSION：默认 12.8.1，决定基础镜像 nvidia/cuda:${CUDA_VERSION}-devel-ubuntu${UBUNTU_VERSION}；文档提示该值需要大体与宿主机环境的 CUDA 匹配；
• UBUNTU_VERSION：默认 24.04；
• CUDA_DOCKER_ARCH：默认为 default（cmake 默认值，覆盖所有支持架构）；若指定了具体架构，构建阶段会转换为 -DCMAKE_CUDA_ARCHITECTURES=<值> 传给 CMake（L45-L47），用于裁剪/指定 GPU 架构以加快编译。

Dockerfile 的 cmake 参数（L48）为 -DGGML_CUDA=ON -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=ON -DLLAMA_BUILD_TESTS=OFF，即 CUDA 后端 + 动态加载 + 全 CPU 变体、不编译测试，编译产物为 Release。

构建完成后得到的三个本地镜像：

1. local/llama.cpp:full-cuda：包含 llama-cli、llama-completion 及模型转换/4-bit 量化工具；
2. local/llama.cpp:light-cuda：仅包含 llama-cli 与 llama-completion；
3. local/llama.cpp:server-cuda：仅包含 llama-server。

运行 CUDA 镜像

本地构建后的用法与非 CUDA 示例类似，但必须添加 --gpus 标志，同时建议配合 --n-gpu-layers 控制卸载到 GPU 的层数（该参数在 common/arg.cpp 中以 --n-gpu-layers / --gpu-layers / -ngl 三个别名注册）：

docker run --gpus all -v /path/to/models:/models local/llama.cpp:full-cuda --run -m /models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 512 --n-gpu-layers 1
docker run --gpus all -v /path/to/models:/models local/llama.cpp:light-cuda -m /models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 512 --n-gpu-layers 1
docker run --gpus all -v /path/to/models:/models local/llama.cpp:server-cuda -m /models/7B/ggml-model-q4_0.gguf --port 8080 --host 0.0.0.0 -n 512 --n-gpu-layers 1

示例中 --n-gpu-layers 1 只是演示用法；实际部署时可逐步调大（甚至设为 99 表示尽量全部上 GPU），直至显存用尽。

五、Docker + MUSA：摩尔线程 GPU 支持

使用前提

假设宿主机是 Linux 并已正确安装 MUSA 的 mt-container-toolkit（见 ci/README-MUSA.md 可了解 MUSA 相关的 CI 说明），容器内即可访问 muBLAS。

本地构建 MUSA 镜像

使用 .devops/musa.Dockerfile：

docker build -t local/llama.cpp:full-musa --target full -f .devops/musa.Dockerfile .
docker build -t local/llama.cpp:light-musa --target light -f .devops/musa.Dockerfile .
docker build -t local/llama.cpp:server-musa --target server -f .devops/musa.Dockerfile .

可按需传入不同的 ARGS，关键默认值（见 .devops/musa.Dockerfile）：

• MUSA_VERSION：默认 rc4.3.0，对应基础镜像 mthreads/musa:${MUSA_VERSION}-devel-ubuntu22.04-amd64；
• MUSA_DOCKER_ARCH：默认 default，指定时会转为 -DMUSA_ARCHITECTURES=<值> 传给 CMake。

编译参数（L51）为 -DGGML_MUSA=ON -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=ON -DLLAMA_BUILD_TESTS=OFF。产出的三个镜像与非 MUSA 版本对应：full-musa（含转换/量化工具）、light-musa（仅两个 CLI）、server-musa（仅 llama-server）。

运行 MUSA 镜像

与 CUDA 不同，MUSA 需要把 mthreads 设为 Docker 的默认 runtime：在宿主机执行 (cd /usr/bin/musa && sudo ./docker setup $PWD)，再用 docker info | grep mthreads 验证生效。之后运行命令类似非 MUSA 示例，但不再需要 --gpus，只需配合 --n-gpu-layers：

docker run -v /path/to/models:/models local/llama.cpp:full-musa --run -m /models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 512 --n-gpu-layers 1
docker run -v /path/to/models:/models local/llama.cpp:light-musa -m /models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 512 --n-gpu-layers 1
docker run -v /path/to/models:/models local/llama.cpp:server-musa -m /models/7B/ggml-model-q4_0.gguf --port 8080 --host 0.0.0.0 -n 512 --n-gpu-layers 1

六、Docker + SYCL：Intel GPU 支持

本地构建 SYCL 镜像

使用 .devops/intel.Dockerfile：

docker build -t local/llama.cpp:full-intel --target full -f .devops/intel.Dockerfile .
docker build -t local/llama.cpp:light-intel --target light -f .devops/intel.Dockerfile .
docker build -t local/llama.cpp:server-intel --target server -f .devops/intel.Dockerfile .

按宿主机 SYCL 环境与 GPU 架构，你可能需要传入不同的 ARGS，可用参数及默认值请参见 .devops/intel.Dockerfile 源码，其中几个关键的构建参数包括：

• ONEAPI_VERSION（默认 2025.3.3-0-devel-ubuntu24.04）：决定 OneAPI 基础镜像；
• GGML_SYCL_F16（默认 ON）：开启后追加 -DGGML_SYCL_F16=ON 并设置 SYCL 编译选项 -cl-fp32-correctly-rounded-divide-sqrt；
• 构建阶段还会额外安装 Level Zero（level-zero / level-zero-devel）以及特定版本的 IGC、compute-runtime、libigdgmm 驱动组件——Dockerfile 注释说明 26.x 版本的多 GPU 场景存在已知问题，因此固定了驱动版本组合。

编译参数（L47）为 -DGGML_SYCL=ON -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=ON -DLLAMA_BUILD_TESTS=OFF，即使用 Intel DPC++ 编译器（icx/icpx）编译 SYCL 后端。产出的 full-intel / light-intel / server-intel 三个镜像与非 SYCL 版本功能对应；其中 full-intel 会把 Python 依赖装进 /opt/venv 虚拟环境并加入 PATH（与 CPU/CUDA 版直接 pip 到系统环境的做法不同）。

运行 SYCL 镜像

本地构建后的用法与非 SYCL 示例类似，但需要添加 --device 标志把 GPU 设备节点透传进容器。先用 ls -la /dev/dri 找到所有 DRI 设备，再选择要使用的卡（下例为 /dev/dri/card0）：

# First, find all the DRI cards
ls -la /dev/dri
# Then, pick the card that you want to use (here for e.g. /dev/dri/card0).
docker run --device /dev/dri/renderD128:/dev/dri/renderD128 --device /dev/dri/card0:/dev/dri/card0 -v /path/to/models:/models local/llama.cpp:full-intel -m /models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 512 --n-gpu-layers 99
docker run --device /dev/dri/renderD128:/dev/dri/renderD128 --device /dev/dri/card0:/dev/dri/card0 -v /path/to/models:/models local/llama.cpp:light-intel -m /models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 512 --n-gpu-layers 99
docker run --device /dev/dri/renderD128:/dev/dri/renderD128 --device /dev/dri/card0:/dev/dri/card0 -v /path/to/models:/models local/llama.cpp:server-intel -m /models/7B/ggml-model-q4_0.gguf --port 8080 --host 0.0.0.0 -n 512 --n-gpu-layers 99

SYCL 场景下文档直接示范了 --n-gpu-layers 99（"尽量全部上 GPU"）。

文档附带的两条注意事项：

• Docker 在原生 Linux 上已验证可用，WSL 支持尚未验证；
• 可能需要在宿主机上安装 Intel GPU 驱动，详见 docs/backend/SYCL.md 的 Linux 配置章节。

七、镜像构建链路小结

从 .devops/cpu.Dockerfile、.devops/cuda.Dockerfile 等文件的多阶段结构可以归纳出官方镜像的统一构建链路：

1. web 阶段：用 Node 24 镜像构建 tools/ui/ 的前端产物，供 llama-server 提供 Web 界面；
2. build 阶段：在对应后端的 devel 基础镜像（Ubuntu 24.04 / nvidia/cuda / mthreads/musa / intel/deep-learning-essentials）中用 CMake 编译全部二进制，开启 GGML_BACKEND_DL（后端动态加载）与 GGML_CPU_ALL_VARIANTS（全 CPU 指令集变体），关闭测试构建；
3. base 阶段：从对应的 runtime 基础镜像出发，安装最小运行依赖（libgomp1 curl ffmpeg），拷入 /app 下的共享库；
4. full / light / server 阶段：按内容多少裁剪文件并分别设置 ENTRYPOINT——full 走 tools.sh 子命令分发，light 走 /app/llama-cli，server 走 /app/llama-server 并带 /health 健康检查。

这套"同一 build 阶段、多目标裁剪"的方式保证了 CPU 与 GPU 镜像、以及三个功能档位之间的行为一致性，也正是 docs/docker.md 中强调的"GPU 镜像与 .devops/ 中 Dockerfile 构建产物无差异"的来源。

八、参考资料（仓库内路径）

• 本文主体文档：docs/docker.md
• Docker 构建与 CI：.github/workflows/docker.yml、.devops/cpu.Dockerfile、.devops/cuda.Dockerfile、.devops/musa.Dockerfile、.devops/intel.Dockerfile、.devops/tools.sh
• 后端文档：docs/backend/SYCL.md、docs/backend/CUDA-FEDORA.md、ci/README-MUSA.md
• 参数别名定义：common/arg.cpp（-ngl / --n-gpu-layers 等）