Skip to content

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

18.7 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.
"""Tests for the pure helpers in auto_round/utils/common.py."""

import argparse
import json
import os
import sys
from unittest.mock import patch

import pytest
import torch


# ---------------------------------------------------------------------------
# contain_any_mm_keys
# ---------------------------------------------------------------------------
class TestContainAnyMmKeys:
    def test_name_with_visual_keyword_matches(self):
        from auto_round.utils.common import contain_any_mm_keys

        assert contain_any_mm_keys("model.visual.blocks.0") is True

    def test_name_with_audio_keyword_matches(self):
        from auto_round.utils.common import contain_any_mm_keys

        assert contain_any_mm_keys("audio_encoder.layers.0") is True

    def test_plain_text_model_name_does_not_match(self):
        from auto_round.utils.common import contain_any_mm_keys

        assert contain_any_mm_keys("model.layers.0.self_attn.q_proj") is False

    def test_empty_name_does_not_match(self):
        from auto_round.utils.common import contain_any_mm_keys

        assert contain_any_mm_keys("") is False


# ---------------------------------------------------------------------------
# is_debug_mode
# ---------------------------------------------------------------------------
class TestIsDebugMode:
    def test_returns_bool(self):
        from auto_round.utils.common import is_debug_mode

        assert isinstance(is_debug_mode(), bool)

    def test_true_when_sys_gettrace_returns_non_none(self):
        from auto_round.utils.common import is_debug_mode

        with patch.object(sys, "gettrace", return_value=lambda *a, **kw: None):
            assert is_debug_mode() is True

    def test_false_when_no_tracer(self):
        from auto_round.utils.common import is_debug_mode

        class _FakeFlags:
            debug = 0

        with patch.object(sys, "gettrace", return_value=None), patch.object(sys, "flags", _FakeFlags()):
            assert is_debug_mode() is False


# ---------------------------------------------------------------------------
# is_local_path
# ---------------------------------------------------------------------------
class TestIsLocalPath:
    def test_existing_text_file_is_local(self, tmp_path):
        from auto_round.utils.common import is_local_path

        p = tmp_path / "weights.txt"
        p.write_text("hi")
        assert is_local_path(str(p)) is True

    def test_existing_json_file_is_local(self, tmp_path):
        from auto_round.utils.common import is_local_path

        p = tmp_path / "weights.json"
        p.write_text("{}")
        assert is_local_path(str(p)) is True

    def test_non_existing_path_is_not_local(self, tmp_path):
        from auto_round.utils.common import is_local_path

        assert is_local_path(str(tmp_path / "missing.txt")) is False

    def test_unsupported_extension_with_existing_file(self, tmp_path):
        from auto_round.utils.common import is_local_path

        p = tmp_path / "weights.bin"
        p.write_text("hi")
        # ".bin" is not in format_list -> returns None, which is falsy
        assert is_local_path(str(p)) is None or is_local_path(str(p)) is False


# ---------------------------------------------------------------------------
# get_library_version
# ---------------------------------------------------------------------------
class TestGetLibraryVersion:
    def test_real_package_returns_string_version(self):
        from auto_round.utils.common import get_library_version

        version = get_library_version("torch")
        assert isinstance(version, str)
        # The returned value should not be the "not installed" sentinel
        assert "not installed" not in version

    def test_missing_package_returns_sentinel_message(self):
        from auto_round.utils.common import get_library_version

        msg = get_library_version("definitely_not_a_real_package_zzz_12345")
        assert isinstance(msg, str)
        assert "not installed" in msg


# ---------------------------------------------------------------------------
# str2bool
# ---------------------------------------------------------------------------
class TestStr2Bool:
    def test_true_variants(self):
        from auto_round.utils.common import str2bool

        for v in ("yes", "true", "t", "y", "1", "YES", "True"):
            assert str2bool(v) is True

    def test_false_variants(self):
        from auto_round.utils.common import str2bool

        for v in ("no", "false", "f", "n", "0", "NO", "False"):
            assert str2bool(v) is False

    def test_already_bool_returns_as_is(self):
        from auto_round.utils.common import str2bool

        assert str2bool(True) is True
        assert str2bool(False) is False

    def test_invalid_string_raises(self):
        from auto_round.utils.common import str2bool

        with pytest.raises(argparse.ArgumentTypeError):
            str2bool("maybe")


