# PR #42726 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[ZenCPU] Add zencpu Platform Runtime Logging and Docs
- 合并时间：2026-06-16 20:23
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/42726

---

# 执行摘要

- 一句话：为 ZenCPU 平台增加运行时日志和文档
- 推荐动作：此 PR 值得精读，特别是日志添加模式（debug_once 统一为所有路径添加）和测试设计（硬件无关的 mock 测试），可作为平台可观测性增强的参考范本。

# 功能与动机

为了增加 AMD Zen CPU 平台的运行时可见性，方便用户通过实时日志确认 ZenCpuPlatform 是否激活、未量化的 GEMM 是否走 zentorch 路径（PR body 原文）。

# 实现拆解

1. 提升平台激活日志级别：在 `vllm/platforms/__init__.py` 的 `cpu_platform_plugin` 函数中，将 Zen 平台匹配成功时的 `logger.debug` 改为 `logger.info`，使得启动时直接输出“AMD Zen CPU detected with zentorch installed, using ZenCpuPlatform.”。
2. 添加 GEMM 分发路径日志：在 `vllm/model_executor/layers/utils.py` 的 `dispatch_cpu_unquantized_gemm` 函数中，对每个分发分支（zentorch、sgl-kernel、oneDNN、fallback）分别添加 `logger.debug_once` 调用，输出当前使用的内核名称和关键参数（如 prepack 状态）。
3. 新增单元测试验证日志：在 `tests/model_executor/test_cpu_unquantized_gemm_dispatch.py` 中新增 `test_dispatch_cpu_unquantized_gemm_logs_zentorch_dispatch`，通过 mock zentorch op 和平台检测，验证 `dispatch_cpu_unquantized_gemm` 在 Zen 路径下输出预期的日志字符串。
4. 更新安装与验证文档：在 `docs/getting_started/installation/cpu.x86.inc.md` 中新增“AMD Zen optimizations”章节（包含 Docker 构建、检测规则、支持 dtype、环境变量等）；在 `docs/getting_started/installation/cpu.md` 中引用该章节并新增 FAQ；在 `docs/models/hardware_supported_models/cpu.md` 中添加 AMD Zen 说明提示。

关键文件：
- `tests/model_executor/test_cpu_unquantized_gemm_dispatch.py`（模块 分发逻辑；类别 test；类型 test-coverage；符号 test_dispatch_cpu_unquantized_gemm_logs_zentorch_dispatch）: 新增测试用例验证 zentorch 路径日志输出，确保日志行为正确且可被 CI 覆盖。
- `vllm/model_executor/layers/utils.py`（模块 GEMM 分发；类别 source；类型 core-logic）: 在 dispatch_cpu_unquantized_gemm 的所有分支添加 debug_once 日志，增强分发可见性。
- `vllm/platforms/__init__.py`（模块 平台检测；类别 source；类型 core-logic；符号 cpu_platform_plugin）: 将 Zen 平台激活日志从 debug 提升为 info，使用户启动时即可确认平台类型。
- `docs/getting_started/installation/cpu.x86.inc.md`（模块 安装文档；类别 docs；类型 documentation）: 新增 AMD Zen 优化章节，包括检测规则、Docker 构建、环境变量等。
- `docs/getting_started/installation/cpu.md`（模块 安装文档；类别 docs；类型 documentation）: 添加 AMD Zen 优化章节链接和环境变量说明。
- `docs/models/hardware_supported_models/cpu.md`（模块 模型文档；类别 docs；类型 documentation）: 添加 AMD Zen CPU 支持说明，提醒用户模型兼容性不变。

关键符号：cpu_platform_plugin, dispatch_cpu_unquantized_gemm, test_dispatch_cpu_unquantized_gemm_logs_zentorch_dispatch

## 关键源码片段

### `tests/model_executor/test_cpu_unquantized_gemm_dispatch.py`

新增测试用例验证 zentorch 路径日志输出，确保日志行为正确且可被 CI 覆盖。

```python
# 测试 zentorch 路径的日志输出（硬件无关的单元测试）
@pytest.mark.usefixtures("_mock_zentorch_linear_unary")
def test_dispatch_cpu_unquantized_gemm_logs_zentorch_dispatch(monkeypatch):
    # 模拟当前平台为 Zen CPU
    monkeypatch.setattr(current_platform, "is_zen_cpu", lambda: True)
    # 期望的 prepacked 状态由环境变量和 zentorch op 能力决定
    expected_prepacked = bool(utils.envs.VLLM_ZENTORCH_WEIGHT_PREPACK) and hasattr(
        torch.ops.zentorch, "zentorch_weight_prepack_for_linear"
    )
    # 捕获 logger.debug_once 调用
    log_calls = []
    monkeypatch.setattr(utils.logger, "debug_once", lambda *args: log_calls.append(args))

    layer = torch.nn.Linear(16, 8, bias=True)
    utils.dispatch_cpu_unquantized_gemm(layer, remove_weight=False)

    # 断言日志内容与预期一致
    assert log_calls == [
        (
            "CPU unquantized GEMM dispatch: using zentorch_linear_unary (prepacked=%s)",
            expected_prepacked,
        )
    ]

```

