10 分钟用 Docker 部署 llama.cpp从本地体验到 GPU 生产级服务【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cppllama.cpp 的 Docker 镜像把 C 编译、CUDA 工具链、依赖库这些麻烦事全打进了容器你只需要一个 Docker 环境就能起服务。先说下为什么要容器化。手工装 llama.cpp 推理服务很折腾CMake、编译器、显卡驱动版本每台机器都要配一遍环境稍有差异就可能装不上。机器配置不一致的问题更常见同事的笔记本能跑你的服务器起不来。模型版本一更新又要重新折腾一轮。把 llama.cpp Docker 部署做好之后换机器只需复制一条docker run命令模型文件放哪里、用几张卡、开多大上下文都写在配置里机器之间没有玄学。读完这篇你会拿到一个能对外提供 API 的推理服务并知道怎么把它搬到 GPU 和生产环境。2. 3 条命令启动第一个本地 LLM API 服务核心就三步拉镜像、挂模型目录、起容器。模型文件先放在宿主机任意目录比如~/models。# 1. 拉取 server 镜像只含 llama-server体积小 docker pull ghcr.io/ggml-org/llama.cpp:server # 2. 起服务挂模型目录映射 8080 端口 docker run -d --name llama-demo -p 8080:8080 \ -v ~/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/qwen2.5-1.5b-instruct-q4_k_m.gguf \ --host 0.0.0.0 -c 4096-v是挂载相当于给容器插一块移动硬盘容器里看到的/models就是宿主机的~/models模型文件不用拷进镜像。# 3. 发一条补全请求看模型开口 curl http://localhost:8080/completion \ -d {prompt: 你好,n_predict: 32}浏览器打开http://localhost:8080也能看到自带 Web 页面。看到回复之后接下来是真正头疼的事镜像那么多变体模型又该挑哪个。3. llama.cpp 容器化推理服务的模型与镜像怎么选选错镜像多下几个 G 是小事少一个工具导致流程卡住才是麻烦。先分清两个维度镜像管程序模型管内容互不绑定。镜像怎么选基础 tag 都支持 amd64 / arm64arm 服务器可以直接用:light—— 只有llama-cli和llama-completion想先本地试跑模型选它:full—— 在上面基础上加了模型转换、量化工具。拿到原始权重要自己转 GGUF 时才需要:server—— 只有llama-server部署 API 服务的默认选择带-cuda、-cuda13、-rocm、-vulkan后缀的 —— 同规格但编译了对应 GPU 后端比如server-cuda、server-rocm模型怎么选llama.cpp 只吃 GGUF 格式。GGUF 是一种单文件权重格式量化后缀决定体积和精度Q4_K_M是 4-bit 档位里精度/体积的常见平衡点Q8_0更接近全精度但体积翻倍Q2更小但明显掉智商。小卡或纯 CPU 场景优先 Q4 档。拿到 HF 上的原始权重safetensors想自己转的话full镜像里有convert_hf_to_gguf.py或者看仓库根目录的转换脚本和 docs/ 说明。整个链路是这样的镜像和模型都定好了下一步就是让它在 GPU 上跑起来速度会完全是另一个量级。4. llama.cpp GPU 加速部署7B / 13B / 70B 层数推荐GPU 加速的关键参数就一个--n-gpu-layers控制多少层权重放显存剩下的留给 CPU。三条路线按硬件对号入座纯 CPU什么都不用加。server 镜像默认按 CPU 跑把-t设成物理核心数就行。够跑 Q4 档的 7B 以内模型速度一般是个位数 token/s适合体验和轻量场景NVIDIA CUDA宿主机装好驱动和 nvidia-container-toolkitnvidia-smi正常、docker run --gpus all能进容器即可然后换成server-cuda镜像AMD ROCm同上思路换server-rocm镜像装好对应容器工具链# CUDA 版起法只比 CPU 版多三处 docker run -d --name llama-cuda -p 8080:8080 \ --gpus all \ -v ~/models:/models \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/llama-2-13b-q4_k_m.gguf \ --host 0.0.0.0 -c 4096 \ --n-gpu-layers 40层数与显存参考Q4 档粗算KV cache 另占显存留 1~2GB 余量7B约 4~6GB 显存--n-gpu-layers 35起塞不下就往下调13B约 8~10GB--n-gpu-layers 40上下70B单卡 24GB 放不下需 40GB 或多卡。多卡时加--split-mode layer细节看 docs/multi-gpu.md现在服务能跑了但docker run一长串参数不适合当正式服务用下面换成 Compose 管理。5. llama.cpp Docker Compose 生产配置生产部署要解决的是参数别散落在命令行、挂了要能自动拉起来、要能探活、日志别撑爆磁盘。一份 Compose 全装下。services: llama-server: image: ghcr.io/ggml-org/llama.cpp:server-cuda container_name: llama-inference restart: unless-stopped ports: - 8080:8080 volumes: - ./models:/models:ro # 模型目录只读挂入 environment: LLAMA_ARG_HOST: 0.0.0.0 LLAMA_ARG_PORT: 8080 LLAMA_ARG_CTX_SIZE: 8192 LLAMA_ARG_N_GPU_LAYERS: 40 LLAMA_ARG_BATCH: 512 LLAMA_ARG_THREADS: 8 command: - --model - /models/llama-2-13b-q4_k_m.gguf - --api-key - ${LLAMA_API_KEY} # 从宿主机 .env 注入别写死在文件里 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: [CMD, curl, -fsS, http://localhost:8080/health] interval: 30s timeout: 5s retries: 3 logging: driver: json-file options: max-size: 50m max-file: 5几个容易踩的点环境变量名是LLAMA_ARG_加参数名对应关系在 tools/server/README.md 的参数表里能查到模型路径走command里的--model-m没有对应的LLAMA_ARG_MODEL别照抄网上文章--api-key开启鉴权后所有请求都要带Authorization: Bearer key/health不带模型参数启动期就能探活适合直接做健康检查日志加了max-size轮转不然json-file会一直往磁盘里写服务稳定之后就该考虑怎么让业务代码调起来了。6. 接入自己的应用三种调用方式同一个服务暴露了三套接口按客户端现状挑一个就行。① 原生 completion—— 最直接的补全接口curl http://localhost:8080/completion \ -d {prompt: 解释一下 KV cache, n_predict: 128}② 流式输出—— 同接口加stream: truetoken 边生成边推curl -N http://localhost:8080/completion \ -d {prompt: 写一首短诗, stream: true}③ OpenAI 兼容—— 走/v1/chat/completions现有 OpenAI SDK 改个base_url就能接curl http://localhost:8080/v1/chat/completions \ -H Authorization: Bearer $LLAMA_API_KEY \ -d {model: llama-2-13b, messages: [ {role: user, content: 你好介绍一下自己} ], max_tokens: 100}怎么选项目已经重度依赖 OpenAI SDK直接上 ③迁移成本最低自己控制请求细节、不想绑 SDK用 ①前端要打字机效果任何方式都开流式。接口细节和请求字段tools/server/ 源码和它的 README 是最权威的参照。当然真上生产总会出点状况。下面四段症状 → 检查 → 解决基本覆盖高频故障。7. llama.cpp 容器排障症状 → 检查 → 解决 四段排查路径按顺序对模型加载失败症状容器起来后日志报failed to load model/health一直不健康检查docker logs llama-inference确认挂载路径下文件真实存在文件名和-m参数完全一致大小正常几 GB 的模型不可能只有几百 KB多半是下载断了解决重新下载或校验 GGUF 文件文件名有空格或中文的改掉再试GPU 识别不到症状日志显示用了 CPU 后端没有 CUDA 相关输出检查宿主机nvidia-smi是否正常docker run --rm --gpus all ghcr.io/ggml-org/llama.cpp:server-cuda --list-devices能否看到卡解决装 nvidia-container-toolkit 并重启 Docker镜像必须用-cuda变体普通 server 镜像里没有 CUDA 后端内存不足 / OOM症状加载卡死或dmesg出现 OOM容器被 kill检查free -h看内存余量对照模型文件大小7B 的 Q4 权重约 4GBKV cache 会再吃一份解决调小--ctx-size、换更低量化档位GPU 场景把--n-gpu-layers调低让部分层留在 CPU端口冲突症状docker run报Bind for 0.0.0.0:8080 failed: port is already allocated检查ss -tlnp | grep 8080看谁占了端口解决宿主机侧换个端口映射比如-p 8081:8080容器内部 8080 不用动8. 再往后的事这套跑稳之后单实例吞吐不够了就在前面加一层 nginx把请求分到多个 llama-server 实例做负载均衡。实例数想跟着负载走可以迁到 Kubernetes 或 Docker Swarm 上配自动扩缩。监控方面服务端原生支持--metrics暴露 Prometheus 指标接上就能盯 token 速度和队列。更大的模型可以靠多卡拆分跑起来相关参数都写在 docs/multi-gpu.md 里。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 10 分钟用 Docker 部署 llama.cpp：从本地体验到 GPU 生产级服务
10 分钟用 Docker 部署 llama.cpp从本地体验到 GPU 生产级服务【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cppllama.cpp 的 Docker 镜像把 C 编译、CUDA 工具链、依赖库这些麻烦事全打进了容器你只需要一个 Docker 环境就能起服务。先说下为什么要容器化。手工装 llama.cpp 推理服务很折腾CMake、编译器、显卡驱动版本每台机器都要配一遍环境稍有差异就可能装不上。机器配置不一致的问题更常见同事的笔记本能跑你的服务器起不来。模型版本一更新又要重新折腾一轮。把 llama.cpp Docker 部署做好之后换机器只需复制一条docker run命令模型文件放哪里、用几张卡、开多大上下文都写在配置里机器之间没有玄学。读完这篇你会拿到一个能对外提供 API 的推理服务并知道怎么把它搬到 GPU 和生产环境。2. 3 条命令启动第一个本地 LLM API 服务核心就三步拉镜像、挂模型目录、起容器。模型文件先放在宿主机任意目录比如~/models。# 1. 拉取 server 镜像只含 llama-server体积小 docker pull ghcr.io/ggml-org/llama.cpp:server # 2. 起服务挂模型目录映射 8080 端口 docker run -d --name llama-demo -p 8080:8080 \ -v ~/models:/models \ ghcr.io/ggml-org/llama.cpp:server \ -m /models/qwen2.5-1.5b-instruct-q4_k_m.gguf \ --host 0.0.0.0 -c 4096-v是挂载相当于给容器插一块移动硬盘容器里看到的/models就是宿主机的~/models模型文件不用拷进镜像。# 3. 发一条补全请求看模型开口 curl http://localhost:8080/completion \ -d {prompt: 你好,n_predict: 32}浏览器打开http://localhost:8080也能看到自带 Web 页面。看到回复之后接下来是真正头疼的事镜像那么多变体模型又该挑哪个。3. llama.cpp 容器化推理服务的模型与镜像怎么选选错镜像多下几个 G 是小事少一个工具导致流程卡住才是麻烦。先分清两个维度镜像管程序模型管内容互不绑定。镜像怎么选基础 tag 都支持 amd64 / arm64arm 服务器可以直接用:light—— 只有llama-cli和llama-completion想先本地试跑模型选它:full—— 在上面基础上加了模型转换、量化工具。拿到原始权重要自己转 GGUF 时才需要:server—— 只有llama-server部署 API 服务的默认选择带-cuda、-cuda13、-rocm、-vulkan后缀的 —— 同规格但编译了对应 GPU 后端比如server-cuda、server-rocm模型怎么选llama.cpp 只吃 GGUF 格式。GGUF 是一种单文件权重格式量化后缀决定体积和精度Q4_K_M是 4-bit 档位里精度/体积的常见平衡点Q8_0更接近全精度但体积翻倍Q2更小但明显掉智商。小卡或纯 CPU 场景优先 Q4 档。拿到 HF 上的原始权重safetensors想自己转的话full镜像里有convert_hf_to_gguf.py或者看仓库根目录的转换脚本和 docs/ 说明。整个链路是这样的镜像和模型都定好了下一步就是让它在 GPU 上跑起来速度会完全是另一个量级。4. llama.cpp GPU 加速部署7B / 13B / 70B 层数推荐GPU 加速的关键参数就一个--n-gpu-layers控制多少层权重放显存剩下的留给 CPU。三条路线按硬件对号入座纯 CPU什么都不用加。server 镜像默认按 CPU 跑把-t设成物理核心数就行。够跑 Q4 档的 7B 以内模型速度一般是个位数 token/s适合体验和轻量场景NVIDIA CUDA宿主机装好驱动和 nvidia-container-toolkitnvidia-smi正常、docker run --gpus all能进容器即可然后换成server-cuda镜像AMD ROCm同上思路换server-rocm镜像装好对应容器工具链# CUDA 版起法只比 CPU 版多三处 docker run -d --name llama-cuda -p 8080:8080 \ --gpus all \ -v ~/models:/models \ ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/llama-2-13b-q4_k_m.gguf \ --host 0.0.0.0 -c 4096 \ --n-gpu-layers 40层数与显存参考Q4 档粗算KV cache 另占显存留 1~2GB 余量7B约 4~6GB 显存--n-gpu-layers 35起塞不下就往下调13B约 8~10GB--n-gpu-layers 40上下70B单卡 24GB 放不下需 40GB 或多卡。多卡时加--split-mode layer细节看 docs/multi-gpu.md现在服务能跑了但docker run一长串参数不适合当正式服务用下面换成 Compose 管理。5. llama.cpp Docker Compose 生产配置生产部署要解决的是参数别散落在命令行、挂了要能自动拉起来、要能探活、日志别撑爆磁盘。一份 Compose 全装下。services: llama-server: image: ghcr.io/ggml-org/llama.cpp:server-cuda container_name: llama-inference restart: unless-stopped ports: - 8080:8080 volumes: - ./models:/models:ro # 模型目录只读挂入 environment: LLAMA_ARG_HOST: 0.0.0.0 LLAMA_ARG_PORT: 8080 LLAMA_ARG_CTX_SIZE: 8192 LLAMA_ARG_N_GPU_LAYERS: 40 LLAMA_ARG_BATCH: 512 LLAMA_ARG_THREADS: 8 command: - --model - /models/llama-2-13b-q4_k_m.gguf - --api-key - ${LLAMA_API_KEY} # 从宿主机 .env 注入别写死在文件里 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] healthcheck: test: [CMD, curl, -fsS, http://localhost:8080/health] interval: 30s timeout: 5s retries: 3 logging: driver: json-file options: max-size: 50m max-file: 5几个容易踩的点环境变量名是LLAMA_ARG_加参数名对应关系在 tools/server/README.md 的参数表里能查到模型路径走command里的--model-m没有对应的LLAMA_ARG_MODEL别照抄网上文章--api-key开启鉴权后所有请求都要带Authorization: Bearer key/health不带模型参数启动期就能探活适合直接做健康检查日志加了max-size轮转不然json-file会一直往磁盘里写服务稳定之后就该考虑怎么让业务代码调起来了。6. 接入自己的应用三种调用方式同一个服务暴露了三套接口按客户端现状挑一个就行。① 原生 completion—— 最直接的补全接口curl http://localhost:8080/completion \ -d {prompt: 解释一下 KV cache, n_predict: 128}② 流式输出—— 同接口加stream: truetoken 边生成边推curl -N http://localhost:8080/completion \ -d {prompt: 写一首短诗, stream: true}③ OpenAI 兼容—— 走/v1/chat/completions现有 OpenAI SDK 改个base_url就能接curl http://localhost:8080/v1/chat/completions \ -H Authorization: Bearer $LLAMA_API_KEY \ -d {model: llama-2-13b, messages: [ {role: user, content: 你好介绍一下自己} ], max_tokens: 100}怎么选项目已经重度依赖 OpenAI SDK直接上 ③迁移成本最低自己控制请求细节、不想绑 SDK用 ①前端要打字机效果任何方式都开流式。接口细节和请求字段tools/server/ 源码和它的 README 是最权威的参照。当然真上生产总会出点状况。下面四段症状 → 检查 → 解决基本覆盖高频故障。7. llama.cpp 容器排障症状 → 检查 → 解决 四段排查路径按顺序对模型加载失败症状容器起来后日志报failed to load model/health一直不健康检查docker logs llama-inference确认挂载路径下文件真实存在文件名和-m参数完全一致大小正常几 GB 的模型不可能只有几百 KB多半是下载断了解决重新下载或校验 GGUF 文件文件名有空格或中文的改掉再试GPU 识别不到症状日志显示用了 CPU 后端没有 CUDA 相关输出检查宿主机nvidia-smi是否正常docker run --rm --gpus all ghcr.io/ggml-org/llama.cpp:server-cuda --list-devices能否看到卡解决装 nvidia-container-toolkit 并重启 Docker镜像必须用-cuda变体普通 server 镜像里没有 CUDA 后端内存不足 / OOM症状加载卡死或dmesg出现 OOM容器被 kill检查free -h看内存余量对照模型文件大小7B 的 Q4 权重约 4GBKV cache 会再吃一份解决调小--ctx-size、换更低量化档位GPU 场景把--n-gpu-layers调低让部分层留在 CPU端口冲突症状docker run报Bind for 0.0.0.0:8080 failed: port is already allocated检查ss -tlnp | grep 8080看谁占了端口解决宿主机侧换个端口映射比如-p 8081:8080容器内部 8080 不用动8. 再往后的事这套跑稳之后单实例吞吐不够了就在前面加一层 nginx把请求分到多个 llama-server 实例做负载均衡。实例数想跟着负载走可以迁到 Kubernetes 或 Docker Swarm 上配自动扩缩。监控方面服务端原生支持--metrics暴露 Prometheus 指标接上就能盯 token 速度和队列。更大的模型可以靠多卡拆分跑起来相关参数都写在 docs/multi-gpu.md 里。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考