执行摘要

• 一句话：修复 vLLM LoRA 堆叠 QKV 索引错位，改用 unstacked mapper
• 推荐动作：值得快速精读，重点学习 HollowMan6 提出的最小化 diff 思路：面对上游行为漂移时优先做局部版本分支，而不是复制整段逻辑。建议后续补充一个覆盖 vLLM 0.25/0.26 的 LoRA 权重映射单测，防止这一版本敏感逻辑再次回归。

功能与动机

PR body 明确指出：Fix vLLM LoRA index resolution for stacked QKV projections by mapping tensors through the unstacked weight mapper and preserving 3D LoRA metadata. This prevents incorrect tensor selection during adapter loading and ensures weights are resumed before vLLM LoRA synchronization (caused by vLLM behavior drift with update to 0.26). 即这是 vLLM 0.26 行为漂移带来的兼容性修复，需要随 vLLM 版本升级一起合入。

实现拆解

1. 定位问题所在：在 verl/utils/vllm/utils.py 的 hijack__load_adapter 函数中，原有逻辑直接使用 model.hf_to_vllm_mapper 作为 weights_mapper，没有考虑 vLLM 0.26 对堆叠 QKV 投影权重索引解析方式的变化。
2. 引入版本分支：通过 is_version_ge(minver="0.25.0") 判断 vLLM 版本，并在 hf_to_vllm_mapper 非空时调用 get_unstacked_mapper()，得到 unstacked 映射器，使权重名映射与 3D LoRA 元数据对齐。
3. 传入下游逻辑：转换后的 mapper 继续放入 lora_request_kwargs["weights_mapper"]，vLLM 在加载 LoRA 时按该 mapper 将 HF 权重名路由到正确的张量索引。
4. 配套变更：本 PR 没有新增测试、配置或文档，最终改动仅 2 行，避免了早期版本中复制整个 vLLM 0.26 分支的逻辑膨胀。

关键文件：

• verl/utils/vllm/utils.py（模块 权重映射；类别 source；类型 core-logic；符号 hijack__load_adapter, get_unstacked_mapper, is_version_ge）: 修复核心文件：在 hijack__load_adapter 中调整 hf_to_vllm_mapper，针对 vLLM>=0.25 使用 unstacked mapper，解决堆叠 QKV 投影的 LoRA 索引错位。

关键符号：hijack__load_adapter, get_unstacked_mapper, is_version_ge

关键源码片段

verl/utils/vllm/utils.py

修复核心文件：在 hijack__load_adapter 中调整 hf_to_vllm_mapper，针对 vLLM>=0.25 使用 unstacked mapper，解决堆叠 QKV 投影的 LoRA 索引错位。

关键源码片段

# 位于 verl/utils/vllm/utils.py 的 hijack__load_adapter 核心段。
# 目标：让 vLLM 在加载 LoRA 权重时，用 unstacked mapper 正确解析堆叠 QKV 的索引。
model = self._adapter_manager.model
hf_to_vllm_mapper = None
​
if hasattr(model, "hf_to_vllm_mapper") and model.hf_to_vllm_mapper is not None:
    hf_to_vllm_mapper = model.hf_to_vllm_mapper
    # vLLM 0.25 起行为发生漂移：堆叠 QKV 投影的 LoRA 元数据按 3D 形状保存，
    # 但 weights_mapper 需要 unstacked 名称才能对齐张量索引。
    # 这里统一做一次转换，避免加载适配器时选错张量。
    if is_version_ge(minver="0.25.0"):
        hf_to_vllm_mapper = hf_to_vllm_mapper.get_unstacked_mapper()
​
# 转换后的 mapper 作为 weights_mapper 传入，vLLM 才能把 HF 权重名路由到正确位置。
lora_request_kwargs = {
    "peft_helper": peft_helper,
    "lora_model_id": lora_request.lora_int_id,
    "device": "cpu",
    "dtype": self.lora_config.lora_dtype,
    "weights_mapper": hf_to_vllm_mapper,
}

评论区精华

审查中 HollowMan6 指出：不需要为 vLLM 0.26 复制整个分支，核心就是 hf_to_vllm_mapper.get_unstacked_mapper()，其他参数可以统一用 hasattr 检查；作者回复 good catch, changed! 后，改动被精简为 2 行。另外 Luosuu 质疑 .pre-commit-config.yaml 的无关修改，作者回复 removed 并删除，保证 PR 只包含核心修复。

• 避免复制 vLLM 0.26 分支 (design): 作者采纳建议，最终改动精简为 2 行条件分支。
• 去除无关的 pre-commit 修改 (style): 无关修改被移除，PR 仅保留核心修复。

风险与影响

• 风险：
  1. 版本条件分支风险：is_version_ge(minver="0.25.0") 对 0.25 及以上版本全部生效，但 unstacked mapper 的语义在多个 vLLM 版本间可能存在细微差异，后续 vLLM 再次调整 mapper 生成方式时仍可能复发。
  2. 缺少测试覆盖：PR 没有增加单测或 e2e 测试，CI 无法覆盖 vLLM 0.26 + LoRA + 堆叠 QKV 的组合场景，回归不易被及时发现。
  3. 依赖配套修复：PR body 提到权重同步前需要先 resume，该能力依赖历史 PR #7434；如果只单独合入本修复而缺少权重复原逻辑，LoRA 同步仍可能异常。
     - 影响：影响范围集中在使用 vLLM>=0.25 的 LoRA 训练/推理场景，尤其是 Qwen2VL 等多模态模型中带堆叠 QKV 投影的权重同步路径。修复后适配器加载能正确选择张量，为 vLLM 0.26 升级扫清障碍；对系统整体影响较小，但涉及 rollout worker 的权重广播完整性，建议与 #7434 一同纳入版本说明。
     - 风险标记：缺少测试覆盖, 版本条件分支, 依赖 vLLM 行为漂移

关联脉络

• PR #7434 [vllm] fix: vllm always need to resume weights before weight sync: 同一 vLLM LoRA 同步路径上的配套修复，PR body 明确提到权重需要先 resume 再同步，依赖该 PR 的权重复原逻辑。
• PR #7376 [megatron] fix: per-name, mapper-aware .base_layer strip in resolve_weight_name: 同样修改了 verl/utils/vllm/utils.py 的权重名映射逻辑，解决 LoRA 权重名解析问题，与本 PR 的 mapper 调整存在直接关联。
• PR #7413 [sglang] fix: lora sglang e2e: 同一 LoRA 同步功能线，修复了 LoRA 同步链路上的多个缺陷，印证 LoRA 同步是当前 rollout 侧的持续热点。