support-new-llm

name	support-new-llm
description	为 MNN 框架添加新的 LLM 模型支持。支持从 HuggingFace/ModelScope 下载模型，分析架构，添加映射，Hook 对齐测试，导出 MNN 模型。采用 TDD 模式，分 6 步执行，每步有独立测试标准。

MNN LLM 新模型支持 SKILL

触发条件：当用户请求支持/添加/适配一个新的 LLM 模型时触发。常见表述包括："支持xxx模型"、"添加xxx模型支持"、"适配xxx"、"导出xxx模型"等。

概述

本 SKILL 指导 AI Agent 为 MNN 框架添加新的 LLM 模型支持。整个流程采用 TDD（测试驱动）模式，每一步都有明确的测试标准，必须通过当前步骤的测试后才能进入下一步。

核心思路

MNN 的模型导出本质上是对照 HuggingFace transformers 库中原始模型的实现代码，将其计算逻辑映射到 MNN 的统一框架中。核心步骤是：

1. 读懂 HF 模型的 config.json 和 modeling_*.py
2. 在 model_mapper.py 中注册字段映射
3. 用 Python --test 验证映射正确性
4. 导出 MNN 模型并用 C++ 引擎验证

注意事项

🚨 严禁将输出错误归因于"量化精度不够"：4bit 量化的 0.5B 小模型都能正确输出。如果 C++ 输出完全不对（如图片识别不出、输出乱码），一定是实现细节没有与 HF 对齐，必须逐步 dump 数据对比定位，不要靠猜。

🚨 测试标准要有定力：每步的通过标准是明确的（如"C++ 能正确描述图片内容"），不能因为"差不多能跑"就跳过。"能感知到一些信号但描述不准确"不等于通过，必须达到与 HF 模型相当的输出质量才算完成。

🚨 多模态/embedding 对齐先看 C++ 端真实输入输出：不要只比 Python 导出逻辑。先直接打印并比对 C++ 运行时的 chat template、token ids、以及必要时的中间输入，确认 runtime tokenizer/Jinja/post_processor 与 HuggingFace 完全一致，再继续看视觉或量化路径。

🚨 改导出模板先做“临时 config 覆盖”验证：当修改 llm_config.json / config.json 里的 jinja.chat_template 时，不要一上来全量重导出模型。先用现有 MNN 模型目录配一个临时 config.json 覆盖 base_dir + jinja/context，直接跑 C++ llm_demo/embedding_demo 验证 prompt token 数、构造出的语义和最终结果是否与基线一致，再决定是否全量 re-export。

🚨 ASR 模型默认按单轮接口设计：除非用户明确要求多轮 ASR 会话，否则用户侧一次 response 结束后就应立即 reset 清空状态，不要把 ASR prompt/template 设计成依赖 trailing assistant、多轮裁剪或 prompt-cache 续写的形态。

严禁访问以下目录：schema/private/ 和 source/internal/，包含内部私有代码，不得读取、修改或引用。

多模态/音频子模块跑通后要及时回收临时代码：新增 talker/token2wav/codec 等导出 wrapper 时，优先复用已有 Decoder、Rotary、FakeLinear、RMSNorm、onnx_export 等导出原语；只为权重命名或外部包加载保留最小 skeleton，避免固化第二套 LLM 导出框架。

外部包恢复可 import 后要删除兼容绕路：如果前期因为依赖版本问题临时使用 importlib.util 按路径加载模型源码、stub module、monkey patch transformers API，依赖修好后必须改回官方 package import，并用完整 llmexport.py --export mnn 验证。

导出后必须检查 .mnn 本体是否残留大权重：使用 MNNDump2Json 按 Const 数据量排序；如果 .mnn 内出现 embedding、lm/head、projection 等大 Const，说明没有走 FakeLinear/外置 embedding/.mnn.weight 路径，不能只因为生成了 .mnn.weight 就认为权重已正确外置。

禁止猜测：如果不确定某个字段名或路径，必须通过工具读取实际文件确认。

---

核心文件清单

文件路径	作用	修改频率
transformers/llm/export/utils/model_mapper.py	模型字段映射	几乎每个新模型
transformers/llm/export/utils/model.py	统一模型类 LlmModel	偶尔
transformers/llm/export/utils/transformers.py	Attention/Decoder/Rotary 等组件	新架构时
transformers/llm/export/utils/config.py	模型配置类 LlmConfig	偶尔
transformers/llm/export/utils/vision.py	Vision Encoder 实现	视觉模型
transformers/llm/export/utils/audio.py	Audio Encoder 实现	音频模型
transformers/llm/export/utils/custom_op.py	自定义算子导出	新算子时
transformers/llm/export/llmexport.py	导出主流程入口	偶尔

---

分步流程总览

整个流程分为 6 个步骤，每个步骤都有独立的文档和测试标准：

