llama.cpp Docker部署：一条命令跑通本地推理服务

llama.cpp Docker部署：一条命令跑通本地推理服务

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

llama.cpp 是一个用纯 C/C++ 实现的本地大模型推理引擎，把它的 llama-server 装进 Docker 之后，你就得到一个开箱即用的容器化推理服务：模型文件留在宿主机上挂载进容器，OpenAI 兼容接口立刻可以调用，宿主机不用装任何 Python 环境。

谁适合用这套方案

• 想在自己的服务器或工作站上跑开源模型，又不想被编译依赖弄脏系统环境
• 给应用提供一个/v1/chat/completions兼容接口，且目标就是单机单卡（或纯 CPU）
• 需要可复制的推理环境：同一份镜像加同一组参数，换台机器照样起

如果你的目标是多机分布式推理或大规模自动扩缩容，llama.cpp 并不是合适的选型，它的设计定位是"单机、单模型、单服务"。

🚀 快速上手：5 分钟看到效果

最短路径是用官方 server 镜像跑 CPU 版：容器里只有 llama-server 可执行文件，模型不拷进镜像，而是用卷挂载的方式放进去。

mkdir -p ~/llama/models # GGUF 模型文件放这里 docker run -d --name llama-server -p 8080:8080 \ -v ~/llama/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/model-q4_k_m.gguf \ --host 0.0.0.0 -c 4096

这条命令做了四件事：把容器 8080 端口映射到宿主机、挂载模型目录、加载模型、以 4096 上下文启动 HTTP 服务。启动日志里出现服务就绪字样后，就可以往下走验证环节了。

整体流程如下：

环境要求与准备

目录规划记住两条：模型放在便于挂载的目录（如~/llama/models），并确认容器用户对该目录有读权限。模型可以是 GGUF 官方量化产物，也可以用 convert_hf_to_gguf.py 从 Hugging Face 权重自行转换。

分场景部署

🖥️ 纯 CPU

把快速上手的命令换一行写全，就是 CPU 版完整配置。生成慢的时候，显式把-t设成物理核心数通常比默认自动探测更好：

docker run -d --name llama-cpu -p 8080:8080 -v ~/llama/models:/models ghcr.io/ggml-org/llama.cpp:server -m /models/model-q4_k_m.gguf --host 0.0.0.0 -t 8

🎮 GPU 加速（NVIDIA）

先在宿主机装好 nvidia-container-toolkit（安装步骤见 NVIDIA 官方文档），再用docker run --rm --gpus all nvidia/cuda nvidia-smi确认容器内能看到卡。然后换server-cuda镜像并加上--gpus all：

docker run -d --name llama-cuda --gpus all \ -p 8080:8080 -v ~/llama/models:/models \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/model-q4_k_m.gguf \ --host 0.0.0.0 --n-gpu-layers 99

--n-gpu-layers 99的意思是"尽量多地把层放到 GPU 上"，显存不够时 llama.cpp 会自动回退到 CPU。AMD 显卡把镜像换成-rocm后缀即可，Intel 核显可用-intel（SYCL）变体，完整镜像清单见 docs/docker.md。

🏭 生产环境：docker compose 固定配置

要长期运行的服务，建议把参数锁进 compose 文件：重启策略、GPU 资源预留、健康检查都写在文件里。官方镜像支持用LLAMA_ARG_*环境变量传参，命令行一个参数都不用敲。

services: llama-server: image: ghcr.io/ggml-org/llama.cpp:server-cuda restart: unless-stopped ports: ["8080:8080"] volumes: [./models:/models, ./logs:/app/logs] environment: LLAMA_ARG_MODEL: /models/model-q4_k_m.gguf LLAMA_ARG_HOST: 0.0.0.0 LLAMA_ARG_CTX_SIZE: 8192 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/health"] interval: 30s

docker compose up -d即可。需要多实例时，起多个容器映射不同端口、前面挂一层反向代理就够了，不必额外引入编排层。

验证跑通与首次调用

先用一条命令确认服务活着，再发一次真实生成请求：

curl -s http://localhost:8080/health # 期望返回 {"status":"ok"} curl -s http://localhost:8080/completion -d '{"prompt":"一句话解释 Docker","n_predict":40}'

第二条命令返回带content字段的 JSON，说明 llama.cpp 容器化推理服务已经跑通。另外 llama-server 自带 Web UI，浏览器直接打开http://localhost:8080就能试聊，适合做冒烟测试。

⚙️ 参数调优与进阶

推理的核心计算是大量矩阵乘法，量化档位和 GPU 卸载策略直接决定速度与显存占用：

常见问题

收个尾

llama.cpp 的 Docker 部署把"模型 + 推理服务"打包成一份可复制的镜像：新机器上一条docker run，就能立刻获得 OpenAI 兼容的推理接口。镜像与参数细节可查 docs/docker.md，服务端的完整参数列表和 API 说明在 tools/server/ 目录里。

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