llama.cpp Docker 实战：把 8B 模型变成 OpenAI 兼容推理接口

llama.cpp Docker 实战把 8B 模型变成 OpenAI 兼容推理接口【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cppllama.cpp 部署只需一个官方 server 镜像加一份 GGUF 文件容器内锁死运行环境llama-server 常驻监听 8080 端口对任意硬件纯 CPU / NVIDIA / AMD都走同一套 llama.cpp Docker 启动流程。适合第一次接触 GGUF 本地推理、需要 OpenAI 兼容接口的开发者与运维。无显卡 / NVIDIA / AMD三条路线各自一条启动命令三条路线的区别只有镜像 tag 与宿主机前置条件命令骨架完全一致验证动作也共用同一个/health端点。使用场景镜像宿主机前置条件启动差异只有 CPUghcr.io/ggml-org/llama.cpp:server无无额外参数NVIDIA 显卡ghcr.io/ggml-org/llama.cpp:server-cudanvidia-container-toolkit装好后重启 Docker追加--gpus all --n-gpu-layers 99AMD 显卡ghcr.io/ggml-org/llama.cpp:server-rocmROCm 驱动与运行时追加--n-gpu-layers 99三条路线各贴一条可直接执行的命令。CPU 路线把宿主机模型目录挂进容器/models模型以 Q4_K_M 量化的 8B GGUF 为例容器后台常驻、端口 8080 对外。docker run -d --name llama-cpu \ -p 8080:8080 \ -v /path/to/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/llama-3.1-8b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 -c 4096验证等 20~60 秒模型加载时间执行curl -s http://localhost:8080/health返回ok即服务就绪。⚠️ 没有现成 GGUF 时用full镜像做模型转换或从模型仓库直接下载量化版不阻塞服务搭建。NVIDIA 路线与 CPU 版唯一差异是运行时 GPU 直通与层数卸载其余参数不动。docker run -d --name llama-cuda --gpus all \ -p 8080:8080 \ -v /path/to/models:/models \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/llama-3.1-8b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 -c 4096 \ --n-gpu-layers 99验证除/health返回ok外docker logs llama-cuda中应出现 CUDA backend 初始化行若看到CUDA not found说明宿主机 toolkit 没生效先别继续调参。AMD 路线镜像换成server-rocm前置条件换成 ROCm命令结构同上这里只列差异段。docker run -d --name llama-rocm \ -p 8080:8080 \ -v /path/to/models:/models \ ghcr.io/ggml-org/llama.cpp:server-rocm \ -m /models/llama-3.1-8b-instruct-q4_k_m.gguf \ --host 0.0.0.0 --port 8080 -c 4096 \ --n-gpu-layers 99验证docker logs llama-rocm确认 ROCm 设备被识别HCC_VERSION/ 设备名行/health返回ok后与 CPU/NVIDIA 路线共用后续全部流程。显存预算权重、KV 缓存、批缓冲各自占多少显存规划就是给三项占用做加法然后按结果反推--n-gpu-layers的取值。以 8B Q4_K_M 为例各项量级如下占用项8B / Q4_K_M 量级受哪个参数控制建议值模型权重约 5GB量化位宽换版本非运行时参数Q4_K_M 起步KV 缓存-c 4096时约 0.3GB随-c线性增长-c4096长文需求再翻倍提示词批缓冲约 0.2GB 起随批大小增大-b512计算与临时开销约 0.5~1GB--flash-attn on可压低注意力开销开合计约 6~8GB8GB 卡可整卡卸载--n-gpu-layers 9912GB 卡再给-c翻倍留空间。层数的取舍逻辑是先填 99 试跑显存不够就向 CPU 回退 10~20 层一次每降一档都重测一次生成速度记录你显存下的最优点。CPU 线程用-t设为物理核心数只影响留在 CPU 上的那部分层。⚠️ 触发 OOM 后的调整顺序固定先降-c再降层数最后才换更低位宽的量化版本不要反着来。上线前检查项Compose、/health、API 密钥、内网、指标交给运维之前需要落五件事这份 Compose 一次全做GPU 设备预留、模型目录挂载、/health健康检查、LLAMA_API_KEY鉴权、内网隔离外加 Prometheus 指标开关。写好保存为docker-compose.yamldocker 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_KEYchange-me-32chars - LLAMA_ARG_ENDPOINT_METRICS1 command: - -m - /models/llama-3.1-8b-instruct-q4_k_m.gguf - --host - 0.0.0.0 - --port - 8080 - -c - 4096 - --n-gpu-layers - 99 - --flash-attn - on deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] networks: - llama-net healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 10s retries: 3 networks: llama-net: driver: bridge internal: true逐项验证docker compose ps状态应为healthy健康检查生效curl http://localhost:8080/health不带密钥也能返回ok因为它是公开端点可放心交给编排系统探测任一业务请求不带Authorization: Bearer key头时应返回 401密钥生效Prometheus 侧把metrics_path指到/metrics抓一次能拉到数据即指标链路通。⚠️internal: true会让容器出不了外网需要在线拉模型的场景去掉这一行密钥防护保持不动。客户端两种接法原生流式补全与 OpenAI 兼容接入只有两种姿势走 llama.cpp 原生/completion端点或走/v1/chat/completions兼容入口其余细节在 tools/server/README.md 里有完整清单。原生流式-N让 curl 实时刷出 token请求体里stream:true是流式开关返回是逐条 JSON 拼出来的 token 流。curl -N http://localhost:8080/completion \ -H Content-Type: application/json \ -d {prompt:用一句话解释什么是容器化:,stream:true,n_predict:64}验证终端应逐字滚动出回答结束后以end事件收尾启用密钥后同一请求补-H Authorization: Bearer 你的key。OpenAI 兼容现有 OpenAI SDK 程序只改base_url为http://主机:8080/v1即可请求体结构与 OpenAI 完全一致。curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的key \ -d {model:llama-3.1-8b-instruct,messages:[{role:user,content:你好你是谁}],max_tokens:128}验证返回 JSON 中choices[0].message.content有内容即接通/embeddings、/slots等其余端点不多查 README 表格即可。按现象查故障五类报错分别先看哪里排障按客户端观察到的现象归类而不是按组件归类每条给出第一动作拿不准时统一回退到docker logs --tail 100 llama-inference看最后 100 行日志。现象根因第一动作8080 拒绝连接宿主机端口被占或容器起来后又退出docker ps -a看状态被占就改映射为8081:8080日志出现CUDA not foundtoolkit 未装或未对 Docker 生效装好 nvidia-container-toolkit 并重启 Docker 后再起容器GPU 版速度≈CPU 版层没上卡--n-gpu-layers实际生效为 0确认参数传进 command重启后看日志层数分布业务请求 401/health正常客户端没带鉴权头补Authorization: Bearer key/health本就公开进程被 OOM 杀掉权重 KV 缓存超出显存/内存按先降-c→ 再降层数 → 最后换量化顺序调整这套方案的边界能扛什么、扛不住什么llama-server 是单进程服务同一实例内的并发由-np槽位数控制横向扩容的正路是多起实例、前置 Nginx 或负载均衡而不是往单容器里堆请求——公开高并发场景直接放弃这个方案。单机私有部署 1B 到几十 B 的量化模型是它的舒适区机器迁移时只带走models/目录即可。需要频繁做模型格式转换时把镜像 tag 换成full-cuda一类带工具链的版本。深入细节查仓库内两份文档镜像清单与平台支持看 docs/docker.md全部 HTTP 端点与参数看 tools/server/README.md。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考