[Bugfix] Fix HYV3 shared_mlp prefix for compressed-tensors ignore matching

HYV3MoEFused built its shared expert (shared_mlp) as an HYV3FeedForward
with `prefix=f"{prefix}"`, omitting the `.shared_mlp` segment. The Linear
layers inside it (gate_up_proj, down_proj) register their parameters under
`...mlp.shared_mlp.<proj>.*` (the attribute name is appended by nn.Module
regardless of the prefix argument), but CompressedTensorsConfig ignores
Linears by matching the *prefix* against its `ignore` list. With the
missing segment the ignore check saw `...mlp.down_proj` instead of
`...mlp.shared_mlp.down_proj`, so a `re:.*shared_mlp.*` ignore entry
failed to match.

Consequence: the shared expert was built as a quantized Linear expecting
weight_packed/scale/shape, while real W4A16 hy_v3 checkpoints (produced
by llm-compressor) correctly keep shared_mlp in BF16 as `.weight`. This
raised `KeyError: '...mlp.shared_mlp.down_proj.weight'` at load time.

Fix: pass `prefix=f"{prefix}.shared_mlp"` so the ignore check matches the
real parameter registration path and the shared expert is built
unquantized (UnquantizedLinearMethod), aligning with the BF16 checkpoint.
Parameter registration names are unchanged.

Adds a regression test that builds HYV3MoEFused under a compressed-tensors
config whose ignore list contains `re:.*shared_mlp.*` and asserts the
shared expert Linears are unquantized, plus a sanity check that they are
quantized when shared_mlp is not ignored.

Co-authored-by: xu_xiaoyi@hotmail.com

Author: DCoEngine

tests/quantization/test_compressed_tensors_hy_v3_shared_mlp.py

