paddle-design-compiler

name: paddle-design-compiler description: "Use when working with Paddle 3.0 compiler full pipeline: SOT (Symbolic Opcode Translator) for bytecode-level dy2st graph capture, PIR (Paddle IR) for SSA-based intermediate representation, CINN for fused CUDA kernel generation, operator decomposition (Prim), or the end-to-end flow from Python eager code to optimized GPU execution."

Paddle 3.0 编译器全链路

Paddle 3.0 的编译器体系通过 SOT → PIR → CINN 三阶段流水线，将用户的动态图 Python 代码编译为高性能 GPU Kernel，实现「动态图编写、编译器加速」的开发体验。

全链路概览

用户 Python 代码（动态图 eager mode）
  │
  ▼  Stage 0: SOT 图捕获
  PEP 523 eval_frame 拦截 → OpcodeExecutor 字节码模拟
  → FunctionGraph / StatementIR
  → paddle.jit.to_static(full_graph=True) 编译子图
  → pir::Program
  │
  ▼  Stage 1: PIR Pass 优化
  pir::Program（SSA 形式的 pd_op.* 算子图）
  │  ├── ShapeOptimizationPass（InferSymbolicShape 动态 shape 符号推导）
  │  ├── 组合算子分解 (DecompInterface → primitive operators)
  │  └── 通用 Pass 优化（常量折叠、死代码消除等）
  │
  ▼  Stage 2: CINN 编译
  ├── PdOpToCinnOpPass / PdOpToDynamicShapeCinnOpPass（算子映射）
  ├── add_cinn_pass → cinn_op.group（算子融合）
  ├── OpLower（Compute + Schedule）→ LoweredFunc
  ├── CodeGenCUDA_Dev → CUDA source → NVRTC → CUfunction
  ├── CompilationCache（编译缓存，相同子图复用已编译 Kernel）
  │
  ▼  Stage 3: 执行
  PirInterpreter 调度 → CinnJitInstruction → cuLaunchKernel

SOT → PIR 的衔接：SOT 捕获的 StatementIR 被包装为 Python 函数后，通过 paddle.jit.to_static(full_graph=True) 再次走 AST Transformer 路径编译为 pir::Program（参见 python/paddle/jit/sot/symbolic/compile_cache.py）。这意味着 SOT 负责"图捕获"，而 to_static 负责"图编译"。

SOT（Symbolic Opcode Translator）

SOT 是 Paddle 3.0 的动转静前端，在 Python VM 字节码层面拦截和模拟执行用户代码，精确捕获 Tensor 计算子图。相比旧的 AST Transformer 方案，SOT 能处理 numpy/Tensor 互操作、动态控制流、第三方库调用等复杂场景。

核心机制

Python Frame
  │
  ▼  PEP 523 eval_frame 拦截
PyInterpreterState.eval_frame
  │
  ▼
OpcodeExecutor（模拟 Python VM 字节码执行）
  │  ├─ Variable 体系 (TensorVariable, ConstantVariable, ContainerVariable, ...)
  │  ├─ Tracker 追踪来源 → 生成 Guard（缓存有效性校验）
  │  └─ SideEffect 记录副作用（全局变量修改、可变对象修改）
  ▼
FunctionGraph / StatementIR（记录算子调用）
  │
  ├─ 无 fallback: 完整子图 → to_static(full_graph=True) → pir::Program
  └─ fallback: 子图切分 → 可静态化部分编译 + 不可静态化部分 Python 执行

Fallback 场景

Fallback 是安全兜底：任何无法处理的情况退化为部分子图编译 + 部分 Python 执行，不会导致报错。

使用方式

# full_graph=False（默认）：启用 SOT 模式（字节码级别捕获 + 自动 fallback）
# full_graph=True：使用传统 AST Transformer（要求整图可转）
net = paddle.jit.to_static(net)  # 默认 full_graph=False，即 SOT 模式
output = net(x)

PIR（Paddle Intermediate Representation）

PIR 是 Paddle 3.0 的统一中间表示，采用 MLIR 风格的 SSA 设计，替代旧的 ProgramDesc/OpDesc 体系。

核心概念

核心 Dialect

PIR Program 结构

