PTQ-Level Efficiency, QAT-Level Accuracy | 训练后量化的效率,量化感知训练的精度
# 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"