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
Studio: preserve guidance for FLUX.1-dev single-file models (#17567)
oobabooga973811bb7dee
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex 752b8ff9da8..f74acca2f1b 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -52,6 +52,7 @@ from utils.hardware import clear_gpu_cachefrom .diffusion_content import (assert_local_pick_is_dit,content_variant_hint,+ inspect_checkpoint,local_pick_file,whole_pipeline_gguf_family,)@@ -10215,9 +10216,14 @@ class DiffusionBackend:or _cached_while_hub_unreachable(fetch_base, "transformer/config.json"),- # config is the family base's (2511); 2509 / original Edit lack its zero_cond_t+ # Header variant first: the config must match the file's tensors, not its name.**transformer_config_overrides_for(- fam, gguf_filename, repo_id, display_repo_id, base+ fam,+ inspect_checkpoint(single_file_path).variant,+ gguf_filename,+ repo_id,+ display_repo_id,+ base,),}# Before the prefix shim, which cannot wrap an unregistered class.diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.pyindex f852108e564..eac26bdeeff 100644--- a/studio/backend/core/inference/diffusion_families.py+++ b/studio/backend/core/inference/diffusion_families.py@@ -503,6 +503,12 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (),),checkpoint_variants = ("flux1-schnell", "flux1-krea-dev", "flux1-dev"),+ # Only schnell lacks guidance_in; either base config on the other variant's file drops or misses it.+ transformer_config_variants = tuple(+ (f"{prefix}-{model}", (("guidance_embeds", guided),))+ for model, guided in (("schnell", False), ("krea-dev", True), ("dev", True))+ for prefix in ("flux.1", "flux1", "flux-1", "flux")+ ),filter_reduction_configs_archs = _FLUX1_REDUCTION_RACE_ARCHS,cudnn_benchmark = False,pipeline_class = "FluxPipeline",diff --git a/studio/backend/tests/test_diffusion_flux1_guidance_config.py b/studio/backend/tests/test_diffusion_flux1_guidance_config.pynew file mode 100644index 00000000000..63a1f945512--- /dev/null+++ b/studio/backend/tests/test_diffusion_flux1_guidance_config.py@@ -0,0 +1,116 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""FLUX.1 dev / Krea-dev single files assembled on the schnell base keep their guidance embedder."""++from __future__ import annotations++import json++import pytest++from core.inference.diffusion_content import inspect_checkpoint+from core.inference.diffusion_families import (+ detect_family,+ transformer_config_overrides_for,+ transformer_variant_differs_from_base,+)++_GUIDED = {"guidance_embeds": True}+_UNGUIDED = {"guidance_embeds": False}+_SCHNELL = "black-forest-labs/FLUX.1-schnell"+_DEV = "black-forest-labs/FLUX.1-dev"+++ "identifiers, expected",+ [+ (("flux.1-dev", "my-model.gguf", "/models/unet", _SCHNELL), _GUIDED),+ (("flux.1-dev", "flux1-schnell-fp8.safetensors", "/models", _SCHNELL), _GUIDED),+ (("flux.1-schnell", "flux1-dev-Q4_K_M.gguf", "/models", _SCHNELL), _UNGUIDED),+ ((None, "flux1-dev-Q4_K_M.gguf", "/models", _SCHNELL), _GUIDED),+ ((None, "flux1_krea_dev_fp8_scaled.safetensors", "/models", _SCHNELL), _GUIDED),+ ((None, "FLUX.1-Krea-dev.safetensors", "/models", _SCHNELL), _GUIDED),+ ((None, "flux1-schnell-Q4_K_S.gguf", "unsloth/FLUX.1-schnell-GGUF", _SCHNELL), _UNGUIDED),+ ((None, None, "unsloth/FLUX.1-dev-GGUF", _DEV), _GUIDED),+ (("flux.1-schnell", "my-model.gguf", "/models", _DEV), _UNGUIDED),+ ((None, "model.gguf", "/models/unet", _SCHNELL), _UNGUIDED),+ ],+)+def test_flux1_transformer_config_per_variant(identifiers, expected):+ fam = detect_family("flux.1")+ assert fam.base_repo == _SCHNELL+ assert transformer_config_overrides_for(fam, *identifiers) == expected+++def test_flux1_variant_mismatch_detection_is_unchanged():+ fam = detect_family("flux.1")+ assert transformer_variant_differs_from_base(fam, _SCHNELL, "flux1-dev-Q4_K_M.gguf")+ assert not transformer_variant_differs_from_base(fam, _SCHNELL, "flux1-schnell-Q4_K_S.gguf")+ assert not transformer_variant_differs_from_base(fam, None, "flux1-dev-Q4_K_M.gguf")+++_TINY = dict(+ patch_size = 1,+ in_channels = 64, # what the header classifier reads as plain FLUX.1 (not Fill / Depth)+ num_layers = 1,+ num_single_layers = 1,+ attention_head_dim = 8,+ num_attention_heads = 2,+ joint_attention_dim = 16,+ pooled_projection_dim = 8,+ axes_dims_rope = [2, 2, 4],+)+++def _forward(model, torch, guidance):+ gen = torch.Generator().manual_seed(0)+ with torch.no_grad():+ return model(+ hidden_states = torch.randn(1, 4, 64, generator = gen),+ encoder_hidden_states = torch.randn(1, 3, 16, generator = gen),+ pooled_projections = torch.randn(1, 8, generator = gen),+ timestep = torch.tensor([0.5]),+ img_ids = torch.zeros(4, 3),+ txt_ids = torch.zeros(3, 3),+ # FluxPipeline passes guidance only when the config enables the embedder.+ guidance = torch.tensor([guidance]) if model.config.guidance_embeds else None,+ ).sample++[email protected]("file_guided", [True, False])+def test_the_config_follows_the_file_not_the_base(tmp_path, file_guided):+ torch = pytest.importorskip("torch")+ diffusers = pytest.importorskip("diffusers")+ save_file = pytest.importorskip("safetensors.torch").save_file++ base = tmp_path / "base"+ (base / "transformer").mkdir(parents = True)+ (base / "transformer" / "config.json").write_text(+ json.dumps(+ {"_class_name": "FluxTransformer2DModel", "guidance_embeds": not file_guided, **_TINY}+ )+ )+ torch.manual_seed(0)+ src = diffusers.FluxTransformer2DModel(guidance_embeds = file_guided, **_TINY)+ path = tmp_path / "renamed.safetensors"+ save_file({k: v.contiguous() for k, v in src.state_dict().items()}, str(path))++ variant = inspect_checkpoint(str(path)).variant+ assert variant == ("flux.1-dev" if file_guided else "flux.1-schnell")+ fam = detect_family("flux.1")+ overrides = transformer_config_overrides_for(+ fam, variant, path.name, str(tmp_path), _SCHNELL if file_guided else _DEV+ )+ model = diffusers.FluxTransformer2DModel.from_single_file(+ str(path),+ config = str(base),+ subfolder = "transformer",+ torch_dtype = torch.float32,+ **overrides,+ )+ assert model.config.guidance_embeds == file_guided+ for (name, got), want in zip(model.state_dict().items(), src.state_dict().values()):+ assert torch.equal(got, want), name+ if file_guided:+ assert not torch.allclose(_forward(model, torch, 1.0), _forward(model, torch, 3.5))