ik_llama.cpp 量化实战解析 --pure 模式下张量行大小对齐与 fallback 量化机制PR #294【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp导读本文围绕 ik_llama.cpp 仓库中的 Pull Request #294「Make sure tensor row size is multiple of block size also when quantizing with --pure」展开深入讲解llama-quantize工具在--pure模式下遇到的张量行大小不是量化块大小整数倍问题及其修复方案。读完本文你将理解 K-quant/IQ-quant 家族对张量形状的硬性约束、--pure与 k-quant 混合方案的本质区别以及当形状不满足约束时量化器如何自动回退到兼容类型从而避免崩溃并保证量化流程顺利完成。背景llama-quantize 的两种量化模式ik_llama.cpp 中的llama-quantize是模型量化的核心工具其完整用法定义在 examples/quantize/quantize.cpp./llama-quantize [--allow-requantize] [--leave-output-tensor] [--pure] models/llama/ggml-model.gguf [models/llama/ggml-model-quant.gguf] type [nthreads]其中--pure参数的官方说明是--pure: Disable k-quant mixtures and quantize all tensors to the same type禁用 k-quant 混合将所有张量量化为同一类型理解这一点至关重要--pure与默认方案的本质区别在于是否允许为不同张量量身定制量化类型。默认k-quant 混合方案量化器会调用 llama_tensor_get_type 函数根据张量名attn_q、attn_k、attn_v、ffn_gate、ffn_down、ffn_up等、所属层号、模型架构甚至重要性矩阵规则为每个张量挑选更优的量化类型。例如ffn_down可能用更低位类型而attn_v用更高位类型最终形成多种 k-quant 混合的量化模型。--pure模式跳过上述复杂的类型推导所有张量统一使用命令行指定的类型行为简单可预期适合追求全体同型的场景。从参数解析代码可以看到--pure只是把 params.pure 置为 true真正的分支逻辑位于量化主循环中。问题根源行大小必须能被量化块大小整除K-quant 与 IQ-quant 家族的量化是按块进行的一个块包含固定数量的元素。在 ik_llama.cpp 的 change_type_if_necessary 函数中可以看到绝大多数 k-quant/IQ-quant 类型Q2_K ~ Q6_K、IQ2_XS、IQ3_XXS、IQ1_S、IQ1_M、IQ2_K、IQ3_K、IQ4_K、IQ5_K、IQ6_K 以及它们的 _R4/_R8 行交错变体等都要求张量的列数行大小nx ne[0]能被 QK_K 整除if (nx % QK_K ! 0) { LLAMA_LOG_WARN(\n\n%s : tensor cols %d x %d are not divisible by %d, required for %s, __func__, nx, ny, QK_K, ggml_type_name(new_type)); convert_incompatible_tensor true; }在 llama.cpp 系实现中 QK_K 为 256这也是 PR #294 描述中提到的ffn_down_expsrow sizes are not a multiple of 256ffn_down_exps行大小不是 256 的倍数的由来。此外还有一组特殊的 BitNet 1.58-bit 类型IQ1_BN、IQ2_BN、IQ2_BN_R4它们要求行大小能被各自的QK_IQ1BN整除。崩溃场景DeepSeek-Lite 的 ffn_down_expsPR #294 作者项目作者 ikawrakow在描述中给出了具体案例ffn_down_expsrow sizes are not a multiple of 256 in DeepSeek-Lite. When using--purewithllama-quantizethis leads to a crash.ffn_down_exps是 MoE混合专家模型中专家的 FFN 下投影张量它是 3D 张量量化器只处理 2D 和 3D 张量见 src/llama-quantize.cpp 中quantize only 2D and 3D tensors (experts)的注释。DeepSeek-Lite 中该张量的行大小并非 256 的倍数一旦用--pure强制以某个 k-quant 类型量化它行大小无法被块大小整除直接导致崩溃。作者的困境也很有代表性由于--pure路径此前没有行大小可整除性检查遇到这类模型时只能通过--custom-q自定义正则量化规则等机制手动为异常张量指定其他类型非常繁琐。PR #294 的动机正是厌倦了在那种情况下做自定义量化覆盖I got tired of having to do custom quantization overrides in that case。修复方案把可整除性检查扩展到 --pure 路径修复的核心是让--pure路径复用既有的change_type_if_necessary检查。量化主循环中 --pure 分支 的实现如下if (quantize) { new_type default_type; // get more optimal quantization type based on the tensor shape, layer, etc. if (params-pure) { auto working_type change_type_if_necessary(new_type, tensor-ne[0], tensor-ne[1]); if (working_type ! new_type) { qs.n_fallback; new_type working_type; } } else if (ggml_is_quantized(default_type)) { new_type llama_tensor_get_type(qs, new_type, tensor, ftype); } ... }也就是说PR 之前只有非--pure路径通过llama_tensor_get_type内部同样调用 change_type_if_necessary会做该检查PR 之后--pure路径也先对ne[0]行大小与目标量化类型做兼容性校验不满足时自动切换到 fallback 类型而不是直接崩溃。fallback 类型映射不满足整除时自动降级change_type_if_necessary后半部分定义了完整的 fallback 映射表src/llama-quantize.cpp。当目标类型无法满足行大小约束时按如下规则切换到不要求 256 整除的基础量化类型原目标类型行大小无法被 QK_K 整除时fallback 类型Q2_K / Q3_K / IQ2_XXS / IQ2_XS / IQ2_KS / IQ2_S / IQ3_XXS / IQ3_S / IQ1_S / IQ1_M / IQ2_K / IQ2_KL / IQ3_KS / IQ3_K / IQ4_KSS / IQ4_KS / IQ1_KT / IQ2_KT / IQ3_KT / IQ4_KT / IQ4_XS 及其 _R4/_R8 变体IQ4_NLIQ4_K / Q4_K / IQ5_KS 等Q5_0IQ5_K / Q5_K 等Q6_0IQ6_K / Q6_K 等Q8_0其余无法映射的类型抛出 Unsupported tensor size encountered 运行时异常选型逻辑很直观IQ4_NL、Q5_0、Q6_0、Q8_0这类 legacy 量化类型采用更小的块不需要 256 元素对齐任何行大小都能容纳因此作为兜底既保证了不崩溃又尽量维持相近的位宽精度。转换后会打印- using fallback quantization %s警告日志并累加统计计数qs.n_fallback。整个量化流程结束时若存在 fallback主函数会汇总输出警告src/llama-quantize.cppif (qs.n_fallback 0) { LLAMA_LOG_WARN(%s: WARNING: %d of %d tensor(s) required fallback quantization\n, __func__, qs.n_fallback, qs.n_k_quantized qs.n_fallback); }借助这一输出用户可以直接看到模型中有多少个张量因形状约束被降级便于评估量化结果是否符合预期。实战复现与验证建议你可以在本仓库中直接查看相关实现与用法查看完整命令行帮助llama-quantize的帮助输出位于 examples/quantize/quantize.cpp其中详细列出了--pure、--custom-q、--ffn-down-type、--override-kv等参数含义以及 Allowed quantization types 列表包含所有支持的 legacy/K/IQ/R4 类型及说明。阅读核心检查逻辑src/llama-quantize.cpp 的change_type_if_necessary完整展示了可整除性检查与 fallback 映射src/llama-quantize.cpp 是--pure分支的调用点。复现思路选取一个存在非 256 倍数行大小张量的 MoE 模型如 DeepSeek-Lite 这类ffn_down_exps形状特殊的模型执行./llama-quantize --pure model-f16.gguf model-q4_k.gguf Q4_K修复后遇到不兼容张量时量化器会打印行大小警告与 fallback 提示WARNING: N of M tensor(s) required fallback quantization而不是崩溃退出。若希望强制观察原始崩溃行为可用--custom-q ffn_down_expsQ4_K等自定义规则对比。小结PR #294 虽然规模很小却修复了一个真实且影响广泛的量化崩溃问题--pure模式下llama-quantize此前缺少张量行大小与量化块大小QK_K 256的可整除性校验遇到 DeepSeek-Lite 等模型中行大小特殊的专家张量ffn_down_exps时直接崩溃。修复后--pure路径与 k-quant 混合路径一样统一经由change_type_if_necessary做形状校验并在必要时将目标类型自动回退到IQ4_NL/Q5_0/Q6_0/Q8_0等基础类型同时在结束阶段给出n_fallback汇总警告。这一改动让--pure模式无需依赖繁琐的自定义量化覆盖即可稳健处理各种模型架构也再次体现了量化工具设计中形状约束检查这一容易被忽略但至关重要的工程细节。【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考