@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Regression test for HYV3 shared expert (shared_mlp) prefix under
+compressed-tensors quantization.
+
+Background:
+    HYV3MoEFused builds its shared expert as HYV3FeedForward. The Linear layers
+    inside it (gate_up_proj, down_proj) register their parameters under the
+    module tree as ``...mlp.shared_mlp.<proj>.*`` (the ``shared_mlp`` attribute
+    name is appended by nn.Module, independent of the ``prefix`` argument).
+
+    CompressedTensorsConfig decides whether a Linear is quantized via
+    ``get_quant_method(layer, prefix=...)``: it ignores layers whose ``prefix``
+    matches the config's ``ignore`` list. A real W4A16 hy_v3 checkpoint keeps
+    ``shared_mlp`` in BF16 (it is in the ignore list, e.g. ``re:.*shared_mlp.*``).
+
+    Bug: HYV3MoEFused previously passed ``prefix=f"{prefix}"`` (without
+    ``.shared_mlp``) to HYV3FeedForward, so the ignore check saw
+    ``...mlp.down_proj`` and did NOT match ``re:.*shared_mlp.*``. The shared
+    expert was then built as a quantized Linear (expecting
+    weight_packed/scale/shape) while the checkpoint stores BF16 ``.weight``,
+    raising KeyError at load time.
+
+    Fix: pass ``prefix=f"{prefix}.shared_mlp"`` so the ignore check matches and
+    the shared expert is built unquantized.
+
+This test builds a single HYV3MoEFused layer with a compressed-tensors config
+whose ignore list contains ``re:.*shared_mlp.*`` and asserts the shared
+expert's Linear layers are unquantized.
+"""
+
+import pytest
+import torch
+from compressed_tensors.quantization import (
+    QuantizationArgs,
+    QuantizationScheme,
+    QuantizationStrategy,
+    QuantizationType,
+)
+
+from vllm.model_executor.layers.linear import UnquantizedLinearMethod
+from vllm.model_executor.layers.quantization.compressed_tensors import (
+    CompressedTensorsConfig,
+    CompressedTensorsLinearMethod,
+)
+from vllm.model_executor.models.hy_v3 import HYV3MoEFused
+from vllm.transformers_utils.configs.hy_v3 import HYV3Config
+
+
+def _make_hy_v3_config() -> HYV3Config:
+    # Minimal MoE config: tiny dims, a few experts, one shared expert.
+    return HYV3Config(
+        vocab_size=16,
+        hidden_size=8,
+        intermediate_size=16,
+        num_hidden_layers=1,
+        num_attention_heads=2,
+        num_key_value_heads=2,
+        head_dim=4,
+        num_experts=2,
+        num_experts_per_tok=1,
+        num_shared_experts=1,
+        expert_hidden_dim=8,
+        first_k_dense_replace=0,
+        route_norm=True,
+    )
+
+
+def _make_w4a16_ct_config_with_shared_mlp_ignore() -> CompressedTensorsConfig:
+    # W4A16 pack-quantized scheme targeting all Linears, but shared_mlp ignored
+    # (matches real hy_v3 W4A16 checkpoints produced by llm-compressor).
+    scheme = QuantizationScheme(
+        targets=["Linear"],
+        weights=QuantizationArgs(
+            num_bits=4,
+            type=QuantizationType.INT,
+            strategy=QuantizationStrategy.GROUP,
+            group_size=128,
+            symmetric=True,
+            dynamic=False,
+        ),
+    )
+    # Reuse the public from_config path so the ignore list is parsed the same
+    # way as when vLLM loads a real model.
+    config_dict = {
+        "format": "pack-quantized",
+        "quant_method": "compressed-tensors",
+        "ignore": ["re:.*shared_mlp.*"],
+        "config_groups": {
+            "config_group_0": {
+                "targets": ["Linear"],
+                "weights": {
+                    "num_bits": 4,
+                    "type": "int",
+                    "strategy": "group",
+                    "group_size": 128,
+                    "symmetric": True,
+                    "dynamic": False,
+                },
+                "input_activations": None,
+            }
+        },
+    }
+    del scheme  # build from dict to exercise the real parsing path
+    return CompressedTensorsConfig.from_config(config_dict)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Needs CUDA for FusedMoE")
+def test_hy_v3_shared_mlp_ignored_under_compressed_tensors(
+    dist_init, default_vllm_config
+):
+    """shared_mlp Linears must be unquantized when shared_mlp is in the ignore
+    list. Without the prefix fix they would be built as CompressedTensorsLinear
+    Method and fail to load BF16 weights."""
+    hy_config = _make_hy_v3_config()
+    quant_config = _make_w4a16_ct_config_with_shared_mlp_ignore()
+
+    with torch.device("cuda:0"):
+        moe = HYV3MoEFused(
+            config=hy_config,
+            quant_config=quant_config,
+            prefix="model.layers.0.mlp",
+        )
+
+    assert moe.shared_mlp is not None
+
+    # down_proj (RowParallelLinear) must be unquantized (ignored).
+    assert isinstance(
+        moe.shared_mlp.down_proj.quant_method, UnquantizedLinearMethod
+    ), "shared_mlp.down_proj should be ignored (unquantized)"
+
+    # gate_up_proj (MergedColumnParallelLinear) must be unquantized (ignored).
+    assert isinstance(
+        moe.shared_mlp.gate_up_proj.quant_method, UnquantizedLinearMethod
+    ), "shared_mlp.gate_up_proj should be ignored (unquantized)"
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Needs CUDA for FusedMoE")
+def test_hy_v3_shared_mlp_quantized_when_not_ignored(
+    dist_init, default_vllm_config
+):
+    """Sanity check: without the ignore entry, shared_mlp Linears ARE quantized.
+    This confirms the test above is actually exercising the ignore path (and is
+    not passing for some other reason)."""
+    hy_config = _make_hy_v3_config()
+
+    config_dict = _make_w4a16_ct_config_with_shared_mlp_ignore().__dict__
+    # Drop the ignore entry so shared_mlp is no longer ignored.
+    config_dict = {
+        "format": "pack-quantized",
+        "quant_method": "compressed-tensors",
+        "ignore": [],
+        "config_groups": {
+            "config_group_0": {
+                "targets": ["Linear"],
+                "weights": {
+                    "num_bits": 4,
+                    "type": "int",
+                    "strategy": "group",
+                    "group_size": 128,
+                    "symmetric": True,
+                    "dynamic": False,
+                },
+                "input_activations": None,
+            }
+        },
+    }
+    quant_config = CompressedTensorsConfig.from_config(config_dict)
+
+    with torch.device("cuda:0"):
+        moe = HYV3MoEFused(
+            config=hy_config,
+            quant_config=quant_config,
+            prefix="model.layers.0.mlp",
+        )
+
+    assert moe.shared_mlp is not None
+    assert isinstance(
+        moe.shared_mlp.down_proj.quant_method, CompressedTensorsLinearMethod
+    ), "shared_mlp.down_proj should be quantized when NOT ignored"

vllm/model_executor/models/hy_v3.py

@@ -171,7 +171,7 @@ def __init__(
                 intermediate_size=config.expert_hidden_dim * config.num_shared_experts,
                 hidden_act=config.hidden_act,
                 quant_config=quant_config,
-                prefix=f"{prefix}",
+                prefix=f"{prefix}.shared_mlp",
                 reduce_results=False,
             )
         else: