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
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.pynew file mode 100644index 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.pyindex 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.pyindex 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 slowos.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 = Falseelse: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.pyindex 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 = {namefor 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_mapdiff --git a/unsloth/models/vision.py b/unsloth/models/vision.pyindex 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 = 0for 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.pyindex 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]: