llama.cpp 量化部署

很多人第一次用 llama.cpp，卡在两个地方：手里只有 Hugging Face 上的原始权重，不知道怎么变成能跑的量化文件；量化出来了，又不知道该选哪一档、该开几层到显卡。这篇按「装环境—转换—量化—跑起来—调参数—排查」的顺序走一遍，每一步给判断标准和动作，不承诺具体速度，数字都让你自己在站内页面核对。

很多人第一次用 llama.cpp，卡在两个地方：手里只有 Hugging Face 上的原始权重，不知道怎么变成能跑的量化文件；量化出来了，又不知道该选哪一档、该开几层到显卡。这篇按「装环境—转换—量化—跑起来—调参数—排查」的顺序走一遍，每一步给判断标准和动作。

不承诺具体速度，也不给死数字。速度、体积、档位命名这些都跟硬件和版本强相关，你到站内页面核对当时的数据比自己记一个数靠谱得多。先把流程走通，再谈调优。

先搞清 llama.cpp 在链路里的位置

llama.cpp 是一个用 C/C++ 写的推理引擎，核心价值是纯 CPU 也能跑、量化支持细、依赖少，适合笔记本、小主机、单卡机器这类资源有限的场景。它不做训练也不做微调，只负责把已经量化好的权重加载进来跑推理；权重格式是它自家生态的 GGUF，别的格式要先转。

和 Ollama、LM Studio 那种一体化工具的差别在于：llama.cpp 把转换、量化、参数全部摊在你面前，可控但步骤多。只想开箱即用的话，站内已有文章对比过这几条路线，去那边看路线选择，这篇只讲 llama.cpp 这一条。

装环境：编译还是下预编译包

优先下官方 Release 里的预编译包，省掉编译时间；只有要用新硬件后端或改代码时才自己编。编译本身不难，难的是后端选错——编错后端的结果是能跑但全走 CPU，慢到你会以为模型有问题。

1. 下包并解压从官方 Release 取对应平台和对应后端的包，解压到固定目录，别放在会被清理的临时路径。
2. 冒烟测试拿一个很小的模型跑一次，看到连续生成文字才算装好。只看编译通过不算，编译通过但后端没生效的情况很常见。
3. 记录环境信息把命令行打印的版本信息和后端信息留存一份，后面排查问题时能省掉一轮来回确认。

踩坑点：显卡驱动版本和后端版本对不上是最常见的启动失败原因，报错通常在加载阶段就出现。这类问题别去改模型参数，先把驱动和后端对齐。

把原始权重转成 GGUF

转换前先确认两件事：模型架构 llama.cpp 是否支持（不支持的架构转出来也加载不了），以及权重是不是已经合并过的完整权重（LoRA 适配器要先合并）。这两条不满足，后面做多少步都是白费。

1. 装 Python 侧依赖按仓库里的转换脚本要求装依赖，建议用独立虚拟环境，避免和机器上其他项目打架。
2. 执行转换把原始权重目录转成 GGUF 格式，得到一个接近全精度的大文件。转换过程中留意有没有告警，架构相关的告警不能忽略。
3. 带上分词器文件分词器文件要跟着一起转、一起带。缺了会出现加载成功但输出乱码这种迷惑现象，排查起来很绕。
4. 先跑全精度版转完先别急着量化，直接拿这个全精度版本跑一次，确认模型本身没问题。跳过这步，后面出问题你分不清是量化的锅还是转换的锅。

量化档位怎么挑，别只盯着最小的

量化本质是降低每个权重的表示精度来换体积和显存，代价是质量损失。损失大小跟模型参数量、量化方法、是否对关键层特殊处理都有关，不是一个固定值，所以别信「某个档位绝对无损」这种说法。