### `vllm/model_executor/layers/utils.py`

在 dispatch_cpu_unquantized_gemm 的所有分支添加 debug_once 日志，增强分发可见性。

```python
def dispatch_cpu_unquantized_gemm(
    layer: torch.nn.Module,
    remove_weight: bool = False,
) -> None:
    # ... 前面的代码 ...

    # Zen CPU 路径：zentorch_linear_unary
    if current_platform.is_zen_cpu() and hasattr(torch.ops.zentorch, "zentorch_linear_unary"):
        zen_weight = layer.weight.detach()
        is_prepacked = False
        if envs.VLLM_ZENTORCH_WEIGHT_PREPACK and hasattr(
            torch.ops.zentorch, "zentorch_weight_prepack_for_linear"
        ):
            zen_weight = torch.ops.zentorch.zentorch_weight_prepack_for_linear(zen_weight)
            is_prepacked = True
        layer.cpu_linear = lambda x, weight, bias, _p=is_prepacked: (
            torch.ops.zentorch.zentorch_linear_unary(x, zen_weight, bias, is_weight_prepacked=_p)
        )
        if remove_weight:
            layer.weight = torch.nn.Parameter(torch.empty(0), requires_grad=False)
        # 添加日志：记录当前使用的内核及 prepack 状态
        logger.debug_once(
            "CPU unquantized GEMM dispatch: using zentorch_linear_unary (prepacked=%s)",
            is_prepacked,
        )
        return

    # sgl-kernel 路径
    if envs.VLLM_CPU_SGL_KERNEL and check_cpu_sgl_kernel(N, K, dtype):
        # ... 原有代码 ...
        logger.debug_once("CPU unquantized GEMM dispatch: using sgl-kernel weight_packed_linear")
        return
    # oneDNN 路径
    elif (
        ops._supports_onednn
        and current_platform.get_cpu_architecture() != CpuArchEnum.POWERPC
    ):
        # ... 原有代码 ...
        logger.debug_once("CPU unquantized GEMM dispatch: using oneDNN onednn_mm")
        return
    # fallback 路径
    # ... 原有代码 ...
    logger.debug_once(
        "CPU unquantized GEMM dispatch: using torch.nn.functional.linear (fallback)"
    )

```

# 评论区精华

1. **测试是否应跳过非 Zen 平台**：AndreasKaratzas 询问新测试是否应该跳过非 Zen CPU 硬件；amd-lalithnc 解释这是一个硬件无关的单元测试，通过 mock 模拟 Zen 环境，目的是在 CI 中也能验证 zentorch 路径的日志输出，因此不应跳过。结论：保持当前设计。
2. **日志级别与统一后端日志**：tlrmchlsmth 建议将 zentorch 路径的 info_once 改为 debug_once，并为所有后端添加类似日志，以便统一分发可见性。amd-lalithnc 最初只添加了 zentorch 日志，后根据建议为所有路径添加了 debug_once 日志。结论：所有分发路径都使用 logger.debug_once。
3. **安装文档简化**：tlrmchlsmth 指出安装命令过于复杂、版本过时，并建议使用 wheels.vllm.ai 索引简化安装步骤。amd-lalithnc 根据反馈改为使用索引和 GitHub API 获取最新版本。结论：安装命令简化。

- 测试是否应跳过非 Zen 平台 (testing): 保持当前设计，测试不跳过，在所有 CI 平台上执行。
- 日志级别与统一后端日志 (design): 所有分发路径都添加了 logger.debug_once 日志，级别统一为 debug。
- 安装文档简化 (documentation): 安装命令简化为使用 wheels.vllm.ai 索引，并动态获取最新 release 版本。

# 风险与影响

- 风险：
 1. 日志级别从 debug 提升为 info：可能产生额外的非关键日志，但条件严格（仅在真实的 AMD Zen CPU 且安装了 zentorch 时触发），影响可控。
 2. 核心分发路径添加日志：虽然使用 logger.debug_once 保证低开销，但如果大量模型加载时仍可能轻度影响启动时间。
 3. 文档版本依赖：安装命令中的 wheel 版本若未及时更新可能导致用户下载失败，但已改为动态获取。
 4. 测试覆盖：单元测试仅覆盖 zentorch 路径，其他分发路径的日志未通过自动化测试验证（依赖手动检查）。
 - 影响：**用户**：启动和运行时现在可以看到平台激活和 GEMM 选择日志，便于调试和确认优化是否生效。
**系统**：新增几行日志，无性能影响。
**团队**：文档增加了 AMD Zen 的完整安装和使用说明，降低了用户上手门槛，同时日志减少了对内部支持的依赖。

- 风险标记：核心路径日志 , 文档更新维护 , 测试覆盖不完整

# 关联脉络

- 暂无明显关联 PR