执行摘要

• 一句话：支持 2D 与 3D MoE LoRA 适配器混布
• 推荐动作：该 PR 值得所有 LoRA MoE 相关开发者精读，尤其关注：
  1) 设计方案：_enable_mixed_moe_lora_format 与 _model_is_3d_moe 的双重状态设计，以及 _convert_3d_to_2d_moe_lora 的具体张量重排实现；
  2) 测试策略：混合 batch 中通过独立输出比对验证适配器路由正确性；
  3) 未解决的 review 意见：assert 与 architectures 访问的改进建议尚未实施，后续需跟进以避免潜在 crash。

功能与动机

来自 Issue #40005 的用户反馈指出，基于 Megatron-Swift 微调的 Qwen3.5-MoE LoRA 权重（采用 3D 格式：gate_up_proj / down_proj 两个融合张量）无法被 vLLM 加载，而 Qwen3-MoE 与 Qwen3-Dense 均可正常工作。该 PR 旨在填补这一兼容性缺口，在不破坏既有 2D LoRA 支持的前提下，允许两种格式在相同 engine 中共存。

实现拆解

1. 配置扩展：在 LoRAConfig 与 EngineArgs 中新增 enable_mixed_moe_lora_format 布尔字段，用户可通过 CLI --enable-mixed-moe-lora-format 启用混合模式。
2. 数据契约扩展：在 LoRARequest 与 LoRAModel 中新增 is_3d_lora_weight 标志，将从 REST API 透传至模型管理器，以识别待加载适配器的格式。
3. 初始化分支：ModelManager.__init__ 根据模型是否为 MoE 以及配置决定 _enable_mixed_moe_lora_format 与 _is_3d_moe_model。当混合模式启用时，即使模型原生支持 3D，也强制使用 FusedMoEWithLoRA 2D 包装器，并通过 force_2d_moe=True 调用 process_packed_modules_mapping 获取 2D 模块映射。
4. 权重转换：新增 _convert_3d_to_2d_moe_lora 方法，解析 3D 格式的 gate_up_proj 与 down_proj 的张量切片，重排为 2D 格式所需的 w1/w2/w3 分离张量。该方法在 _create_merged_loras_inplace 中对于 FusedMoEWithLoRA 且 lora_model.is_3d_lora_weight=True 时被调用。
5. 入口透传：在 OpenAIServing 的静态 LoRA 初始化与动态加载方法中，传递 is_3d_lora_weight 到后端。
6. 测试覆盖：新增 test_qwen36_moe_lora.py，使用 Qwen3.6-35B-A3B 模型做 2D/3D 混合 batch 测试，验证单独推理与混合推理输出一致，并交换顺序验证路由正确。在 conftest.py 中注册 fixture 提供权重路径。现有 test_qwen3moe_tp.py 也更新以使用新配置。

关键文件：

