# PR #36702 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[ROCm] Attention selector reordering
- 合并时间：2026-03-25 17:42
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/36702

---

# 执行摘要
本 PR 重构了 vLLM 中 ROCm 平台上的 attention 后端选择逻辑，将 ROCM_ATTN 设为最高优先级以优化性能，移除冗余环境变量 VLLM_ROCM_CUSTOM_PAGED_ATTN，并更新 ROCM_ATTN 的 sinks 支持为 False。变更影响 ROCm 相关模块，旨在提升 attention 性能并简化配置，但需关注优先级调整可能带来的性能回归风险。

# 功能与动机
此变更的动机源于单元测试的增强（如 PR #36025 和 #35334），允许调整后端优先级。PR body 明确指出："Changing the priorities of ROCm attention backends to 1. ROCM_ATTN - when applicable it is the most performant backend today"，目标是让 ROCM_ATTN 作为默认首选后端，提升 ROCm 设备上的 attention 效率。同时，移除 VLLM_ROCM_CUSTOM_PAGED_ATTN 环境变量以简化配置，因为该变量已不再必要。

# 实现拆解
实现方案按文件拆解如下：
- **优先级逻辑核心**：在 `vllm/platforms/rocm.py` 中，`_get_backend_priorities` 函数被重构，新优先级顺序为：
  ```python
  backends = [
      AttentionBackendEnum.ROCM_ATTN,
  ]
  if rocm_aiter_ops.is_mha_enabled():
      backends.append(AttentionBackendEnum.ROCM_AITER_FA)
  if is_aiter_found_and_supported():
      backends.append(AttentionBackendEnum.ROCM_AITER_UNIFIED_ATTN)
  backends.append(AttentionBackendEnum.TRITON_ATTN)
  ```
 移除了基于 `VLLM_ROCM_USE_AITER` 等环境变量的复杂分支。

- **能力声明更新**：`vllm/v1/attention/backends/rocm_attn.py` 中 `supports_sink` 方法改为返回 `False`，文档 `docs/design/attention_backends.md` 同步更新 sinks 支持列，以避免 ROCM_ATTN 在 sinks 场景下回退到低效 Triton 实现。
- **环境变量清理**：`vllm/envs.py` 删除 VLLM_ROCM_CUSTOM_PAGED_ATTN 定义，CI 脚本 `.buildkite/scripts/hardware_ci/run-amd-test.sh` 移除相关设置。
- **测试和兼容性**：更新测试文件 `tests/v1/attention/test_rocm_attention_backends_selection.py` 以反映新优先级，修改 `vllm/_aiter_ops.py` 中 `is_aiter_found_and_supported` 函数使用 `on_mi3xx` 检查。

# 评论区精华
Review 讨论中关键交锋：
- **优先级顺序争议**：`gemini-code-assist[bot]` 指出代码中 AITER_FA 优先级高于 AITER_UNIFIED_ATTN，可能与描述不符，但作者 `gshtras` 回复：
 > By design
 确认这是有意设计，旨在优化性能选择。

- **aiter 检查问题**：`AndreasKaratzas` 提问：
 > Why not also check if aiter is enabled (`rocm_aiter_ops.is_enabled()`)?
 此问题未得到回复，暗示潜在遗漏，可能影响后端选择的正确性。

# 风险与影响
**风险**：
- **性能回归**：新优先级可能在某些场景（如使用 sinks 的模型）下选择次优后端，导致性能下降。
- **兼容性破坏**：移除 VLLM_ROCM_CUSTOM_PAGED_ATTN 环境变量可能影响依赖此配置的用户工作流。
- **测试覆盖不足**：测试更新未全面覆盖所有环境变量组合，可能隐藏边缘案例。

**影响**：
- **用户**：ROCm 平台 attention 性能预计提升，但需注意 sinks 场景下的回退；配置简化，减少环境变量管理负担。
- **系统**：后端选择更直接，代码维护性增强，但需监控实际性能数据。
- **团队**：开发者需更新测试和文档，理解新逻辑以避免误用。

# 关联脉络
本 PR 是 ROCm attention 优化系列的一部分，与历史 PR 关联：
- **PR #37453**和 **PR #38043**：均涉及 ROCm 平台 bugfix 和优化，特别是 gpt-oss 模型处理，与本 PR 的 sinks 支持调整相关。
- **PR #36025**和 **PR #35334**：在 PR body 中被提及，作为单元测试基础，可能涉及 attention 后端测试的先前改进。
整体脉络显示 vLLM 在持续优化 ROCm 平台性能，本 PR 通过优先级重构推动这一方向。