External Cannbot Model Model Infer Runtime Debug

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

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

诊断路径总览

问题发生
  │
  ├── 有明确错误信息 → 通用诊断流程
  │     ├── 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 调用处）通常不是出错的位置（某个具体算子）。

常见根因：

• 算子入参违反硬件约束（如 MC2 要求 ep_world_size >= 16，见「常见算子约束」）
• 算子 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 跳过某次通信）
• 通信组创建时参数错误（group_stride、group_num 不匹配 world_size）
• 网络问题（跨节点时 HCCL_IF_IP 配置错误）
• 某些 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 超出预期

D. Shape 不匹配

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

含义：tensor 维度不对。

常见根因：

• TP 切分后维度未正确除以 tp_size
• EP 切分后每卡专家数计算错误
• Prefill/Decode 分支传入了错误 shape 的 tensor

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）

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

# 示例：MC2 MoE 算子 EP<16 时回退到 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:
        if self.moe_ep_size < 16:
            # MC2 requires ep_world_size >= 16 on A2; fall back to double_routing
            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 阶段。

权重加载 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() 操作就会越界。

常见场景：

修复模板（vocab pad + weight pad）：

# 1. 创建 lm_head 时 pad vocab size
lm_head_raw = getattr(config, "text_vocab_plus_multimodal_special_token_size", config.vocab_size)
self.lm_head_vocab_size = ((lm_head_raw + tp_size - 1) // tp_size) * tp_size

# 2. 加载权重时 pad checkpoint tensor
if "lm_head" in name and loaded_weight.shape[0] < self.lm_head_vocab_size:
    padded = torch.zeros(self.lm_head_vocab_size, *loaded_weight.shape[1:],
                         dtype=loaded_weight.dtype, device=loaded_weight.device)
    padded[:loaded_weight.shape[0]] = loaded_weight
    loaded_weight = padded

排查技巧：如果只有高位 rank (rank 3-7) crash 而低位 rank (0-2) 正常，几乎一定是切分越界 —— 因为低位 rank 的 start_idx 还在合法范围内。

Config 兼容性问题

从 HuggingFace 原始模型加载时，config.json 可能缺少代码期望的字段，或字段格式不同。

常见问题：

最佳实践：在 config class 的 __init__ 末尾为缺失字段补 defensive defaults。对有模型差异的参数（如 rope_theta），从 config.json 读取而非硬编码默认值，缺失时报错。

部分 Rank 静默失败

有时 rank crash 了但错误被吞掉，存活的 rank 卡在下一个 dist.barrier() 或集合通信上，看起来像"推理卡住"。

诊断流程：

# 1. npu-smi 确认进程数
npu-smi info | grep "Process id"

# 2. 逐 rank 检查日志末尾
for i in $(seq 0 7); do
    echo "=== Rank $i ===" 
    tail -5 logs/log_${i}.log
done

# 3. 检查是否所有 rank 都到达了同一个里程碑
grep "model run success" logs/log_*.log
# 或
grep "Loading weights took" logs/log_*.log

多卡权重加载检查清单

在发起多卡推理前，逐项确认：

• embed_tokens 维度：checkpoint 里 embed_tokens.weight.shape[0] 和 config.vocab_size 一致
• lm_head 维度：checkpoint 里 lm_head.weight.shape[0] 可能小于 embed_tokens（多模态模型常见）
• vocab 整除 tp_size：lm_head 和 embed_tokens 的 output_size 都能被各自的 tp_size 整除（不能则 pad）
• ignore 规则覆盖：_keys_to_ignore_on_load_unexpected 包含所有不需要的权重前缀（ngram、visual、audio、mtp 等）
• config 字段完整：rope_parameters、num_layers、zero_expert_num 等代码必需字段在 config.json 中有或有 default
• 模型路径绝对路径：executor 框架中相对路径可能在不同 rank 的 cwd 下解析不同

推理卡住诊断

推理卡住与 crash 不同——进程仍在运行但不产出结果。需要区分真卡住和假卡住。先通过入口 npu-smi 表判断状态，再按以下路径排查。

eager 模式复现

卡住 → 换 eager YAML 跑同样模型
  ├── eager 也卡 → bug 在模型代码 → 用 sync+print 定位
  ├── eager 正常 → bug 在图模式适配
  │     ├── 看报错：ERR03007 / graph break → 找不兼容的算子
  │     └── 无报错但慢/卡 → 比较 eager 和 graph 模式代码路径差异
  └── 两者都正常但上次卡了 → 检查是否有残留进程占 NPU

模型构造阶段卡住（CPU 密集）

症状：日志停在 HCCL init 之后，HBM 不增长，但 CPU 100%+

常见根因：

诊断技巧：

# 区分真卡和 CPU 密集慢
ps aux | grep "infer.py" | awk '{print $2, $3"%CPU", int($6/1024)"MB"}'
# CPU 100%+ = 还在算（慢但没死）
# CPU 0%    = 真卡住（等通信/IO）

修复模板（大 embedding 模块）：

from transformers.modeling_utils import no_init_weights

# 用 no_init_weights 包裹，避免对即将被 checkpoint 覆盖的参数做随机初始化
with no_init_weights():
    self.large_embeddings = LargeEmbeddingModule(config, ...)

残留进程导致 HCCL 卡住

症状：新启动的推理卡在 HCCL init，不报错不超时

根因：上次推理的进程未正确退出，仍占用 NPU 设备或 HCCL 端口

修复：

# 1. 杀死残留进程
ps aux | grep "infer.py" | grep -v grep | awk '{print $2}' | xargs kill -9

# 2. 等待 NPU 释放
sleep 3

# 3. 确认 NPU 完全空闲
npu-smi info | grep "No running"
# 期望输出 8 行 "No running processes found"

# 4. 重新启动推理

预防：每次启动推理前，先检查并清理残留进程。

附录

运行监控与提效

以下命令示例基于当前仓默认的日志路径和启动脚本约定，executor 或日志组织变更后需相应调整。

核心原则

判断完成状态看进程，不看日志流。多卡推理通过 infer.sh 后台启动 N 个进程再 wait。rank 0 的 stdout 通过 tee 到终端，可能缓冲截断；其他 rank 只写日志文件。

完成检测方法

日志关键字判断阶段

grep "Loading safetensors" logs/*/log_1.log     # 正在加载权重
grep "Loading weights took" logs/*/log_1.log    # 加载完成
grep "inference time cost of prefill" logs/*/log_1.log  # 推理已开始
grep "model run success" logs/*/log_1.log       # 推理已结束

一条命令获取全局状态

echo "=== NPU ===" && npu-smi info | grep -E "Process|HBM" | head -5 && \
echo "=== Log ===" && tail -3 logs/*/log_1.log && \
echo "=== Done? ===" && grep -c "model run success" logs/*/log_*.log 2>/dev/null

常见误判场景

Agent 工作模式

1. 启动推理（bash infer.sh，前台或 run_in_background）
2. 不要盲目 sleep —— 用 run_in_background 等通知，或前台直接看输出
3. 10 分钟无进展 → 主动排查：推理启动超过 10 分钟仍无 model run success 输出，不要继续等待，按「推理卡住诊断」流程排查（npu-smi → 判断状态 → 分流）
4. 超时后第一步查 npu-smi，不要先查日志
5. 检查完成时查 rank 1（不是 rank 0）—— rank 1 日志完整无截断
6. 一次检查多个信号：npu-smi + tail log_1.log + grep "model run success" log_*.log 并行执行