llama.cpp Docker 部署完整指南：三步搭起本地大模型推理服务

llama.cpp Docker 部署完整指南三步搭起本地大模型推理服务【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp手动编译 llama.cpp 要装 cmake、CUDA Toolkit、一摞依赖库换台机器全来一遍环境不一致、迁移麻烦是本地部署最耗时的部分。llama.cpp Docker 部署把整套推理栈打进了一个镜像同一条命令测试机和生产机跑出来的行为完全一致模型像 U 盘一样挂进去就能出词。本文带你从 CPU 裸跑一路走到生产级容器化推理镜像选型、GPU 加速、Compose 编排、API 接入、故障排查全覆盖。部署前速览一张表查清环境要求和镜像选型看完这节你能判断手头这台机器够不够跑该拉哪个镜像 tag。硬件底线以 7–8B Q4 量化模型为基准项目最低要求说明内存8 GB模型权重约 4–5 GB上下文 KV 缓存另占 1–3 GB磁盘20 GB 起一个 8B GGUF 约 5 GB留空间放多个量化版本CPU4 核以上建议 8 核线程数-t对齐物理核心NVIDIA GPU驱动 470 nvidia-container-toolkit显存 8 GB 起步AMD GPUAMDGPU 内核驱动 ROCm 主机库server-rocm镜像仅linux/amd64软件Docker Engine 20.10无需宿主机预装任何 C 依赖镜像怎么选官方提供full/light/server三个功能档位再叠加加速后缀。CPU 三档同时支持linux/amd64、linux/arm64、linux/s390x。Tag 后缀内容适合谁server仅llama-server可执行文件只要 HTTP 推理服务本文主线server-cuda/server-cuda13CUDA 12 / 13 编译NVIDIA 显卡server-rocmROCm 编译AMD 显卡server-vulkan/server-intel/server-musa对应后端编译其他 GPU 路线full推理工具 模型转换/量化全套需要自己把 HF 模型转 GGUFlight仅llama-cli/llama-completion命令行轻量实验一个细节server镜像内置HEALTHCHECKcurl /health默认入口就是/app/llama-server且预置LLAMA_ARG_HOST0.0.0.0——容器起来默认监听所有网卡你只需要关心模型和端口。更多细节可看项目里的 docs/docker.md。三步跑通第一个推理服务CPU 版看完这节能得到一个在http://localhost:18080上可用的推理接口。全程 CPU不碰 GPU。Step 1模型落盘准备目录结构模型统一放modelsmkdir -p ~/llama-stack/{models,logs,config}如果你手上只有 HuggingFace 原始权重用full镜像一次完成转换 量化容器内自带全部 Python 转换脚本docker run -v ~/llama-stack/models:/models \ ghcr.io/ggml-org/llama.cpp:full \ /app/convert_hf_to_gguf.py /host/path/to/hf-model \ --outtype q4_k_m -o /models/qwen3-8b-q4_k_m.gguf已有现成 GGUF 文件的直接丢进~/llama-stack/models/即可跳过这一步。Step 2启动容器docker run -d --name infer-core \ -p 18080:8080 \ -v ~/llama-stack/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/qwen3-8b-q4_k_m.gguf \ -c 8192 \ -t 8参数说明-p 18080:8080把宿主机 18080 映射到容器固定端口 8080-c 8192上下文长度-t 8CPU 生成线程数建议等于物理核心数。模型文件通过卷挂载插入容器宿主机换模型不用重建镜像。Step 3验证接口curl -s http://localhost:18080/health # 期望输出 {status: ok} curl -s http://localhost:18080/v1/models # 应看到刚加载的模型名/health是公开端点不校验任何密钥后面写健康检查直接复用。让 GPU 真正干活NVIDIA 与 AMD 两条路线这节解决两个问题容器里怎么看到显卡以及--n-gpu-layers到底填多少。先装 NVIDIA 容器工具链宿主机已装好 NVIDIA 驱动的前提下把nvidia-container-toolkit装上并重启 Dockersudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker一行验证驱动是否穿透到容器docker run --rm --gpus all ghcr.io/nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi能看到显卡型号就通了。然后拉 CUDA 版镜像跑服务docker run -d --name infer-gpu \ --gpus all \ -p 18080:8080 \ -v ~/llama-stack/models:/models \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/qwen3-8b-q4_k_m.gguf \ -c 8192 \ --n-gpu-layers -1--n-gpu-layers -1表示能塞进显存的层全部塞进去这是最省事的写法。也可以填具体层数配合--tensor-split 12,12把层切到多张卡上。GPU 层数怎么配显存对照表把--n-gpu-layers理解成分给显卡的工位模型有多少层你就可以决定前几层坐在 GPU 上剩下的留在 CPU。显存装不下的层会被自动挪回 CPU不会崩但速度掉得厉害。模型规模Q4_K_M权重大小建议显存建议配置7–8B约 4.5 GB8 GB全部层进 GPU余量给 KV 缓存14B约 8.5 GB12–16 GB全层或留最后 2–4 层在 CPU32B约 20 GB24 GB 单卡全层上下文别开太大70B约 40 GB2×24 GB双卡 --tensor-split注意显存 权重 KV 缓存。8192 上下文的 KV 缓存可能再吃 1–2 GB按权重 2 GB 缓冲来估比较稳。AMD ROCm 路线ROCm 需要手动把设备节点挂进容器标准四件套是--device /dev/kfd、--device /dev/dri、--group-add video、--ipchostdocker run -d --name infer-rocm \ --device /dev/kfd --device /dev/dri \ --group-add video --ipchost \ -p 18081:8080 \ -v ~/llama-stack/models:/models \ ghcr.io/ggml-org/llama.cpp:server-rocm \ -m /models/qwen3-8b-q4_k_m.gguf \ -c 8192 \ --n-gpu-layers -1AMD 显卡层数分配逻辑与 NVIDIA 相同看显存定层数即可。生产级编排一份完整的 docker-compose 配置这节给你一份可直接落盘的docker-compose.yml环境变量驱动、带健康检查、限制 GPU 资源、挂 Prometheus 采集指标。第一段推理服务本体./models只读挂载防容器内误写services: llama-infer: image: ghcr.io/ggml-org/llama.cpp:server-cuda container_name: llama-infer restart: unless-stopped ports: - 18080:8080 volumes: - ./models:/models:ro - ./logs:/app/logs environment: LLAMA_ARG_MODEL: /models/qwen3-8b-q4_k_m.gguf LLAMA_ARG_CTX_SIZE: 8192 LLAMA_ARG_N_GPU_LAYERS: -1 LLAMA_ARG_THREADS: 8 LLAMA_ARG_ENDPOINT_METRICS: 1 # 打开 /metrics 端点 healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 5s retries: 3 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]健康检查直接打/health模型没加载完时它返回 503Docker 会自动标记 unhealthy 并配合restart: unless-stopped拉起来。deploy.resources.reservations.devices把 GPU 数量钉死成 1 张防止调度歧义。第二段指标采集prometheus: image: prom/prometheus:latest ports: - 9091:9090 volumes: - ./config/prometheus.yml:/etc/prometheus/prometheus.yml depends_on: - llama-inferconfig/prometheus.yml指向容器服务名即可scrape_configs: - job_name: llama-infer metrics_path: /metrics static_configs: - targets: [llama-infer:8080]/metrics输出 Prometheus 格式指标前提是上面开了LLAMA_ARG_ENDPOINT_METRICS。常用环境变量速查环境变量等价参数作用LLAMA_ARG_MODEL-mGGUF 路径LLAMA_ARG_CTX_SIZE-c上下文长度LLAMA_ARG_N_GPU_LAYERS--n-gpu-layersGPU 层数-1为全量LLAMA_ARG_THREADS--threadsCPU 线程数LLAMA_ARG_ENDPOINT_METRICS--metrics开启指标端点LLAMA_API_KEY--api-key鉴权密钥逗号分隔多个环境变量与命令行参数等价好处是镜像、命令不变只改 compose 就能换模型、换上下文重跑docker compose up -d生效。接入你的应用API 三种玩法服务起来后你的应用有三种方式消费它按需选择。普通补全一次拿到完整结果curl -s http://localhost:18080/completion \ -H Content-Type: application/json \ -d { prompt: 请用三句话概括 KV 缓存的作用\n, n_predict: 128, temperature: 0.3 }流式输出边生成边打印请求体加stream: true响应变成逐行的 NDJSON每行一个content片段最后一行done: truecurl -sN http://localhost:18080/completion \ -H Content-Type: application/json \ -d {prompt: 写一个 docker 健康检查的要点,stream:true,n_predict:64}-N关掉 curl 缓冲前端体验上就是打字机效果。OpenAI 兼容接口存量代码零改造curl -s http://localhost:18080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-8b, messages: [ {role: user, content: 一句话解释什么是上下文窗口} ], max_tokens: 80 }只要你的代码走 OpenAI SDK把 base_url 指到http://宿主机:18080/v1其余参数几乎原样可用——这是接入成本最低的一条路。运维速查常见故障与日志排查出问题时按现象 → 先查什么对号入座能省掉一半定位时间。现象先查这里容器秒退日志报模型加载失败挂载路径对不对docker exec llama-infer ls /models有 GPU 却全在 CPU 上算是否加了--gpus all/ 工具链是否装好docker logs llama-infer \| grep -i cudaCUDA out of memory降-c、降--n-gpu-layers、换更低量化位宽启动报bind: address already in uselsof -i:18080找出占端口的进程/health返回 503模型还在加载或上下文耗尽稍等重试请求卡住后超时提示词超过-c限制或服务线程被打满看/metrics里队列指标排查命令四件套docker logs --tail 200 -f llama-infer # 跟踪最新日志 docker logs llama-infer 21 | grep -iE error|fail|CUDA docker stats llama-infer --no-stream # 看一眼 CPU / 内存 / 显存快照 curl -s http://localhost:18080/metrics | head # 采集到的指标头几行想看 GPU 到底吃进去多少层启动日志里有offloaded XX/YY layers to GPU数一下就知道分配结果。加固与横向扩展密钥、网络隔离与负载均衡服务要对内网或公网开放前先做三件事上密钥、关直连、能扩容。API 密钥server镜像支持--api-key可逗号分隔配多个。/health保持公开其余端点必须带Authorization: Bearer keydocker run -d --name infer-secure \ -e LLAMA_API_KEYsk-demo-001,sk-demo-002 \ -p 18080:8080 \ -v ~/llama-stack/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/qwen3-8b-q4_k_m.gguf curl -s http://localhost:18080/v1/models \ -H Authorization: Bearer sk-demo-001多客户端场景建议把密钥放文件里用--api-key-file环境变量LLAMA_ARG_API_KEY_FILE挂载进容器避免密钥进 compose 文件被提交进版本库。网络隔离推理容器不直接暴露端口统一走网关。给 compose 加一个内部网络networks: infer-net: internal: true # 容器无出网能力 services: llama-infer: networks: [infer-net] # ports 段删掉只允许内网访问 gateway: image: nginx:alpine ports: - 443:443 networks: [infer-net]internal: true意味着即使配置失误容器也连不出去只能从网关进来。TLS、限流都压在 nginx 层。横向扩展GPU 服务扩容就是多副本 轮询。两个实例跑在不同宿主机/端口nginx upstream 里写两个后端即可CPU 场景甚至可以在一台 8 卡机上起多个实例分卡。另一条路是官方镜像内置的 router 模式设LLAMA_ARG_MODELS_DIR指向模型目录一个 server 进程同时加载多个模型LLAMA_ARG_MODELS_MAX控制上限省掉多容器编排。收尾容器化推理换来的东西环境一致性镜像即环境编译、驱动封装全在镜像里换机器零配置模型即插即拔换 GGUF 只改挂载不动镜像GPU 按需开关server和server-cuda只差一个 tagCPU 调试、GPU 生产随意切可观测/health、/metrics开箱可用接 Prometheus 只要三行配置可复制compose 文件进版本库扩容就是docker compose up多几台llama.cpp 的镜像矩阵还在持续扩张Vulkan、OpenVino、SYCL……容器化部署这套打法可以原样平移到每一种后端上。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考