# ---------------------------------------------------------------------------
# flatten_list
# ---------------------------------------------------------------------------
class TestFlattenList:
    def test_flatten_nested_lists(self):
        from auto_round.utils.common import flatten_list

        assert flatten_list([1, [2, 3], [4, [5, 6]]]) == [1, 2, 3, 4, 5, 6]

    def test_flatten_already_flat(self):
        from auto_round.utils.common import flatten_list

        assert flatten_list([1, 2, 3]) == [1, 2, 3]

    def test_flatten_with_tuples(self):
        from auto_round.utils.common import flatten_list

        assert flatten_list([(1, 2), 3, [4]]) == [1, 2, 3, 4]

    def test_flatten_empty(self):
        from auto_round.utils.common import flatten_list

        assert flatten_list([]) == []

    def test_flatten_deeply_nested(self):
        from auto_round.utils.common import flatten_list

        assert flatten_list([[[1, 2], [3, 4]], [[5]]]) == [1, 2, 3, 4, 5]


# ---------------------------------------------------------------------------
# to_standard_regex
# ---------------------------------------------------------------------------
class TestToStandardRegex:
    def test_plain_string_wraps_with_wildcards(self):
        from auto_round.utils.common import to_standard_regex

        result = to_standard_regex("model.embed_tokens")
        # Should wrap with .* on each side
        assert result.startswith(".*")
        assert result.endswith(".*")
        # The middle part should still contain the original text
        assert "model" in result and "embed_tokens" in result

    def test_string_with_anchors_kept_as_is(self):
        from auto_round.utils.common import to_standard_regex

        anchored = "mlp.gate$"
        result = to_standard_regex(anchored)
        # '$' signals user intent, should be preserved (no double-wrap)
        assert "$" in result

    def test_string_with_wildcard_still_wrapped(self):
        from auto_round.utils.common import to_standard_regex

        # Implementation always wraps with .* on both sides; confirm behaviour
        result = to_standard_regex("model.*attn")
        assert result.startswith(".*") and result.endswith(".*")
        assert "model" in result and "attn" in result

    def test_string_with_caret_kept(self):
        from auto_round.utils.common import to_standard_regex

        result = to_standard_regex("^layer.0")
        assert result.startswith("^")

    def test_returns_compilable_regex(self):
        import re as _re

        from auto_round.utils.common import to_standard_regex

        # Must not raise when compiled
        _re.compile(to_standard_regex("plain_text"))

    @pytest.mark.parametrize(
        "pattern, matching, nonmatching",
        [
            ("layers.{3}mlp", "layers.3.mlp", "layers.33.mlp"),
            ("layers.{2,3}mlp", "layers.3.mlp", "layers.333.mlp"),
            ("layers.{3,}mlp", "layers.33.mlp", "layers3mlp"),
            ("layer*s", "layerrs", "layexs"),
        ],
    )
    def test_unanchored_quantifiers(self, pattern, matching, nonmatching):
        import re as _re

        from auto_round.utils.common import to_standard_regex

        regex = to_standard_regex(pattern)
        assert _re.search(regex, matching)
        assert not _re.search(regex, nonmatching)

    def test_regex_tokens_and_escapes_kept(self):
        import re as _re

        from auto_round.utils.common import to_standard_regex

        name = "model.layers.3.mlp.gate"
        for pattern in ("layers.+mlp", r"layers\.[0-9]+\.mlp", r"model\.layers\.3"):
            assert _re.search(to_standard_regex(pattern), name), pattern
        # Bare dots are still literal.
        assert not _re.search(to_standard_regex("mlp.gate"), "mlpXgate")


# ---------------------------------------------------------------------------
# matches_any_regex
# ---------------------------------------------------------------------------
class TestMatchesAnyRegex:
    def test_empty_config_returns_false(self):
        from auto_round.utils.common import matches_any_regex

        assert matches_any_regex("anything", {}) is False

    def test_matching_pattern_returns_true(self):
        from auto_round.utils.common import matches_any_regex

        cfg = {".*attn.*": {"bits": 4}}
        assert matches_any_regex("layer.0.self_attn.q_proj", cfg) is True

    def test_no_match_returns_false(self):
        from auto_round.utils.common import matches_any_regex

        cfg = {"^mlp\\.": {"bits": 8}}
        assert matches_any_regex("layer.0.self_attn.q_proj", cfg) is False

    def test_dynamic_prefix_is_stripped(self):
        """Patterns starting with '+:' or '-:' should be treated as raw regex."""
        from auto_round.utils.common import matches_any_regex

        cfg = {"+:attn.*": {"bits": 4}}
        assert matches_any_regex("layer.0.attn.q_proj", cfg) is True

    def test_invalid_regex_is_skipped(self):
        from auto_round.utils.common import matches_any_regex

        cfg = {"[unclosed": {"bits": 4}}
        # Should not raise; returns False since the only pattern is invalid
        assert matches_any_regex("anything", cfg) is False


# ---------------------------------------------------------------------------
# json_serialize
# ---------------------------------------------------------------------------
class TestJsonSerialize:
    def test_torch_dtype_float16(self):
        from auto_round.utils.common import json_serialize

        assert json_serialize(torch.float16) == "float16"

    def test_torch_dtype_int64(self):
        from auto_round.utils.common import json_serialize

        assert json_serialize(torch.int64) == "int64"

    def test_unsupported_type_raises(self):
        from auto_round.utils.common import json_serialize

        with pytest.raises(TypeError):
            json_serialize(object())


# ---------------------------------------------------------------------------
# get_reciprocal
# ---------------------------------------------------------------------------
class TestGetReciprocal:
    def test_normal_values(self):
        from auto_round.utils.common import get_reciprocal

        t = torch.tensor([2.0, 4.0, 0.5])
        r = get_reciprocal(t)
        assert torch.allclose(r, torch.tensor([0.5, 0.25, 2.0]))

    def test_small_values_are_masked_to_zero(self):
        from auto_round.utils.common import get_reciprocal

        # Use a value smaller than the fp32 eps used inside the function (1e-30)
        t = torch.tensor([1e-40, 1.0])
        r = get_reciprocal(t)
        assert r[0].item() == 0.0
        assert r[1].item() == pytest.approx(1.0)

    def test_float16_uses_larger_eps(self):
        from auto_round.utils.common import get_reciprocal

        # Use a value smaller than the fp16 eps of 1e-5
        t = torch.tensor([1e-7, 1.0], dtype=torch.float16)
        r = get_reciprocal(t)
        # 1e-7 is below the fp16 eps of 1e-5, so should be masked to 0
        assert r[0].item() == 0.0
        assert r[1].item() == pytest.approx(1.0, rel=1e-2)

    def test_does_not_raise_under_torch_compile(self):
        """Smoke test: should not contain operations that break torch.compile."""
        from auto_round.utils.common import get_reciprocal

        t = torch.tensor([0.0, 1.0, -2.0])
        # No exception expected; the function uses torch.where to avoid nonzero
        out = get_reciprocal(t)
        assert out.shape == t.shape


# ---------------------------------------------------------------------------
# parse_layer_config_arg
# ---------------------------------------------------------------------------
class TestParseLayerConfigArg:
    def test_strict_json(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg('{"bits": 4, "group_size": 128}')
        assert result == {"bits": 4, "group_size": 128}

    def test_regex_key_with_json_invalid_escapes(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg(r'{"layers\.\d{1,2}\.mlp": {"bits": 8, "group_size": 64}}')
        assert result == {r"layers\.\d{1,2}\.mlp": {"bits": 8, "group_size": 64}}

    def test_cli_friendly_dict_syntax(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg("{bits:4, group_size:128}")
        assert result == {"bits": 4, "group_size": 128}

    def test_quoted_string_keys_are_stripped(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg('{"bits": 4}')
        assert result == {"bits": 4}

    def test_negative_integer_is_preserved(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg('{"bits": -4}')
        assert result == {"bits": -4}

    def test_boolean_strings_normalized(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg('{"a": true, "b": false}')
        assert result == {"a": True, "b": False}

    def test_null_string_normalized_to_none(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg('{"a": null}')
        assert result == {"a": None}

    def test_nested_dict(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg('{"outer": {"inner": 1}}')
        assert result == {"outer": {"inner": 1}}

    def test_invalid_input_raises(self):
        from auto_round.utils.common import parse_layer_config_arg

        with pytest.raises(ValueError):
            parse_layer_config_arg("")

    def test_multi_key_unquoted_dict(self):
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg("{mtp:{bits:8,data_type:int},mtp.fc:{bits:16,data_type:int}}")
        assert result == {
            "mtp": {"bits": 8, "data_type": "int"},
            "mtp.fc": {"bits": 16, "data_type": "int"},
        }

    def test_quoted_regex_keys_preserved(self):
        """Quoted JSON-like input with regex paths should remain usable from the CLI."""
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg(
            r'{"model.language_model.layers.\\d+.self_attn..":{"bits":"8"},'
            r'"model.language_model.layers.\\d+.router..*":{"bits":"8"}}'
        )
        assert result == {
            r"model.language_model.layers.\d+.self_attn..": {"bits": 8},
            r"model.language_model.layers.\d+.router..*": {"bits": 8},
        }

    def test_single_escaped_regex_keys_recovered(self):
        """Shell-passed strings often contain single backslashes that are invalid JSON but still recoverable."""
        from auto_round.utils.common import parse_layer_config_arg

        result = parse_layer_config_arg(
            r'{"model.language_model.layers.\d+.self_attn..":{"bits":"8"},'
            r'"model.language_model.layers.\d+.mlp..":{"bits":"8"}}'
        )
        assert result == {
            r"model.language_model.layers.\d+.self_attn..": {"bits": 8},
            r"model.language_model.layers.\d+.mlp..": {"bits": 8},
        }


# ---------------------------------------------------------------------------
# GlobalState
# ---------------------------------------------------------------------------
class TestGlobalState:
    def test_starts_at_zero(self):
        from auto_round.utils.common import GlobalState

        gs = GlobalState()
        assert isinstance(gs.replaced_module_count, int)

    def test_can_be_incremented(self):
        from auto_round.utils.common import GlobalState

        gs = GlobalState()
        before = gs.replaced_module_count
        gs.replaced_module_count += 5
        assert gs.replaced_module_count == before + 5


# ---------------------------------------------------------------------------
# Transformers version checks
# ---------------------------------------------------------------------------
class TestTransformersVersionChecks:
    def test_v5_4_returns_bool(self):
        from auto_round.utils.common import is_transformers_version_greater_or_equal_5_4_0

        # Cache may already be set; result must be bool
        assert isinstance(is_transformers_version_greater_or_equal_5_4_0(), bool)

    def test_v5_returns_bool(self):
        from auto_round.utils.common import is_transformers_version_greater_or_equal_5

        assert isinstance(is_transformers_version_greater_or_equal_5(), bool)

    def test_v4_returns_bool(self):
        from auto_round.utils.common import is_transformers_version_greater_or_equal_4

        assert isinstance(is_transformers_version_greater_or_equal_4(), bool)


# ---------------------------------------------------------------------------
# infer_bits_by_data_type
# ---------------------------------------------------------------------------
class TestInferBitsByDataType:
    def test_int2_returns_2(self):
        from auto_round.utils.common import infer_bits_by_data_type

        assert infer_bits_by_data_type("int2") == 2

    def test_int4_returns_4(self):
        from auto_round.utils.common import infer_bits_by_data_type

        assert infer_bits_by_data_type("int4") == 4

    def test_int8_returns_8(self):
        from auto_round.utils.common import infer_bits_by_data_type

        assert infer_bits_by_data_type("int8") == 8

    def test_unknown_returns_none(self):
        from auto_round.utils.common import infer_bits_by_data_type

        assert infer_bits_by_data_type("not_a_real_dtype") is None