| 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 的统一框架中。核心步骤是：
- 读懂 HF 模型的
config.json 和 modeling_*.py
- 在
model_mapper.py 中注册字段映射
- 用 Python
--test 验证映射正确性
- 导出 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。