Program
├── weights: unordered_map<string, shared_ptr<Parameter>>
└── ModuleOp (顶层 Operation)
    └── Region[0]
        └── Block[0]
            ├── builtin.parameter("w")      → %0  (从权重表读取参数)
            ├── pd_op.matmul(%input, %0)    → %1
            ├── pd_op.if(%cond)              → %2
            │   ├── Region[0] (then)
            │   │   └── Block[0]: pd_op.relu(%1) → cf.yield
            │   └── Region[1] (else)
            │       └── Block[0]: pd_op.tanh(%1) → cf.yield
            └── builtin.set_parameter(%2, "out")

组合算子分解（Prim）

将高层算子分解为基础算子（primitive operators），降低编译器 / 分布式 / 新硬件适配成本：

• 前向分解：DecompInterface → call_decomp_rule() → composite.h
• 反向分解（VJP）：两条路径——VjpInterface 经 call_vjp() 处理前向 op 的反向；DecompVjpInterface 经 call_decomp_vjp() 分解反向 op。规则实现均在 details.h
• CustomVJP：为 sigmoid、log_softmax 等数值敏感算子提供手写反向

PIR Pass 框架

PIR 提供 MLIR 风格的 Pass 基础设施，用于图优化：

• Pass：单个优化 Pass 基类，通过 Run(Operation*) 执行
• PassManager：管理 Pass 执行顺序，支持嵌套 Pipeline
• PatternRewritePass：基于 Pattern Matching 的重写 Pass，通过 RewritePattern 定义匹配和替换规则

CINN 编译与执行

CINN（Compiler Infrastructure for Neural Networks）将 PIR Program 中的算子子图编译为高性能 CUDA Kernel，由 PirInterpreter 调度执行。当前默认走动态 shape主线。

编译流水线（含动态 shape）

PIR Program (pd_op.*)
  │
  ▼  Stage 1: Frontend（前端）
  ├── ShapeOptimizationPass（InferSymbolicShape 符号推导）
  ├── PdOpToCinnOpPass / PdOpToDynamicShapeCinnOpPass（算子映射）
  ├── add_broadcast_to_elementwise_pass（显式 broadcast 插入）
  └── add_cinn_pass → cinn_op.group（按 OpPatternKind 融合）
  │
  ▼  Stage 2: Lowering（后端下降）
  ├── PirCompiler → CompilationTask（per GroupOp）
  │   ├── CompilationCache 查询（命中则跳过编译）
  │   ├── OpLower：Compute → AST IR → Schedule
  │   ├── DynamicShapeGroupScheduler（动态 shape 调度）
  │   └── LowerToAstVec → LoweredFunc
  │
  ▼  Stage 3: CodeGen（代码生成）
  ├── ir::Module → CodeGenCUDA_Dev → CUDA __global__ source
  └── nvrtc::Compiler → PTX → cubin → CUfunction
  │
  ▼  Stage 4: Execution（执行）
  └── cinn_runtime.jit_kernel (CINNKernelInfo: fn_ptr + symbol_args_map)
      └── CinnJitInstruction → cuLaunchKernel

OpPatternKind 融合规则

Group-level Schedule（DynamicShapeGroupScheduler）

编译缓存（CompilationCache）

CINN 对已编译的 GroupOp 结果进行缓存（基于 FusionInfo hash），相同结构的子图可直接复用已编译的 Kernel，避免重复编译开销。

执行（PirInterpreter）

编译完成的 Kernel 最终由 PirInterpreter 调度执行：

StandaloneExecutor
  └─ PirInterpreter (per Job)
       │
       ├─ Build（首次 Run，结果缓存）
       │   ├── 为每个 Op 构建 Instruction（Kernel 选择 + 数据传输插入）
       │   ├── 构建算子依赖 DAG → 传递性边消除
       │   ├── PirStreamAnalyzer 流调度分类（direct / event / sync）
       │   └── Variable 引用计数 → GC 生命周期管理
       │
       └─ Scheduling（每次 Run）
            ├── dep_count=0 的 Instruction 推入 work queue
            ├── 线程池并行派发 → kernel launch
            ├── 跨 stream 同步：cudaEventRecord + cudaEventWait
            └── ref_count=0 时回收 Variable 内存

CINN 编译产物通过 CinnJitInstruction 执行：从 CINNKernelInfo 获取 fn_ptr，收集输入输出 device pointer，调用 cuLaunchKernel。非 CINN 算子则通过 PHI Kernel 常规路径执行。

调试速查

什么场景看什么文件

源码入口

SOT

PIR

组合算子（Prim）

CINN

执行器（PIR-based）