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 gradient checkpointing settings working on transformers 5.23 (#16833)

Nilaye8aaca2e0b19
diff --git a/tests/test_decision_model.py b/tests/test_decision_model.py
index de756c545f8..4f2be2d7d16 100644
--- a/tests/test_decision_model.py
+++ b/tests/test_decision_model.py
@@ -362,6 +362,26 @@ def test_head_learning_rate_and_weight_decay(checkpoint, tmp_path, lora):
assert group["weight_decay"] == (0.0 if name in no_decay else 0.01)
+ not hasattr(TrainingArguments, "activation_checkpointing"),
+ reason = "transformers < 5.23 reads gradient_checkpointing",
+)
+def test_trainer_checkpoints_the_encoder_not_the_wrapper(checkpoint, tmp_path):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(4)], tokenizer, model)
+ trainer = DecisionTrainer(
+ model = model,
+ args = _args(tmp_path, max_steps = 1, gradient_checkpointing = True),
+ train_dataset = items,
+ processing_class = tokenizer,
+ )
+ assert trainer.args.activation_checkpointing is False
+ assert model.encoder.is_gradient_checkpointing
+ trainer.train()
+
+
def test_length_grouping_only_with_gradient_accumulation(checkpoint, tmp_path):
model, tokenizer = FastDecisionModel.from_pretrained(
str(checkpoint), use_gradient_checkpointing = False
diff --git a/tests/test_gc_enable_kwargs.py b/tests/test_gc_enable_kwargs.py
index 590dd70d167..d3995802464 100644
--- a/tests/test_gc_enable_kwargs.py
+++ b/tests/test_gc_enable_kwargs.py
@@ -24,6 +24,7 @@ FUNCS = (
)
ASSIGNS = ("_OFFLOADING_CHECKPOINT_SHIMS", "_GC_KWARGS_WARNED")
NATIVE = "offload" in inspect.signature(PreTrainedModel.gradient_checkpointing_enable).parameters
+RENAMED = hasattr(PreTrainedModel, "activation_checkpointing_enable")
def _load():
@@ -41,13 +42,22 @@ def _load():
@pytest.fixture
def patched():
- original = PreTrainedModel.__dict__["gradient_checkpointing_enable"]
+ original = {
+ name: PreTrainedModel.__dict__[name]
+ for name in (
+ "gradient_checkpointing_enable",
+ "activation_checkpointing_enable",
+ "_activation_checkpointing_enable",
+ )
+ if name in PreTrainedModel.__dict__
+ }
previous_checkpoint = hf_modeling_utils.checkpoint
patch = _load().get("patch_gradient_checkpointing_enable_kwargs")
if patch is not None:
patch()
yield
- PreTrainedModel.gradient_checkpointing_enable = original
+ for name, function in original.items():
+ setattr(PreTrainedModel, name, function)
hf_modeling_utils.checkpoint = previous_checkpoint
@@ -149,6 +159,73 @@ def test_every_n_layers_survives_for_training_flag_rewrite(patched):
assert _flags(model) == [True, True, True, True]
+ not RENAMED, reason = "the Trainer calls activation_checkpointing_enable from transformers 5.23"
+)
+def test_every_n_layers_survives_flag_rewrite_through_activation_checkpointing_enable(patched):
+ model = _model()
+ model.activation_checkpointing_enable(activation_checkpointing_kwargs = None, every_n_layers = 2)
+ assert _flags(model) == [True, False, True, False]
+ for module in model.modules():
+ if hasattr(module, "gradient_checkpointing"):
+ module.gradient_checkpointing = True
+ assert _flags(model) == [True, False, True, False]
+
+
[email protected](RENAMED, reason = "before transformers 5.23 the patched method is the public one")
+def test_explicit_every_n_layers_beats_the_dict_on_the_legacy_api(patched):
+ model = _model()
+ model.gradient_checkpointing_enable({"every_n_layers": 2}, every_n_layers = 1)
+ assert _flags(model) == [True, True, True, True]
+
+
+ not RENAMED,
+ reason = "the old name is an alias of activation_checkpointing_enable from transformers 5.23",
+)
+def test_every_n_layers_dict_through_instance_wrapper_of_old_name(patched):
+ # vision.py wraps the old name per instance (gemma3n / gemma4, forced non-reentrant).
+ model = _model()
+ original = model.gradient_checkpointing_enable
+ model.gradient_checkpointing_enable = lambda **kwargs: original(**kwargs)
+ model.gradient_checkpointing_enable(
+ gradient_checkpointing_kwargs = {"use_reentrant": False, "every_n_layers": 2}
+ )
+ assert _flags(model) == [True, False, True, False]
+ _grads(model)
+
+
+ not RENAMED, reason = "the Trainer calls activation_checkpointing_enable from transformers 5.23"
+)
+def test_offload_dropped_under_offloading_shim_through_activation_checkpointing_enable(
+ patched, smart_gc, monkeypatch
+):
+ entered = []
+ real = hf_modeling_utils.save_on_cpu
+
+ class Counting(real):
+ def __init__(
+ self,
+ pin_memory = False,
+ device_type = "cuda",
+ ):
+ pin_memory = pin_memory and torch.accelerator.is_available()
+ super().__init__(pin_memory = pin_memory, device_type = device_type)
+
+ def __enter__(self):
+ entered.append(1)
+ return super().__enter__()
+
+ monkeypatch.setattr(hf_modeling_utils, "save_on_cpu", Counting)
+ model = _model()
+ model.activation_checkpointing_enable(
+ activation_checkpointing_kwargs = {"use_reentrant": True}, offload = True
+ )
+ _grads(model)
+ assert entered == []
+
+
@pytest.mark.skipif(
not NATIVE, reason = "offload is a gradient_checkpointing_enable argument from transformers 5.17"
)
diff --git a/tests/test_gc_every_n_cpu_route.py b/tests/test_gc_every_n_cpu_route.py
index d96d6e2c9a9..8d986491b1f 100644
--- a/tests/test_gc_every_n_cpu_route.py
+++ b/tests/test_gc_every_n_cpu_route.py
@@ -46,7 +46,8 @@ def run(m):
out = {"device_type": unsloth.DEVICE_TYPE,
"models_loaded": sorted(n for n in sys.modules if n == "unsloth.models" or n.startswith("unsloth.models.")),
- "patched": bool(getattr(PreTrainedModel.gradient_checkpointing_enable, "_unsloth_gc_kwargs", False))}
+ "patched": any(getattr(getattr(PreTrainedModel, n, None), "_unsloth_gc_kwargs", False)
+ for n in ("_activation_checkpointing_enable", "activation_checkpointing_enable", "gradient_checkpointing_enable"))}
res = {}
# dict form (TrainingArguments on transformers < 5.17, PEFT prepare_model_for_kbit_training, direct calls)
m = model()
diff --git a/tests/test_gradient_checkpointing_off_honoured.py b/tests/test_gradient_checkpointing_off_honoured.py
index 85f18e6e9f7..66bcbcc4b76 100644
--- a/tests/test_gradient_checkpointing_off_honoured.py
+++ b/tests/test_gradient_checkpointing_off_honoured.py
@@ -93,6 +93,55 @@ def test_honour_rules(capsys):
assert foreign.gradient_checkpointing is True
+def test_off_reaches_activation_checkpointing():
+ module = _load_module()
+ Config = _config_class()
+ module.track_explicit_gradient_checkpointing(Config)
+ args = Config()
+ args.__dict__["activation_checkpointing"] = True
+ assert module.honour_gradient_checkpointing_off(args, _Model(False))
+ assert args.gradient_checkpointing is False
+ assert args.activation_checkpointing is False
+
+
+def _renamed_config_class():
+ class Config:
+ def __init__(
+ self,
+ output_dir = None,
+ activation_checkpointing = None,
+ gradient_checkpointing = True,
+ **kwargs,
+ ):
+ self.output_dir = output_dir
+ if activation_checkpointing is None:
+ activation_checkpointing = gradient_checkpointing
+ self.activation_checkpointing = activation_checkpointing
+ self.gradient_checkpointing = activation_checkpointing
+
+ return Config
+
+
+def test_explicit_activation_checkpointing_is_kept():
+ module = _load_module()
+ Config = _renamed_config_class()
+ assert module.track_explicit_gradient_checkpointing(Config)
+ assert Config().__dict__[module.EXPLICIT_FLAG] is False
+
+ passed = Config(activation_checkpointing = True)
+ assert not module.honour_gradient_checkpointing_off(passed, _Model(False))
+ assert passed.activation_checkpointing is True
+
+ assigned = Config()
+ assigned.activation_checkpointing = True
+ assert not module.honour_gradient_checkpointing_off(assigned, _Model(False))
+ assert assigned.activation_checkpointing is True
+
+ default = Config()
+ assert module.honour_gradient_checkpointing_off(default, _Model(False))
+ assert default.activation_checkpointing is False
+
+
def test_assignment_after_construction_is_explicit():
import dataclasses
diff --git a/tests/test_gradient_checkpointing_reentrant.py b/tests/test_gradient_checkpointing_reentrant.py
index cd8495bc901..3ee7adcb040 100644
--- a/tests/test_gradient_checkpointing_reentrant.py
+++ b/tests/test_gradient_checkpointing_reentrant.py
@@ -104,3 +104,15 @@ def test_the_snippet_pins_true_rather_than_deleting_the_key():
"deleting the key is not enough: a config that never set it leaves "
"None, and transformers substitutes False"
)
+
+
+class _RenamedConfig(_Config):
+ def __init__(self, kwargs = None):
+ super().__init__(kwargs = kwargs)
+ self.activation_checkpointing_kwargs = kwargs
+
+
+def test_the_pin_reaches_activation_checkpointing_kwargs():
+ config = _run_post(_RenamedConfig(kwargs = None))
+ assert config.activation_checkpointing_kwargs == {"use_reentrant": True}
+ assert config.gradient_checkpointing_kwargs == {"use_reentrant": True}
diff --git a/tests/test_pp_native_gloo.py b/tests/test_pp_native_gloo.py
index d8d88793457..e138060bf55 100644
--- a/tests/test_pp_native_gloo.py
+++ b/tests/test_pp_native_gloo.py
@@ -772,6 +772,30 @@ def test_layer_call_format_reads_tuple_loops():
assert ppn._layer_call_format(Decoder(), "layers") == "tuple"
+def test_layer_call_format_knows_the_renamed_checkpointing_layer():
+ class ActivationCheckpointingLayer(torch.nn.Module):
+ pass
+
+ class Decoder(torch.nn.Module):
+ gradient_checkpointing = True
+
+ def __init__(self):
+ super().__init__()
+ self.layers = torch.nn.ModuleList()
+
+ def forward(self, hidden_states):
+ for decoder_layer in self.layers:
+ if isinstance(decoder_layer, ActivationCheckpointingLayer):
+ hidden_states = decoder_layer(hidden_states)
+ else:
+ hidden_states = self._gradient_checkpointing_func(
+ decoder_layer.__call__, hidden_states
+ )
+ return hidden_states
+
+ assert ppn._layer_call_format(Decoder(), "layers") == "tensor"
+
+
def test_non_last_stage_compiles_as_one_graph():
from torch._dynamo.utils import counters
diff --git a/unsloth/_gc_kwargs.py b/unsloth/_gc_kwargs.py
index 466b7376cec..6c8d78b161b 100644
--- a/unsloth/_gc_kwargs.py
+++ b/unsloth/_gc_kwargs.py
@@ -90,16 +90,28 @@ def patch_gradient_checkpointing_enable_kwargs():
import transformers.modeling_utils as hf_modeling_utils
except Exception:
return
- original = PreTrainedModel.gradient_checkpointing_enable
+ # transformers >= 5.23: both public names and instance wrappers of the old one end here.
+ name = next(
+ (
+ n
+ for n in ("_activation_checkpointing_enable", "activation_checkpointing_enable")
+ if hasattr(PreTrainedModel, n)
+ ),
+ "gradient_checkpointing_enable",
+ )
+ original = getattr(PreTrainedModel, name)
if getattr(original, "_unsloth_gc_kwargs", False):
return
try:
params = list(inspect.signature(original).parameters)
except Exception:
return
- positional = [p for p in params if p not in ("self", "gradient_checkpointing_kwargs")]
+ kwargs_name = name.lstrip("_").replace("_enable", "_kwargs")
+ positional = [p for p in params if p not in ("self", kwargs_name)]
native_every = "every_n_layers" in params
native_offload = "offload" in params
+ # transformers >= 5.23 always passes the defaults (1, False) here, so they cannot override the dict.
+ forwards_defaults = name == "_activation_checkpointing_enable"
@functools.wraps(original)
def gradient_checkpointing_enable(
@@ -108,6 +120,7 @@ def patch_gradient_checkpointing_enable_kwargs():
*args,
**kwargs,
):
+ gradient_checkpointing_kwargs = kwargs.pop(kwargs_name, gradient_checkpointing_kwargs)
kwargs.update(zip(positional, args))
every = kwargs.pop("every_n_layers", None)
offload = kwargs.pop("offload", None)
@@ -115,6 +128,9 @@ def patch_gradient_checkpointing_enable_kwargs():
gc_kwargs = dict(gradient_checkpointing_kwargs)
dict_every = gc_kwargs.pop("every_n_layers", None)
dict_offload = gc_kwargs.pop("offload", None)
+ if forwards_defaults:
+ every = None if every == 1 else every
+ offload = offload or None
every = dict_every if every is None else every
offload = dict_offload if offload is None else offload
if len(gc_kwargs) != len(gradient_checkpointing_kwargs):
@@ -154,4 +170,4 @@ def patch_gradient_checkpointing_enable_kwargs():
return out
gradient_checkpointing_enable._unsloth_gc_kwargs = True
- PreTrainedModel.gradient_checkpointing_enable = gradient_checkpointing_enable
+ setattr(PreTrainedModel, name, gradient_checkpointing_enable)
diff --git a/unsloth/models/_gc_config_default.py b/unsloth/models/_gc_config_default.py
index 73e3bc2d866..21b6142c1ec 100644
--- a/unsloth/models/_gc_config_default.py
+++ b/unsloth/models/_gc_config_default.py
@@ -27,6 +27,7 @@ __all__ = [
EXPLICIT_FLAG = "_unsloth_gradient_checkpointing_explicit"
_WRAPPED_FLAG = "_unsloth_tracks_explicit_gradient_checkpointing"
_NOTED = set()
+_FIELDS = ("gradient_checkpointing", "activation_checkpointing")
def _note(key, message):
@@ -47,11 +48,13 @@ def track_explicit_gradient_checkpointing(config_class):
return False
if "gradient_checkpointing" not in names:
return False
- position = names.index("gradient_checkpointing") - 1
+ # transformers >= 5.23 renames it activation_checkpointing and mirrors the old name from the new one.
+ fields = [name for name in _FIELDS if name in names]
+ positions = [names.index(name) - 1 for name in fields]
@functools.wraps(init)
def __init__(self, *args, **kwargs):
- explicit = "gradient_checkpointing" in kwargs or len(args) > position
+ explicit = any(name in kwargs for name in fields) or len(args) > min(positions)
init(self, *args, **kwargs)
# Not a dataclass field: to_dict(), to_json_string() and asdict() never see it.
self.__dict__[EXPLICIT_FLAG] = explicit
@@ -65,7 +68,7 @@ def track_explicit_gradient_checkpointing(config_class):
def __setattr__(self, name, value):
original_setattr(self, name, value)
- if name == "gradient_checkpointing" and EXPLICIT_FLAG in self.__dict__:
+ if name in _FIELDS and EXPLICIT_FLAG in self.__dict__:
self.__dict__[EXPLICIT_FLAG] = True
config_class.__setattr__ = __setattr__
@@ -98,6 +101,8 @@ def honour_gradient_checkpointing_off(args, model):
)
return False
args.gradient_checkpointing = False
+ if hasattr(args, "activation_checkpointing"):
+ args.activation_checkpointing = False
_note(
"off",
"Unsloth: the model was set up with use_gradient_checkpointing = False, so gradient checkpointing stays "
diff --git a/unsloth/models/decision.py b/unsloth/models/decision.py
index f8e87e1b3ad..28029b6179c 100644
--- a/unsloth/models/decision.py
+++ b/unsloth/models/decision.py
@@ -1267,6 +1267,8 @@ class DecisionTrainer(Trainer):
# Trainer would call model.gradient_checkpointing_enable, which only the encoder has.
# Clef's backbone already got Unsloth's checkpointing when it loaded.
args.gradient_checkpointing = False
+ if hasattr(args, "activation_checkpointing"):
+ args.activation_checkpointing = False
if not clef and not model.encoder.is_gradient_checkpointing:
_gradient_checkpointing(model, True)
if kwargs.get("processing_class") is None:
diff --git a/unsloth/models/pp_native.py b/unsloth/models/pp_native.py
index 19a0ba52a7b..1e90619fd5d 100644
--- a/unsloth/models/pp_native.py
+++ b/unsloth/models/pp_native.py
@@ -838,7 +838,10 @@ def _layer_call_format(decoder, layers_name):
and any(var in ast.unparse(a) for a in node.args)
and "checkpoint" in ast.unparse(node.func).lower()
):
- if "GradientCheckpointingLayer" not in text:
+ if (
+ "GradientCheckpointingLayer" not in text
+ and "ActivationCheckpointingLayer" not in text
+ ):
formats.add("checkpointed")
if "checkpointed" in formats:
if getattr(decoder, "gradient_checkpointing", False):
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index 9f4d24a913a..f46cfacbfd1 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -3744,6 +3744,8 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
" if _gc_kwargs.get('context_fn') is None and not _gc_kwargs.get('debug', False):\n"
" _gc_kwargs['use_reentrant'] = True\n"
" self.gradient_checkpointing_kwargs = _gc_kwargs\n"
+ " if hasattr(self, 'activation_checkpointing_kwargs'):\n"
+ " self.activation_checkpointing_kwargs = _gc_kwargs\n"
)
if "optim" in call_args: