Skip to content

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

13.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.
"""Tests for ``auto_round/utils/offload.py``.

CPU-friendly: tests the small helpers (``_flatten_names``,
``OffloadManager.__init__``, ``OffloadManager.has``, ``estimate_module_size_gb``,
``_clear_module_weights``, ``_load_state_dict_into_module``) on a tiny model.
The full save/reload path requires a real model checkpoint and is covered
elsewhere.
"""

import json
import os
from unittest.mock import patch

import pytest
import torch
import torch.nn as nn


# ---------------------------------------------------------------------------
# _flatten_names
# ---------------------------------------------------------------------------
class TestFlattenNames:
    def test_flat_already(self):
        from auto_round.utils.offload import OffloadManager

        assert OffloadManager._flatten_names(["a", "b", "c"]) == ["a", "b", "c"]

    def test_nested_one_level(self):
        from auto_round.utils.offload import OffloadManager

        result = OffloadManager._flatten_names([["a", "b"], "c", ["d"]])
        assert result == ["a", "b", "c", "d"]

    def test_empty_input(self):
        from auto_round.utils.offload import OffloadManager

        assert OffloadManager._flatten_names([]) == []

    def test_deeply_nested(self):
        from auto_round.utils.offload import OffloadManager

        result = OffloadManager._flatten_names([["a", ["b", "c"]], "d"])
        # Inner ["b", "c"] is itself a list, so it gets treated as a single item;
        # the helper only handles one level of nesting
        assert result == ["a", ["b", "c"], "d"]


