ik_llama.cpp 离线 Repack 实战指南：将已有 GGUF 重新打包为行交错 R4 变体，摆脱 --run-time-repack 并启用 mmap

ik_llama.cpp 离线 Repack 实战指南将已有 GGUF 重新打包为行交错 R4 变体摆脱 --run-time-repack 并启用 mmap【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp导读本文围绕 ik_llama.cpp 社区讨论 #323 的核心议题展开如何将一个已经量化好的 GGUF例如 DeepSeek-V3-0324 的 Q4_K_XL 量化版**离线重新打包repack**为行交错row-interleaved的_R4变体从而在加载模型时不再依赖--run-time-repack-rtr选项进而重新获得mmap内存映射加载能力。读完本文你将掌握llama-quantize --repack与--repack-pattern正则的完整用法、--override-tensor与 repack 正则之间的对应关系、多部分 GGUF 的处理方式以及混合 CPU/GPU 部署下专家张量exps 系列放置与性能调试的实战经验。背景-rtr与 mmap 的取舍在 ik_llama.cpp 中--run-time-repack-rtr会在模型加载时把所有张量就地in-place重打包为对应的行交错变体如果存在的话。这种做法带来的直接代价可以在 common/common.cpp 的参数解析逻辑中看到if (arg -rtr || arg --run-time-repack) { params.repack_tensors true; params.use_mmap false; return true; }也就是说一旦启用-rtrmmap会被强制关闭。这正是讨论发起人 Lissanro 面临的两难处境使用 Unsloth 发布的DeepSeek-V3-0324-GGUF-UD-Q4_K_XL配合-rtr运行时在 EPYC 776364 核 1TB DDR4-3200 内存 4×RTX 3090 的机器上可以获得7 tokens/s的生成速度但-rtr禁用 mmap 后每次重新加载模型都需要大量计算每次加载都要重新做一遍 repack而他的工作流需要频繁切换模型例如先用 72B 视觉模型处理图片再切换回 DeepSeek-V3切换成本被显著放大。于是核心诉求就变成了能不能把-rtr在加载时做的 repack 一次性离线完成、固化到一个新的 GGUF 文件里这样加载时无需-rtr、可以继续使用 mmap、还能保住同样的性能。核心概念行交错Row-InterleavedR4 量化变体要理解 repack先要理解 ik_llama.cpp 特有的行交错量化类型。这类类型以_R4、_R8以及更高阶的_R16后缀命名可以从 examples/quantize/quantize.cpp 中的QUANT_OPTIONS列表一览全貌例如IQ2_K_R4IQ2_K repacked、IQ4_K_R4、IQ4_KS_R4、IQ5_KS_R4Q2_K_R4、Q3_K_R4、Q4_K_R4、Q5_K_R4、Q6_K_R4、Q8_K_R8IQ1_S_R4、IQ1_M_R4、IQ2_XXS_R4、IQ2_XS_R4、IQ3_XXS_R4、IQ3_S_R4Q4_0_R8、Q8_0_R8、Q8_KV_R8、BF16_R16、MXFP4_R8等这些类型的共同点是把若干行row的数据交错打包在一起从而让内存布局更有利于 CPU 侧的矩阵乘法特别是配合 MoE 专家张量在 CPU 上执行时实现比传统同 bpw 类型更高的吞吐。也正因如此它们通常被当作运行在 CPU 内存上的张量的首选格式。从 src/llama-quantize.cpp 的repacked_ftype()映射表可以看出每个传统量化类型都有且仅有一个对应的行交错变体例如原类型repack 后类型Q4_K_S / Q4_K_MQ4_K_R4Q5_K_S / Q5_K_MQ5_K_R4Q6_KQ6_K_R4Q8_KQ8_K_R8IQ2_K / IQ3_K / IQ4_K / IQ5_KIQ2_K_R4 / IQ3_K_R4 / IQ4_K_R4 / IQ5_K_R4IQ4_XSIQ4_XS_R8Q4_0 / Q8_0Q4_0_R8 / Q8_0_R8BF16BF16_R16重要限制repack 只能把某个类型转换到它唯一的对应行交错变体不能随意改造成别的量化类型。正如作者 ikawrakow 在讨论中明确回应的No. The repacking is only to the corresponding row-interleaved type. Repacking to something else would result in quality loss.不行repack 只针对对应的行交错类型改成别的类型会导致质量损失。例如IQ4_XS只能变成IQ4_XS_R4或IQ4_XS_R8视映射而定不会变成Q4_K_R4。离线 Repack 实操llama-quantize --repack基础命令离线 repack 正是由llama-quantize工具完成的核心参数是--repack与--repack-pattern。作者 ikawrakow 给出的最简命令如下./bin/llama-quantize --repack \ --repack-pattern exps \ ~/models/DeepSeek-V3-0324-GGUF-UD-Q4_K_XL/DeepSeek-V3-0324-UD-Q4_K_XL-00001-of-00009.gguf \ repacked_model_file_name q4_k_r4逐项解读--repack进入仅 repack模式等价于把 examples/quantize/quantize.cpp 中的params.only_repack置为true此时工具不做重新量化只对匹配到的张量做类型重打包--repack-pattern逗号分隔的正则表达式列表只有张量名匹配其中任一正则的张量才会被 repack参数解析见 quantize.cpp。exps会匹配 DeepSeek 这类 MoE 模型中以ffn_down_exps、ffn_up_exps、gate_exps结尾的专家张量q4_k_r4目标类型参数这里表示把匹配到的张量转换为Q4_K_R4大小写不敏感工具内部会统一转大写后查表输出文件必须与输入模型是不同路径。命令不会覆盖原模型因此磁盘上需要同时容纳新旧两份模型的空间对于 DeepSeek-V3 这类数百 GB 的模型务必提前确认磁盘余量。repack 正则与 --override-tensor 的对应关系讨论中最实用的一条技巧是--repack-pattern的正则可以直接从--override-tensor参数里抄过来去掉CPU部分即可。因为两者使用的都是张量名正则匹配机制。例如服务器启动参数中的--override-tensor ffn_down_expsCPU, ffn_up_expsCPU, gate_expsCPU等价于更简洁的写法--override-tensor本身支持正则--override-tensor expsCPU而与之对应的 repack 命令则是./bin/llama-quantize --repack --repack-pattern ffn_down_exps,ffn_up_exps,gate_exps ... q4_k_r4即你打算在 CPU 上运行的张量就写进--repack-pattern你打算放在 GPU 上的张量就不要 repack保持非 R4 类型。这是整个 repack 部署策略的核心准则。多部分 GGUF 的处理DeepSeek-V3 / R1 的 GGUF 往往被拆成多个分片例如-00001-of-00009.gguf。ikawrakow 坦言自己从未 repack 过多部分 GGUF不确定llama-quantize是否能正确加载全部分片讨论参与者 saood06 则补充了关键细节按 gguf-split 方式拆分的文件必须用 gguf-split 工具合并不能直接用cat拼接。因此如果遇到多分片 repack 失败的情况合理的做法是先合并分片得到单一 GGUF 文件再执行 repack。另外值得注意的是Lissanro 在转换日志中看到llama_model_loader: additional 8 GGUFs metadata loaded.说明在部分场景下加载器确实能够读取到其余分片但为稳妥起见仍建议优先保证单一文件输入。实战案例DeepSeek-R1 / V3 的专家张量离线 Repack用户的最终 repack 命令经过多轮调试Lissanro 最终用于 R1 的离线 repack 命令如下~/pkgs/ik_llama.cpp/build/bin/llama-quantize --repack \ --repack-pattern (^blk\.[7-9]|\d\d).ffn_(up|gate)_exps|ffn_down_exps \ /mnt/secondary/neuro/DeepSeek-R1-GGUF_Q4_K_M-163840seq/DeepSeek-R1-Q4_K_M-00001-of-00011.gguf \ /home/lissanro/neuro/DeepSeek-R1-GGUF_Q4_K_M-163840seq/DeepSeek-R1-GGUF_Q4_K_M_R4.gguf \ q4_k_r4这个正则(^blk\.[7-9]|\d\d).ffn_(up|gate)_exps|ffn_down_exps的含义是(^blk\.[7-9]|\d\d).ffn_(up|gate)_exps匹配第 7~9 层以及所有两位数的层即 10 层及以上的ffn_up_exps和ffn_gate_exps张量ffn_down_exps匹配所有ffn_down_exps张量。这样精心构造的意图是第 0~6 层含一位数编号的层的ffn_up_exps/ffn_gate_exps要保留在 GPU 上执行因此不 repack其余专家张量全部转为Q4_K_R4交给 CPU 处理。正如 ubergarm 所建议的先规划好哪些层要放 GPU把对应张量排除在 repack 之外只把剩余的路由专家层 repack 成 CPU 友好格式。配套的服务器启动命令repack 之后加载模型就无需-rtr可以正常享受 mmap。Lissanro 的启动命令为taskset -c 0-63 ~/pkgs/ik_llama.cpp/build/bin/llama-server \ --model /home/lissanro/neuro/DeepSeek-R1-GGUF_Q4_K_M-163840seq/DeepSeek-R1-GGUF_Q4_K_M_R4.gguf \ --ctx-size 73728 --n-gpu-layers 62 --tensor-split 25,25,25,25 -mla 2 -fa -ctk q8_0 -amb 1024 -fmoe \ -ot blk\.3\.ffn_up_expsCUDA0, blk\.3\.ffn_gate_expsCUDA0 \ -ot blk\.4\.ffn_up_expsCUDA1, blk\.4\.ffn_gate_expsCUDA1 \ -ot blk\.5\.ffn_up_expsCUDA2, blk\.5\.ffn_gate_expsCUDA2 \ -ot blk\.6\.ffn_up_expsCUDA3, blk\.6\.ffn_gate_expsCUDA3 \ -ot ffn_down_expsCPU, ffn_up_expsCPU, gate_expsCPU \ --threads 64 --host 0.0.0.0 --port 5000这里有两条非常实用的经验-ot--override-tensor支持正则例如blk\.3\.ffn_up_expsCUDA0中的\.是转义后的字面点号正则匹配同样适用于 repack因此--repack-pattern可以直接复用这些正则去掉设备部分。CPU 覆盖规则必须放在最后Lissanro 实测发现如果先写ffn_down_expsCPU, ffn_up_expsCPU, gate_expsCPU再写各 GPU 的覆盖CUDA 覆盖会不生效把 CPU 兜底规则放在最后一条-ot各 GPU 的逐层覆盖才真正生效。由于单个-ot参数无法表达多行格式可以用多个-ot参数每个参数一行便于在脚本中组织可读性。专家张量放置策略up/gate 优先上 GPU关于剩余 VRAM 该放哪些张量ikawrakow 给出了明确的策略性建议在 VRAM 有富余时优先把若干层的ffn_up_exps和ffn_gate_exps成对放进 GPU——这比只放某一个专家张量、或把三个专家张量都放进去收益更大尤其是在开启-fmoe时。他在低配硬件Ryzen 5975WX RTX 4080上实验 Llama-4-Scout 时使用的配置是一个很好的模板-ot blk\.[0-9]\.ffn_up_expsCUDA0,blk\.[0-9]\.ffn_gate_expsCUDA0,blk\.1[0-9]\.ffn_up_expsCUDA0,blk\.1[0-9]\.ffn_gate_expsCUDA0,expsCPU -ngl 100其含义是所有 attention 与共享专家张量放 GPU前 20 层blk.[0-9]与blk.1[0-9]的ffn_up_exps/ffn_gate_exps也放 GPU其余专家exps全部留在 CPU。至于具体放多少层取决于剩余 VRAM 与张量大小——Lissanro 在 4×24GB VRAM、72K 上下文的约束下最终只能在每张卡上各放一层blk.3~blk.6的 up/gate 专家对。性能调试实录mmap 与页缓存问题离线 repack 与在线 repack 是否等价ikawrakow 明确表示The offline repacking command should produce a result that is 100% equivalent to what happens with online repacking.离线 repack 命令的结果应当与在线 repack 100% 等价。但他同时指出两种运行方式下内存的分配与张量归属方式不同因此性能表现可能不完全一致——只是在他的硬件上差异从未达到 Lissanro 报告的那么大。Lissanro 实测对比同一 prompt多次运行取计时行原版 Unsloth 量化 -rtr约7.26 / 7.29 / 7.56 tokens/s离线 repack 后不带-rtr约4.28 / 5.07 / 3.96 tokens/s他观察到 EPYC 7763 的 64 核在两种场景下都接近满载怀疑转换后的量化在 CPU 侧存在额外瓶颈。排查步骤drop_caches、--no-mmap 与 BIOSikawrakow 建议先尝试清空页缓存再加载离线 repack 的模型echo 3 | sudo tee /proc/sys/vm/drop_cachesLissanro 照做后系统 1TB 内存、无 swap模型约 378GB加载后仍有 300GB 空闲性能不升反降从接近 7.5 掉到不足 4 tokens/s随后又发现给 repack 后的模型加上-rtr再跑性能又恢复到 7.3~7.5 tokens/s说明 repack 操作本身没问题用--no-mmap显式关闭 mmap、不带-rtr运行性能恢复到 7.34 tokens/s——由此定位到问题出在 mmap 而非量化文件。ubergarm 则补充了两点重要的 mmap 基准测试常识mmap 模式下模型是懒加载进页缓存的第一轮完整运行的计时通常会偏慢需要先预热页缓存再统计可以借助btop观察磁盘 I/O 与cached来确认。而关闭 mmap 时启动更慢要把整个模型读入 RAM但后续运行更快。关闭 mmap 时系统可能自动利用透明大页transparent huge pages可以用numastat -m -p $(pidof llama-server)或 llama-bench 等进程检查该因素对性能的影响因系统而异。最终 Lissanro 通过重置 BIOS、只保留必要设置解决了 mmap 下的性能问题——他怀疑是 BIOS 中关于内存吞吐的性能调优项影响了 mmap 访问效率。修复后mmap 模式下 repack 模型的性能为上下文填充约 2.5K token 时7.86 tokens/s32K 填充时5.09 tokens/s64K 填充时略高于 3 tokens/s输入处理约 50~80 tokens/smmap 加载模型耗时约 45 秒相比-rtr每次重新计算 repack切换模型的成本大幅下降。源码级原理支撑1. repack 的目标类型由映射表决定离线 repack 时llama-quantize会读取输入模型的ftype通过repacked_ftype()见 src/llama-quantize.cpp查出整模型的 repack 目标类型对每个张量则通过iqk_repacked_type()判断是否存在行交错变体相关逻辑见 src/llama-quantize.cpp。若张量类型没有对应 R4/R8 变体或张量名不匹配任何--repack-pattern正则则保持原样写入新文件。2. --repack 与 --repack-pattern 的参数解析两个参数在 examples/quantize/quantize.cpp 中解析--repack将params.only_repack置为true--repack-pattern把逗号分隔的正则列表拆分为std::vectorstd::string。工具的 usage 帮助文本quantize.cpp也明确写道--repack Repack all tensors to the corresponding _r4/8 variant if available. --repack-pattern Comma separated list of regexs to use for matching tensor names to be repacked.3. -rtr 与 mmap 的绑定关系如前文所述common/common.cpp 中-rtr同时设置params.repack_tensors true与params.use_mmap false这就是启用-rtr必然失去 mmap的代码根源。此外src/llama-reload.cpp 也指出-rtr会在加载时把宿主张量就地 repack类型变为行交错变体且热切换hotswap恢复的张量无法复现 repack 后的状态——这意味着需要频繁切换模型的场景下每次切换都要付出重新 repack 的计算代价进一步凸显离线 repack 的价值。总结与适用建议一句话方案用llama-quantize --repack --repack-pattern 正则 输入.gguf 输出.gguf 目标R4类型把要留在 CPU 上的张量离线转成行交错变体加载时去掉-rtr即可恢复 mmap。正则设计--repack-pattern的正则直接取自--override-tensor去掉设备后缀只 repack CPU 侧张量GPU 侧张量保持非 R4 类型。类型限制repack 只能转换为该类型唯一的对应行交错变体如Q4_K_M → Q4_K_R4不能跨类型转换否则会有质量损失。多分片模型gguf-split 拆分的分片应先用 gguf-split 合并成单文件再 repack。性能验证离线 repack 与在线 repack 理论上 100% 等价但实际运行时的内存分配、页缓存状态、透明大页乃至 BIOS 设置都可能造成显著差异mmap 场景下基准测试应预热页缓存后再统计。GPU 放置优先级VRAM 富余时优先把ffn_up_exps与ffn_gate_exps成对放 GPU配合-fmoe收益更大ffn_down_exps可留 CPU多-ot时 CPU 兜底规则要放在最后。进一步参考llama-quantize 工具源码、量化核心实现、命令行参数解析 与 工具使用文档可在当前仓库中继续深入阅读。【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考