📚 课程目录第4章 Docker容器化部署llama.cpp

4. Docker容器化部署llama.cpp

任务目标

构建一个包含 llama.cpp 可执行文件的 Docker 镜像，通过容器运行 llama.cpp 的 main 命令完成一次本地大模型推理，验证容器化部署链路可用。

环境与依赖

宿主机需安装 Docker（20.10+），支持 Linux 容器。
模型文件：准备一个 GGUF 格式的量化模型（如 qwen2.5-0.5b-instruct-q4_k_m.gguf），放置于宿主机目录 ./models/ 下。
构建阶段需要访问 GitHub 与 CMake 依赖，确保网络可用。

实现方案

采用多阶段构建：第一阶段在 Ubuntu 基础镜像中编译 llama.cpp 源码生成可执行文件；第二阶段使用精简的 Ubuntu 镜像，仅拷贝编译产物与运行库，降低最终镜像体积。容器启动时挂载宿主机模型目录，通过 main 命令执行推理。

关键完整代码

# Dockerfile
# 构建阶段
FROM ubuntu:22.04 AS builder

RUN apt-get update && apt-get install -y \
    git cmake build-essential \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
RUN git clone https://github.com/ggerganov/llama.cpp.git
WORKDIR /app/llama.cpp
RUN cmake -B build -DLLAMA_CUBLAS=OFF \
    && cmake --build build --config Release -j $(nproc)

# 运行阶段
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    libgomp1 \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/llama.cpp/build/bin/main /usr/local/bin/main
COPY --from=builder /app/llama.cpp/build/bin/llama-cli /usr/local/bin/llama-cli 2>/dev/null || true

WORKDIR /workspace
ENTRYPOINT ["main"]

构建与运行

# 1. 构建镜像
docker build -t llama-cpp:latest .

# 2. 运行容器执行推理（以 qwen2.5-0.5b 为例）
docker run --rm -v $(pwd)/models:/models llama-cpp:latest \
    -m /models/qwen2.5-0.5b-instruct-q4_k_m.gguf \
    -p "请用一句话介绍你自己" \
    -n 128 \
    --temp 0.7

验证方法与通过条件

构建验证：执行 docker build 无报错，最终输出 Successfully tagged llama-cpp:latest。
运行验证：容器启动后，终端输出模型加载日志（如 llama_model_load 相关行），随后打印与提示词对应的中文回答文本，退出码为 0。
判定标准：容器能正常加载挂载的 GGUF 模型并生成连贯文本，即视为容器化部署成功。若模型路径错误或缺少运行库，会分别报 cannot open file 或 error while loading shared libraries 错误，需按提示排查。

常见问题

CUDA 不可用：本案例默认 CPU 推理（LLAMA_CUBLAS=OFF）。如需 GPU 加速，需在构建阶段安装 CUDA 工具链并改为 -DLLAMA_CUBLAS=ON，同时运行阶段使用 nvidia/cuda 基础镜像。
镜像体积过大：多阶段构建已剥离编译工具链。若仍需要精简，可改用 alpine 基础镜像，但需额外安装 gcompat 等兼容库。
模型挂载权限：确保宿主机 ./models 目录对容器用户可读，必要时在 docker run 中加 --user $(id -u):$(id -g)。