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: convert the decoded image to uint8 on the device (#12847)
Daniel Han25546d00d86e
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex db9886be6cd..001aac67d85 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -212,6 +212,7 @@ from . import diffusion_bg_compile as bg_compilefrom . import diffusion_cuda_graph as cuda_graphfrom .diffusion_block_graph import compile_below_hooks_enabled, compile_pipe_below_offload_hooksfrom . import diffusion_render_thread as render_thread+from .diffusion_postprocess import install as install_device_postprocessfrom .diffusion_batched import (chunk_jobs,is_oom_error,@@ -10261,6 +10262,8 @@ class DiffusionBackend:elif state.transformer_cache:# diffusers resets FBCache only after a SUCCESSFUL __call__; a raised call leaves a stale residual.self._reset_step_cache(state.pipe)+ # Per pipe, idempotent: a workflow pipe built by from_pipe has its own image processor.+ install_device_postprocess(pipe, logger)protect_ctx = protect_generation(pipe, denoise_steps, logger = logger)# Per chunk: a later chunk encodes again after an earlier one decoded.gen.phase = "encode"diff --git a/studio/backend/core/inference/diffusion_postprocess.py b/studio/backend/core/inference/diffusion_postprocess.pynew file mode 100644index 00000000000..4841cc6ffa5--- /dev/null+++ b/studio/backend/core/inference/diffusion_postprocess.py@@ -0,0 +1,121 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""diffusers' ``postprocess(output_type="pil")`` uint8 conversion on the device instead of numpy on the host.++Stock runs ``(x * 255).round().astype("uint8")`` over host float32 copies, which stalls under host load. Same IEEE ops+on clamped [0, 1] values, so bit-identical; anything else takes the stock path. Kill switch:+``UNSLOTH_DIFFUSION_DEVICE_POSTPROCESS=0``.+"""++from __future__ import annotations++import os+from typing import Any, Optional++DEVICE_POSTPROCESS_ENV = "UNSLOTH_DIFFUSION_DEVICE_POSTPROCESS"+_MARK = "_unsloth_device_postprocess"+++def disabled() -> bool:+ return (os.environ.get(DEVICE_POSTPROCESS_ENV) or "").strip().lower() in (+ "0",+ "off",+ "false",+ "no",+ )+++def _stock_postprocess_class(processor: Any) -> bool:+ """Subclasses overriding ``postprocess`` (LDM3D, PixArt) keep theirs."""+ try:+ from diffusers.image_processor import VaeImageProcessor+ except Exception: # noqa: BLE001+ return False+ return isinstance(processor, VaeImageProcessor) and (+ getattr(type(processor), "postprocess", None) is VaeImageProcessor.postprocess+ )+++def _all_denormalized(processor: Any, image: Any, do_denormalize: Optional[list]) -> bool:+ if do_denormalize is None:+ return bool(getattr(getattr(processor, "config", None), "do_normalize", False))+ return len(do_denormalize) == int(image.shape[0]) and all(bool(d) for d in do_denormalize)+++def to_pil_on_device(+ processor: Any,+ image: Any,+ do_denormalize: Optional[list] = None,+) -> Optional[list]:+ """The PIL list stock ``postprocess(image, "pil", do_denormalize)`` returns, or None when the stock path must run."""+ import torch++ if not isinstance(image, torch.Tensor) or image.device.type == "cpu":+ return None+ # RGBA: Qwen-Image-2.1's VAE decodes 4 channels.+ if image.ndim != 4 or int(image.shape[1]) not in (3, 4) or not image.is_floating_point():+ return None+ if not _all_denormalized(processor, image, do_denormalize):+ return None+ from PIL import Image++ image = processor._denormalize_conditionally(image, do_denormalize)+ if bool(torch.isnan(image).any()):+ return None+ pixels = uint8_hwc(image).cpu().numpy()+ return [Image.fromarray(pixels[i]) for i in range(pixels.shape[0])]+++def uint8_hwc(image: Any) -> Any:+ """Values must lie in [0, 1]: the uint8 cast of anything else is undefined."""+ import torch+ return (image.float() * 255).round().to(torch.uint8).permute(0, 2, 3, 1).contiguous()+++def install(pipe: Any, logger: Any = None) -> bool:+ """Idempotent; an instance attribute, so ``uninstall`` restores stock."""+ if disabled():+ return False+ processor = getattr(pipe, "image_processor", None)+ if (+ processor is None+ or getattr(processor, _MARK, False)+ or not _stock_postprocess_class(processor)+ ):+ return False+ stock = processor.postprocess++ def postprocess(+ image: Any,+ output_type: str = "pil",+ do_denormalize: Optional[list] = None,+ ) -> Any:+ if output_type == "pil":+ try:+ out = to_pil_on_device(processor, image, do_denormalize)+ except Exception as exc: # noqa: BLE001 - the stock path is always correct+ out = None+ if logger is not None:+ logger.debug("diffusion.postprocess: stock path (%s)", exc)+ if out is not None:+ return out+ return stock(image, output_type = output_type, do_denormalize = do_denormalize)++ processor.postprocess = postprocess+ setattr(processor, _MARK, True)+ return True+++def uninstall(pipe: Any) -> None:+ processor = getattr(pipe, "image_processor", None)+ if processor is None or not getattr(processor, _MARK, False):+ return+ try:+ del processor.postprocess+ except AttributeError:+ pass+ try:+ delattr(processor, _MARK)+ except AttributeError:+ passdiff --git a/studio/backend/tests/test_diffusion_postprocess.py b/studio/backend/tests/test_diffusion_postprocess.pynew file mode 100644index 00000000000..78693351513--- /dev/null+++ b/studio/backend/tests/test_diffusion_postprocess.py@@ -0,0 +1,212 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Tests for ``diffusion_postprocess.py``: the decoded image goes to uint8 on the device with output bit-identical to+diffusers' stock ``VaeImageProcessor.postprocess(output_type="pil")``, every case it does not cover takes the stock+path, the kill switch holds, and the generate path installs it on the pipe it renders with."""++from __future__ import annotations++import ast+from pathlib import Path++import numpy as np+import pytest++from core.inference import diffusion_postprocess as dp++torch = pytest.importorskip("torch")+ip_mod = pytest.importorskip("diffusers.image_processor")+VaeImageProcessor = ip_mod.VaeImageProcessor++needs_cuda = pytest.mark.skipif(not torch.cuda.is_available(), reason = "needs a CUDA device")+++class _Pipe:+ def __init__(self, processor):+ self.image_processor = processor++[email protected](autouse = True)+def _env(monkeypatch):+ monkeypatch.delenv(dp.DEVICE_POSTPROCESS_ENV, raising = False)+++def _decoded(+ dtype,+ batch = 1,+ size = 64,+ channels_last = False,+ device = "cpu",+ channels = 3,+):+ g = torch.Generator().manual_seed(0)+ x = torch.randn(batch, channels, size, size, generator = g) * 0.7+ # Exact rounding ties after the denormalize: (v * 0.5 + 0.5) * 255 == k + 0.5.+ ties = (torch.arange(0, 255, dtype = torch.float32) + 0.5) / 255 * 2 - 1+ x.view(-1)[: ties.numel()] = ties+ x.view(-1)[300:310] = torch.tensor([-3.0, 3.0, -1.0, 1.0, 0.0, 1e-8, -1e-8, 0.999, -0.999, 2.0])+ x = x.to(dtype = dtype, device = device)+ return x.contiguous(memory_format = torch.channels_last) if channels_last else x+++def _stock(+ processor,+ image,+ do_denormalize = None,+):+ return VaeImageProcessor.postprocess(+ processor, image, output_type = "pil", do_denormalize = do_denormalize+ )++[email protected]("dtype", ["float32", "bfloat16", "float16"])[email protected]("channels_last", [False, True])[email protected]("channels", [3, 4])+def test_uint8_conversion_matches_numpy_bit_for_bit(dtype, channels_last, channels):+ proc = VaeImageProcessor()+ image = proc.denormalize(+ _decoded(getattr(torch, dtype), batch = 2, channels_last = channels_last, channels = channels)+ )+ ours = dp.uint8_hwc(image).numpy()+ stock = (VaeImageProcessor.pt_to_numpy(image) * 255).round().astype("uint8")+ assert ours.dtype == np.uint8 and ours.shape == stock.shape+ assert np.array_equal(ours, stock)+++@needs_cuda[email protected]("dtype", ["float32", "bfloat16"])[email protected]("channels_last", [False, True])[email protected]("channels,mode", [(3, "RGB"), (4, "RGBA")])+def test_device_postprocess_is_bit_identical_to_stock(dtype, channels_last, channels, mode):+ """4 channels is Qwen-Image-2.1's VAE output; stock returns RGBA for it."""+ proc = VaeImageProcessor(vae_scale_factor = 16)+ image = _decoded(+ getattr(torch, dtype),+ batch = 2,+ size = 128,+ channels_last = channels_last,+ device = "cuda",+ channels = channels,+ )+ stock = _stock(proc, image)+ assert dp.install(_Pipe(proc))+ ours = proc.postprocess(image, output_type = "pil")+ assert len(ours) == len(stock) == 2+ for a, b in zip(ours, stock):+ assert a.mode == b.mode == mode and a.size == b.size+ assert np.array_equal(np.asarray(a), np.asarray(b))+++@needs_cuda[email protected]("channels", [3, 4])+def test_device_path_actually_runs(monkeypatch, channels):+ proc = VaeImageProcessor()+ calls = []+ real = dp.uint8_hwc+ monkeypatch.setattr(+ dp, "uint8_hwc", lambda image: calls.append(image.device.type) or real(image)+ )+ dp.install(_Pipe(proc))+ proc.postprocess(_decoded(torch.bfloat16, device = "cuda", channels = channels), output_type = "pil")+ assert calls == ["cuda"]+++ "case",+ ["cpu_tensor", "no_normalize", "partial_denormalize", "grayscale", "integer"],+)+def test_uncovered_inputs_return_none_for_the_stock_path(case):+ proc = VaeImageProcessor(do_normalize = case != "no_normalize")+ device = "cpu" if case == "cpu_tensor" else "meta"+ image = torch.empty(2, 3, 8, 8, device = device)+ do_denormalize = None+ if case == "partial_denormalize":+ do_denormalize = [True, False]+ elif case == "grayscale":+ image = torch.empty(2, 1, 8, 8, device = device)+ elif case == "integer":+ image = torch.empty(2, 3, 8, 8, device = device, dtype = torch.uint8)+ assert dp.to_pil_on_device(proc, image, do_denormalize) is None+++@needs_cuda+def test_nan_input_returns_none_for_the_stock_path():+ image = torch.full((1, 3, 8, 8), float("nan"), device = "cuda")+ assert dp.to_pil_on_device(VaeImageProcessor(), image) is None+++def test_stock_path_still_serves_other_output_types_and_cpu():+ proc = VaeImageProcessor()+ dp.install(_Pipe(proc))+ image = _decoded(torch.float32)+ assert isinstance(proc.postprocess(image, output_type = "np"), np.ndarray)+ assert isinstance(proc.postprocess(image, output_type = "pt"), torch.Tensor)+ ours = proc.postprocess(image, output_type = "pil")+ assert np.array_equal(np.asarray(ours[0]), np.asarray(_stock(proc, image)[0]))+++def test_install_is_idempotent_and_uninstall_restores():+ proc = VaeImageProcessor()+ pipe = _Pipe(proc)+ assert dp.install(pipe) is True+ patched = proc.postprocess+ assert dp.install(pipe) is False+ assert proc.postprocess is patched+ dp.uninstall(pipe)+ assert "postprocess" not in proc.__dict__+ assert proc.postprocess.__func__ is VaeImageProcessor.postprocess+++def test_kill_switch(monkeypatch):+ monkeypatch.setenv(dp.DEVICE_POSTPROCESS_ENV, "0")+ proc = VaeImageProcessor()+ assert dp.install(_Pipe(proc)) is False+ assert "postprocess" not in proc.__dict__+++def test_processor_that_overrides_postprocess_is_left_alone():+ class Custom(VaeImageProcessor):+ def postprocess(+ self,+ image,+ output_type = "pil",+ do_denormalize = None,+ ):+ return "custom"++ proc = Custom()+ assert dp.install(_Pipe(proc)) is False+ assert dp.install(_Pipe(object())) is False+ assert dp.install(object()) is False+++def test_generate_installs_it_on_the_render_pipe():+ """The call sits in generate's chunk loop, ahead of the pipe call, so every workflow pipe (from_pipe builds its own+ image processor) is covered."""+ src = Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py"+ tree = ast.parse(src.read_text(encoding = "utf-8"))+ gen = next(+ n+ for n in ast.walk(tree)+ if isinstance(n, ast.FunctionDef)+ and n.name == "generate"+ and any(a.arg == "prompt" for a in n.args.kwonlyargs)+ )+ calls = [+ n+ for n in ast.walk(gen)+ if isinstance(n, ast.Call)+ and isinstance(n.func, ast.Name)+ and n.func.id == "install_device_postprocess"+ ]+ assert len(calls) == 1+ assert isinstance(calls[0].args[0], ast.Name) and calls[0].args[0].id == "pipe"+ protect = next(+ n+ for n in ast.walk(gen)+ if isinstance(n, ast.Call)+ and isinstance(n.func, ast.Name)+ and n.func.id == "protect_generation"+ )+ assert calls[0].lineno < protect.lineno