第 8 课：Transform Dialect、Pipeline 调试与面试设计

本课目标与完成标准

学完后你应能：把变换策略与 payload IR 分离，使用 IR dump/verify 定位第一个破坏不变量的 pass。

通过必须同时满足：

  • 独立补齐本课唯一的代码填空题，并通过给定检查；
  • 三个问答题均说明因果链，而不是只报术语；
  • 能指出至少一个正确性边界和一个性能取舍；
  • 总分不低于 8/10，且没有一票否决级概念错误。

前置关系

  • 课程前置：编译原理基础、C++ 阅读能力
  • 本课在路线中的作用：Transform dialect 用 handle 匹配 payload IR 并显式编排 tile/fuse/vectorize 等变换；它把调优策略表示成可检查 IR。

核心心智模型

1. 它是什么，解决什么问题

在传统的算子优化中，分块大小（Tile Size）、循环展开因子（Unroll Factor）、向量化策略以及多级流水线通常以硬编码（Hard-coded）的方式写死在 C++ Pass 逻辑中。这导致针对不同硬件架构（如 A100 vs H100 vs 手机端 NPU）或不同张量形状调优时，必须频繁修改、重新编译整个编译器，调优极其迟钝，且搜索空间（Autotuning Space）完全无法暴露给上层框架（如 Python 或 TVM-like Tuner）。 为了解决这一根本痛点，MLIR 提出了元编译控制系统——Transform Dialect。 它将“对计算图的变换调度策略（Schedule）”本身也提升为一段可解析、可验证、甚至可被元编译器优化的 IR 脚本（Transform IR），与实际执行数值计算的 Payload IR 实现正交解耦。 本课解决的核心工程问题是：理解 Transform Dialect 基于句柄（Handle）的元编程控制流与就地变异机制，掌握生命周期与失效契约（Consume vs Readonly），以及熟练运用 --mlir-print-ir-after-all、mlir-reduce 和 Reproducer 黄金工具链，快速定位编译管线破坏 Invariant 的根因。

2. 它如何工作

Transform 脚本驱动体系与编译管线排错全流程如图 8-1 与图 8-2 所示：

图 8-1：Transform Dialect 元调度脚本与被变换 Payload IR 的解耦驱动体系

图 8-2：MLIR 编译管线排错、最小化复现与诊断全流程

  1. 解耦的双重 IR 体系（Transform Script vs Payload IR）： 如图 8-1 所示，系统存在两套相互映射的 IR：
    • Payload IR：用户真实的计算代码（如 linalg.matmul）；
    • Transform IR：指示如何变换 Payload 的元脚本（如 @__transform_main）。 Transform 脚本中的 SSA 变量（如 %target、%tiled）称为 Handle（句柄），其类型通常为 !transform.any_op 或 !transform.op<"linalg.matmul">。Handle 内部维护的是指向 Payload IR 中对应 Operation 节点的动态指针集合。
  2. 解释执行与就地变异（In-place Payload Mutation）： Transform 解释器顺序执行脚本：
    • 步骤一（匹配）：%target = transform.structured.match ops{["linalg.matmul"]} in %root，在 Payload 中抓取所有的矩阵乘节点；
    • 步骤二（瓦片化）：%tiled, %loops:2 = transform.structured.tile_using_for %target tile_sizes [32, 32]（旧版本中的 tile_to_scf_for 已被移除；生成 scf.forall 时用 tile_using_forall）。该操作修改 Payload IR 生成双重 scf.for 循环，并将原 %target 替换为瓦片化后的内部 linalg.matmul。同时，原 %target 句柄被消费并标记为失效（Consumed），产生全新的合法句柄 %tiled；
    • 步骤三（向量化）：transform.structured.vectorize %tiled，进一步将瓦片就地降低为 vector.contract。
  3. 管线调试黄金工具链（Pipeline Debugging Workflow）： 如图 8-2 所示，当复杂 Pass Pipeline 发生崩溃或 Verifier 拒绝时：
    • 运行 mlir-opt --mlir-print-ir-after-all，在每个 Pass 之后打印 IR；加 --mlir-print-ir-after-change 只打印 IR 发生变化的 Pass，--mlir-print-ir-before-all 打印执行前的 IR，--mlir-print-ir-after-failure 只打印失败 Pass 之后的 IR；配合 --mlir-disable-threading 可保证输出顺序；
    • 利用 --mlir-pass-pipeline-crash-reproducer=/tmp/repro.mlir 在崩溃或失败时生成带 pipeline 信息、可用 mlir-opt --run-reproducer 单独重放的复现文件（--mlir-pass-pipeline-local-reproducer 可进一步缩小到出错的那个 Pass）；
    • 使用 mlir-reduce 配合判定脚本做自动化缩减（Delta Debugging），剔除与问题无关的 IR，得到更小的触发用例。

