• 大模型
• 基础模型
• 模型优化
• 模型压缩
• Qwen

本文以开源项目Qwen2.5-7B-base-mla-topk8-rank128为例，带你完整走一遍 MLAfication 改造流程：如何把一个使用 GQA（分组查询注意力）的开源模型，仅修改注意力模块就升级为 MLA（Multi-head Latent Attention，多头潜在注意力），并理解这个 1.38 GiB 注意力增量权重（delta weights）里到底装了什么、如何加载、以及如何把同样的方法复用到任意 GQA 模型上。

为什么要把 GQA 模型改造成 MLA？

先搞清楚两种注意力的差别，你才能明白这套改造的价值：

换句话说：GQA 已经省了一部分，MLA 把 KV 缓存进一步"压缩存储"——只存低秩潜在表示，K 和 V 用的时候再现场解出来。

而 MLAfication 的巧妙之处在于：不需要从零预训练一个新 MLA 模型。它把现成 GQA 模型的注意力模块"手术式"替换成 MLA 结构，只重训注意力相关的参数（其他模块全部冻结），用少量训练步数让新结构"蒸馏"出与原模型相近的行为。这就是本项目 README 中提到的stage1+2-distill-QKV训练变体的含义。

仓库里装了什么：336 个注意力增量权重

⚠️ 先说重点：这个仓库不是完整的模型检查点，它只包含注意力部分的增量权重。完整模型 = Qwen2.5-7B 官方权重 + 本仓库的 delta 权重。

仓库共 4 个文件，各司其职：

• model.safetensors：注意力增量权重（336 个张量，BF16，约 1.38 GiB）
• config.json：基础架构参数 + 逐层 RoPE 索引 + MLAfication 元数据
• manifest.json：来源信息、字节大小、张量数量、SHA-256 校验和
• README.md：使用说明与变体信息

关键变体信息一览（来自 README.md）：

打开 manifest.json 可以看到 delta 里张量的 12 种后缀，它们正好对应 MLA 注意力模块的新结构（每层 12 个 × 28 层 = 336）：

kv_proj.down_kv.weight # 隐藏层 → 低秩潜在向量（压缩） kv_proj.up_kc.weight # 潜在向量 → 内容部分 K kv_proj.up_v.weight/bias # 潜在向量 → V self_attn.q_proj.* # 原 Q 投影（保留） self_attn.q_c_proj.* # Q 的内容部分投影 self_attn.q_r_proj.* # Q 的 RoPE 低维部分 self_attn.k_r_proj.* # K 的 RoPE 低维部分

manifest.json中的attention_only_verification字段还说明了训练纪律：训练时冻结了所有非注意力参数，且连注意力的输出投影o_proj也冻结了，所以 delta 严格只包含名字里带attn且不带o_proj的参数；嵌入层、MLP、LayerNorm、LM Head 一律没动。

MLAfication 如何改写注意力结构

理解了上面 12 个张量，你就理解了整个改造的核心。一次前向传播的数据流变化如下：

改造前（GQA）：X → q_proj → Q，X → k_proj → K，X → v_proj → V，RoPE 直接作用在完整的 K 上，KV Cache 存的是完整 K/V。

改造后（MLA，rank128 / topk8）：

1. X → down_kv → c_kv（128 维潜在向量，KV Cache 只存它）
2. c_kv → up_kc / up_v反投影出 K 的内容部分和 V
3. RoPE 不再作用于整个 K，而是只作用在每头 8 维的旋转子空间（q_r_proj、k_r_proj负责这部分）
4. Q 同样拆成"内容部分 + 旋转部分"两路（q_c_proj、q_r_proj）

这样 KV Cache 从"存 1024 个数/token"变成"存 128+32 个数/token"，而模型容量由 rank=128 的潜在空间承载——用小得多的存储换取几乎无损的注意力计算。

另外注意 config.json 里那份很长的rope_indices：它是逐层、逐头记录的 RoPE 频率索引，由 MLAfication 工具在转换时生成，加载时必须原样保留，这也是"加载前必须先打好架构补丁"的原因之一。

加载教程：三步还原 MLA 模型

第一步，克隆本仓库获取 delta 权重：

git clone https://gitcode.com/OpenMOSS/Qwen2.5-7B-base-mla-topk8-rank128

