Llama.cpp 服务器安装指南（使用 Docker，GPU 专用）

前置条件

在开始之前，请确保你的系统满足以下要求：

• 操作系统：Ubuntu 20.04/22.04（或支持 Docker 的 Linux 系统）。
• 硬件：NVIDIA GPU（例如 RTX 4090）。
• 内存：16GB+ 系统内存，GPU 需 12GB+ 显存（RTX 4090 有 24GB）。
• 存储：15GB+ 可用空间（用于源码、镜像和模型文件）。
• 网络：需要互联网连接以下载源码和依赖。
• 软件：
  • 已安装并运行 Docker。
  • 已安装 NVIDIA Container Toolkit 以支持 GPU。

第一步：安装 Docker 和 NVIDIA Container Toolkit

安装 Docker

1. 更新软件包列表：

   sudo apt update
   

2. 安装 Docker：

   sudo apt install -y docker.io
   

3. 启动并启用 Docker：

   sudo systemctl start docker
   sudo systemctl enable docker
   

4. 将用户添加到 Docker 组（避免每次使用 sudo）：

   sudo usermod -aG docker $USER
   newgrp docker
   

5. 验证安装：

   docker --version
   

安装 NVIDIA Container Toolkit

1. 添加 NVIDIA 仓库：

   curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
   curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
       sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
       sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
   sudo apt update
   

2. 安装工具包：

   sudo apt install -y nvidia-container-toolkit
   

3. 配置 Docker：

   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker
   

4. 验证 GPU 支持：

   docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
   

   预期输出：显示你的 GPU 信息（例如 RTX 4090）。

第二步：下载并修改 llama.cpp 源码

1. 克隆仓库：

   git clone https://github.com/ggml-org/llama.cpp.git
   cd llama.cpp
   

2. 编辑 cuda.Dockerfile：

   • 打开 .devops/cuda.Dockerfile：

     nano .devops/cuda.Dockerfile
     

   • 找到以下行：

     ARG CUDA_VERSION=12.4.0
     

   • 修改为：

     ARG CUDA_VERSION=12.2.0
     

   • 保存并退出（Ctrl+O，回车，Ctrl+X）。

• 为什么要修改？
  你的 RTX 4090 驱动 535.183.01 支持 CUDA 12.2，默认的 12.4 可能不兼容。

第三步：构建自定义 Docker 镜像

1. 构建服务器镜像：

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

   • -t：命名镜像为 local/llama.cpp:server-cuda。
   • --target server：仅构建服务器版本。
   • -f：指定修改后的 cuda.Dockerfile。
   • .：使用当前目录作为构建上下文。
   • 构建时间：10-20 分钟，取决于网络和机器性能。

2. 验证：

   docker images
   

   预期输出：

   REPOSITORY                TAG            IMAGE ID       CREATED       SIZE
   local/llama.cpp          server-cuda    xxxxxxxx       yyyy-mm-dd    zzzMB
   

第四步：准备模型目录

1. 创建目录：

   mkdir -p ~/llama-models
   

2. 下载 GGUF 模型：

• 可参考： https://blog.csdn.net/canduecho/article/details/145898586?sharetype=blogdetail&sharerId=145898586&sharerefer=PC&sharesource=canduecho&spm=1011.2480.3001.8118

第五步：运行服务器（GPU 专用）

1. 运行容器：

   docker run --gpus all \
       -v ~/llama-models:/models \
       -p 9000:9000 \
       local/llama.cpp:server-cuda \
       -m /models/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf \
       -t 16 \
       --host 0.0.0.0 \
       --port 9000 \
       -ngl 99 \
       -n 64 \
       -c 4096
   

   • --gpus all：启用 GPU 支持。
   • -v：挂载模型目录。
   • -p：映射端口 9000。
   • -t 16：线程数（主要影响提示处理，GPU 主导时作用小）。
   • -ngl 99：将所有层（最多 33 层，8B 模型）卸载到 GPU。
   • -n 64：限制输出为 64 个 token。
   • -c 4096：上下文大小。

2. 后台运行（可选）：

   docker run -d --gpus all -v ~/llama-models:/models -p 9000:9000 local/llama.cpp:server-cuda -m /models/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf -t 16 --host 0.0.0.0 --port 9000 -ngl 99 -n 64 -c 4096
   

3. 检查日志：

   docker ps  # 查看容器 ID
   docker logs <container_id>
   

   查找：offloaded 33/33 layers to GPU。

4. 完整docker compose 文件：

version: '3.8'
services:
  llama-server:
    image: local/llama.cpp:server-cuda 
    container_name: local-llama-server
    volumes:
      - /home/docpal/AI/llama_cpp/models:/models
    ports:
      - "8000:8000"
    command: >
      -m /models/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf
      --port 8000
      --host 0.0.0.0
      -n 3000   
      -c 8192
      -np 5 
      -t 16   
      -ngl 99 
      --defrag-thold 0.1
    environment:
      - TZ=Asia/Shanghai
      - NVIDIA_VISIBLE_DEVICES=all  # 暴露所有 GPU
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - test-network
networks:
  test-network:
    name: test-network-1

第六步：测试服务器

curl -X POST http://localhost:9000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "DeepSeek-R1-Distill-Llama-8B-Q4_K_M",
        "messages": [{"role": "user", "content": "你好，怎么样？"}],
        "max_tokens": 50,
        "temperature": 0.1
    }'

• 预期：快速返回 JSON 响应（1-2 秒，GPU 加速）。

第七步：验证 GPU 使用

1. 监控 GPU：

   nvidia-smi
   

   • 请求时，GPU 使用率和显存应增加。

2. 检查日志：

   • 加 -v 查看详细输出：

     docker run ... -v ...
     

   • 确认 eval time 是否很快（例如 50-100 token/s）。

故障排除

• 错误：“ggml_cuda_init: failed”：
  • CUDA 12.2 与驱动不匹配，运行 nvidia-smi 确认支持 12.2。
• GPU 未使用：
  • 确保 --gpus all 和 -ngl 99 已添加。
  • 重建镜像：docker build ...。
• 性能慢：
  • 检查 nvidia-smi，若 GPU 未用，可能是镜像编译问题。
• 容器退出：
  • 查看日志：docker logs <container_id>。

示例工作流程

1. 安装 Docker 和 NVIDIA Toolkit：

   sudo apt update && sudo apt install -y docker.io nvidia-container-toolkit
   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker
   

2. 下载并修改源码：

   git clone https://github.com/ggml-org/llama.cpp.git
   cd llama.cpp
   sed -i 's/ARG CUDA_VERSION=12.4.0/ARG CUDA_VERSION=12.2.0/' .devops/cuda.Dockerfile
   

3. 构建镜像：

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

4. 运行服务器：

   docker run -d --gpus all -v ~/llama-models:/models -p 9000:9000 local/llama.cpp:server-cuda -m /models/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf -t 16 --host 0.0.0.0 --port 9000 -ngl 99
   

5. 测试：

   curl -X POST http://localhost:9000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "DeepSeek-R1-Distill-Llama-8B-Q4_K_M", "messages": [{"role": "user", "content": "你好！"}]}'