企业官网建设流程全解析

用 Docker 在 10 分钟内部署 llama.cpp 容器化推理服务的完整指南

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

一台装好 Docker 的 Linux 机器，加上一个现成的 GGUF 模型文件，本文带你用 2 条命令先跑通 llama.cpp 的 CPU 推理服务，再切换 CUDA 版本上生产配置，全程约 10 分钟。

先判断：它是不是为你准备的

先说适用面：这套方案面向"手上有机器、想尽快调用大模型 API"的读者，不面向需要训练或微调的人。

三条前置条件，缺一条就先补齐：

1. 一台 Linux 机器，Docker 已安装且在运行（仓库 docs/docker.md 把 Docker 列为唯一硬性前置）；
2. 一个 GGUF 格式的模型文件放在宿主机某个目录里，比如./models/；
3. 宿主机 8080 端口空闲，或者你愿意改端口映射。

如果你要跑的是模型权重转换（HuggingFace 格式转 GGUF），那是full镜像的活，本文的 server 路线帮不上你，可以划走。

路线选型：你的情况走哪条路

镜像按"功能 × 加速后端"打 tag，仓库 docs/docker.md 列了完整清单，常用的 4 条路线对号入座：

拿不准就先走server（纯 CPU）路线，链路通了再换后缀版本，其余参数原样保留。

主线走查：先最小可用，再补完整配置

第 1 步：最小可用。把 GGUF 文件放进./models/，直接抄这条命令：

mkdir -p ./models docker run -d --name llama-min \ -p 8080:8080 \ -v ./models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/change-me-8b-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 -c 4096

预期看到什么：命令无输出直接返回，随后docker ps里llama-min状态为 Up，没退出、没重启。

验证只有一条命令：

curl -s http://localhost:8080/health

预期看到什么：返回包含ok的 JSON，即服务已就绪 ✅ 注意/health是公开端点，不走密钥校验。

第 2 步：完整形态。链路通了之后，把 GPU 加速、密钥鉴权、Prometheus 指标、健康检查一次补齐。把下面这份 compose 文件存为docker-compose.yaml，模型文件名和密钥替换成你的值，然后执行docker compose up -d：

services: llama-inference: image: ghcr.io/ggml-org/llama.cpp:server-cuda container_name: llama-inference restart: unless-stopped ports: - "8080:8080" volumes: - ./models:/models environment: - LLAMA_API_KEY=change-me command: - -m - /models/change-me-8b-q4_k_m.gguf - --host - 0.0.0.0 - --port - 8080 - -c - 4096 - --n-gpu-layers - "99" - --flash-attn - on - --metrics 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

预期看到什么：docker compose up -d完成后，docker ps显示llama-inference为 Up 且健康检查状态逐步变为 healthy；日志里能看到 GPU 层被 offload 的条目，而不是纯 CPU 推理。

参数解读：每个开关动了什么

只盯最影响结果的 5 个开关，其余保持默认：

改参数时的正确姿势：一次只动一个，对比生成速度再决定去留。

验收清单：怎样算真的跑通了

逐条执行下面 5 个动作，全部通过才算成功：

1. docker ps显示目标容器 Up 且未反复重启；
2. curl -s http://localhost:8080/health返回包含ok的 JSON；
3. 发一条真实请求，确认模型真的在生成，而不只是服务活着：

curl http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer change-me" \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"你好"}],"max_tokens":64}'

预期看到什么：返回带choices字段的 JSON，生成内容在choices[0].message.content里；这条走的是 OpenAI 兼容入口，现有 OpenAI SDK 客户端改base_url即可切换。

4. 启动时带过--metrics的话，curl -s http://localhost:8080/metrics能返回 Prometheus 格式指标；
5. 启用LLAMA_API_KEY后，不带Authorization头的请求返回 401。

绕行手册：卡住时先做这几件事

信息不够时最快的排查入口是这条：

docker logs --tail 100 llama-inference

预期看到什么：模型加载进度、启动参数回显和错误堆栈的最后 100 行，报错关键字基本都在这。⚠️ 日志里若只有启动参数没有加载完成行，说明卡死或崩溃发生在加载阶段，优先怀疑-m路径与文件大小。

边界与出口：它到哪儿为止

先把话说死：llama-server 本质是单进程服务，单机私有部署 1B~几十 B 量级的量化模型没问题，但别指望它扛公开高并发；横向扩容的正路是跑多个实例、前面挂一层负载均衡，而不是往单容器里塞更多请求。需要频繁做 HF 权重转 GGUF 时，把镜像 tag 换成full-cuda即可同时拿到推理和转换工具链；多模态、函数调用、投机解码等高级能力同样由 server 镜像提供，只是本文不展开。

两处仓库内文档，比翻 README 首页更快：

• 镜像 tag 全清单与各后端构建方式：docs/docker.md
• 全部 HTTP 端点与参数表：tools/server/README.md

下一步动作：跑通第 1 步的最小可用后，先把你自己的 OpenAI SDK 客户端base_url指向http://<你的机器IP>:8080发一条真实业务请求——客户端能拿到正常回复，这套部署才算真正交付。

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp