llama.cpp 与 GGUF 格式：本地大模型的"裸引擎"
本篇拆到"发动机"层：llama.cpp 是什么、GGUF 为什么成为本地模型的主流容器格式、Windows/Linux 怎么获取、llama-cli 怎么跑模型、llama-server 怎么起 OpenAI 兼容服务 。适合想搞懂底层、想榨性能、想把自己应用接到轻量级推理服务上的人。读完你会：拿到 llama.cpp 可执行文件、跑通第一个
.gguf模型、理解 Q4_K_M/Q8_0 量化档位、用 curl 调通 8080 端口的/v1/chat/completions。
一、为什么需要它
先建立定位：Ollama 和 LMStudio 底层就是 llama.cpp 系引擎，它们帮你打包好了模型管理、服务、界面；而直接用 llama.cpp，相当于开着没有挡位自动挡的"裸引擎"------少了一层封装，换来的是完全的控制权（GPU 层数、线程、编译选项）和最小的依赖。搞清楚它，等于把整个本地推理栈的地基打牢：Ollama 报的错、LMStudio 的参数，追到底都是这一层的行为。
GGUF 是理解 llama.cpp 的钥匙 。它是 GGML 的统一文件格式，把一个 .gguf 文件做成"量化权重 + 模型配置"一体的单文件容器：文件里既有量化后的张量数据，也有模型结构、量化档位等元信息，对 CPU/GPU 混合推理特别友好。这也是为什么现在社区量化模型几乎清一色以 .gguf 发布------Ollama 的模型、LMStudio 的 Model Finder、各种 GGUF 镜像站，本质都是这个格式。你从《AI-06》下到的 qwen2.5-7b-instruct-q4_k_m.gguf，就是 Ollama、LMStudio、llama.cpp 三家都能直接加载的同一份文件。格式统一带来的"一套权重、多处能用"，已经是本地生态的默认预期：换工具不用重新下载模型，这也是 GGUF 能一统本地量化模型市场的关键原因。
搜索词"llama.cpp 编译""GGUF 是什么""Q4_K_M 什么量化"指向的其实是同一件事：本地跑模型，为什么大家都用这套 C/C++ 引擎 + GGUF 格式 ？答案是性能与格式的平衡：纯 C/C++ 实现、不依赖重型框架、量化推理成熟，是 CPU/GPU 混合推理的事实标准（仓库 ggerganov/llama.cpp）。
"纯 C/C++"意味着什么：没有 Python 环境、没有 pip install、没有框架依赖，解压出来的 exe 直接就能跑（Windows）。这带来两个直接好处：一是体小、启动快，单文件起服务，适合"把本地模型嵌进自己小工具"的场景；二是可移植------整个目录拷到另一台没有 Python 的电脑上照样能用。对 Ollama/LMStudio 这类"整机"方案，你得到的是便利；对 llama.cpp，你得到的是控制权，两者不冲突，模型文件还通用。
二、环境要求
| 项目 | 要求 | 说明 |
|---|---|---|
| 系统 | Windows（用现成 exe）或 Linux（可自行编译） | 本篇两条路都讲 |
| CPU | 任意现代 x86/ARM 均可 | 无 N 卡也能纯 CPU 跑，速度降档 |
| GPU | 可选。N 卡 + 对应编译选项（GPU 版加 -DGGML_CUDA=on） |
层数越靠 GPU 越快，显存要够 |
| 磁盘 | 工具 + 模型放非 C 盘 （如 D:\llama.cpp、D:\models） |
7B Q4_K_M 约 4-5 GB |
| 网络 | 能访问 GitHub（或镜像站）即可 | 国内直连 GitHub 不稳，见 3.1 |
| 编译链（仅 Linux 自编） | git + cmake + C/C++ 编译器 | apt install build-essential cmake git（Ubuntu） |
显存口径与《AI-05》一致：7B 级 fp16 权重约 14-15 GB，量化后 Q8_0 约 7-8 GB、Q4_K_M 约 4-5 GB 。8 GB 显存跑 7B Q4_K_M 很舒适；想跑 32B Q4（约 16-20 GB）就需要 24 GB 卡或 CPU/GPU 混合（-ngl 控制，见第五节）。
三、安装与部署
3.1 获取 llama.cpp（Windows：Releases 免编译）
- 打开仓库
github.com/ggerganov/llama.cpp的 Releases 页，下载最新的 Windows.zip包（内含llama-cli、llama-server等 exe）； - 解压到非 C 盘，如
D:\llama.cpp，无需安装、无需 PATH（直接进目录运行，或把目录加进 PATH）。
国内网络提示：GitHub 直连时快时慢，git clone 极慢/失败时，用镜像站/代理，或直接下 Releases 压缩包（下载失败重跑即可，浏览器/下载工具带续传的更稳）。
3.2 获取 llama.cpp（Linux：git clone + cmake）
CPU 版（两行命令：先配置、再编译，Release 开优化）：
bash
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
cmake -B build && cmake --build build --config ReleaseN 卡 GPU 版（编译时加 CUDA 开关）：
css
cmake -B build -DGGML_CUDA=on && cmake --build build --config Release预期：编译结束，build/bin（或 build 目录下）出现 llama-cli、llama-server、llama-bench 等可执行文件。编译报错多数是缺工具链：Ubuntu 先 apt install build-essential cmake git。
3.3 准备模型（任意 .gguf，复用 AI-06 成果）
用《AI-06 模型下载全攻略》的任一方案下好一个 GGUF 到 D:\models，例如：
arduino
set HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF --include "qwen2.5-7b-instruct-q4_k_m.gguf" --local-dir D:\models（或 ModelScope / 直链 wget -c，命令见 AI-06。）单个 .gguf 即完整可加载的模型。
3.4 跑模型：llama-cli
bash
:: Windows（在 D:\llama.cpp 下）
llama-cli -m D:\models\qwen2.5-7b-instruct-q4_k_m.gguf -p "你好"
:: Linux（自编版，模型放 ~/models）
./build/bin/llama-cli -m ~/models/qwen2.5-7b-instruct-q4_k_m.gguf -p "你好"-m 指模型文件，-p 给提示词。预期：先打印模型权重加载进度，随后输出通顺回答。首次加载时若你有 N 卡且用的是 GPU 版，权重层会自动进显存（层数可手动控制，见第五节）。输出之后是停在终端里继续对话，还是回答完直接退出，因版本而异------以终端提示和 llama-cli --help 的输出为准。脚本化使用时，常见做法就是用 -p 传一次性问题，把输出重定向给后面的程序处理。
3.5 起服务：llama-server（OpenAI 兼容）
lua
llama-server -m D:\models\qwen2.5-7b-instruct-q4_k_m.gguf --port 8080启动后默认监听 8080 端口，进程里会打印监听地址；浏览器打开 http://localhost:8080 能看到内置 Web 界面，同时对外提供 OpenAI 兼容 的 /v1/chat/completions 接口。用 curl 验证（model 字段填你的 .gguf 文件名）：
sql
curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\":\"qwen2.5-7b-instruct-q4_k_m.gguf\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}"预期：返回 JSON，choices[0].message.content 为正常回答。这个接口和 Ollama 的 OpenAI 兼容端点（localhost:11434/v1）、和云端 OpenAI 的形状一致，差别只在 base_url 和 model 名------Cherry Studio、OpenWebUI、OpenAI SDK 把 base_url 填 http://localhost:8080/v1 就能直接用，应用代码一行不用改。另外 http://localhost:8080 本身还带一个 Web 聊天页，正式接第三方之前可以先在浏览器里快速试问两句。
四、验证
- llama-cli 跑通 ：
-p "你好"输出通顺中文，不重复不乱码；乱码/重复先怀疑量化过低或文件不完整（见第六节）； - llama-bench 测速 ：
llama-bench -m D:\models\qwen2.5-7b-instruct-q4_k_m.gguf，输出 tokens/s 基准------量级参考：GPU 上 7B Q4 应明显高于个位数 tokens/s，纯 CPU 通常是每 token 一秒上下，具体数值随硬件差异很大； - 服务连通 ：
curl http://localhost:8080/v1/chat/completions（命令见 3.5）能拿到 JSON 回答，浏览器http://localhost:8080能打开。
三项都过，裸引擎这条线就验收合格，可以接自己的应用。
一个习惯：把 llama-bench 的输出（pp/tg tokens/s）连同硬件型号、模型档位、-ngl 层数记一行到笔记里。以后换量化档位、调 -ngl 层数、升级驱动之后重测同一行，就能判断"这次调整到底有没有收益"------没有基线记录，调优就只能靠感觉（方法口径见《AI-29 推理性能调优》）。
五、进阶技巧
- 量化档位怎么选（§5.10 口径） ：GGUF 家族常见
Q2_K / Q3_K_M / Q4_K_M / Q5_K_M / Q6_K / Q8_0。Q4_K_M 是"精度-体积"甜点 ，默认推荐，7B 约 4-5 GB；Q8_0 近无损 ，7B 约 7-8 GB，显存够且要质量就选它；Q2/Q3 会明显掉智商 （输出重复、变笨），除非机器很弱否则别用。需要自己量化时，仓库自带的llama-quantize工具可以从已有权重生成目标量化档的.gguf，Q4_K_M为默认推荐档，按磁盘与显存余量再选更低/更高档。 - CPU/GPU 混合推理（-ngl 层数） ：大模型可以只把部分层放到 GPU、其余留在 CPU 内存里跑，
-ngl指定卸载到 GPU 的层数------层数越多越快，但显存占用越高；显存不够就把-ngl调小，用 CPU 内存兜底。实操顺序：先按"全部层进 GPU"试，报显存不足再往下调，直到"装得下且速度可接受"为止。没有 N 卡的纯 CPU 机器不用关心这个参数------所有层走 CPU，速度主要看物理核心数和模型大小，7B Q4_K_M 大概能维持"每 token 一秒"上下，轻体验够用。其余参数（线程数、上下文长度等）建议直接看llama-cli --help/llama-server --help，以工具当前版本输出为准。 - 和 Ollama 的关系 ：Ollama 底层即 llama.cpp 系，模型同为 GGUF。选法很简单：要省心、多模型管理、局域网共享 → Ollama （详见《AI-07 Ollama本地部署大模型》）；要精细控制（-ngl、线程、自编 GPU 优化、嵌入自己项目）→ llama.cpp 本篇路线；两者模型文件直接复用，不冲突。
- 目录纪律 ：exe 放
D:\llama.cpp、模型放D:\models，与 Ollama 的OLLAMA_MODELS、LMStudio 模型目录统一思路------大文件一律非 C 盘 SSD。跑服务时给 llama-server 的日志留个终端窗口（或重定向到文件），排错时第一手信息都在启动日志里，和 Ollama 看日志的习惯一致。
六、故障排查（按层定位）
| # | 症状（报错原文） | 层 | 原因 | 解决 |
|---|---|---|---|---|
| 1 | git clone 极慢/失败（GitHub） |
网络 | 国内访问 GitHub 不稳 | 用镜像站/代理，或直接下 Releases 压缩包（Windows 首选）；中断重跑 |
| 2 | HuggingFace 下载卡住 / ConnectionError / 超时 |
网络 | 国内直连 huggingface.co 受限 | set HF_ENDPOINT=https://hf-mirror.com（Win）/ export HF_ENDPOINT=https://hf-mirror.com（Linux）；或改 ModelScope / wget -c 续传（见《AI-06》） |
| 3 | CUDA error: out of memory |
显存 | 模型/上下文/卸载层数超出显存 | 调小 -ngl 让 CPU 兜底、降上下文、换 Q4_K_M 更低档位；nvidia-smi 查显存占用 |
| 4 | CUDA error: no kernel image is available for execution on the device |
框架/CUDA | 编译所用 CUDA 版本与显卡架构不匹配（如太新的 CUDA 编译 + 老卡） | 换与显卡架构匹配的预编译包，或用匹配的 CUDA 重新编译（-DGGML_CUDA=on） |
| 5 | 模型加载成功但输出乱码/重复 | 量化 | 量化位宽过低（Q2/Q3）或 tokenizer 不匹配 | 升量化位宽（Q4_K_M 起）；确认权重与 tokenizer 来自同一 repo |
| 6 | port 8080 already in use |
端口 | 8080 被其他程序占用 | 换端口（--port 8081）；Windows `netstat -ano |
| 7 | Linux 编译报错（缺 cmake/编译器） | 环境 | 编译工具链不全 | sudo apt install build-essential cmake git 后重跑 cmake 两行命令 |
七、本篇自检清单
- 能说出 llama.cpp 与 Ollama/LMStudio 的关系：后者底层即 llama.cpp 系，本篇是"裸引擎"
- 能说出 GGUF 的结构：量化权重 + 配置一体的单文件格式，CPU/GPU 混合推理友好
- Windows 下会拿 GitHub Releases .zip（llama-cli/llama-server），Linux 下会
cmake -B build && cmake --build build --config Release（GPU 加-DGGML_CUDA=on） - 跑通
llama-cli -m model.gguf -p "你好"，输出通顺 - 起过
llama-server -m model.gguf --port 8080，curl/v1/chat/completions拿到 JSON - 会用
llama-bench -m model.gguf测 tokens/s 并知道量级参考 - 能讲清量化档位：Q4_K_M 甜点 / Q8_0 近无损 / Q2、Q3 掉智商，且会按显存选
- 工具与模型都在非 C 盘，了解
-ngl层数与显存的权衡