mcgatom/codex-cannbot/model-infer-runtime-debug

NPU 推理运行时错误诊断与修复

核心理念：先定位再修复。不覆盖精度问题，精度调优见 model-infer-precision-debug。 —— 通过二分法逐步缩小故障范围，避免在错误方向浪费时间。

部署模式适配：诊断流程对框架部署 / 独立部署两模式均适用，差异点：

- 启动协议：框架部署走 cann-recipes-infer/executor/scripts/function.sh::launch 多卡 fork python；独立部署走 torchrun --nproc_per_node=N infer.py。卡住 / crash 时先确认进程模型对应。

- 通信组管理：框架部署由 executor.core.config.comm_manager.CommManager 一次性建组，模型类用 comm_manager.get_group(name)；独立部署 Runner 内 inline ParallelContext，对外接口对齐 get_group(name) / get_group_name(name) / get_rank(name)。HCCL 错误诊断时确认是哪条路径。

- KV cache 接入：框架部署由 cann-recipes-infer/executor/core/kv_cache/ 自动管理 cache_entries / block_table[attn_type] / slot_mapping[attn_type]；独立部署 Runner 自管 KV tensor + block_table + slot_mapping。详见 model-infer-kvcache。

- 权重加载：框架部署 enable_online_split_weight: True 由 ParallelLinear.weight_loader 自动按 rank 切；独立部署 Runner 自管或调 executor.model_loader.weight_utils.default_weight_loader。

诊断路径总览

问题发生
  │
  ├── 有明确错误信息 → 通用诊断流程
  │     ├── aicore timeout (507014) → 二分法定位
  │     │     ├── 定位到阶段 → 层 → 模块 → 算子
  │     │     └── 查表「常见算子约束」→ 修复策略 → 验证
  │     ├── OOM → 检查参数量 / batch_size / seq_len / 中间 buffer
  │     ├── Shape 不匹配 → 检查 TP/EP 切分维度 / Prefill vs Decode 分支
  │     └── HCCL timeout → 检查各 rank 代码路径一致性 / 通信组创建
  │
  └── 无明确错误 → npu-smi 状态检查
       ├── 部分 rank 缺失 / HBM 不均 → 多卡部署诊断
       │     ├── 权重加载 crash → TP 切分越界 / vocab pad
       │     ├── Config 字段缺失 → Config 兼容性
       │     └── 静默失败 → 逐 rank 检查日志
       ├── 有进程 + HBM 不变 + CPU 100% → 推理卡住诊断 - 模型构造阶段
       ├── 有进程 + HBM 不变 + CPU 0% → 推理卡住诊断
       │     ├── 检查残留进程
       │     ├── eager 也卡 → sync+print 定位（通用流程第二步）
       │     └── 仅 graph 卡 → 比较 eager/graph 代码路径差异
       └── 0 进程 → 查 rank 0 日志 → 通用诊断流程

npu-smi 状态检查

当没有明确错误信息时，通过设备状态判断问题类型：

npu-smi info

通用诊断流程

适用于有明确错误信息的场景（aicore timeout、HCCL error、OOM、shape mismatch 等）。按分类 → 定位 → 查表 → 修复 → 验证线性推进。

第一步：错误分类

拿到错误信息后，先判断属于哪一类。不同类别的根因和排查路径完全不同，分类错误会浪费大量时间。

A. aicore timeout（错误码 507014）

特征：AclrtSynchronizeDeviceWithTimeout、error code is 507014、aicore timeout、fftsplus aivector error、Kernel task happen error, retCode=0x25

含义：某个 NPU 算子在设备上执行时超时未返回。这是最常见也最难排查的错误，因为报错的位置（synchronize 调用处）通常不是出错的位置（某个具体算子）。

常见根因：

• 算子入参违反硬件约束（如 A2 上 MC2 要求 experts_per_rank <= 24，见「常见算子约束」）
• 算子 shape 超出硬件限制（如单次 matmul 的 M/N/K 维度超限）
• 死锁：部分 rank 走了不同的通信路径，导致集合通信永远等不齐
• 内存越界：slot_mapping/block_table 索引超出 KV cache 分配范围

B. HCCL 通信错误

特征：HCCL_CONNECT_TIMEOUT、HCCL error、AllReduce/AllToAll timeout、HCCL_EXEC_TIMEOUT

含义：分布式通信操作超时或失败。

常见根因：

• 各 rank 进入通信操作的顺序/次数不一致（代码分支导致部分 rank 跳过某次通信，常见于 modeling forward 内有 if forward_metadata.is_prefill 等分支）
• 通信组创建时参数错误：框架部署核查 CommManager.initialize() 的 group_stride / group_num；独立部署核查 ParallelContext.build_parallel_context() 内 init_comm_group 调用参数
• MoE EP 场景缺 moe_ep_group_name：dispatch_v2 / combine_v2 算子要求 HCCL group name，框架部署用 comm_manager.get_group_name("moe_ep_group")；独立部署用 parallel_ctx.get_group_name("moe_ep_group")
• 网络问题（跨节点时 HCCL_IF_IP 配置错误）
• HCCL_BUFFSIZE 不足（大 batch / 大 hidden_size 的 dispatch/combine 失败）—— 调高至 512MB 试试
• 某些 rank 已经 crash 但其他 rank 还在等它参与通信

