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: 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.py
index 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_compile
from . import diffusion_cuda_graph as cuda_graph
from .diffusion_block_graph import compile_below_hooks_enabled, compile_pipe_below_offload_hooks
from . import diffusion_render_thread as render_thread
+from .diffusion_postprocess import install as install_device_postprocess
from .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.py
new file mode 100644
index 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:
+ pass
diff --git a/studio/backend/tests/test_diffusion_postprocess.py b/studio/backend/tests/test_diffusion_postprocess.py
new file mode 100644
index 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