执行摘要

• 一句话：修复 FP8 scale refit bug 并拆分 FP8/MXFP4 权重同步
• 推荐动作：值得精读，特别是 _iter_transferable_param_attrs 对 bound method 的处理和 FP8/MXFP4 两套 in-place staging 机制，对理解 vLLM 量化权重同步与 CUDA graph 交互非常有价值。关注点：verl/utils/vllm/vllm_fp8_utils.py 的 staging/fold 生命周期、vllm_fp4_utils.py 的 DeepGEMM 分支判断，以及删除旧模块后 TP 分片加载逻辑是否完整保留。建议在合并后补充 GPU 上的 refit 集成测试。

功能与动机

PR body 明确了动机：修复 FP8 scale refit 在 rollout 权重同步中的 bug——_copy_param_subclass_attrs 复制了包括 bound methods 在内的所有属性，vLLM 的 loader 入口点是绑定到 tensor 的方法，复制后遮蔽类方法，导致后续 load 静默写入过期 tensor；权重因 in-place 重新量化别名存储而幸存，scale 因 DeepGEMM 打包重新分配而保持全零。同时需要按量化方案拆分代码，让 FP8 与 MXFP4 路径独立演进，并为 MXFP4 MoE 提供正确的 refit 支持。

实现拆解

1. 重构模块结构：新增 verl/utils/vllm/vllm_quant_utils.py 作为统一入口，承载 FP8State、is_fp8_model、is_fp8_weight、模块解析辅助函数（_is_expert_weight_module、_is_fused_moe_block、_resolve_expert_weight_module）以及 stage/process 分发逻辑；vllm_fp8_utils.py 收敛为 Fp8LinearMethod/Fp8MoEMethod 的专属处理；新增 vllm_fp4_utils.py 处理 Mxfp4MoEMethod；删除 vllm_dsv4_fp8_utils.py，其 DeepSeek-V4 特有逻辑（is_deepseek_v4_model、iter_deepseek_v4_weights、MXFP4 布局相关辅助函数）并入 FP4 模块。入口向各后端单向导入，避免循环依赖。
2. 修复参数属性复制 bug：在 vllm_fp8_utils.py 中新增 _iter_transferable_param_attrs，用 inspect.ismethod(value) and isinstance(value.__self__, torch.Tensor) 过滤掉绑定到 tensor 的方法，_copy_param_subclass_attrs 改为只搬运数据属性、weight_loader 等绑定到 layer 的属性以及 subclass_type，让 load_merged_column_weight 等能重新通过类 MRO 解析。
3. 实现 in-place staging/折回机制：_record_pristine_fp8_layout 在模型加载时记录每层 FP8 权重与 scale 的 checkpoint 形状/dtype（只记布局不记 tensor，避免进入 vLLM 的 weights 内存池）；stage_fp8_params_for_loading 在每次 refit 前把 live 参数换成 checkpoint 布局 buffer（存储可复用则 reshape，否则新分配并用 0xFF 毒化）；process_fp8_weights_after_loading 通过 patch replace_parameter 或 _fold_into_live_param 把后处理结果拷回原 storage，保证 CUDA graph 捕获的指针不失效。_FP8_REFIT_PARAM_NAMES 扩展覆盖 MoE 的 w13_weight/w2_weight 及其 scale 参数。
4. 新增 MXFP4 MoE refit 支持：vllm_fp4_utils.py 实现 _mxfp4_checkpoint_layout（与 vLLM create_weights 形状一致的布局表）、_stage_mxfp4_moe_params（expert 权重复用 live 存储、scale 分配零填充临时 buffer）、_replace_parameter_in_place（patch 掉 vLLM 的 replace_parameter，在 process_weights_after_loading 返回前折回 live 参数）、_process_mxfp4_moe_params（检查 _MXFP4_LIVE_ATTR 是否有未被折回的残余参数）。stage_mxfp4_moe_params_for_loading 对非 DeepGEMM 后端直接抛 NotImplementedError，拒绝静默跳过。
5. 配套改动：apply_vllm_fp8_patches 重命名为 apply_vllm_quant_patches 并更新 vllm_rollout/utils.py、vllm_async_server.py 导入；测试文件 test_vllm_fp8_utils_moe_on_cpu.py 重命名为 test_vllm_quant_utils_moe_on_cpu.py 并适配新的模块加载方式（stub 包路径指向真实目录）；verl/utils/megatron/dist_checkpointing.py 改用 Megatron-Core 新的 TorchDistLoadShardedStrategy/TorchDistSaveShardedStrategy 接口；同时 PR 追加 DeepSeek-V4 的 Continuous Token 编码器（verl/utils/tokenizer/deepseek.py）、DeepSeekV4ToolParser（verl/experimental/agent_loop/tool_parser.py）、ContinuousTokenModelFamily.DEEPSEEKV4 注册、示例脚本 run_deepseek_v4_flash_megatron.sh 与文档更新。

关键文件：

• verl/utils/vllm/vllm_quant_utils.py（模块 量化入口；类别 source；类型 entrypoint；符号 _get_vllm_version, FP8State, is_fp8_model, _is_expert_weight_module）: 新增的统一入口文件，承载 FP8State、is_fp8_weight、模块解析与 stage/process 分发，是理解整个重构结构的起点。
• verl/utils/vllm/vllm_fp8_utils.py（模块 权重装载；类别 source；类型 core-logic；符号 _get_vllm_version, _iter_transferable_param_attrs, FP8State, is_fp8_model）: 核心 bug 修复所在文件：_iter_transferable_param_attrs 过滤 bound method，stage_fp8_params_for_loading/process_fp8_weights_after_loading 实现 in-place staging 与折回。
• verl/utils/vllm/vllm_fp4_utils.py（模块 量化加载；类别 source；类型 core-logic；符号 is_deepseek_v4_model, iter_deepseek_v4_weights, _is_mxfp4_fused_moe_module, _is_deepgemm_mxfp4_moe_module）: 新增的 MXFP4 MoE refit 模块，仅支持 DeepGEMM 后端，实现 checkpoint 布局 staging 与 replace_parameter 的 in-place 替换。
• verl/utils/vllm/vllm_dsv4_fp8_utils.py（模块 权重同步；类别 source；类型 deletion；符号 is_deepseek_v4_model, iter_deepseek_v4_weights, _is_mega_moe_module, _is_mxfp4_fused_moe_module）: 整文件删除，其 DeepSeek-V4 特有逻辑被并入 vllm_fp4_utils.py，删除时需确认线性层 TP 分片加载辅助逻辑被完整迁移。
• verl/utils/tokenizer/deepseek.py（模块 编码器；类别 source；类型 core-logic；符号 _to_json, _text_of, render_tools, _render_tool_call）: 新增 DeepSeek-V4 的 DSML 提示编码器与 Continuous Token Builder，是 DeepSeek-V4 集成的一部分，与量化修复同 PR 合入。
• verl/experimental/agent_loop/tool_parser.py（模块 工具解析；类别 source；类型 core-logic；符号 DeepSeekV4ToolParser, init, _parse_tool_calls, extract_tool_calls）: 新增 DeepSeekV4ToolParser，解析 DSML 格式的工具调用，与 deepseek.py 编码器配对。
• verl/utils/tokenizer/continuous_token_wiring.py（模块 模型识别；类别 source；类型 core-logic；符号 ContinuousTokenModelFamily）: 注册 DeepSeekV4ContinuousTokenBuilder 并新增 ContinuousTokenModelFamily.DEEPSEEKV4 枚举值，同时将 StrEnum 改为兼容 Python 3.10 的 str+Enum 实现。
• tests/utils/test_vllm_quant_utils_moe_on_cpu.py（模块 测试；类别 test；类型 test-coverage；符号 _load_fp8_utils, _load_quant_utils）: 由 test_vllm_fp8_utils_moe_on_cpu.py 重命名而来，适配新模块结构和 stub 加载方式，是量化工具的主要 CPU 测试。
• verl/utils/megatron/dist_checkpointing.py（模块 检查点；类别 source；类型 dependency-wiring）: 适配 Megatron-Core 新 API，将 get_default_save/load_sharded_strategy 替换为 TorchDistSave/LoadShardedStrategy 直接实例化，可能影响 Megatron 后端 checkpoint 行为。
• examples/grpo_trainer/run_deepseek_v4_flash_megatron.sh（模块 示例脚本；类别 other；类型 configuration）: DeepSeek-V4 示例脚本调整，配合新量化模块与工具链的运行参数。

关键符号：_iter_transferable_param_attrs, _copy_param_subclass_attrs, _fold_into_live_param, _fp8_staging_data, stage_fp8_params_for_loading, process_fp8_weights_after_loading, stage_mxfp4_moe_params_for_loading, process_mxfp4_moe_weights_after_loading, _stage_mxfp4_moe_params, _replace_parameter_in_place, apply_vllm_quant_patches, is_fp8_weight, encode_messages, DeepSeekV4ToolParser, DeepSeekV4ContinuousTokenBuilder

关键源码片段

verl/utils/vllm/vllm_fp8_utils.py

核心 bug 修复所在文件：_iter_transferable_param_attrs 过滤 bound method，stage_fp8_params_for_loading/process_fp8_weights_after_loading 实现 in-place staging 与折回。

# verl/utils/vllm/vllm_fp8_utils.py（节选：参数属性复制过滤 + 折回 live 参数）
​
def _iter_transferable_param_attrs(src_param):
    """只搬运值得迁移的参数属性，排除绑定到 tensor 的方法。
​
    这是本 PR 修复的核心：``dir()`` 会把 vLLM 的 loader 入口点
    （``load_merged_column_weight`` 等）也列出来，而它们都是绑定到
    某个 tensor 的方法。如果原样 setattr 到重建后的参数上，就会把
    ``self`` 指向其他 tensor 的方法写进目标实例 dict，遮蔽类方法，
    后续所有加载都会静默写入那个过期 tensor（shape 一致所以不报错）。
    """
    base_param_attrs = dir(torch.nn.Parameter)
    for attr in dir(src_param):
        if attr in base_param_attrs or attr.startswith("__"):
            continue
        try:
            value = getattr(src_param, attr)
        except AttributeError:
            continue
        # 只要 value 是绑定到 tensor 的方法就跳过；注意判断的是
        # " 绑定到 tensor" 而不是 " 绑定到源参数 "，因为方法会随重建被
        # 反复复制，等它造成破坏时 self 可能已是若干次重建前的临时对象。
        if inspect.ismethod(value) and isinstance(value.__self__, torch.Tensor):
            continue
        yield attr, value
​
​
def _copy_param_subclass_attrs(dst_param, src_param):
    """把 vLLM 参数子类的元数据（output_dim、weight_loader、
    tp 状态等）带到重建后的参数上，否则下一次 refit 不知道如何分片。
    """
    if src_param is None:
        return
    for attr, value in _iter_transferable_param_attrs(src_param):
        try:
            setattr(dst_param, attr, value)
        except AttributeError:
            pass
    subclass_type = getattr(src_param, "subclass_type", type(src_param))
    if subclass_type is not torch.nn.Parameter:
        dst_param.subclass_type = subclass_type
​
​
def _fold_into_live_param(layer, param_name, param, new_data):
    """把后处理产物写回 CUDA graph 已捕获的原始存储。
​
    替换参数对象会让 CUDA graph 持有的指针失效，所以这里只允许
    在 shape 与 dtype 完全一致时原地 copy 回 live 参数，
    不一致则直接抛错，避免静默产生错误布局。
    """
    if isinstance(new_data, torch.nn.Parameter):
        new_data = new_data.data
    if new_data.shape != param.shape or new_data.dtype != param.dtype:
        raise RuntimeError(
            f"FP8 refit 重新推导的 {param_name} 形状/类型 "
            f"({tuple(new_data.shape)}/{new_data.dtype}) 与 live 参数 "
            f"({tuple(param.shape)}/{param.dtype}) 不一致，无法原地更新。"
        )
    if new_data.data_ptr() != param.data_ptr():
        param.data.copy_(new_data)
    setattr(layer, param_name, param)

verl/utils/vllm/vllm_fp4_utils.py

新增的 MXFP4 MoE refit 模块，仅支持 DeepGEMM 后端，实现 checkpoint 布局 staging 与 replace_parameter 的 in-place 替换。

