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.

DeepSeek-V4.1 (transformers port): load, place and train it with LoRA / QLoRA (#17625)

Daniel Han3221ed08b084
diff --git a/tests/test_deepseek_v41_lora_coverage.py b/tests/test_deepseek_v41_lora_coverage.py
new file mode 100644
index 00000000000..7d2f7c10281
--- /dev/null
+++ b/tests/test_deepseek_v41_lora_coverage.py
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team.
+"""DeepSeek-V4.1 (community port) LoRA / QLoRA load rules: grouped o_a_proj stays 16-bit, padding-free is refused."""
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+
+def test_4bit_keeps_the_grouped_output_projection_in_16bit():
+ from unsloth.models.vision import _architecture_skip_modules
+
+ # bitsandbytes swaps any nn.Linear subclass for a plain Linear4bit, dropping the per-group forward.
+ for model_types in (
+ ["deepseek_v41"],
+ ["deepseek_v41", "deepseek_v41_text"],
+ ["deepseek_v41_text"],
+ ):
+ assert "o_a_proj" in _architecture_skip_modules(model_types)
+ assert "o_a_proj" not in _architecture_skip_modules(["deepseek_v4"])
+ assert _architecture_skip_modules(["llama"]) == []
+
+
+def test_padding_free_is_refused_for_deepseek_v41():
+ from unsloth.utils.packing import packing_boundary_blocker
+
+ # Engram n-grams and the CSA2 compressor run over the whole row, ignoring packed boundaries.
+ for model_type in ("deepseek_v41", "deepseek_v41_text"):
+ assert packing_boundary_blocker(None, (model_type,)) == model_type
+
+ class DeepseekV41NgramHashState(torch.nn.Module):
+ pass
+
+ holder = torch.nn.Module()
+ holder.hash_state = DeepseekV41NgramHashState()
+ assert packing_boundary_blocker(holder) == "DeepseekV41NgramHashState"
+ assert packing_boundary_blocker(None, ("llama",)) is None
+
+
+def test_vision_config_without_image_text_class_resolves_to_causal_lm():
+ import importlib.util
+
+ if importlib.util.find_spec("transformers.models.deepseek_v41") is None:
+ pytest.skip("needs the DeepSeek-V4.1 transformers port")
+ from transformers import AutoModelForCausalLM, AutoModelForImageTextToText
+ from transformers.models.deepseek_v41.configuration_deepseek_v41 import DeepseekV41Config
+
+ from unsloth.models._utils import resolve_model_class
+
+ # The composite config carries a vision_config (so the loader calls it a VLM), but the port maps only a
+ # causal LM; loader.py now falls back to it instead of raising "Unrecognized configuration class".
+ config = DeepseekV41Config(text_config = {"num_hidden_layers": 4, "num_nextn_predict_layers": 0})
+ assert resolve_model_class(AutoModelForImageTextToText, config) is None
+ assert resolve_model_class(AutoModelForCausalLM, config).__name__ == "DeepseekV41ForCausalLM"
+ import re
+
+ import unsloth.models.loader as loader_module
+
+ with open(loader_module.__file__) as handle:
+ source = handle.read()
+ assert re.search(r"auto_model = AutoModelForCausalLM\s+is_vlm = False", source)
+
+
+def test_deepseek_v41_blocks_are_not_region_compiled():
+ from unsloth.models import _block_compile
+ assert "DeepseekV41DecoderLayer" in _block_compile._SKIP
+
+
+def test_no_placement_keeps_only_the_engram_table_off_the_device_map():
+ import importlib.util
+
+ if importlib.util.find_spec("transformers.models.deepseek_v41") is None:
+ pytest.skip("needs the DeepSeek-V4.1 transformers port")
+ from transformers.models.deepseek_v41.configuration_deepseek_v41 import DeepseekV41TextConfig
+ from transformers.models.deepseek_v41.modeling_deepseek_v41 import DeepseekV41ForCausalLM
+
+ from unsloth.models.loader_utils import exclude_no_placement_params, no_placement_tensor_names
+
+ config = DeepseekV41TextConfig(
+ vocab_size = 256,
+ hidden_size = 64,
+ num_hidden_layers = 4,
+ num_attention_heads = 2,
+ head_dim = 64,
+ qk_rope_head_dim = 16,
+ q_lora_rank = 32,
+ o_groups = 2,
+ o_lora_rank = 16,
+ moe_intermediate_size = 32,
+ n_routed_experts = 4,
+ num_experts_per_tok = 2,
+ compress_ratios = [0, 0, 2, 1],
+ kv_source_layer_ids = [2, 3],
+ index_source_layer_ids = [2, 3],
+ candidate_source_layer_id = 3,
+ index_n_heads = 2,
+ index_head_dim = 32,
+ hc_mult = 2,
+ engram_layer_ids = [1],
+ engram_num_embeddings = [64],
+ engram_head_dim = 32,
+ engram_vocab_size = 3,
+ engram_n_heads = 2,
+ engram_compressed_vocab_size = 8,
+ num_nextn_predict_layers = 0,
+ )
+ with torch.device("meta"):
+ model = DeepseekV41ForCausalLM(config)
+ # `_no_placement_params = ["weight", "weight_scale_inv"]` is relative to the no-split engram table; a suffix
+ # match kept every weight of the model on CPU.
+ assert no_placement_tensor_names(model) == {
+ "model.engram_tables.1.weight",
+ "model.engram_tables.1.weight_scale_inv",
+ }
+ device_map = exclude_no_placement_params({"": 0}, DeepseekV41ForCausalLM, config)
+ assert "model.engram_tables" not in device_map and device_map.get("lm_head") == 0
+ assert device_map.get("model.layers") == 0 and "model.engram_tables.1" not in device_map
+
+
+def test_deepseek_v41_loads_with_model_compile_disabled():
+ import re
+
+ import unsloth.models.loader as loader_module
+
+ with open(loader_module.__file__) as handle:
+ source = handle.read()
+ branch = re.search(
+ r'elif "deepseek_v41," in model_types_all or "deepseek_v41_text," in model_types_all:(.*?)elif "csm"',
+ source,
+ re.S,
+ )
+ assert branch and 'os.environ["UNSLOTH_COMPILE_DISABLE"] = "partial"' in branch.group(1)
+ # The trailing comma keeps deepseek_v4 (and any other prefix) out of the branch.
+ assert "deepseek_v41," not in "deepseek_v4,"
diff --git a/unsloth/models/_block_compile.py b/unsloth/models/_block_compile.py
index 278867a88cf..aa32c02cb0e 100644
--- a/unsloth/models/_block_compile.py
+++ b/unsloth/models/_block_compile.py
@@ -715,7 +715,10 @@ def _region_recompile_limit(kinds):
# gpt-oss builds its flex mask inside attention: the block broke and recompiled per length.
-_SKIP = {"GptOssDecoderLayer"}
+# DeepSeek-V4.1 port: the CSA2 top-k gather is [B, S, min(index_topk, T), D]; Inductor's backward codegen fails on the
+# unbound symbol ("For Min(4, s24), expected [s24] to have been codegen-ed", torch 2.14). Its layers also share a
+# per-forward group-state dict that gradient checkpointing replays per layer.
+_SKIP = {"GptOssDecoderLayer", "DeepseekV41DecoderLayer"}
def _enabled():
diff --git a/unsloth/models/loader.py b/unsloth/models/loader.py
index 5db938280da..42e70e6efb3 100644
--- a/unsloth/models/loader.py
+++ b/unsloth/models/loader.py
@@ -2869,6 +2869,10 @@ class FastModel(FastBaseModel):
raise RuntimeError(
"Unsloth: Cohere's Command model only works on transformers >= 4.50.0." + NIGHTLY
)
+ elif "deepseek_v41," in model_types_all or "deepseek_v41_text," in model_types_all:
+ # DeepSeek-V4.1 port: under gradient checkpointing a compiled helper inside a layer (rope, mHC, LoRA
+ # forwards) ran compiled in the forward and not in the recompute, and the saved tensors no longer matched.
+ os.environ["UNSLOTH_COMPILE_DISABLE"] = "partial"
elif "csm" in model_types_all:
os.environ["UNSLOTH_COMPILE_DISABLE"] = "partial" # Inference is too slow
os.environ["UNSLOTH_DISABLE_STATIC_GENERATION"] = "1" # Sesame fails
@@ -3387,6 +3391,19 @@ class FastModel(FastBaseModel):
or _resolve_audio_auto_model(model_config, **_probe_hub_kwargs)
or auto_model
)
+ # A vision_config with only a causal-LM class mapped (the DeepSeek-V4.1 port builds no vision
+ # tower yet): the image-text auto class would raise "Unrecognized configuration class".
+ if (
+ auto_model is AutoModelForVision2Seq
+ and resolve_model_class(auto_model, model_config, **_probe_hub_kwargs)
+ is None
+ and resolve_model_class(
+ AutoModelForCausalLM, model_config, **_probe_hub_kwargs
+ )
+ is not None
+ ):
+ auto_model = AutoModelForCausalLM
+ is_vlm = False
else:
auto_model = _resolve_non_vlm_auto_model(model_config, **_probe_hub_kwargs)
diff --git a/unsloth/models/loader_utils.py b/unsloth/models/loader_utils.py
index 99fe4be74cc..c1ca022e464 100644
--- a/unsloth/models/loader_utils.py
+++ b/unsloth/models/loader_utils.py
@@ -620,6 +620,30 @@ def _single_device_index(device_map):
return None
+def no_placement_matcher(model, names = None):
+ """Predicate: is this tensor name one of `model._no_placement_params`? transformers reads the names relative to a
+ `_no_split_modules` module: a bare name ("weight", DeepSeek-V4.1's engram table) matches only a direct tensor of
+ such a module (a suffix match would take every weight in the model); a dotted one (Qwen4Exp's
+ "ple.ple_embedding.ngram_embedding.weight") keeps the suffix match."""
+ names = list(getattr(model, "_no_placement_params", None) or [] if names is None else names)
+ dotted = [n for n in names if "." in n]
+ bare = {n for n in names if "." not in n}
+ roots = set()
+ if bare:
+ no_split = set(getattr(model, "_no_split_modules", None) or [])
+ roots = {
+ path for path, module in model.named_modules() if type(module).__name__ in no_split
+ }
+
+ def match(name):
+ if any(name == n or name.endswith("." + n) for n in dotted):
+ return True
+ owner, _, leaf = name.rpartition(".")
+ return leaf in bare and owner in roots
+
+ return match
+
+
def no_placement_tensor_names(model):
"""Every tensor name under a module owning one of the model's `_no_placement_params`."""
names = getattr(model, "_no_placement_params", None)
@@ -628,11 +652,8 @@ def no_placement_tensor_names(model):
tensors = list(model.named_parameters(remove_duplicate = False)) + list(
model.named_buffers(remove_duplicate = False)
)
- owners = {
- name.rsplit(".", 1)[0]
- for name, _ in tensors
- if any(name == n or name.endswith("." + n) for n in names)
- }
+ match = no_placement_matcher(model, names)
+ owners = {name.rsplit(".", 1)[0] for name, _ in tensors if match(name)}
return {name for name, _ in tensors if any(name.startswith(o + ".") for o in owners)}
@@ -662,10 +683,11 @@ def exclude_no_placement_params(device_map, model_class, config):
f"Unsloth: could not build {model_class.__name__} on meta to place {names} ({error})."
)
return device_map
+ match = no_placement_matcher(meta, names)
matched = {
name
for name, _ in list(meta.named_parameters()) + list(meta.named_buffers())
- if any(name == n or name.endswith("." + n) for n in names)
+ if match(name)
}
if not matched:
return device_map
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index f98adb3636f..5f2b57f593c 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -701,10 +701,10 @@ def _hook_no_placement_ancestors(model):
}
if len(placed_devices) < 2:
return 0
- names = getattr(model, "_no_placement_params", None) or []
- owners = {
- n.rsplit(".", 1)[0] for n in unplaced if any(n == x or n.endswith("." + x) for x in names)
- }
+ from .loader_utils import no_placement_matcher
+
+ match = no_placement_matcher(model)
+ owners = {n.rsplit(".", 1)[0] for n in unplaced if match(n)}
skip_keys = getattr(model, "_skip_keys_device_placement", None)
hooked = 0
for owner in owners:
@@ -3279,6 +3279,10 @@ def _architecture_skip_modules(model_types):
)
)
skip.extend(f"encoder.layers.{i}.attention" for i in range(48))
+ # DeepSeek-V4.1's o_a_proj is a grouped nn.Linear (G weight blocks applied per head group); bitsandbytes swaps it
+ # for a plain Linear4bit whose forward multiplies every group by the whole weight.
+ if any(mt.startswith("deepseek_v41") for mt in model_types):
+ skip.append("o_a_proj")
# Gemma 3n AltUp clamps prediction_coefs.weight.data in place every training step, which fails on packed
# uint8 weights; the same four modules unsloth/gemma-3n-*-unsloth-bnb-4bit keeps in 16-bit.
# transformers 5 matches a skip key as a suffix of each Linear's name, so the ModuleList children are listed too.
diff --git a/unsloth/utils/packing.py b/unsloth/utils/packing.py
index 31e08f98ea5..9266dd39467 100644
--- a/unsloth/utils/packing.py
+++ b/unsloth/utils/packing.py
@@ -477,10 +477,19 @@ def _stateful_mixer_kind(module) -> Optional[str]:
_PACKING_BOUNDARY_BLIND_MODULES = (
"DeepseekV4CSACompressor",
"DeepseekV4HCACompressor",
+ # DeepSeek-V4.1 port: engram n-grams hash across the whole row; the compressor pools row-wide token counts.
+ "DeepseekV41NgramHashState",
+ "DeepseekV41Compressor",
"ZayaCCAProjection",
"RecurrentGemmaRglru",
)
-_PACKING_BOUNDARY_BLIND_MODEL_TYPES = ("deepseek_v4", "zaya", "recurrent_gemma")
+_PACKING_BOUNDARY_BLIND_MODEL_TYPES = (
+ "deepseek_v4",
+ "deepseek_v41",
+ "deepseek_v41_text",
+ "zaya",
+ "recurrent_gemma",
+)
def packing_boundary_blocker(model, model_types = ()) -> Optional[str]: