# graph-debug-skill

**Repository Path**: it_view_world/graph-debug-skill

## Basic Information

- **Project Name**: graph-debug-skill
- **Description**: AI辅助入图问题定位skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TorchAir/ACLGraph 入图问题定位技能

用于系统化定位和解决 TorchAir 图模式（ACLGraph/GE）相关问题的 Claude Code 技能。

## 快速开始

### 方式一：命令行调用

```bash
/graph-debug [错误日志文件路径或问题描述]
```

**示例：**
```bash
/graph-debug test_logs/error_log.txt
/graph-debug "mod算子入图报ValuePack类型错误"
/graph-debug "warmup后触发重编译"
```

### 方式二：自动触发

在对话中描述问题，包含以下关键词时自动触发：

- `入图失败`、`图编译错误`、`重编译问题`
- `OOM`、`断图`、`guard失败`
- `ValuePack`、`BackendCompilerFailed`
- `meta注册错误`、`精度问题`

---

## 目录结构

```
.claude/skills/graph-debug/
│
├── SKILL.md                    # 技能主文档（问题定位流程）
│
├── references/                 # 参考文档
│   ├── common-issues.md        # 常见问题案例库（8个典型案例）
│   └── debug-commands.md       # 调试命令速查手册
│
├── scripts/                    # 工具脚本
│   ├── log_analyzer.py         # 日志自动分析工具
│   └── diagnose.py             # 分阶段诊断工具
│
└── examples/                   # 使用示例
    └── basic_usage.py          # 8个典型场景示例
```

---

## 功能特性

### 1. 日志自动分析

自动解析错误日志，支持两层分析机制：

```bash
python scripts/log_analyzer.py --log error.log

# 输出JSON格式
python scripts/log_analyzer.py --log error.log --json

# 保存报告
python scripts/log_analyzer.py --log error.log --output report.md
```

**两层分析：**

| 层级 | 匹配方式 | 置信度 | 说明 |
|------|----------|--------|------|
| 已知模式 | 精确匹配案例库 | 80-98% | 7种常见问题 |
| 语义推断 | 错误类型+算子约束 | 30-70% | 未知问题智能分析 |

**已知问题类型：**

| 问题类型 | 关键特征 |
|----------|----------|
| mod算子失败 | `unsupported operand type(s) for %: 'ValuePack'` |
| meta device错误 | `tensor's device must be 'meta', got cpu` |
| dtype不一致 | `dtype.*inconsistent` |
| 重编译问题 | `Recompiling function`, `guard failure` |
| OOM | `NPU out of memory` |
| Core Dump | `core dumped`, `segment fault` |

**语义推断能力（未知问题）：**

| 场景 | 识别方式 | 解决建议 |
|------|----------|----------|
| 算子约束 | `input must be non-negative` | 提示使用clamp/abs |
| 除零错误 | `division by zero` | 提示添加eps |
| shape不匹配 | `shape.*mismatch` | 提示检查维度 |
| 类型错误 | `TypeError`, `ValueError` | 提示类型转换 |

### 2. 分阶段诊断

按 Phase 1-5 顺序自动定位问题阶段：

```python
from scripts.diagnose import full_diagnose

# 执行完整诊断
results = full_diagnose(model, inputs)

# 单独执行各阶段
from scripts.diagnose import phase1_single_operator, phase2_eager_backend, phase3_npu_backend
phase1_single_operator(model, inputs)
phase2_eager_backend(model, inputs)
phase3_npu_backend(model, inputs, config)
```

### 3. 问题案例库

`references/common-issues.md` 包含 10 个典型案例：

| 编号 | 问题 | 类型 |
|------|------|------|
| COMPILE-001 | floordiv类型不一致 | 编译时 |
| COMPILE-002 | meta注册device错误 | 编译时 |
| COMPILE-003 | mod算子入图失败 | 编译时 |
| COMPILE-004 | torch 2.6 view触发重编译 | 编译时 |
| COMPILE-005 | 算子参数名称不对齐 | 编译时 |
| EXEC-001 | 单算子反向踩内存 | 执行时 |
| EXEC-002 | npu_print结果不一致 | 执行时 |
| PRECISION-001 | GE图与FX图输出shape/dtype不一致 | 精度 |
| PRECISION-002 | GE融合模式精度问题 | 精度 |

### 4. 调试命令速查

`references/debug-commands.md` 提供完整命令手册：

- 日志配置（TorchAir/Dynamo/GE）
- 图Dump（FX图/GE图）
- 数据Dump与解析
- Profiling配置
- 断图定位
- Core Dump分析

