.. _attention-implementation-override:

注意力实现覆盖
================

最后更新：10/31/2025。

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

支持的注意力实现
------------------

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

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

何时覆盖
--------

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

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

配置示例
----------

PPO 训练使用 Eager 注意力
~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code:: bash

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

PPO 训练使用 SDPA 注意力
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: bash

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

Critic 模型覆盖
~~~~~~~~~~~~~~~~

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

.. code:: bash

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

YAML 配置
~~~~~~~~~~

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

.. code:: 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``。

故障排除
---------

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

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

示例错误解决
~~~~~~~~~~~~~

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

.. code:: bash

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

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