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_CUDAon层数越靠 GPU 越快显存要够磁盘工具 模型放非 C 盘如D:\llama.cpp、D:\models7B Q4_K_M 约 4-5 GB网络能访问 GitHub或镜像站即可国内直连 GitHub 不稳见 3.1编译链仅 Linux 自编git cmake C/C 编译器apt install build-essential cmake gitUbuntu显存口径与《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.cppWindowsReleases 免编译打开仓库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.cppLinuxgit clone cmakeCPU 版两行命令先配置、再编译Release 开优化git clone https://github.com/ggerganov/llama.cpp cd llama.cpp cmake -B build cmake --build build --config ReleaseN 卡 GPU 版编译时加 CUDA 开关cmake -B build -DGGML_CUDAon 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例如set HF_ENDPOINThttps://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:: 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-serverOpenAI 兼容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文件名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\:\你好\}]}预期返回 JSONchoices[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 GBQ8_0 近无损7B 约 7-8 GB显存够且要质量就选它Q2/Q3 会明显掉智商输出重复、变笨除非机器很弱否则别用。需要自己量化时仓库自带的llama-quantize工具可以从已有权重生成目标量化档的.ggufQ4_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 看日志的习惯一致。六、故障排查按层定位#症状报错原文层原因解决1git clone极慢/失败GitHub网络国内访问 GitHub 不稳用镜像站/代理或直接下 Releases 压缩包Windows 首选中断重跑2HuggingFace 下载卡住 / ConnectionError / 超时网络国内直连 huggingface.co 受限set HF_ENDPOINThttps://hf-mirror.comWin/export HF_ENDPOINThttps://hf-mirror.comLinux或改 ModelScope / wget-c续传见《AI-06》3CUDA error: out of memory显存模型/上下文/卸载层数超出显存调小-ngl让 CPU 兜底、降上下文、换 Q4_K_M 更低档位nvidia-smi查显存占用4CUDA error: no kernel image is available for execution on the device框架/CUDA编译所用 CUDA 版本与显卡架构不匹配如太新的 CUDA 编译 老卡换与显卡架构匹配的预编译包或用匹配的 CUDA 重新编译-DGGML_CUDAon5模型加载成功但输出乱码/重复量化量化位宽过低Q2/Q3或 tokenizer 不匹配升量化位宽Q4_K_M 起确认权重与 tokenizer 来自同一 repo6port 8080 already in use端口8080 被其他程序占用换端口--port 8081Windowsnetstat -ano | findstr :8080/ Linuxlsof -i:8080找占用进程7Linux 编译报错缺 cmake/编译器环境编译工具链不全sudo apt install build-essential cmake git后重跑 cmake 两行命令七、本篇自检清单能说出 llama.cpp 与 Ollama/LMStudio 的关系后者底层即 llama.cpp 系本篇是裸引擎能说出 GGUF 的结构量化权重 配置一体的单文件格式CPU/GPU 混合推理友好Windows 下会拿 GitHub Releases .zipllama-cli/llama-serverLinux 下会cmake -B build cmake --build build --config ReleaseGPU 加-DGGML_CUDAon跑通llama-cli -m model.gguf -p 你好输出通顺起过llama-server -m model.gguf --port 8080curl/v1/chat/completions拿到 JSON会用llama-bench -m model.gguf测 tokens/s 并知道量级参考能讲清量化档位Q4_K_M 甜点 / Q8_0 近无损 / Q2、Q3 掉智商且会按显存选工具与模型都在非 C 盘了解-ngl层数与显存的权衡