• vllm/lora/model_manager.py（模块 LoRA 管理器；类别 source；类型 core-logic；符号 _convert_3d_to_2d_moe_lora）: 核心变更：添加 _convert_3d_to_2d_moe_lora 转换方法，修改初始化逻辑以支持混合模式，是重量级改动。
• tests/lora/test_qwen36_moe_lora.py（模块 集成测试；类别 test；类型 test-coverage；符号 _build_prompts, _generate, _run_mixed_2d_3d_lora_test, test_qwen36_moe_mixed_2d_3d_lora_tp2）: 新增的测试文件，覆盖 2D/3D 混合 batch 的核心场景，验证路由与正确性。
• vllm/lora/utils.py（模块 工具函数；类别 source；类型 core-logic；符号 process_packed_modules_mapping）: 修改 process_packed_modules_mapping，新增 force_2d_moe 参数，使 3D 模型也可生成 2D 映射。
• vllm/lora/lora_model.py（模块 LoRA 模型；类别 source；类型 data-contract）: LoRAModel 添加 is_3d_lora_weight 属性，标识适配器格式。
• vllm/lora/request.py（模块 请求层；类别 source；类型 data-contract）: LoRARequest 添加 is_3d_lora_weight 字段，用于从入口传递标志。
• vllm/config/lora.py（模块 配置层；类别 config；类型 configuration）: LoRAConfig 添加 enable_mixed_moe_lora_format 配置项。
• vllm/engine/arg_utils.py（模块 引擎参数；类别 config；类型 configuration）: EngineArgs 注册 CLI 参数并传递至配置，是用户可见的入口。
• vllm/entrypoints/openai/models/serving.py（模块 服务层；类别 source；类型 data-contract）: 在静态 LoRA 初始化与动态加载方法中传递 is_3d_lora_weight。
• tests/lora/conftest.py（模块 测试配置；类别 test；类型 test-coverage；符号 qwen36_moe_2d_lora_files, qwen36_moe_3d_lora_files）: 注册测试 fixture 提供 2D/3D LoRA 权重路径，支撑集成测试。
• tests/lora/test_qwen3moe_tp.py（模块 TP 测试；类别 test；类型 test-coverage；符号 test_qwen3moe_lora_tp2, test_qwen3moe_lora_tp4）: 更新现有 TP 测试以使用新配置（enable_mixed_moe_lora_format=False）保持向后兼容。

关键符号：_convert_3d_to_2d_moe_lora, process_packed_modules_mapping

关键源码片段

vllm/lora/model_manager.py

核心变更：添加 _convert_3d_to_2d_moe_lora 转换方法，修改初始化逻辑以支持混合模式，是重量级改动。

def __init__(self, ...):
    # ... 省略前置代码 ...
    is_moe = is_moe_model(self.model)
    # 记录模型原生的 3D 权重标志
    self._model_is_3d_moe = is_moe and self.model.is_3d_moe_weight
    # 决定是否启用混合模式：强制使用 2D 包装器
    self._enable_mixed_moe_lora_format = (
        is_moe and lora_config.enable_mixed_moe_lora_format
    )
    # 最终决定是否将 model 视为 3D ( 当混合模式关闭时才视为 3D)
    self._is_3d_moe_model = (
        self._model_is_3d_moe and not self._enable_mixed_moe_lora_format
    )
    # 在混合模式下强制生成 2D 映射
    self.packed_modules_mapping = process_packed_modules_mapping(
        self.model, force_2d_moe=self._enable_mixed_moe_lora_format
    )
    # ... 后续代码 ...
​
def _convert_3d_to_2d_moe_lora(self, lora_model, module, module_name):
    """将 3D 格式的 MoE LoRA 适配器转换为 2D 布局。
    3D 格式存储两个融合张量对 (gate_up_proj / down_proj)，
    需要拆解并重排为 2D 所需的 w1/w2/w3 分离张量。
    """
    # 从 lora_model.loras 中提取 gate_up_proj 与 down_proj
    # ... 具体张量操作 ...
    # 注意：中间维度检查使用了 assert，建议改为 ValueError（见 Review）
    assert intermediate_x2 % 2 == 0, "gate_up_proj LoRA-B 维度应为 2*intermediate"
    # 安全访问模型架构名（存在 IndexError 风险，见 Review）
    base_arch = self.model.config.architectures[0]
    # ... 重塑与拆分逻辑 ...

tests/lora/test_qwen36_moe_lora.py

新增的测试文件，覆盖 2D/3D 混合 batch 的核心场景，验证路由与正确性。

def _run_mixed_2d_3d_lora_test(
    lora_2d_files: str,
    lora_3d_files: str,
    tensor_parallel_size: int,
    fully_sharded_loras: bool,
) -> None:
    llm = vllm.LLM(
        model=MODEL_PATH,
        max_model_len=4096,
        enable_lora=True,
        enable_mixed_moe_lora_format=True, # 启用混合模式
        max_loras=2,
        max_lora_rank=8,
        max_num_seqs=4,
        enforce_eager=True,
        tensor_parallel_size=tensor_parallel_size,
        enable_expert_parallel=not fully_sharded_loras,
        fully_sharded_loras=fully_sharded_loras,
        trust_remote_code=True,
        enable_tower_connector_lora=True,
        mm_processor_cache_gb=0,
        limit_mm_per_prompt={"image": 1},
    )
