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 MiniMax-H3: run one denoiser forward per requested step (20 steps ran 19) (#17362)

Daniel Han8699f88215d8
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index c68ee21eb96..89a98170421 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -14107,14 +14107,15 @@ class VideoBackend:
if callable(setter) and value is not None:
setter(float(value))
if fam.name == "minimax-h3":
+ from .video_minimax_h3 import h3_num_inference_steps
from .video_minimax_h3_pdd import (
bind_h3_pdd_render,
h3_pdd_num_inference_steps,
)
- # A PDD head bank reads each step's (sigma, sigma_next) off this render's video schedule. The
- # H3 scheduler's grid holds the terminal 0, so `steps` model evaluations (ComfyUI's count, which
- # the bank's 8-step partition is distilled for) is a grid of steps + 1.
+ # H3 grid includes the terminal 0: `steps` evaluations need steps + 1 points.
+ kwargs["num_inference_steps"] = h3_num_inference_steps(steps)
+ # PDD bank is distilled for ComfyUI's count, so it keeps steps + 1 even under the kill switch.
if bind_h3_pdd_render(pipe, shift, audio_shift):
kwargs["num_inference_steps"] = h3_pdd_num_inference_steps(steps)
request_shape["pdd"] = True
diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.py
index 6d93996d07c..920fcec7b4a 100644
--- a/studio/backend/core/inference/video_minimax_h3.py
+++ b/studio/backend/core/inference/video_minimax_h3.py
@@ -26,6 +26,23 @@ H3_AUDIO_VAE = "vae/official/minimax_h3_audio_vae_fp32.safetensors"
H3_QWEN_Q2 = "qwen3vl_32b_minimax_h3-Q2_K_M.gguf"
H3_QWEN_Q4 = "qwen3vl_32b_minimax_h3-Q4_K_M.gguf"
+# diffusers' H3 grid of n points (terminal 0 included) runs n - 1 evaluations; SGLang/ComfyUI/sd.cpp run n. "0" = old grid.
+H3_STEP_EVALUATIONS_ENV = "UNSLOTH_H3_STEP_EVALUATIONS"
+
+
+def h3_step_evaluations_enabled() -> bool:
+ return os.environ.get(H3_STEP_EVALUATIONS_ENV, "").strip().lower() not in (
+ "0",
+ "false",
+ "no",
+ "off",
+ )
+
+
+def h3_num_inference_steps(steps: int) -> int:
+ return int(steps) + 1 if h3_step_evaluations_enabled() else int(steps)
+
+
# Measured (Diffusers T2VA, component CPU offload, 960x544..1344x768, 124-345 frames); base is largest component plus overhead; margin = allocator variance.
H3_DIFFUSERS_VRAM_BASE_GB = 68.5
H3_DIFFUSERS_VRAM_GB_PER_MPIXEL_FRAME = 0.08
diff --git a/studio/backend/tests/test_h3_step_evaluations.py b/studio/backend/tests/test_h3_step_evaluations.py
new file mode 100644
index 00000000000..6794296664f
--- /dev/null
+++ b/studio/backend/tests/test_h3_step_evaluations.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A requested MiniMax-H3 step is one denoiser evaluation on the real diffusers scheduler."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.inference import video_minimax_h3 as h3
+
+
+def _scheduler():
+ pytest.importorskip("torch")
+ diffusers = pytest.importorskip("diffusers")
+ cls = getattr(diffusers, "MiniMaxH3Scheduler", None)
+ if cls is None:
+ pytest.skip("this diffusers has no MiniMaxH3Scheduler")
+ return cls(shift = 12.0)
+
+
[email protected]("steps", [1, 2, 8, 20, 30, 50])
+def test_requested_steps_are_model_evaluations(steps):
+ sched = _scheduler()
+ sched.set_timesteps(h3.h3_num_inference_steps(steps))
+ assert len(sched.timesteps) == steps
+ assert float(sched.sigmas[-1]) == 0.0 and float(sched.sigmas[0]) == 1.0
+
+
+def test_kill_switch_keeps_the_grid_point_count(monkeypatch):
+ monkeypatch.setenv(h3.H3_STEP_EVALUATIONS_ENV, "0")
+ sched = _scheduler()
+ sched.set_timesteps(h3.h3_num_inference_steps(20))
+ assert len(sched.timesteps) == 19
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 438a8d0e216..1af003992b3 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -605,7 +605,8 @@ class _FakeModularPipe:
"output": output,
**kwargs,
}
- for _ in range(int(num_inference_steps or 1)):
+ # As diffusers' MiniMaxH3Scheduler: grid points include the terminal 0.
+ for _ in range(int(num_inference_steps or 2) - 1):
self.scheduler.step(object(), 0, object())
return {"videos": [[object() for _ in range(int(num_frames or 1))]], "audio": None}
@@ -5820,6 +5821,24 @@ def test_h3_modular_generation_ticks_and_cancels_through_the_scheduler(fake_runt
assert pipe.scheduler.step.__func__ is _FakeH3Scheduler.step
[email protected]("steps", [1, 2, 8, 20])
+def test_h3_modular_runs_one_denoiser_evaluation_per_requested_step(fake_runtime, steps):
+ backend = VideoBackend()
+ pipe = _load_h3_modular(backend)
+ backend.generate(prompt = "a fox", steps = steps)
+ assert pipe.scheduler.calls == steps
+ assert pipe.last_kwargs["num_inference_steps"] == steps + 1
+
+
+def test_h3_step_evaluations_kill_switch_passes_the_grid_through(fake_runtime, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_H3_STEP_EVALUATIONS", "0")
+ backend = VideoBackend()
+ pipe = _load_h3_modular(backend)
+ backend.generate(prompt = "a fox", steps = 20)
+ assert pipe.last_kwargs["num_inference_steps"] == 20
+ assert pipe.scheduler.calls == 19
+
+
def test_the_pipeline_call_runs_with_uint8_frames_on_every_family(
fake_runtime, tmp_path, monkeypatch
):
diff --git a/studio/backend/tests/test_video_static_skip.py b/studio/backend/tests/test_video_static_skip.py
index 827c0523d98..38432f02fc2 100644
--- a/studio/backend/tests/test_video_static_skip.py
+++ b/studio/backend/tests/test_video_static_skip.py
@@ -545,7 +545,8 @@ class _H3LoopPipe:
num_frames = None,
**kwargs,
):
- for _ in range(int(num_inference_steps or 1)):
+ # H3 grid points include the terminal 0
+ for _ in range(int(num_inference_steps or 2) - 1):
self.outputs.append(self.transformer(timestep = None, return_dict = False))
self.scheduler.step(object(), 0, object())
return {"videos": [[object() for _ in range(int(num_frames or 1))]], "audio": None}