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
Pass Q-GaLore optimizer options to bitsandbytes by name (#10874)
Vineeth Sai Varikuntla9f182473aac3
diff --git a/tests/utils/test_q_galore.py b/tests/utils/test_q_galore.pyindex cc583a52fd2..69fbd64d8a7 100644--- a/tests/utils/test_q_galore.py+++ b/tests/utils/test_q_galore.py@@ -14,6 +14,7 @@## Tests for Q-GaLore integration (unsloth/optimizers/).+import inspectimport pytestimport sysimport os@@ -82,6 +83,96 @@ def requires_bnb_optimizer(device):pytest.skip(f"This bitsandbytes version cannot run an optimizer step on {device}")[email protected](not _adamw_mod._HAS_BNB, reason = "bitsandbytes is required")+def test_optimizer_constructs_against_the_installed_bitsandbytes():+ """Runs on every version in the CI matrix, unlike the tests that need a step.++ Construction needs no optimizer kernels, so this is the only check the 0.45.x-0.49.x+ matrix jobs can actually execute. It has to assert on the bound arguments because the+ 0.50.x misbinding left the arity intact and raised nothing.+ """+ signature = inspect.signature(_adamw_mod.Optimizer2State.__init__)+ captured = {}+ original = _adamw_mod.Optimizer2State.__init__++ def record(self, *args, **kwargs):+ bound = signature.bind(self, *args, **kwargs)+ bound.apply_defaults()+ captured.update(bound.arguments)+ return original(self, *args, **kwargs)++ _adamw_mod.Optimizer2State.__init__ = record+ try:+ _adamw_mod.QGaLoreAdamW8bit([nn.Parameter(torch.ones(8, 8))], lr = 1e-3)+ finally:+ _adamw_mod.Optimizer2State.__init__ = original++ assert captured.get("optimizer_name") == "adam"+ assert captured.get("optim_bits") == 8+ for name, default in (("max_unorm", 0.0), ("skip_zeros", False)):+ if name in signature.parameters:+ assert captured.get(name) == default, (+ f"bitsandbytes received {name}={captured.get(name)!r}, but its default is "+ f"{default!r}; an option is landing in the wrong parameter positionally."+ )++[email protected](not _adamw_mod._HAS_BNB, reason = "bitsandbytes is required")[email protected]("projected", [True, False])[email protected]("initial_value", [0.0, 1.0])+def test_default_optimizer_updates_match_adamw(projected, initial_value):+ pytest.importorskip("bitsandbytes")+ device = "cuda" if torch.cuda.is_available() else "cpu"+ requires_bnb_optimizer(device)+ param = nn.Parameter(torch.full((2, 2), initial_value, device = device))+ reference = nn.Parameter(param.detach().clone())+ group = {"params": [param]}+ if projected:+ group.update(rank = 2, scale = 1.0, quant = False)+ optimizer = _adamw_mod.QGaLoreAdamW8bit([group], lr = 0.1, weight_decay = 0.0)+ reference_optimizer = torch.optim.AdamW([reference], lr = 0.1, weight_decay = 0.0)+ # A diagonal gradient keeps full-rank projection aligned with the AdamW reference.+ gradient = torch.diag(torch.tensor([2.0, 1.0], device = device))+ for weight, opt in [(param, optimizer), (reference, reference_optimizer)]:+ (weight * gradient).sum().backward()+ opt.step()+ torch.testing.assert_close(param, reference)++[email protected](not _adamw_mod._HAS_BNB, reason = "bitsandbytes is required")+def test_legacy_bitsandbytes_options_are_forwarded_by_name(monkeypatch):+ original_init = _adamw_mod.Optimizer2State.__init__+ received = []++ def legacy_init(+ self,+ *args,+ percentile_clipping = 100,+ block_wise = True,+ **kwargs,+ ):+ received.append((percentile_clipping, block_wise))+ original_init(self, *args, **kwargs)++ monkeypatch.setattr(_adamw_mod.Optimizer2State, "__init__", legacy_init)+ _adamw_mod.QGaLoreAdamW8bit(+ [nn.Parameter(torch.ones(2))],+ percentile_clipping = 95,+ block_wise = False,+ )+ assert received == [(95, False)]++[email protected](not _adamw_mod._HAS_BNB, reason = "bitsandbytes is required")[email protected]("name,value", [("percentile_clipping", 95), ("block_wise", False)])+def test_removed_bitsandbytes_options_are_rejected(name, value):+ import inspect+ if name in inspect.signature(_adamw_mod.Optimizer2State.__init__).parameters:+ pytest.skip("This bitsandbytes version still supports the option")+ with pytest.raises(ValueError, match = name):+ _adamw_mod.QGaLoreAdamW8bit([nn.Parameter(torch.ones(2))], **{name: value})++# ======================================================================# Projector tests# ======================================================================diff --git a/tests/version_compat/test_bitsandbytes_pinned_symbols.py b/tests/version_compat/test_bitsandbytes_pinned_symbols.pyindex a8acd7e2a27..a21ce157b38 100644--- a/tests/version_compat/test_bitsandbytes_pinned_symbols.py+++ b/tests/version_compat/test_bitsandbytes_pinned_symbols.py@@ -4,13 +4,54 @@from __future__ import annotations+import astimport re+from pathlib import Pathimport pytestfrom tests.version_compat._fetch import fetch_text, first_match, has_def+++def _super_init_call(source: str, class_name: str) -> ast.Call | None:+ """The ``super().__init__(...)`` Call node inside ``class_name``'s __init__.++ Parsed rather than grepped: a substring search over the class body also sees the+ names quoted in the legacy_kwargs table, so it passes whether or not the real call+ uses keywords.+ """+ for node in ast.walk(ast.parse(source)):+ if not (isinstance(node, ast.ClassDef) and node.name == class_name):+ continue+ for sub in ast.walk(node):+ if (+ isinstance(sub, ast.Call)+ and isinstance(sub.func, ast.Attribute)+ and sub.func.attr == "__init__"+ ):+ return sub+ return None++def first_match_signature(src: str, class_name: str) -> str | None:+ """The text of ``class_name``'s __init__ parameter list, or None."""+ at = src.find(f"class {class_name}")+ if at == -1:+ return None+ at = src.find("def __init__", at)+ if at == -1:+ return None+ depth = 0+ for i in range(src.index("(", at), len(src)):+ if src[i] == "(":+ depth += 1+ elif src[i] == ")":+ depth -= 1+ if depth == 0:+ return src[src.index("(", at) : i + 1]+ return None+# pyproject pin: bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0 Test floor + each safe minor since.BNB_TAGS = ["0.45.5",@@ -217,3 +258,54 @@ def test_bnb_version_parseable(tag: str):assert (has_literal or has_subimport or has_metadata or has_version_attr), f"{tag}: bnb.__version__ not exported"+++def test_bnb_optimizer2state_options_are_not_passed_positionally(tag: str):+ """QGaLoreAdamW8bit must not pass percentile_clipping / block_wise by position.++ bitsandbytes 0.50.0 removed both from Optimizer2State.__init__ (PR #1871), so positions+ 10 and 11 became max_unorm and skip_zeros. Arity still matched, nothing raised, and the+ optimiser silently received max_unorm=100 / skip_zeros=True. Since Q-GaLore zeroes+ p.data before the update, param_norm was 0, the unorm clip scaled every update to 0 and+ projected parameters stopped moving entirely.++ Checked here rather than at runtime because the failure is invisible on the installed+ version alone: it needs the signature from a version the test environment does not have.+ """+ src = fetch_text(+ "bitsandbytes-foundation/bitsandbytes",+ tag,+ "bitsandbytes/optim/optimizer.py",+ )+ if src is None:+ pytest.skip(f"{tag}: bitsandbytes/optim/optimizer.py missing")++ signature = first_match_signature(src, "Optimizer2State")+ if signature is None:+ pytest.skip(f"{tag}: could not read Optimizer2State.__init__ signature")++ removed = [n for n in ("percentile_clipping", "block_wise") if n not in signature]+ caller = (+ Path(__file__).resolve().parents[2] / "unsloth" / "optimizers" / "q_galore_adamw.py"+ ).read_text()++ call = _super_init_call(caller, "QGaLoreAdamW8bit")+ assert call is not None, "could not find QGaLoreAdamW8bit's super().__init__ call"++ # "adam" and params are positional on purpose; everything after them must be a keyword,+ # because bitsandbytes reorders the tail of this signature between minors.+ positional = [a for a in call.args if not isinstance(a, ast.Starred)]+ extra = positional[2:]+ assert not extra, (+ f"{tag}: QGaLoreAdamW8bit passes {len(extra)} argument(s) after params positionally. "+ f"{removed or 'Nothing'} was removed from Optimizer2State at this tag, so a positional "+ f"call lands values in whichever parameters now occupy those slots."+ )+ passed = {kw.arg for kw in call.keywords if kw.arg}+ assert "optim_bits" in passed, f"{tag}: optim_bits must be passed by name"+ for name in ("percentile_clipping", "block_wise"):+ if name in signature:+ continue+ assert name not in passed, (+ f"{tag}: Optimizer2State no longer accepts {name}, but it is still passed."+ )diff --git a/unsloth/optimizers/q_galore_adamw.py b/unsloth/optimizers/q_galore_adamw.pyindex 36aac62c1d5..b705a3d6d20 100644--- a/unsloth/optimizers/q_galore_adamw.py+++ b/unsloth/optimizers/q_galore_adamw.py@@ -12,6 +12,7 @@# Original paper: "Q-GaLore: Quantized GaLore with INT4 Projection and# Layer-Adaptive Low-Rank Gradients" (arXiv:2407.08296)+import inspectimport torchfrom typing import Optional, List@@ -80,19 +81,30 @@ class QGaLoreAdamW8bit(Optimizer2State):is_paged: bool = False,):_require_bnb()+ bnb_parameters = inspect.signature(Optimizer2State.__init__).parameters+ legacy_kwargs = {}+ for name, value, default in (+ ("percentile_clipping", percentile_clipping, 100),+ ("block_wise", block_wise, True),+ ):+ if name in bnb_parameters:+ legacy_kwargs[name] = value+ elif value != default:+ raise ValueError(+ f"This bitsandbytes version no longer supports {name}={value}; "+ f"use {name}={default}."+ )super().__init__("adam",params,- lr,- betas,- eps,- weight_decay,- 8, # optim_bits- None, # args- min_8bit_size,- percentile_clipping,- block_wise,+ lr = lr,+ betas = betas,+ eps = eps,+ weight_decay = weight_decay,+ optim_bits = 8,+ min_8bit_size = min_8bit_size,is_paged = is_paged,+ **legacy_kwargs,)@torch.no_grad()