Inference Precision Tensor Dump Compare

Tensor Dump Compare

在模型 forward 过程中打点，捕获中间 tensor，用于 GPU/NPU 精度对比。

支持框架: vLLM, SGLang

⚠️ 必须环境变量

vLLM 框架

⚠️ 重要: vLLM 默认启用 torch.compile，会导致 tensor dump 日志不输出。必须设置 TORCHDYNAMO_DISABLE=1！

# vLLM 启动命令 (必须)
export TORCHDYNAMO_DISABLE=1
export TENSOR_DUMP_ENABLE=1
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

vllm serve /path/to/model --tensor-parallel-size 8

SGLang 框架

# SGLang 启动命令
export TENSOR_DUMP_ENABLE=1
export TENSOR_DUMP_DEVICE=npu:0

python -m sglang.launch_server --model-path /path/to/model --tp 8

环境变量速查表

框架选择

⚠️ 工作流程 (必须遵循)

注入完成后，必须立即执行自检，不得跳过！

⚠️ 重要提示: 即使使用自动注入脚本，也必须根据Tag自检表进行自检！自动注入可能因代码模式匹配失败而遗漏部分 Tags。

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  1. 分析模型  │ -> │  2. 注入代码  │ -> │  3. 自检验证  │ -> │  4. 启动服务  │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
                                               │
                                               ▼
                                    ┌───────────────────────────────┐
                                    │  失败或者缺少Tag则修复并重新注入 │
                                    └───────────────────────────────┘

自检步骤 (注入后必做)

必须 Tags (⭐⭐⭐)

注入后必须验证以下 Tags 存在：

完整 Tag 列表请参阅 references/tensor-tags-guide.md

自检验证命令

# 1. 检查各模块 layer_idx 是否都已定义 (所有模块都需要!)
for cls in Attention DecoderLayer MLP; do
    grep "class $cls" model.py > /dev/null && \
    echo "$cls: $(grep -c 'self.layer_idx = ' model.py) 次"
done

# 2. 检查必须 Tags
for tag in input_ids hs.in final_hs logits attn.in attn.out hs.out mlp.input mlp.output; do
    grep "\"$tag\"" model.py > /dev/null && echo "✓ $tag" || echo "✗ $tag 缺失"
done

自检失败处理

⚠️ 特别注意: vLLM 必须设置 TORCHDYNAMO_DISABLE=1

原因: vLLM 默认启用 torch.compile，会优化掉 tensor dump 代码，导致日志不输出。

症状: 服务启动正常，推理正常，但日志中没有 [TD_CMP] 输出。

解决方案: 启动命令中必须包含 export TORCHDYNAMO_DISABLE=1

# 正确 ✓
export TORCHDYNAMO_DISABLE=1
export TENSOR_DUMP_ENABLE=1
vllm serve /path/to/model

# 错误 ✗ (日志无输出)
export TENSOR_DUMP_ENABLE=1
vllm serve /path/to/model

详见: references/review-guide.md

通用环境变量

设备过滤

通过 TENSOR_DUMP_DEVICE 环境变量控制：

日志格式

[TD_CMP] layer=0 attn.out device=npu:1 shape=[2048,5120] dtype=bfloat16 l1_norm=1.152184e+05

快速开始

⚠️ vLLM 必须设置 TORCHDYNAMO_DISABLE=1

原因: vLLM 默认启用 torch.compile，会优化掉 tensor dump 代码，导致日志不输出。

vLLM

# 1. 分析模型
grep -E "class.*\(|use_moe|gate\(" /path/to/model.py

# 2. 注入
python scripts/inject_tensor_dump.py --framework vllm --model-path /path/to/model.py --backup

# 3. 自检验证 (必须!)
#    - 语法检查
python -m py_compile /path/to/model.py
#    - 检查 Tag 数量
grep -c '_td_compare_log' /path/to/model.py
#    - 检查必须 Tags 存在
for tag in input_ids hs.in final_hs logits attn.in attn.out hs.out mlp.output; do
    grep "\"$tag\"" /path/to/model.py > /dev/null && echo "✓ $tag" || echo "✗ $tag 缺失"
done

# 4. 启动服务 (必须设置 TORCHDYNAMO_DISABLE=1!)
export TORCHDYNAMO_DISABLE=1  # 必须设置，否则日志无输出!
export TENSOR_DUMP_ENABLE=1
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
vllm serve /path/to/model --tensor-parallel-size 8

# 5. 验证日志输出
grep "\[TD_CMP\]" /tmp/vllm.log | head -20

SGLang

# 1. 分析模型
grep -E "class.*\(|forward_prepare|forward_core|layer_communicator" /path/to/model.py

# 2. 注入
python scripts/inject_tensor_dump.py --framework sglang --model-path /path/to/model.py --backup

# 3. 自检验证 (必须!)
python -m py_compile /path/to/model.py
grep '_td_compare_log' /path/to/model.py | grep '"' | sort | uniq
grep "self.layer_id = layer_id" /path/to/model.py

# 4. 启动
export TENSOR_DUMP_ENABLE=1
export MIMO_COMPARE=1
python -m sglang.launch_server --model-path /path/to/model

# 5. 验证
grep "\[TD_CMP\]" logs/sglang.log | head -20

框架差异速查

Attention 类型说明

layer_idx 的重要性

注意: MLP/Attention/DecoderLayer 等模块需要通过 extract_layer_index() 提取层索引，否则日志中 layer=None，无法定位问题。

详见: references/framework-integration.md - 框架集成指南

优先级建议

完整 Tag 列表请参阅 references/tensor-tags-guide.md

Scripts

使用示例

# vLLM
python scripts/inject_tensor_dump.py --framework vllm --model-path /path/to/model.py --backup

# SGLang
python scripts/inject_tensor_dump_sglang.py --model-path /path/to/model.py --backup

# 验证
python scripts/verify_tags.py /path/to/model.py --model-type xxx

参考文件