# ---------------------------------------------------------------------------
# OffloadManager.__init__
# ---------------------------------------------------------------------------
class TestOffloadManagerInit:
    def test_default_construction(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager()
        assert mgr.mode == "offload"
        assert mgr.enabled is True
        assert mgr._saved == {}
        assert mgr._tempdir is None

    def test_disabled_construction(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager(enabled=False)
        assert mgr.enabled is False

    def test_clean_mode(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager(mode="clean", model_dir="/some/dir")
        assert mgr.mode == "clean"
        assert mgr.model_dir == "/some/dir"

    def test_cache_numel_flag(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager(cache_numel=True)
        assert mgr.cache_numel is True


# ---------------------------------------------------------------------------
# OffloadManager.has / reset
# ---------------------------------------------------------------------------
class TestOffloadManagerStateQueries:
    def test_has_returns_false_initially(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager()
        assert mgr.has("any.module") is False

    def test_has_offload_mode_returns_true_after_save(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager(mode="offload")
        mgr._saved["model.layer"] = {"save_path": "/tmp/foo"}
        assert mgr.has("model.layer") is True
        assert mgr.has("model.other") is False

    def test_has_clean_mode_always_false(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager(mode="clean")
        mgr._saved["model.layer"] = {"save_path": "/tmp/foo"}  # pretend
        # In clean mode, has() always returns False
        assert mgr.has("model.layer") is False

    def test_reset_clears_saved(self):
        from auto_round.utils.offload import OffloadManager

        mgr = OffloadManager(mode="offload")
        mgr._saved["a"] = {"save_path": "/tmp/a"}
        mgr._current_loaded = "a"
        mgr._last_loaded = "a"
        mgr.reset()
        assert mgr._saved == {}
        assert mgr._current_loaded is None
        assert mgr._last_loaded is None


# ---------------------------------------------------------------------------
# estimate_module_size_gb
# ---------------------------------------------------------------------------
class TestEstimateModuleSize:
    def test_empty_module(self):
        from auto_round.utils.offload import OffloadManager

        m = nn.Module()
        size = OffloadManager.estimate_module_size_gb(m)
        assert size == 0.0

    def test_small_module(self):
        from auto_round.utils.offload import OffloadManager

        m = nn.Linear(10, 10)  # 110 fp32 params
        size = OffloadManager.estimate_module_size_gb(m)
        # 110 * 4 bytes = 440 bytes; in GB = 440 / 1024^3
        assert size > 0
        assert size < 1e-6  # way less than a GB


# ---------------------------------------------------------------------------
# _clear_module_weights
# ---------------------------------------------------------------------------
class TestClearModuleWeights:
    def test_clear_sets_weight_to_empty(self):
        from auto_round.utils.offload import _clear_module_weights

        layer = nn.Linear(4, 4)
        assert layer.weight.numel() == 16
        _clear_module_weights(layer)
        assert layer.weight.numel() == 0
        assert layer.bias.numel() == 0

    def test_clear_caches_numel_and_shape(self):
        from auto_round.utils.offload import _clear_module_weights

        layer = nn.Linear(4, 4)
        _clear_module_weights(layer, cache_numel=True)
        assert layer._cached_weight_numel == 16
        assert layer._cached_weight_shape == (4, 4)

    def test_clear_none_is_noop(self):
        from auto_round.utils.offload import _clear_module_weights

        # Should not raise
        _clear_module_weights(None)

    def test_clear_skips_orig_layer(self):
        from auto_round.utils.offload import _clear_module_weights

        class _Wrapper(nn.Module):
            pass

        inner = nn.Linear(4, 4)
        wrapper = _Wrapper()
        wrapper.orig_layer = inner
        # Should skip clearing when orig_layer is set
        _clear_module_weights(wrapper)
        # inner.weight should remain intact
        assert inner.weight.numel() == 16

    def test_clear_with_restorable_filter(self):
        from auto_round.utils.offload import _clear_module_weights

        layer = nn.Linear(4, 4)
        # Layer has both weight and bias; only clear weight
        _clear_module_weights(layer, restorable_params={"weight"})
        assert layer.weight.numel() == 0
        # bias should remain
        assert layer.bias.numel() == 4

    def test_clear_with_restorable_excluding_weight(self):
        from auto_round.utils.offload import _clear_module_weights

        layer = nn.Linear(4, 4)
        # Restorable set does NOT include weight -> weight must remain
        _clear_module_weights(layer, restorable_params={"bias"})
        assert layer.weight.numel() == 16
        assert layer.bias.numel() == 0


# ---------------------------------------------------------------------------
# _load_state_dict_into_module
# ---------------------------------------------------------------------------
class TestLoadStateDictIntoModule:
    def test_restores_linear_weight(self):
        from auto_round.utils.offload import (
            _clear_module_weights,
            _load_state_dict_into_module,
        )

        layer = nn.Linear(4, 4)
        saved = {"weight": layer.weight.detach().clone(), "bias": layer.bias.detach().clone()}

        _clear_module_weights(layer)
        assert layer.weight.numel() == 0

        _load_state_dict_into_module(saved, layer)
        # Weight should be restored
        assert layer.weight.numel() == 16
        assert torch.allclose(layer.weight.data, saved["weight"])

    def test_skips_missing_submodule(self):
        """If a nested attribute is missing, the loader must silently skip."""
        from auto_round.utils.offload import _load_state_dict_into_module

        # state_dict has a key whose intermediate path doesn't exist
        state_dict = {"nonexistent_sub.weight": torch.zeros(4, 4)}
        # Should not raise
        _load_state_dict_into_module(state_dict, nn.Linear(4, 4))


# ---------------------------------------------------------------------------
# _resolve_model_dir
# ---------------------------------------------------------------------------
class TestResolveModelDir:
    def test_existing_directory_returned_as_is(self, tmp_path):
        from auto_round.utils.offload import _resolve_model_dir

        assert _resolve_model_dir(str(tmp_path)) == str(tmp_path)

    def test_nonexistent_path_falls_through(self, tmp_path):
        """If snapshot_download fails, the original input is returned."""
        from auto_round.utils.offload import _resolve_model_dir

        with patch(
            "huggingface_hub.snapshot_download",
            side_effect=Exception("not on hub"),
        ):
            result = _resolve_model_dir(str(tmp_path / "missing"))
            assert result == str(tmp_path / "missing")

    def test_revision_resolves_partial_snapshot_from_cached_weight_index(self, tmp_path):
        """A usable weight snapshot need not contain every repository file."""
        from auto_round.utils.offload import _resolve_model_dir

        snapshot = tmp_path / "snapshots" / "commit"
        index_path = snapshot / "model.safetensors.index.json"
        index_path.parent.mkdir(parents=True)
        index_path.write_text('{"weight_map": {}}')
        incomplete = RuntimeError("snapshot is missing README.md")
        with (
            patch("huggingface_hub.try_to_load_from_cache", return_value=str(index_path)) as cached,
            patch("huggingface_hub.snapshot_download", side_effect=incomplete) as download,
        ):
            resolved = _resolve_model_dir("org/model", revision="commit")

        assert resolved == str(snapshot)
        cached.assert_called_once_with("org/model", "model.safetensors.index.json", revision="commit")
        download.assert_not_called()

    def test_offload_manager_resolves_model_id_once(self, tmp_path):
        """Block reloads must reuse the snapshot resolved when the manager is created."""
        from auto_round.utils.offload import OffloadManager

        snapshot = tmp_path / "snapshot"
        snapshot.mkdir()
        model = nn.Sequential(nn.Linear(2, 2))
        with (
            patch("auto_round.utils.offload._resolve_model_dir", return_value=str(snapshot)) as resolve,
            patch("auto_round.utils.offload.load_block_from_model_files") as load_block,
        ):
            manager = OffloadManager(mode="clean", model_dir="org/model", model_revision="commit")
            manager.reload(model, "0")

        assert manager.model_dir == str(snapshot)
        resolve.assert_called_once_with("org/model", revision="commit")
        load_block.assert_called_once_with(str(snapshot), "0", model[0])

    def test_offload_manager_uses_diffusion_component_subfolder(self, tmp_path):
        """Diffusers block reloads must read from the active pipeline component."""
        from auto_round.utils.offload import OffloadManager

        component_dir = tmp_path / "transformer_2"
        component_dir.mkdir()
        model = nn.Sequential(nn.Linear(2, 2))
        model._autoround_checkpoint_subfolder = "transformer_2"
        with patch("auto_round.utils.offload.load_block_from_model_files") as load_block:
            manager = OffloadManager(mode="clean", model_dir=str(tmp_path))
            manager.reload(model, "0")

        load_block.assert_called_once_with(str(component_dir), "0", model[0])

    def test_offload_manager_does_not_eagerly_resolve_without_revision(self):
        """Revision-less and non-Hugging Face sources retain the legacy lazy path."""
        from auto_round.utils.offload import OffloadManager

        with patch("auto_round.utils.offload._resolve_model_dir") as resolve:
            manager = OffloadManager(mode="clean", model_dir="modelscope/model")

        assert manager.model_dir == "modelscope/model"
        resolve.assert_not_called()

    def test_revision_resolution_preserves_hub_error(self):
        """A pinned lookup failure must not be hidden behind a local-path error."""
        from auto_round.utils.offload import _resolve_model_dir

        error = RuntimeError("snapshot unavailable")
        with (
            patch("huggingface_hub.try_to_load_from_cache", return_value=None),
            patch("huggingface_hub.snapshot_download", side_effect=error),
            pytest.raises(RuntimeError) as exc_info,
        ):
            _resolve_model_dir("org/model", revision="commit")

        assert exc_info.value is error


class TestBuildWeightMap:
    def test_custom_diffusers_safetensors_index(self, tmp_path):
        from auto_round.utils.offload import _build_weight_map

        weight_map = {"blocks.0.weight": "diffusion_pytorch_model-00001-of-00002.safetensors"}
        index_path = tmp_path / "diffusion_pytorch_model.safetensors.index.json"
        index_path.write_text(json.dumps({"weight_map": weight_map}))

        assert _build_weight_map(str(tmp_path)) == weight_map