llama.cpp Docker 部署指南：一条命令拉起 LLM 推理 API，附 GPU 与生产编排方案

llama.cpp Docker 部署指南：一条命令拉起 LLM 推理 API，附 GPU 与生产编排方案

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

本文讲 llama.cpp Docker 部署：llama.cpp 是纯 C/C++ 推理引擎，不依赖 Python 环境，一条docker run命令就能起一个随时可调用的 HTTP 推理 API。全文覆盖镜像选型、CPU 最小化部署、接口调用、GPU 加速与生产编排。

选型速览：先判断 llama.cpp 该拉哪个 Docker 镜像

选镜像只取决于两件事：机器上有没有 GPU、是什么 GPU，以及这个服务是临时跑还是长期跑。把决策表放在前面，对号确认后再动手：

server这个 tag 的镜像里只有llama-server可执行文件，体积最小，纯推理场景完全够用；fulltag 额外带模型转换与量化工具链，临时跑服务用不上，不必多拉。

CPU 最小化部署：llama.cpp 一条 docker run 命令跑通推理服务

整个过程不碰源码：不用 clone 仓库，也没有本地编译环节，宿主机 Docker 能跑就行。下面这条命令同时完成四件事——拉取官方server镜像、映射端口、挂载模型目录、启动 HTTP 服务：

docker run -d --name llama-server \ -p 8080:8080 \ -v /data/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080

每个参数都有明确用意：-p 8080:8080把宿主机端口映射到容器内服务端口；-v /data/models:/models把本地模型目录挂进容器，模型文件不烧进镜像，以后换模型只需替换挂载目录里的文件；-m指定 GGUF 模型在容器内的路径；--host 0.0.0.0让服务监听容器的所有网卡，漏掉这个参数，外部机器就访问不到。

服务起来后做两个验证。第一，健康检查：

curl http://localhost:8080/health

返回{"status":"ok"}即就绪。第二，浏览器直接打开http://localhost:8080/，llama-server 自带一个 Web 聊天页，打开就能和模型对话，无需自己写前端。

⚠️ 动手前确认两点：要跑的模型文件只能是 GGUF 格式，llama.cpp 统一用它作为模型载体；内存吃紧时优先挑低精度量化版本（如 Q4_K_M）。

性能预期可作为参照：7B 参数 Q4_K_M 量化在普通桌面 CPU 上通常能跑到几到几十个 token/s，首 token 延迟在 1 秒以内算正常。明显慢于这个水平时，先用top确认线程是否真正跑满，再回头检查两个可调参数：-c是上下文长度上限，直接决定内存占用，从 4096 起步、内存吃紧就往下调；-t是 CPU 线程数，填物理核心数即可。

llama-server 怎么调接口：/completion 与 /v1/chat/completions 两种调法

服务暴露一组 HTTP 接口，日常用得多的是两个。

原生补全接口/completion——prompt 由自己拼好，模型只负责续写：

curl http://localhost:8080/completion \ -H "Content-Type: application/json" \ -d '{"prompt": "介绍一下 llama.cpp", "n_predict": 64, "stream": false}'

OpenAI 兼容接口/v1/chat/completions——手上已有 OpenAI SDK 代码的话，只需把 base URL 指过来，其余逻辑一行不动：

curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"messages": [{"role": "user", "content": "你好"}], "max_tokens": 64}'

容器里做的事情本质上是模型逐 token 做矩阵乘法，下面的采样参数只决定每次乘法完成后，如何从输出概率分布里挑出下一个 token：

llama.cpp 怎么开 GPU 加速，服务如何长期稳定运行

NVIDIA 显卡：换 server-cuda 镜像开 CUDA 推理

相比 CPU 版只动两处：镜像 tag 换成server-cuda，启动参数加--gpus all（前提是宿主机已安装 nvidia-container-toolkit），再带上--n-gpu-layers 99，把尽可能多的层卸载到显存：

docker run -d --name llama-server \ --gpus all \ -p 8080:8080 \ -v /data/models:/models \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/7b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 \ --n-gpu-layers 99

如果显存装不下、启动即 OOM，就把 99 逐级往下调，调到能顺利加载为止；7B Q4_K_M 的权重基本能完整放进 8GB 显存。判断是否生效看两处：启动日志里出现 CUDA 设备初始化，单 token 速度比 CPU 快出数倍。

AMD 显卡：server-rocm 镜像（仅 amd64）

镜像 tag 换成server-rocm，--gpus all与--n-gpu-layers的用法和 NVIDIA 一致，需要留意的是 ROCm 镜像只提供 amd64 平台。vulkan、intel 等其他后端对应的镜像 tag，可以在 Docker 官方文档 里查到。

长期运行：Compose 编排 + 健康检查 + 日志轮转

服务要长期在线，就不该再依赖一次性命令。把配置固化进 Compose 文件，重启策略、日志上限、健康检查一并落定：

services: llama-server: image: ghcr.io/ggml-org/llama.cpp:server restart: unless-stopped ports: ["8080:8080"] volumes: ["/data/models:/models"] logging: driver: json-file options: {max-size: "10m", max-file: "3"} command: -m /models/7b-instruct-q4_k_m.gguf --host 0.0.0.0 --port 8080 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/health"] interval: 30s retries: 3

docker compose up -d启动服务，docker compose logs -f实时跟踪日志。restart: unless-stopped让宿主机重启之后服务自动恢复；日志驱动限制单文件 10MB、最多保留 3 份，避免容器日志把磁盘写满。镜像内部其实已内置健康检查，这里显式写一遍，是为了升级镜像版本时行为不依赖默认值。

跑不通时自查：llama.cpp Docker 部署的 6 个高频故障

服务起不来或行为不对时，按下面这张表从高频到低频排查：

部署稳定之后：监控接入与横向扩容

llama-server 自带/metrics端点，Prometheus 可以直接抓取做监控；流量上来需要横向扩容时，用 nginx 给多个实例做负载均衡，或者把上面的 Compose 配置平移成 K8s Deployment 即可。

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp