文档导航

compile=True 与 TileLang 快路径:工程笔记

这些笔记讲 compile=True 和 fast=True 在 README 之外的行为。它们来自在 #472、#576 和 #718 上工作时的实测,环境是 RTX 4070 Ti SUPER、torch 2.11 和 tilelang 0.1.14。放在这里,是为了 下一个人不用再测一遍。

后端选择

Agent(..., backend="auto") 和 laya.load(..., backend="auto") 选择启用后端类层。默认仍是 eager。显式的 backend= 优先于 compile 和 fast;省略它就保留这两个标志现有的行为。

  • eager:原装的 PyTorch 前向,在任何受支持的设备上。
  • compile:仅 CUDA 的 torch.compile,带动态形状和 reduce-overhead 模式、桶填充、持久化 inductor 缓存,并在安装时预热。它复用与 compile=True 相同的独立维度作用域,后者保留其现有的默认模式和 CPU 支持。设 LAYA_COMPILE_WARMUP=0 推迟后端预热,设 LAYA_INDUCTOR_CACHE_DIR 选择它的缓存目录(默认 ~/.cache/laya/inductor)。
  • tilelang:当前快路径之上的一个适配器,使用 agent 的 bf16 或 fp16 dtype。
  • auto:当安装了 TileLang、且有受支持的 ModernBERT 编码器和 dtype 时,在 CUDA 上用 TileLang;否则在 CUDA 上编译;其它设备上用 eager。
  • onnx:laya.load(..., backend="onnx", onnx_path="model.onnx") 返回现有的 ONNXAgent。没有 onnx_path 时,它用 laya.onnx。

一个不可用的后端会发出一个 RuntimeWarning,说出解析到的后端,并回退到 eager。要强制要求某个后端,就用 agent.set_backend("tilelang", strict=True)。切换会等待活跃推理;agent.backend 报告活跃的名称,agent.backend_object 暴露已安装的对象。agent.set_backend("compile", warmup=False) 把编译推迟到推理时,所以编译错误那时会在请求上浮现。agent.warmup() 仍然可用。agent.deaccelerate() 移除通过类层安装的后端。

Router 通过 Router(agent_kwargs={"backend": "auto"}) 转发显式的选择。它们默认不传后端参数,保持与现有类 Agent 构造函数的兼容性。作用域受限的 CPU OOM 重试会分离后端,并在模型回到其原始设备时恢复它。

compile=True 实体化注意力掩码

Eager SDPA 把 ModernBERT 的 (rows, 1, L, L) 注意力掩码当作一个广播视图。在 compile=True 使用的动态形状下,inductor 无法证明最后一维是对齐的。它把掩码扩展到每个头,并填充进一个真实的 rows x heads x L x L 缓冲区。在 bf16、12 个头的配置下,32 行 x 1024 token 时就是 0.8 GB。

  • GPU 有余量。 这个缓冲区消耗带宽,每个长批次几十毫秒。
  • GPU 接近占满。 缓存分配器会颠簸,同一次调用可能要几十秒。

如果在繁忙的 GPU 上用长批次编译,就限制批大小(predict_batch(..., batch_size=)) or use fast=True。TileLang 注意力读取打包的 QKV 缓冲区,并按序列长度做掩码, 所以它没有这样的缓冲区。

冷启动

  • 首次编译。 每个图要几十秒。compile=True 需要两个图:一个用于批,一个用于单行,后者由 torch 特化。compile=True 现在在加载期间调用 agent.warmup()。compile_warmup=False 恢复惰性 编译,而 agent.warmup(shapes=...) 仍可手动使用。Eager 和 TileLang 加载不会自动预热。这些形状 覆盖常见的请求,而不是每一种可能的形状守卫。
  • 预热失败。 自动预热是尽力而为:失败会发出一个 RuntimeWarning,说出错误(包括底层编译器 错误),加载带着完好的 torch.compile 包装器和编译设置返回。例如,没有 MSVC 的 Windows 可以 在预热失败的情况下仍以 compile=True 加载。后续请求仍使用编译后的模型并浮现编译失败;Laya 不会把它们切到 eager 执行。显式的 agent.warmup() 调用也会传播失败,包括在一次失败的自动预热 之后。所以一次成功的加载并不保证编译后的推理已经就绪。
  • Laya 缓存的选择启用。 laya.load(..., compile=True, compile_cache=True) 只在进程级 TORCHINDUCTOR_CACHE_DIR 缺失时才设置它,设为 $XDG_CACHE_HOME/laya/torchinductor,或在 XDG 未设置或不是绝对路径时设为 ~/.cache/laya/torchinductor。已有的设置(包括更早的 PyTorch 编译 所设的那个)优先。该目录在加载时创建;文件系统错误会传播。compile_cache=False(默认)、 eager 和 TileLang 加载不动环境。这不会移动或删除旧缓存。容器仍然需要一个持久的 home/卷。缓存 兼容性与失效由 PyTorch 管理;一次 GPU、torch、编译器、模型或输入守卫的变化可能要求重新编译。
  • 跨重启。 Inductor 的 FX-graph 缓存把编译好的图放在 TORCHINDUCTOR_CACHE_DIR 下。默认 在 /tmp 下,重启机器或重启容器就没了。把它设成一个持久目录,或者容器里的一个卷,第二个进程 就会加载这些图,而不是重新编译。在 #472 的实测里,这把预热从约 120 秒降到约 50 秒。