3. 正确性条件与常见误区

  • 句柄失效与野句柄访问（Dangling Handle Violation）： 这是 Transform Dialect 中最容易犯的错误。很多 Transform 操作具有破坏性消费语义（Consumes Handle）。例如执行 Tiling 操作后，原有的单一大矩阵乘已被拆毁，旧句柄 %target 指向的节点在 Payload 中已不复存在。若后续代码尝试再次使用旧句柄 %target，在开启 expensive checks（默认开启）时解释器会报错（如 op uses a handle invalidated by a previously executed transform op）；关闭检查时则是未定义行为。

  • 定位“第一个坏 IR”而非“崩溃抛出点”： 很多时候，Pass A 破坏了某个未立即验证的不变量（例如留下了未定义的 SSA 引用或损坏的支配树），但 Pass A 本身没有崩溃；直到数十个 Pass 之后，Pass Z 的 Verifier 或内存访问才最终被引爆。此时看 Pass Z 的报错无济于事，必须通过逐步 Diff 找出第一个使 Verifier 失效的源头 Pass。

  • 变换失败的传播策略（Silenceable vs Definite Failure）： Transform op 失败分为可静默失败（Silenceable Failure，可由 transform.alternatives 或 failure_propagation_mode = suppress 的 sequence 接住，交给备用策略）与致命失败（Definite Failure，立即中止）。transform.structured.match 找不到目标时返回空句柄而不是失败，后续变换对空句柄通常什么也不做；若不检查，可能导致流水线静默跳过核心优化。

4. 性能与工程取舍

  • Transform Dialect vs 硬编码 C++ Pipeline：
    • Transform Dialect 胜出场景：大模型算子内核深度调优（Search-based Autotuning）。调度策略作为独立文本存在，上层调优器（Python脚本）可以快速修改 [BM, BN, BK] 参数并复用同一套二进制运行时，无需重新编译 C++ 源码；并且策略可以保存在 Git 中与特定模型权重版本协同演进；
    • 硬编码 Pipeline 适用场景：固定的通用基础规范化（如 DCE、常量折叠、标量类型降级），这些优化与具体形状参数无关，硬编码在 C++ 中能获得更短的编译器启动延迟和更少的内存元数据开销。

具体演示

以对矩阵乘法应用调度变异为例：

module attributes {transform.with_named_sequence} {
  transform.named_sequence @__transform_main(
      %root: !transform.any_op {transform.readonly}) {
    %matmul = transform.structured.match ops{["linalg.matmul"]} in %root
      : (!transform.any_op) -> !transform.any_op
    transform.yield
  }
}
  • 输入：%root 句柄绑定顶层 Module。
  • 匹配：transform.structured.match ops{["linalg.matmul"]} 精准抓取所有 linalg.matmul 操作并赋予强类型句柄 %matmul。
  • 若随后执行先降级循环（Lower to loops）再尝试匹配 linalg.matmul，由于 Payload 的抽象层级已被降解，匹配会返回空集合，后续所有结构化变换直接静默熔断。

请在阅读后先合上这一节，用自己的语言复述“输入状态 → 中间状态 → 输出状态”，再做练习。

实践任务：唯一代码填空题

补齐 transform sequence 对 linalg.matmul 的匹配。

规则：只能修改 TODO/______ 所在位置；不要删除断言或放宽误差。代码注释说明了每个边界条件。

Code 
%%writefile /tmp/lesson08.mlir
module attributes {transform.with_named_sequence} {
  transform.named_sequence @__transform_main(
      %root: !transform.any_op {transform.readonly}) {
    %matmul = transform.structured.match ops{[______]} in %root
      : (!transform.any_op) -> !transform.any_op
    transform.yield
  }
}

检查方法

按当前 MLIR 版本核对 transform syntax 并运行 mlir-opt；API 会演进，因此以仓库版本文档为准。

提交时请给出：补齐后的代码、实际运行输出（环境不可用时注明“仅静态审查”）以及对失败用例的解释。

Q1

不要背定义：请从输入、状态变化和输出三个阶段解释“Transform Dialect、Pipeline 调试与面试设计”的工作机制。

你的答案：

Q2

某 pass 后 verifier 才失败，为什么应定位“第一个坏 IR”而不是最终报错 op？

