llama.cpp Docker 部署教程3 条命令起容器化推理服务镜像选型与生产配置全解【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp手上有一台装好 Docker 的 Linux 机器时用llama.cpp官方镜像可以在 10 分钟内把 GGUF 模型变成 HTTP 推理服务。前置条件只有三项Docker 可用、一个 GGUF 模型文件、一个空闲端口。全文共 6 步起 CPU 版容器验证链路、按硬件选镜像 tag、调 4 个性能参数、补生产化配置、发 2 种请求做验收、对照表格排障。所有命令与 tag 均出自 docs/docker.md 与 tools/server/README.md。用 3 条命令起一个 CPU 版 llama-server 容器直接说结论先不碰 GPU用纯 CPU 的server镜像把「模型文件 → 容器 → HTTP 接口」这条链路验证通。假设 GGUF 文件已放在~/llama-docker/models/目录没有的话可用full镜像的--all-in-one做下载与转换见 docs/docker.md依次执行mkdir -p ~/llama-docker/models docker run -d --name llama-min \ -p 8080:8080 \ -v ~/llama-docker/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参数逐一对应文档里的LLAMA_ARG_HOST/LLAMA_ARG_PORT/LLAMA_ARG_MODEL/LLAMA_ARG_CTX_SIZE容器内监听地址必须写0.0.0.0否则宿主机端口映射不进来。验证就一条命令curl -s http://localhost:8080/health返回 503 表示模型还在加载返回{status: ok}才是就绪状态——拿到后者链路就通了。✅ 若手头没有 GGUF 文件启动参数里把-m换成-hf user/model[:quant]如ggml-org/Qwen3.5-0.8B-GGUF可让服务直接从 Hugging Face 拉取这一步不阻塞部署。按硬件对号入座镜像 tag 与宿主机前置条件官方镜像按「入口程序 × 计算后端」打 tag完整清单见 docs/docker.md。server系列只含llama-serverlight系列只含 CLI 工具full系列额外带模型转换链。拿不准硬件就先用不带后缀的server链路通了再换后缀版本其余参数原样保留计算后端镜像 tag宿主机前置条件可用平台纯 CPUghcr.io/ggml-org/llama.cpp:server无amd64 / arm64 / s390xNVIDIA GPUghcr.io/ggml-org/llama.cpp:server-cuda或server-cuda13nvidia-container-toolkit运行时加--gpus allamd64 / arm64AMD GPUghcr.io/ggml-org/llama.cpp:server-rocmROCm 驱动与运行时amd64摩尔线程 GPUghcr.io/ggml-org/llama.cpp:server-musamt-container-toolkit 并设 mthreads 为默认 runtimeamd64Intel GPUghcr.io/ggml-org/llama.cpp:server-intel宿主装好 Intel GPU 驱动挂载/dev/dri设备amd64通用 GPU无专用驱动ghcr.io/ggml-org/llama.cpp:server-vulkan无几乎通吃各类 GPUamd64 / arm64⚠️ 官方说明 GPU 镜像在 CI 中只验证构建、不做功能测试。tag 里带cuda13/特定 CUDA 版本不满足你的环境时用仓库内.devops/cuda.Dockerfile本地docker build --target server自行构建文档中给出了完整示例。4 个参数决定显存占用与生成速度llama-server全部是原生命令行参数且每个参数都有同名LLAMA_ARG_*环境变量compose 里更常用。调优只盯下面 4 个其余保持默认即可参数环境变量控制什么建议起步值-ngl, --n-gpu-layersLLAMA_ARG_N_GPU_LAYERS放进显存的最大层数支持精确数字、auto、allGPU 场景先给99OOM 再降到 20~40-c, --ctx-sizeLLAMA_ARG_CTX_SIZE提示上下文长度显存随其上涨4096长文再翻倍-t, --threadsLLAMA_ARG_THREADS生成阶段 CPU 线程数等于物理核心数-fa, --flash-attnLLAMA_ARG_FLASH_ATTN注意力优化on/off/auto三态长上下文给on补充两点批处理大小-b, --batch-size默认已是 2048一般不用动-ngl与显存不匹配时默认开启的--fiton会自动把未设参数收缩到设备能容纳的范围这解释了「为什么启动日志里的层数和你填的不一样」。验证 GPU 是否真的参与计算看容器日志里 backend 初始化段落与每 token 速度即可速度量级差 5 倍以上才算上了卡。用 4 项配置把服务加固到生产标准生产化只补 4 件事抄这份精简版docker-compose.yaml即可上线写法参照 tools/server/README.md 的环境变量示例services: llama-inference: image: ghcr.io/ggml-org/llama.cpp:server-cuda restart: unless-stopped ports: [8080:8080] volumes: - ./models:/models environment: LLAMA_ARG_MODEL: /models/llama-3.1-8b-instruct-q4_k_m.gguf # 模型路径走环境变量 LLAMA_ARG_CTX_SIZE: 4096 LLAMA_ARG_N_GPU_LAYERS: 99 LLAMA_ARG_ENDPOINT_METRICS: 1 # 打开 /metrics LLAMA_API_KEY: change-me-32chars # 鉴权密钥/health 不受影响 healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 10s retries: 3 networks: [llama-net] networks: llama-net: driver: bridge internal: true # 禁止容器出网见下方说明四项各自的落点密钥LLAMA_API_KEY支持逗号分隔多 key请求侧带Authorization: Bearer key/health是公开端点可放心交给编排系统探测。健康检查/health在模型加载完成前返回 503正好被curl -f判为失败天然适合作为编排系统的就绪探针。指标LLAMA_ARG_ENDPOINT_METRICS1后Prometheus 将metrics_path指向/metrics可抓predicted_tokens_seconds生成吞吐等 15 项指标清单见 tools/server/README.md。内网⚠️internal: true意味着容器无法访问外网。需要-hf在线拉模型或访问外部资源时去掉该行并保留密钥防护。多 GPU 场景再把deploy.resources.reservations.devicesnvidiacount: 1加上参数细节参考 docs/multi-gpu.md。发 2 种请求验收服务验收只需两类请求原生补全接口验证链路OpenAI 兼容接口验证客户端切换成本。# 原生流式补全-N 让 curl 不缓冲、实时刷出 token curl -N http://localhost:8080/completion \ -H Content-Type: application/json \ -H Authorization: Bearer change-me-32chars \ -d {prompt:用一句话解释什么是容器化:,stream:true,n_predict:64}响应体逐段打印 token 且无报错说明推理链路完整。第二条给现有 OpenAI SDK 客户端验证兼容性curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer change-me-32chars \ -d {model:llama-3.1-8b-instruct,messages:[{role:user,content:你好你是谁}],max_tokens:128}拿到choices[0].message.content即代表 OpenAI SDK 只需改base_url就能接入。✅ 注意/completion不是 OpenAI 兼容端点SDK 客户端必须走/v1/completions。其余/slots、/embeddings、/reranking、/tokenize等端点不多全部定义在 tools/server/README.md 的 API Endpoints 一节。故障对照表与适用边界排障先看现象动作都在下面这张表里覆盖 90% 的部署卡点现象大概率原因处理动作8080 连不上容器启动即退出或宿主机端口被占docker logs --tail 100 llama-min端口冲突改映射为8081:8080报找不到模型文件挂载点与-m路径没对上确认-m以/models/开头且文件真实存在于宿主机./models进程被 OOM 杀掉-c或-ngl撑爆内存/显存降上下文或层数或换更低量化版本1.5~8 bit 均可CUDA 镜像却跑在 CPU缺 nvidia-container-toolkit 或漏了--gpus all装好 toolkit 后重启 Docker补--gpus all再跑加密钥后 401请求没带鉴权头补Authorization: Bearer key/health一直 503大模型加载慢或加载失败等加载完成仍 503 则查docker logs中加载报错适合谁单机私有部署 1B 到几十 B 量级的量化模型。环境锁死在镜像里机器迁移只需带走models/目录需要同时做格式转换时把 tag 换成full-cuda即可兼得推理与转换工具链。不适合谁公网高并发入口。llama-server本质是单进程服务内部用 slots 连续批处理承载并发横向扩容的正路是起多个实例、前面挂反向代理做负载均衡而不是往单容器塞更多请求。想继续深入读 docs/docker.md镜像清单与本地构建和 tools/server/README.md全部 HTTP 端点与参数多卡场景另见 docs/multi-gpu.md。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考