Skip to content

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.

Keep the RoPE base frequency on transformers 5, and make triton optional (#11037)

Daniel Han65facffde3ee
diff --git a/.github/actions/core-cpu-setup/action.yml b/.github/actions/core-cpu-setup/action.yml
index 799cfb1e3a1..4460d1b7cf0 100644
--- a/.github/actions/core-cpu-setup/action.yml
+++ b/.github/actions/core-cpu-setup/action.yml
@@ -136,10 +136,10 @@ runs:
# does `from transformers.utils import sentencepiece_model_pb2`,
# which imports `google.protobuf`. Not pulled by transformers'
# base install.
- # - triton: unsloth/_gpu_init.py:232 does an unconditional
- # `import triton`. The triton PyPI wheel installs cleanly on
- # Linux x86_64 even without CUDA (the import succeeds; runtime
- # GPU work is what would fail, which we never do here).
+ # - triton: unsloth/kernels and unsloth_zoo's compiler and loss_utils
+ # import it at module scope, so `import unsloth` needs it even though
+ # _gpu_init.py treats it as optional. The PyPI wheel imports fine on
+ # Linux x86_64 without CUDA; only runtime GPU work would fail.
# transformers + trl are matrix-parameterized.
shell: bash
run: |
diff --git a/.github/workflows/consolidated-tests-ci.yml b/.github/workflows/consolidated-tests-ci.yml
index 222880c957f..d78ee60aadf 100644
--- a/.github/workflows/consolidated-tests-ci.yml
+++ b/.github/workflows/consolidated-tests-ci.yml
@@ -335,6 +335,14 @@ jobs:
run: |
python -m pytest -v --tb=short tests/test_import_fixes_drift.py
+ - name: triton-absent import guard (HARD GATE)
+ # PyPI ships no Windows `triton` wheel, so the unconditional module-level import
+ # in _gpu_init.py killed `import unsloth` on a CPU-only Windows install. Named
+ # here because nothing else in the repo collects this file, so a deleted guard
+ # would leave CI green.
+ run: |
+ python -m pytest -v --tb=short tests/test_triton_optional_import.py
+
- name: public-api surface drift detectors (9 tests, HARD GATE)
# Companion to test_import_fixes_drift.py: that file catches
# third-party drift; this one catches drift in unsloth's OWN
diff --git a/.github/workflows/notebooks-ci.yml b/.github/workflows/notebooks-ci.yml
index 9072e2057c2..1d1f9fb1738 100644
--- a/.github/workflows/notebooks-ci.yml
+++ b/.github/workflows/notebooks-ci.yml
@@ -337,10 +337,10 @@ jobs:
# Pin to the same versions update_all_notebooks.py installs in
# generated notebooks. Keep these in lockstep with PIN_TRL /
# PIN_TRANSFORMERS in unslothai/notebooks/update_all_notebooks.py.
- # `triton` is added because unsloth/_gpu_init.py:232 does an
- # unconditional `import triton`; the PyPI wheel installs cleanly
- # on Linux x86_64 even without CUDA (same rationale as
- # consolidated-tests-ci.yml line 192-205).
+ # `triton` because unsloth/kernels and unsloth_zoo's compiler and
+ # loss_utils import it at module scope, so `import unsloth` needs it
+ # even though _gpu_init.py treats it as optional. Same rationale as
+ # consolidated-tests-ci.yml line 192-205.
# Pillow is listed explicitly as a defensive belt-and-braces
# next to torchvision (vision_utils crashes ModuleNotFoundError
# if torchvision skipped its Pillow dep for any reason).
diff --git a/.github/workflows/workflow-trigger-lint.yml b/.github/workflows/workflow-trigger-lint.yml
index d68bbd30201..614bc653b00 100644
--- a/.github/workflows/workflow-trigger-lint.yml
+++ b/.github/workflows/workflow-trigger-lint.yml
@@ -237,12 +237,10 @@ jobs:
# `unsloth/__init__.py`, and that raises ImportError outright when the zoo
# distribution is absent - `UNSLOTH_ZOO_DISABLE_GPU_INIT` does not bypass it.
# Without this the job would fail during collection rather than run.
- # Triton as well. `unsloth/_gpu_init.py` imports it unconditionally, and the
- # CPU torch wheel does not supply it - only the CUDA wheels pull
- # pytorch-triton in. `UNSLOTH_ALLOW_CPU=1` bypasses device probing, not that
- # import, so without this the job fails during collection and none of the
- # four suites run. `consolidated-tests-ci.yml` installs it for the same
- # reason on the same kind of runner.
+ # Triton as well: unsloth/kernels and unsloth_zoo's compiler and loss_utils
+ # import it at module scope and the CPU torch wheel does not supply it.
+ # `UNSLOTH_ALLOW_CPU=1` bypasses device probing, not those imports, so without
+ # this the job fails during collection.
python -m pip install --quiet transformers peft pytest unsloth-zoo triton
# Named one by one, not as a directory. The point of this job is those three
diff --git a/tests/test_import_fixes_drift.py b/tests/test_import_fixes_drift.py
index d8cde86537f..63b7de6981d 100644
--- a/tests/test_import_fixes_drift.py
+++ b/tests/test_import_fixes_drift.py
@@ -1037,3 +1037,363 @@ def test_torchao_intmm_patch_wired_into_gpu_init():
"DRIFT DETECTED: fix_torchao_safe_int_mm_repr_probe is left bound on the unsloth "
"namespace; _gpu_init.py deletes every fix it calls."
)
+
+
+# ===========================================================================
+# transformers -- a replaced rope_scaling drops the RoPE base frequency
+# ===========================================================================
+
+
+def test_rope_scaling_replacement_keeps_the_base_frequency():
+ """The pathology: transformers 5 moved ``rope_theta`` inside
+ ``config.rope_parameters`` while keeping ``rope_scaling`` as an alias that replaces
+ that whole dict, so assigning a normalized scaling dict leaves the base ``None``.
+ Asked of the live build after the fix has run, so this fails whenever the fix
+ stopped neutralising it, and passes on 4.57.6 where there is nothing to neutralise.
+ """
+ pytest.importorskip("transformers")
+ from unsloth.import_fixes import (
+ _rope_scaling_property_owner,
+ _rope_scaling_setter_is_patched,
+ _transformers_rope_scaling_assignment_drops_theta,
+ fix_transformers_rope_scaling_drops_theta,
+ )
+
+ owner = _rope_scaling_property_owner()
+ # Already installed by `import unsloth`; calling it again must be a no-op.
+ fix_transformers_rope_scaling_drops_theta()
+ assert not _transformers_rope_scaling_assignment_drops_theta(), (
+ "DRIFT DETECTED: replacing config.rope_scaling still loses the RoPE base "
+ "frequency, so the object-style delegation retry in models/llama.py falls back "
+ "to unscaled RoPE (issue #2405)."
+ )
+ if owner is None:
+ # transformers 4.x: rope_scaling is a plain attribute an assignment cannot
+ # clobber, so there must be nothing installed.
+ assert not _rope_scaling_setter_is_patched(owner), (
+ "the rope_scaling setter is reported patched on a build that has no "
+ "rope_scaling property to patch"
+ )
+ elif not _rope_scaling_setter_is_patched(owner):
+ # Healthy, not drift: the fix installs nothing when the probe finds no loss, so a
+ # transformers that keeps the alias and fixes the base lands here. Requiring the
+ # wrapper would fail this hard gate on the release that makes it unnecessary.
+ assert not _transformers_rope_scaling_assignment_drops_theta()
+
+
+def test_rope_scaling_setter_patch_is_idempotent():
+ """Calling the fix twice must not stack a wrapper on a wrapper."""
+ pytest.importorskip("transformers")
+ from unsloth.import_fixes import (
+ _ROPE_SCALING_PATCH_FLAG,
+ _rope_scaling_property_owner,
+ _rope_scaling_setter_is_patched,
+ fix_transformers_rope_scaling_drops_theta,
+ )
+
+ owner = _rope_scaling_property_owner()
+ fix_transformers_rope_scaling_drops_theta()
+ if owner is None:
+ assert (
+ _rope_scaling_property_owner() is None
+ ), "the fix created a rope_scaling property on a build that had none"
+ return
+ if not _rope_scaling_setter_is_patched(owner):
+ # Same healthy case as above: no wrapper was installed, so there is no stacking
+ # to check. Idempotence of a no-op is that it stays a no-op.
+ fix_transformers_rope_scaling_drops_theta()
+ assert not _rope_scaling_setter_is_patched(owner)
+ return
+ before = owner.__dict__["rope_scaling"]
+ fix_transformers_rope_scaling_drops_theta()
+ after = owner.__dict__["rope_scaling"]
+ assert after is before, "DRIFT DETECTED: the rope_scaling property was replaced twice."
+ inner = getattr(after.fset, "__wrapped__", None)
+ assert inner is not None, "the patched setter must keep the original reachable"
+ assert not getattr(
+ inner, _ROPE_SCALING_PATCH_FLAG, False
+ ), "DRIFT DETECTED: the rope_scaling setter is wrapped twice."
+
+
+def test_rope_theta_carry_only_writes_when_the_base_would_be_lost():
+ """The carry helper, on every shape the parameters can arrive as.
+
+ Cases three to five are the fix, case one is what keeps it self-neutralising on a
+ transformers that keeps the base itself, and the last two are the shapes a naive
+ carry would damage: a per-layer rope dict, and the Gemma local rotary, where a base
+ the caller stated on purpose must survive untouched.
+ """
+ from types import SimpleNamespace
+
+ from unsloth.import_fixes import _carry_rope_theta_across_assignment as carry
+
+ # 1. The new parameters name their own base: write nothing at all.
+ parameters = {"rope_type": "linear", "factor": 4.0, "rope_theta": 1000000.0}
+ config = SimpleNamespace(rope_parameters = parameters)
+ assert carry(config, 500000.0) == 1000000.0
+ assert not hasattr(config, "rope_theta")
+ assert parameters == {"rope_type": "linear", "factor": 4.0, "rope_theta": 1000000.0}
+
+ # 2. An attribute that is already there is kept in step, never left stale.
+ config = SimpleNamespace(
+ rope_parameters = {"rope_type": "linear", "factor": 4.0, "rope_theta": 1000000.0},
+ rope_theta = 500000.0,
+ )
+ assert carry(config, 500000.0) == 1000000.0
+ assert config.rope_theta == 1000000.0
+
+ # 3. The base would be lost: restore it inside rope_parameters, through a COPY, and
+ # leave the config without a top-level attribute it never had.
+ parameters = {"rope_type": "linear", "factor": 4.0}
+ config = SimpleNamespace(rope_parameters = parameters)
+ assert carry(config, 500000.0) == 500000.0
+ assert config.rope_parameters["rope_theta"] == 500000.0
+ assert parameters == {"rope_type": "linear", "factor": 4.0}
+ assert not hasattr(config, "rope_theta")
+
+ # 4. Object-style replacement, #2405's own shape: no dict to write into, so the
+ # attribute is the only thing that carries the base to the retry.
+ config = SimpleNamespace(rope_parameters = object())
+ assert carry(config, 500000.0) == 500000.0
+ assert config.rope_theta == 500000.0
+
+ # 5. The retry: a dict again, and the base case 4 wrote lands back inside it.
+ parameters = {"rope_type": "linear", "factor": 4.0}
+ config = SimpleNamespace(rope_parameters = parameters, rope_theta = 500000.0)
+ assert carry(config, None) == 500000.0
+ assert config.rope_parameters["rope_theta"] == 500000.0
+ assert parameters == {"rope_type": "linear", "factor": 4.0}
+
+ # 6. The caller's dict is never written to: transformers 5 stores it verbatim, so
+ # one scaling dict reused across two configs would carry the first base into the
+ # second, silently wrong rather than an error.
+ shared = {"rope_type": "linear", "factor": 4.0}
+ first = SimpleNamespace(rope_parameters = shared)
+ assert carry(first, 500000.0) == 500000.0
+ assert shared == {"rope_type": "linear", "factor": 4.0}, shared
+ second = SimpleNamespace(rope_parameters = shared, rope_theta = 10000.0)
+ assert carry(second, None) == 10000.0
+ assert second.rope_parameters["rope_theta"] == 10000.0
+ assert first.rope_parameters["rope_theta"] == 500000.0
+
+ # 7. Nothing to carry and nothing stated: untouched.
+ parameters = {"rope_type": "linear", "factor": 4.0}
+ config = SimpleNamespace(rope_parameters = parameters)
+ assert carry(config, None) is None
+ assert not hasattr(config, "rope_theta")
+ assert "rope_theta" not in parameters
+
+ # 8. Per-layer parameters: the base belongs one level down, so the top-level dict
+ # must not gain a key or transformers reads the whole thing as flat.
+ parameters = {
+ "full_attention": {"rope_type": "linear", "factor": 4.0},
+ "sliding_attention": {"rope_type": "default"},
+ }
+ config = SimpleNamespace(
+ rope_parameters = parameters,
+ layer_types = ["full_attention", "sliding_attention"],
+ )
+ assert carry(config, 500000.0) == 500000.0
+ assert set(parameters) == {"full_attention", "sliding_attention"}
+ assert config.rope_theta == 500000.0, (
+ "a per-layer dict has no global slot, so the attribute is where the base "
+ "standardize_rope_params hands to each layer type has to live"
+ )
+
+ # 8. unsloth_zoo/empty_model.py's Gemma local rotary: rope_theta is set to the
+ # LOCAL base on purpose, then the scaling is replaced. Carrying the global base
+ # over it would give the local rotary the wrong base.
+ parameters = {"rope_type": "default"}
+ config = SimpleNamespace(rope_parameters = parameters, rope_theta = 10000.0)
+ assert carry(config, 1000000.0) == 10000.0
+ assert (
+ config.rope_theta == 10000.0
+ ), "the carry overwrote a base frequency the caller set deliberately"
+ assert config.rope_parameters["rope_theta"] == 10000.0
+ assert parameters == {"rope_type": "default"}
+
+
+def test_rope_scaling_patch_wired_into_gpu_init():
+ source = Path(__file__).resolve().parent.parent / "unsloth" / "_gpu_init.py"
+ source = source.read_text(encoding = "utf-8")
+ assert "fix_transformers_rope_scaling_drops_theta()" in source, (
+ "DRIFT DETECTED: fix_transformers_rope_scaling_drops_theta is defined but never "
+ "called in _gpu_init.py, so real imports never install it."
+ )
+ assert "del fix_transformers_rope_scaling_drops_theta" in source, (
+ "DRIFT DETECTED: fix_transformers_rope_scaling_drops_theta is left bound on the "
+ "unsloth namespace; _gpu_init.py deletes every fix it calls."
+ )
+
+
+def test_a_reloaded_configuration_module_gets_the_new_base_class_patched():
+ """A reload replaces the owner underneath the cached config the probe measures.
+
+ `importlib.reload(transformers.configuration_utils)` re-runs the class body and
+ produces a NEW, unpatched base class, while `transformers.LlamaConfig` stays in
+ `sys.modules` with its old bases -- including the class we patched. The probe therefore
+ reported the base frequency survives, the fix returned early, and the new base class
+ stayed unpatched for every config module imported afterwards.
+ """
+ pytest.importorskip("transformers")
+ from unsloth.import_fixes import (
+ _rope_probe_inherits,
+ _rope_scaling_property_owner,
+ )
+
+ owner = _rope_scaling_property_owner()
+ if owner is None:
+ pytest.skip("this transformers has no rope_scaling alias property to own")
+
+ # On an ordinary build the probe measures a descendant of the live owner, so nothing
+ # about the normal path changes.
+ assert _rope_probe_inherits(owner) is True
+
+ # A stand-in for the post-reload owner: a class the cached LlamaConfig does not
+ # descend from. The probe's verdict cannot speak for it, so it must not veto.
+ replacement = type("_ReloadedConfigBase", (object,), {})
+ assert _rope_probe_inherits(replacement) is False
+
+
+def test_the_reload_check_rejects_a_non_class_owner():
+ """NEGATIVE CONTROL: the helper answers about classes, and anything else is 'no
+ evidence' rather than an exception out of `issubclass`."""
+ pytest.importorskip("transformers")
+ from unsloth.import_fixes import _rope_probe_inherits
+
+ for not_a_class in (None, object(), "PreTrainedConfig", 7):
+ assert _rope_probe_inherits(not_a_class) is False
+
+
+def test_rope_theta_carry_restores_each_layer_types_own_base():
+ """Per-layer parameters hold one base PER LAYER TYPE, and a single scalar cannot
+ describe them.
+
+ transformers 5.5's T5Gemma2DecoderConfig starts at 10000.0 for sliding attention and
+ 1000000.0 for full attention. Reading `parameters["rope_theta"]` off the OUTER dict
+ finds nothing, so the snapshot was None, the carry declined, and a later
+ standardize_rope_params filled both nested bases with None: invalid RoPE
+ initialisation with nothing raised.
+ """
+ from types import SimpleNamespace
+
+ from unsloth.import_fixes import (
+ _carry_rope_theta_across_assignment as carry,
+ _rope_theta_snapshot,
+ )
+
+ before = SimpleNamespace(
+ rope_parameters = {
+ "sliding_attention": {"rope_type": "default", "rope_theta": 10000.0},
+ "full_attention": {"rope_type": "default", "rope_theta": 1000000.0},
+ },
+ layer_types = ["sliding_attention", "full_attention"],
+ )
+ carried = _rope_theta_snapshot(before)
+ assert carried == {"sliding_attention": 10000.0, "full_attention": 1000000.0}
+
+ # The replacement a caller assigns: per-layer scaling with no bases in it.
+ replacement = {
+ "sliding_attention": {"rope_type": "linear", "factor": 4.0},
+ "full_attention": {"rope_type": "linear", "factor": 4.0},
+ }
+ config = SimpleNamespace(
+ rope_parameters = replacement,
+ layer_types = ["sliding_attention", "full_attention"],
+ )
+ assert carry(config, carried) == carried
+
+ assert config.rope_parameters["sliding_attention"]["rope_theta"] == 10000.0
+ assert config.rope_parameters["full_attention"]["rope_theta"] == 1000000.0
+ # No global key: it would make standardize_rope_params read the whole dict as flat.
+ assert "rope_theta" not in config.rope_parameters
+ assert not hasattr(config, "rope_theta")
+ # The caller's dicts are never written to, inner ones included.
+ assert replacement["sliding_attention"] == {"rope_type": "linear", "factor": 4.0}
+ assert replacement["full_attention"] == {"rope_type": "linear", "factor": 4.0}
+
+
+def test_rope_theta_carry_leaves_a_per_layer_base_the_caller_stated():
+ """NEGATIVE CONTROL: an entry that names its own base is a deliberate statement and
+ must survive, exactly as the flat path leaves a stated base alone."""
+ from types import SimpleNamespace
+
+ from unsloth.import_fixes import _carry_rope_theta_across_assignment as carry
+
+ config = SimpleNamespace(
+ rope_parameters = {
+ "sliding_attention": {"rope_type": "linear", "rope_theta": 50.0},
+ "full_attention": {"rope_type": "linear"},
+ },
+ layer_types = ["sliding_attention", "full_attention"],
+ )
+ carry(config, {"sliding_attention": 10000.0, "full_attention": 1000000.0})
+
+ assert config.rope_parameters["sliding_attention"]["rope_theta"] == 50.0
+ assert config.rope_parameters["full_attention"]["rope_theta"] == 1000000.0
+
+
+def test_rope_theta_snapshot_still_reads_a_flat_base():
+ """The control that the snapshot did not change the ordinary shape: a flat dict has
+ one base and the snapshot is that scalar, which is what every other case expects."""
+ from types import SimpleNamespace
+
+ from unsloth.import_fixes import _rope_theta_snapshot
+
+ assert (
+ _rope_theta_snapshot(
+ SimpleNamespace(rope_parameters = {"rope_type": "linear", "rope_theta": 500000.0})
+ )
+ == 500000.0
+ )
+ assert _rope_theta_snapshot(SimpleNamespace(rope_parameters = {"rope_type": "linear"})) is None
+ assert _rope_theta_snapshot(SimpleNamespace(rope_parameters = object())) is None
+ assert _rope_theta_snapshot(SimpleNamespace()) is None
+ # Per-layer with no bases anywhere is None, not an empty dict, so the global
+ # attribute path below it still runs.
+ assert (
+ _rope_theta_snapshot(
+ SimpleNamespace(
+ rope_parameters = {"full_attention": {"rope_type": "linear"}},
+ layer_types = ["full_attention"],
+ )
+ )
+ is None
+ )
+
+
+def test_a_per_layer_snapshot_never_becomes_a_scalar_rope_theta():
+ """Per-layer parameters replaced by a FLAT dict.
+
+ The snapshot is a {layer_type: base} mapping and every slot below the per-layer branch
+ holds a number, so passing the mapping through wrote a dict into
+ `rope_parameters["rope_theta"]` and the first RoPE arithmetic on it would raise. One
+ base can stand for the mapping only when every layer type agreed on it.
+ """
+ from types import SimpleNamespace
+
+ from unsloth.import_fixes import _carry_rope_theta_across_assignment as carry
+
+ # Disagreeing bases: there is no scalar that is true, so nothing is carried.
+ flat = {"rope_type": "linear", "factor": 4.0}
+ config = SimpleNamespace(rope_parameters = flat)
+ assert carry(config, {"sliding_attention": 10000.0, "full_attention": 1000000.0}) is None
+ assert config.rope_parameters == {"rope_type": "linear", "factor": 4.0}
+ assert not hasattr(config, "rope_theta")
+
+ # Agreeing bases: the one they agree on is a true answer, so it is carried as a number.
+ config = SimpleNamespace(rope_parameters = {"rope_type": "linear", "factor": 4.0})
+ assert carry(config, {"sliding_attention": 10000.0, "full_attention": 10000.0}) == 10000.0
+ assert config.rope_parameters["rope_theta"] == 10000.0
+
+ # And whatever is carried, it is never a dict.
+ for snapshot in (
+ {"a": 1.0, "b": 2.0},
+ {"a": 10000.0, "b": 10000.0},
+ {},
+ ):
+ config = SimpleNamespace(rope_parameters = {"rope_type": "linear"})
+ carry(config, snapshot)
+ written = config.rope_parameters.get("rope_theta", None)
+ assert not isinstance(written, dict), written
+ assert not isinstance(getattr(config, "rope_theta", None), dict)
diff --git a/tests/test_triton_optional_import.py b/tests/test_triton_optional_import.py
new file mode 100644
index 00000000000..2248fc8fc30
--- /dev/null
+++ b/tests/test_triton_optional_import.py
@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""A missing `triton` must not stop `unsloth/_gpu_init.py`.
+
+The PyPI `triton` project publishes no Windows wheel (Windows is served by the separate
+`triton-windows` package), so a CPU only Windows install has no `triton` at all. The
+module level `import triton` in `unsloth/_gpu_init.py` was unconditional, so `import
+unsloth` there died with a bare `ModuleNotFoundError: No module named 'triton'` from a
+line that only exists to resolve `libcuda_dirs` on CUDA hosts.
+
+The absent module is simulated with `sys.modules["triton"] = None`, which is what the
+import system already uses to mean "blocked": `import triton` then raises `ImportError`
+without touching the filesystem, and it blocks `triton.*` submodules too.
+"""
+
+from __future__ import annotations
+
+import ast
+import functools
+import os
+import pathlib
+import subprocess
+import sys
+import textwrap
+
+import pytest
+
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[1]
+GPU_INIT = REPO_ROOT / "unsloth" / "_gpu_init.py"
+GPU_INIT_NAME = os.path.join("unsloth", "_gpu_init.py")
+
+
+def _run(code: str) -> subprocess.CompletedProcess:
+ """Run `code` in a fresh interpreter so no module state leaks between cases."""
+ path = [str(REPO_ROOT)]
+ if os.environ.get("PYTHONPATH"):
+ path.append(os.environ["PYTHONPATH"])
+ return subprocess.run(
+ [sys.executable, "-c", textwrap.dedent(code)],
+ capture_output = True,
+ text = True,
+ env = dict(os.environ, PYTHONPATH = os.pathsep.join(path)),
+ timeout = 1800,
+ )
+
+
+_IMPORT_WITHOUT_TRITON = """
+ import sys, traceback
+ for name in [key for key in sys.modules if key == "triton" or key.startswith("triton.")]:
+ del sys.modules[name]
+ sys.modules["triton"] = None # the import system's own "blocked" marker
+ frames = []
+ try:
+ import unsloth
+ except BaseException as error:
+ traceback.print_exc()
+ frames = traceback.extract_tb(error.__traceback__)
+ # Every frame that is itself an `import triton` statement, i.e. every place that
+ # still treats Triton as mandatory on the `import unsloth` path.
+ for frame in frames:
+ if frame.line and "import triton" in frame.line:
+ print("TRITON_FRAME", frame.filename, frame.lineno)
+ print("INNERMOST", frames[-1].filename, frames[-1].lineno)
+ print("UNSLOTH_IMPORT_FAILED")
+ else:
+ print("UNSLOTH_IMPORT_OK")
+ # Did unsloth/_gpu_init.py run at all? Apple Silicon takes the MLX path and never
+ # executes it, so the message this file checks for is not emitted there. A failed
+ # import drops the module from sys.modules again, so the traceback counts too.
+ ran = ("unsloth._gpu_init" in sys.modules) or any(
+ "_gpu_init.py" in frame.filename for frame in frames
+ )
+ print("GPU_INIT_RAN", ran)
+"""
+
+
+def _import_without_triton() -> subprocess.CompletedProcess:
+ return _run(_IMPORT_WITHOUT_TRITON)
+
+
+def _unsloth_is_importable() -> bool:
+ return _run("import unsloth").returncode == 0
+
+
+def _needs_unsloth():
+ if not _unsloth_is_importable():
+ pytest.skip("unsloth is not importable in this environment")
+
+
+def _module_level_triton_imports(tree: ast.Module) -> list[ast.Import]:
+ """Every module level `import triton` that is not inside a `try`."""
+ found = []
+ for node in tree.body:
+ if isinstance(node, ast.Import) and any(alias.name == "triton" for alias in node.names):
+ found.append(node)
+ return found
+
+
+def test_the_module_level_triton_import_is_inside_a_try():
+ """Structure, so the guard cannot be removed silently.
+
+ The bare statement at module scope is the defect: nothing below it can recover,
+ because the exception escapes `unsloth/__init__.py` itself.
+ """
+ tree = ast.parse(GPU_INIT.read_text(encoding = "utf-8"))
+ bare = _module_level_triton_imports(tree)
+ assert not bare, (
+ "unsloth/_gpu_init.py imports triton unguarded at module scope on line(s) "
+ f"{[node.lineno for node in bare]}; PyPI triton has no Windows wheel, so this "
+ "raises ModuleNotFoundError on a CPU only Windows install"
+ )
+ guarded = [
+ node
+ for handler in ast.walk(tree)
+ if isinstance(handler, ast.Try)
+ for node in handler.body
+ if isinstance(node, ast.Import) and any(alias.name == "triton" for alias in node.names)
+ ]
+ assert guarded, "the guarded `import triton` is gone"
+
+
+def test_the_guard_binds_triton_to_none_and_records_why():
+ """`triton` and `TRITON_IMPORT_ERROR` are the contract the rest of the file reads."""
+ source = GPU_INIT.read_text(encoding = "utf-8")
+ assert "TRITON_IMPORT_ERROR" in source
+ # Every later use of `triton` in this module has to tolerate None.
+ tree = ast.parse(source)
+ version_calls = [
+ node
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Attribute)
+ and node.attr == "__version__"
+ and isinstance(node.value, ast.Name)
+ and node.value.id == "triton"
+ ]
+ assert version_calls, "triton.__version__ is no longer read, update this test"
+
+
+def test_a_missing_triton_does_not_fail_in_gpu_init():
+ """The behaviour: with triton blocked, nothing raises from `unsloth/_gpu_init.py`.
+
+ This does not assert that `import unsloth` completes. The Triton kernel modules
+ under `unsloth/kernels` and the zoo's compiler import Triton for their own reasons,
+ so the import can still stop further down; what must no longer happen is stopping
+ here, on a line whose only job is CUDA library resolution.
+ """
+ _needs_unsloth()
+ result = _import_without_triton()
+ combined = result.stdout + result.stderr
+ triton_frames = [line for line in combined.splitlines() if line.startswith("TRITON_FRAME ")]
+ offending = [line for line in triton_frames if GPU_INIT_NAME in line]
+ assert not offending, (
+ "importing unsloth without triton still raises at the `import triton` in "
+ "_gpu_init.py:\n" + "\n".join(offending) + "\n\nfull output:\n" + combined[-4000:]
+ )
+ innermost = [line for line in combined.splitlines() if line.startswith("INNERMOST ")]
+ assert GPU_INIT_NAME not in "".join(innermost), (
+ "the import still dies inside _gpu_init.py:\n" + "\n".join(innermost)
+ )
+
+
+def test_a_missing_triton_is_reported_in_words():
+ """A user on Windows has to be told which package to install."""
+ _needs_unsloth()
+ result = _import_without_triton()
+ combined = (result.stdout + result.stderr).lower()
+ if "gpu_init_ran true" not in combined:
+ pytest.skip(
+ "unsloth/_gpu_init.py does not run on this platform (Apple Silicon takes the MLX "
+ "path), so the guard that emits this message never executes"
+ )
+ assert "triton" in combined
+ assert "triton-windows" in combined, (
+ "the message must name the package that provides Triton on Windows:\n" + combined[-4000:]
+ )
+
+
+def test_an_installed_triton_is_left_alone():
+ """No behaviour change where triton imports: the module stays bound, no error recorded."""
+ _needs_unsloth()
+ probe = _run(
+ """
+ try:
+ import triton # noqa: F401
+ except Exception:
+ print("NO_TRITON")
+ else:
+ import unsloth # noqa: F401
+ from unsloth import _gpu_init
+ print("BOUND", _gpu_init.triton is not None, _gpu_init.TRITON_IMPORT_ERROR)
+ """
+ )
+ combined = probe.stdout + probe.stderr
+ if "NO_TRITON" in combined:
+ pytest.skip("triton is not installed in this environment")
+ assert probe.returncode == 0, combined[-4000:]
+ assert "BOUND True None" in combined, combined[-4000:]
diff --git a/tests/utils/test_rope_scaling_drift.py b/tests/utils/test_rope_scaling_drift.py
index 4a97c77e13d..7c45909bd66 100644
--- a/tests/utils/test_rope_scaling_drift.py
+++ b/tests/utils/test_rope_scaling_drift.py
@@ -542,3 +542,70 @@ def test_object_style_rope_scaling_on_config_delegates_correctly():
"(issue #2405)."
)
assert torch.allclose(inv_freq.float().cpu(), expected, rtol = 1e-4, atol = 1e-6)
+
+
+def _linear_inv_freq(base, factor):
+ """transformers' linear RoPE, written out, so a base can be asserted directly."""
+ inv_freq = 1.0 / (base ** (torch.arange(0, HEAD_DIM, 2, dtype = torch.int64).float() / HEAD_DIM))
+ return inv_freq / factor
+
+
+def test_replacing_rope_scaling_keeps_the_base_frequency():
+ # The mechanism behind #2405 on transformers 5: rope_theta lives INSIDE
+ # config.rope_parameters and rope_scaling is an alias that replaces that whole dict, so
+ # assigning a normalized scaling dict drops the base. That assignment is exactly what
+ # _compute_config_rope_inv_freq's object-style retry does, and with the base gone
+ # transformers computes `None ** positions` and unsloth falls back to unscaled RoPE.
+ import unsloth # noqa: F401 -- installs the import fixes this test is about
+ from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS
+
+ scaling = {"rope_type": "linear", "factor": 4.0}
+ expected = _reference_inv_freq(_make_config(dict(scaling)), "linear")
+ # Guard against a vacuous test: the scaled base must not equal the 10000.0 default.
+ assert not torch.allclose(
+ expected, _linear_inv_freq(10000.0, 4.0), rtol = 1e-4
+ ), "test setup error: rope_theta 500000 must not match the default base"
+
+ replaced = _make_config(dict(scaling))
+ replaced.rope_scaling = dict(scaling)
+ inv_freq, _attention_factor = ROPE_INIT_FUNCTIONS["linear"](replaced, torch.device("cpu"))
+ assert torch.allclose(inv_freq.float().cpu(), expected.float().cpu(), rtol = 1e-4, atol = 1e-6), (
+ "replacing config.rope_scaling lost the RoPE base frequency, so scaled models "
+ "run with the wrong inverse frequencies (issue #2405).\n"
+ f"got[:6]={inv_freq[:6].tolist()}\nexpected[:6]={expected[:6].tolist()}"
+ )
+
+
+def test_reassigning_the_configs_own_rope_parameters_changes_nothing():
+ # The healthy path, so carrying a base forward cannot alter a replacement that
+ # already carries everything transformers needs: writing a config's own parameters
+ # back must leave the inverse frequencies bit-identical, on 4.x and on 5.x alike.
+ import unsloth # noqa: F401
+ from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS
+
+ scaling = {"rope_type": "linear", "factor": 4.0}
+ expected = _reference_inv_freq(_make_config(dict(scaling)), "linear")
+
+ subject = _make_config(dict(scaling))
+ own = getattr(subject, "rope_parameters", None)
+ if not isinstance(own, dict):
+ own = subject.rope_scaling
+ subject.rope_scaling = dict(own)
+ inv_freq, _attention_factor = ROPE_INIT_FUNCTIONS["linear"](subject, torch.device("cpu"))
+ assert torch.equal(inv_freq.float().cpu(), expected.float().cpu()), (
+ "writing a config's own rope parameters back changed the inverse frequencies.\n"
+ f"got[:6]={inv_freq[:6].tolist()}\nexpected[:6]={expected[:6].tolist()}"
+ )
+
+
+def test_clearing_rope_scaling_keeps_the_base_frequency():
+ # Unscaled is not the same as unbased. Clearing the scaling must leave the base
+ # readable, or every rotary rebuilt from this config silently falls back to 10000.
+ from unsloth.models.llama import _get_rope_theta
+
+ config = _make_config(LLAMA3_ROPE_SCALING)
+ config.rope_scaling = None
+ assert _get_rope_theta(config, default = 10000.0) == ROPE_THETA, (
+ "clearing config.rope_scaling dropped rope_theta, so the base frequency fell back "
+ f"to the 10000.0 default (issue #2405); got {_get_rope_theta(config, default = 10000.0)}"
+ )
diff --git a/unsloth/_gpu_init.py b/unsloth/_gpu_init.py
index 962494728bb..18cc7926cad 100644
--- a/unsloth/_gpu_init.py
+++ b/unsloth/_gpu_init.py
@@ -225,6 +225,7 @@ from .device_type import arch_lacks_bf16, hip_visible_archs
from .import_fixes import (
fix_transformers5_bare_annotation_configs,
fix_transformers_fully_masked_rows,
+ fix_transformers_rope_scaling_drops_theta,
fix_xformers_performance_issue,
fix_flash_attn_4_namespace_shadow,
fix_vllm_aimv2_issue,
@@ -265,6 +266,10 @@ fix_transformers5_bare_annotation_configs()
# nothing. Ordered here, before anything imports a model, so a plain transformers.generate in the
# same process is covered too (#9708).
fix_transformers_fully_masked_rows()
+# Probe-gated: no-ops unless replacing config.rope_scaling on this transformers really loses the
+# RoPE base frequency. Ordered here, before any config is built, so the object-style delegation
+# retry in models/llama.py sees a config that kept its base (#2405).
+fix_transformers_rope_scaling_drops_theta()
fix_xformers_performance_issue()
# Must run AFTER fix_xformers_performance_issue (it rewrites xformers' cutlass.py on disk) and
# BEFORE models/_utils.py imports xformers.ops.
@@ -312,6 +317,7 @@ fix_peft_stale_torchao_import_error()
patch_accelerate_recursively_apply()
del fix_transformers5_bare_annotation_configs
+del fix_transformers_rope_scaling_drops_theta
del fix_xformers_performance_issue
del fix_flash_attn_4_namespace_shadow
del fix_vllm_aimv2_issue
@@ -393,11 +399,43 @@ elif DEVICE_TYPE == "npu":
# For Gradio HF Spaces?
# if "SPACE_AUTHOR_NAME" not in os.environ and "SPACE_REPO_NAME" not in os.environ:
-import triton
+# `triton` is optional here, like bitsandbytes below. The PyPI `triton` project publishes no
+# Windows wheel (Windows is served by the separate `triton-windows` package), so a CPU only
+# Windows install has no `triton` at all, and an unconditional import here killed
+# `import unsloth` with a bare ModuleNotFoundError from a line whose only job is to resolve
+# `libcuda_dirs` on CUDA hosts. Everything below treats `triton is None` as "no Triton
+# kernels", which is already the state of a CPU only install.
+try:
+ import triton
+except Exception as _triton_import_exception:
+ triton = None
+ TRITON_IMPORT_ERROR = f"{type(_triton_import_exception).__name__}: {_triton_import_exception}"
+ del _triton_import_exception
+else:
+ TRITON_IMPORT_ERROR = None
+
+if TRITON_IMPORT_ERROR is not None:
+ if DEVICE_TYPE in ("cuda", "hip") and torch.cuda.is_available():
+ # A real accelerator with no Triton: the fused kernels are gone, so say so loudly.
+ warnings.warn(
+ f"Unsloth: `triton` could not be imported ({TRITON_IMPORT_ERROR}), so the fused Triton "
+ "kernels are unavailable and training will be slower or may fail.\n"
+ "On Windows install `triton-windows`, on Linux reinstall `triton`.",
+ stacklevel = 2,
+ )
+ else:
+ # No usable accelerator anyway (CPU only install, or UNSLOTH_ALLOW_CPU=1): expected state.
+ print(
+ f"Unsloth: `triton` is not available ({TRITON_IMPORT_ERROR}) - continuing without the "
+ "fused Triton kernels, which a CPU only install does not use.\n"
+ "On Windows, Triton is published as the separate `triton-windows` package."
+ )
if DEVICE_TYPE == "cuda":
libcuda_dirs = lambda: None
- if Version(triton.__version__) >= Version("3.0.0"):
+ if triton is None:
+ pass
+ elif Version(triton.__version__) >= Version("3.0.0"):
# Try loading bitsandbytes and triton
try:
from triton.backends.nvidia.driver import libcuda_dirs
@@ -456,11 +494,16 @@ if DEVICE_TYPE == "cuda":
if bnb is not None:
importlib.reload(bnb)
- importlib.reload(triton)
+ if triton is not None:
+ importlib.reload(triton)
# Same degradation as the cuda branch above: no bnb means no 4bit, not a failed `import unsloth`.
+ # No triton either means there is nothing to re-resolve here, and the missing Triton was
+ # already reported above, so do not re-report it as a CUDA linking failure.
try:
libcuda_dirs = lambda: None
- if Version(triton.__version__) >= Version("3.0.0"):
+ if triton is None:
+ pass
+ elif Version(triton.__version__) >= Version("3.0.0"):
try:
from triton.backends.nvidia.driver import libcuda_dirs
except:
diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.py
index a2880e2645a..0b0eee9f5f8 100644
--- a/unsloth/import_fixes.py
+++ b/unsloth/import_fixes.py
@@ -884,6 +884,326 @@ def fix_transformers_fully_masked_rows():
logger.info(f"Unsloth: Failed patching sdpa_mask ({e})")
+_ROPE_SCALING_PATCH_FLAG = "_unsloth_patched_rope_scaling_setter"
+
+
+def _rope_scaling_property_owner():
+ """The class that DEFINES a writable ``rope_scaling`` property, or ``None``.
+
+ transformers 5 keeps ``rope_scaling`` as an alias for ``rope_parameters``; 4.x has a
+ plain attribute, so ``None`` there. The MRO is walked because the base config is
+ spelled ``PretrainedConfig`` on 4.x and ``PreTrainedConfig`` on 5.x.
+ """
+ try:
+ from transformers.configuration_utils import PretrainedConfig
+ except Exception:
+ return None
+ for klass in getattr(PretrainedConfig, "__mro__", ()):
+ prop = klass.__dict__.get("rope_scaling", None)
+ if isinstance(prop, property) and prop.fset is not None:
+ return klass
+ return None
+
+
+def _rope_probe_inherits(owner):
+ """Does the config class the probe measures still descend from the LIVE owner?
+
+ False only after a reload has replaced the owner underneath a cached config module,
+ which is exactly when the probe's verdict describes a class nobody will use again.
+ """
+ try:
+ from transformers import LlamaConfig
+ except Exception:
+ return False
+ return isinstance(owner, type) and issubclass(LlamaConfig, owner)
+
+
+def _rope_scaling_setter_is_patched(owner = None):
+ """Is the LIVE ``rope_scaling`` setter ours, right now?
+
+ Asked of the descriptor, not of a class flag: a reload of
+ ``transformers.configuration_utils`` puts the upstream property back while a class
+ attribute survives, so a flag would refuse to re-patch a vulnerable build.
+ """
+ if owner is None:
+ owner = _rope_scaling_property_owner()
+ if owner is None:
+ return False
+ prop = owner.__dict__.get("rope_scaling", None)
+ if not isinstance(prop, property):
+ return False
+ return bool(getattr(prop.fset, _ROPE_SCALING_PATCH_FLAG, False))
+
+
+def _rope_parameters_are_per_layer(config, parameters):
+ """Is this a per-layer-type rope dict rather than one global one?
+
+ transformers' own discriminator: per-layer exactly when the config declares
+ ``layer_types`` and every key is one of them. A global key written into such a dict
+ makes transformers read the whole thing as flat, so this is asked first.
+ """
+ layer_types = getattr(config, "layer_types", None)
+ if not layer_types or not isinstance(parameters, dict) or not parameters:
+ return False
+ try:
+ return set(parameters.keys()).issubset(set(layer_types))
+ except Exception:
+ return False
+
+
+def _rope_theta_snapshot(config):
+ """The base(s) ``rope_parameters`` holds right now, in the shape it holds them.
+
+ A flat dict has one base. A per-layer dict has one per layer type (5.5's
+ ``T5Gemma2DecoderConfig``: 10000.0 sliding, 1000000.0 full), returned as
+ ``{layer_type: base}``; the outer dict has no ``rope_theta``, which is how both
+ bases used to be lost.
+ """
+ parameters = getattr(config, "rope_parameters", None)
+ if not isinstance(parameters, dict):
+ return None
+ if not _rope_parameters_are_per_layer(config, parameters):
+ return parameters.get("rope_theta", None)
+ snapshot = {}
+ for layer_type, entry in parameters.items():
+ if isinstance(entry, dict) and entry.get("rope_theta", None) is not None:
+ snapshot[layer_type] = entry["rope_theta"]
+ return snapshot or None
+
+
+def _carry_per_layer_rope_theta(config, parameters, carried):
+ """Put each layer type's base back into a per-layer replacement that lost it.
+
+ A top-level ``rope_theta`` would make the dict read as flat, so the base goes back
+ into each nested entry. Copies throughout, never the caller's dicts in place. An
+ entry naming its own base is left alone.
+ """
+ if not isinstance(carried, dict) or not carried:
+ return None
+ replacement = {}
+ changed = False
+ for layer_type, entry in parameters.items():
+ if (
+ isinstance(entry, dict)
+ and entry.get("rope_theta", None) is None
+ and carried.get(layer_type, None) is not None
+ ):
+ entry = dict(entry)
+ entry["rope_theta"] = carried[layer_type]
+ changed = True
+ replacement[layer_type] = entry
+ if not changed:
+ return None
+ try:
+ config.rope_parameters = replacement
+ except Exception:
+ return None
+ return carried
+
+
+def _carry_rope_theta_across_assignment(config, carried):
+ """Keep the RoPE base frequency across a ``rope_scaling`` replacement.
+
+ Separated from the wrapper so every parameter shape is testable without a live
+ transformers.
+
+ Precedence, so nothing a caller said is overwritten: the NEW parameters' base, then
+ the config's own, then ``carried`` (the base held before the assignment). That order
+ matters because ``unsloth_zoo/empty_model.py`` sets Gemma's local rotary base and
+ then replaces the scaling, and carrying the global base over it would be wrong.
+
+ The base is written to ``rope_parameters`` where 5.x keeps it, so the answer does
+ not depend on ``standardize_rope_params`` running first and ``validate_rope`` and
+ ``save_pretrained`` see a complete dict. A per-layer dict is left alone.
+
+ The config's ``rope_theta`` attribute (the 4.x slot) is written only when it is the
+ only slot that can hold the base, which is the non-dict replacement of #2405, or
+ when it already exists and would otherwise go stale. Otherwise a saved config gains
+ no key it did not have. Writes nothing when the new parameters name their own base
+ and the config states none, so this is a no-op on a build that keeps the base.
+ """
+ parameters = getattr(config, "rope_parameters", None)
+ per_layer = _rope_parameters_are_per_layer(config, parameters)
+ if per_layer:
+ # Per-layer bases go back one level down. Falls through to the global attribute
+ # below only when there is no nested snapshot to restore.
+ restored = _carry_per_layer_rope_theta(config, parameters, carried)
+ if restored is not None:
+ return restored
+ elif isinstance(carried, dict):
+ # Per-layer parameters replaced by a FLAT dict. Passing the mapping through would
+ # write a dict where a number belongs. One base stands for it only when every
+ # layer type agreed; otherwise carry nothing rather than invent a scalar.
+ bases = set(carried.values())
+ carried = bases.pop() if len(bases) == 1 else None
+ is_flat_dict = isinstance(parameters, dict) and not per_layer
+ current = parameters.get("rope_theta", None) if is_flat_dict else None
+ stated = getattr(config, "rope_theta", None)
+
+ base = current
+ if base is None:
+ base = stated
+ if base is None:
+ base = carried
+ if base is None:
+ return None
+
+ readable = current is not None
+ if is_flat_dict and not readable:
+ try:
+ # A COPY, never the dict in place: transformers 5 stores the caller's object
+ # verbatim, so one scaling dict reused across a loop of models would carry the
+ # first config's base into the second. Measured on 5.0.0, 5.5.4 and 5.17.0: a
+ # config declaring 10000.0 came out with 500000.0, silently.
+ replacement = dict(parameters)
+ replacement["rope_theta"] = base
+ config.rope_parameters = replacement
+ parameters = replacement
+ readable = True
+ except Exception:
+ pass
+ if stated is not None or not readable:
+ try:
+ config.rope_theta = base
+ except Exception:
+ return None
+ return base
+
+
+def _transformers_rope_scaling_assignment_drops_theta():
+ """Does replacing ``config.rope_scaling`` on THIS build lose the base frequency?
+
+ Measured, not inferred from a version: the move into ``rope_parameters``, the alias
+ property and the strict validation landed in different 5.x releases and have been
+ backported. Two configs, because ``ROPE_INIT_FUNCTIONS`` mutates the one it is
+ handed. Absent positive evidence answer ``False`` and leave transformers alone.
+ """
+ try:
+ import torch
+ from transformers import LlamaConfig
+ from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS
+ except Exception:
+ return False
+ try:
+ rope_init_fn = ROPE_INIT_FUNCTIONS["linear"]
+ except Exception:
+ return False
+ scaling = {"rope_type": "linear", "factor": 4.0}
+
+ def build():
+ # Tiny, and a base far from the 10000.0 default so a silent fallback shows up
+ # as a difference rather than a match.
+ return LlamaConfig(
+ hidden_size = 64,
+ num_attention_heads = 2,
+ num_key_value_heads = 2,
+ head_dim = 32,
+ rope_theta = 500000.0,
+ max_position_embeddings = 2048,
+ rope_scaling = dict(scaling),
+ )
+
+ # CPU explicitly: under a "meta" default device the comparison cannot be read, which
+ # would answer "not affected" for a reason unrelated to the bug.
+ device = torch.device("cpu")
+ try:
+ reference, _attention_factor = rope_init_fn(build(), device)
+ subject = build()
+ except Exception:
+ return False
+ try:
+ subject.rope_scaling = dict(scaling)
+ except Exception:
+ return False
+ try:
+ replaced, _attention_factor = rope_init_fn(subject, device)
+ except Exception:
+ # The base came out None and `base ** positions` raised. This is the defect.
+ return True
+ try:
+ return not bool(torch.allclose(replaced.float().cpu(), reference.float().cpu()))
+ except Exception:
+ return False
+
+
+def fix_transformers_rope_scaling_drops_theta():
+ """Stop a replaced ``rope_scaling`` silently unscaling RoPE (issue #2405).
+
+ transformers 5 moved ``rope_theta`` into ``config.rope_parameters`` and kept
+ ``rope_scaling`` as an alias that REPLACES that whole dict, so assigning a
+ normalized scaling dict takes the base with it and
+ ``_compute_linear_scaling_rope_parameters`` raises ``TypeError: unsupported operand
+ type(s) for ** or pow(): 'NoneType' and 'Tensor'``. That assignment is what
+ ``models/llama.py``'s ``_compute_config_rope_inv_freq`` retry does, and unsloth
+ catches the raise and falls back to UNSCALED RoPE, which is #2405's gibberish past
+ the original context.
+
+ Measured here, one venv per transformers minor on torch 2.11.0:
+ ``tests/utils/test_rope_scaling_drift.py`` fails on 5.0.0 through 5.3.0 and passes
+ on 4.57.6, where ``rope_theta`` is an attribute the assignment cannot touch. From
+ 5.4.0 a config refuses a non-dict ``rope_parameters``, so the object route is
+ unreachable, but any dict assignment still drops the base and ``save_pretrained``
+ raises ``KeyError: Missing required keys ... {'rope_theta'}`` instead. The probe
+ therefore fires on every 5.x.
+
+ The alias setter is the only site where the outgoing and incoming parameters are
+ both visible. Nothing is normalized or rejected on the way in; the wrapper only puts
+ the base back where it would otherwise be gone. Assignments to ``rope_parameters``
+ itself need no cover: a caller writing that field writes what transformers reads.
+ """
+ owner = _rope_scaling_property_owner()
+ if owner is not None and _rope_scaling_setter_is_patched(owner):
+ return
+ # The probe answers through the cached `transformers.LlamaConfig`. After a reload of
+ # configuration_utils that class still inherits the OLD patched owner while the live
+ # owner is new and unpatched, so the probe would report the base survives and leave
+ # the live owner to lose it. A probe that cannot see the owner is no evidence and
+ # does not get to veto; installing anyway is safe, since the wrapper is a no-op on a
+ # build that keeps the base.
+ probe_can_see_owner = owner is None or _rope_probe_inherits(owner)
+ if probe_can_see_owner and not _transformers_rope_scaling_assignment_drops_theta():
+ return
+ if owner is None:
+ logger.info("Unsloth: Skipping the rope_scaling base-frequency fix (no alias property)")
+ return
+
+ prop = owner.__dict__["rope_scaling"]
+ # Unwrap first, so a reload that restored upstream's property is re-patched rather
+ # than wrapped on top of a wrapper.
+ original = getattr(prop.fset, "__wrapped__", prop.fset)
+
+ @functools.wraps(original)
+ def rope_scaling(self, value):
+ # Both halves are guarded, since this runs on every model load and an unexpected
+ # config shape must not turn an assignment into a traceback. The assignment
+ # itself is not, since swallowing that would be a silent behaviour change.
+ try:
+ carried = _rope_theta_snapshot(self)
+ except Exception:
+ carried = None
+ result = original(self, value)
+ try:
+ _carry_rope_theta_across_assignment(self, carried)
+ except Exception:
+ pass
+ return result
+
+ # Set explicitly as well as by wraps: the unwrap above and the tests read it, so a
+ # wraps-less edit must not make the patch un-probeable.
+ rope_scaling.__wrapped__ = original
+ # The mark travels ON the setter, so a reload that drops it is re-patched.
+ setattr(rope_scaling, _ROPE_SCALING_PATCH_FLAG, True)
+
+ try:
+ setattr(owner, "rope_scaling", property(prop.fget, rope_scaling, prop.fdel, prop.__doc__))
+ logger.info(
+ "Unsloth: Patching transformers `rope_scaling` so replacing it keeps the "
+ "RoPE base frequency (unsloth #2405)"
+ )
+ except Exception as e:
+ logger.info(f"Unsloth: Failed patching rope_scaling ({e})")
+
+
# ValueError: 'aimv2' is already used by a Transformers config, pick another name.
def fix_vllm_aimv2_issue():
spec = importlib.util.find_spec("vllm")