你的答案：

Q3

什么情况下 transform dialect 比硬编码 C++ pass pipeline 更合适？

你的答案：

评分与通过规则

  • 代码 4 分：正常输入 2 分，边界输入 1 分，解释实现 1 分；
  • Q1～Q3 各 2 分；
  • 一票否决：结果碰巧正确但核心因果链错误、删除边界检查、把未运行结果说成实测。

需要提示时按四级机制请求：概念区域 → 具体方向 → 关键局部 → 完整答案。

参考答案（仅 answer 分支）

先完成题目再核对。即使代码一致，也要能解释关键步骤，并尝试更换一个输入规模。

Code 
%%writefile /tmp/lesson08.mlir
module attributes {transform.with_named_sequence} {
  transform.named_sequence @__transform_main(
      %root: !transform.any_op {transform.readonly}) {
    %matmul = transform.structured.match ops{["linalg.matmul"]} in %root
      : (!transform.any_op) -> !transform.any_op
    transform.yield
  }
}

Q1 参考答案

从三个阶段拆解其运行机制：

  1. 输入阶段（解耦载入与元句柄初始化）：系统同时载入两份 IR：被变换的目标计算图（Payload IR）与描述优化策略的调度脚本（Transform IR）。解释器以顶层根节点初始化入口句柄（如 %root），建立句柄到实际 Operation 指针的抽象引用。

  2. 状态变化阶段（解释执行、模式搜寻与拓扑就地变异）：Transform 解释器顺序解释执行每个元操作。首先通过 match 算子按类型或属性在 Payload 中搜索目标计算节点生成句柄；随后调用变换算子（如 tile_using_for、vectorize）直接对 Payload IR 实施就地增删改。操作完成后，原句柄被标记为消费失效，解释器生成指向新生成节点的新句柄，并保证每一步变异前后 Payload 的类型与支配关系自洽。

  3. 输出阶段（调度终结与变异后 Payload 移交）：脚本执行至 transform.yield 顺利终结。变异完成的 Payload IR（例如原本的矩阵乘已被展开为带有向量融合指令的多层嵌套循环）脱离 Transform 上下文，移交给后续的标准后端 Pass 进行底层机器码生成。

Q2 参考答案

在大型编译器排错时，如果某一后端 Pass 运行时 Verifier 校验失败或崩溃，必须顺着流水线倒查“第一个制造坏 IR 的 Pass”，而不是纠结于最终报错的算子，原因在于：

  1. 错误会延迟暴露：上游 Pass A 可能破坏了某个不变量（例如留下违反支配关系的使用，或破坏了某个 op 的语义约束），而这个不变量不一定被立即检查（例如关闭了 -verify-each，或违反的是 verifier 不检查的语义约束），Pass A 照常完成。
  2. 报错点只是第一个检查者：损坏的 IR 经过 Pass B、C 继续传递，直到某个依赖该不变量的 Pass Z 断言失败。Pass Z 的代码可能没有问题；在 Z 处打补丁（如加判空）只会掩盖错误。

做法是用 --mlir-print-ir-after-all 或逐个 Pass 运行 verifier，找到第一个产出非法 IR 的 Pass（详见第 2 节第 3 条与第 3 节第 2 条）。

Q3 参考答案

在以下典型工程场景中，Transform Dialect 显著优于硬编码的 C++ Pass Pipeline：

  1. 针对异构硬件与多形状的大规模自动调优（Autotuning / Search-based Optimization）： 在高性能算子库（如类似 FlashAttention、GEMM 调优）开发中，最佳的 Tiling 尺寸（如 32 vs 64）、流水线级数、向量化宽度强依赖于具体的矩阵尺寸 (M,N,K)(M, N, K) 和目标 GPU 架构。使用 Transform Dialect 可以将调度策略完全抽取为外部文本脚本。自动调优框架（如 Python 贝叶斯搜索器）仅需动态生成不同的 .mlir 调度脚本即可测算性能，完全无需频繁重新编译庞大的 C++ 编译器代码库。

  2. 跨团队协作与生产环境策略热更新： 算法或算子优化专家只需要编写和修改 Transform 脚本即可指导编译器生成最优代码，无需深入理解复杂的 C++ MLIR 编译框架内部实现；优化策略可以作为类似配置文件的独立资产进行版本控制、回归测试与动态分发。

参考资料

资料用于建立事实基线；面试回答仍需用自己的语言组织。

← 上一课
第 7 课：逐级 Lowering 到 LL… 下一课 →
第 1 课：PyTorch 执行栈、Disp…