可选的 CUDA 图

agent = laya.load("convaiinnovations/laya", compile=True,
                  compile_cache=True, compile_mode="reduce-overhead")

compile_mode 默认是 "default";在活跃的编译路径上只接受 "default" 和 "reduce-overhead"。Eager 和 TileLang 加载忽略编译选项。CPU 编译仍然可用,但 CUDA 图记录只适用于 CUDA。CUDA 模式需要 PyTorch 的 torch.compiler.cudagraph_mark_step_begin API;没有它的更旧构建会抛出一个明确的错误。

动态的 Dynamo 图并不意味着形状无关的 CUDA 图:新的具体形状可能需要再次预热和记录,而不需要新的 Dynamo 图。两个默认的合成预热形状不会预记录每一种请求形状。重复的形状可以受益,但变化的形状可能要付出额外的延迟并保留图池。PyTorch 可能对不受支持的操作或配置跳过 CUDA 图;设置这个模式并不保证捕获。

Laya 把每次编译后的 CUDA 前向标记为一个新的步骤,在它的各个 agent 之间把这些前向串行化,并在释放锁之前把两个输出张量克隆到编译图之外。这使被保留的输出在重放之间保持有效,代价是两次拷贝和串行化的前向执行。这个锁不协调无关的、应用自己拥有的编译模型;共享 CUDA 图迭代或使用自定义流的调用方必须管理它们自己的协调。磁盘缓存跨进程复用编译后的代码,而不是实时的 CUDA 图记录或它们的设备内存。

用 benchmarks/bench_compile_defaults.py 复现冷/重启计时、内存和缓存计数;见记录的测量。

AOTInductor:还不行

为每个 checkpoint 和 GPU 架构预先编译一个产物(torch._inductor.aoti_compile_and_package), 就能完全省掉编译。在 torch 2.11 上,它卡在打包这一步:

  • 导出没问题。 对 DecisionModel 做 torch.export 能成功,约 5 秒,带动态的 rows、 markers 和 tokens。tokens 必须声明成 16 的倍数(16 * Dim(...));普通的 range 过不了 导出器自己的 L % 8 对齐检查。这跟上面是同一个掩码对齐问题。
  • 打包失败。 怎么失败,取决于程序是怎么导出的:
    • 在 autocast 下,程序带着 dtype 断言,AOTI 在 autocast 之外会踩中它: Tensor dtype mismatch! Expected: torch.bfloat16, Got: torch.float32。
    • 从不带 autocast 的 bf16 副本出发,trace 会在前向里失败: mat1 and mat2 must have the same dtype。DecisionModel.forward 在 action head 之前 把池化后的 state 和置信度特征升到 fp32,而 autocast 通常会把这个协调好。

所以产物这条路需要一个 dtype 明确的 action head:要么把它的输入转成 head 的 dtype,要么让 head 跑 fp32。

TileLang 的可移植性:内核只支持 CUDA

tilelang 为 CUDA、HIP、Metal、WebGPU 和一个 C 后端注册了 target。没有 AMD 或 Apple 硬件时, 还能回答的问题是:laya/tl_kernels.py 到底能不能为 CPU 降低。在 Linux x86-64 上用 tilelang.compile(kernel.prim_func, target=...) 探测:

target 结果
"cpu" 一开始就被拒绝:Target cpu is not supported。tilelang 的 CPU 后端是 "c"。
"llvm" Cannot find global function target.build.llvm。这个 wheel 不带 LLVM 后端。
"c" 降低到 C,能跑 CPU 张量,但只覆盖这门语言的一个子集。

每个 Laya 内核在 "c" 上都失败,原因属于这三类之一:

内核 在 target="c" 上的失败 用到的构造
gemm_kernel, gemm_geglu_kernel CPU fill only supports local and global buffers, but got dst scope local.fragment T.alloc_fragment 累加器
add_ln_kernel CPU reduce only supports local src and local/local.var dst buffers 对 fragment 做 T.reduce_sum / T.reduce_max
rope_kernel Cannot convert type bfloat16 to C type bf16 张量
attn_kernel 在 T.alloc_fragment 处失败 fragment

C 后端确实接受:

  • fp32 逐元素循环(T.Parallel);
  • T.Pipelined,它会降低成一个普通循环;
  • 带 T.alloc_local 累加器的 T.gemm,它会降低成一个标量三重循环。

所以一个 CPU 版本会是第二套内核,而不是一个 target 开关。它的 GEMM 会是不分块的标量循环, 也就没法跟原装前向在 CPU 上已经在用的 MKL/oneDNN 路径竞争。这三样构造也是在 HIP 和 Metal 上 首先要检查的:fragment、带 GemmWarpPolicy 的 T.gemm,以及 bf16/fp16 支持。

要复现第二张表的第一行:tilelang.compile(K.gemm_kernel(768, 768).prim_func, target="c")。