C. OOM（显存不足）

特征：NPU out of memory、Tried to allocate X GiB、ENOMEM

含义：NPU HBM 不够。

常见根因：

• 模型参数/KV cache/activation 总和超过单卡显存
• 中间 tensor 未及时释放（常见于 MoE EP all-to-all 中间 buffer）
• batch_size 或 seq_len 超出预期
• migrator 阶段单卡 OOM：编排层会标记"需多卡"，并行化（parallel-impl skill）后再补采基线，不是必修问题

D. Shape 不匹配

特征：RuntimeError: shape mismatch、expected size X but got Y、mat1 and mat2 shapes cannot be multiplied

含义：tensor 维度不对。

常见根因：

• TP 切分后维度未正确除以 tp_size：核对 ParallelLinear 的 tp_size / tp_rank（标准用 comm_manager.get_rank("attn_tp_group") / parallel_ctx.get_rank("attn_tp_group") 等取，避免硬编码）
• KV cache 的 num_head 字段：必须用 num_kv_heads_per_rank = max(num_kv_heads // attn_tp_size, 1)，与 parallel-impl skill attn_tp_size 改动联动
• EP 切分后每卡专家数计算错误：检查 experts_per_rank = num_experts // ep_size
• Prefill/Decode 分支传入了错误 shape 的 tensor（阶段分支统一用 forward_metadata.is_prefill）
• packed sequence 协议错误：modeling 内 hidden_states 被 reshape 成 [B, S, H]（变长 batch 不能简单 reshape，应保持 [TotalTokens, hidden_size] 二维，详见 model-infer-kvcache §3.1）
• 多 attn_type 混合模型：误把 block_table 当 plain Tensor 传给 FA，应该取 block_table[self.attn_type]（dict 索引）

E. 算子约束违反

特征：不直接报约束错误，通常表现为 aicore timeout 或 SIGABRT。需要通过二分法定位后，查阅算子文档确认。

含义：NPU 自定义算子对入参有隐含约束（数据类型、维度范围、硬件平台限制），违反时行为未定义。

第二步：二分法定位（sync+barrier 检查点法）

核心方法。当错误发生在 torch.npu.synchronize() 时，错误信息只告诉你"设备上有东西出错了"，不告诉你具体哪个算子。通过插入检查点逐步缩小范围。

2.1 定位到阶段（Prefill vs Decode）

在 runner 的 model_inference 方法中，prefill 和 decode 调用之间插入同步检查：

# 在 prefill 之后、decode 之前
torch.npu.synchronize()
logging.info("prefill passed")

关键陷阱：NPU 操作是异步的。model.prefill() 返回不代表 prefill 完成 —— 只有 torch.npu.synchronize() 返回才代表所有已提交的操作完成。所以报错位置（synchronize 调用处）不一定是出错位置（某个具体算子）。确保检查点覆盖所有可能的异步操作。

2.2 定位到层

确认出错阶段后（如 Decode），在每个 decoder layer 之间插入检查点：

for i, layer in enumerate(self.layers):
    hidden_states = layer(hidden_states, ...)
    torch.npu.synchronize()
    logging.info(f"layer {i} passed")

如果 Layer 0 就超时 —— 问题在第一层内部。如果 Layer 2 超时 —— 问题在第 2 层或其子模块。

2.3 定位到模块

进入出错层，在各子模块之间插入检查点：

# 在 DecoderLayer.forward 中
hidden_states = self.input_layernorm(hidden_states)
torch.npu.synchronize(); logging.info("  norm passed")
hidden_states = self.self_attn(hidden_states, ...)
torch.npu.synchronize(); logging.info("  attention passed")
hidden_states = self.mlp(hidden_states)  # MoE
torch.npu.synchronize(); logging.info("  MoE passed")

2.4 定位到算子

进入出错模块，在每个 NPU 算子调用之间插入检查点。此时通常可以定位到具体算子及其入参，结合下文「常见算子约束」判断根因。

2.5 注意事项

• 先用 `torch.npu.synchronize()` 做单卡定位，确认是哪个算子出错。不要一开始就加 dist.barrier()——barrier 会在某 rank 已崩溃时导致其他 rank 永久挂起
• 怀疑多 rank 不同步时，用 dist.barrier() 或 torch.distributed.monitored_barrier() 确认各 rank 是否走到同一位置。monitored_barrier 在超时后会报告哪个 rank 未到达
• 查看所有 rank 的日志，确认各 rank 到达的检查点是否一致（不一致说明有条件分支差异 → 通信死锁）
• 不要一次插入太多检查点 —— 每次 sync 有开销，且大量 sync 可能改变时序。先粗粒度，再细粒度
• 保留日志：把每轮定位的检查点输出保存，供后续分析

第三步：常见 NPU 算子约束速查

以下约束来自本仓实际调试经验，定位到具体算子后应回到当前调用的 API 签名和官方文档核对，不要跨算子套用规则。违反约束的典型表现是 aicore timeout。

MoE 相关算子

FA (Flash Attention) 算子

actual_seq_lengths 相关参数以"当前调用算子的签名与官方 API 文档"为准，不跨算子套用规则：

- torch_npu.npu_fused_infer_attention_score / torch_npu.npu_fusion_attention：actual_seq_lengths* 为 List[int]（文档为 int64 语义）

- torch_npu.npu_kv_quant_sparse_flash_attention：actual_seq_lengths_query/kv 为 Tensor（文档为 int32）

通信算子

第四步：修复策略模式

定位根因后，选择合适的修复策略。

模式 1：算子回退（Operator Fallback）

当某个高性能算子在当前硬件/配置下不可用时，回退到功能等价但限制更少的替代算子。

# 示例：A2 上 experts_per_rank > 24 时 MC2 算子不可用，回退到 double_routing
def forward(self, hidden_states, is_prefill):
    topk_indices, topk_weights, _ = self.router(hidden_states)
    if is_prefill:
        return self.moe_infer_double_routing(hidden_states, topk_indices, topk_weights)
    else:
        experts_per_rank = self.num_experts // (self.moe_ep_size - self.shared_expert_rank_num)
        if experts_per_rank > 24:
            # A2 MC2 dispatch_v2/combine_v2 requires experts_per_rank <= 24; fall back
            return self.moe_infer_double_routing(hidden_states, topk_indices, topk_weights)
        return self.moe_infer_dispatch_combine(hidden_states, topk_indices, topk_weights)

适用场景：硬件约束、EP/TP size 不满足算子要求 注意：回退通常有性能损失，需记录在优化报告中

模式 2：参数修正（Parameter Fix）

算子入参计算错误（如 FA head_num 用了 KV heads 而非 Q heads、TP 切分后维度未除以 tp_size）。定位到具体算子后，逐个核对入参与算子文档/参考模型的差异。

适用场景：shape 不匹配、dtype 错误、维度计算错误

模式 3：路径统一（Path Unification）

部分 rank 走不同代码路径导致通信死锁。

# 错误：不同 rank 可能在不同 step 进入 prefill/decode
if is_prefill:
    self.all_reduce(...)  # rank 0 执行
# rank 1 已进入 decode，不执行 all_reduce → 死锁
# 修复：确保所有 rank 同步状态后再分支
dist.barrier()
is_prefill_tensor = torch.tensor([int(is_prefill)], device="npu")
dist.broadcast(is_prefill_tensor, src=0)
is_prefill = bool(is_prefill_tensor.item())

适用场景：多 rank 死锁、HCCL timeout

模式 4：配置降级（Configuration Downgrade）

配置组合不兼容时，调整 YAML 参数（如降低 moe_chunk_max_len、减小 batch_size）。

适用场景：OOM、性能异常

第五步：验证清单

修复后，按以下清单验证：

• [ ] 单步验证：在出错位置前后加 sync+barrier，确认不再超时
• [ ] 全流程验证：移除所有调试检查点，运行完整 warmup + inference
• [ ] 全 rank 验证：检查所有 rank 的日志，确认全部成功（grep "model run success" log_*.log）
• [ ] 输出一致性：各 rank 的最终输出应一致（对 DP 模式，同 DP group 内的 rank 输出应一致）
• [ ] 性能记录：记录修复后的 Prefill/Decode 耗时，与修复前对比
• [ ] 回退文档：如果使用了算子回退，记录性能影响和未来可恢复条件

特定场景诊断

以下场景有独立的诊断路径，不走通用流程。通过入口 npu-smi 表判断后直接跳转。

多卡部署诊断

多卡部署引入了一类单卡不存在的问题：权重加载切分、vocab 对齐、部分 rank 崩溃、config 兼容性。共同特点：部分 rank 成功、部分 rank 失败，错误出现在权重加载阶段而非 forward 阶段。

启动协议区分：框架部署用 cann-recipes-infer/executor/scripts/function.sh::launch 多卡 fork python（每个 rank 单独起进程，通过 LOCAL_RANK / RANK_ID 环境变量区分）；独立部署用 torchrun --nproc_per_node=N infer.py（torchrun 自动注入 RANK / WORLD_SIZE / LOCAL_RANK / MASTER_ADDR / MASTER_PORT）。卡 / crash 时先确认对应启动方式的进程模型。

权重加载 TP 切分越界

典型错误：

RuntimeError: start (105984) + length (35328) exceeds dimension size (131125)

或：

ValueError: 131125 is not divisible by 8

根因：ColumnParallelLinear / VocabParallelEmbedding 将权重沿 output 维度切分为对应 *_tp_size 份。如果 checkpoint 的实际维度不等于模型参数的维度，或者不能被对应 *_tp_size 整除，高位 rank 的 narrow() 操作就会越界。

常见场景：