Skip to content

Commit c88d48f

Browse files
zrr1999zrr1999
authored
add skills (PaddlePaddle#78331)
* add skills * rename
1 parent 4941dec commit c88d48f

File tree

28 files changed

+4063
-0
lines changed

28 files changed

+4063
-0
lines changed

‎skills/paddle-build/SKILL.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
name: paddle-build
3+
description: Use when needing to compile, rebuild, or install Paddle from source after code changes. Covers cmake configuration, ninja incremental build, wheel packaging, and common build failure diagnosis.
4+
---
5+
6+
# Paddle 源码编译
7+
8+
## 概览
9+
10+
Paddle 使用 CMake + Ninja 构建。典型流程：cmake 配置 → ninja 编译 → whl 打包安装。修改 C++/CUDA 代码后需重新编译才能生效。
11+
12+
## 编译流程
13+
14+
### 1. 环境准备（venv）
15+
16+
```bash
17+
cd /workspace/Paddle
18+
uv venv --relocatable --seed --python 3.10 # 首次创建
19+
source .venv/bin/activate
20+
uv pip install -r python/requirements.txt
21+
uv pip install func_timeout pandas numpy "numpy<2.0"
22+
```
23+
24+
若 `.venv` 已存在，直接 `source .venv/bin/activate` 即可。
25+
26+
### 2. CMake 配置
27+
28+
```bash
29+
mkdir -p build && cd build
30+
cmake .. \
31+
-GNinja \
32+
-DCMAKE_BUILD_TYPE=Release \
33+
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
34+
-DPY_VERSION=3.10 \
35+
-DPADDLE_VERSION=0.0.0 \
36+
-DCUDA_ARCH_NAME=Auto \
37+
-DWITH_GPU=ON \
38+
-DWITH_DISTRIBUTE=ON \
39+
-DWITH_CINN=ON \
40+
-DWITH_UNITY_BUILD=OFF \
41+
-DWITH_TESTING=OFF
42+
```
43+
44+
配置只需首次执行或 CMake 选项变更时重新执行。
45+
46+
### 3. 编译
47+
48+
```bash
49+
ninja -j$(nproc)
50+
```
51+
52+
Ninja 自动增量编译，仅重编变更文件及其依赖。
53+
54+
### 4. 安装
55+
56+
```bash
57+
cd /workspace/Paddle
58+
uv pip install build/python/dist/*.whl --no-deps --force-reinstall
59+
```
60+
61+
`--no-deps` 跳过依赖解析加速安装，`--force-reinstall` 确保覆盖旧版。
62+
63+
## 常用 CMake 选项
64+
65+
| 选项 | 默认 | 说明 |
66+
|------|------|------|
67+
| `WITH_GPU` | ON(有CUDA时) | GPU 支持 |
68+
| `WITH_DISTRIBUTE` | OFF | 分布式训练 |
69+
| `WITH_CINN` | OFF | CINN 编译器 |
70+
| `WITH_TESTING` | ON | C++ 单测（关闭可加速编译） |
71+
| `WITH_UNITY_BUILD` | OFF | 合并编译单元加速（可能掩盖头文件问题） |
72+
| `CUDA_ARCH_NAME` | Auto | GPU 架构，Auto 自动检测当前卡 |
73+
| `CMAKE_BUILD_TYPE` | Release | Debug 可调试但更慢 |
74+
| `CMAKE_EXPORT_COMPILE_COMMANDS` | OFF | 生成 `compile_commands.json` 供 clangd 使用 |
75+
| `WITH_TENSORRT` | OFF | TensorRT 推理加速 |
76+
| `WITH_ROCM` | OFF | AMD ROCm 支持 |
77+
| `WITH_XPU` | OFF | 百度昆仑 XPU 支持 |
78+
79+
## 增量编译策略
80+
81+
```dot
82+
digraph incremental {
83+
"修改了什么?" [shape=diamond];
84+
"Python 代码" [shape=box, label="无需编译\npip install -e 或直接测试"];
85+
"C++/CUDA kernel" [shape=box, label="ninja → 安装 whl"];
86+
"CMakeLists / cmake 选项" [shape=box, label="重新 cmake → ninja → 安装 whl"];
87+
"YAML (ops/backward)" [shape=box, label="ninja（触发代码生成）→ 安装 whl"];
88+
89+
"修改了什么?" -> "Python 代码" [label="python/"];
90+
"修改了什么?" -> "C++/CUDA kernel" [label="paddle/phi/"];
91+
"修改了什么?" -> "CMakeLists / cmake 选项" [label="cmake/"];
92+
"修改了什么?" -> "YAML (ops/backward)" [label="ops.yaml 等"];
93+
}
94+
```
95+
96+
- **仅改 Python**：无需编译。如果已 `pip install -e .` 或在 `build/python` 下测试，改动即时生效。
97+
- **改 C++/CUDA**：`cd build && ninja -j$(nproc)` + 重新安装 whl。
98+
- **改 CMake 配置**：需重新 `cmake ..` 再 `ninja`。
99+
- **改 YAML（ops.yaml / backward.yaml）**：ninja 会自动触发代码生成脚本。
100+
101+
## 检查已有构建产物
102+
103+
复用已有 build 可大幅节约时间：
104+
105+
```bash
106+
# 检查是否已有 whl
107+
ls build/python/dist/*.whl 2>/dev/null && echo "已有构建产物" || echo "需要编译"
108+
109+
# 检查 compile_commands.json（clangd 需要）
110+
ls build/compile_commands.json 2>/dev/null
111+
```
112+
113+
## 常见编译问题
114+
115+
| 症状 | 原因 | 解决 |
116+
|------|------|------|
117+
| `ninja: error: loading 'build.ninja'` | 未执行 cmake 配置 | 先执行 cmake 命令 |
118+
| CUDA arch 不匹配 | `CUDA_ARCH_NAME` 与实际 GPU 不符 | 设为 `Auto` 或指定具体架构 |
119+
| 链接时 OOM | 并行链接占用过多内存 | `ninja -j4` 减少并行度 |
120+
| protobuf 版本冲突 | 系统 protobuf 与编译版本不一致 | 在 venv 内编译，隔离系统包 |
121+
| `ccache` 缓存失效导致全量重编 | 头文件路径变更 | 清理 ccache: `ccache -C` |
122+
| whl 安装后 import 报错 | 旧 .so 残留 | `--force-reinstall` 或清理 `site-packages/paddle` |
123+
124+
## 完整一键编译示例
125+
126+
```bash
127+
cd /workspace/Paddle
128+
source .venv/bin/activate
129+
cd build
130+
ninja -j$(nproc) && cd .. && uv pip install build/python/dist/*.whl --no-deps --force-reinstall
131+
```
132+
133+
## 调试编译（Debug 模式）
134+
135+
需要 gdb 调试 C++ 代码时，将 `CMAKE_BUILD_TYPE` 改为 `Debug`：
136+
137+
```bash
138+
cmake .. -GNinja -DCMAKE_BUILD_TYPE=Debug [其他选项...]
139+
ninja -j$(nproc)
140+
```
141+
142+
Debug 模式编译产物更大、运行更慢，仅在需要调试时使用。
143+
144+
## 关键目录
145+
146+
| 目录 | 说明 |
147+
|------|------|
148+
| `build/` | 构建产物根目录 |
149+
| `build/python/dist/` | 生成的 whl 文件 |
150+
| `build/compile_commands.json` | clangd 索引文件 |
151+
| `paddle/phi/kernels/` | PHI kernel 源码 |
152+
| `paddle/phi/ops/yaml/` | 算子 YAML 定义 |
153+
| `cmake/` | CMake 模块和工具链 |

‎skills/paddle-debug/SKILL.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
name: paddle-debug
3+
description: 专注于在 Paddle 代码库中定位问题并输出高质量调试报告的调试流程与技巧；代码修复是在结论充分后的后续步骤。遇到 Paddle 框架、算子、训练脚本或分布式训练相关问题时，优先使用本 skill 规划调试与报告输出。
4+
---
5+
6+
# Paddle 仓库调试
7+
8+
## 调试流程
9+
10+
### 1. 描述问题并构造最小复现
11+
12+
- 用简洁的自然语言说明：
13+
- 触发步骤（命令、脚本、关键配置）。
14+
- 期望行为 vs 实际行为。
15+
- 是否只在特定环境 / 机器 / 设备 / 数据子集上出现。
16+
- 任何调试开始前，**先确认 bug 能被稳定复现**。若按照给定命令或脚本无法复现：
17+
- 检查命令是否抄错、参数是否缺失；
18+
- 比对并对齐环境（Paddle / Python / CUDA / CUDNN / 驱动 / 显卡型号等）；
19+
- 确认与最初出问题的环境一致后再继续。
20+
- 尽量抽取一个独立的 Python 脚本（或单测）承载问题：
21+
- 固定随机种子（`numpy` / `random` / `paddle.seed` 等）；
22+
- 使用固定、可序列化的小数据（固定随机数或离线样本）；
23+
- 去掉与问题无关的逻辑（复杂数据增强、冗余日志、训练循环中的花活等）。
24+
- 目标是做到：
25+
- 一条命令即可复现：`python reproduce_xxx.py`；
26+
- 输入、输出和错误信息尽量稳定可重复。
27+
28+
### 2. 代码定位与多假设验证
29+
30+
#### 2.1 使用工具定位代码
31+
32+
- **ast-grep**：用于结构化代码搜索，快速定位特定代码模式，推荐 ast-grep/agent-skill 中的 ast-grep 技能。
33+
34+
#### 2.2 带观测点的复现
35+
36+
- 阅读报错栈和相关代码时，先列出**多个可能原因假设**（数据异常、shape 错误、数值不稳定、环境不一致、算子实现问题等），不要立刻改代码。
37+
- 围绕这些假设，在关键路径上加入**观测点**，用合适的方式采集运行时信息（print、logger、profiling、断点、额外统计等）。
38+
- 常用观测方式：
39+
- 打印与断言：
40+
- 在关键算子调用前后，打印 Tensor 的 shape、dtype、device、数值范围（min/max/mean）。
41+
- 使用断言检查 shape、数值范围、NaN/Inf，在异常刚出现时 fail fast。
42+
- 对比法：
43+
- 对同一逻辑分别在 CPU / GPU 上运行，比较中间结果差异。
44+
- 通过简化模型或更小 batch 验证问题是否依赖规模。
45+
- 版本与环境信息：
46+
- 记录 `paddle.__version__`、CUDA/CUDNN 版本、驱动信息等，保证之后能在相同环境下复现。
47+
- 每完成一次带观测点的复现：
48+
- 基于运行时数据**排除不成立的假设**，收敛到少数更可疑的根因；
49+
- 在更窄的范围内继续加观测点，逐步缩小问题所在的模块 / 算子 / 配置。
50+
- 将本轮调试产生的原始日志和关键观测结果统一保存到 `.paddle-agent/debug-logs/` 目录，便于后续对比与归档。
51+
52+
### 3. 先写问题分析报告，再做最小修复
53+
54+
- 基于已有观测和对比结果，先完成**问题分析报告**，重点回答：
55+
- 如何复现：命令、环境、最小脚本路径；
56+
- 现象是什么：错误信息或异常行为；
57+
- 根因是什么：配置 / 数据 / 框架 / 算子 / 环境中的哪一处有问题；
58+
- 有哪些关键证据：日志片段、对比结果、重要观测点输出。
59+
- 报告以独立文件形式存放在 `.paddle-agent/debug-analysis/` 目录，按问题编号或日期命名，便于团队检索。
60+
- 归因时可结合以下典型维度进行简要说明：
61+
- 接口 / 形状 / dtype：
62+
- 指出出错的 Paddle API 或算子，以及哪个输入 Tensor 的 shape / dtype 与预期不符。
63+
- NaN / Inf / 数值发散：
64+
- 说明哪一层或哪段前向 / 反向首次出现异常数值，以及关闭某些损失项或调整学习率后的对比结果。
65+
- 性能与显存：
66+
- 指明瓶颈主要在 CPU、IO 还是 GPU kernel，以及简化数据增强或调整 batch size / num_workers 后的变化。
67+
- 只有在分析结论较为充分且需要推进修复时，才进入「最小修复」阶段：
68+
- 设计**改动面尽量小**的一组修改来验证根因，而不是大范围重写或连带修改无关模块。
69+
- 先用最小复现脚本验证问题已被修复且未引入新异常；
70+
- 再用完整训练 / 推理脚本验证关键业务路径；
71+
- 若问题仍存在或出现新异常，则基于新现象补充观测点，继续新的「假设 → 埋点观察 → 验证 / 否定 → 小步修复」循环。
72+
73+
### 4. 利用 Git / CI 收束和巩固结论
74+
75+
- 当判断问题可能由近期提交引入时：
76+
- 使用 `git bisect` 对可疑提交范围做二分定位，将排查范围压缩到少量变更。
77+
- 对已经定位并（准备）修复的问题：
78+
- 补充一条覆盖「最小复现脚本」逻辑的单测，防止后续回归；
79+
- 留意 CI 中与该模块相关用例是否出现新增失败或波动，并在调试报告中记录；
80+
- 将最终结论与关键证据沉淀到 `.paddle-agent/debug-analysis/` 中对应的问题文档，保证与代码和用例信息一致。
81+
82+
## 注意事项
83+
84+
- 调试的第一目标是**稳定复现并缩小范围**，不要一开始就尝试大规模重构或到处改逻辑。
85+
- 任何「只在某些机器上出现」的问题，优先从环境差异入手，而不是猜测代码随机出错。
86+
- 对于已经完成一次完整调试闭环的问题，建议整理：
87+
- 问题现象与复现步骤；
88+
- 归因（配置 / 数据 / 框架 / 算子 / 环境）；
89+
- 关键证据（日志、对比实验、最小复现脚本）；
90+
- 最终修复方案及其对行为、性能的影响。
91+
- 在 Paddle 仓库或相关项目中遇到 bug 时，优先按本 skill 的流程执行，再考虑具体修复实现细节。

‎skills/paddle-design-distributed/SKILL.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
name: paddle-distributed
3+
description: "Use when working with Paddle's distributed training, dynamic-to-static conversion (SOT/dy2st), or Python-C++ interoperability: understanding parallelism strategies, SPMD sharding rules, pipeline scheduling, PaddleSOT bytecode-level graph capture, or how C++ core is exposed to Python via pybind11 and Python/C API."
4+
---
5+
6+
# Paddle 分布式训练、SOT 动转静与 Python-C++ 互操作
7+
8+
## 分布式范式速查
9+
10+
| 范式 | 核心思想 | 通信原语 |
11+
|------|---------|---------|
12+
| **Data Parallel** | 复制模型，切分数据，AllReduce 梯度 | AllReduce |
13+
| **Group Sharded (ZeRO)** | Stage1 切 optimizer / Stage2 + 切 grad / Stage3 + 切 weight | Broadcast, ReduceScatter, AllGather |
14+
| **Model Parallel (Tensor)** | Column Parallel 切权重列 / Row Parallel 切权重行 | AllReduce / AllGather |
15+
| **Pipeline Parallel** | F-then-B / 1F1B 交错前反向 | Send / Recv (P2P) |
16+
| **Sequence Parallel** | 沿 sequence 维度切分 LayerNorm/Dropout | AllGather / ReduceScatter |
17+
18+
三种编程范式：**手动** (`fleet.meta_parallel`)、**半自动动态图** (`ProcessMesh` + `shard_tensor`)、**半自动静态图** (`auto_parallel.Engine`)。
19+
20+
## SOT 架构速查
21+
22+
```
23+
Python Frame
24+
│
25+
▼ PEP 523 eval_frame 拦截
26+
PyInterpreterState.eval_frame
27+
│
28+
▼
29+
OpcodeExecutor（模拟 Python VM 字节码执行）
30+
│ ├─ Variable 体系 (TensorVariable, ConstantVariable, ...)
31+
│ ├─ Tracker 追踪来源 → 生成 Guard
32+
│ └─ SideEffect 记录副作用
33+
▼
34+
FunctionGraph / StatementIR（记录算子调用）
35+
│
36+
▼ fallback 场景: DDCF / UNSPS / CDBL / UNIMP
37+
Sub-graph 切分 → StaticFunction 编译执行
38+
```
39+
40+
## 什么场景看什么文件
41+
42+
| 场景 | 文件 / 参考 |
43+
|------|------------|
44+
| 分布式策略原理（DP/Sharded/MP/PP/SP） | `references/distributed-primer.md` |
45+
| SPMD 推导规则与 Pipeline 调度 | `references/spmd-rules.md` |
46+
| SOT 动转静（字节码级别图捕获） | `references/sot-design.md` |
47+
| Python-C++ 桥接（pybind11 / Python/C API） | `references/python-cpp-bridge.md` |
48+
| ProcessMesh / shard_tensor API | `python/paddle/distributed/auto_parallel/` |
49+
| SPMD 推导规则 C++ 实现 | `paddle/phi/infermeta/spmd_rules/` |
50+
| Pipeline 调度器 | `python/paddle/distributed/passes/pipeline_scheduler_pass/` |
51+
| SOT 核心实现 | `python/paddle/jit/sot/opcode_translator/` |
52+
| Python-C 绑定源码 | `paddle/fluid/pybind/eager*.cc` |
53+
| 自动代码生成（Op 绑定） | `paddle/fluid/eager/auto_code_generator/generator/python_c_gen.py` |
54+
55+
## 社区源码入口 (L3)
56+
57+
- 分布式总目录：`python/paddle/distributed/`
58+
- PHI SPMD 规则：`paddle/phi/infermeta/spmd_rules/`
59+
- SOT 总目录：`python/paddle/jit/sot/`
60+
- pybind 目录：`paddle/fluid/pybind/`
61+
- 自动生成脚本：`paddle/fluid/eager/auto_code_generator/`

0 commit comments

Comments
 (0)