执行摘要

• 一句话：废弃 9 个 MoE/线性环境变量，统一 FutureWarning
• 推荐动作：此 PR 是规范废弃流程的典范：明确的移除版本、集中管理、使用正确的警告类别。建议团队将此模式推广到其他废弃场景。对于读者，可以学习 deprecated_env 的设计（包装 getter、惰性警告），并关注如何在不破坏现有代码的前提下引导用户迁移。

功能与动机

这些环境变量（如 VLLM_USE_FLASHINFER_MOE_FP8、VLLM_USE_FBGEMM 等）已分别被 --moe-backend 和 --linear-backend CLI 标志替代，为了引导用户迁移到统一的配置接口，需要在废弃前发出可见的警告。PR body 要求使用对终端用户可见的 FutureWarning，并指定明确的移除版本。

实现拆解

1. 定义 centralized deprecated_env 辅助函数：在 vllm/envs.py 中新增 deprecated_env，接受 env_name、removal_version、replacement 和 getter，返回 _read 闭包；闭包仅在环境变量被显式设置（env_name in os.environ）时发出 FutureWarning，然后调用原始 getter。

2. 在环境变量字典中替换 9 个废弃条目：将 VLLM_USE_FLASHINFER_MOE_FP8 等 9 个环境变量在 environment_variables 中的定义从简单 lambda 改为 deprecated_env 包装，所有条目统一指定 removal_version="v0.23" 并给出具体的替换建议（如 --moe-backend flashinfer_trtllm）。

3. 清理线性内核中的内联警告：在 vllm/model_executor/kernels/linear/init.py 中移除 import warnings 以及 init_nvfp4_linear_kernel 函数内三个 elif 分支的 warnings.warn(..., DeprecationWarning) 调用，改为注释说明警告已由 vllm/envs.py 统一发出。

关键文件：

• vllm/envs.py（模块 环境配置；类别 source；类型 core-logic；符号 deprecated_env, _read）: 核心变更文件：新增 deprecated_env 函数，并将 9 个废弃环境变量条目从简单 lambda 替换为 deprecation 包装，是整个废弃逻辑的集中枢纽。
• vllm/model_executor/kernels/linear/__init__.py（模块 线性内核；类别 source；类型 data-contract）: 清理了原本分散在此文件中的内联 DeprecationWarning，将废弃通知集中到 envs.py，简化了线性内核选择逻辑。

关键符号：deprecated_env

关键源码片段

vllm/envs.py

核心变更文件：新增 deprecated_env 函数，并将 9 个废弃环境变量条目从简单 lambda 替换为 deprecation 包装，是整个废弃逻辑的集中枢纽。

def deprecated_env(
    env_name: str,
    removal_version: str,
    replacement: str,
    getter: Callable[[], Any],
) -> Callable[[], Any]:
    """Wrap an env-var getter to emit a FutureWarning when the var is set."""
    def _read() -> Any:
        if env_name in os.environ:
            # 只在用户显式设置时警告，默认值保持静默
            warnings.warn(
                f"{env_name} is deprecated and will be removed in "
                f"{removal_version}. {replacement}",
                FutureWarning,
                stacklevel=2,
            )
        return getter()
    return _read
​
# 在 environment_variables 字典中使用示例：
"VLLM_USE_FLASHINFER_MOE_FP8": deprecated_env(
    "VLLM_USE_FLASHINFER_MOE_FP8",
    "v0.23",
    "Use --moe-backend (e.g. flashinfer_trtllm, flashinfer_cutlass).",
    lambda: bool(int(os.getenv("VLLM_USE_FLASHINFER_MOE_FP8", "0"))),
),

评论区精华

核心讨论：gemini-code-assist[bot] 在多个 oracle 文件的 review 中指出，使用 DeprecationWarning 在默认情况下对终端用户是不可见的（会被 Python 过滤），应改用 FutureWarning。同时建议警告消息应避免在用户设置环境变量为 0（禁用）时仍然建议“启用”某个后端，以免造成混淆。

决策结果：作者采纳了这些意见，但选择了更彻底的方案——将所有警告逻辑集中到 envs.py 的 deprecated_env 函数中，统一使用 FutureWarning，并谨慎设计了消息措辞。原先分散在 oracle 文件中的内联 warning 被移除，改为单一入口的集中管理。此外，review 要求 removal_version 必须显式指定（最初使用默认值），已在第二次 commit 中修复。

• 使用 FutureWarning 替代 DeprecationWarning 以对终端用户可见 (design): 作者采纳了建议，进一步将所有警告集中到 envs.py 的 deprecated_env 函数，统一使用 FutureWarning 并优化消息措辞。

风险与影响

• 风险：警告可见性风险：虽然 FutureWarning 默认对终端用户可见，但某些日志配置可能将其过滤；建议使用者确认 CI 日志包含 FutureWarning。

行为一致风险：deprecated_env 仅在变量被显式设置时警告，与之前内联的 DeprecationWarning 行为一致。从 envs.py 的返回值来看，getter 被原样传递，因此原有逻辑无变化。

API 兼容性风险：linear/init.py 中移除了 DeprecationWarning，依赖该警告的监控工具会失效；但 centralized 的 FutureWarning 覆盖了相同场景，影响可控。

未覆盖情况：部分 Oracle 文件（如 fp8.py）中是否仍保留有重复的警告？从最终文件变更看，这些文件未修改，但之前的内联 warning 可能已被移除或保留。需要确认最终状态。

• 影响：用户影响：使用已废弃环境变量的用户会看到 FutureWarning（Python 默认显示），建议迁移到 CLI 标志。未设置这些变量的用户无任何影响。警告最多触发一次（通过 functools.cache 缓存），不会重复。

系统影响：无功能变化，performance 不受影响。

团队影响：精简了 21 行冗余代码，统一了废弃策略，降低了未来维护成本。引入了可复用的 deprecated_env 模式，可用于后续其他环境变量的废弃。

• 风险标记：废弃可见性, 配置迁移提醒

关联脉络

• PR #33807 Add --moe-backend CLI flag: 本 PR 废弃的环境变量 VLLM_USE_FLASHINFER_MOE_* 和 VLLM_FLASHINFER_MOE_BACKEND 正是被 --moe-backend 替代。
• PR #41566 Add --quantization_config.moe.activation: 废弃的 VLLM_USE_FLASHINFER_MOE_MXFP4_MXFP8 等需要与 --quantization_config.moe.activation 结合使用。
• PR #39538 Add --linear-backend CLI flag: 废弃的 VLLM_USE_FBGEMM、VLLM_USE_NVFP4_CT_EMULATIONS、VLLM_NVFP4_GEMM_BACKEND 被 --linear-backend 替代。