注意力实现覆盖

最后更新：10/31/2025。

默认情况下，VERL 的 FSDP 工作进程使用 flash_attention_2 作为注意力实现，以提高性能。但是，您现在可以根据需要覆盖此设置，以使用不同的注意力实现。

支持的注意力实现

支持以下注意力实现（取决于模型和硬件的兼容性）：

flash_attention_2：高性能注意力实现（默认）
eager：标准 PyTorch 注意力实现
sdpa：缩放点积注意力（PyTorch 原生）

何时覆盖

在以下场景中，您可能希望覆盖注意力实现：

调试：使用 eager 来简化调试并获得更好的错误消息
兼容性：某些模型或硬件配置可能不支持 flash_attention_2
内存约束：不同实现具有不同的内存特征
性能调优：测试不同实现以获得最佳性能

配置示例

PPO 训练使用 Eager 注意力

要覆盖 actor、rollout 和 reference 模型的注意力实现：

python3 ppo_trainer.py \
    +actor_rollout_ref.model.override_config.attn_implementation=eager \
    [other parameters...]

PPO 训练使用 SDPA 注意力

python3 ppo_trainer.py \
    +actor_rollout_ref.model.override_config.attn_implementation=sdpa \
    [other parameters...]

Critic 模型覆盖

对于包含 critic 模型的训练配置，您也可以覆盖其注意力实现：

python3 ppo_trainer.py \
    +actor_rollout_ref.model.override_config.attn_implementation=eager \
    +critic.model.override_config.attn_implementation=eager \
    [other parameters...]

YAML 配置

您也可以在 YAML 配置文件中指定注意力实现：

actor_rollout_ref:
  model:
    override_config:
      attn_implementation: eager
      # other overrides...

critic:  # if using a critic model
  model:
    override_config:
      attn_implementation: eager
      # other overrides...

重要说明

向后兼容性：如果您在覆盖配置中未指定 attn_implementation， VERL 将继续默认使用 flash_attention_2，确保与现有配置保持向后兼容。

模型支持：并非所有模型都支持所有注意力实现。在训练前，请确保您的模型与所选的注意力实现兼容。

性能影响：不同注意力实现具有不同的性能特征。 flash_attention_2 通常提供最佳性能，而 eager 提供更好的调试能力。

硬件依赖：某些注意力实现（如 flash_attention_2）可能需要特定的硬件或 CUDA 版本。如果遇到兼容性问题，请尝试使用 eager 或 sdpa。

故障排除

如果在使用特定注意力实现时遇到错误：

检查模型兼容性：验证您的模型是否支持所选的注意力实现
尝试 eager 注意力：使用 attn_implementation=eager 作为调试的回退选项
检查硬件要求：确保您的硬件支持该注意力实现
查看错误消息：注意力实现的错误通常会提供有关支持选项的明确指导

示例错误解决

如果您看到类似“flash_attention_2 不受支持”的错误，您可以通过切换到 eager 注意力来解决：

# Instead of the default flash_attention_2
python3 ppo_trainer.py +actor_rollout_ref.model.override_config.attn_implementation=eager

此覆盖确保您的训练能够继续进行，同时您可以调查 flash 注意力兼容性问题。