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 通常会把这个协调好。
- 在 autocast 下,程序带着 dtype 断言,AOTI 在 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")。