# verl/utils/vllm/vllm_fp4_utils.py（节选：MXFP4 MoE 的 checkpoint 布局 staging 与原地折回）
​
_MXFP4_SF_BLOCK = 32 # MXFP4 的 block scale 因子
_MXFP4_LIVE_ATTR = "_verl_mxfp4_live_params" # 暂存 live 参数的模块属性名
​
​
def _mxfp4_checkpoint_layout(module):
    """回推 checkpoint 布局下的专家参数形状与 dtype。
​
    这些形状不是猜测：vLLM 在 ``_setup_kernel`` 开头会重新断言相同形状，
    所以 refit 交出任何其他形状都会在那里立刻失败。第三个元素是
    ``quant_method`` 标签，``RoutedExperts.weight_loader`` 会按它分发，
    ``replace_parameter`` 不会保留它，需要在此重新挂上。
    """
    qm = module.quant_method
    num_experts, inter, hidden = qm.num_experts, qm.intermediate_size, qm.hidden_size
    return {
        "w13_weight": ((num_experts, 2 * inter, hidden // 2), torch.uint8, None),
        "w2_weight": ((num_experts, hidden, inter // 2), torch.uint8, None),
        "w13_weight_scale": ((num_experts, 2 * inter, hidden // _MXFP4_SF_BLOCK), torch.uint8, "block"),
        "w2_weight_scale": ((num_experts, hidden, inter // _MXFP4_SF_BLOCK), torch.uint8, "block"),
    }
​
​
def _stage_mxfp4_moe_params(module):
    """在不搬动 live 存储的前提下，向 ``load_weights`` 暴露 checkpoint 布局。
​
    DeepGEMM 后端不会重排专家权重，所以 live 参数可以直接吸收 checkpoint
    数据，只需要把 ``weight_loader`` 等属性装回去；而 block scale 已被
    重排为 DeepGEMM 布局，因此要分配临时 buffer 承接加载结果，
    之后由 ``_process_mxfp4_moe_params`` 折回 live 存储。
    """
    live = {}
    for name, (shape, dtype, scale_kind) in _mxfp4_checkpoint_layout(module).items():
        param = getattr(module, name, None)
        if not isinstance(param, torch.nn.Parameter):
            continue
        live[name] = param
        if param.shape == torch.Size(shape) and param.dtype == dtype:
            data = param.data
        else:
            # 这里用零而不是空 buffer：如果 refit 流恰好跳过某个 scale，
            # 零会让该层输出直接崩溃，而不是读到被释放内存里的残留值。
            data = torch.zeros(shape, dtype=dtype, device=param.device)
        staged = torch.nn.Parameter(data, requires_grad=False)
        staged.weight_loader = module.weight_loader
        if scale_kind is not None:
            staged.quant_method = scale_kind
        setattr(module, name, staged)
    setattr(module, _MXFP4_LIVE_ATTR, live)
​
​
def _replace_parameter_in_place(layer, param_name, new_data, prefer_copy=False):
    """把后处理输出折回 CUDA graph 已捕获的 live 参数。
​
    必须在 ``process_weights_after_loading`` 返回前完成：其尾部会用当前
    layer 上的参数重建 ``moe_quant_config`` 与 ``moe_kernel`` 并缓存 tensor
    引用，若之后再换回 live 参数，kernel 会仍然指向临时 buffer。
    """
    from vllm.model_executor.utils import replace_parameter
    live = getattr(layer, _MXFP4_LIVE_ATTR, None) or {}
    param = live.pop(param_name, None)
    if param is None or new_data is None:
        return replace_parameter(layer, param_name, new_data, prefer_copy)
    if isinstance(new_data, torch.nn.Parameter):
        new_data = new_data.data
    if new_data.shape != param.shape or new_data.dtype != param.dtype:
        raise RuntimeError(
            f"mxfp4 refit 重新推导 {param_name} 为 "
            f"{tuple(new_data.shape)}/{new_data.dtype}，但 live 参数是 "
            f"{tuple(param.shape)}/{param.dtype}，无法原地更新。"
        )
    if new_data.data_ptr() != param.data_ptr():
        param.data.copy_(new_data)
    setattr(layer, param_name, param)

评论区精华

本 PR 没有公开的 review 评论（review_comments_count = 0），核心设计权衡由作者在 PR body 中阐述：

• 为什么必须 in-place staging 而不是替换参数对象：替换参数对象会使捕获的 CUDA graph 持有的指针失效；且 Fp8MoEMethod._setup_kernel 尾部会从当前 layer 状态重建 moe_quant_config/moe_kernel 并缓存 tensor 引用，所以必须在 process_weights_after_loading 返回前把 live 参数折回，否则 kernel 会指向临时 buffer。
• staging buffer 毒化策略分 scheme 不同：FP8 路径用 0xFF（在所有 staged dtype 中都是 NaN）毒化，未写到的 buffer 会在首次 forward 中爆炸；MXFP4 路径的 scale 若被跳过会导致层输出崩溃，因此对临时 scale buffer 用零填充，并在后处理末尾检查 _MXFP4_LIVE_ATTR 是否有残余。
• 非 DeepGEMM MXFP4 后端抛 NotImplementedError 而非静默跳过：其他后端在后处理时会重排 expert 权重，refit 会把 checkpoint 布局数据静默加载进已重写布局的参数，导致 rollout 权重漂移；failing loudly 优于产出 stale weights。

• _iter_transferable_param_attrs 判断的是“绑定到 tensor”而非“绑定到源参数”：loader 方法会随参数重建被反复复制，等它造成破坏时 self 通常已是若干次重建前的临时对象，因此不能简单与源比较。

  • 为什么必须 in-place staging 而不是替换参数对象 (design): 采用 staging buffer + _fold_into_live_param/_replace_parameter_in_place 在过程中立即折回，避免 CUDA graph 指向临时 buffer。
  • staging buffer 毒化策略：0xFF vs 零填充 (design): 两种量化方案采用不同的毒化策略，均以快速暴露错误为目标。
  • 非 DeepGEMM MXFP4 后端为何抛 NotImplementedError (design): 非 DeepGEMM 后端直接抛 NotImplementedError，并在错误信息中提示使用 --moe-backend deep_gemm。

风险与影响

• 风险：
  1. 核心路径变更风险：vLLM rollout 权重同步是 RL 训练的关键路径，本 PR 修改了 FP8/FP4 量化模型的加载与后处理流程，任何边缘情况（如某层未通过 replace_parameter 折回）都可能导致训练静默产出错误权重。
  2. 删除 352 行旧模块的迁移完整性：vllm_dsv4_fp8_utils.py 整文件删除，其中包含线性层 TP 分片加载辅助逻辑（_try_load_column_weight、_try_load_merged_weight、_attach_weight_loaders 等），这些逻辑是否被完整迁移到新模块需要进一步确认；目前 CPU 测试只覆盖模块解析与 is_fp8_weight 判定，未覆盖实际 TP 分片加载路径。
  3. vLLM 版本兼容分支：vllm_quant_utils.py 对 FusedMoE 是类还是函数做了版本分支（vLLM 0.24.0 前后），并在导入时动态解析 RoutedExperts/MoERunner，但若 vLLM 后续继续重构 MoE 结构，这些 duck typing 分支可能失效。
  4. MXFP4 局限：仅 DeepGEMM 后端支持 refit，其他后端直接抛错，用户如果不小心用默认后端启动 DeepSeek-V4 训练会直接失败，虽然是有意的 fail-loud 设计，但可能影响未预期用户。
  5. 内部 API 重命名：apply_vllm_quant_patches 替换 apply_vllm_fp8_patches，若下游或第三方脚本仍引用旧名会报 ImportError。
     - 影响：对用户：修复了 DeepSeek-V4-Flash 等 FP8/FP4 量化模型在 RL rollout 中 refit 后 scale 全零的静默错误，保证训练正确性；MXFP4 用户需显式使用 --moe-backend deep_gemm 才能启用 refit。对系统：vLLM rollout 权重同步模块从单一文件拆分为按量化方案组织的多文件结构，降低后续维护复杂度，并为 MXFP4 提供了独立的扩展入口。对团队：PR 同时引入了 DeepSeek-V4 的 Continuous Token 编码器与工具解析器，扩展了 agent loop 和 tokenizer 的模型家族支持，但与量化修复打包在同一 PR 中增加了 review 和回溯复杂度。
     - 风险标记：核心路径变更, 删除 352 行旧模块需验证迁移完整性, 缺少 GPU 单测覆盖, vLLM 版本兼容分支, 内部 API 重命名

关联脉络

• PR #7101 [docker] feat: upgrade vllm and megatron version, add packages to support DeepSeek-V4: 升级 vLLM 至 0.24.0 支持 DeepSeek-V4，本 PR 中的 FusedMoE 版本分支（v0.24 MoE 重构）正是在该版本基础上适配。
• PR #7179 [vllm] refactor: clean up weight sync: 对 vLLM 权重同步逻辑的重构与本 PR 的量化权重同步改动处于同一模块（verl/utils/vllm），存在重叠演进。
• PR #7190 [vllm] refactor: drop support for vLLM older than 0.18.0: 提升 vLLM 最低版本，与本 PR 的 vLLM 版本兼容分支策略相关。
• PR #7221 [megatron] feat: support contiguous context-parallel layout for DeepSeek V4: 同为 DeepSeek V4 支持线，Megatron 侧的 CP 布局支持与本 PR 的 vLLM 量化 refit 配合完成 DSV4 全链路。