llama.cpp 本地部署完全指南：从安装到 OpenAI 兼容 API 服务

发布日期：2026-08-12 | 数据来源：llama.cpp 官方 GitHub（ggml-org/llama.cpp）文档、官方 install.md / build.md / server 文档 | 话题：llama.cpp · 本地大模型 · GGUF · llama-server

llama.cpp 是由 Georgi Gerganov 开发的高性能大模型推理框架，以纯 C/C++ 实现、零外部依赖著称，支持 1.5 到 8 位整数量化，可在笔记本 CPU 上运行 7B 模型，也可通过 CUDA / Metal / Vulkan 将推理卸载到 GPU 加速；截至 2026 年 8 月最新版本 b10369（123k+ Stars），项目已从早期仅支持 LLaMA 系列发展为覆盖 Qwen3、DeepSeek、Kimi K3、GLM 等主流开源模型的通用推理引擎，内置llama-server可一键暴露 OpenAI 兼容 REST API，让本地模型无缝替换云端 API；本文覆盖三平台（macOS / Linux / Windows）的安装方式、GPU 加速编译、GGUF 模型选择、llama-server生产配置，以及常见显存不足场景的调参策略。

llama.cpp 是什么，和 Ollama 有什么区别

llama.cpp是底层推理引擎，直接操作 GGUF 量化格式的模型文件，提供命令行工具和 REST API，适合需要精细控制推理参数、自行集成 API 服务的开发者。

Ollama是对 llama.cpp 的高层封装（macOS 版已从 llama.cpp 迁移至 Apple MLX，2026 年 3 月），提供更简单的模型管理命令（ollama pull/ollama run），适合快速上手但不需要调参的场景。

关系：学 llama.cpp = 学底层，理解量化、层卸载、KV Cache 等机制；用 Ollama = 黑盒使用，两者都基于 GGUF 格式，模型文件通用。

安装：三平台最快路径

macOS（推荐 Homebrew）

brewinstallllama.cpp

Homebrew 版本随官方 Release 自动更新，包含 Metal GPU 加速支持（Apple Silicon 默认启用）。

验证安装：

llama-cli--versionllama-server--version

Linux

# conda-forge（包含 CUDA / Vulkan 版本）condainstall-cconda-forge llama.cpp# 或 Homebrew（Linux 同样支持）brewinstallllama.cpp

Windows（三种方式，任选其一）

方式一：Winget（最简单）

winget install llama.cpp

方式二：GitHub Release 预编译包（推荐，按显卡选版本）

前往 https://github.com/ggml-org/llama.cpp/releases 下载对应版本：

下载后解压，在解压目录直接运行llama-server.exe，无需安装。

方式三：从源码编译（需要 GPU 加速时）

从源码编译：GPU 加速版本

包管理器安装的版本已包含对应平台的 GPU 加速，若需要手动编译：

NVIDIA CUDA 加速（Linux / Windows）

前提：安装 CUDA Toolkit（12.x 推荐）

gitclone https://github.com/ggml-org/llama.cppcdllama.cpp cmake-Bbuild-DGGML_CUDA=ON cmake--buildbuild--configRelease-j8

Apple Silicon Metal 加速（macOS）

Metal 默认启用，无需额外参数：

cmake-Bbuild cmake--buildbuild--configRelease-j8

AMD GPU（Vulkan，跨平台）

cmake-Bbuild-DGGML_VULKAN=ON cmake--buildbuild--configRelease-j8

编译完成后，可执行文件在build/bin/目录下。

获取模型：GGUF 格式和量化选择

llama.cpp 只能运行 GGUF 格式的量化模型。

从 HuggingFace 下载（命令行直接拉取）

# 直接运行 HuggingFace 上的 GGUF 模型（自动下载）llama-cli-hfggml-org/Qwen3.5-0.8B-GGUF

也可以手动下载 GGUF 文件：

# 安装 huggingface_hubpipinstallhuggingface_hub# 下载指定量化版本huggingface-cli download\Qwen/Qwen3-8B-GGUF\qwen3-8b-q4_k_m.gguf\--local-dir ./models

量化版本怎么选

GGUF 文件名中的量化标识对应不同的精度和内存需求，以 7B/8B 模型为例：

命名规则：Q{位数}_K_{规格}中，K表示 K-quant 方法（比同位数的旧方法精度更高），M是中等（Medium），S是小（Small），L是大（Large）。通常首选 Q4_K_M，在文件大小和输出质量之间平衡最优。

各参数量对应内存需求（Q4_K_M）

估算公式：参数量（B）× 量化位数 / 8 × 1.2（KV Cache + 框架开销）

基础推理：llama-cli

# 单次问答llama-cli-m./models/qwen3-8b-q4_k_m.gguf\-p"用一句话解释什么是量化"# 交互式对话模式llama-cli-m./models/qwen3-8b-q4_k_m.gguf\-i-ins# 全 GPU 推理（-ngl 999 = 所有层卸载到 GPU）llama-cli-m./models/qwen3-8b-q4_k_m.gguf\-ngl999\-p"写一个快速排序的 Python 实现"

常用参数说明：

llama-server：一键启动 OpenAI 兼容 API

这是 llama.cpp 最重要的功能之一：启动一个完全兼容 OpenAI API 格式的本地 HTTP 服务，现有接入 OpenAI 的代码只需改base_url即可指向本地。

基础启动

llama-server\-m./models/qwen3-8b-q4_k_m.gguf\--host0.0.0.0\--port8080\-ngl999

启动后：

