Skip to content

Commit acefbad

Browse files
youge325claude
youge325
and
claude
authored
Add GPUContext related architecture diagram and Update API mapping table (#63)
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 395f3ac commit acefbad

309 files changed

Lines changed: 80864 additions & 1765 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/skills/api-mapping-updater/SKILL.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
name: api-mapping-updater
3+
description: '定期触发验证并自动更新 API 映射表。基于 verify_api_mapping.py 全量验证，检测分类漂移，自动修复高置信度问题，低置信度进入Agent 审核队列。'
4+
argument-hint: '可选批次名（P0/P1/P2/P3/P4/P5/all），不传则全量验证'
5+
---
6+
7+
# API 映射表定期更新 Skill
8+
9+
基于 Step 2-1 追踪验证的映射表自动维护工作流，定期检测 PyTorch/Paddle 更新导致的映射分类漂移。
10+
11+
## 上游调用上下文
12+
13+
| 上游调用方 | 调用时机 | 期望传入字段 | 处理策略 |
14+
|-----------|---------|-------------|---------|
15+
| cron / schedule | 定期触发（如每周） | `batch=all` | 全量验证 + 自动修复 + 生成报告 |
16+
| 用户手动 | 映射表疑似过时 | `batch=P4_missing` 等 | 指定批次验证 |
17+
| CI/CD | Paddle/PyTorch 版本升级后 | `batch=all` | 全量验证确认兼容性 |
18+
19+
## 何时使用
20+
21+
- 定期（每周/每月）自动验证映射表准确性
22+
- Paddle 或 PyTorch 版本升级后验证映射是否仍有效
23+
- 批量发现映射表中的分类漂移
24+
- 自动修复高置信度的映射错误
25+
26+
## 输入参数
27+
28+
| 参数 | 类型 | 默认值 | 说明 |
29+
|------|------|--------|------|
30+
| `batch` | string | `all` | 验证批次：P0/P1/P2/P3/P4/P5/all |
31+
| `auto_fix` | bool | `true` | 是否自动修复高置信度问题 |
32+
| `output_dir` | string | `doc/mapping/verification_output` | 报告输出目录 |
33+
| `libtorch_ops_dir` | string | `D:/Lenovo/libtorch/include/ATen/ops` | libtorch 头文件路径 |
34+
| `paddle_src_dir` | string | `D:/Lenovo/Paddle` | Paddle 源码路径 |
35+
| `pytorch_src_dir` | string | `D:/Lenovo/pytorch` | PyTorch 源码路径 |
36+
37+
## 输出产物
38+
39+
1. **验证报告** `verification_report_YYYY-MM-DD.md` — 人类可读的差异报告
40+
2. **JSON 结果** `verification_results_*.json` — 结构化验证结果
41+
3. **修复日志** `fix_log_YYYY-MM-DD.md` — 自动修复操作记录
42+
4. **Agent 审核队列** `manual_review_queue.json` — 需 Agent 确认的条目
43+
44+
## 工作流
45+
46+
> **核心原则**：脚本只负责**表层验证**（头文件签名、kernel 文件路径定位、重复条目检测），**具体 C++ 实现逻辑的审核由 Agent 逐一阅读源码完成**。
47+
48+
### Step 1. 环境检查
49+
50+
确认以下路径存在且可访问：
51+
- `libtorch_ops_dir` — ATen/ops 头文件
52+
- `paddle_src_dir/paddle/phi/api/include/api.h` — Paddle API 声明
53+
- `pytorch_src_dir/aten/src/ATen/native/native_functions.yaml` — PyTorch 原生函数定义
54+
55+
### Step 2. 脚本执行表层验证
56+
57+
```bash
58+
cd "$PCAT_ROOT/doc/mapping"
59+
python verify_api_mapping.py --batch "$batch"
60+
```
61+
62+
脚本输出（仅限表层信息）：
63+
- 各分类验证状态统计
64+
- **PyTorch kernel 实现文件路径**
65+
- **Paddle kernel 实现文件路径**
66+
- 头文件签名对比结果
67+
- 重复条目检测
68+
69+
### Step 3. Agent 源码审核（核心步骤）
70+
71+
对 P0（API 完全一致）和 P1（仅参数名不一致）等关键批次的 API，**逐一阅读 C++ 实现文件**，对比以下维度：
72+
73+
| 检查项 | PyTorch 关注点 | Paddle 关注点 | 差异影响 |
74+
|--------|--------------|--------------|---------|
75+
| **核心数学运算** | 实际调用的函数（`std::abs`, `sum_stub` 等） | Functor 中的运算（`Acos<T>`, `SumFunctor`） | 数学语义是否一致 |
76+
| **数据类型处理** | `AT_DISPATCH_*` 宏、complex 分支 | `if constexpr`、float16 特化 | dtype 支持范围是否一致 |
77+
| **空张量处理** | `TensorIterator.numel() == 0` | `if (x.numel() == 0)` | 边界行为是否一致 |
78+
| **精度累积** | `should_use_acc_buffer`、中间 float 缓冲 | `Cast` 到 float32 | 低精度输入结果是否一致 |
79+
| **非连续张量** | `TensorIterator` 自动处理 | 是否检查 `is_contiguous()` | 布局敏感操作是否有差异 |
80+
| **异常/断言** | `TORCH_CHECK`、`AT_ASSERT` | `PADDLE_ENFORCE` | 异常触发时机是否一致 |
81+
| **in-place 限制** | complex 禁止、维度检查 | 是否由上层框架处理 | in-place 语义是否一致 |
82+
83+
**审核产出**：每个 API 的风险评级（低/中/高）+ 差异说明
84+
85+
### Step 4. 脚本差异检测（自动化）
86+
87+
对比本次与历史验证结果：
88+
- 新增 `truly_missing`（Paddle 侧实现被移除）
89+
- 新增 `verified_api_h_only`（Paddle 新增实现但未封装 compat）
90+
- 新增 `alias_candidate`（发现新别名映射）
91+
- 状态变更（如 `verified_compat` → `truly_missing`）
92+
93+
### Step 5. 自动修复（仅限高置信度表层问题）
94+
95+
脚本可自动修复的场景（不涉及实现逻辑判断）：
96+
97+
| 场景 | 修复操作 | 置信度 |
98+
|------|---------|--------|
99+
| 别名映射在 Paddle api.h 中无实现 | 从 `cpp_api_alias_mapping.json` 移除 | high |
100+
| 映射表中有重复条目 | 删除重复，保留正确分类 | high |
101+
| `verified_compat` API 的 compat 层文件缺失 | 降级为 `verified_api_h_only` | medium |
102+
| 发现新的 `strip_underscore_prefix` 别名 | 添加到 `cpp_api_alias_mapping.json` | high |
103+
104+
**⚠️ 注意**：脚本**不**判断实现语义等价性，语义审核必须由 Step 3 的 Agent 审核完成。
105+
106+
修复后运行 `fix_mapping.py` 更新 `cpp_api_mapping_cn.md`。
107+
108+
### Step 6. 生成报告
109+
110+
```bash
111+
python generate_comprehensive_report.py
112+
```
113+
114+
报告包含：
115+
- 各批次验证统计
116+
- 脚本发现的问题列表
117+
- **Agent 源码审核记录**（风险评级 + 差异说明）
118+
- 自动修复记录
119+
- 需继续 Agent 审核的条目
120+
121+
### Step 7. 提交 PR
122+
123+
若存在修复：
124+
1. `git add doc/mapping/`
125+
2. pre-commit 检查
126+
3. `git commit`
127+
4. `git push origin doc`
128+
5. （可选）创建 PR 到 master
129+
130+
## 决策分支
131+
132+
### 分支 A：无差异发现
133+
- 验证结果与上次一致
134+
- 仅更新报告时间戳，不提交代码
135+
136+
### 分支 B：发现高置信度问题
137+
- 执行自动修复
138+
- 提交修复后的映射表
139+
140+
### 分支 C：发现低置信度问题
141+
- 生成Agent 审核队列
142+
- 不自动修复，等待 Agent 确认
143+
144+
### 分支 D：Paddle/PyTorch 版本升级
145+
- 执行全量验证
146+
- 重点检查 `verified_compat` 类是否仍有效
147+
- 检查新增 API 是否需要映射
148+
149+
## 质量标准
150+
151+
1. **可追溯**：每次验证都有时间戳和完整报告
152+
2. **低风险**：高置信度自动修复才执行，低置信度必须 Agent 审核
153+
3. **可回滚**：每次自动修复前备份 `cpp_api_mapping_cn.md` 和 `cpp_api_alias_mapping.json`
154+
4. **不破坏**：自动修复后验证总数不变（1096 → 1096）
155+
156+
## 常见隐患
157+
158+
### 隐患 1：自动修复过度
159+
**❌ 错误**：自动移除了实际上存在的别名映射（因 api.h 未暴露但 kernel 已注册）
160+
**✅ 要求**：`kernel_only` 的 API 不移除别名映射，仅标记状态
161+
162+
### 隐患 2：验证耗时过长
163+
**❌ 错误**：每次全量验证 1096 个 API，耗时数小时
164+
**✅ 要求**：支持增量验证（仅验证变更分类的 API）
165+
166+
### 隐患 3：报告被覆盖
167+
**❌ 错误**：每次验证覆盖上次的报告
168+
**✅ 要求**：报告文件名带时间戳，保留历史报告
169+
170+
## 推荐触发词
171+
172+
- "定期验证映射表"
173+
- "检查映射表是否有漂移"
174+
- "Paddle 升级后验证映射"
175+
- "全量验证 API 映射"
176+
- "验证 P4 缺失类"

‎.github/skills/api-mapping-verifier/SKILL.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
name: api-mapping-verifier
3+
description: '按需验证单个或批次 API 的映射准确性，基于 Step 2-1 追踪方法深入 PyTorch 实现链路。支持发现问题、给出修复建议、执行修复。'
4+
argument-hint: '目标 API 名（如 abs）或批次名（P0/P1/P2/P3/P4/P5）'
5+
---
6+
7+
# API 映射表按需验证 Skill
8+
9+
基于 Step 2-1 方法论的按需验证工作流，用于验证单个 API 或批次 API 的映射分类是否准确。
10+
11+
## 何时使用
12+
13+
- 怀疑某个 API 的映射分类不正确
14+
- 新增 compat 接口后验证映射表是否需要更新
15+
- 排查具体 API 的兼容性差异
16+
- 验证 Paddle 新增实现是否已正确映射
17+
18+
## 输入参数
19+
20+
| 参数 | 类型 | 默认值 | 说明 |
21+
|------|------|--------|------|
22+
| `op` | string | — | 单个 API 名称（如 `abs`） |
23+
| `batch` | string | — | 验证批次：P0/P1/P2/P3/P4/P5 |
24+
| `pytorch_src_dir` | string | `D:/Lenovo/pytorch` | PyTorch 源码路径（用于追踪 kernel） |
25+
| `paddle_src_dir` | string | `D:/Lenovo/Paddle` | Paddle 源码路径 |
26+
| `libtorch_ops_dir` | string | `D:/Lenovo/libtorch/include/ATen/ops` | libtorch 头文件路径 |
27+
28+
**注意**：`op` 和 `batch` 二选一，同时传入时优先 `op`。
29+
30+
## 输出产物
31+
32+
1. **验证结果 JSON** — 结构化追踪记录
33+
2. **终端输出** — 人类可读的结果摘要
34+
3. **修复建议** — 基于验证状态的具体操作建议
35+
36+
## 工作流
37+
38+
> **核心原则**：脚本只负责**定位**和**提取表层信息**（头文件签名、kernel 文件路径），**具体 C++ 实现逻辑的审核由 Agent 逐一阅读源码完成**。
39+
40+
### Step 1. 脚本定位（自动化）
41+
42+
脚本通过 `verify_api_mapping.py` 完成以下工作：
43+
44+
```bash
45+
cd "$PCAT_ROOT/doc/mapping"
46+
# 单 API
47+
python verify_api_mapping.py --op "$op"
48+
# 批次
49+
python verify_api_mapping.py --batch "$batch"
50+
```
51+
52+
脚本输出：
53+
- 验证状态（verified_compat / verified_api_h_only / alias_candidate / ...）
54+
- **PyTorch kernel 实现文件路径**（如 `aten/src/ATen/native/UnaryOps.cpp:543`）
55+
- **Paddle kernel 实现文件路径**（如 `paddle/phi/kernels/cpu/abs_kernel.cc:25`）
56+
- 头文件签名对比结果
57+
58+
### Step 2. Agent 源码审核（核心步骤）
59+
60+
**根据脚本定位的文件路径，逐一阅读 C++ 实现文件**，对比以下维度：
61+
62+
#### 2.1 必须阅读的源码位置
63+
64+
| 框架 | 文件类型 | 典型路径示例 |
65+
|------|---------|-------------|
66+
| PyTorch | CPU kernel | `aten/src/ATen/native/cpu/UnaryOpsKernel.cpp` |
67+
| PyTorch | CUDA kernel | `aten/src/ATen/native/cuda/AbsKernel.cu` |
68+
| PyTorch | 高层封装 | `aten/src/ATen/native/UnaryOps.cpp` |
69+
| Paddle | CPU kernel | `paddle/phi/kernels/cpu/abs_kernel.cc` |
70+
| Paddle | CUDA kernel | `paddle/phi/kernels/gpu/abs_kernel.cu` |
71+
| Paddle | Functor | `paddle/phi/kernels/funcs/activation_functor.h` |
72+
73+
#### 2.2 审核检查清单
74+
75+
| 检查项 | PyTorch 关注点 | Paddle 关注点 | 差异影响 |
76+
|--------|--------------|--------------|---------|
77+
| **核心数学运算** | 实际调用的函数（`std::abs`, `sum_stub` 等） | Functor 中的运算（`Acos<T>`, `SumFunctor`） | 数学语义是否一致 |
78+
| **数据类型处理** | `AT_DISPATCH_*` 宏、complex 分支 | `if constexpr`、float16 特化 | dtype 支持范围是否一致 |
79+
| **空张量处理** | `TensorIterator.numel() == 0` | `if (x.numel() == 0)` | 边界行为是否一致 |
80+
| **精度累积** | `should_use_acc_buffer`、中间 float 缓冲 | `Cast` 到 float32 | 低精度输入结果是否一致 |
81+
| **非连续张量** | `TensorIterator` 自动处理 | 是否检查 `is_contiguous()` | 布局敏感操作是否有差异 |
82+
| **异常/断言** | `TORCH_CHECK`、`AT_ASSERT` | `PADDLE_ENFORCE` | 异常触发时机是否一致 |
83+
| **in-place 限制** | complex 禁止、维度检查 | 是否由上层框架处理 | in-place 语义是否一致 |
84+
| **向量化实现** | AVX512、Vectorized | Eigen 向量化 | 性能差异，不影响语义 |
85+
86+
#### 2.3 审核结论模板
87+
88+
对每 个 API，填写以下审核记录：
89+
90+
```markdown
91+
## at::<op_name> 源码审核
92+
93+
**PyTorch 实现**（文件:行号）：
94+
```cpp
95+
// 粘贴核心实现代码
96+
```
97+
98+
**Paddle 实现**（文件:行号）：
99+
```cpp
100+
// 粘贴核心实现代码
101+
```
102+
103+
**审核结论**：
104+
105+
| 维度 | PyTorch | Paddle | 差异 |
106+
|------|---------|--------|------|
107+
| 核心运算 | ... | ... | ... |
108+
| 数据类型 | ... | ... | ... |
109+
| 边界条件 | ... | ... | ... |
110+
| 异常语义 | ... | ... | ... |
111+
112+
**风险评级**：低 / 中 / 高
113+
**理由**：...
114+
```
115+
116+
### Step 3. 头文件签名对比（脚本辅助）
117+
118+
脚本对比签名层面的差异：
119+
120+
| 验证状态 | 含义 | 修复建议 |
121+
|----------|------|----------|
122+
| `verified_compat` | compat 层已实现 | 需Agent 审核实现逻辑 |
123+
| `verified_api_h_only` | api.h 有实现，compat 层未封装 | 可考虑添加 compat 层封装 |
124+
| `alias_candidate` | 发现别名映射候选 | 需 Agent 确认别名语义等价 |
125+
| `kernel_only` | kernel 已注册但未暴露到 api.h | 需 Paddle 侧暴露到 api.h |
126+
| `truly_missing` | 真正缺失 | 确认是否真的无对应实现 |
127+
128+
### Step 4. 修复建议与执行
129+
130+
**场景 A：`verified_api_h_only` → 应添加 compat 层**
131+
- 参考同类型 API 的 compat 层实现模板
132+
- 建议创建 `paddle/phi/api/include/compat/ATen/ops/<op>.h`
133+
134+
**场景 B：分类错误 → 应修正映射表**
135+
- 结合源码审核结论，判断当前分类是否准确
136+
- 给出 `fix_mapping.py` 的修复参数
137+
138+
**场景 C：发现实现语义差异 → 更新文档**
139+
- 在映射表备注中注明差异（如 `at::abs` 的非连续张量处理差异）
140+
- 更新差异文档
141+
142+
执行修复：
143+
1. 更新 `cpp_api_alias_mapping.json`（如需）
144+
2. 运行 `fix_mapping.py` 更新映射表
145+
3. 删除/更新相关差异文档
146+
4. 重新运行验证确认修复成功
147+
148+
## 决策分支
149+
150+
### 分支 A：验证通过（verified_compat）
151+
- 输出追踪详情供参考
152+
- 无需修复
153+
154+
### 分支 B：api.h 有实现但 compat 层未封装
155+
- 给出 compat 层封装模板
156+
- 用户确认后创建 compat 头文件
157+
158+
### 分支 C：发现别名候选
159+
- 给出别名映射建议
160+
- 用户确认后更新别名映射文件
161+
162+
### 分支 D：真正缺失
163+
- 检查是否有组合实现方案
164+
- 记录到"功能缺失"跟踪列表
165+
166+
## 使用示例
167+
168+
```bash
169+
# 验证单个 API
170+
/api-mapping-verifier --op abs
171+
172+
# 验证批次
173+
/api-mapping-verifier --batch P0_exact_match
174+
175+
# 验证并自动修复
176+
/api-mapping-verifier --batch P1_name_diff --auto_fix
177+
```
178+
179+
## 质量标准
180+
181+
1. **追踪完整**：展示从 libtorch 声明到 kernel 实现的完整链路
182+
2. **建议具体**：给出可直接执行的修复操作，不只是描述问题
183+
3. **可验证**：修复后必须重新验证确认
184+
185+
## 与 api-mapping-updater 的区别
186+
187+
| | api-mapping-verifier | api-mapping-updater |
188+
|--|---------------------|---------------------|
189+
| 触发方式 | 按需（用户指定 API） | 定期（cron/schedule） |
190+
| 验证范围 | 单个 API 或单批次 | 全量或大批次 |
191+
| 修复策略 | 用户确认后执行 | 高置信度自动修复 |
192+
| 输出 | 终端摘要 + 追踪详情 | 完整报告 + 审核队列 |
193+
| 典型场景 | 排查具体问题 | 定期维护 |

0 commit comments

Comments
 (0)