Transformers 里的 LayoutLMv3 现在可以用 SDPA 了
到这周为止,Hugging Face Transformers 里的 LayoutLMv3 只有一个手写的 eager 注意力,而且每一层都要从头重建一遍相对位置偏置。我的 PR huggingface/transformers#50688 把它迁移到了库的注意力接口上,现在可以直接用 PyTorch 的 SDPA,也可以用 flex attention。这个 PR 同时关闭了一个提了很久的功能请求 #35467。PR 已于 2026 年 11 月 17 日合并,改动已经在 main 上,会随下一个版本发布。
先看结果。用 microsoft/layoutlmv3-base 做 token 分类,A100,fp16 autocast:
| 文本 token 数 | 模式 | batch | 之前(eager) | 现在(SDPA) |
|---|---|---|---|---|
| 512 | 推理 | 8 | 51.7 ms / 1.81 GiB | 28.3 ms / 1.27 GiB |
| 512 | 训练一步 | 8 | 129.7 ms / 9.58 GiB | 64.4 ms / 5.06 GiB |
| 2048 | 推理 | 2 | 119.2 ms / 3.45 GiB | 49.2 ms / 2.07 GiB |
| 2048 | 训练一步 | 2 | 显存不够(上限 15 GiB) | 94.3 ms / 6.98 GiB |
时间取 10 次迭代的平均值,显存是峰值(GiB),batch 里每隔一个样本有 padding。GPU 当时和别的任务共用,所以时间只能作为大致参考。2048 token 那两行把文本位置嵌入扩到了 2050。这不是官方发布的配置,但我就是这样用 LayoutLMv3 处理整页文档的(见《在 16 GB 显卡上用 LayoutLMv3 处理长文档》)。
原来慢在哪里
LayoutLMv3 会在注意力分数上加两个可学习的相对位置偏置:一个基于 token 位置,一个基于边界框的 x、y 坐标。两者形状都是 (batch, heads, n, n),而且每一层都完全一样。旧代码却在每一层都重新构建一遍:用 fp32 对每一对 (query, key) 做分桶,再到偏置表里取值,最后跑自己的 softmax。这个 softmax 是 CogView 论文里一个提高数值稳定性的变体。这样一来,SDPA 用不上,每层还会产生好几个 n x n 的 fp32 临时张量。在 2048 token 时,正是这些临时张量让训练一步就爆了显存。
三处改动
1. 走注意力接口。自注意力现在像 BERT 一样通过 ALL_ATTENTION_FUNCTIONS 分发,并像 T5 一样把偏置作为 position_bias 传进去。SDPA 和 flex attention 都支持加性偏置,不需要任何特殊处理。FlashAttention 不支持加性偏置,所以仍然不支持,这和 UDOP 的情况一样。
2. 偏置只算一次。编码器每次前向只计算一次合并后的偏置,再传给每一层。
3. 对距离分桶,而不是对每一对分桶。相对位置的桶只取决于距离,并且超过 max_distance 后不再变化。所以代码只对 2 * max_distance + 1 个可能的距离分一次桶,把成对距离截断到这个范围,再用一次 index_select 取值。新加的测试在 600 个位置、坐标最大到 1000 的输入上,以零容差把它和“逐对分桶”做对比。
为什么输出没有变
替换 softmax 是我最小心的一步,因为下游有大量基于 LayoutLMv3 微调的模型。CogView 的技巧是在 softmax 之前计算 (x/α - max(x/α)) · α,其中 α = 32。32 是 2 的幂,在浮点数里除以它再乘回来是精确的,所以这个式子恰好等于 x - max(x);而 softmax 内部本来就会减去最大值。我没有只靠推理,而是在真实模型上做了验证。用 microsoft/layoutlmv3-base、batch 为 3(含 padding)、512 个文本 token 加 197 个图像 patch,新代码的 eager fp32 输出与旧代码在 CPU 和 A100 上都逐位一致。211 个梯度最多相差 1.1e-7,原因是旧代码的减最大值操作在反向图里。和 eager 相比,SDPA 的差异在 CPU 上为 3.2e-6,在 A100 上为 1.6e-5(token 分类 logits,fp32)。在 fp16 和 bf16 下,新旧代码的差异处于舍入误差级别。
review 改变了什么
Hugging Face 的 vasqu 审了这个 PR,他的三个要求改变了设计:
- 通过接口传偏置。我的第一版把偏置一次性合进注意力 mask,所有层共用。他要求改用标准的
position_bias参数。这样更干净,代价是训练时 SDPA 会在每一层把偏置和 padding mask 合并一次,并为反向传播各保留一份。2048 token 训练一步的峰值显存从 3.54 GiB 变成 6.98 GiB。我在 PR 里说明了这个取舍,它仍然远低于原来那个会爆显存的版本。 - 用标准的 eager 函数。这条背后有个不明显的原因。PP-DocLayoutV2 通过 Transformers 的 modular 代码生成复用了 LayoutLMv3 的类,它生成的文件里只有一个
eager_attention_forward,RT-DETR 检测部分的注意力也调用它。如果这个名字下是 CogView 版本,检测器的注意力也会被一起改掉。换成普通 softmax 后,PP-DocLayoutV2 的输出保持逐位一致。它的阅读顺序模型现在也支持 SDPA 和 flex:在 fp32 下,eager、SDPA、flex 三者相差不超过 4.8e-8。 - 修测试配置,而不是改测试。通用的 flex 测试在每个头小于 16 维时会放大
hidden_size,这会破坏 LayoutLMv3 的版面嵌入。我原来覆盖了这个测试,他建议直接改测试配置的初始值。把头数从 4 改成 2 后,每个头 18 维,通用测试不用任何修改就能跑。
怎么用
你的代码不需要任何改动:只要环境支持,SDPA 就是默认实现。下面这段代码在当前的 main 上可以运行:
import torch
from PIL import Image
from transformers import AutoProcessor, LayoutLMv3ForTokenClassification
processor = AutoProcessor.from_pretrained("microsoft/layoutlmv3-base", apply_ocr=False)
model = LayoutLMv3ForTokenClassification.from_pretrained("microsoft/layoutlmv3-base", num_labels=5)
print(model.config._attn_implementation) # "sdpa"
image = Image.new("RGB", (800, 1000), "white")
words = ["Invoice", "number", "12345"]
boxes = [[10, 10, 80, 30], [90, 10, 160, 30], [170, 10, 230, 30]]
inputs = processor(image, words, boxes=boxes, return_tensors="pt")
with torch.no_grad():
print(model(**inputs).logits.shape) # torch.Size([1, 7, 5])
有两点需要注意:
- 和 BERT 一样,
output_attentions=True需要设置attn_implementation="eager"。 - PR 标题带有 Transformers 表示破坏性改动的 🚨 标记。内部的注意力辅助函数变了,如果你的代码改过
cogview_attention,或者用到了每层的rel_pos/rel_2d_pos参数,需要相应更新。
代码、测试和基准测试是我借助 AI 编程助手(Claude)完成的,结果由我本人核对。