┌──────────────────────────────────────────────────────────┐
│  步骤 1: 下载、理解与测试模型 (step1-analyze.md)           │
│  输入: 模型链接(HF/ModelScope)或本地路径                   │
│  输出: 模型下载到本地 + transformers 推理成功               │
│       + 架构分析完成 + Tier 判定                           │
│  测试: test_origin.py 输出正确 + 5 个架构问题已回答        │
├──────────────────────────────────────────────────────────┤
│  步骤 2: 添加映射 (step2-mapping.md)                      │
│  输入: 步骤1的差异清单                                     │
│  输出: model_mapper.py 中的新映射                          │
│  测试: LlmModel.from_pretrained 加载不报错                 │
├──────────────────────────────────────────────────────────┤
│  步骤 3: Hook 对齐测试 (step3-test-python.md)             │
│  输入: 步骤1的原始模型结果 + 步骤2的 LlmModel              │
│  输出: Hook 中间结果数值对齐                               │
│  测试: 5 个检查点(embed/layer0/lastlayer/norm/logits)一致  │
├──────────────────────────────────────────────────────────┤
│  步骤 4: 导出与 C++ 测试 (step4-export.md)                │
│  输入: 步骤3通过                                           │
│  输出: MNN 模型文件                                        │
│  测试: C++ llm_demo 输出正确                               │
├──────────────────────────────────────────────────────────┤
│  步骤 5: 视觉/音频支持 (step5-multimodal.md)              │
│  输入: 仅 Tier 4/5/6 需要                                  │
│  输出: vision.py 或 audio.py 中的新子类                    │
│  测试: 多模态推理测试通过                                   │
├──────────────────────────────────────────────────────────┤
│  步骤 6: 特殊架构支持 (step6-new-architecture.md)         │
│  输入: 仅 Tier 6 需要                                      │
│  输出: 新算子 + C++ 实现                                   │
│  测试: 全链路测试通过                                       │
└──────────────────────────────────────────────────────────┘

步骤选择指南

不是所有步骤都需要执行。 根据步骤 1 判定的 Tier，选择需要执行的步骤：

Tier	需要执行的步骤	说明
Tier 1 (纯文本 Llama-like)	1 → 2 → 3 → 4	最简单，仅需映射
Tier 2 (轻微架构差异)	1 → 2 → 3 → 4	可能需要修改 transformers.py
Tier 3 (MoE 模型)	1 → 2 → 3 → 4	需要 mlp/expert 映射 + routing 实现，参见 common-pitfalls.md 第 9 节
Tier 4 (音频模型)	1 → 2 → 3 → 5 → 4	需要 audio.py
Tier 5 (视觉模型)	1 → 2 → 3 → 5 → 4	需要 vision.py
Tier 6 (全新架构)	1 → 2 → 6 → 3 → 4	需要新算子（如叠加 Tier 4/5 则加入 step5）

---

Tier 判定速查

根据 config.json 中的字段快速判定 Tier：

config.json 中是否有 num_experts 或 num_local_experts?
├─ 是 → Tier 3 (MoE)
└─ 否 → 继续

config.json 中是否有 vision_config?
├─ 是 → Tier 5 (视觉)
└─ 否 → 继续

config.json 中是否有 audio_config?
├─ 是 → Tier 4 (音频)
└─ 否 → 继续

layer_types 中是否有非 Attention 层（如 conv / mamba / rwkv）?
├─ 是 → Tier 6 (混合架构，如 lfm2 的 conv + full_attention)
└─ 否 → 继续

modeling_*.py 中是否有全新的 Attention 类型（非标准 SDPA）?
├─ 是 → Tier 6 (新架构，如 qwen3_5 的 gated_delta_rule)
└─ 否 → 继续

是否有额外 LayerNorm / scale_depth / scale_emb / 没有 post_attention_layernorm?
├─ 是 → Tier 2 (轻微差异)
└─ 否 → Tier 1 (标准 Llama-like)

注意：Tier 可以叠加。例如 MoE + 视觉 = Tier 3+5，需要同时执行对应步骤。

Tier 叠加时的执行顺序

当模型跨多个 Tier 时，按以下原则确定步骤顺序：

叠加	执行顺序	说明
Tier 3+6 (MoE + 新架构)	1 → 2 → 6 → 3 → 4	先支持新架构（如 short_conv），再加 MoE routing
Tier 3+5 (MoE + 视觉)	1 → 2 → 3 → 5 → 4	MoE 是 text-only，视觉单独加
Tier 5+6 (视觉 + 新架构)	1 → 2 → 6 → 5 → 3 → 4	先支持新架构，再加视觉

原则：Tier 6（新架构）最先实现，因为它影响基础层结构；Tier 3（MoE）次之，因为它在 Tier 6 层结构之上；Tier 4/5（多模态）最后，因为它与层结构独立。

---

已支持模型速查表

收到新模型请求时，先查 config.json 的 model_type，在下表中搜索。如果已存在则无需修改。

model_type	Tier	类型
llama, qwen2, internlm, mobilellm	1	文本
baichuan	1	文本 (fused QKV)
qwen	1	文本 (Qwen1)
qwen3	1	文本 (q/k norm)
chatglm, chatglm2	1	文本 (特殊 RoPE)
phi-msft, phi	1	文本
gemma2	2	文本 (额外 LayerNorm)
gemma3_text	2	文本
minicpm	2	文本 (scale_depth)
gpt_oss	3	MoE (topk → softmax)
qwen3_moe	3	MoE (softmax → topk)
lfm2_moe	3+6	MoE (sigmoid routing) + 混合架构 (short_conv)
qwen2_audio	4	音频
funaudiochat	4	音频
lfm2_audio	4+6	音频 (FastConformer + MLP adapter) + 混合架构
qwen2_vl, qwen2_5_vl, qwen3_vl	5	视觉
internvl_chat	5	视觉
gemma3	5	视觉
gemma4	5	视觉 (PLE + KV共享 + 双Rotary + patch-based vision)
glm_ocr	5	视觉 (Gemma2残差 + interleaved M-RoPE)
smolvlm	5

---

常见陷阱

在开始之前，建议先浏览 common-pitfalls.md，了解已知的常见问题和解决方案（RoPE 变体、dtype 级联、Jinja 限制、tokenizer post_processor 对齐、stop token、残差模式、MoE 支持要点、FakeLinear axis 陷阱、do_map 静默失败与 rope_theta 间接存储、非标准模型加载等）。

---

开始执行

现在请打开 skills/support-new-llm/step1-analyze.md，开始步骤 1。