22.3 算子与模型结构适配：先做清单再改代码
GPU/NPU 软件栈、算子迁移、精度定位与验收
从计算图列出 Linear/MatMul、RMSNorm、RoPE、Attention、Softmax、SiLU、TopK/Sampling、KV 读写和集合通信；逐项记录输入输出 shape/dtype/stride/layout、是否支持动态 Shape、目标设备实现和回退路径。对每个不支持的算子按“现成 NPU 实现 → 算子拆解 → 自定义 Kernel”选择，并记录拆解后是否引入额外搬运、同步或精度误差。
新模型接入推理框架还需要走完 Model Config → Architecture 注册 → Weight Loader → Layer/Attention 实现 → KV Cache 规格 → Kernel/Backend → Sampler。先读配置中的层数、hidden size、Q/KV head 数、head dim、RoPE 类型和上下文上限，再核对 checkpoint key 到目标参数的映射：融合 QKV 或 Gate/Up 时，拼接顺序、转置方向和 TP 分片轴必须一致。接着以固定输入检查 embedding、每层输出、logits；分别验证 Prefill 与逐 Token Decode，并核对 tokenizer、chat template、mask、position_id、GQA/MQA head 映射、KV 布局和采样配置。模型能加载权重并生成文本，只证明入口打通；是否正确要由这些中间结果和任务指标证明。DeepSeek-V4/V4.1 一类新架构还需核对压缩组尾部、SWA 状态、跨层 KV 引用及 Replay，见第 23 章。
| 模型特性 | 适配时要核对的语义 | 常见故障表现 |
|---|---|---|
| GQA/MQA | Q Head 与 KV Head 映射、KV 缓存布局 | 某些 Head 的 logits 错、长上下文才错 |
| MLA / 特殊 Attention | 压缩与解压路径、mask、位置编码、缓存格式 | Prefill 对而 Decode 错 |
| RoPE / MRoPE | 配对布局、position_id、多轴位置 | 首轮正常，Prefix/分块/多模态错误 |
| MoE | Router Top-K、Expert 排布、Token 重排与还原 | 并发或多卡时输出错/通信慢 |
| MTP / 特殊解码 | 额外预测头、候选 token 验证、状态推进 | 生成位置错位或接受率异常 |
| 动态 Shape | 编译缓存、padding、尾块 mask、layout 转换 | 某些 batch/长度才报错或重编译 |
适配顺序：先保证 eager、单卡、FP32/BF16 reference 路径正确；再接 KV Cache 与分块/并发；最后启用融合、量化、Graph 与多卡。这样每一步都能知道是哪项变化引入分歧。特殊结构（如 Gated DeltaNet）应先对照模型定义核对状态更新，再判断现有 Attention Kernel 是否适用，不能按普通 Transformer 路径硬套。