llama.cpp 量化 命令行

本地部署时，拉下来的权重动辄几十 GB，直接跑显存吃不消，得先用自己的机器量化一遍。但真到敲命令那一步，convert 脚本在哪个目录、量化工具吃的是什么格式、参数里那一串档位怎么选，很容易卡住。这篇按实际执行顺序给一套命令行流程，每步说明要检查什么、失败了往哪查，最后给一份参数与排查对照。

本地跑模型，拉下来的权重通常是几十 GB 的原始格式，直接加载对显存和内存都不友好，一般要先用 llama.cpp 自带的工具链量化一遍。但真到敲命令那一步，很容易卡：转换脚本和量化可执行文件不在一个目录、量化工具不认原始权重、参数里那串档位不知道该挑哪个。

下面按实际执行顺序走一遍：先把环境和目录理顺，再转 GGUF，然后选档位量化，最后跑起来验证，末尾给一份参数与报错对照。每一步都说清「做什么、怎么确认做对了、失败往哪查」，你照着敲就行。

动手前先把环境和目录理顺

这一步最容易被跳过，但也最容易在这里返工。先搞清楚手里的权重是什么状态：如果已经是 GGUF 且带量化后缀，那它就已经量化过了，直接跳到验证环节，别再做一遍转换。只有原始权重（HF 格式那种带配置文件、分词器、权重分片的目录）才需要走完整流程。

1. 确认权重形态看目录里有没有 config、tokenizer 这类文件和多个权重分片：有就是原始权重，需要转换；只有一个 .gguf 文件就是已经处理过的，跳过转换。
2. 在构建目录里找两个工具转换脚本和量化可执行文件不在同一层目录，先在构建目录里用 find 或列目录的方式确认它们各自的真实路径，别凭记忆拼相对路径。
3. 列一遍原始目录文件转换要求目录完整，配置文件、分词器文件、权重分片缺一个都会在中途报错，先列出来目测一遍。
4. 留够磁盘空间转换出的未量化 GGUF 再加上多份量化产物，通常比原始权重更占地方，先看一眼剩余空间。

第一步：把原始权重转成 GGUF

转换的核心就两个参数：原始权重目录、输出文件路径，再加一个输出精度类型。这里输出的应该是未量化的高精度 GGUF，给后面的量化留足余量，不要在这一步就压得太狠。

# 示意：路径按你机器上的实际位置替换
python /path/to/build/convert_hf_to_gguf.py \
  /path/to/original-model-dir \
  --outfile /path/to/model-f16.gguf \
  --outtype f16

权重是多分片的话脚本会自动合并，不用手动拼。转完先确认文件真的生成、体积合理，再往下走；如果这一步出来的东西就不对，量化阶段只会把错误放大，查起来更麻烦。

• 报「不认识的架构」：先怀疑工具版本太旧，跟模型架构对不上，而不是权重文件坏了。
• 报缺文件：回头核对原始目录，配置文件或某个分片没下载全。
• 转换跑完但文件异常小：大概率是权重分片缺失，脚本只处理了部分。
• 同一模型换脚本版本后表现不同：说明架构支持在变，固定用一套能跑通的工具版本做基线。

第二步：quantize 的参数怎么定

量化工具吃的是上一步产出的 GGUF，吐出的还是 GGUF，输入输出都是同一个扩展名。这里最容易犯的错是拿原始权重直接喂给量化工具，它不认 HF 目录，只会报格式不对。

档位怎么选没有万能答案：几 bit 一档的方案和带 K 的混合精度方案，在质量损失和体积上的取舍不一样，还跟你的卡容量、模型规模有关。具体每个档位在你那种配置下的大致情况，到 /models/deploy 按你的硬件和模型规模算一遍再定，数字以那个页面当时展示的为准。

# 示意：输入是上一步的 GGUF，输出换个带档位后缀的名字
/path/to/build/llama-quantize \
  /path/to/model-f16.gguf \
  /path/to/model-q4.gguf \
  Q4_K_M

第三步：跑起来验证，别只看文件大小

量化产物体积对了不代表能用。先用命令行直接加载量化后的文件，喂一段短输入，确认能正常出字，再考虑接到服务里。跳过这一步直接上服务，出问题时你分不清是量化坏了还是服务配置坏了。

1. 命令行直跑一次用 llama.cpp 自带的命令行工具加载量化文件，给一句短问题，看是否正常输出，确认加载本身没问题。
2. 和原模型对答案同一组问题分别问原模型和量化模型，重点看长回答会不会中途跑偏、格式崩不崩，这比看文件大小更能反映质量。
3. 按显存决定卸载层数显存吃紧时把部分层放到 CPU，会明显影响速度。卸载多少层要按你的显卡容量算，到 /models/deploy 做测算，别拍脑袋。
4. 测一次出字速度留一个速度基线，以后换档位或换机器时拿来对比，测法参照 /tools/speed-test 的说明，保证前后口径一致。

常见报错与排查顺序

报错按阶段判断最省时间：转换阶段的问题基本在权重或工具版本，量化阶段的问题基本在输入格式或磁盘，加载和运行阶段的问题则回到档位和精度上找。下面这张表按阶段给排查顺序。

有一点要提醒：这套流程适用于从原始权重开始自建量化，如果你本来就只需要跑别人做好的量化文件，转换和量化这两步都可以跳过，直接从验证环节开始。另外显卡显存够大、直接用未量化版本也能跑起来的情况下，不必为了省空间强行量化，质量优先时这条流程并不适用。

先确认手里是什么文件，再决定走几步；每个阶段只查自己那几项，别把错误叠在一起。