在vllm上运行的bug以及解决方法

[isolitude]

Describe the bug
使用vllm启动openbmb/MiniCPM-V-4.6，会报错

(EngineCore pid=139) ERROR 05-19 10:10:22 [core.py:1159] ValueError: There is no module or parameter named 'vit_merger.self_attn.k_proj' in MiniCPMV4_6ForConditionalGeneration. The available parameters belonging to vit_merger.self_attn (MiniCPMV4_6ViTWindowAttentionSelfAttn) are: {'vit_merger.self_attn.qkv_proj.bias', 'vit_merger.self_attn.out_proj.bias', 'vit_merger.self_attn.out_proj.weight', 'vit_merger.self_attn.qkv_proj.weight'}

vllm版本

(APIServer pid=19) INFO 05-19 10:09:30 [utils.py:306]
(APIServer pid=19) INFO 05-19 10:09:30 [utils.py:306]        █     █     █▄   ▄█
(APIServer pid=19) INFO 05-19 10:09:30 [utils.py:306]  ▄▄ ▄█ █     █     █ ▀▄▀ █  version 0.20.2rc1.dev418+g0fa888465.d20260519
(APIServer pid=19) INFO 05-19 10:09:30 [utils.py:306]   █▄█▀ █     █     █     █  model   openbmb/MiniCPM-V-4.6
(APIServer pid=19) INFO 05-19 10:09:30 [utils.py:306]    ▀▀  ▀▀▀▀▀ ▀▀▀▀▀ ▀     ▀
(APIServer pid=19) INFO 05-19 10:09:30 [utils.py:306]

To Reproduce
由于我是用的是Nvidia DGX spark，使用spark-vllm-docker，具体操作如下

• 从vllm官方的main分支编译vllm whl和docker image

./build-and-copy.sh  --tf5 --rebuild-vllm

• 使用recipe启动

  vllm serve openbmb/MiniCPM-V-4.6 \
  --gpu-memory-utilization {gpu_memory_utilization} \
  --max-model-len {max_model_len} \
  --host {host} \
  --port {port} \
  --api-key {api_key} \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --default-chat-template-kwargs '{{"enable_thinking": true}}'

Desktop (please complete the following information):

• OS: Ubuntu 22.04

修复方案
claude给的修复方案，修改/usr/local/lib/python3.12/dist-packages/vllm/model_executor/models/minicpmv4_6.py

1. 新增 import（第60行）

from vllm.model_executor.model_loader.weight_utils import default_weight_loader

2. 新增 load_weights 方法（第593-614行）

这是核心修复。问题在于 MiniCPM-V 4.6 的 checkpoint 里权重是分开存储的（q_proj, k_proj, v_proj），但 vllm 的模型定义用的是融合的 qkv_proj。原始代码没有处理这个映射，导致权重加载失败或错误。

这个 load_weights 方法做的事：遍历 checkpoint 里的所有权重。遇到 q_proj.* / k_proj.* / v_proj.* 时，把它们打包进对应的 qkv_proj.* shard（用 "q" / "k" / "v" 标识）其他权重（out_proj, attn.* 等）直接按名字加载

    def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
        # Checkpoint stores split q/k/v_proj; pack them into fused qkv_proj.
        qkv_shard_id = {"q_proj": "q", "k_proj": "k", "v_proj": "v"}
        params = dict(self.named_parameters(recurse=True))
        loaded: set[str] = set()
        for name, tensor in weights:
            top = name.split(".")[0]
            if top in qkv_shard_id:
                # e.g. "q_proj.weight" -> qkv_proj.weight shard "q"
                suffix = name[len(top) + 1:]  # "weight" or "bias"
                param = params[f"qkv_proj.{suffix}"]
                weight_loader = getattr(param, "weight_loader", default_weight_loader)
                weight_loader(param, tensor, qkv_shard_id[top])
            else:
                # out_proj.weight, out_proj.bias, attn.*
                if name in params:
                    param = params[name]
                    weight_loader = getattr(param, "weight_loader", default_weight_loader)
                    weight_loader(param, tensor)
            loaded.add(name)
        return loaded

修复后的minicpmv4_6.py
minicpmv4_6.py

[tc-mb]

你好，非常感谢详细的问题定位和修复方案！这个权重映射问题我们核对一下，会尽快在 vllm 上提一个修复 PR。修复合并后会在这里同步。再次感谢社区贡献！