上一篇文章聊硬件，这一篇回到软件侧的起点。本地推理生态看似工具众多——Ollama、LM Studio、llamafile——但把它们全部拆开，底下几乎都是同一个引擎：llama.cpp。不理解它，就只能停在"装个 App 点按钮"的层面；理解了它，显存怎么算、量化怎么选、服务怎么起，全都透明。
本文是《本地大模型部署实战》系列第 3 篇，手把手走完一条完整链路：从源码编译（或下载预编译包）开始，下载第一个 GGUF 模型，用 llama-cli 跑通推理，再用 llama-server 起一个 OpenAI 兼容的本地 API，最后解剖 GGUF 格式、讲清量化档位选择与 GPU 卸载参数。
1、llama.cpp 概述
llama.cpp 是 Georgi Gerganov 在 2023 年 3 月发起的项目，起点只有一个目标：让 LLaMA 7B 跑在一台 MacBook 的 CPU 上。三年多过去，它成了整个本地推理生态的地基，仓库也迁到了 ggml-org 组织下，Ollama、LM Studio 等工具都直接复用它的推理核心。
它的设计哲学用三个选择概括。第一，纯 C/C++、零运行时依赖：不依赖 Python、不依赖 PyTorch，编译产物是几个 MB 的静态二进制，拷到任何机器就能跑。PyTorch 栈则是 GB 级的环境外加 CUDA、cuDNN 的版本地狱，这在"我只想在旧笔记本上跑个 7B"的场景里完全是杀鸡用牛刀。第二，CPU 优先、GPU 可选：核心算子用手写 SIMD（x86 的 AVX、Arm 的 NEON）直接吃满 CPU，GPU 后端（CUDA、Vulkan、Metal、SYCL）以可插拔方式叠加，同一份代码从树莓派覆盖到 H100。第三，GGUF 单文件：模型权重、分词器、配置元数据全在一个文件里，没有散落的 checkpoint 目录，这点第 5 节细讲。
顺带纠正一个历史遗留认知：2024 年 6 月的 PR #7809 之后，二进制统一加了 llama- 前缀——旧的 main 现在叫 llama-cli，旧的 server 叫 llama-server。网上老教程里的 ./main 已经过时。
2、安装与构建
拿到 llama.cpp 有两条路：源码编译和官方预编译包。前者灵活可控，后者五分钟见效。
2.1、源码编译
源码编译只需要 CMake 和一套编译器（Linux 的 gcc/clang、macOS 的 Xcode CLT、Windows 的 Visual Studio Build Tools），官方构建文档给的标准流程如下。
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release -j 8
第一条 cmake -B build 在 build/ 目录生成构建配置，第二条执行编译，-j 8 指定 8 路并行（按自己的 CPU 核数调）。编译产物全部落在 build/bin/ 下，包括本文要用的 llama-cli 和 llama-server，Windows 上则多一层 build/bin/Release/。
要开 NVIDIA GPU 加速，只需在配置阶段多加一个开关。
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j 8
-DGGML_CUDA=ON 会启用 CUDA 后端，前提是装好了 CUDA Toolkit。Vulkan 后端同理，换成 -DGGML_VULKAN=ON，对 AMD 和 Intel 显卡兼容性更好。
2.2、预编译包下载
不想装编译器，直接去 Releases 页面下载预编译包。每个版本以 b 加四位数字编号（如 b7000），资产按平台和加速后端分包：Windows x64 有 CPU、Vulkan、CUDA 12、CUDA 13 几种变体，Linux 有 Ubuntu x64 的 CUDA 12 包，macOS 有 universal 的 Metal 包。
选包原则很简单：有 N 卡选对应 CUDA 版本（注意本机驱动支持的 CUDA 大版本），A 卡或核显选 Vulkan 版，都不确定就先拿 CPU 版验证流程。解压即用，里面的二进制与源码编译完全一致。唯一代价是版本由官方决定，需要特殊编译选项（比如自定义 GGML_CUDA_F16）时仍得走源码。
3、跑通第一个模型
llama.cpp 只认 GGUF 格式，第一步是去 HuggingFace 下载模型。识别方法：仓库文件列表里全是 .gguf 文件的是量化仓库，能直接用；是 .safetensors 或分片 checkpoint 的是原版权重仓库，llama.cpp 加载不了。可靠的量化发布者有模型官方（如 Qwen、DeepSeek 官方仓库自带 GGUF 版）、bartowski、unsloth、lmstudio-community。
以通义千问的官方量化仓库 Qwen/Qwen3-8B-GGUF 为例，用官方 CLI 下载单个文件。
pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-8B-GGUF \
Qwen3-8B-Q4_K_M.gguf --local-dir models
文件名自带量化档位信息（第 6 节详解），这里选的是 Q4_K_M 档，约 5.0 GB。下载完成后用 llama-cli 直接推理。
./build/bin/llama-cli -m models/Qwen3-8B-Q4_K_M.gguf \
-p "用一句话解释什么是模型量化" -n 256 -t 8
-m 指定模型文件，-p 是提示词，-n 256 限制最多生成 256 个 token，-t 8 用 8 个 CPU 线程。首次运行会先输出一段加载日志，摘录如下。
llama_model_loader: - kv 0: general.architecture str = qwen3
llm_load_print_meta: format = GGUF V3 (spec version 3.0)
llm_load_print_meta: model params = 8.22 B
llama_new_context_with_model: n_ctx = 4096
日志能读出三件事：模型架构是 qwen3、文件格式是 GGUF V3、上下文窗口默认 4096。随后 CPU 开始逐 token 生成，速度取决于机器，纯 CPU 跑 8B 的 Q4 模型在主流台式机上一般有每秒十几个 token 的体感。看到答案逐字吐出来，这条链路就算通了。
4、启动本地 API 服务
命令行交互只是验证，真正的用法是把模型变成服务。llama-server 内置一个纯 C/C++ 的 HTTP 服务器，暴露 OpenAI 兼容接口，/v1/chat/completions、/v1/embeddings 等端点齐全，还自带一个网页聊天界面。
启动命令如下。
./build/bin/llama-server -m models/Qwen3-8B-Q4_K_M.gguf \
--host 127.0.0.1 --port 8080
--host 绑定地址，只在本机用就保持 127.0.0.1，要让局域网其他设备调用才改 0.0.0.0。这里显式传了 --port 8080，不是多余的：从 2026 年 10 月的 v0.7.0 起，llama-server 默认端口从沿用三年的 8080 改成了 9931（Docker 镜像内部仍是 8080），网上大量旧教程写的 8080 会直接连不上。显式指定端口是最稳的习惯。
服务起来后用 curl 走一遍 chat 接口。
curl http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"qwen3-8b","messages":[
{"role":"user","content":"一句话介绍你自己"}]}'
请求体结构与 OpenAI 官方 API 完全一致，model 字段随便填（单模型服务不校验），messages 是对话数组。响应也是标准形状。
{
"choices": [
{
"message": {
"role": "assistant",
"content": "我是通义千问……"
},
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 14, "completion_tokens": 52 }
}
拿到这个响应，意味着任何 OpenAI SDK、任何支持自定义 base URL 的客户端（Cursor、各类 ChatBox、LangChain）都能指向 http://127.0.0.1:8080/v1 直接使用本地模型，业务代码一行不用改。
5、GGUF 格式解剖
GGUF（GPT-Generated Unified Format）是 llama.cpp 配套的模型容器格式，由老 GGML 格式演化而来。它的核心主张就一条：一个文件装下推理需要的一切。
具体说，一个 GGUF 文件里装了三层内容。最上层是元数据，一组键值对：general.architecture 声明架构（qwen3、llama、qwen2vl），qwen3.context_length 记录上下文长度，还有分词器词表和 tokenizer.chat_template 对话模板。中层是张量信息表，每个权重张量的名字、形状、类型、偏移。最底层是权重数据本体，量化和全精度张量可以混放。
理解了"自包含"，就理解了它对分发的友好。对比 PyTorch 生态一个模型七八个文件（config.json、tokenizer.json、若干 safetensors 分片）加一个特定版本的 Python 环境，GGUF 是单文件、自描述、免环境的：拷给同事就能跑，放 U 盘就能带走，支持 mmap 后加载不读全内存，同一份文件在 CPU、CUDA、Metal、Vulkan 后端通吃。想看一个模型文件里到底有什么，仓库自带的 gguf_dump.py 脚本能把所有键值对和张量表打印出来，排查分词器、对话模板问题时的第一工具。
6、量化档位选择
量化是把权重从 16 bit 压到更低位宽以换体积和速度的技术。GGUF 的命名体系要会读：Q4_K_M 表示 4 bit 量化的 K-quant 变体、中等强度；K 系列是混合精度方案，对注意力等敏感层保留更高精度，后缀 S/M/L 表示重要层精度的档位；Q8_0 这类无后缀的是老式块量化；还有 IQ 系列（如 IQ4_XS）用重要性矩阵进一步压体积。档位间的差距用困惑度（perplexity，PPL）衡量——模型对文本的"意外程度"，越低越好，官方讨论区维护着各档位的困惑度对照。
以 8B 模型为例，常用档位对照如下（体积以 Qwen3-8B 实测为参考，质量体感为定性结论）。
| 档位 | 平均位宽 | 8B 体积 | 质量体感 | 建议 |
|---|---|---|---|---|
Q2_K |
~3.4 bpw | ≈3.2 GB | 明显劣化 | 仅极限救急 |
Q3_K_M |
~3.9 bpw | ≈3.8 GB | 可感知下降 | 低配设备 |
Q4_K_S |
~4.6 bpw | ≈4.7 GB | 轻微 | 极限省显存 |
Q4_K_M |
~4.8 bpw | ≈5.0 GB | 几乎无感 | 默认甜区 |
Q5_K_M |
~5.7 bpw | ≈5.9 GB | 更贴近原版 | 显存富余时 |
Q6_K |
~6.6 bpw | ≈6.7 GB | 接近无损 | 追求质量 |
Q8_0 |
~8.5 bpw | ≈8.7 GB | 近乎无损 | 基准与存档 |
选择建议一句话版本：没把握就用 Q4_K_M。它相对全精度的困惑度上升通常在百分之一二量级，日常对话、代码、摘要几乎无感，体积却砍到三分之一。显存富裕就上 Q5_K_M 或 Q6_K，属于花钱买安心；做评测基准、跑对比实验、留长期存档用 Q8_0，它接近无损且到处都有发布。Q3 以下只在老设备跑不动时的最后手段，知识性任务已经能问出退化。
注意：困惑度是统计量，小模型比大模型对量化更敏感——同为 Q4_K_M，70B 的体感损失远小于 3B。
另外，仓库里只发布了原版权重时，可以用 llama-quantize 自己从 fp16 GGUF 压出任意档位，命令行一条，流程在后续篇章展开。
7、GPU 加速卸载
纯 CPU 能跑但慢，有显卡就该开 GPU 卸载。llama.cpp 把模型切成一层层的 transformer 块，-ngl 参数指定把多少层搬进显存，这是开关 GPU 的唯一入口。
完整卸载的启动命令如下。
./build/bin/llama-server -m models/Qwen3-8B-Q4_K_M.gguf \
-ngl 99 --port 8080 -c 8192
-ngl 99 是惯用写法，意思是"层总数肯定不到 99，全搬进去"。Qwen3-8B 共 36 层，全卸载约需 5 GB 显存放权重（8B 的 Q4_K_M 文件大小），再加 KV 缓存。显存不够时就做部分卸载：先 -ngl 0 全 CPU 跑基准，再逐步加到 -ngl 20、-ngl 28，观察启动日志里的 offloaded X/36 layers，直到显存用满。混合模式比纯 CPU 快、比全卸载慢，速度随卸载层数近似线性过渡。
两个相关的账要会算。权重吃显存的大头，但上下文长度也吃：-c 每翻倍，KV 缓存占用也近似翻倍，8B 模型 32k 上下文的 KV 缓存能到 2 GB 上下。另外日志里如果显示 offloaded 0/36 layers 而你明明有 N 卡，说明编译时没开对应后端，回第 2 节用 -DGGML_CUDA=ON 重新编译。
8、常见坑盘点
下载了不带对话模板的模型。症状是 llama-cli 一问一答正常，模型却自言自语、复读问题。原因是拿到了 base（基座）版 GGUF——它没内嵌 tokenizer.chat_template，不会按对话格式组织输入。解法：认准文件名带 Instruct 或本身就是对话模型的仓库，Qwen3 这类对话模型官方 GGUF 自带模板。用 gguf_dump.py 查一下元数据最快。
分片文件没下全。部分仓库把大档位拆成 model-00001-of-00002.gguf 这样的分片，llama.cpp 支持加载，但一片都不能少。报错通常是张量校验失败或文件尾缺失，把同目录所有分片补齐即可。
线程数设错。默认 -t 取逻辑核数，但超线程对推理吞吐常常是负贡献。8 核 16 线程的机器，-t 8（物理核数）往往比 -t 16 更快，拿不准就在两个值之间实测，差距能有 20% 上下。
上下文用了默认值还不自知。llama-server 默认上下文 4096，喂长文档时输入被静默截断，模型"看不全"还以为它笨。长文场景显式加 -c 16384 之类，同时记住第 7 节的账：上下文翻倍，KV 缓存也翻倍。再叠加端口变更（8080 改 9931）这一个，就是新手最常撞的四堵墙，撞之前读日志、撞之后查元数据，基本都能自诊。
9、总结与练习
本文走完了本地推理的地基链路：llama.cpp 以纯 C/C++、零依赖、CPU 优先的设计成为生态底座；源码编译与预编译包二选一起步；llama-cli 验证推理，llama-server 把模型变成 OpenAI 兼容服务；GGUF 单文件自包含权重、分词器与元数据；量化默认选 Q4_K_M，追求质量上 Q5/Q6，基准存档用 Q8_0；-ngl 控制层卸载，显存不够就部分卸载。
留一个体感练习：从 Qwen 官方仓库分别下载 Qwen3-8B-Q4_K_M.gguf（5.0 GB）与 Qwen3-8B-Q8_0.gguf（8.7 GB），用同一组问题各问十次——一道数学题、一段代码生成、一篇长摘要，对比二者的正确率与文字质感差距是否配得上 3.7 GB 的体积差。做完这个实验，你对"量化损失"的判断就从传闻变成了体感，也为下一篇讲 Ollama（它就是 llama.cpp 加了一层模型管理壳）打好了地基。对于想长期在本地跑模型的工程师，建议先把本文的 llama-server 加 GPU 卸载流程跑熟，它是不依赖任何上层工具的最小可用方案。