• 选档顺序：先按可用显存和内存定上限，再从能装下的档位里挑损失最小的那一档，而不是反过来先挑最小档位再想能不能跑。
• 小参数量模型对量化更敏感，大模型相对耐压。同一个档位用在不同规模的模型上，体感差别可能很大。
• 如果对输出质量要求高，宁愿换更小的模型配更高的量化档，也不要大模型配极限压缩档。
• 具体档位命名、体积对照和质量取舍，站内已有专门文章讲量化原理和档位选择，去那边核对当时的对照表，这里只讲怎么在你的机器上落到某一档。

落地动作很简单：把你的显存或内存总量、想跑的上下文长度、权重占用的估算填进站内的部署测算页面，让它按模型和量化档位算一遍。算完能装下哪些档位是确定的，剩下的就是从里面挑最好那一档。

跑起来：把层卸到显卡、把上下文调对

关键参数就三个方向：卸载到 GPU 的层数、上下文长度、并行线程数。层数决定多少计算在显卡上，上下文决定显存里要预留多少 KV 缓存，线程数影响纯 CPU 部分的效率。

1. 先设上下文长度按你实际要做的事设长度，别一上来拉满。要处理长文档就设长，只是日常问答就设短，设置值只对当前这次运行生效。
2. 再加 GPU 卸载层数从低位开始往上加，加到显存快满但不炸为止。每次只改这一个变量，出问题才知道是谁的锅。
3. 最后调线程数纯 CPU 场景下线程数一般设成物理核心数附近，超过之后收益递减甚至变慢，实测比照抄参数靠谱。
4. 需要对外提供接口时设监听默认只绑本机，局域网要用得显式改监听地址和端口。改完记得想清楚谁能访问，别顺手绑到所有网卡上。

KV 缓存的显存占用随上下文线性增长，长上下文场景下它可能比权重本身还占地方，这是很多人「模型能装下但一对话就爆」的原因。看到爆显存先想上下文，再想层数。

量出自己的基线，别问「快不快」

速度受模型规模、量化档位、硬件、上下文长度、是否走显卡共同影响，同一个模型在不同机器上差几倍很正常，别人报的数字对你不构成参考。你要的是自己这台机器的基线。

站内有接口测速工具可以先量出基线。跑完之后拿自己的基准去对比同一台机器上的前后变化，而不是拿网上的说法对比。什么情况下不用测：只是偶尔手动问几句、对等待不敏感，那设完参数能用就行，测速的收益很低。

跑不动、跑不对时的排查顺序

排查最忌讳东改一下西改一下。固定顺序能帮你少走弯路：先确认后端有没有生效（是不是偷偷全走 CPU）→ 再确认模型文件完整（量化中途中断会得到半截文件）→ 再看显存或内存是不是被 KV 缓存吃满 → 最后才怀疑量化档位不合适。

• 加载阶段报错：基本都是文件格式、架构支持或后端问题，先去看加载日志里那几行后端信息。
• 生成阶段报错或输出乱码：多半是分词器、上下文或参数问题，回头检查转换时有没有带全文件。
• 显存不够时的降级路径：先降上下文，再减卸载层数，再换更小的量化档位，最后才是换更小的模型。这个顺序对应影响从小到大。
• 速度突然腰斩：先看是不是有别的进程在占显卡，再看是不是上下文被设得比平时长很多。
• 如果本来是想跑多并发、给人共用的服务，先别在 llama.cpp 上硬调，回头看看自己的场景是不是选错了框架。

什么时候值得走这条路，什么时候不值得

值得：单机自用、显存紧张、想要细粒度控制、想在本地方便地换不同量化档位做对比。这些场景下 llama.cpp 的轻量和可控是真优势，你花在流程上的时间能从后续的灵活度里赚回来。

不值得：团队要共享一个稳定接口、要按并发扩容、要跑在已经有一套推理平台的集群上。这些场景的维护成本会盖过 llama.cpp 的轻量优势，换个自带服务化能力的方案更省事。

判断动作：先写清你的并发人数、单次对话长度、可接受等待时间，再回头到站内的部署测算页面按模型和量化档位算一遍，算完再决定要不要动手。算之前动手的人，往往会在量化档位这一步返工。