`transformers_compat.py` — Transformers 库版本兼容¶

文件路径: verl/utils/transformers_compat.py

文件概述¶

处理不同版本 HuggingFace Transformers 库的 API 差异，确保 verl 在不同版本下都能正常工作。

核心函数详解¶

1. FlashAttention 支持检查¶

try:
    from transformers.modeling_flash_attention_utils import flash_attn_supports_top_left_mask
except ImportError:
    def flash_attn_supports_top_left_mask():
        return False

新版 transformers 加入了 flash_attn_supports_top_left_mask，旧版没有。这里做了兼容。

2. 版本范围检查¶

@lru_cache
def is_transformers_version_in_range(min_version=None, max_version=None) -> bool:
    transformers_version = version.parse(importlib.metadata.version("transformers"))
    lower = version.parse(min_version) <= transformers_version if min_version else True
    upper = transformers_version <= version.parse(max_version) if max_version else True
    return lower and upper

用于检查当前安装的 transformers 版本是否在某个范围内，以决定使用哪个 API。

3. 视觉语言模型类选择¶

@lru_cache
def get_auto_model_for_vision2seq():
    try:
        from transformers import AutoModelForImageTextToText  # 新版
    except ImportError:
        from transformers import AutoModelForVision2Seq       # 旧版
        return AutoModelForVision2Seq
    return AutoModelForImageTextToText

Transformers v5 将 AutoModelForVision2Seq 重命名为 AutoModelForImageTextToText，这里自动选择。

核心函数列表¶

函数	说明
`flash_attn_supports_top_left_mask()`	FlashAttention mask 支持
`is_transformers_version_in_range()`	版本范围检查
`get_auto_model_for_vision2seq()`	获取 VL 模型类

与其他模块的关系¶

被 model.py 用来选择正确的 Auto 类
被需要 FlashAttention 的模块检查支持情况

小结¶

transformers_compat.py 是版本兼容的安全网，让 verl 能在不同 transformers 版本下稳定运行，无需用户手动调整。

transformers_compat.py — Transformers 库版本兼容¶