Qiming Bao · Blog · 2026 年 11 月 17 日 · English / 中文

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推理851.7 ms / 1.81 GiB28.3 ms / 1.27 GiB
512训练一步8129.7 ms / 9.58 GiB64.4 ms / 5.06 GiB
2048推理2119.2 ms / 3.45 GiB49.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,他的三个要求改变了设计:

怎么用

你的代码不需要任何改动:只要环境支持,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])

有两点需要注意:

代码、测试和基准测试是我借助 AI 编程助手(Claude)完成的,结果由我本人核对。