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.

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.py
index 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 inspect
import pytest
import sys
import 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.py
index 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 ast
import re
+from pathlib import Path
import pytest
from 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.py
index 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 inspect
import torch
from 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()