# PR #43331 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[ROCm] Enable the aiter top-k/top-p sampler by default
- 合并时间：2026-05-29 02:19
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/43331

---

# 执行摘要

- 一句话：启用 ROCm aiter 采样器并移除硬编码禁用标志
- 推荐动作：本 PR 变更极小但影响明确，建议 ROCm 用户确认 aiter 版本后合并。值得关注的是 review 中关于日志级别、版本依赖和验证方法的讨论，对后续类似 PR 有参考意义。

# 功能与动机

之前由于 aiter top-p 采样器的精度问题（特别是在 DeepSeek 模型上导致重复生成），vLLM 在 #32413 中通过硬编码 `DISABLE_AITER_SAMPLER = True` 禁用了该路径。上游 [ROCm/aiter#2035](https://github.com/ROCm/aiter/pull/2035) 已修复了该精度问题，因此禁用标志已过时，应移除以使 aiter 采样器能正常工作，并带来潜在的性能提升。

# 实现拆解

1. 在 `TopKTopPSampler.forward_hip` 中删除了 `DISABLE_AITER_SAMPLER = True` 及其关联的 FIXME 注释，使 aiter 采样路径不再被无条件跳过。
2. 在 `TopKTopPSampler.__init__` 中，最初将日志消息从 `info_once` 改为 `warning_once` 以提醒版本要求，后根据 review 建议恢复为原始的 `info_once`，因为上游 vLLM 已固定使用包含修复的 aiter v0.1.13。
3. 删除了最初引入的独立环境变量 `VLLM_ROCM_USE_AITER_SAMPLER`，改为仅依赖现有的 `rocm_aiter_ops.is_enabled()` 条件，该条件由全局环境变量 `VLLM_ROCM_USE_AITER` 控制。

关键文件：
- `vllm/v1/sample/ops/topk_topp_sampler.py`（模块 采样器；类别 source；类型 core-logic；符号 TopKTopPSampler, forward_hip, __init__）: 唯一变更文件；移除硬编码禁用标志，使 aiter 采样器在 ROCm 上默认启用，并调整了相关日志消息。

关键符号：forward_hip, __init__

## 关键源码片段

### `vllm/v1/sample/ops/topk_topp_sampler.py`

唯一变更文件；移除硬编码禁用标志，使 aiter 采样器在 ROCm 上默认启用，并调整了相关日志消息。

```python
def forward_hip(self, logits, generators, k, p):
    """Optimized ROCm/aiter path (same structure as forward_cuda)."""
    # 之前这里存在一行：DISABLE_AITER_SAMPLER = True
    # 导致即使 aiter 可用也无法进入该路径
    # 现已移除，使 aiter 采样器可正常启用

    if (k is None and p is None) or generators:
        # greedy 或种子采样时回退到 native
        return self.forward_native(logits, generators, k, p)

    if self.logprobs_mode in ("processed_logits", "processed_logprobs"):
        # aiter 不支持返回 logits/logprobs，回退到 native
        return self.forward_native(logits, generators, k, p)

    # aiter 路径：启用采样并返回
    return self.aiter_sample(logits, k, p, generators), None

```

# 评论区精华

review 中主要讨论了三个关键点：
- Rohan138 建议移除独立环境变量，直接利用现有的 `rocm_aiter_ops.is_enabled()` 条件，被采纳。
- dllehr-amd 建议将日志从 `warning_once` 降级为 `info_once`，因为 aiter v0.1.13 已包含修复，被采纳。
- tjtanaa 要求对非 seeded 采样路径（top-k/top-p/top-k+top-p）进行精确性验证，在提交了完整评估结果后获得批准。

- 移除独立环境变量，使用现有 gate (design): 采纳建议，删除了 `VLLM_ROCM_USE_AITER_SAMPLER`，仅依赖现有的 `VLLM_ROCM_USE_AITER`。
- 日志级别从 warning 降为 info (style): 日志级别改回 `info_once`，并移除了版本要求说明。
- 要求充分验证非 seeded 采样准确性 (testing): 验证通过，获得批准。
- 版本兼容性警告 (other): 未在代码中添加版本检查或警告；仅通过 commit 消息和 PR 描述说明需要 aiter v0.1.13+。

# 风险与影响

- 风险：
 - 版本兼容风险：如用户使用的 aiter 版本低于 v0.1.13（不含 #2035 修复），可能重新引入精度问题，导致采样质量下降或重复生成。未添加显式版本检查。
 - 测试覆盖风险：标准评测通常使用 seeded 路径，而非 seeded 路径的验证需要手动禁用 seeded fallback，可能被忽略。
 - 影响范围：仅影响 ROCm 后端，CUDA 和 XPU 不受影响。
- 影响：
 - 用户影响：ROCm 用户将默认获得更快的采样性能（吞吐量提升约 14%，ITL 降低约 14%），但需确保 aiter 版本满足要求。
 - 系统影响：无 API 或配置变更，仅内部采样路径默认切换。
 - 团队影响：清理了遗留 work-around 代码，降低维护成本。
 - 风险标记：缺少上游 aiter 版本检查 , 非 seeded 采样路径验证不充分 , 可能回归旧 bug

# 关联脉络

- PR #32413 [ROCm] Disable aiter sampler due to accuracy issue: 原始禁用 aiter 采样器的 PR，本 PR 撤销了该禁用。
- PR #32754 [ROCm] Sampler accuracy validation: 之前验证采样器精度的 PR，本 PR 参考了其验证方法。
- PR #33043 [ROCm] Add env var for aiter sampling: 提议类似环境变量的 PR，本 PR 采用了不同的替代方案。