​
    lora_2d = LoRARequest("lora_2d", 1, lora_2d_files, is_3d_lora_weight=False)
    lora_3d = LoRARequest("lora_3d", 2, lora_3d_files, is_3d_lora_weight=True)
​
    # 基线：单独使用单个适配器对两个 prompt 生成
    outputs_2d_alone = _generate(llm, lora_2d)
    outputs_3d_alone = _generate(llm, lora_3d)
​
    # 混合 batch：prompt 0 -> lora_2d, prompt 1 -> lora_3d
    mixed_outputs = _generate(llm, [lora_2d, lora_3d])
    assert mixed_outputs[0] == outputs_2d_alone[0]
    assert mixed_outputs[1] == outputs_3d_alone[1]
​
    # 顺序交换验证路由无误
    swapped_outputs = _generate(llm, [lora_3d, lora_2d])
    assert swapped_outputs[0] == outputs_3d_alone[0]
    assert swapped_outputs[1] == outputs_2d_alone[1]

评论区精华

在 Review 中，gemini-code-assist[bot] 提出两点改进建议：

1) 将 _convert_3d_to_2d_moe_lora 中的 assert intermediate_x2 % 2 == 0 改为 raise ValueError(...)，以避免在生产环境中因断言失败导致引擎崩溃；
2) 直接访问 self.model.config.architectures[0] 可能因模型配置异常引发 IndexError，建议通过 getattr(config, 'architectures', [None])[0] 安全访问。
维护者 ywang96 询问了 _is_3d_moe_model 属性的用途，作者 jeejeelee 解释该属性用于 GPT-Oss 等始终为 3D MoE 的模型初始化对应的 LoRA 层。这些讨论已记录并合入，但前两处改进尚未在最终版本中应用（需关注后续修复）。

• assert 应替换为 ValueError (correctness): 已被记录，但尚未应用修改。
• architectures[0] 可能 IndexError (correctness): 已被记录，但尚未应用修改。
• _is_3d_moe_model 属性用途 (question): 作者 jeejeelee 解释用于 GPT-Oss 等始终为 3D MoE 的模型初始化 LoRA 层。

风险与影响

• 风险：
  1) 断言风险：_convert_3d_to_2d_moe_lora 中使用 assert 检查中间维度，在 python -O 模式下会被跳过，导致静默错误；
  2) 兼容性风险：当 enable_mixed_moe_lora_format=True 时，所有 3D 模型（包括原本不需要转换的模型，如 GPT-Oss）也将强制走 2D 包装路径，需要保证所有 3D 原生模型的权重加载路径无误；
  3) 性能影响：3D→2D 转换发生在适配器加载时，对推理延迟无影响，但会增加加载时间与额外内存拷贝。
  • 影响：用户端：Qwen3.5-MoE 用户可直接加载 3D LoRA 权重，无需手动转换；系统端：新增配置与数据标志，扩展 LoRA 接口契约；测试侧：新增多 GPU 混合 batch 测试，覆盖 TP=2/4 场景；维护侧：model_manager.py 的初始化逻辑与 _create_merged_loras_inplace 分支复杂度增加，需维护状态一致性。
  • 风险标记：核心路径变更, 断言取代, 配置新增, 兼容性影响

关联脉络

• PR #42757 [LoRA][Bugfix] Dedup LoRA wrapping for modules referenced from multiple attribute paths (MoE gate): 同样涉及 vllm/lora/model_manager.py，与 MoE LoRA 加载相关的 Bugfix，反映该模块的持续演进。