llama.cpp Docker 部署指南涵盖基础 CPU 部署、NVIDIA CUDA GPU 加速及 Docker Compose 生产环境配置。内容包含镜像选择、模型准备流程、环境变量设置、多模型支持、性能优化参数及 OpenAI 兼容 API 调用示例。提供健康检查、Prometheus 监控配置及安全最佳实践，解决模型加载失败、GPU 识别等常见问题，实现稳定可移植的 AI 推理服务搭建。
llama.cpp 是 Facebook LLaMA 模型的 C/C++移植版本，提供了高效的本地推理能力。通过 Docker 容器化部署，可以快速搭建稳定、可移植的 AI 推理服务环境。本文将详细介绍如何使用 Docker 部署 llama.cpp 推理服务，涵盖基础部署、GPU 加速、生产环境配置等场景。
mkdir -p ~/llama-docker
cd ~/llama-docker
mkdir models config logs
llama.cpp 提供多种 Docker 镜像，根据需求选择：
| 镜像类型 | 描述 | 适用场景 |
|---|---|---|
ghcr.io/ggml-org/llama.cpp:light | 仅包含主可执行文件 | 最小化部署 |
ghcr.io/ggml-org/llama.cpp:full | 包含完整工具链 | 模型转换 + 推理 |
ghcr.io/ggml-org/llama.cpp:server | 仅包含服务器 | HTTP API 服务 |
*-cuda 后缀 | CUDA GPU 支持 | NVIDIA GPU 环境 |
*-rocm 后缀 | ROCm GPU 支持 | AMD GPU 环境 |
# 拉取最新 server 镜像
docker pull ghcr.io/ggml-org/llama.cpp:server
# 运行基础服务
docker run -d \
--name llama-server \
-p 8080:8080 \
-v $(pwd)/models:/models \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/llama-2-7b.Q4_K_M.gguf \
--host 0.0.0.0 \
--port 8080 \
-c 4096 \
-t 8
模型需转换为 GGUF 格式并放置于挂载卷中。
# 安装 NVIDIA 容器工具包
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
# 运行 CUDA 版本服务
docker run -d \
--name llama-server-cuda \
--gpus all \
-p 8080:8080 \
-v $(pwd)/models:/models \
ghcr.io/ggml-org/llama.cpp:server-cuda \
-m /models/llama-2-7b.Q4_K_M.gguf \
--host 0.0.0.0 \
--port 8080 \
-c 4096 \
--n-gpu-layers 35
| 模型大小 | 建议 GPU 层数 | VRAM 需求 |
|---|---|---|
| 7B 模型 | 30-35 层 | 8-10GB |
| 13B 模型 | 40-45 层 | 16-20GB |
| 70B 模型 | 60-80 层 | 40-80GB |
version: '3.8'
services:
llama-server:
image: ghcr.io/ggml-org/llama.cpp:server-cuda
container_name: llama-inference
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./models:/models
- ./logs:/app/logs
environment:
LLAMA_ARG_MODEL: /models/llama-2-7b.Q4_K_M.gguf
LLAMA_ARG_HOST: 0.0.0.0
LLAMA_ARG_PORT: 8080
LLAMA_ARG_CTX_SIZE: 4096
LLAMA_ARG_N_GPU_LAYERS: 35
LLAMA_ARG_THREADS: 8
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
| 环境变量 | 描述 | 默认值 |
|---|---|---|
LLAMA_ARG_MODEL | 模型文件路径 | - |
LLAMA_ARG_HOST | 监听主机 | 127.0.0.1 |
LLAMA_ARG_PORT | 监听端口 | 8080 |
LLAMA_ARG_CTX_SIZE | 上下文大小 | 4096 |
LLAMA_ARG_N_GPU_LAYERS | GPU 层数 | 0 |
LLAMA_ARG_THREADS | CPU 线程数 | -1（自动） |
# 启动多个模型实例
docker run -d \
--name llama-7b \
-p 8081:8080 \
-v $(pwd)/models:/models \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/llama-2-7b.Q4_K_M.gguf \
--host 0.0.0.0 \
--port 8080
docker run -d \
--name llama-13b \
-p 8082:8080 \
-v $(pwd)/models:/models \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/llama-2-13b.Q4_K_M.gguf \
--host 0.0.0.0 \
--port 8080
docker run -d \
--name llama-optimized \
-p 8080:8080 \
-v $(pwd)/models:/models \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/llama-2-7b.Q4_K_M.gguf \
--host 0.0.0.0 \
--port 8080 \
-c 8192 \
-tb 16 \
-b 512 \
--flash-attn \
--cont-batching
curl -X POST http://localhost:8080/completion \
-H "Content-Type: application/json" \
-d '{ "prompt": "人工智能的未来发展：", "temperature": 0.7, "top_p": 0.9, "n_predict": 100 }'
curl -X POST http://localhost:8080/completion \
-H "Content-Type: application/json" \
-d '{ "prompt": "解释机器学习：", "stream": true, "n_predict": 50 }'
curl -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{ "model": "llama-2-7b", "messages": [{"role": "user", "content": "你好，请介绍你自己"}], "max_tokens": 100 }'
# 检查服务状态
curl http://localhost:8080/health
# 查看容器日志
docker logs llama-server
# 监控资源使用
docker stats llama-server
创建 Prometheus 配置文件 config/prometheus.yml：
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'llama-server'
static_configs:
- targets: ['llama-server:8080']
metrics_path: '/metrics'
| 问题 | 解决方案 |
|---|---|
| 模型加载失败 | 检查模型路径和文件权限 |
| GPU 无法识别 | 验证 NVIDIA 驱动和容器工具包 |
| 内存不足 | 减少上下文大小或使用量化模型 |
| 端口冲突 | 更改监听端口或停止冲突服务 |
# 查看详细日志
docker logs --tail 100 -f llama-server
# 调试模式启动
docker run -it --rm \
-v $(pwd)/models:/models \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/your-model.gguf \
--verbose
networks:
llama-net:
internal: true
driver: bridge
services:
llama-server:
networks:
- llama-net
nginx:
networks:
- llama-net
- public
docker run -d \
--name llama-secure \
-p 8080:8080 \
-v $(pwd)/models:/models \
-e LLAMA_API_KEY=your-secret-key \
ghcr.io/ggml-org/llama.cpp:server \
-m /models/model.gguf \
--api-key your-secret-key
version: '3.8'
services:
llama-1:
image: ghcr.io/ggml-org/llama.cpp:server
environment:
- LLAMA_ARG_MODEL=/models/llama-7b.gguf
networks:
- llama-net
llama-2:
image: ghcr.io/ggml-org/llama.cpp:server
environment:
- LLAMA_ARG_MODEL=/models/llama-7b.gguf
networks:
- llama-net
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
networks:
- llama-net
# 使用 Docker Swarm 或 Kubernetes 实现自动扩缩容
docker service create \
--name llama-service \
--replicas 3 \
--mount type=bind,source=$(pwd)/models,destination=/models \
-p 8080:8080 \
ghcr.io/ggml-org/llama.cpp:server
通过 Docker 部署 llama.cpp 推理服务，可获得以下优势：
该部署方案涵盖了从基础单实例到生产级集群的各种场景，可根据实际需求选择合适的配置方案。随着 llama.cpp 项目的持续发展，Docker 部署将成为 AI 推理服务标准化的重要方式。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online