执行摘要

• 一句话：修复 WSL 平台循环导入导致 import vLLM 失败
• 推荐动作：此 PR 是紧急 bugfix，修复逻辑简单明确，值得快速合并。测试设计巧妙（伪造 uname 模拟 WSL），可作为类似场景的参考。对于阅读者，核心看点是理解循环导入的触发链。

功能与动机

修复 Issue #48397：在 WSL 上 import vLLM 时因 warning_once 引起的循环导入错误。PR #46511 修改后，WSL 下 is_pin_memory_available() 通过 warning_once 输出警告，但 warning_once 内部 _should_log_with_scope 会延迟导入 vllm.distributed.parallel_state，而 parallel_state 又导入 vllm.utils.torch_utils 中的 direct_register_custom_op，此时 torch_utils 尚未完成初始化（正在执行 PIN_MEMORY = is_pin_memory_available()），导致 ImportError。

实现拆解

1. 回退 warning_once 为 warning：在 vllm/platforms/interface.py 和 vllm/platforms/cuda.py 的 is_pin_memory_available() 方法中，将 logger.warning_once 改回 logger.warning，并添加注释引用 Issue #48397 以说明原因。
2. 添加注释：在两个文件的对应位置增加注释 # warning_once() causes a circular import on WSL, see #48397.，提高代码可维护性。
3. 新增 standalone 测试：创建 tests/standalone_tests/wsl_pin_memory_import.py，模拟 WSL 旧内核环境，验证 import vllm 成功。该测试遵循现有的 lazy_imports.py 模式，通过伪造 uname() 返回值来触发条件。
4. CI 集成：将新测试接入到 .buildkite/test_areas/misc.yaml 和 .buildkite/test-amd.yaml 中已有的 lazy_imports 测试步骤。

关键文件：

• vllm/platforms/cuda.py（模块 平台层；类别 source；类型 core-logic；符号 is_pin_memory_available）: CudaPlatformBase 的 is_pin_memory_available() 方法中的关键修改点，将 warning_once 改为 warning，并添加了注释。
• vllm/platforms/interface.py（模块 平台层；类别 source；类型 core-logic；符号 is_pin_memory_available）: Platform 基类的 is_pin_memory_available() 方法中的对应修改，保持一致性。

关键符号：is_pin_memory_available

关键源码片段

vllm/platforms/cuda.py

CudaPlatformBase 的 is_pin_memory_available() 方法中的关键修改点，将 warning_once 改为 warning，并添加了注释。

# vllm/platforms/cuda.py (CudaPlatformBase.is_pin_memory_available)
# 关键片段：将 warning_once 改为 warning 以避免循环导入
@classmethod
def is_pin_memory_available(cls) -> bool:
    if in_wsl():
        version = _get_wsl_kernel_version()
        if version is None or version < (4, 19, 121):
            # warning_once() causes a circular import on WSL, see #48397.
            logger.warning(
                "Using 'pin_memory=False' as WSL is detected and the "
                "WSL2 kernel version is below 4.19.121. This may slow "
                "down performance. Please run `wsl --update`."
            )
            return False
        import vllm.envs as envs
        return envs.VLLM_WSL2_ENABLE_PIN_MEMORY
    return True

vllm/platforms/interface.py

Platform 基类的 is_pin_memory_available() 方法中的对应修改，保持一致性。

# vllm/platforms/interface.py (Platform.is_pin_memory_available)
# 关键片段：将 warning_once 改为 warning 以避免循环导入
@classmethod
def is_pin_memory_available(cls) -> bool:
    """Checks whether pin memory is available on the current platform."""
    if in_wsl():
        # https://docs.nvidia.com/cuda/wsl-user-guide/index.html#known-limitations-for-linux-cuda-applications
        # warning_once() causes a circular import on WSL, see #48397.
        logger.warning(
            "Using 'pin_memory=False' as WSL is detected. "
            "This may slow down performance."
        )
        return False
    return True

评论区精华

Reviewer Harry-Chen 在第一次评论中指出测试不够有意义，因为测试环境不会真正运行在 WSL 上。作者随后清理了测试，并应要求添加了 inline 注释引用 Issue。最终 Harry-Chen 批准了 PR。

• 测试有效性 (testing): 作者清理了测试，并通过伪造 uname 模拟 WSL 环境，使其在非 WSL 下仍能验证代码路径。
• 添加注释 (documentation): 作者按要求添加了指向 Issue #48397 的注释。

风险与影响

• 风险：
  1. 回归风险：低。仅将两个调用点从 warning_once 改回 warning，不会影响非 WSL 平台。
  2. 性能影响：无。is_pin_memory_available() 每个进程只调用一次（被 @cache 装饰），warning_once 的重复抑制在此场景并无实际收益。
  3. 兼容性：无。warning 和 warning_once 对外部接口无影响。
     - 影响：直接影响：WSL 用户现在可以正常 import vLLM，不会因循环导入而崩溃。间接影响：警告信息在每次进程启动时都会输出，但每个进程只触发一次，影响可忽略。
     - 风险标记：核心路径变更, 缺少测试覆盖

关联脉络

• PR #46511 add warning_once for pin_memory: 当前 PR 正是回退该 PR 中引入的 warning_once 变更，以修复循环导入。