---

## 定位流程

```
┌─────────────────────────────────────────────────────────┐
│  用户提供错误日志或问题描述                              │
│      ↓                                                  │
│  日志自动分析（log_analyzer.py）                        │
│      ↓                                                  │
│  问题分类（编译时/执行时/精度/重编译）                   │
│      ↓                                                  │
│  分阶段定界（Phase 1-5）                                │
│      ↓                                                  │
│  详细定位（匹配案例库）                                  │
│      ↓                                                  │
│  输出诊断报告与解决方案                                  │
└─────────────────────────────────────────────────────────┘
```

**定界阶段说明：**

| 阶段 | 验证内容 | 失败则问题归属 |
|------|----------|----------------|
| Phase 1 | 单算子模式 | 算子实现 |
| Phase 2 | eager后端 | meta注册 |
| Phase 3 | NPU后端 | TorchAir |
| Phase 4 | Converter | IR定义/参数对齐 |
| Phase 5 | GE执行 | GE/算子 |

---

## 使用示例

### 示例1：分析错误日志

```
用户：我遇到了一个入图失败的问题，日志在 test_logs/error_log.txt

Claude 会自动：
1. 读取日志文件
2. 解析环境信息和错误类型
3. 匹配问题模式
4. 输出诊断报告和解决方案
```

### 示例2：定位重编译问题

```
用户：warmup后正式推理触发重编译，报错 'NoneType' object has no attribute 'size'

Claude 会自动：
1. 判定为重编译问题
2. 分析guard失败原因
3. 识别torch 2.6+ view输入问题
4. 给出统一输入处理的解决方案
```

### 示例3：自定义算子入图

```
用户：自定义算子入图报错 tensor's device must be 'meta', got cpu instead

Claude 会自动：
1. 判定为meta注册问题
2. 定位到缺少 device="meta"
3. 给出正确写法示例
```

---

## 快速参考

### 常用调试命令

```bash
# 开启所有调试日志
export TNG_LOG_LEVEL=0
export TORCH_LOGS="guards,recompiles"
export ASCEND_GLOBAL_LOG_LEVEL=0
export ASCEND_SLOG_PRINT_TO_STDOUT=1

# Dump图结构
export DUMP_GE_GRAPH=2
export DUMP_GRAPH_LEVEL=2
export DUMP_GRAPH_PATH="./dump"

# 配置数据dump
config.dump_config.enable_dump = True
config.dump_config.dump_mode = 'all'
config.dump_config.dump_path = './dump'
```

### 常见问题速查

| 问题 | 解决方案 |
|------|----------|
| `seq_len % 4` 报错 | 改用 `torch.remainder(seq_len, 4)` |
| meta返回cpu tensor | 添加 `device="meta"` |
| view tensor触发重编译 | 使用 `.clone()` 断开view关系 |
| dtype不一致 | 在Converter中插入Cast节点 |

---

## 版本兼容性

| PyTorch | 关键变化 |
|---------|----------|
| 2.1.x | 基础guard机制 |
| 2.3.x | 反向多流支持 |
| 2.5.x | 增强shape guard |
| 2.6.x | 新增 `_base` guard（view输入需注意） |

---

## 相关文档

| 文档 | 说明 |
|------|------|
| [TorchAir使用指南](https://www.hiascend.com/document/detail/zh/Pytorch/700/modthirdparty/torchairuseguide/) | 官方文档 |
| [PyTorch Dynamo FAQ](https://pytorch.ac.cn/docs/stable/torch.compiler_faq.html) | Dynamo问题 |
| [CANN开发文档](https://www.hiascend.com/document) | CANN文档 |
| [TorchAir场景-整网算子精度比对](https://gitee.com/ascend/msit/blob/master/msit/docs/llm/TorchAir场景-整网算子精度比对.md) | msit精度比对工具 |

**本地文档：**

| 文档 | 内容 |
|------|------|
| `ge graph问题定位/单算子入图后输出校验和精度对比指导.md` | GE/FX输出校验、msit工具使用 |
| `aclgraph问题定位/定界定位流程.md` | 完整定界流程 |
| `ge graph问题定位/定位思路.md` | 报错类问题分类 |

---

## 更新日志

| 版本 | 更新内容 |
|------|----------|
| v1.3.0 | 精简SKILL.md，优化结构 |
| v1.2.0 | 新增日志自动分析工具、版本兼容性矩阵 |
| v1.1.0 | 完善问题定界流程、增加常见案例库 |
| v1.0.0 | 初始版本 |