llama.cpp Docker 部署：容器化推理服务搭建
概述
llama.cpp 是 Meta LLaMA 模型的 C/C++ 移植版本，提供了高效的本地推理能力。通过 Docker 容器化部署，可以快速搭建稳定、可移植的 AI 推理服务环境。本文将详细介绍如何使用 Docker 部署 llama.cpp 推理服务，涵盖基础部署、GPU 加速、生产环境配置等场景。
环境准备
系统要求
- Docker Engine 20.10+
- NVIDIA Container Toolkit（如需 GPU 支持）
- 至少 8GB 可用内存
- 20GB+ 磁盘空间（用于模型存储）
目录结构规划
mkdir -p ~/llama-docker
cd ~/llama-docker
mkdir models config logs
Docker 镜像选择
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 环境 |
基础部署
1. CPU 版本部署
# 拉取最新 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
2. 模型准备流程
模型加载与初始化流程涉及下载量化模型文件并挂载至容器卷。
GPU 加速部署
NVIDIA CUDA 环境
# 安装 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 层数配置建议
| 模型大小 | 建议 GPU 层数 | VRAM 需求 |
|---|---|---|
| 7B 模型 | 30-35 层 | 8-10GB |
| 13B 模型 | 40-45 层 | 16-20GB |
| 70B 模型 | 60-80 层 | 40-80GB |
Docker Compose 生产部署
完整 docker-compose.yml 配置
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
# 可选：监控服务
monitoring:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- ./config/prometheus.yml:/etc/prometheus/prometheus.yml
depends_on:
- llama-server
环境变量配置表
| 环境变量 | 描述 | 默认值 |
|---|---|---|
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（自动） |
高级配置
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
2. 性能优化参数
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
API 使用示例
基础文本补全
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 }'
OpenAI 兼容 API
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
安全最佳实践
1. 网络隔离
networks:
llama-net:
internal: true
driver: bridge
services:
llama-server:
networks:
- llama-net
nginx:
networks:
- llama-net
- public
2. API 密钥保护
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
扩展部署方案
1. 负载均衡配置
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
2. 自动扩缩容
# 使用 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 推理服务标准化的重要方式。