# PR #50728 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[ROCm][Test] Fix AITER MXFP4 oracle contract
- 合并时间：2026-08-04 04:53
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/50728

---

# 执行摘要

- 一句话：修复 AITER MXFP4 oracle 测试配置与就地修改问题
- 推荐动作：该 PR 属于测试契约修正，值得快速浏览以理解两个教训：一是测试配置必须与上游转换器 / 内核的实际契约对齐，二是当被测试代码会就地修改输入张量时，参考计算应先克隆原始数据。实现本身简单，不需要精读。

# 功能与动机

PR #46298 把测试切换到 GPT-OSS MXFP4 转换器却保留了 SILU 配置，参考计算又复用了被转换器就地修改的张量；PR #49361 的新 AITER 版本将这个不一致暴露为 unsupported small-M kernel configuration 并导致 AMD CI 失败。本 PR 的目标是让 oracle 测试契约与转换器实现一致，同时回答审查者关于收紧精度容差的 TODO。

# 实现拆解

1. **调整 AITER_MXFP4_BF16 测试配置**：在 `tests/kernels/moe/test_ocp_mx_moe.py` 的 `ROCM_BACKEND_CONFIGS` 中，将 `AITER_MXFP4_BF16` 条目的 `activation` 从 `SILU` 改为 `SWIGLUOAI`，`rtol` 从 `1.0` 收紧至 `0.1`，`percent` 保持 `0.7`。原因是 GPT-OSS 转换器（PR #46298 引入）按 gate/up 交替的 `SWIGLUOAI` 布局处理权重，而 `SILU` 使用 chunked 布局，两者不一致导致新 AITER 版本（PR #49361）以不支持的 small-M 内核配置运行并失败。
2. **转换前克隆权重与缩放**：在调用 oracle 转换之前，对 `w13_quant`、`w13_scale`、`w2_quant`、`w2_scale` 执行 `clone()` 保存为 `w13_quant_ref`、`w13_scale_ref`、`w2_quant_ref`、`w2_scale_ref`。因为 AITER 转换会就地重排这些 checkpoint 格式张量的布局，直接使用原变量会使参考反量化基于被修改后的数据，与内核实际输入不一致。
3. **参考计算改用克隆张量**：将 `upcast_from_mxfp` 的输入从原张量切换为 `*_ref` 克隆张量，使 `reference_moe` 基于原始权重布局计算，保证与经过转换的 kernel 输入语义一致。代码注释中保留了进一步收紧阈值的 TODO。

本 PR 为纯测试修改，无产品代码、配置或部署配套改动；AMD CI 验证通过。

关键文件：
- `tests/kernels/moe/test_ocp_mx_moe.py`（模块 MoE 测试；类别 test；类型 test-coverage；符号 ROCM_BACKEND_CONFIGS, test_rocm_mxfp4_moe_oracle）: 核心修改文件：修复 AITER MXFP4 oracle 测试契约，将激活改为 SWIGLUOAI 并收紧 rtol，同时添加权重 / 缩放克隆以规避 AITER 转换器的就地修改问题。

关键符号：test_rocm_mxfp4_moe_oracle

## 关键源码片段

### `tests/kernels/moe/test_ocp_mx_moe.py`

核心修改文件：修复 AITER MXFP4 oracle 测试契约，将激活改为 SWIGLUOAI 并收紧 rtol，同时添加权重 / 缩放克隆以规避 AITER 转换器的就地修改问题。

```python
# ROCm oracle 测试的后端配置：每个后端声明激活、容差和运行前提
ROCM_BACKEND_CONFIGS = {
    "TRITON": {"activation": "SWIGLUOAI", "rtol": 0.3, "percent": 0.95,
               "requires_aiter": False, "requires_gfx950": False},
    "TRITON_UNFUSED": {"activation": "SWIGLUOAI", "rtol": 0.3, "percent": 0.95,
                       "requires_aiter": False, "requires_gfx950": False},
    # AITER_MXFP4_BF16 必须与 GPT-OSS 转换器契约保持一致：
    # 使用 SWIGLUOAI 而非 SILU，否则会触发不支持的 small-M 内核配置
    "AITER_MXFP4_BF16": {"activation": "SWIGLUOAI", "rtol": 0.1,
                         "percent": 0.7, "requires_aiter": True,
                         "requires_gfx950": True},
    "AITER_MXFP4_FP8": {"activation": "SWIGLUOAI", "rtol": 0.5,
                        "percent": 0.9, "requires_aiter": True,
                        "requires_gfx950": True},
}

# 在调用 AITER 转换 oracle 前，先克隆 checkpoint 格式的权重与缩放。
# 原因：AITER 转换会就地重排这些张量的布局；参考反量化必须使用原始布局，
# 否则计算出的 reference 与内核实际输入不一致。
w13_quant_ref = w13_quant.clone()
w13_scale_ref = w13_scale.clone()
w2_quant_ref = w2_quant.clone()
w2_scale_ref = w2_scale.clone()

# 参考计算使用克隆张量反量化，保持与转换前 checkpoint 布局一致
w13_dq = upcast_from_mxfp(w13_quant_ref.view(torch.uint8), w13_scale_ref,
                          torch.bfloat16, axis=-1)
w2_dq = upcast_from_mxfp(w2_quant_ref.view(torch.uint8), w2_scale_ref,
                         torch.bfloat16, axis=-1)

```

# 评论区精华

唯一实质讨论来自审查者 dllehr-amd 在 PR 评论中的提问：
> Hey @AndreasKaratzas Do you want to tighten up the rtol with this change as well? I noticed the TODO in the code asking to eventually handle this?

作者回复 "Done :)"，并在第二次提交中将 `AITER_MXFP4_BF16` 的 `rtol` 从 1.0 收紧至 0.1，完成了 TODO 中关于精度的改进。最终审查者 APPROVED。

- 是否顺带收紧 rtol 精度容差 (testing): 作者回复已完成，并在第二次提交中将 AITER_MXFP4_BF16 的 rtol 从 1.0 收紧到 0.1。

# 风险与影响

- 风险：风险集中在测试层：将 `rtol` 从 1.0 收紧到 0.1 可能增加测试对内核数值波动的敏感度，若 AITER MXFP4 内核在特定形状下精度波动较大，可能产生误报；但该用例仅在 `gfx950` 且启用 AITER 的环境运行，且 `percent=0.7` 允许 70% 的点通过，整体风险可控。另外，克隆数组增加少量显存占用（测试规模很小，可忽略）。无产品代码改动，不影响生产路径。
- 影响：影响范围限于 ROCm 环境下 `tests/kernels/moe/test_ocp_mx_moe.py` 的 oracle 测试，特别是 `AITER_MXFP4_BF16` 用例。修复后测试与 GPT-OSS 转换器契约一致，避免因配置不一致导致的 CI 失败，并提高精度敏感性，能更快暴露 AITER 内核回归。对用户无影响。
- 风险标记：测试容差收紧 , ROCm 专属测试路径

# 关联脉络

- PR #46298 Switch the ROCm MXFP4 MoE test to the GPT-OSS converter: 本 PR 解决的问题根源：该 PR 将测试切换到 GPT-OSS MXFP4 转换器却保留了 SILU 配置，留下不一致的 oracle 契约。
- PR #49361 Add AITER MXFP4 support for ROCm: 其新版 AITER 实现将不一致的测试配置暴露为构建失败，是本 PR 的直接触发因素。
- PR #50582 [ROCm][Kimi-K3] aiter moe environment variable cleanup: 同属 ROCm AITER MoE 相关改动，涉及 mxfp4 oracle 与 AITER 环境配置，与本 PR 为同一功能线的持续演进。