• 内置 Web UI：http://localhost:8080
• API 端点：http://localhost:8080/v1/chat/completions
• 模型列表：http://localhost:8080/v1/models

生产配置（多并发 + Flash Attention）

llama-server\-m./models/qwen3-8b-q4_k_m.gguf\--host0.0.0.0\--port8080\-ngl999\-c8192\--parallel4\--flash-attn\--api-key"your-local-key"

用 OpenAI SDK 调用本地服务

fromopenaiimportOpenAI client=OpenAI(api_key="your-local-key",# 与 --api-key 一致，不鉴权时填任意字符串base_url="http://localhost:8080/v1",)completion=client.chat.completions.create(model="qwen3-8b-q4_k_m",# 填 model 名（llama-server 自动识别）messages=[{"role":"system","content":"你是一位专业的代码审查工程师。"},{"role":"user","content":"帮我审查这段 Python 代码：..."},],)print(completion.choices[0].message.content)

Node.js 同样适用，只需将baseURL指向http://localhost:8080/v1。

显存不足怎么办：层卸载调参

llama.cpp 的核心优势之一是CPU+GPU 混合推理：当显存不够装下整个模型时，可以通过-ngl控制卸载到 GPU 的层数，剩余层在 CPU 内存中运行，速度下降但不会崩溃。

调参策略：

# 先试全量 GPU（-ngl 999），如果 OOM：llama-server-mmodel.gguf-ngl999# OOM？# 逐步降低 -ngl 值，找到不 OOM 的最大值llama-server-mmodel.gguf-ngl32# 32 层到 GPU，其余 CPUllama-server-mmodel.gguf-ngl20# 继续降低

其他节省显存的手段：

1. 选更低量化版本：Q4_K_S 比 Q4_K_M 小约 10%
2. 缩减上下文：-c 2048比-c 8192节省约 75% KV Cache 显存
3. 启用 Flash Attention：--flash-attn，KV Cache 显存减少约 30–50%
4. 使用更小参数量模型：3B 量化版比 7B 显存需求减半

多 GPU 配置

多张 NVIDIA GPU 时，llama.cpp 默认在全部可用 GPU 上均匀分层。可以通过CUDA_VISIBLE_DEVICES环境变量控制使用哪几张：

# 只使用 GPU 0 和 GPU 1CUDA_VISIBLE_DEVICES=0,1llama-server-mmodel.gguf-ngl999

多 GPU 拆分模式详见官方docs/multi-gpu.md。

常见问题

Q：GGUF 文件去哪里下载？
主要来源：HuggingFace（huggingface.co）搜索模型名 + GGUF，通常找ggml-org/、bartowski/或模型原始仓库下的 GGUF 分支；国内可通过 ModelScope（modelscope.cn）镜像下载，速度更快。

Q：-ngl 999和-ngl 0有什么区别？
-ngl 999= 尽可能多地把模型层卸载到 GPU（受显存限制自动截断）；-ngl 0= 全 CPU 推理，完全不使用 GPU。通常设-ngl 999让 llama.cpp 自动决定能卸多少层。

Q：llama-server 启动后 Web UI 没有响应？
检查：①--host是否写了0.0.0.0（默认 127.0.0.1 不对外）；②端口是否被占用（换--port 8081）；③设了--api-key但浏览器没有带 Token 访问。

Q：模型输出是乱码或者语言错误？
通常是-c上下文设置过小（被截断）或者系统提示词语言与用户语言不一致。另外部分模型有 chat_template，使用-i -ins参数确保使用了正确的对话格式。

Q：llama.cpp 和 vLLM 怎么选？
llama.cpp：单机本地部署、显存有限、需要量化、以 GGUF 为格式，适合个人开发者和边缘设备；vLLM：高并发生产服务、A100/H100 级 GPU、需要 PagedAttention 提升吞吐量，适合企业规模推理服务。两者定位不同，llama.cpp 在资源受限场景下是首选。

Q：企业有 GPU 服务器但不想自己维护推理服务，有什么替代方案？
可以选择支持多家国产开源模型的 API 平台，统一 OpenAI 格式接入，无需维护推理基础设施。代码调用方式与 llama-server 相同，只需将base_url和api_key替换为平台提供的值（如七牛云 Token Plan，qiniu.com/ai/plan，覆盖 DeepSeek / Kimi / GLM / MiniMax 四家共 25 个模型）。

小结

llama.cpp 是当前最成熟的本地大模型推理引擎：安装方面，macOS 用brew install llama.cpp，Windows 用 Winget 或 GitHub Release 预编译包，10 分钟内可完成部署；模型方面，Q4_K_M 是性价比最高的量化选择，6–8 GB 显存可流畅运行 7B 模型；API 服务方面，llama-server一行命令启动 OpenAI 兼容接口，现有代码零改动接入本地；性能不足时，先用--flash-attn降 KV Cache 开销，再用-ngl混合 CPU/GPU 推理，几乎在所有硬件上都能找到可用配置。

本文基于 llama.cpp b10369（2026-08-12），项目更新活跃，最新参数以官方 GitHub 文档为准。

延伸阅读

• llama.cpp 官方仓库（ggml-org）：https://github.com/ggml-org/llama.cpp
• llama.cpp 安装文档（install.md）：https://github.com/ggml-org/llama.cpp/blob/master/docs/install.md
• llama.cpp 编译文档（build.md）：https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md
• Qwen 官方 llama.cpp 接入指南：https://qwen.readthedocs.io/zh-cn/latest/run_locally/llama.cpp.html