第二步，准备 Qwen2.5-7B 的官方基础权重（模型卡中锁定的 revision 为d149729398750b98c0af14eb82c78cfe92750796）。

第三步，先打架构补丁，再加载 delta（顺序不能反）：

from safetensors.torch import load_file # 用 MLAfication 实现基于锁定版本的 Qwen2.5-7B 实例化 MLA 架构 # （即：把注意力模块替换为 MLA 结构后得到 mla_model） delta = load_file("model.safetensors") load_result = mla_model.load_state_dict(delta, strict=False)

这里strict=False是刻意为之：delta 只覆盖 336 个注意力张量，嵌入层、MLP 等冻结参数直接沿用基础模型的权重，跳过即可。

通用工作流：把任意 GQA 模型改造成 MLA 的 5 个步骤

本仓库是一个"成品 delta"，但整个方法可以套用到任何 GQA 模型（Llama 系、Qwen 系等都适用），通用流程如下：

1. 选定基础模型并锁定 revision。在config.json的mha2mla元数据中记录base_model_name_or_path和base_model_revision，保证 delta 与基础权重严格对应、可复现。
2. 打架构补丁。用 MLAfication 实现把每层的q/k/v_proj替换为上述 12 个新投影，并生成逐层rope_indices写回 config。
3. 智能初始化。新投影的权重不是随机初始化，而是从原 GQA 权重因子化分解而来，让改造后的模型在训练前就尽量接近原模型行为。
4. 注意力专属训练（surgical training）。冻结所有非注意力参数（含o_proj、MLP、嵌入），只用蒸馏方式训练注意力参数若干步（本项目为 4800 步），让 MLA 结构"学会"复刻原模型的注意力输出。
5. 导出注意力增量 delta。只保存名字匹配"attn" in name and "o_proj" not in name的参数，生成带 SHA-256 校验的manifest.json，体积小、易分发、易复现。

这套"补丁 + 增量权重"的交付方式正是本仓库的组织形式，也方便你为自己的 GQA 模型复刻同样的一套。

参数怎么选：rank 与 rope_topk

名字mla-topk8-rank128里的两个数字就是改造的核心旋钮：

• rank（潜在秩，本项目为 128）：决定 KV 潜在向量的维度。rank 越大，表达能力越强、KV 缓存越接近原始精度，但压缩率下降。7B 级别模型取 128 是精度与压缩率的折中；更大模型通常可以取更大的 rank。
• rope_topk（RoPE 维度，本项目为 8）：RoPE 只保留在每 KV 头的 8 维低维子空间上。这是 MLA 的标志性设计——位置编码不需要整个 128 维，低维就足够保留位置信息。

调整这两个参数重新训练后，delta 张量个数不变（仍是每层 12 个），但每个张量的形状随之变化，manifest.json的字节数与校验和也会不同，记得同步更新。

文件清单与完整性校验

下载后建议先核对完整性（数值来自 manifest.json）：

校验命令示例：

sha256sum model.safetensors

新手必读：4 个常见坑

1. 不能直接用AutoModelForCausalLM.from_pretrained加载本仓库——它不是完整模型，必须先按 MLAfication 架构实例化再加载 delta。
2. 顺序问题：架构补丁要在加载 delta 之前完成，否则张量形状对不上。
3. 基础版本必须一致：delta 是针对锁定 revision 的 Qwen2.5-7B 训练的，换别的 Qwen2.5-7B 版本可能导致行为异常。
4. strict=False不是偷懒：加载结果里"跳过"的参数恰好就是被冻结的嵌入、MLP 等模块，属正常现象；但 delta 内的 336 个张量必须全部命中，否则说明架构补丁有误。

小结

Qwen2.5-7B-base-mla-topk8-rank128 展示了一种高效的模型改造范式：不重新预训练，只用 1.38 GiB 的注意力增量权重 + 4800 步蒸馏训练，就把 GQA 模型升级为 MLA 注意力，换来约 6 倍以上的 KV Cache 压缩。而这套"补丁架构 → 智能初始化 → 冻结注意力外参数 → 导出 delta"的方法论，可以平滑迁移到任何 GQA 模型——这正是 MLAfication 的魅力所在 🚀。

• 大模型
• 基础模型
• 模型优化
• 模型压缩
• Qwen