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.

Studio: load ComfyUI Krea-2 and HunyuanImage-2.1 single-file DiTs (#12885)

Daniel Hand1a38621f9c4
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index bc2180769cd..0e3d6a3a54b 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -263,6 +263,10 @@ from .diffusion_precision import (
from .diffusion_te_prequant import te_prequant_pipe_kwargs
from .diffusion_fast_load import start_load_prefetch, stop_prefetch, te_precast_components
from .diffusion_flow_shift import apply_comfy_flow_shift
+from .diffusion_single_file_converters import (
+ CONVERTERS as _ORIGINAL_LAYOUT_CONVERTERS,
+ load_original_layout_transformer,
+)
from .diffusion_text_length import (
IDEOGRAM4_COMFY_GUIDANCE,
ideogram4_comfy_guidance_schedule,
@@ -1399,6 +1403,7 @@ def _qwen_image_21_checkpoint_to_diffusers(checkpoint = None, **kwargs):
# there: the pinned sd.cpp prebuilt carries no Windows GPU build at all.
_UNREGISTERED_SINGLE_FILE_CLASSES: dict = {
"QwenImage21Transformer2DModel": _qwen_image_21_checkpoint_to_diffusers,
+ **_ORIGINAL_LAYOUT_CONVERTERS,
}
@@ -6857,10 +6862,18 @@ class DiffusionBackend:
)
comfy_compile = comfy_torchao_quantized(transformer)
else:
- # A safetensors single-file (fp8) carries its own dtype: no GGUF dequant config.
- transformer = transformer_cls.from_single_file(
- single_file_path, **sf_kwargs
- )
+ if kind != "gguf" and not hasattr(
+ transformer_cls, "from_single_file"
+ ):
+ # Krea 2: diffusers gives the class no single-file loader at all.
+ transformer = load_original_layout_transformer(
+ transformer_cls, single_file_path, sf_kwargs, logger
+ )
+ else:
+ # A safetensors single-file (fp8) carries its own dtype: no GGUF dequant config.
+ transformer = transformer_cls.from_single_file(
+ single_file_path, **sf_kwargs
+ )
if kind == "gguf":
_dequantize_gguf_outside_linears(transformer, dtype, logger)
self._raise_if_load_cancelled(_load_token)
@@ -6898,6 +6911,12 @@ class DiffusionBackend:
}
if hf_token:
pipe_kwargs["token"] = hf_token
+ if fam.name == "hunyuanimage-2.1" and getattr(
+ getattr(transformer, "config", None), "guidance_embeds", False
+ ):
+ # Distilled file on the base repo: the base's CFG guiders would double every step.
+ pipe_kwargs["guider"] = None
+ pipe_kwargs["ocr_guider"] = None
if fam.name == HIDREAM_FAMILY_NAME:
pipe_kwargs.update(
hidream_te4_kwargs(
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index c6c5c752885..a23fe8675ce 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -716,6 +716,12 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
cfg_kwarg = "distilled_guidance_scale",
aliases = ("hunyuanimage-2.1-diffusers", "hunyuanimage2.1"),
fp16_incompatible = True,
+ # Distilled MeanFlow files: two extra embedders, shift 4. The catch-all row marks the base as another variant.
+ transformer_config_variants = (
+ ("distilled", (("guidance_embeds", True), ("use_meanflow", True))),
+ ("hunyuanimage", ()),
+ ),
+ comfy_flow_shift_variants = (("distilled", 4.0),),
),
DiffusionFamily(
name = "hidream-i1",
diff --git a/studio/backend/core/inference/diffusion_single_file_converters.py b/studio/backend/core/inference/diffusion_single_file_converters.py
new file mode 100644
index 00000000000..7c581c289c8
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_single_file_converters.py
@@ -0,0 +1,419 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Original-layout (ComfyUI / reference repo) single files -> diffusers state dicts for Krea 2 and
+HunyuanImage 2.1, which diffusers ships without a single-file converter.
+
+Rules only rename, split rows or reorder whole rows, never columns: ``diffusion_comfy_quant`` traces
+each int8 / fp8 row (and GGUF block) back to its source and refuses anything else. Unknown keys raise.
+No module-level torch import: ``diffusion.py`` imports this on every load.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_CONTAINER_PREFIXES = ("model.diffusion_model.", "model.model.", "diffusion_model.")
+
+
+def _strip_prefix(key: str) -> str:
+ for prefix in _CONTAINER_PREFIXES:
+ if key.startswith(prefix):
+ return key[len(prefix) :]
+ return key
+
+
+def _plain_1d(value: Any) -> Any:
+ """Dequantise a 1-D GGUF tensor: diffusers only dequantises inside swapped Linears, so a packed
+ norm / modulation vector would reach the forward as raw bytes."""
+ quant_shape = getattr(value, "quant_shape", None)
+ if quant_shape is not None and len(quant_shape) == 1:
+ from diffusers.quantizers.gguf.utils import dequantize_gguf_tensor
+ return dequantize_gguf_tensor(value)
+ return value
+
+
+def _split_rows(key: str, value: Any, sizes: tuple) -> list:
+ rows = int(value.shape[0])
+ if rows != sum(sizes):
+ raise ValueError(
+ f"{key}: {rows} rows cannot be split into {list(sizes)}; this is not the expected layout"
+ )
+ out, start = [], 0
+ for size in sizes:
+ out.append(value[start : start + size])
+ start += size
+ return out
+
+
+_KREA2_TOP = {
+ "first.weight": "img_in.weight",
+ "first.bias": "img_in.bias",
+ "tmlp.0.weight": "time_embed.linear_1.weight",
+ "tmlp.0.bias": "time_embed.linear_1.bias",
+ "tmlp.2.weight": "time_embed.linear_2.weight",
+ "tmlp.2.bias": "time_embed.linear_2.bias",
+ "tproj.1.weight": "time_mod_proj.weight",
+ "tproj.1.bias": "time_mod_proj.bias",
+ "txtmlp.0.scale": "txt_in.norm.weight",
+ "txtmlp.1.weight": "txt_in.linear_1.weight",
+ "txtmlp.1.bias": "txt_in.linear_1.bias",
+ "txtmlp.3.weight": "txt_in.linear_2.weight",
+ "txtmlp.3.bias": "txt_in.linear_2.bias",
+ "txtfusion.projector.weight": "text_fusion.projector.weight",
+ "last.linear.weight": "final_layer.linear.weight",
+ "last.linear.bias": "final_layer.linear.bias",
+ "last.norm.scale": "final_layer.norm.weight",
+ "last.modulation.lin": "final_layer.scale_shift_table",
+}
+
+_KREA2_BLOCK = {
+ "attn.wq.weight": "attn.to_q.weight",
+ "attn.wk.weight": "attn.to_k.weight",
+ "attn.wv.weight": "attn.to_v.weight",
+ "attn.wo.weight": "attn.to_out.0.weight",
+ "attn.gate.weight": "attn.to_gate.weight",
+ "attn.qknorm.qnorm.scale": "attn.norm_q.weight",
+ "attn.qknorm.knorm.scale": "attn.norm_k.weight",
+ "mlp.gate.weight": "ff.gate.weight",
+ "mlp.up.weight": "ff.up.weight",
+ "mlp.down.weight": "ff.down.weight",
+ "prenorm.scale": "norm1.weight",
+ "postnorm.scale": "norm2.weight",
+}
+
+_KREA2_BLOCK_RE = re.compile(
+ r"^(blocks|txtfusion\.layerwise_blocks|txtfusion\.refiner_blocks)\.(\d+)\.(.+)$"
+)
+_KREA2_BLOCK_STEM = {
+ "blocks": "transformer_blocks",
+ "txtfusion.layerwise_blocks": "text_fusion.layerwise_blocks",
+ "txtfusion.refiner_blocks": "text_fusion.refiner_blocks",
+}
+
+
+def krea2_checkpoint_to_diffusers(checkpoint: Any = None, **kwargs: Any) -> dict:
+ """Krea 2 original layout -> ``Krea2Transformer2DModel``. Renames, plus ``blocks.N.mod.lin``
+ ``[6 * hidden]`` viewed as ``scale_shift_table`` ``[6, hidden]`` (same six chunks, row-major)."""
+ converted: dict = {}
+ for raw_key, value in (checkpoint or {}).items():
+ key = _strip_prefix(raw_key)
+ if value is not None and getattr(value, "dim", lambda: 2)() == 1:
+ value = _plain_1d(value)
+ new = _KREA2_TOP.get(key)
+ if new is not None:
+ converted[new] = value
+ continue
+ match = _KREA2_BLOCK_RE.match(key)
+ if match is None:
+ raise ValueError(f"{raw_key}: not a Krea 2 transformer key this converter knows")
+ group, index, rest = match.groups()
+ stem = f"{_KREA2_BLOCK_STEM[group]}.{index}."
+ if group == "blocks" and rest == "mod.lin":
+ if value.dim() != 1 or value.shape[0] % 6:
+ raise ValueError(f"{raw_key}: expected a flat [6 * hidden] modulation table")
+ converted[stem + "scale_shift_table"] = value.reshape(6, -1)
+ continue
+ new = _KREA2_BLOCK.get(rest)
+ if new is None:
+ raise ValueError(f"{raw_key}: not a Krea 2 transformer key this converter knows")
+ converted[stem + new] = value
+ return converted
+
+
+_HYIMG_TOP = {
+ "img_in.proj": "x_embedder.proj",
+ "time_in.in_layer": "time_guidance_embed.timestep_embedder.linear_1",
+ "time_in.out_layer": "time_guidance_embed.timestep_embedder.linear_2",
+ # Guidance-distilled (distilled_guidance_scale) and MeanFlow (timestep_r) embedders: distilled only.
+ "guidance_in.in_layer": "time_guidance_embed.guidance_embedder.linear_1",
+ "guidance_in.out_layer": "time_guidance_embed.guidance_embedder.linear_2",
+ "time_r_in.in_layer": "time_guidance_embed.timestep_embedder_r.linear_1",
+ "time_r_in.out_layer": "time_guidance_embed.timestep_embedder_r.linear_2",
+ "txt_in.input_embedder": "context_embedder.proj_in",
+ "txt_in.t_embedder.in_layer": "context_embedder.time_text_embed.timestep_embedder.linear_1",
+ "txt_in.t_embedder.out_layer": "context_embedder.time_text_embed.timestep_embedder.linear_2",
+ "txt_in.c_embedder.in_layer": "context_embedder.time_text_embed.text_embedder.linear_1",
+ "txt_in.c_embedder.out_layer": "context_embedder.time_text_embed.text_embedder.linear_2",
+ "byt5_in.layernorm": "context_embedder_2.norm",
+ "byt5_in.fc1": "context_embedder_2.linear_1",
+ "byt5_in.fc2": "context_embedder_2.linear_2",
+ "byt5_in.fc3": "context_embedder_2.linear_3",
+ "final_layer.linear": "proj_out",
+}
+
+_HYIMG_REFINER = {
+ "norm1": "norm1",
+ "norm2": "norm2",
+ "self_attn.proj": "attn.to_out.0",
+ "mlp.0": "ff.net.0.proj",
+ "mlp.2": "ff.net.2",
+ "adaLN_modulation.1": "norm_out.linear",
+}
+
+_HYIMG_DOUBLE = {
+ "img_mod.lin": "norm1.linear",
+ "txt_mod.lin": "norm1_context.linear",
+ "img_attn.proj": "attn.to_out.0",
+ "txt_attn.proj": "attn.to_add_out",
+ "img_attn.norm.query_norm": "attn.norm_q",
+ "img_attn.norm.key_norm": "attn.norm_k",
+ "txt_attn.norm.query_norm": "attn.norm_added_q",
+ "txt_attn.norm.key_norm": "attn.norm_added_k",
+ "img_mlp.0": "ff.net.0.proj",
+ "img_mlp.2": "ff.net.2",
+ "txt_mlp.0": "ff_context.net.0.proj",
+ "txt_mlp.2": "ff_context.net.2",
+}
+
+_HYIMG_SINGLE = {
+ "linear2": "proj_out",
+ "modulation.lin": "norm.linear",
+ "norm.query_norm": "attn.norm_q",
+ "norm.key_norm": "attn.norm_k",
+}
+
+_HYIMG_QKV = {
+ # Fused rows are q, then k, then v.
+ "img_attn.qkv": ("attn.to_q", "attn.to_k", "attn.to_v"),
+ "txt_attn.qkv": ("attn.add_q_proj", "attn.add_k_proj", "attn.add_v_proj"),
+ "self_attn.qkv": ("attn.to_q", "attn.to_k", "attn.to_v"),
+}
+
+_HYIMG_REFINER_RE = re.compile(
+ r"^txt_in\.individual_token_refiner\.blocks\.(\d+)\.(.+)\.(weight|bias|scale)$"
+)
+_HYIMG_DOUBLE_RE = re.compile(r"^double_blocks\.(\d+)\.(.+)\.(weight|bias|scale)$")
+_HYIMG_SINGLE_RE = re.compile(r"^single_blocks\.(\d+)\.(.+)\.(weight|bias|scale)$")
+_HYIMG_TOP_RE = re.compile(r"^(.+)\.(weight|bias|scale)$")
+
+
+# Reference-repo names (Comfy-Org's bf16 file) -> the ComfyUI names the tables above use.
+_HYIMG_REFERENCE_NAMES = (
+ (re.compile(r"^((?:double_blocks\.\d+\.)(?:img|txt))_attn_(qkv|proj)\."), r"\1_attn.\2."),
+ (
+ re.compile(r"^((?:double_blocks\.\d+\.)(?:img|txt))_attn_q_norm\.weight$"),
+ r"\1_attn.norm.query_norm.scale",
+ ),
+ (
+ re.compile(r"^((?:double_blocks\.\d+\.)(?:img|txt))_attn_k_norm\.weight$"),
+ r"\1_attn.norm.key_norm.scale",
+ ),
+ (re.compile(r"^(single_blocks\.\d+\.)q_norm\.weight$"), r"\1norm.query_norm.scale"),
+ (re.compile(r"^(single_blocks\.\d+\.)k_norm\.weight$"), r"\1norm.key_norm.scale"),
+ (
+ re.compile(r"^(txt_in\.individual_token_refiner\.blocks\.\d+\.)self_attn_(qkv|proj)\."),
+ r"\1self_attn.\2.",
+ ),
+ (re.compile(r"\.(img_mlp|txt_mlp|mlp)\.fc1\."), r".\1.0."),
+ (re.compile(r"\.(img_mlp|txt_mlp|mlp)\.fc2\."), r".\1.2."),
+ (re.compile(r"\.(img_mod|txt_mod|modulation)\.linear\."), r".\1.lin."),
+ (re.compile(r"^(time_in|time_r_in|guidance_in|txt_in\.t_embedder)\.mlp\.0\."), r"\1.in_layer."),
+ (
+ re.compile(r"^(time_in|time_r_in|guidance_in|txt_in\.t_embedder)\.mlp\.2\."),
+ r"\1.out_layer.",
+ ),
+ (re.compile(r"^txt_in\.c_embedder\.linear_1\."), "txt_in.c_embedder.in_layer."),
+ (re.compile(r"^txt_in\.c_embedder\.linear_2\."), "txt_in.c_embedder.out_layer."),
+)
+
+
+def _hyimg_comfy_name(key: str) -> str:
+ for pattern, repl in _HYIMG_REFERENCE_NAMES:
+ key = pattern.sub(repl, key)
+ return key
+
+
+def _hyimg_param(suffix: str) -> str:
+ return "weight" if suffix == "scale" else suffix
+
+
+def hunyuanimage_checkpoint_to_diffusers(
+ checkpoint: Any = None,
+ config: Any = None,
+ **kwargs: Any,
+) -> dict:
+ """HunyuanImage 2.1 original layout (reference or ComfyUI naming, base or distilled) ->
+ ``HunyuanImageTransformer2DModel``. Fused ``qkv`` and single-block ``linear1`` (q, k, v, MLP in)
+ split by rows; ``final_layer.adaLN_modulation.1`` is (shift, scale), diffusers reads (scale, shift)."""
+ hidden = None
+ if config is not None:
+ try:
+ hidden = int(config["num_attention_heads"]) * int(config["attention_head_dim"])
+ except Exception: # noqa: BLE001 - derived from the tensors below instead
+ hidden = None
+ stripped = {_hyimg_comfy_name(_strip_prefix(k)): (k, v) for k, v in (checkpoint or {}).items()}
+ if hidden is None:
+ probe = stripped.get("img_in.proj.weight") or stripped.get("img_in.proj.bias")
+ if probe is None:
+ raise ValueError("not a HunyuanImage 2.1 checkpoint: no img_in.proj")
+ hidden = int(probe[1].shape[0])
+
+ converted: dict = {}
+ for key, (raw_key, value) in stripped.items():
+ if value is not None and getattr(value, "dim", lambda: 2)() == 1:
+ value = _plain_1d(value)
+
+ match = _HYIMG_REFINER_RE.match(key)
+ if match:
+ index, layer, suffix = match.groups()
+ stem = f"context_embedder.token_refiner.refiner_blocks.{index}."
+ if layer in _HYIMG_QKV:
+ for name, part in zip(
+ _HYIMG_QKV[layer], _split_rows(raw_key, value, (hidden,) * 3)
+ ):
+ converted[f"{stem}{name}.{suffix}"] = part
+ continue
+ new = _HYIMG_REFINER.get(layer)
+ if new is None:
+ raise ValueError(
+ f"{raw_key}: not a HunyuanImage 2.1 transformer key this converter knows"
+ )
+ converted[f"{stem}{new}.{_hyimg_param(suffix)}"] = value
+ continue
+
+ match = _HYIMG_DOUBLE_RE.match(key)
+ if match:
+ index, layer, suffix = match.groups()
+ stem = f"transformer_blocks.{index}."
+ if layer in _HYIMG_QKV:
+ for name, part in zip(
+ _HYIMG_QKV[layer], _split_rows(raw_key, value, (hidden,) * 3)
+ ):
+ converted[f"{stem}{name}.{suffix}"] = part
+ continue
+ new = _HYIMG_DOUBLE.get(layer)
+ if new is None:
+ raise ValueError(
+ f"{raw_key}: not a HunyuanImage 2.1 transformer key this converter knows"
+ )
+ converted[f"{stem}{new}.{_hyimg_param(suffix)}"] = value
+ continue
+
+ match = _HYIMG_SINGLE_RE.match(key)
+ if match:
+ index, layer, suffix = match.groups()
+ stem = f"single_transformer_blocks.{index}."
+ if layer == "linear1":
+ mlp = int(value.shape[0]) - 3 * hidden
+ if mlp <= 0:
+ raise ValueError(f"{raw_key}: too few rows for q, k, v and the MLP input")
+ names = ("attn.to_q", "attn.to_k", "attn.to_v", "proj_mlp")
+ for name, part in zip(
+ names, _split_rows(raw_key, value, (hidden, hidden, hidden, mlp))
+ ):
+ converted[f"{stem}{name}.{suffix}"] = part
+ continue
+ new = _HYIMG_SINGLE.get(layer)
+ if new is None:
+ raise ValueError(
+ f"{raw_key}: not a HunyuanImage 2.1 transformer key this converter knows"
+ )
+ converted[f"{stem}{new}.{_hyimg_param(suffix)}"] = value
+ continue
+
+ match = _HYIMG_TOP_RE.match(key)
+ if match:
+ layer, suffix = match.groups()
+ if layer == "final_layer.adaLN_modulation.1":
+ rows = int(value.shape[0])
+ if rows % 2:
+ raise ValueError(f"{raw_key}: an odd row count cannot hold (shift, scale)")
+ shift, scale = value[: rows // 2], value[rows // 2 :]
+ converted[f"norm_out.linear.{suffix}"] = _cat_rows(scale, shift)
+ continue
+ new = _HYIMG_TOP.get(layer)
+ if new is not None:
+ converted[f"{new}.{_hyimg_param(suffix)}"] = value
+ continue
+ raise ValueError(f"{raw_key}: not a HunyuanImage 2.1 transformer key this converter knows")
+ return converted
+
+
+def _cat_rows(first: Any, second: Any) -> Any:
+ """Concatenate two row blocks, keeping a ``GGUFParameter``'s quant type (whole blocks per row)."""
+ import torch
+
+ out = torch.cat([first, second], dim = 0)
+ quant_type = getattr(first, "quant_type", None)
+ if quant_type is not None and getattr(out, "quant_type", None) is None:
+ from diffusers.quantizers.gguf.utils import GGUFParameter
+ out = GGUFParameter(out, quant_type = quant_type)
+ return out
+
+
+CONVERTERS: dict = {
+ "Krea2Transformer2DModel": krea2_checkpoint_to_diffusers,
+ "HunyuanImageTransformer2DModel": hunyuanimage_checkpoint_to_diffusers,
+}
+
+
+def load_original_layout_transformer(
+ transformer_cls: Any,
+ path: str,
+ sf_kwargs: dict,
+ logger: Any = None,
+) -> Any:
+ """Load a plain original-layout safetensors file for a class without ``from_single_file``
+ (Krea 2 on diffusers 0.40). ``sf_kwargs`` = the ``from_single_file`` kwargs. Cast like
+ ``from_pretrained`` (``_keep_in_fp32_modules`` stay fp32); strict on keys and shapes."""
+ import torch
+ from accelerate import init_empty_weights
+ from diffusers.loaders import single_file_model as sfm
+ from safetensors.torch import load_file
+
+ kwargs = dict(sf_kwargs)
+ dtype = kwargs.pop("torch_dtype", None) or torch.bfloat16
+ config_repo = kwargs.pop("config", None)
+ if not isinstance(config_repo, str):
+ raise ValueError("an original-layout single file needs the base repo's transformer config")
+ config = transformer_cls.load_config(
+ config_repo,
+ subfolder = kwargs.pop("subfolder", None),
+ token = kwargs.pop("token", None),
+ cache_dir = kwargs.pop("cache_dir", None),
+ local_files_only = bool(kwargs.pop("local_files_only", False)),
+ )
+ expected, optional = transformer_cls._get_signature_keys(transformer_cls)
+ config.update({k: v for k, v in kwargs.items() if k in expected or k in optional})
+ entry = sfm.SINGLE_FILE_LOADABLE_CLASSES.get(transformer_cls.__name__) or {}
+ mapping_fn = entry.get("checkpoint_mapping_fn") or CONVERTERS.get(transformer_cls.__name__)
+ if mapping_fn is None:
+ raise ValueError(f"{transformer_cls.__name__} has no single-file converter")
+ with init_empty_weights():
+ model = transformer_cls.from_config(config)
+ wanted = model.state_dict()
+ state = load_file(str(path))
+ converted = state if set(state) == set(wanted) else mapping_fn(checkpoint = state, config = config)
+ del state
+ missing = sorted(set(wanted) - set(converted))
+ unexpected = sorted(set(converted) - set(wanted))
+ if missing or unexpected:
+ import os
+ name = os.path.basename(str(path))
+ raise ValueError(
+ f"{name} does not match {transformer_cls.__name__}: {len(missing)} missing "
+ f"(e.g. {missing[:1]}), {len(unexpected)} unused (e.g. {unexpected[:1]})"
+ )
+ keep = getattr(transformer_cls, "_keep_in_fp32_modules", None) or []
+ if isinstance(keep, str):
+ keep = [keep]
+ for key, value in converted.items():
+ want = torch.float32 if any(m in key.split(".") for m in keep) else dtype
+ if not value.is_floating_point():
+ continue
+ if tuple(value.shape) != tuple(wanted[key].shape):
+ raise ValueError(
+ f"{key}: {tuple(value.shape)} in the file, {tuple(wanted[key].shape)} in the model"
+ )
+ if value.dtype != want:
+ converted[key] = value.to(want)
+ model.load_state_dict(converted, strict = True, assign = True)
+ model.eval()
+ if logger is not None:
+ logger.info(
+ "diffusion.single_file: %s loaded from an original-layout file",
+ transformer_cls.__name__,
+ )
+ return model
diff --git a/studio/backend/tests/test_diffusion_single_file_krea2_hunyuanimage.py b/studio/backend/tests/test_diffusion_single_file_krea2_hunyuanimage.py
new file mode 100644
index 00000000000..c972693fb80
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_single_file_krea2_hunyuanimage.py
@@ -0,0 +1,654 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Krea 2 and HunyuanImage 2.1 original-layout single files (the ComfyUI ``diffusion_models`` files).
+
+diffusers ships both transformers without a single-file converter, so every ComfyUI file of either
+family failed before this with "has no single-file converter" (the ComfyUI int8 / fp8 loader) or
+"FromOriginalModelMixin is currently only compatible with ..." (plain files).
+
+The stubs below are written from the real files' headers by an inverse map kept here, independent of
+the converter's own tables: a tiny diffusers model's weights go out in the original layout and must
+come back bit-identical, under exactly the model's keys and shapes. The ComfyUI int8 loader is then
+run on a real-format int8 file of the same tiny model, which proves the converter only moves whole
+rows (that loader refuses anything else) and that the codes and scales survive exactly.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import struct
+from pathlib import Path
+
+import pytest
+import torch
+
+from core.inference import diffusion as studio
+from core.inference import diffusion_comfy_quant as cq
+from core.inference import diffusion_single_file_converters as conv
+from core.inference.diffusion_families import (
+ comfy_flow_shift_for,
+ detect_family,
+ transformer_config_overrides_for,
+ transformer_variant_differs_from_base,
+)
+
+diffusers = pytest.importorskip("diffusers")
+safetensors_torch = pytest.importorskip("safetensors.torch")
+
+KREA2_CFG = dict(
+ in_channels = 8,
+ num_layers = 2,
+ attention_head_dim = 16,
+ num_attention_heads = 2,
+ num_key_value_heads = 1,
+ intermediate_size = 48,
+ timestep_embed_dim = 16,
+ text_hidden_dim = 24,
+ num_text_layers = 3,
+ text_num_attention_heads = 2,
+ text_num_key_value_heads = 2,
+ text_intermediate_size = 40,
+ num_layerwise_text_blocks = 2,
+ num_refiner_text_blocks = 2,
+ axes_dims_rope = (4, 6, 6),
+)
+HY_CFG = dict(
+ in_channels = 8,
+ out_channels = 8,
+ num_attention_heads = 2,
+ attention_head_dim = 16,
+ num_layers = 2,
+ num_single_layers = 2,
+ num_refiner_layers = 2,
+ mlp_ratio = 4.0,
+ patch_size = (1, 1),
+ text_embed_dim = 24,
+ text_embed_2_dim = 20,
+ rope_axes_dim = (8, 8),
+)
+HY_DISTILLED = dict(guidance_embeds = True, use_meanflow = True)
+
+
+def _class(name):
+ cls = getattr(diffusers, name, None)
+ if cls is None:
+ pytest.skip(f"this diffusers does not ship {name}")
+ return cls
+
+
+def _tiny(name, cfg):
+ torch.manual_seed(0)
+ model = _class(name)(**cfg)
+ # Unique values everywhere, so a misplaced row or a swapped half cannot compare equal by accident.
+ with torch.no_grad():
+ for p in model.parameters():
+ p.copy_(torch.randn_like(p))
+ return model.eval()
+
+
+# ------------------------------------------------- inverse maps: diffusers -> original, from the real headers
+
+_KREA2_INV_BLOCK = {
+ "attn.to_q.weight": "attn.wq.weight",
+ "attn.to_k.weight": "attn.wk.weight",
+ "attn.to_v.weight": "attn.wv.weight",
+ "attn.to_out.0.weight": "attn.wo.weight",
+ "attn.to_gate.weight": "attn.gate.weight",
+ "attn.norm_q.weight": "attn.qknorm.qnorm.scale",
+ "attn.norm_k.weight": "attn.qknorm.knorm.scale",
+ "ff.gate.weight": "mlp.gate.weight",
+ "ff.up.weight": "mlp.up.weight",
+ "ff.down.weight": "mlp.down.weight",
+ "norm1.weight": "prenorm.scale",
+ "norm2.weight": "postnorm.scale",
+}
+_KREA2_INV_TOP = {
+ "img_in.weight": "first.weight",
+ "img_in.bias": "first.bias",
+ "time_embed.linear_1.weight": "tmlp.0.weight",
+ "time_embed.linear_1.bias": "tmlp.0.bias",
+ "time_embed.linear_2.weight": "tmlp.2.weight",
+ "time_embed.linear_2.bias": "tmlp.2.bias",
+ "time_mod_proj.weight": "tproj.1.weight",
+ "time_mod_proj.bias": "tproj.1.bias",
+ "txt_in.norm.weight": "txtmlp.0.scale",
+ "txt_in.linear_1.weight": "txtmlp.1.weight",
+ "txt_in.linear_1.bias": "txtmlp.1.bias",
+ "txt_in.linear_2.weight": "txtmlp.3.weight",
+ "txt_in.linear_2.bias": "txtmlp.3.bias",
+ "text_fusion.projector.weight": "txtfusion.projector.weight",
+ "final_layer.linear.weight": "last.linear.weight",
+ "final_layer.linear.bias": "last.linear.bias",
+ "final_layer.norm.weight": "last.norm.scale",
+ "final_layer.scale_shift_table": "last.modulation.lin",
+}
+
+
+def krea2_original(sd: dict) -> dict:
+ out = {}
+ for key, value in sd.items():
+ if key in _KREA2_INV_TOP:
+ out[_KREA2_INV_TOP[key]] = value.clone()
+ continue
+ m = re.match(
+ r"^(transformer_blocks|text_fusion\.layerwise_blocks|text_fusion\.refiner_blocks)\.(\d+)\.(.+)$",
+ key,
+ )
+ assert m, key
+ group, index, rest = m.groups()
+ stem = {
+ "transformer_blocks": "blocks",
+ "text_fusion.layerwise_blocks": "txtfusion.layerwise_blocks",
+ "text_fusion.refiner_blocks": "txtfusion.refiner_blocks",
+ }[group]
+ if rest == "scale_shift_table":
+ out[f"{stem}.{index}.mod.lin"] = value.reshape(
+ -1
+ ).clone() # stored flat in the real files
+ else:
+ out[f"{stem}.{index}.{_KREA2_INV_BLOCK[rest]}"] = value.clone()
+ return out
+
+
+def hy_original(sd: dict, hidden: int, comfy_names: bool) -> dict:
+ """Reference-repo naming (Comfy-Org's bf16 file) or ComfyUI naming under ``model.model.`` (its fp8 and
+ distilled files)."""
+ out: dict = {}
+
+ def put(name, value):
+ out[name] = value.clone()
+
+ def ref_or_comfy(ref, comfy):
+ return comfy if comfy_names else ref
+
+ mlp_in, mlp_out = ref_or_comfy("fc1", "0"), ref_or_comfy("fc2", "2")
+ lin = ref_or_comfy("linear", "lin")
+ used = set()
+
+ def take(key):
+ used.add(key)
+ return sd[key]
+
+ def emb(dst, src):
+ a, b = ref_or_comfy(("mlp.0", "mlp.2"), ("in_layer", "out_layer"))
+ for p in ("weight", "bias"):
+ put(f"{dst}.{a}.{p}", take(f"{src}.linear_1.{p}"))
+ put(f"{dst}.{b}.{p}", take(f"{src}.linear_2.{p}"))
+
+ for p in ("weight", "bias"):
+ put(f"img_in.proj.{p}", take(f"x_embedder.proj.{p}"))
+ put(f"txt_in.input_embedder.{p}", take(f"context_embedder.proj_in.{p}"))
+ put(f"byt5_in.layernorm.{p}", take(f"context_embedder_2.norm.{p}"))
+ for i in (1, 2, 3):
+ put(f"byt5_in.fc{i}.{p}", take(f"context_embedder_2.linear_{i}.{p}"))
+ put(f"final_layer.linear.{p}", take(f"proj_out.{p}"))
+ scale, shift = take(f"norm_out.linear.{p}").chunk(2, dim = 0)
+ put(f"final_layer.adaLN_modulation.1.{p}", torch.cat([shift, scale]))
+ emb("time_in", "time_guidance_embed.timestep_embedder")
+ if "time_guidance_embed.guidance_embedder.linear_1.weight" in sd:
+ emb("guidance_in", "time_guidance_embed.guidance_embedder")
+ if "time_guidance_embed.timestep_embedder_r.linear_1.weight" in sd:
+ emb("time_r_in", "time_guidance_embed.timestep_embedder_r")
+ emb("txt_in.t_embedder", "context_embedder.time_text_embed.timestep_embedder")
+ # c_embedder has its own naming in the reference repo: linear_1 / linear_2
+ for p in ("weight", "bias"):
+ a, b = ref_or_comfy(("linear_1", "linear_2"), ("in_layer", "out_layer"))
+ put(
+ f"txt_in.c_embedder.{a}.{p}",
+ take(f"context_embedder.time_text_embed.text_embedder.linear_1.{p}"),
+ )
+ put(
+ f"txt_in.c_embedder.{b}.{p}",
+ take(f"context_embedder.time_text_embed.text_embedder.linear_2.{p}"),
+ )
+
+ n_ref = len(
+ {
+ k.split(".")[3]
+ for k in sd
+ if k.startswith("context_embedder.token_refiner.refiner_blocks.")
+ }
+ )
+ for i in range(n_ref):
+ s, d = (
+ f"context_embedder.token_refiner.refiner_blocks.{i}.",
+ f"txt_in.individual_token_refiner.blocks.{i}.",
+ )
+ qkv, proj = ref_or_comfy(
+ ("self_attn_qkv", "self_attn_proj"), ("self_attn.qkv", "self_attn.proj")
+ )
+ for p in ("weight", "bias"):
+ put(f"{d}norm1.{p}", take(f"{s}norm1.{p}"))
+ put(f"{d}norm2.{p}", take(f"{s}norm2.{p}"))
+ put(f"{d}{qkv}.{p}", torch.cat([take(f"{s}attn.to_{x}.{p}") for x in "qkv"]))
+ put(f"{d}{proj}.{p}", take(f"{s}attn.to_out.0.{p}"))
+ put(f"{d}mlp.{mlp_in}.{p}", take(f"{s}ff.net.0.proj.{p}"))
+ put(f"{d}mlp.{mlp_out}.{p}", take(f"{s}ff.net.2.{p}"))
+ put(f"{d}adaLN_modulation.1.{p}", take(f"{s}norm_out.linear.{p}"))
+
+ n_double = len({k.split(".")[1] for k in sd if k.startswith("transformer_blocks.")})
+ for i in range(n_double):
+ s, d = f"transformer_blocks.{i}.", f"double_blocks.{i}."
+ for side, q, k, v, o, nq, nk, mod, ff in (
+ ("img", "to_q", "to_k", "to_v", "to_out.0", "norm_q", "norm_k", "norm1", "ff"),
+ (
+ "txt",
+ "add_q_proj",
+ "add_k_proj",
+ "add_v_proj",
+ "to_add_out",
+ "norm_added_q",
+ "norm_added_k",
+ "norm1_context",
+ "ff_context",
+ ),
+ ):
+ attn_qkv = ref_or_comfy(f"{side}_attn_qkv", f"{side}_attn.qkv")
+ attn_proj = ref_or_comfy(f"{side}_attn_proj", f"{side}_attn.proj")
+ for p in ("weight", "bias"):
+ put(f"{d}{attn_qkv}.{p}", torch.cat([take(f"{s}attn.{x}.{p}") for x in (q, k, v)]))
+ put(f"{d}{attn_proj}.{p}", take(f"{s}attn.{o}.{p}"))
+ put(f"{d}{side}_mod.{lin}.{p}", take(f"{s}{mod}.linear.{p}"))
+ put(f"{d}{side}_mlp.{mlp_in}.{p}", take(f"{s}{ff}.net.0.proj.{p}"))
+ put(f"{d}{side}_mlp.{mlp_out}.{p}", take(f"{s}{ff}.net.2.{p}"))
+ put(
+ ref_or_comfy(
+ f"{d}{side}_attn_q_norm.weight", f"{d}{side}_attn.norm.query_norm.scale"
+ ),
+ take(f"{s}attn.{nq}.weight"),
+ )
+ put(
+ ref_or_comfy(
+ f"{d}{side}_attn_k_norm.weight", f"{d}{side}_attn.norm.key_norm.scale"
+ ),
+ take(f"{s}attn.{nk}.weight"),
+ )
+
+ n_single = len({k.split(".")[1] for k in sd if k.startswith("single_transformer_blocks.")})
+ for i in range(n_single):
+ s, d = f"single_transformer_blocks.{i}.", f"single_blocks.{i}."
+ for p in ("weight", "bias"):
+ put(
+ f"{d}linear1.{p}",
+ torch.cat(
+ [take(f"{s}attn.to_{x}.{p}") for x in "qkv"] + [take(f"{s}proj_mlp.{p}")]
+ ),
+ )
+ put(f"{d}linear2.{p}", take(f"{s}proj_out.{p}"))
+ put(f"{d}modulation.{lin}.{p}", take(f"{s}norm.linear.{p}"))
+ put(
+ ref_or_comfy(f"{d}q_norm.weight", f"{d}norm.query_norm.scale"),
+ take(f"{s}attn.norm_q.weight"),
+ )
+ put(
+ ref_or_comfy(f"{d}k_norm.weight", f"{d}norm.key_norm.scale"),
+ take(f"{s}attn.norm_k.weight"),
+ )
+
+ assert used == set(sd), sorted(set(sd) - used)[:5] # the inverse covers the whole model
+ if comfy_names:
+ out = {"model.model." + k: v for k, v in out.items()}
+ return out
+
+
+def _assert_round_trip(model, converted):
+ want = model.state_dict()
+ assert set(converted) == set(want), (
+ sorted(set(want) - set(converted))[:5],
+ sorted(set(converted) - set(want))[:5],
+ )
+ for key, value in want.items():
+ assert tuple(converted[key].shape) == tuple(value.shape), key
+ assert torch.equal(converted[key], value), key
+ # And the model takes it strictly.
+ model.load_state_dict(converted, strict = True)
+
+
+# ------------------------------------------------------------------------------------------ key maps, strict
+
+
+def test_krea2_original_layout_round_trips_bit_identical():
+ model = _tiny("Krea2Transformer2DModel", KREA2_CFG)
+ original = krea2_original(model.state_dict())
+ # The real files' top-level names, from Comfy-Org/Krea-2's headers.
+ assert {
+ "first.weight",
+ "tproj.1.weight",
+ "txtmlp.3.bias",
+ "last.modulation.lin",
+ "blocks.0.mod.lin",
+ } <= set(original)
+ assert original["blocks.0.mod.lin"].dim() == 1
+ _assert_round_trip(model, conv.krea2_checkpoint_to_diffusers(checkpoint = original))
+
+
+def test_krea2_container_prefix_is_stripped():
+ model = _tiny("Krea2Transformer2DModel", KREA2_CFG)
+ original = {
+ "model.diffusion_model." + k: v for k, v in krea2_original(model.state_dict()).items()
+ }
+ _assert_round_trip(model, conv.krea2_checkpoint_to_diffusers(checkpoint = original))
+
+
[email protected]("comfy_names", [False, True], ids = ["reference_names", "comfyui_names"])
[email protected]("distilled", [False, True], ids = ["base", "distilled"])
+def test_hunyuanimage_original_layouts_round_trip_bit_identical(comfy_names, distilled):
+ cfg = {**HY_CFG, **(HY_DISTILLED if distilled else {})}
+ model = _tiny("HunyuanImageTransformer2DModel", cfg)
+ hidden = cfg["num_attention_heads"] * cfg["attention_head_dim"]
+ original = hy_original(model.state_dict(), hidden, comfy_names)
+ _assert_round_trip(
+ model, conv.hunyuanimage_checkpoint_to_diffusers(checkpoint = original, config = cfg)
+ )
+ # Without a config the hidden size is read off img_in.
+ _assert_round_trip(model, conv.hunyuanimage_checkpoint_to_diffusers(checkpoint = original))
+
+
+def test_hunyuanimage_final_modulation_halves_swap():
+ """The one reorder: the original final layer holds (shift, scale), diffusers' norm_out reads (scale, shift)."""
+ shift, scale = torch.full((4, 3), 1.0), torch.full((4, 3), 2.0)
+ out = conv.hunyuanimage_checkpoint_to_diffusers(
+ checkpoint = {
+ "img_in.proj.bias": torch.zeros(8),
+ "final_layer.adaLN_modulation.1.weight": torch.cat([shift, scale]),
+ }
+ )
+ assert torch.equal(out["norm_out.linear.weight"], torch.cat([scale, shift]))
+
+
+def test_unknown_keys_are_refused_not_dropped():
+ with pytest.raises(ValueError, match = "not a Krea 2 transformer key"):
+ conv.krea2_checkpoint_to_diffusers(
+ checkpoint = {"blocks.0.attn.something.weight": torch.zeros(2, 2)}
+ )
+ with pytest.raises(ValueError, match = "not a HunyuanImage 2.1 transformer key"):
+ conv.hunyuanimage_checkpoint_to_diffusers(
+ checkpoint = {
+ "img_in.proj.bias": torch.zeros(8),
+ "double_blocks.0.img_attn.extra.weight": torch.zeros(2, 2),
+ }
+ )
+ with pytest.raises(ValueError, match = "cannot be split"):
+ conv.hunyuanimage_checkpoint_to_diffusers(
+ checkpoint = {
+ "img_in.proj.bias": torch.zeros(8),
+ "double_blocks.0.img_attn.qkv.weight": torch.zeros(23, 8),
+ }
+ )
+
+
+# --------------------------------------------------------------------------------- row-only, on every weight
+
+
[email protected]("family", ["krea2", "hy_ref", "hy_comfy_distilled"])
+def test_every_2d_weight_is_a_whole_row_gather(family):
+ """What the ComfyUI int8 / fp8 loader needs: each output row is exactly one source row of one layer,
+ every source row lands exactly once, and no column moves. Checked with that loader's own decoder."""
+ if family == "krea2":
+ model = _tiny("Krea2Transformer2DModel", KREA2_CFG)
+ original = krea2_original(model.state_dict())
+ fn = conv.krea2_checkpoint_to_diffusers
+ else:
+ distilled = family == "hy_comfy_distilled"
+ model = _tiny(
+ "HunyuanImageTransformer2DModel", {**HY_CFG, **(HY_DISTILLED if distilled else {})}
+ )
+ original = hy_original(model.state_dict(), 32, comfy_names = distilled)
+ fn = conv.hunyuanimage_checkpoint_to_diffusers
+ weights = sorted(k for k, v in original.items() if v.dim() == 2)
+ sources = []
+ tagged = dict(original)
+ for index, key in enumerate(weights):
+ rows, cols = original[key].shape
+ codes = torch.zeros(rows, cols, dtype = torch.int8)
+ sources.append((key, codes, None))
+ tag = torch.arange(rows, dtype = torch.float64) + index * cq._TAG
+ tagged[key] = tag.view(-1, 1).expand(rows, cols)
+ out = fn(checkpoint = tagged)
+ seen = {}
+ for name, value in out.items():
+ if value.dtype != torch.float64:
+ continue
+ for i, r, n in cq._decode_rows(name, value, sources):
+ for row in range(r, r + n):
+ assert (
+ i,
+ row,
+ ) not in seen, f"{name}: row {row} of {weights[i]} also went to {seen[(i, row)]}"
+ seen[(i, row)] = name
+ assert len(seen) == sum(int(original[k].shape[0]) for k in weights)
+
+
+def _int8_rows(weight, group = None):
+ scale = weight.abs().amax(dim = 1, keepdim = True).clamp_min(1e-8) / 127.0
+ return torch.round(weight / scale).clamp(-127, 127).to(torch.int8), scale.to(torch.float32)
+
+
+def test_comfy_int8_krea2_file_loads_with_codes_exact(tmp_path, monkeypatch):
+ """A Krea 2 int8_tensorwise file in the real ComfyUI layout through Studio's ComfyUI loader with the
+ real converter: every int8 layer converts (the loader refuses a non-row-only converter), and each
+ dequantized diffusers weight equals its own source codes times its own scales."""
+ cls = _class("Krea2Transformer2DModel")
+ model = _tiny("Krea2Transformer2DModel", KREA2_CFG)
+ original = krea2_original(model.state_dict())
+ tensors, expected = {}, {}
+ inv = {v: k for k, v in _KREA2_INV_BLOCK.items()}
+ for key, value in original.items():
+ if re.match(r"^blocks\.\d+\.(attn\.(wq|wk|wv|wo|gate)|mlp\.(gate|up|down))\.weight$", key):
+ codes, scale = _int8_rows(value)
+ stem = key[: -len(".weight")]
+ tensors[key] = codes
+ tensors[stem + ".weight_scale"] = scale
+ tensors[stem + ".comfy_quant"] = torch.tensor(
+ list(json.dumps({"format": "int8_tensorwise"}).encode()), dtype = torch.uint8
+ )
+ index, rest = key.split(".", 2)[1], key.split(".", 2)[2]
+ expected[f"transformer_blocks.{index}.{inv[rest]}"] = codes.float() * scale
+ else:
+ tensors[key] = value.contiguous()
+ path = tmp_path / "krea2_tiny_int8.safetensors"
+ safetensors_torch.save_file(tensors, str(path))
+ monkeypatch.setattr(cls, "load_config", classmethod(lambda c, *a, **k: dict(KREA2_CFG)))
+
+ scan = cq.refuse_comfy_quant(str(path))
+ loaded = cq.load_comfy_quant_transformer(
+ cls,
+ str(path),
+ scan,
+ {"torch_dtype": torch.float32, "config": "krea/Krea-2-Turbo", "subfolder": "transformer"},
+ int8_backend = None,
+ family = "krea-2",
+ )
+ assert len(expected) == 2 * 8
+ sd = loaded.state_dict()
+ for name, weight in expected.items():
+ assert torch.equal(sd[name], weight), name
+ assert loaded._unsloth_comfy_quant["dequantized"] == len(expected)
+
+
+def test_plain_krea2_file_loads_like_the_base_repo(tmp_path, monkeypatch):
+ """A plain bf16 ComfyUI file through Studio's loader (used while diffusers gives Krea 2 no
+ from_single_file): same tensors as the diffusers weights, the _keep_in_fp32_modules norms in float32
+ as from_pretrained leaves them, strict on keys."""
+ cls = _class("Krea2Transformer2DModel")
+ model = _tiny("Krea2Transformer2DModel", KREA2_CFG)
+ path = tmp_path / "krea2_tiny_bf16.safetensors"
+ safetensors_torch.save_file(
+ {
+ k: v.to(torch.bfloat16).contiguous()
+ for k, v in krea2_original(model.state_dict()).items()
+ },
+ str(path),
+ )
+ monkeypatch.setattr(cls, "load_config", classmethod(lambda c, *a, **k: dict(KREA2_CFG)))
+ loaded = conv.load_original_layout_transformer(
+ cls,
+ str(path),
+ {"torch_dtype": torch.bfloat16, "config": "krea/Krea-2-Turbo", "subfolder": "transformer"},
+ )
+ keep = cls._keep_in_fp32_modules
+ for key, value in model.state_dict().items():
+ got = loaded.state_dict()[key]
+ fp32 = any(m in key.split(".") for m in keep)
+ assert got.dtype == (torch.float32 if fp32 else torch.bfloat16), key
+ assert torch.equal(got, value.to(torch.bfloat16).to(got.dtype)), key
+
+ bad = tmp_path / "krea2_extra.safetensors"
+ tensors = {k: v.contiguous() for k, v in krea2_original(model.state_dict()).items()}
+ del tensors["blocks.0.attn.wq.weight"]
+ safetensors_torch.save_file(tensors, str(bad))
+ with pytest.raises(ValueError, match = "1 missing"):
+ conv.load_original_layout_transformer(cls, str(bad), {"config": "krea/Krea-2-Turbo"})
+
+
+def test_the_single_file_branch_uses_studio_loader_only_without_from_single_file():
+ import inspect
+
+ # Whitespace-free, so a formatter rewrapping the condition cannot break the check.
+ source = "".join(inspect.getsource(studio).split())
+ gate = source.index('ifkind!="gguf"andnothasattr(transformer_cls,"from_single_file"):')
+ assert (
+ gate
+ < source.index("transformer=load_original_layout_transformer(", gate)
+ < source.index("transformer=transformer_cls.from_single_file(", gate)
+ )
+
+
+# ------------------------------------------------------------------------------------------- family wiring
+
+
+def test_both_classes_register_and_resolve(monkeypatch):
+ from diffusers.loaders import single_file_model as sfm
+
+ monkeypatch.setattr(sfm, "SINGLE_FILE_LOADABLE_CLASSES", dict(sfm.SINGLE_FILE_LOADABLE_CLASSES))
+ for name in ("Krea2Transformer2DModel", "HunyuanImageTransformer2DModel"):
+ _class(name)
+ sfm.SINGLE_FILE_LOADABLE_CLASSES.pop(name, None)
+ added = studio._register_unregistered_single_file_classes()
+ assert {"Krea2Transformer2DModel", "HunyuanImageTransformer2DModel"} <= set(added)
+ assert sfm.SINGLE_FILE_LOADABLE_CLASSES["Krea2Transformer2DModel"]["checkpoint_mapping_fn"] is (
+ conv.krea2_checkpoint_to_diffusers
+ )
+ # The ComfyUI loader's lookup, which raised "has no single-file converter" before.
+ fn, _ = cq._mapping(diffusers.HunyuanImageTransformer2DModel)
+ assert fn is conv.hunyuanimage_checkpoint_to_diffusers
+
+
+ "filename, family",
+ [
+ ("krea2_turbo_int8_convrot.safetensors", "krea-2"),
+ ("krea2_turbo_fp8_scaled.safetensors", "krea-2"),
+ ("krea2_turbo_bf16.safetensors", "krea-2"),
+ ("hunyuanimage2.1_bf16.safetensors", "hunyuanimage-2.1"),
+ ("hunyuanimage2.1_fp8_e4m3fn.safetensors", "hunyuanimage-2.1"),
+ ("hunyuanimage2.1_distilled_fp8_e4m3fn.safetensors", "hunyuanimage-2.1"),
+ ],
+)
+def test_comfy_file_names_detect_their_family(filename, family):
+ fam = detect_family(f"/models/ComfyUI/models/diffusion_models/{filename}")
+ assert fam is not None and fam.name == family
+
+
+def test_hunyuanimage_distilled_file_gets_its_own_config_and_shift():
+ fam = detect_family("hunyuanimage-2.1")
+ base = fam.base_repo
+ distilled = "hunyuanimage2.1_distilled_fp8_e4m3fn.safetensors"
+ plain = "hunyuanimage2.1_fp8_e4m3fn.safetensors"
+ assert transformer_config_overrides_for(fam, distilled, base) == HY_DISTILLED
+ assert transformer_config_overrides_for(fam, plain, base) == {}
+ assert transformer_variant_differs_from_base(fam, base, distilled)
+ assert not transformer_variant_differs_from_base(fam, base, plain)
+ assert comfy_flow_shift_for(fam, distilled, base) == 4.0
+ assert comfy_flow_shift_for(fam, plain, base) is None # the shipped shift-5 scheduler stays
+
+
+def test_distilled_single_file_drops_the_base_cfg_guiders():
+ """A guidance-distilled transformer on the base repo must not inherit its two CFG guiders."""
+ import inspect
+
+ source = inspect.getsource(studio)
+ gate = source.index('fam.name == "hunyuanimage-2.1" and getattr(')
+ block = source[gate : gate + 800]
+ assert '"guidance_embeds"' in block
+ assert 'pipe_kwargs["guider"] = None' in block and 'pipe_kwargs["ocr_guider"] = None' in block
+ assert gate < source.index("pipe = pipeline_cls.from_pretrained(\n", gate)
+
+
+# ------------------------------------------------------------------ the real files' headers, when cached
+
+# The suite isolates HF_HUB_CACHE, so the real files are opted into by naming a hub cache that holds them.
+_REAL_HUB_ENV = "UNSLOTH_TEST_REAL_HF_HUB_CACHE"
+
+
+def _real(pattern):
+ import os
+
+ root = os.environ.get(_REAL_HUB_ENV)
+ hits = sorted(Path(root).glob(pattern)) if root else []
+ if not hits:
+ pytest.skip(f"set {_REAL_HUB_ENV} to a hub cache holding {pattern}")
+ return hits[0]
+
+
+def _header_stub(path):
+ with open(path, "rb") as f:
+ n = struct.unpack("<Q", f.read(8))[0]
+ header = json.loads(f.read(n))
+ header.pop("__metadata__", None)
+ dtypes = {
+ "BF16": torch.bfloat16,
+ "F32": torch.float32,
+ "F16": torch.float16,
+ "F8_E4M3": torch.float8_e4m3fn,
+ "I8": torch.int8,
+ "U8": torch.uint8,
+ }
+ layers = {k[: -len(".comfy_quant")] for k in header if k.endswith(".comfy_quant")}
+ stub = {}
+ for key, meta in header.items():
+ if key.endswith((".comfy_quant", ".weight_scale", ".input_scale")) or key == "scaled_fp8":
+ continue
+ dtype = torch.float64 if key[: -len(".weight")] in layers else dtypes[meta["dtype"]]
+ stub[key] = torch.empty(meta["shape"], dtype = dtype, device = "meta")
+ return stub
+
+
+def _meta_model(cls, cfg):
+ from accelerate import init_empty_weights
+ with init_empty_weights():
+ return cls.from_config(cfg)
+
+
+ "pattern",
+ [
+ "models--Comfy-Org--Krea-2/snapshots/*/diffusion_models/krea2_turbo_int8_convrot.safetensors",
+ "models--Comfy-Org--Krea-2/snapshots/*/diffusion_models/krea2_turbo_fp8_scaled.safetensors",
+ "models--Comfy-Org--Krea-2/snapshots/*/diffusion_models/krea2_turbo_bf16.safetensors",
+ "models--Comfy-Org--HunyuanImage_2.1_ComfyUI/snapshots/*/split_files/diffusion_models/hunyuanimage2.1_bf16.safetensors",
+ "models--Comfy-Org--HunyuanImage_2.1_ComfyUI/snapshots/*/split_files/diffusion_models/hunyuanimage2.1_fp8_e4m3fn.safetensors",
+ "models--Comfy-Org--HunyuanImage_2.1_ComfyUI/snapshots/*/split_files/diffusion_models/hunyuanimage2.1_distilled_fp8_e4m3fn.safetensors",
+ ],
+)
+def test_real_comfy_headers_convert_strictly(pattern):
+ path = _real(pattern)
+ if "Krea-2" in pattern:
+ cls, cfg, fn = _class("Krea2Transformer2DModel"), {}, conv.krea2_checkpoint_to_diffusers
+ else:
+ cls, fn = (
+ _class("HunyuanImageTransformer2DModel"),
+ conv.hunyuanimage_checkpoint_to_diffusers,
+ )
+ cfg = dict(
+ text_embed_2_dim = 1472,
+ rope_axes_dim = (64, 64),
+ **(HY_DISTILLED if "distilled" in pattern else {}),
+ )
+ model = _meta_model(cls, cfg)
+ converted = fn(checkpoint = _header_stub(path), config = dict(model.config))
+ want = model.state_dict()
+ assert set(converted) == set(want)
+ assert all(tuple(converted[k].shape) == tuple(want[k].shape) for k in want)
diff --git a/studio/backend/tests/test_diffusion_single_file_registry.py b/studio/backend/tests/test_diffusion_single_file_registry.py
index cc86704596c..9be7463c8d1 100644
--- a/studio/backend/tests/test_diffusion_single_file_registry.py
+++ b/studio/backend/tests/test_diffusion_single_file_registry.py
@@ -117,7 +117,8 @@ def test_registration_fills_the_gap_and_the_real_call_stops_refusing(monkeypatch
monkeypatch.setattr(sfm, "SINGLE_FILE_LOADABLE_CLASSES", dict(sfm.SINGLE_FILE_LOADABLE_CLASSES))
sfm.SINGLE_FILE_LOADABLE_CLASSES.pop(CLASS, None)
- assert studio._register_unregistered_single_file_classes() == (CLASS,)
+ # Other classes of the table (Krea 2, HunyuanImage 2.1) may register alongside it.
+ assert CLASS in studio._register_unregistered_single_file_classes()
entry = sfm.SINGLE_FILE_LOADABLE_CLASSES[CLASS]
assert entry["checkpoint_mapping_fn"] is studio._qwen_image_21_checkpoint_to_diffusers
assert entry["default_subfolder"] == "transformer"
@@ -135,7 +136,7 @@ def test_registration_never_overwrites_diffusers_own_entry(monkeypatch):
)
monkeypatch.setattr(diffusers, CLASS, type(CLASS, (), {}), raising = False)
- assert studio._register_unregistered_single_file_classes() == ()
+ assert CLASS not in studio._register_unregistered_single_file_classes()
assert sfm.SINGLE_FILE_LOADABLE_CLASSES[CLASS] is upstream