Skip to content

PTQ-Level Efficiency, QAT-Level Accuracy | 训练后量化的效率,量化感知训练的精度

16.5 KB
Raw Blame
# Copyright (c) 2026 Intel Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Unit tests for Qwen2.5-Omni and Qwen3-Omni-MoE model support.

Tests cover:
- Block name discovery (thinker + talker layers)
- MoE module replacement and weight fidelity (Qwen3-Omni)
- Forward function patching (_handle_special_model)
- Processor and template registration
- MoE utility functions (is_moe_layer, get_expert_linear_names, etc.)
- Ignore layer registration (mlp.gate for MoE)
"""

import copy
import shutil
from test.helpers import check_version, make_tiny_qwen3_omni_moe_config, transformers_version

import pytest
import torch
from transformers import Qwen2_5OmniForConditionalGeneration, Qwen3OmniMoeForConditionalGeneration

pytestmark = pytest.mark.skipif(
    not check_version("transformers>=5.1.0"),
    reason="Qwen-Omni models require transformers >= 5.1.0",
)


def _qwen3_omni_thinker_layers(model):
    from auto_round.special_model_handler import _get_qwen3_omni_thinker_layer_info

    layer_prefix, layers = _get_qwen3_omni_thinker_layer_info(model)
    assert layers is not None
    return layer_prefix, layers


# ========================= Qwen2.5-Omni Tests =============================
# NOTE: Tests use the `tiny_qwen2_5_omni` session-scoped fixture from fixtures.py
# (real config, reduced layers, random weights). Skipped if model not available.


class TestQwen2_5Omni:
    """Test block name discovery for Qwen2.5-Omni (dense, not MoE)."""

    @pytest.fixture(autouse=True, scope="class")
    def setup_and_teardown_class(self, tiny_qwen2_5_omni_model_path, request):
        request.cls.model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
            tiny_qwen2_5_omni_model_path, trust_remote_code=True
        )
        yield
        shutil.rmtree("runs", ignore_errors=True)

    def test_block_names_default(self):
        """Test that get_block_names returns thinker layers only by default."""
        from auto_round.utils import get_block_names

        block_names = get_block_names(self.model, quant_vision=False)
        # Should have thinker.model.layers but not talker.model.layers
        assert any(
            "thinker.model.layers" in str(b) for b in block_names
        ), f"Expected thinker.model.layers in block_names, got: {block_names}"
        assert not any(
            "talker.model.layers" in str(b) for b in block_names
        ), f"Did not expect talker.model.layers by default, got: {block_names}"

    def test_block_names_quant_vision(self):
        """Test that quant_vision adds visual and audio blocks."""
        from auto_round.utils import get_block_names

        blocks_no_vision = get_block_names(self.model, quant_vision=False)
        blocks_with_vision = get_block_names(self.model, quant_vision=True)

        assert len(blocks_with_vision) > len(blocks_no_vision), "quant_vision=True should add visual/audio blocks"

    def test_handle_special_model_forward(self):
        """Test that _handle_special_model patches the forward function."""
        from auto_round.special_model_handler import _handle_special_model

        # Deepcopy to avoid mutating the shared session-scoped fixture
        model = copy.deepcopy(self.model)
        original_forward = model.forward
        model = _handle_special_model(model)
        assert model.forward != original_forward, "Forward should be patched for qwen2_5_omni"

    def test_not_moe(self):
        from auto_round.utils.model import is_moe_layer

        # Thinker uses dense MLP, not MoE
        thinker_mlp = self.model.thinker.model.layers[0].mlp
        assert not is_moe_layer(thinker_mlp), "Qwen2.5-Omni should not be detected as MoE"

    def test_not_custom_model(self):
        from auto_round.modeling.fused_moe.replace_modules import is_custom_model

        assert not is_custom_model(self.model), "Qwen2.5-Omni should not be in BUILTIN_MODULES"


class TestQwen2_5OmniProcessor:
    """Test processor and template registration for Qwen2.5-Omni."""

    def test_processor_registered(self):
        from auto_round.compressors.mllm.processor import PROCESSORS

        assert "qwen2_5_omni" in PROCESSORS, "qwen2_5_omni processor not registered"

    def test_template_registered(self):
        from auto_round.compressors.mllm.template import TEMPLATES

        assert "qwen2_5_omni" in TEMPLATES, "qwen2_5_omni template not registered"

    def test_template_default_dataset(self):
        from auto_round.compressors.mllm.template import TEMPLATES

        template = TEMPLATES["qwen2_5_omni"]
        assert template.default_dataset is not None


# ========================= Qwen3-Omni-MoE Tests ===========================


class TestQwen3OmniMoeBlockNames:
    """Test block name discovery for Qwen3-Omni-MoE."""

    def test_block_names_language_model_nested_layers(self):
        from types import SimpleNamespace

        from auto_round.special_model_handler import _get_qwen3_omni_moe_multimodal_block

        model = SimpleNamespace(
            thinker=SimpleNamespace(model=SimpleNamespace(language_model=SimpleNamespace(layers=[object(), object()])))
        )
        block_names = _get_qwen3_omni_moe_multimodal_block(model)
        assert block_names == [["thinker.model.language_model.layers.0", "thinker.model.language_model.layers.1"]]

    def test_block_names_default(self):
        """Test that get_block_names returns thinker layers only by default."""
        from auto_round.utils import get_block_names

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        block_names = get_block_names(model, quant_vision=False)
        layer_prefix, _ = _qwen3_omni_thinker_layers(model)
        assert any(layer_prefix in str(b) for b in block_names), f"Expected {layer_prefix}, got: {block_names}"
        assert not any(
            "talker.model.layers" in str(b) for b in block_names
        ), f"Did not expect talker.model.layers by default, got: {block_names}"

    def test_block_names_quant_vision(self):
        """Test that quant_vision adds visual and audio blocks."""
        from auto_round.utils import get_block_names

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        blocks_no_vision = get_block_names(model, quant_vision=False)
        blocks_with_vision = get_block_names(model, quant_vision=True)

        assert len(blocks_with_vision) > len(blocks_no_vision), "quant_vision=True should add visual/audio blocks"


class TestQwen3OmniMoeForward:
    """Test forward function patching for Qwen3-Omni-MoE."""

    def test_handle_special_model(self):
        """Test that _handle_special_model patches the forward function."""
        from auto_round.special_model_handler import _handle_special_model

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        original_forward = model.forward
        model = _handle_special_model(model)
        assert model.forward != original_forward, "Forward should be patched for qwen3_omni_moe"


class TestQwen3OmniMoeReplacement:
    """Test MoE module replacement for Qwen3-Omni-MoE."""

    def test_replacement_registered(self):
        """Test that thinker MoE block is registered."""
        from auto_round.modeling.fused_moe.qwen3_omni import (
            LinearQwen3OmniThinkerSparseMoeBlock,
        )
        from auto_round.modeling.fused_moe.replace_modules import ReplacementModuleBase

        assert ReplacementModuleBase.is_registered("Qwen3OmniMoeThinkerTextSparseMoeBlock")
        # Talker has no replacement class — it stays fused and is excluded via MOE_SKIP_PREFIXES
        assert not ReplacementModuleBase.is_registered("Qwen3OmniMoeTalkerTextSparseMoeBlock")

    def test_builtin_modules_entry(self):
        """Test that qwen3_omni_moe is in BUILTIN_MODULES."""
        from auto_round.modeling.fused_moe.replace_modules import BUILTIN_MODULES

        assert "qwen3_omni_moe" in BUILTIN_MODULES

    def test_is_custom_model(self):
        """Test that is_custom_model returns True for Qwen3-Omni-MoE."""
        from auto_round.modeling.fused_moe.replace_modules import is_custom_model

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)
        assert is_custom_model(model)

    def test_apply_replacements(self):
        """Test that only thinker MoE blocks are replaced; talker stays fused."""
        from auto_round.modeling.fused_moe.replace_modules import apply_replacements

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        original_talker_class = model.talker.model.layers[0].mlp.__class__.__name__
        model = apply_replacements(model)

        # Check that thinker MoE was custom-replaced
        _, thinker_layers = _qwen3_omni_thinker_layers(model)
        thinker_mlp = thinker_layers[0].mlp
        assert (
            "LinearQwen3OmniThinker" in thinker_mlp.__class__.__name__
        ), f"Expected LinearQwen3OmniThinker, got {thinker_mlp.__class__.__name__}"

        # Talker MoE stays fused (excluded from both custom replacement and generic unfuse)
        # to prevent memory eviction during disk-offloaded quantization.
        # ShardWriter handles fused→per-expert conversion at save time.
        talker_mlp = model.talker.model.layers[0].mlp
        assert (
            talker_mlp.__class__.__name__ == original_talker_class
        ), f"Expected talker MoE to stay original ({original_talker_class}), got {talker_mlp.__class__.__name__}"
        assert hasattr(
            model.talker.model.layers[0].mlp.experts, "gate_up_proj"
        ), "Talker experts should keep fused gate_up_proj"

    def test_weight_fidelity(self):
        """Test that unfused thinker weights match original fused weights.

        Talker MoE stays fused (excluded from quantization), so only
        thinker experts are verified here.
        """
        from auto_round.modeling.fused_moe.replace_modules import apply_replacements, materialize_model_

        torch.manual_seed(42)

        def assert_same_weights(actual: torch.Tensor, expected: torch.Tensor):
            torch.testing.assert_close(actual, expected, rtol=0, atol=0, equal_nan=True)

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        # Save original fused thinker weights
        _, thinker_layers = _qwen3_omni_thinker_layers(model)
        thinker_gate_up = thinker_layers[0].mlp.experts.gate_up_proj.data.clone()
        thinker_down = thinker_layers[0].mlp.experts.down_proj.data.clone()

        model = apply_replacements(model)
        materialize_model_(model)

        intermediate = 32  # moe_intermediate_size
        # Verify thinker expert weights
        # Use equal_nan=True because fused expert parameters may contain
        # uninitialized memory with NaN bit patterns, and NaN != NaN in IEEE 754.
        for i in range(4):
            _, thinker_layers = _qwen3_omni_thinker_layers(model)
            expert = thinker_layers[0].mlp.experts[i]
            assert_same_weights(expert.gate_proj.weight.data, thinker_gate_up[i, :intermediate, :])
            assert_same_weights(expert.up_proj.weight.data, thinker_gate_up[i, intermediate:, :])
            assert_same_weights(expert.down_proj.weight.data, thinker_down[i])

    def test_forward_output_match(self):
        """Test that replaced thinker MoE forward output matches original.

        Talker MoE is not replaced, so only thinker output is verified.
        """
        from auto_round.modeling.fused_moe.replace_modules import apply_replacements, materialize_model_

        torch.manual_seed(0)
        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)
        _, thinker_layers = _qwen3_omni_thinker_layers(model)

        x = torch.randn(1, 4, 64) * 0.1
        with torch.no_grad():
            orig_thinker_out = thinker_layers[0].mlp(x)

        model = apply_replacements(model)
        materialize_model_(model)
        _, thinker_layers = _qwen3_omni_thinker_layers(model)

        with torch.no_grad():
            new_thinker_out = thinker_layers[0].mlp(x)

        assert orig_thinker_out.shape == new_thinker_out.shape, "Thinker shape mismatch"
        orig_nan = torch.isnan(orig_thinker_out)
        new_nan = torch.isnan(new_thinker_out)
        assert torch.equal(orig_nan, new_nan), "Thinker NaN positions differ"
        finite_mask = ~orig_nan
        if finite_mask.any():
            assert torch.allclose(
                orig_thinker_out[finite_mask], new_thinker_out[finite_mask], atol=1e-5
            ), "Thinker MoE forward mismatch on finite values"


class TestQwen3OmniMoeProcessor:
    """Test processor and template registration for Qwen3-Omni-MoE."""

    def test_processor_registered(self):
        from auto_round.compressors.mllm.processor import PROCESSORS

        assert "qwen3_omni" in PROCESSORS, "qwen3_omni processor not registered"

    def test_template_registered(self):
        from auto_round.compressors.mllm.template import TEMPLATES

        assert "qwen3_omni_moe" in TEMPLATES, "qwen3_omni_moe template not registered"


class TestQwen3OmniMoeUtils:
    """Test MoE utility functions for Qwen3-Omni-MoE classes."""

    def test_is_moe_layer_thinker(self):
        from auto_round.utils.model import is_moe_layer

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)
        _, thinker_layers = _qwen3_omni_thinker_layers(model)
        moe_block = thinker_layers[0].mlp
        assert is_moe_layer(moe_block), f"Thinker MoE block ({moe_block.__class__.__name__}) should be detected as MoE"

    def test_is_moe_layer_talker(self):
        from auto_round.utils.model import is_moe_layer

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)
        moe_block = model.talker.model.layers[0].mlp
        assert is_moe_layer(moe_block), f"Talker MoE block ({moe_block.__class__.__name__}) should be detected as MoE"

    def test_get_expert_linear_names(self):
        from auto_round.utils.model import get_expert_linear_names

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        _, thinker_layers = _qwen3_omni_thinker_layers(model)
        thinker_mlp = thinker_layers[0].mlp
        names = get_expert_linear_names(thinker_mlp)
        assert set(names) == {"gate_proj", "down_proj", "up_proj"}

        talker_mlp = model.talker.model.layers[0].mlp
        names = get_expert_linear_names(talker_mlp)
        assert set(names) == {"gate_proj", "down_proj", "up_proj"}

    def test_get_expert_input_proj_names(self):
        from auto_round.utils.model import get_expert_input_proj_names

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        _, thinker_layers = _qwen3_omni_thinker_layers(model)
        thinker_mlp = thinker_layers[0].mlp
        names = get_expert_input_proj_names(thinker_mlp)
        assert set(names) == {"gate_proj", "up_proj"}

    def test_ignore_layers_registered(self):
        from auto_round.special_model_handler import get_predefined_ignore_layers

        config = make_tiny_qwen3_omni_moe_config()
        model = Qwen3OmniMoeForConditionalGeneration(config)

        layer_prefix, _ = _qwen3_omni_thinker_layers(model)
        ignore_layers = get_predefined_ignore_layers(model)
        assert ignore_layers == [
            f"{layer_prefix}.0.mlp.gate",
            "talker.model.layers.0.mlp.gate",
            "talker.model.layers.0.mlp.shared_expert_gate",
        ], f"Expected mlp.gate in ignore_layers for qwen3_omni_moe, got: {ignore_layers}"


class TestVisualKeysExclusion:
    """Test that omni sub-modules are properly excluded from quantization."""

    def test_visual_keys_contain_omni_keys(self):
        from auto_round.compressors.mllm.utils import VISUAL_KEYS

        expected_keys = ["thinker", "talker", "audio", "token2wav", "code2wav", "audio_tower", "code_predictor"]
        for key in expected_keys:
            assert key in VISUAL_KEYS, f"'{key}' should be in VISUAL_KEYS"