Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Catch a temporary patch that stops applying instead of only logging it (#11198)
Daniel Hane00e8bb7fd90
diff --git a/tests/test_import_time_floors.py b/tests/test_import_time_floors.pyindex 677c51543f8..af411e7e8a7 100644--- a/tests/test_import_time_floors.py+++ b/tests/test_import_time_floors.py@@ -790,8 +790,12 @@ class _CollectingLogger:self.warnings.append(message)-def _isolated_run_temporary_patches(patches, logger):- """`_run_temporary_patches` alone, with its two module globals supplied.+def _isolated_run_temporary_patches(+ patches,+ logger,+ outcomes = None,+):+ """`_run_temporary_patches` alone, with its module globals supplied.Loading it out of the file rather than importing unsloth.models._utils keepsthis a test of the control flow and not of a full model-stack import.@@ -806,7 +810,11 @@ def _isolated_run_temporary_patches(patches, logger):else:raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")- namespace = {"TEMPORARY_PATCHES": patches, "logger": logger}+ namespace = {+ "TEMPORARY_PATCHES": patches,+ "logger": logger,+ "TEMPORARY_PATCH_OUTCOMES": {} if outcomes is None else outcomes,+ }exec(compile(segment, str(path), "exec"), namespace)return namespace["_run_temporary_patches"]diff --git a/tests/test_temporary_patch_coverage.py b/tests/test_temporary_patch_coverage.pynew file mode 100644index 00000000000..2863b35c30b--- /dev/null+++ b/tests/test_temporary_patch_coverage.py@@ -0,0 +1,430 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.+#+# This program is free software: you can redistribute it and/or modify+# it under the terms of the GNU Affero General Public License as published by+# the Free Software Foundation, either version 3 of the License, or+# (at your option) any later version.+#+# This program is distributed in the hope that it will be useful,+# but WITHOUT ANY WARRANTY; without even the implied warranty of+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+# GNU Affero General Public License for more details.+#+# You should have received a copy of the GNU Affero General Public License+# along with this program. If not, see <https://www.gnu.org/licenses/>.+"""A temporary patch that stops applying has to be caught, not just logged.++`_run_temporary_patches` calls each entry of `TEMPORARY_PATCHES` inside+`except Exception` and emits `logger.warning`, so `import unsloth` survives a+patch that blows up (#3130 ended the import outright on a `SyntaxError` from+one). The cost of that is a silent one: a patch can rot away against a new+transformers and every job stays green, because the only trace is a warning+line nobody asserts on.++The gate here reads the outcome that `_run_temporary_patches` now records and+fails on any patch that RAISED.++Why not assert a list of patch names, or a count. Which patches apply depends+entirely on what is installed. `patch_gemma4_moe` has nothing to attach itself+to on transformers 4.57.6 and returns without doing anything; the MoE+quantization patches check `is_transformers_v5_moe_quantization_available()`+first and decline on v4. A name list or a count would go red on the 4.57.6 leg+of the matrix for patches that are behaving exactly as designed, and would need+editing every time a patch is added. So the question asked is not "did patch X+apply" but "did any patch raise", which is version independent: declining+cleanly is a normal return, raising never is.+"""++import ast+import gc+import json+import os+import pathlib+import subprocess+import sys+import weakref++import pytest++_ROOT = pathlib.Path(__file__).resolve().parents[1]+_UTILS = _ROOT / "unsloth" / "models" / "_utils.py"++_BEGIN = "UNSLOTH_PATCH_REPORT_BEGIN"+_END = "UNSLOTH_PATCH_REPORT_END"++# Imports unsloth for real, then dumps what `_run_temporary_patches` recorded.+# The injection point is where a mutation control installs an extra patch and+# re-runs the pass, so the control travels the same code path as the gate.+_CHILD = """+import json+import unsloth # noqa: F401+import unsloth.models._utils as _utils++# `import unsloth` only runs the "init" pass. The other two run from+# unsloth_compile_transformers around the compiler, and a phase-aware patch+# branches on which one it is (patch_Gemma4_static_cache_backport and+# patch_gpt_oss_for_grpo both return immediately unless phase == post_compile),+# so a patch can be perfectly quiet at import and raise only in a compile pass.+# Running the two passes here executes those branches without standing up a+# model or a compiler. It is not the full production state -- post_compile+# normally runs after _unsloth_compile_transformers has swapped classes -- so+# this catches a patch that raises on its own terms, not one that only raises+# against a compiled model.+_utils._run_temporary_patches("pre_compile")+_utils._run_temporary_patches("post_compile")++{injection}++report = {{}}+for phase, outcome in _utils.TEMPORARY_PATCH_OUTCOMES.items():+ report[phase] = {{+ "completed": [getattr(p, "__name__", repr(p)) for p in outcome["completed"]],+ "raised": [+ [getattr(p, "__name__", repr(p)), type(e).__name__, str(e)]+ for p, e in outcome["raised"]+ ],+ }}+print({begin!r})+print(json.dumps(report))+print({end!r})+"""++_NO_ACCELERATOR = (+ "Unsloth cannot find any torch accelerator",+ "No CUDA GPUs are available",+ "Torch not compiled with CUDA enabled",+)+++def _spawn(code, **extra_env):+ path = [str(_ROOT)]+ if os.environ.get("PYTHONPATH"):+ path.append(os.environ["PYTHONPATH"])+ return subprocess.run(+ [sys.executable, "-c", code],+ capture_output = True,+ text = True,+ env = dict(os.environ, PYTHONPATH = os.pathsep.join(path), **extra_env),+ timeout = 1800,+ )+++def _collect(injection = ""):+ """The real import, in a fresh interpreter, reported as plain data.++ A host with no accelerator at all cannot finish `import unsloth` without+ `UNSLOTH_ALLOW_CPU=1`, and CI's CPU job is exactly that. Retrying on that+ one symptom rather than probing the host keeps this free of any assumption+ about which accelerator (or operating system) is present.+ """+ code = _CHILD.format(injection = injection, begin = _BEGIN, end = _END)+ result = _spawn(code)+ if result.returncode != 0 and any(m in result.stderr for m in _NO_ACCELERATOR):+ result = _spawn(code, UNSLOTH_ALLOW_CPU = "1")+ if result.returncode != 0 or _BEGIN not in result.stdout:+ raise AssertionError(+ "could not import unsloth to read the temporary patch outcomes\n"+ f"exit {result.returncode}\n--- stdout ---\n{result.stdout}\n"+ f"--- stderr ---\n{result.stderr}"+ )+ body = result.stdout.split(_BEGIN, 1)[1].split(_END, 1)[0]+ return json.loads(body)+++def _assert_no_patch_raised(report):+ """The gate. Fails naming every patch that raised, and with what."""+ failures = []+ for phase in sorted(report):+ for name, exception_type, message in report[phase]["raised"]:+ failures.append(f" {name} (phase {phase}): {exception_type}: {message}")+ assert not failures, (+ "PATCH COVERAGE LOST: these temporary patches raised and were swallowed by the "+ "fail-soft handler in _run_temporary_patches, so they are no longer applied. A "+ "patch that no longer has anything to patch on this library version must return "+ "cleanly, not raise.\n" + "\n".join(failures)+ )++[email protected](scope = "module")+def _clean_report():+ return _collect()+++# ------------------------------------------------------------------ the gate+++_PHASES = ("init", "pre_compile", "post_compile")+++def test_no_temporary_patch_raised_on_this_library_version(_clean_report):+ assert _clean_report, "no phase was recorded at all, the bookkeeping is not running"+ missing = [phase for phase in _PHASES if phase not in _clean_report]+ assert not missing, f"no outcome was recorded for {missing}"+ _assert_no_patch_raised(_clean_report)++[email protected]("phase", _PHASES)+def test_every_pass_actually_ran_some_patches(_clean_report, phase):+ # Guards the degenerate green: an empty TEMPORARY_PATCHES, or a pass that+ # was never driven, would satisfy the gate above without applying anything.+ # No upper or exact bound, and no names, so adding or removing a patch never+ # touches this file.+ assert _clean_report[phase][+ "completed"+ ], f"no temporary patch completed in the {phase} pass, so the gate above is vacuous there"+++# ------------------------------------------------- mutation controls+# The gate is only worth having if it is sensitive to a patch that breaks and+# insensitive to one that declines because this library version has nothing for+# it to patch. Both controls go through the real import and the real recording.+++_RAISES = """+def _mutation_control_patch_that_raises():+ # What patch_merge_quantization_configs did in #3130: a SyntaxError out of+ # an exec'd string, from inside a patch body.+ raise SyntaxError("mutation control: this patch is broken")++_utils.TEMPORARY_PATCHES.append(_mutation_control_patch_that_raises)+_utils._run_temporary_patches("init")+"""++_DECLINES = """+def _mutation_control_patch_that_declines(phase):+ # The shape of every version-conditional patch in unsloth_zoo: look for the+ # thing to patch, and return without touching anything when this library+ # version does not have it.+ try:+ import a_module_no_transformers_release_ships # noqa: F401+ except ImportError:+ return+ raise AssertionError("unreachable")++_utils.TEMPORARY_PATCHES.append(_mutation_control_patch_that_declines)+_utils._run_temporary_patches("init")+"""+++_RAISES_ONLY_AT_COMPILE_TIME = """+def _mutation_control_patch_quiet_until_compile(phase = "post_compile"):+ # The shape the import-only gate could not see: the same phase test the two+ # real phase-aware patches use, with a body that no longer works.+ if phase != "post_compile": return+ raise AttributeError("mutation control: this compile-time patch is broken")++_utils.TEMPORARY_PATCHES.append(_mutation_control_patch_quiet_until_compile)+_utils._run_temporary_patches("init")+_utils._run_temporary_patches("post_compile")+"""+++def test_mutation_control_a_patch_that_only_breaks_at_compile_time_turns_the_gate_red():+ report = _collect(injection = _RAISES_ONLY_AT_COMPILE_TIME)+ assert (+ "_mutation_control_patch_quiet_until_compile" in report["init"]["completed"]+ ), "the control has to be quiet during import, or it proves nothing about the compile passes"+ with pytest.raises(AssertionError) as caught:+ _assert_no_patch_raised(report)+ message = str(caught.value)+ assert "_mutation_control_patch_quiet_until_compile" in message, message+ assert "phase post_compile" in message, message+++def test_mutation_control_a_raising_patch_turns_the_gate_red():+ report = _collect(injection = _RAISES)+ with pytest.raises(AssertionError) as caught:+ _assert_no_patch_raised(report)+ message = str(caught.value)+ assert "_mutation_control_patch_that_raises" in message, message+ assert "SyntaxError" in message, message+++def test_mutation_control_a_cleanly_declining_patch_does_not():+ report = _collect(injection = _DECLINES)+ _assert_no_patch_raised(report)+ assert (+ "_mutation_control_patch_that_declines" in report["init"]["completed"]+ ), "a patch that declined cleanly was not recorded as completed"+++# ---------------------------------------------- the recording itself+# Fast, no import of unsloth: the function is loaded out of the file the way+# tests/test_import_time_floors.py does, so these run everywhere including a+# host that cannot import the model stack at all.+++class _CollectingLogger:+ def __init__(self):+ self.warnings = []++ def warning(self, message):+ self.warnings.append(message)+++def _isolated(patches, logger, outcomes):+ source = _UTILS.read_text(encoding = "utf-8")+ tree = ast.parse(source)+ for node in tree.body:+ if isinstance(node, ast.FunctionDef) and node.name == "_run_temporary_patches":+ segment = ast.get_source_segment(source, node)+ break+ else:+ raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")+ namespace = {+ "TEMPORARY_PATCHES": patches,+ "logger": logger,+ "TEMPORARY_PATCH_OUTCOMES": outcomes,+ }+ exec(compile(segment, str(_UTILS), "exec"), namespace)+ return namespace["_run_temporary_patches"]+++def test_outcomes_separate_raising_from_returning():+ def declines():+ return None++ def explodes():+ raise RuntimeError("boom")++ outcomes = {}+ logger = _CollectingLogger()+ _isolated([declines, explodes], logger, outcomes)("init")++ assert [p.__name__ for p in outcomes["init"]["completed"]] == ["declines"]+ assert [p.__name__ for p, _ in outcomes["init"]["raised"]] == ["explodes"]+ assert len(logger.warnings) == 1, "fail-soft logging must be unchanged"+++def test_outcomes_are_recorded_per_phase():+ def declines(phase):+ return None++ outcomes = {}+ run = _isolated([declines], _CollectingLogger(), outcomes)+ run("init")+ run("pre_compile")++ assert sorted(outcomes) == ["init", "pre_compile"]+++def test_a_repeated_pass_replaces_rather_than_grows_its_phase():+ # `_run_temporary_patches` runs again on every model load, so an appending+ # record would be a leak in a long-lived process.+ def declines():+ return None++ outcomes = {}+ run = _isolated([declines], _CollectingLogger(), outcomes)+ for _ in range(5):+ run("pre_compile")++ assert len(outcomes["pre_compile"]["completed"]) == 1+++def test_a_recorded_failure_does_not_pin_the_frames_it_raised_from():+ # The count check above uses a patch that returns cleanly, which is the+ # cheap half of the question. The half that can cost memory is a patch that+ # RAISES: `raised` stores the exception object, an exception carries its+ # __traceback__, and a traceback keeps every frame in it and every local in+ # those frames alive. Measured before the trim went in: the raising frame's+ # local stayed reachable for as long as the phase entry lived, and the+ # "init" entry is written once per process and never replaced, so an+ # import-time failure pinned them until the process ended.+ class _Held:+ pass++ probes = []++ def explodes():+ heavy = _Held()+ # A weak reference, so the probe itself is not what keeps `heavy` alive.+ probes.append(weakref.ref(heavy))+ raise RuntimeError("boom")++ outcomes = {}+ run = _isolated([explodes], _CollectingLogger(), outcomes)+ run("init")++ patch, exception = outcomes["init"]["raised"][0]+ assert patch is explodes+ assert isinstance(exception, RuntimeError), "the exception itself must still be recorded"+ assert str(exception) == "boom", "the message the gate reports must survive the trim"+ assert exception.__traceback__ is None, (+ "the recorded exception still carries its traceback, which keeps the failed patch's "+ "frames and their locals alive for the lifetime of the phase entry"+ )++ # And the frame's local really is gone, not merely unreachable through the+ # attribute that was cleared.+ gc.collect()+ assert probes[0]() is None, (+ "an object local to the failed patch is still alive after the pass, so the record "+ "is pinning the raising frame"+ )+++def test_an_exception_that_refuses_the_trim_does_not_break_the_pass():+ # __traceback__, __context__ and __cause__ are ordinary settable attributes,+ # and a subclass can shadow them with a property that refuses the write.+ # This loop runs inside `import unsloth`, so the trim must never be the thing+ # that ends the import.+ class _Stubborn(Exception):+ @property+ def __traceback__(self):+ return None++ @__traceback__.setter+ def __traceback__(self, value):+ raise ValueError("this exception will not give up its traceback")++ def explodes():+ raise _Stubborn("boom")++ def runs_after():+ return None++ outcomes = {}+ logger = _CollectingLogger()+ _isolated([explodes, runs_after], logger, outcomes)("init")++ assert [p.__name__ for p, _ in outcomes["init"]["raised"]] == ["explodes"]+ assert [p.__name__ for p in outcomes["init"]["completed"]] == ["runs_after"]+ assert len(logger.warnings) == 1+++def test_an_unnamed_callable_does_not_break_the_recording():+ # The success path stores the callable itself and formats nothing, so a+ # callable with no __name__ cannot make the bookkeeping raise inside+ # `import unsloth`.+ class _Callable:+ def __call__(self):+ return None++ outcomes = {}+ logger = _CollectingLogger()+ _isolated([_Callable()], logger, outcomes)("init")++ assert len(outcomes["init"]["completed"]) == 1+ assert logger.warnings == []+++def test_the_recording_is_wired_into_the_patch_loop():+ # DRIFT: the gate is only as good as its wiring, and a refactor that drops+ # these lines would leave every test above green while recording nothing.+ source = _UTILS.read_text(encoding = "utf-8")+ tree = ast.parse(source)+ for node in tree.body:+ if isinstance(node, ast.FunctionDef) and node.name == "_run_temporary_patches":+ segment = ast.get_source_segment(source, node)+ break+ else:+ raise AssertionError("_run_temporary_patches is gone from unsloth/models/_utils.py")++ assert "TEMPORARY_PATCH_OUTCOMES[phase]" in segment+ assert "raised.append(" in segment+ assert "completed.append(" in segment+ assert (+ "TEMPORARY_PATCH_OUTCOMES = {}" in source+ ), "the module level record the gate reads is gone"diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.pyindex 1484ec5429a..9df944f352a 100644--- a/unsloth/models/_utils.py+++ b/unsloth/models/_utils.py@@ -911,8 +911,28 @@ def resolve_encoder_attention_implementation(return None+# Outcome of the most recent `_run_temporary_patches` pass, keyed by phase, as+# {"completed": [patch, ...], "raised": [(patch, exception), ...]}. A temporary+# patch that raises is warned about rather than propagated, so without this a+# whole patch silently dropping out leaves CI green; the regression gate in+# tests/test_temporary_patch_coverage.py reads it and fails on a non-empty+# "raised" bucket. Which patches legitimately decline depends on the installed+# transformers/TRL/PEFT, so only "raised" is a defect, never the membership of+# "completed".+TEMPORARY_PATCH_OUTCOMES = {}++def _run_temporary_patches(phase):import inspect++ # Bookkeeping is one list append per patch, storing the callables as they+ # are so nothing is formatted on the success path, and the per-phase entry+ # is replaced rather than extended so repeated model loads cannot grow it.+ # Nothing here can raise, which matters because this loop runs inside+ # `import unsloth`.+ completed = []+ raised = []+ TEMPORARY_PATCH_OUTCOMES[phase] = {"completed": completed, "raised": raised}for temporary_patch in TEMPORARY_PATCHES:# Two separate questions, kept separate. inspect.signature raises# ValueError or TypeError for a callable whose signature it cannot read,@@ -933,12 +953,34 @@ def _run_temporary_patches(phase):else:temporary_patch()except Exception as exception:+ # Keep the exception, drop what it drags along. An exception holds+ # its __traceback__, and a traceback holds every frame in it and+ # every local in those frames; __context__ and __cause__ chain to+ # more of the same. The "init" entry is written once per process and+ # never replaced, so recording a failure as-is would pin the failed+ # patch's frames for the lifetime of the process. Nothing reads them+ # (the gate and the warning below both use only the type and the+ # message), so this loses no diagnosis and bounds the record to the+ # exception objects themselves.+ # Guarded because these three are ordinary settable attributes and a+ # subclass can shadow them with a property that refuses the write+ # (measured: a ValueError out of a __traceback__ setter). Losing the+ # trim is fine; losing the import over bookkeeping is not.+ try:+ exception.__traceback__ = None+ exception.__context__ = None+ exception.__cause__ = None+ except Exception:+ pass+ raised.append((temporary_patch, exception))logger.warning(f"Unsloth: temporary patch "f"{getattr(temporary_patch, '__name__', temporary_patch)} failed in "f"phase {phase} and was skipped. "f"({type(exception).__name__}: {exception})")+ else:+ completed.append(temporary_patch)_run_temporary_patches("init")