llama.cpp Docker 部署：容器化推理服务搭建

GPU 层数配置建议

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

环境变量配置表

高级配置

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'

故障排除

常见问题解决

日志分析

# 查看详细日志
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 推理服务，可获得以下优势：

1. 环境一致性：消除环境配置差异
2. 快速部署：几分钟内完成服务搭建
3. 资源隔离：避免与其他服务冲突
4. 易于扩展：支持水平扩展和负载均衡
5. 维护简便：统一的日志和监控方案

该部署方案涵盖了从基础单实例到生产级集群的各种场景，可根据实际需求选择合适的配置方案。随着 llama.cpp 项目的持续发展，Docker 部署将成为 AI 推理服务标准化的重要方式。