2026/9/19 9:18:13
FEATURED · 精选文章 
ik_llama.cpp 兼容主流的 DeepSeek GGUF不兼容 MLA 张量布局的检测与自动修复实战【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp导读本篇文章以 ik_llama.cpp 仓库 PR #394Handle incompatible DeepSeek GGUFs为核心讲解当 DeepSeek GGUF 模型按主流 llama.cpp 的 MLA 张量布局导出、与 ik_llama.cpp 自身格式不一致时模型加载器如何自动检测、降级并在线重建张量使模型仍可运行。读完本文你将理解 wkv_b 与 wk_b/wv_b 两种 MLA 张量布局的差异、加载期自动修复的源码实现、-mla参数各档位的含义与性能取舍以及如何在多 GPU 环境下配合--override-tensor、-fmoe、-ub、-rtr等参数调优 DeepSeek 推理。一、背景MLA 支持分叉引发的 GGUF 兼容性危机DeepSeek 系列模型DeepSeek-V2/V3/R1 及 DeepSeek-Lite采用 MLAMulti-head Latent Attention架构。ik_llama.cpp 早在主流 llama.cpp 之前约 2.5 个月就实现了 MLA 支持并采用了合并的wkv_b张量布局每层注意力用一个[kv_lora_rank, n_head * (n_embd_head_qk_nope n_embd_head_v)]的wkv_b权重完成 KV 压缩投影。而主流 llama.cpp 在 PR 12801 中加入 MLA 支持时采用了另一套布局把 KV 压缩投影拆成wk_bK 的 no-pe 部分与wv_bV 部分两个独立张量。这一改动打破了向后兼容性——在此之后Hugging Face 上陆续出现的新 DeepSeek GGUF例如 Unsloth 发布的 UD 量化都是按主流格式导出的直接导致 ik_llama.cpp 用户无法加载这些新文件对应仓库中的 issue #373DeepSeek-V3-0324 无法加载最新 UD 量化 与 issue #383加载 DeepSeek R1T Chimera 失败。PR #394 的作者 ikawrakow 起初并不打算支持这些不兼容 GGUF——毕竟让用户重新下载动辄数百 GB 的 DeepSeek-R1/V3 模型代价过高而且 MLA 所需的新张量完全可以像本仓库此前所做的那样在加载模型时即时创建。但权衡之后PR #394 最终实现了对不兼容 GGUF 的加载期自动修复。该 PR 于 2025-05-07 创建、2025-05-10 合入作者本人用与 DeepSeek-R1/V3 完全相同的注意力架构的 DeepSeek-Lite 完成了验证并在社区用户 Panchovix 的 DeepSeek-V3-0324 实测中得到确认。二、不兼容的表象与本质wkv_b vs wk_b/wv_b2.1 两种 MLA 张量布局对比以 PR 对话中 Panchovix 加载的DeepSeek-V3-0324-UD-Q2_K_XL为例模型元数据中的 MLA 关键参数为元数据键值含义deepseek2.attention.q_lora_rank1536Q 低秩投影秩deepseek2.attention.kv_lora_rank512KV 低秩投影秩deepseek2.attention.key_length576K 全长度rope 64×… no-pe 部分deepseek2.attention.value_length512V 长度deepseek2.attention.key_length_mla192MLA 中 K 的 rope 部分长度deepseek2.attention.value_length_mla128MLA 中 V 的压缩长度ik_llama.cpp 的合并布局把wk_b与wv_b合并为单个blk.N.attn_kv_b.weightwkv_b形状为[kv_lora_rank, n_head * (n_embd_head_qk_nope n_embd_head_v)]主流 llama.cpp 则是两个独立张量。两种布局在数学上等价K 的 no-pe 部分与 V 的投影结果可以直接拼接但文件层面的张量名与形状不同因此 GGUF 无法互通。2.2 社区实测中暴露的其他形状差异PR 对话中用户 whatever1983 用主流convert_hf_to_gguf.py转换 DeepSeek-V3-0324-Pruned-Coder-411B 再重量化为 IQ4K 后加载时报出llama_model_load: error loading model: check_tensor_dims: tensor blk.0.attn_q_b.weight has wrong shape; expected 1536, 73728, got 1536, 24576, 1, 1 llama_load_model_from_file: failed to load model其中 73728 128 heads × 576ik 期望 attn_q_b 输出每个 head 的完整 K 长度而 24576 128 × 192主流格式中 attn_q_b 只负责 rope 部分。这说明 MLA 的差异不只体现在wkv_bQ 投影的张量切分方式也不一致。作者对此的回应是当前 master 的convert_hf_to_gguf.py对 mergesBPE 合并规则处理不佳对应修复在 PR #377因rope_scaling张量缺失问题尚未合入因此更稳妥的做法是使用本仓库自带的 convert_hf_to_gguf.py 重新转换得到与 ik_llama.cpp 完全兼容的 GGUF。三、加载期自动修复的源码实现PR #394 的修复集中在三处超参数检测、张量加载分支、KV 缓存降级。3.1 超参数检测识别主流格式的 MLA 模型在 src/llama-hparams.cpp#L1199-L1221 的LLM_ARCH_DEEPSEEK2分支中当n_head_kv() 1MLA 的标志时加载器先验证一组可修复前提条件int expected_head_size_k model.arch LLM_ARCH_DEEPSEEK2 ? 576 : 320; int expected_head_size_v model.arch LLM_ARCH_DEEPSEEK2 ? 512 : 256; if (hparams.n_head_kv() 1) { int n_nead_kv hparams.n_gqa(); if (n_nead_kv%4 ! 0 || hparams.n_embd_head_k(0) ! expected_head_size_k || hparams.n_embd_head_v(0) ! expected_head_size_v || hparams.n_rot ! 64) { LLAMA_LOG_ERROR(\n); LLAMA_LOG_ERROR(Detected incompatible DeepSeek model without a known way to fix it.\n); ... GGML_ABORT(Fatal error); } LLAMA_LOG_INFO( Adjusted mainline llama.cpp MLA tensors to ik_llama.cpp\n); for (auto item : hparams.n_head_kv_arr) item n_nead_kv; hparams.n_embd_head_k_full 192; hparams.n_embd_head_v_full 128; ml.get_key(LLM_KV_ATTENTION_KEY_LENGTH_MLA, hparams.n_embd_head_k_full); ml.get_key(LLM_KV_ATTENTION_VALUE_LENGTH_MLA, hparams.n_embd_head_v_full); }要点可修复的前提n_gqa % 4 0、n_embd_head_k 576、n_embd_head_v 512、n_rot 64。满足这些条件说明模型是标准 DeepSeek-V2/V3/R1 类 MLA 布局加载器可以自动把 head 数调整到n_gqa并把 MLA 的 K/V 长度校准为 192/128不可修复的模型条件不满足时直接打印Detected incompatible DeepSeek model without a known way to fix it并终止加载绝不强行拼凑类似的检测逻辑也出现在 DeepSeek-V4llama-dsv4相关分支的 src/llama-hparams.cpp#L2143-L2159 中表明该机制已成为仓库处理外部 DeepSeek GGUF 的标准入口。3.2 张量加载分支wkv_b 缺失则回退到 wk_b/wv_b在 src/llama-load-tensors.cpp#L3243-L3256 中wkv_b被标记为TENSOR_NOT_REQUIRED可选张量layer.wkv_b create_tensor(wkv_b_ctx, tn(LLM_TENSOR_ATTN_KV_B, weight, i), {kv_lora_rank, n_head * (n_embd_head_qk_nope n_embd_head_v)}, llama_model_loader::TENSOR_NOT_REQUIRED); if (!layer.wkv_b) { // Incompatible mainline model. Lets see if we can still load it layer.wk_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_K_B, weight, i), {n_embd_head_qk_nope, kv_lora_rank, n_head}, 0); layer.wv_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_V_B, weight, i), {kv_lora_rank, n_embd_head_v, n_head}, 0); } else { layer.wk_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_K_B, weight, i), {n_embd_head_qk_nope, n_head * kv_lora_rank}, 1); layer.wv_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_V_B, weight, i), {kv_lora_rank, n_head * n_embd_head_v}, 1); }逻辑很直白优先尝试读取合并的wkv_bik 原生格式若 GGUF 中不存在则按主流格式读取独立的wk_b/wv_b进入兼容模式。代码注释// Incompatible mainline model. Lets see if we can still load it与 PR 描述Will try to fix, but there are no guarantees的警示口径完全一致。3.3 在线重建从 wk_b/wv_b 计算 wkv_b兼容模式下wk_b/wv_b并不会直接参与计算而是在模型加载阶段被实时合并回wkv_b。核心函数是 src/llama.cpp#L3050-L3139 的llm_compute_wkv_b// Compute the combined wkv_b tensor of one layer from the current wk_b/wv_b // tensor data, on the CPU. static ggml_tensor * llm_compute_wkv_b(ggml_context * ctx, ggml_cgraph * graph, const ggml_tensor * wk_b_src, const ggml_tensor * wv_b_src, ...) { ... auto wkv_b_f32_3d ggml_concat(ctx, wk_b_transposed, wv_b_used, 1); ... auto new_type wk_b.type GGML_TYPE_BF16 wv_b.type GGML_TYPE_BF16 ? GGML_TYPE_BF16 : wk_b.type GGML_TYPE_F16 wv_b.type GGML_TYPE_F16 ? GGML_TYPE_F16 : GGML_TYPE_Q8_0; auto wkv_b ggml_cast(ctx, wkv_b_f32, new_type); ... ggml_build_forward_expand(graph, wkv_b); ... }实现细节值得注意若wk_b/wv_b不在 host 内存如驻留 GPU会先通过ggml_backend_tensor_get拷回临时缓冲区非 F32 权重先ggml_cast到 F32转置后沿维度 1 拼接再按源类型降级输出源为 BF16 则输出 BF16、F16 则输出 F16否则输出 Q8_0整个推导被构建成一个小型计算图约 8 个节点在 CPU 上执行结果写入tmp_buffer只在加载阶段有效不进入后续推理图由于合并在加载期一次性完成推理时依然走 ik 原生mla3的wkv_b路径——只是合并不是无损的当wk_b/wv_b本身是量化类型时合并结果统一降级为 Q8_0 精度的wkv_b而非 F32 原值。3.4 KV 缓存降级强制 mla1即使模型张量加载成功KV 缓存初始化阶段还有一个关键降级步骤。在 src/llama.cpp#L1318-L1340 的llama_kv_cache_init中bool have_wkv_b n_have_wkv_b 0; if (!have_wkv_b) { if (cparams.mla_attn ! 1) { LLAMA_LOG_WARN(\n); LLAMA_LOG_WARN(%s: missing wkv_b tensor(s)\n, __func__); LLAMA_LOG_WARN(%s: changing MLA from %d to 1\n, __func__, cparams.mla_attn); if (cparams.mla_attn 1) { LLAMA_LOG_WARN(%s: ** Prompt processing performance will be crippled **\n, __func__); } LLAMA_LOG_WARN(\n); // Sorry for the hack. auto non_cparams const_castllama_cparams(cparams); non_cparams.mla_attn 1; } }这正是 PR 描述中Big caveat的代码落点使用不兼容模型时只能运行初始版 MLAmla1即与主流 llama.cpp 相同的实现方式。用户日志中可以看到llama_kv_cache_init: missing wkv_b tensor(s) llama_kv_cache_init: changing MLA from 0 to 1四、mla 档位与不兼容模型的性能代价-mla--mla-use参数在 common/common.h#L424 中定义默认值为 3在 common/common.cpp#L1929 中解析int mla_attn 3; // MLA 0: standard, 1: MLA with K and V^T cache, 2: MLA with just K cache, 3: the best of both worlds档位含义说明0standard标准注意力不启用 MLA 专用缓存路径1K V^T 缓存等价于主流 llama.cpp 的实现方式不兼容 GGUF 被强制锁定在此档2仅 K 缓存进一步压缩缓存占用3两者结合默认档ik_llama.cpp 最优实现需要原生wkv_b布局使用不兼容 GGUF 时被锁定在mla1意味着两个直接后果PR 原文明示Prompt processing 性能低于mla3且性能退化随 KV 缓存中 token 数量的增加即上下文变长而加剧GPU Flash Attention 仅对 Ampere 及更新架构的 NVIDIA GPU 可用因为mla1的 FA 实现依赖较新的 GPU 特性。因此最理想的做法仍是使用 ik_llama.cpp 原生兼容的 GGUF用仓库自带 convert_hf_to_gguf.py 转换或用与仓库兼容的量化工具导出从而保留mla3的全部性能PR #394 的自动修复只是为手上只有主流格式大模型文件、不愿重新下载的场景兜底。五、实战加载不兼容 DeepSeek GGUF 并调优5.1 最小启动命令以 PR 对话中 Panchovix 实测通过的 DeepSeek-V3-0324 UD-Q2_K_XL 为例不兼容模型的完整加载命令为./llama-server -m /GGUFs/DeepSeek-V3-0324-UD-Q2_K_XL-merged.gguf \ -c 16384 --no-mmap --no-warmup -v -ngl 999 \ -ot blk.(0|1|2|3|4|5|6).ffn.CUDA0 \ -ot blk.(7|8|9|10).ffn.CUDA1 \ -ot blk.(11|12|13|14).ffn.CUDA2 \ -ot blk.(15|16|17|18|19|20|21|22|23|24).ffn.CUDA3 \ -ot ffn.*CPU -fmoe -mla 1各参数说明-ngl 999尽可能多的层卸载到 GPU-ot patternDEVICE--override-tensor按正则把指定张量强制分配到某块 GPU这里把不同层区间的 MoE 专家*.ffn.*分散到 4 块 GPU剩余专家留在 CPU-fmoe启用融合 MoEfused MoE内核-mla 1显式声明使用mla1档加载不兼容模型时即使不指定也会被强制降级。加载成功的标志性日志序列如下节选自 PR 实测输出Detected incompatible DeepSeek model. Will try to fix, but there are no guarantees *** Your prompt processing speed will be crippled *** Consider making your own ik_llama.cpp compatible model or ask the model provider to make one for you, ... llama_kv_cache_init: missing wkv_b tensor(s) llama_kv_cache_init: changing MLA from 0 to 1第一段警告来自张量加载阶段检测到无wkv_b第二段来自 KV 缓存初始化确认降级到mla1。看到这两段后模型仍能正常加载并生成即代表自动修复生效。5.2 与主流 llama.cpp 的对比命令Panchovix 在主流 llama.cpp 上的等价命令同样用张量覆盖实现专家分散./llama-server -m /GGUFs/DeepSeek-V3-0324-UD-Q2_K_XL-merged.gguf \ -c 16384 --no-mmap --no-warmup -ngl 99 \ --override-tensor blk\.([0-7])\..*_exps\.CUDA0 \ --override-tensor blk\.([8-9]|1[0-1])\..*_exps\.CUDA1 \ --override-tensor blk\.(1[2-6])\..*_exps\.CUDA2 \ --override-tensor blk\.(1[7-9]|2[0-6])\..*_exps\.CUDA3 \ --override-tensor blk\..*_exps\.CPU -mg 0 -fa --ubatch-size 1024注意两者在提示词处理PP性能上的差异有明确的架构原因作者在对话中解释主流 llama.cpp 会把驻留 RAM 的张量也搬运到 GPU 做矩阵乘法而 ik_llama.cpp 对驻留 RAM 的张量在 CPU 上做矩阵乘法。因此CPU 较弱 VRAM 充足 PCIe 带宽高 大 batch的场景下主流实现占优而在CPU 强 / KV 缓存长 / 专家矩阵巨大的场景下不搬运反而减少 PCIe 流量ik_llama.cpp 更有利。作者随后在对话中透露PR #405 为 ik_llama.cpp 增加了反向开关强制把 RAM 中的张量卸载到 GPU 计算并建议想压榨 PP 性能时用尽可能大的 u-batch且不要加-rtr实时重打包会禁用专家张量的 GPU 卸载。5.3 进一步调优建议综合 PR 对话中的实测经验可提炼出以下可复现的调优点增大 u-batch-ub 1024把 PP 从 66 t/s 提升到 100 t/s-ub 1536进一步提升到约 126 t/s主流 llama.cpp 侧实测配合-rtr可进一步改善 PP但会禁用专家 GPU 卸载需按 5.2 的取舍选择合理分配专家张量MoE 专家ffn_*_exps是 DeepSeek 模型的体积大头用--override-tensor/-ot按正则把不同层区间映射到不同 GPU尽量填满每张卡的显存余量关注加载顺序若 GPU 主卡在加载时未被优先填充日志中CPU buffer size先出现PP 性能会明显下滑——这在主流 llama.cpp 上同样存在属于加载分配顺序问题而非模型兼容性问题KV 缓存占用mla1模式仍会存储 V 缓存而 ik 原生mla2/3可省去 V 缓存因此不兼容模型还会多占用一部分显存可据此评估是否上调-ub。六、从源码结构看兼容性机制的整体设计纵观整个兼容层可以总结出三点设计思路从源码结构推断加载期一次性修复推理期零开销wkv_b的合并只在模型加载阶段执行一次llm_compute_wkv_b的结果写入临时 buffer推理图全程使用统一的原生wkv_b路径避免每次前向都做布局转换显式降级而非静默失败从 hparams 检测的GGML_ABORT(Fatal error)到 KV 缓存初始化的changing MLA from %d to 1所有兼容性决策都有明确的日志输出与强制约束用户可清楚看到模型处于兼容模式尽力而为的边界诚实PR 在描述、日志与社区回复中反复强调mla1的性能代价PP 降低、FA 仅限 Ampere不夸大兼容能力对于无法修复的变体如 head 参数不符的模型则直接拒绝加载防止产出错误结果。七、小结PR #394 为 ik_llama.cpp 提供了面向主流 DeepSeek GGUF 的加载期兼容层通过n_head_kv 1的 MLA 特征识别主流格式在张量加载阶段回退读取wk_b/wv_b在 CPU 上实时重建wkv_b并将 KV 缓存路径强制降级为mla1。这一机制让用户无需重新下载数百 GB 的模型文件即可运行新版 DeepSeek GGUF代价是 PP 性能与 Flash Attention 支持范围受限。对实践者的最终建议日常使用优先选择 ik_llama.cpp 原生兼容的 GGUF 并保留mla3仅在必须使用手头主流格式文件时依靠本机制兜底并配合--override-tensor专家分散、-ub大 batch 等参数尽量挽回性能。该兼容路径已合入主线是仓库处理 DeepSeek 系列外部模型的成熟标准入口。【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ik_llama.cpp 兼容主流的 DeepSeek GGUF：不兼容 MLA 张量布局的检测与自动修复实战
ik_llama.cpp 兼容主流的 DeepSeek GGUF不兼容 MLA 张量布局的检测与自动修复实战【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp导读本篇文章以 ik_llama.cpp 仓库 PR #394Handle incompatible DeepSeek GGUFs为核心讲解当 DeepSeek GGUF 模型按主流 llama.cpp 的 MLA 张量布局导出、与 ik_llama.cpp 自身格式不一致时模型加载器如何自动检测、降级并在线重建张量使模型仍可运行。读完本文你将理解 wkv_b 与 wk_b/wv_b 两种 MLA 张量布局的差异、加载期自动修复的源码实现、-mla参数各档位的含义与性能取舍以及如何在多 GPU 环境下配合--override-tensor、-fmoe、-ub、-rtr等参数调优 DeepSeek 推理。一、背景MLA 支持分叉引发的 GGUF 兼容性危机DeepSeek 系列模型DeepSeek-V2/V3/R1 及 DeepSeek-Lite采用 MLAMulti-head Latent Attention架构。ik_llama.cpp 早在主流 llama.cpp 之前约 2.5 个月就实现了 MLA 支持并采用了合并的wkv_b张量布局每层注意力用一个[kv_lora_rank, n_head * (n_embd_head_qk_nope n_embd_head_v)]的wkv_b权重完成 KV 压缩投影。而主流 llama.cpp 在 PR 12801 中加入 MLA 支持时采用了另一套布局把 KV 压缩投影拆成wk_bK 的 no-pe 部分与wv_bV 部分两个独立张量。这一改动打破了向后兼容性——在此之后Hugging Face 上陆续出现的新 DeepSeek GGUF例如 Unsloth 发布的 UD 量化都是按主流格式导出的直接导致 ik_llama.cpp 用户无法加载这些新文件对应仓库中的 issue #373DeepSeek-V3-0324 无法加载最新 UD 量化 与 issue #383加载 DeepSeek R1T Chimera 失败。PR #394 的作者 ikawrakow 起初并不打算支持这些不兼容 GGUF——毕竟让用户重新下载动辄数百 GB 的 DeepSeek-R1/V3 模型代价过高而且 MLA 所需的新张量完全可以像本仓库此前所做的那样在加载模型时即时创建。但权衡之后PR #394 最终实现了对不兼容 GGUF 的加载期自动修复。该 PR 于 2025-05-07 创建、2025-05-10 合入作者本人用与 DeepSeek-R1/V3 完全相同的注意力架构的 DeepSeek-Lite 完成了验证并在社区用户 Panchovix 的 DeepSeek-V3-0324 实测中得到确认。二、不兼容的表象与本质wkv_b vs wk_b/wv_b2.1 两种 MLA 张量布局对比以 PR 对话中 Panchovix 加载的DeepSeek-V3-0324-UD-Q2_K_XL为例模型元数据中的 MLA 关键参数为元数据键值含义deepseek2.attention.q_lora_rank1536Q 低秩投影秩deepseek2.attention.kv_lora_rank512KV 低秩投影秩deepseek2.attention.key_length576K 全长度rope 64×… no-pe 部分deepseek2.attention.value_length512V 长度deepseek2.attention.key_length_mla192MLA 中 K 的 rope 部分长度deepseek2.attention.value_length_mla128MLA 中 V 的压缩长度ik_llama.cpp 的合并布局把wk_b与wv_b合并为单个blk.N.attn_kv_b.weightwkv_b形状为[kv_lora_rank, n_head * (n_embd_head_qk_nope n_embd_head_v)]主流 llama.cpp 则是两个独立张量。两种布局在数学上等价K 的 no-pe 部分与 V 的投影结果可以直接拼接但文件层面的张量名与形状不同因此 GGUF 无法互通。2.2 社区实测中暴露的其他形状差异PR 对话中用户 whatever1983 用主流convert_hf_to_gguf.py转换 DeepSeek-V3-0324-Pruned-Coder-411B 再重量化为 IQ4K 后加载时报出llama_model_load: error loading model: check_tensor_dims: tensor blk.0.attn_q_b.weight has wrong shape; expected 1536, 73728, got 1536, 24576, 1, 1 llama_load_model_from_file: failed to load model其中 73728 128 heads × 576ik 期望 attn_q_b 输出每个 head 的完整 K 长度而 24576 128 × 192主流格式中 attn_q_b 只负责 rope 部分。这说明 MLA 的差异不只体现在wkv_bQ 投影的张量切分方式也不一致。作者对此的回应是当前 master 的convert_hf_to_gguf.py对 mergesBPE 合并规则处理不佳对应修复在 PR #377因rope_scaling张量缺失问题尚未合入因此更稳妥的做法是使用本仓库自带的 convert_hf_to_gguf.py 重新转换得到与 ik_llama.cpp 完全兼容的 GGUF。三、加载期自动修复的源码实现PR #394 的修复集中在三处超参数检测、张量加载分支、KV 缓存降级。3.1 超参数检测识别主流格式的 MLA 模型在 src/llama-hparams.cpp#L1199-L1221 的LLM_ARCH_DEEPSEEK2分支中当n_head_kv() 1MLA 的标志时加载器先验证一组可修复前提条件int expected_head_size_k model.arch LLM_ARCH_DEEPSEEK2 ? 576 : 320; int expected_head_size_v model.arch LLM_ARCH_DEEPSEEK2 ? 512 : 256; if (hparams.n_head_kv() 1) { int n_nead_kv hparams.n_gqa(); if (n_nead_kv%4 ! 0 || hparams.n_embd_head_k(0) ! expected_head_size_k || hparams.n_embd_head_v(0) ! expected_head_size_v || hparams.n_rot ! 64) { LLAMA_LOG_ERROR(\n); LLAMA_LOG_ERROR(Detected incompatible DeepSeek model without a known way to fix it.\n); ... GGML_ABORT(Fatal error); } LLAMA_LOG_INFO( Adjusted mainline llama.cpp MLA tensors to ik_llama.cpp\n); for (auto item : hparams.n_head_kv_arr) item n_nead_kv; hparams.n_embd_head_k_full 192; hparams.n_embd_head_v_full 128; ml.get_key(LLM_KV_ATTENTION_KEY_LENGTH_MLA, hparams.n_embd_head_k_full); ml.get_key(LLM_KV_ATTENTION_VALUE_LENGTH_MLA, hparams.n_embd_head_v_full); }要点可修复的前提n_gqa % 4 0、n_embd_head_k 576、n_embd_head_v 512、n_rot 64。满足这些条件说明模型是标准 DeepSeek-V2/V3/R1 类 MLA 布局加载器可以自动把 head 数调整到n_gqa并把 MLA 的 K/V 长度校准为 192/128不可修复的模型条件不满足时直接打印Detected incompatible DeepSeek model without a known way to fix it并终止加载绝不强行拼凑类似的检测逻辑也出现在 DeepSeek-V4llama-dsv4相关分支的 src/llama-hparams.cpp#L2143-L2159 中表明该机制已成为仓库处理外部 DeepSeek GGUF 的标准入口。3.2 张量加载分支wkv_b 缺失则回退到 wk_b/wv_b在 src/llama-load-tensors.cpp#L3243-L3256 中wkv_b被标记为TENSOR_NOT_REQUIRED可选张量layer.wkv_b create_tensor(wkv_b_ctx, tn(LLM_TENSOR_ATTN_KV_B, weight, i), {kv_lora_rank, n_head * (n_embd_head_qk_nope n_embd_head_v)}, llama_model_loader::TENSOR_NOT_REQUIRED); if (!layer.wkv_b) { // Incompatible mainline model. Lets see if we can still load it layer.wk_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_K_B, weight, i), {n_embd_head_qk_nope, kv_lora_rank, n_head}, 0); layer.wv_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_V_B, weight, i), {kv_lora_rank, n_embd_head_v, n_head}, 0); } else { layer.wk_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_K_B, weight, i), {n_embd_head_qk_nope, n_head * kv_lora_rank}, 1); layer.wv_b create_tensor(ctx_split, tn(LLM_TENSOR_ATTN_V_B, weight, i), {kv_lora_rank, n_head * n_embd_head_v}, 1); }逻辑很直白优先尝试读取合并的wkv_bik 原生格式若 GGUF 中不存在则按主流格式读取独立的wk_b/wv_b进入兼容模式。代码注释// Incompatible mainline model. Lets see if we can still load it与 PR 描述Will try to fix, but there are no guarantees的警示口径完全一致。3.3 在线重建从 wk_b/wv_b 计算 wkv_b兼容模式下wk_b/wv_b并不会直接参与计算而是在模型加载阶段被实时合并回wkv_b。核心函数是 src/llama.cpp#L3050-L3139 的llm_compute_wkv_b// Compute the combined wkv_b tensor of one layer from the current wk_b/wv_b // tensor data, on the CPU. static ggml_tensor * llm_compute_wkv_b(ggml_context * ctx, ggml_cgraph * graph, const ggml_tensor * wk_b_src, const ggml_tensor * wv_b_src, ...) { ... auto wkv_b_f32_3d ggml_concat(ctx, wk_b_transposed, wv_b_used, 1); ... auto new_type wk_b.type GGML_TYPE_BF16 wv_b.type GGML_TYPE_BF16 ? GGML_TYPE_BF16 : wk_b.type GGML_TYPE_F16 wv_b.type GGML_TYPE_F16 ? GGML_TYPE_F16 : GGML_TYPE_Q8_0; auto wkv_b ggml_cast(ctx, wkv_b_f32, new_type); ... ggml_build_forward_expand(graph, wkv_b); ... }实现细节值得注意若wk_b/wv_b不在 host 内存如驻留 GPU会先通过ggml_backend_tensor_get拷回临时缓冲区非 F32 权重先ggml_cast到 F32转置后沿维度 1 拼接再按源类型降级输出源为 BF16 则输出 BF16、F16 则输出 F16否则输出 Q8_0整个推导被构建成一个小型计算图约 8 个节点在 CPU 上执行结果写入tmp_buffer只在加载阶段有效不进入后续推理图由于合并在加载期一次性完成推理时依然走 ik 原生mla3的wkv_b路径——只是合并不是无损的当wk_b/wv_b本身是量化类型时合并结果统一降级为 Q8_0 精度的wkv_b而非 F32 原值。3.4 KV 缓存降级强制 mla1即使模型张量加载成功KV 缓存初始化阶段还有一个关键降级步骤。在 src/llama.cpp#L1318-L1340 的llama_kv_cache_init中bool have_wkv_b n_have_wkv_b 0; if (!have_wkv_b) { if (cparams.mla_attn ! 1) { LLAMA_LOG_WARN(\n); LLAMA_LOG_WARN(%s: missing wkv_b tensor(s)\n, __func__); LLAMA_LOG_WARN(%s: changing MLA from %d to 1\n, __func__, cparams.mla_attn); if (cparams.mla_attn 1) { LLAMA_LOG_WARN(%s: ** Prompt processing performance will be crippled **\n, __func__); } LLAMA_LOG_WARN(\n); // Sorry for the hack. auto non_cparams const_castllama_cparams(cparams); non_cparams.mla_attn 1; } }这正是 PR 描述中Big caveat的代码落点使用不兼容模型时只能运行初始版 MLAmla1即与主流 llama.cpp 相同的实现方式。用户日志中可以看到llama_kv_cache_init: missing wkv_b tensor(s) llama_kv_cache_init: changing MLA from 0 to 1四、mla 档位与不兼容模型的性能代价-mla--mla-use参数在 common/common.h#L424 中定义默认值为 3在 common/common.cpp#L1929 中解析int mla_attn 3; // MLA 0: standard, 1: MLA with K and V^T cache, 2: MLA with just K cache, 3: the best of both worlds档位含义说明0standard标准注意力不启用 MLA 专用缓存路径1K V^T 缓存等价于主流 llama.cpp 的实现方式不兼容 GGUF 被强制锁定在此档2仅 K 缓存进一步压缩缓存占用3两者结合默认档ik_llama.cpp 最优实现需要原生wkv_b布局使用不兼容 GGUF 时被锁定在mla1意味着两个直接后果PR 原文明示Prompt processing 性能低于mla3且性能退化随 KV 缓存中 token 数量的增加即上下文变长而加剧GPU Flash Attention 仅对 Ampere 及更新架构的 NVIDIA GPU 可用因为mla1的 FA 实现依赖较新的 GPU 特性。因此最理想的做法仍是使用 ik_llama.cpp 原生兼容的 GGUF用仓库自带 convert_hf_to_gguf.py 转换或用与仓库兼容的量化工具导出从而保留mla3的全部性能PR #394 的自动修复只是为手上只有主流格式大模型文件、不愿重新下载的场景兜底。五、实战加载不兼容 DeepSeek GGUF 并调优5.1 最小启动命令以 PR 对话中 Panchovix 实测通过的 DeepSeek-V3-0324 UD-Q2_K_XL 为例不兼容模型的完整加载命令为./llama-server -m /GGUFs/DeepSeek-V3-0324-UD-Q2_K_XL-merged.gguf \ -c 16384 --no-mmap --no-warmup -v -ngl 999 \ -ot blk.(0|1|2|3|4|5|6).ffn.CUDA0 \ -ot blk.(7|8|9|10).ffn.CUDA1 \ -ot blk.(11|12|13|14).ffn.CUDA2 \ -ot blk.(15|16|17|18|19|20|21|22|23|24).ffn.CUDA3 \ -ot ffn.*CPU -fmoe -mla 1各参数说明-ngl 999尽可能多的层卸载到 GPU-ot patternDEVICE--override-tensor按正则把指定张量强制分配到某块 GPU这里把不同层区间的 MoE 专家*.ffn.*分散到 4 块 GPU剩余专家留在 CPU-fmoe启用融合 MoEfused MoE内核-mla 1显式声明使用mla1档加载不兼容模型时即使不指定也会被强制降级。加载成功的标志性日志序列如下节选自 PR 实测输出Detected incompatible DeepSeek model. Will try to fix, but there are no guarantees *** Your prompt processing speed will be crippled *** Consider making your own ik_llama.cpp compatible model or ask the model provider to make one for you, ... llama_kv_cache_init: missing wkv_b tensor(s) llama_kv_cache_init: changing MLA from 0 to 1第一段警告来自张量加载阶段检测到无wkv_b第二段来自 KV 缓存初始化确认降级到mla1。看到这两段后模型仍能正常加载并生成即代表自动修复生效。5.2 与主流 llama.cpp 的对比命令Panchovix 在主流 llama.cpp 上的等价命令同样用张量覆盖实现专家分散./llama-server -m /GGUFs/DeepSeek-V3-0324-UD-Q2_K_XL-merged.gguf \ -c 16384 --no-mmap --no-warmup -ngl 99 \ --override-tensor blk\.([0-7])\..*_exps\.CUDA0 \ --override-tensor blk\.([8-9]|1[0-1])\..*_exps\.CUDA1 \ --override-tensor blk\.(1[2-6])\..*_exps\.CUDA2 \ --override-tensor blk\.(1[7-9]|2[0-6])\..*_exps\.CUDA3 \ --override-tensor blk\..*_exps\.CPU -mg 0 -fa --ubatch-size 1024注意两者在提示词处理PP性能上的差异有明确的架构原因作者在对话中解释主流 llama.cpp 会把驻留 RAM 的张量也搬运到 GPU 做矩阵乘法而 ik_llama.cpp 对驻留 RAM 的张量在 CPU 上做矩阵乘法。因此CPU 较弱 VRAM 充足 PCIe 带宽高 大 batch的场景下主流实现占优而在CPU 强 / KV 缓存长 / 专家矩阵巨大的场景下不搬运反而减少 PCIe 流量ik_llama.cpp 更有利。作者随后在对话中透露PR #405 为 ik_llama.cpp 增加了反向开关强制把 RAM 中的张量卸载到 GPU 计算并建议想压榨 PP 性能时用尽可能大的 u-batch且不要加-rtr实时重打包会禁用专家张量的 GPU 卸载。5.3 进一步调优建议综合 PR 对话中的实测经验可提炼出以下可复现的调优点增大 u-batch-ub 1024把 PP 从 66 t/s 提升到 100 t/s-ub 1536进一步提升到约 126 t/s主流 llama.cpp 侧实测配合-rtr可进一步改善 PP但会禁用专家 GPU 卸载需按 5.2 的取舍选择合理分配专家张量MoE 专家ffn_*_exps是 DeepSeek 模型的体积大头用--override-tensor/-ot按正则把不同层区间映射到不同 GPU尽量填满每张卡的显存余量关注加载顺序若 GPU 主卡在加载时未被优先填充日志中CPU buffer size先出现PP 性能会明显下滑——这在主流 llama.cpp 上同样存在属于加载分配顺序问题而非模型兼容性问题KV 缓存占用mla1模式仍会存储 V 缓存而 ik 原生mla2/3可省去 V 缓存因此不兼容模型还会多占用一部分显存可据此评估是否上调-ub。六、从源码结构看兼容性机制的整体设计纵观整个兼容层可以总结出三点设计思路从源码结构推断加载期一次性修复推理期零开销wkv_b的合并只在模型加载阶段执行一次llm_compute_wkv_b的结果写入临时 buffer推理图全程使用统一的原生wkv_b路径避免每次前向都做布局转换显式降级而非静默失败从 hparams 检测的GGML_ABORT(Fatal error)到 KV 缓存初始化的changing MLA from %d to 1所有兼容性决策都有明确的日志输出与强制约束用户可清楚看到模型处于兼容模式尽力而为的边界诚实PR 在描述、日志与社区回复中反复强调mla1的性能代价PP 降低、FA 仅限 Ampere不夸大兼容能力对于无法修复的变体如 head 参数不符的模型则直接拒绝加载防止产出错误结果。七、小结PR #394 为 ik_llama.cpp 提供了面向主流 DeepSeek GGUF 的加载期兼容层通过n_head_kv 1的 MLA 特征识别主流格式在张量加载阶段回退读取wk_b/wv_b在 CPU 上实时重建wkv_b并将 KV 缓存路径强制降级为mla1。这一机制让用户无需重新下载数百 GB 的模型文件即可运行新版 DeepSeek GGUF代价是 PP 性能与 Flash Attention 支持范围受限。对实践者的最终建议日常使用优先选择 ik_llama.cpp 原生兼容的 GGUF 并保留mla3仅在必须使用手头主流格式文件时依靠本机制兜底并配合--override-tensor专家分散、-ub大 batch 等参数尽量挽回性能。该兼容路径已合入主线是仓库处理 DeepSeek 系列外部模型的成熟标准入口。【免费下载链接】ik_llama.cppllama.cpp fork with additional SOTA quants and improved performance项目地址: https://gitcode.com/GitHub_Trending/ik/ik_llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
