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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""MiniMax-H3 LoRA: clip datasets, packing, sigma coupling and forward contract, CPU only."""
from __future__ import annotations
import importlib
import json
import random
import sys
import types
from pathlib import Path
import pytest
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from core.training.diffusion_h3_clips import ( # noqa: E402
H3_AUDIO_CHANNELS,
H3_AUDIO_LATENTS_PER_SECOND,
H3_AUDIO_SAMPLING_RATE,
H3_CANVAS_MULTIPLE,
H3_FPS,
H3_FRAMES_PER_CHUNK,
H3_LATENTS_PER_CHUNK,
H3_SPATIAL_COMPRESSION,
H3_TRAIN_NUM_FRAMES,
discover_clip_caption_pairs,
h3_align_num_frames,
h3_audio_latent_count,
h3_audio_sample_count,
h3_packed_sequence_length,
h3_rows_per_latent_frame,
h3_train_canvas,
h3_video_latent_frames,
)
from core.training.diffusion_train_common import ( # noqa: E402
TRAINABLE_VIDEO_FAMILIES,
DiffusionLoraConfig,
_FLOW_TRAIN_FAMILIES,
bf16_unsupported_reason,
dit_accelerator_missing_reason,
get_trainer,
resolve_trainable_family,
train_defaults,
)
def test_align_num_frames_snaps_up_to_the_vae_grid():
# The video VAE encodes 17 * n + 5 frames; anything else is not encodable at all.
assert h3_align_num_frames(22) == 22
assert h3_align_num_frames(1) == 5
assert h3_align_num_frames(6) == 22
assert h3_align_num_frames(124) == 124
assert h3_align_num_frames(125) == 141
for n in range(1, 400):
aligned = h3_align_num_frames(n)
assert aligned >= n
assert aligned % H3_FRAMES_PER_CHUNK == H3_LATENTS_PER_CHUNK
def test_align_num_frames_refuses_a_non_positive_count():
with pytest.raises(ValueError):
h3_align_num_frames(0)
def test_video_latent_frames_is_five_per_chunk_plus_two():
assert h3_video_latent_frames(5) == 2
assert h3_video_latent_frames(22) == 7
assert h3_video_latent_frames(124) == 37
assert h3_video_latent_frames(345) == 102
def test_video_latent_frames_refuses_an_unaligned_count():
with pytest.raises(ValueError):
h3_video_latent_frames(24)
def test_the_training_clip_is_exactly_one_vae_chunk():
assert H3_TRAIN_NUM_FRAMES == H3_FRAMES_PER_CHUNK + H3_LATENTS_PER_CHUNK
assert h3_align_num_frames(H3_TRAIN_NUM_FRAMES) == H3_TRAIN_NUM_FRAMES
assert h3_align_num_frames(H3_LATENTS_PER_CHUNK + 1) == H3_TRAIN_NUM_FRAMES
def test_audio_latent_count_follows_the_forty_per_second_grid():
assert h3_audio_latent_count(H3_FPS) == H3_AUDIO_LATENTS_PER_SECOND
assert h3_audio_latent_count(124) == 207
assert h3_audio_latent_count(22) == 37
def test_audio_sample_count_is_a_whole_number_of_hops():
# The audio VAE hops 800 samples and right-pads, so latents * hop yields the reserved rows.
hop = H3_AUDIO_SAMPLING_RATE // H3_AUDIO_LATENTS_PER_SECOND
assert hop == 800
for frames in (22, 124, 345):
samples = h3_audio_sample_count(frames)
assert samples % hop == 0
assert samples // hop == h3_audio_latent_count(frames)
def test_rows_per_latent_frame_applies_the_two_by_two_patch():
assert h3_rows_per_latent_frame(48, 84) == 24 * 42
def test_packed_sequence_length_counts_text_audio_and_video_rows():
text, frames, height, width = 48, 22, 768, 1344
latent_h, latent_w = height // H3_SPATIAL_COMPRESSION, width // H3_SPATIAL_COMPRESSION
expected = (
text
+ h3_audio_latent_count(frames) * H3_AUDIO_CHANNELS
+ h3_video_latent_frames(frames) * h3_rows_per_latent_frame(latent_h, latent_w)
)
assert h3_packed_sequence_length(text, frames, height, width) == expected
assert expected == 7178
def test_a_five_second_clip_is_five_times_the_sequence_of_a_training_clip():
short = h3_packed_sequence_length(48, 22, 768, 1344)
full = h3_packed_sequence_length(48, 124, 768, 1344)
assert full > 5 * short
def test_train_canvas_reproduces_the_released_sixteen_by_nine_canvas():
assert h3_train_canvas(16, 9) == (1344, 768)
def test_train_canvas_snaps_both_axes_to_the_multiple():
for aspect in ((16, 9), (4, 3), (1, 1), (3, 4), (9, 16), (2048, 872)):
width, height = h3_train_canvas(*aspect)
assert width % H3_CANVAS_MULTIPLE == 0
assert height % H3_CANVAS_MULTIPLE == 0
def test_train_canvas_scales_its_area_cap_with_the_short_edge():
# Keep the released AREA budget in short-edge units, not pixels, so smaller canvases scale.
def area_ratio(short_edge: int) -> float:
width, height = h3_train_canvas(21, 9, short_edge = short_edge)
return width * height / short_edge**2
assert area_ratio(384) == pytest.approx(area_ratio(768), rel = 0.10)
assert area_ratio(192) == pytest.approx(area_ratio(768), rel = 0.10)
def test_train_canvas_refuses_an_untrained_aspect_ratio():
with pytest.raises(ValueError, match = "1:4 to 4:1"):
h3_train_canvas(10, 1)
def test_train_canvas_names_a_degenerate_size_as_such():
with pytest.raises(ValueError, match = "must be positive"):
h3_train_canvas(0, 9)
with pytest.raises(ValueError, match = "must be positive"):
h3_train_canvas(16, -1)
def _clip(tmp_path: Path, name: str) -> Path:
path = tmp_path / name
path.write_bytes(b"not a real container")
return path
def test_discover_clip_pairs_reads_a_sidecar_caption(tmp_path):
_clip(tmp_path, "a.mp4")
(tmp_path / "a.txt").write_text("a rabbit in a meadow")
assert discover_clip_caption_pairs(tmp_path) == [
(str(tmp_path / "a.mp4"), "a rabbit in a meadow")
]
def test_discover_clip_pairs_reads_metadata_jsonl(tmp_path):
_clip(tmp_path, "a.mov")
(tmp_path / "metadata.jsonl").write_text(
json.dumps({"file_name": "a.mov", "text": "from metadata"}) + "\n"
)
assert discover_clip_caption_pairs(tmp_path)[0][1] == "from metadata"
def test_discover_clip_pairs_accepts_a_video_key_in_metadata(tmp_path):
_clip(tmp_path, "a.webm")
(tmp_path / "metadata.jsonl").write_text(
json.dumps({"video": "a.webm", "text": "keyed by video"}) + "\n"
)
assert discover_clip_caption_pairs(tmp_path)[0][1] == "keyed by video"
def test_a_sidecar_beats_a_metadata_row(tmp_path):
_clip(tmp_path, "a.mp4")
(tmp_path / "a.txt").write_text("the explicit edit")
(tmp_path / "metadata.jsonl").write_text(
json.dumps({"file_name": "a.mp4", "text": "the bulk caption"}) + "\n"
)
assert discover_clip_caption_pairs(tmp_path)[0][1] == "the explicit edit"
def test_an_empty_sidecar_is_a_tombstone_that_falls_back_to_the_instance_prompt(tmp_path):
_clip(tmp_path, "a.mp4")
(tmp_path / "a.txt").write_text(" ")
(tmp_path / "metadata.jsonl").write_text(
json.dumps({"file_name": "a.mp4", "text": "suppressed"}) + "\n"
)
pairs = discover_clip_caption_pairs(tmp_path, instance_prompt = "fallback")
assert pairs[0][1] == "fallback"
def test_discover_clip_pairs_ignores_still_images(tmp_path):
# H3 has no still-image milestone: a 1-frame clip is not a valid video VAE input.
(tmp_path / "a.png").write_bytes(b"x")
(tmp_path / "a.txt").write_text("a still")
with pytest.raises(ValueError, match = "clips with sound"):
discover_clip_caption_pairs(tmp_path)
def test_discover_clip_pairs_raises_for_a_missing_directory(tmp_path):
with pytest.raises(FileNotFoundError):
discover_clip_caption_pairs(tmp_path / "nope")
def test_discover_clip_pairs_is_sorted_and_stable(tmp_path):
for name in ("c.mp4", "a.mp4", "b.mp4"):
_clip(tmp_path, name)
pairs = discover_clip_caption_pairs(tmp_path, instance_prompt = "p")
assert [Path(p).name for p, _ in pairs] == ["a.mp4", "b.mp4", "c.mp4"]
def test_discover_training_pairs_routes_h3_to_the_clip_discovery(tmp_path):
"""H3 discovery must use clip discovery, not image discovery, or valid clip datasets are rejected."""
from core.training.diffusion_train_common import discover_training_pairs
_clip(tmp_path, "a.mp4")
(tmp_path / "a.txt").write_text("a rabbit in a meadow")
pairs = discover_training_pairs("minimax-h3", tmp_path, verify_images = True)
assert [Path(p).name for p, _ in pairs] == ["a.mp4"]
assert pairs[0][1] == "a rabbit in a meadow"
def test_discover_training_pairs_leaves_an_image_family_on_the_image_discovery(tmp_path):
"""The other half: nothing about an existing image family moves, verify_images included."""
from PIL import Image
from core.training.diffusion_train_common import discover_training_pairs
Image.new("RGB", (8, 8)).save(tmp_path / "a.png")
_clip(tmp_path, "b.mp4")
pairs = discover_training_pairs("sdxl", tmp_path, instance_prompt = "p", verify_images = True)
assert [Path(p).name for p, _ in pairs] == ["a.png"]
def test_the_clip_families_are_exactly_the_ones_whose_trainer_takes_clips():
"""LTX-2 trains a style LoRA FROM STILLS, so it must keep the image discovery even though it
is a video family -- the split is by what the TRAINER reads, not by output modality."""
from core.training.diffusion_train_common import (
CLIP_TRAINED_FAMILIES,
TRAINABLE_VIDEO_FAMILIES,
)
assert CLIP_TRAINED_FAMILIES == {"minimax-h3"}
assert CLIP_TRAINED_FAMILIES <= TRAINABLE_VIDEO_FAMILIES
assert "ltx-2" not in CLIP_TRAINED_FAMILIES
def test_the_two_shifts_come_from_the_released_scheduler_configs():
from core.training.diffusion_h3_trainer import _H3_AUDIO_SHIFT, _H3_VIDEO_SHIFT
assert _H3_VIDEO_SHIFT == 12.0
assert _H3_AUDIO_SHIFT == 3.0
def test_an_omitted_flow_shift_reaches_the_trainer_as_the_released_video_shift():
"""An omitted flow_shift must become H3's video shift, since 1.0 is a number and wins the fallback."""
from core.training.diffusion_train_common import AUTO_FLOW_SHIFT_FAMILIES, DiffusionLoraConfig
assert "minimax-h3" in AUTO_FLOW_SHIFT_FAMILIES
cfg = DiffusionLoraConfig(
base_model = "MiniMaxAI/MiniMax-H3",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
).normalized()
assert cfg.resolved_family == "minimax-h3"
assert cfg.flow_shift == "auto"
assert not isinstance(cfg.flow_shift, (int, float))
def test_an_explicit_flow_shift_still_overrides_the_video_default():
"""The escape hatch stays: a caller who names a shift gets it, not 12.0."""
from core.training.diffusion_train_common import DiffusionLoraConfig
cfg = DiffusionLoraConfig(
base_model = "MiniMaxAI/MiniMax-H3",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
flow_shift = 7.0,
).normalized()
assert cfg.flow_shift == 7.0
def test_shifted_sigma_matches_the_schedulers_exponential_shift():
from core.training.diffusion_h3_trainer import _shifted_sigma
for shift in (3.0, 12.0):
assert _shifted_sigma(0.0, shift) == 0.0
assert _shifted_sigma(1.0, shift) == 1.0
for u in (0.1, 0.25, 0.5, 0.9):
assert _shifted_sigma(u, shift) == pytest.approx(shift * u / (1 + (shift - 1) * u))
def test_a_larger_shift_pushes_sigma_higher_so_video_is_always_noisier_than_audio():
# Both streams index the SAME step at inference, so one u is pushed through both shifts.
from core.training.diffusion_h3_trainer import (
_H3_AUDIO_SHIFT,
_H3_VIDEO_SHIFT,
_shifted_sigma,
)
for u in (0.05, 0.2, 0.5, 0.8, 0.95):
assert _shifted_sigma(u, _H3_VIDEO_SHIFT) > _shifted_sigma(u, _H3_AUDIO_SHIFT)
def test_shifted_sigma_is_monotonic_in_u():
from core.training.diffusion_h3_trainer import _shifted_sigma
previous = -1.0
for i in range(101):
value = _shifted_sigma(i / 100, 12.0)
assert value > previous
previous = value
# Every Linear name MiniMaxH3Transformer3DModel builds, with the layer counts cut down.
_H3_LINEARS = (
"proj_in",
"audio_proj_in",
"context_embedder",
"time_embedder.linear_1",
"time_embedder.linear_2",
"token_refiner.refiner_blocks.0.attn.to_q",
"token_refiner.refiner_blocks.0.attn.to_k",
"token_refiner.refiner_blocks.0.attn.to_v",
"token_refiner.refiner_blocks.0.attn.to_out.0",
"token_refiner.refiner_blocks.0.ff.net.0.proj",
"token_refiner.refiner_blocks.0.ff.net.2",
"token_refiner.refiner_blocks.1.attn.to_q",
"transformer_blocks.0.attn.to_q",
"transformer_blocks.0.attn.to_k",
"transformer_blocks.0.attn.to_v",
"transformer_blocks.0.attn.to_out.0",
"transformer_blocks.0.ff.net.0.proj",
"transformer_blocks.0.ff.net.2",
"transformer_blocks.0.adaln_proj.linear",
"transformer_blocks.49.attn.to_q",
"transformer_blocks.49.ff.net.2",
"norm_out.linear",
"proj_out",
"audio_proj_out",
)
def _selected(target_regex: str) -> set:
"""PEFT's own rule for a STRING target_modules: re.fullmatch on the module name."""
import re
return {name for name in _H3_LINEARS if re.fullmatch(target_regex, name)}
def test_h3_targets_are_a_regex_because_peft_does_not_glob():
# PEFT suffix-matches a LIST or fullmatches a STRING: a glob inside a list matches nothing.
from core.training.diffusion_h3_trainer import _H3_TARGETS
assert isinstance(_H3_TARGETS, str)
assert "*" not in _H3_TARGETS
def test_h3_targets_never_adapt_the_text_refiner():
# Token refiner blocks reuse `attn`/`ff` leaf names, so a bare "to_q" would adapt the text stream.
from core.training.diffusion_h3_trainer import _H3_TARGETS
assert not any(name.startswith("token_refiner") for name in _selected(_H3_TARGETS))
def test_h3_targets_cover_attention_and_the_feed_forward_and_nothing_else():
from core.training.diffusion_h3_trainer import _H3_TARGET_LEAVES, _H3_TARGETS
assert set(_H3_TARGET_LEAVES) == {
"attn.to_q",
"attn.to_k",
"attn.to_v",
"attn.to_out.0",
"ff.net.0.proj",
"ff.net.2",
}
selected = _selected(_H3_TARGETS)
assert selected == {
f"transformer_blocks.{index}.{leaf}"
for index in (0, 49)
for leaf in _H3_TARGET_LEAVES
if f"transformer_blocks.{index}.{leaf}" in _H3_LINEARS
}
# adaln_proj is 40% of the checkpoint but its input carries two or three rows per step.
assert not any("adaln" in name for name in selected)
# The patch and text projections are fp32 in the checkpoint's own _keep_in_fp32_modules.
assert not any(
"proj_in" in name or "proj_out" in name or "context_embedder" in name for name in selected
)
assert "norm_out.linear" not in selected
def test_the_nf4_skip_list_covers_every_dtype_reading_module():
# Params4bit reports uint8 and activations are cast to a weight's dtype, so these skip NF4.
from core.training.diffusion_h3_trainer import _H3_NF4_SKIP_MODULES
assert set(_H3_NF4_SKIP_MODULES) == {"context_embedder", "adaln_proj", "norm_out"}
def test_minimax_h3_is_a_trainable_video_family():
assert "minimax-h3" in TRAINABLE_VIDEO_FAMILIES
def test_minimax_h3_routes_to_its_own_trainer():
from core.training import diffusion_h3_trainer
assert get_trainer("minimax-h3") is diffusion_h3_trainer.run_h3_lora_training
def test_minimax_h3_does_not_route_to_the_dit_trainer():
# Two schedules in one joint loss on a packed sequence; DiT has one sigma and one target.
from core.training import diffusion_dit_trainer
assert get_trainer("minimax-h3") is not diffusion_dit_trainer.run_dit_lora_training
def test_the_official_h3_base_resolves_to_the_h3_family():
assert resolve_trainable_family("MiniMaxAI/MiniMax-H3") == "minimax-h3"
def test_minimax_h3_is_a_flow_family_for_the_preflight_gates():
# Without this the start route skips bf16/accelerator checks and evicts before failing.
assert "minimax-h3" in _FLOW_TRAIN_FAMILIES
assert bf16_unsupported_reason("minimax-h3") is None or isinstance(
bf16_unsupported_reason("minimax-h3"), str
)
assert dit_accelerator_missing_reason("minimax-h3") is None or isinstance(
dit_accelerator_missing_reason("minimax-h3"), str
)
def test_the_official_h3_base_is_trusted_for_training():
from core.training.diffusion_train_common import _assert_trusted_base_model
_assert_trusted_base_model("MiniMaxAI/MiniMax-H3")
with pytest.raises(ValueError, match = "untrusted"):
_assert_trusted_base_model("some-random-user/minimax-h3-repack")
def test_h3_defaults_train_at_the_released_short_edge():
defaults = train_defaults("minimax-h3")
assert defaults["resolution"] == 768
assert defaults["train_batch_size"] == 1
assert defaults["lora_rank"] == 16
def _cfg(**kw) -> DiffusionLoraConfig:
base = {
"base_model": "MiniMaxAI/MiniMax-H3",
"data_dir": "/tmp/clips",
"output_dir": "/tmp/out",
"mixed_precision": "bf16",
"resolution": 768,
}
base.update(kw)
return DiffusionLoraConfig(**base)
def test_h3_refuses_fp16():
with pytest.raises(ValueError, match = "bf16"):
_cfg(mixed_precision = "fp16").normalized()
def test_h3_refuses_an_off_grid_resolution():
with pytest.raises(ValueError, match = "multiple of 32"):
_cfg(resolution = 760).normalized()
def test_h3_refuses_the_float8_precisions():
for mode in ("fp8", "mxfp8"):
with pytest.raises(ValueError, match = "minimax-h3"):
_cfg(base_precision = mode).normalized()
def test_h3_accepts_the_precisions_it_supports():
for mode in ("nf4", "auto"):
assert _cfg(base_precision = mode).normalized().base_precision == mode
def test_h3_resolves_to_its_family_through_normalized():
assert _cfg().normalized().resolved_family == "minimax-h3"
def _run(**kw):
from core.training.diffusion_h3_trainer import run_h3_lora_training
return run_h3_lora_training(_cfg(**kw))
def test_h3_refuses_a_batch_larger_than_one():
# Row layout depends on clip geometry and caption length, so clips cannot share a sequence.
with pytest.raises(ValueError, match = "batch size 1"):
_run(train_batch_size = 2)
def test_h3_refuses_a_cfg_dropout():
# The checkpoint is guidance-distilled: there is no unconditional branch to train.
with pytest.raises(ValueError, match = "guidance-distilled"):
_run(cfg_dropout = 0.1)
def test_h3_refuses_a_weighted_loss():
with pytest.raises(ValueError, match = "weighting_scheme"):
_run(weighting_scheme = "bell")
def test_the_entrypoint_refusals_fire_before_the_data_directory_is_read():
# _cfg's data_dir does not exist, so reaching discovery would raise FileNotFoundError instead.
with pytest.raises(ValueError):
_run(train_batch_size = 4)
torch = pytest.importorskip("torch")
try:
# diffusers' lazy modules make importorskip on the package succeed; import the real symbol.
from diffusers.modular_pipelines.minimax_h3.before_denoise import ( # noqa: F401
MiniMaxH3PrepareLayoutStep,
)
_H3_BLOCKS = True
_H3_BLOCKS_WHY = ""
except Exception as _exc: # noqa: BLE001 -- a host without the H3 diffusers revision
_H3_BLOCKS = False
_H3_BLOCKS_WHY = f"diffusers MiniMax-H3 blocks unavailable: {_exc}"
needs_h3_blocks = pytest.mark.skipif(not _H3_BLOCKS, reason = _H3_BLOCKS_WHY)
def _layout(
text_tokens = 6,
latent_frames = 2,
latent_h = 4,
latent_w = 6,
audio_latents = 3,
):
from core.training.diffusion_h3_trainer import _build_layout
return _build_layout(
text_tokens, latent_frames, latent_h, latent_w, audio_latents, (1, 2, 2), "cpu"
)
@needs_h3_blocks
def test_the_layout_reserves_one_row_per_token_of_every_modality():
layout = _layout()
rows = h3_rows_per_latent_frame(4, 6)
assert layout["text_indices"].numel() == 6
assert layout["audio_indices"].numel() == 3 * H3_AUDIO_CHANNELS
assert layout["video_indices"].numel() == 2 * rows
assert layout["position_ids"].shape == (6 + 3 * H3_AUDIO_CHANNELS + 2 * rows, 3)
@needs_h3_blocks
def test_the_layout_has_no_conditioning_rows():
layout = _layout()
assert layout["num_condition_video_rows"] == 0
assert layout["num_condition_audio_rows"] == 0
@needs_h3_blocks
def test_every_row_of_the_layout_is_claimed_by_exactly_one_modality():
layout = _layout()
claimed = torch.cat([layout["text_indices"], layout["audio_indices"], layout["video_indices"]])
assert claimed.numel() == layout["position_ids"].shape[0]
assert torch.equal(claimed.sort().values, torch.arange(claimed.numel()))
@needs_h3_blocks
def test_the_row_timestep_plan_carries_exactly_the_two_generated_timesteps():
from core.training.diffusion_h3_trainer import _row_timesteps
layout = _layout()
timestep, indices = _row_timesteps(layout, 6, 0.25, 0.75, "cpu")
assert sorted(round(float(t), 6) for t in timestep) == [0.25, 0.75]
assert indices.shape == (layout["position_ids"].shape[0],)
video_t = timestep[indices[layout["video_indices"]]]
audio_t = timestep[indices[layout["audio_indices"]]]
assert torch.allclose(video_t, torch.full_like(video_t, 0.25))
assert torch.allclose(audio_t, torch.full_like(audio_t, 0.75))
@needs_h3_blocks
def test_the_text_rows_inherit_the_video_timestep():
from core.training.diffusion_h3_trainer import _row_timesteps
layout = _layout()
timestep, indices = _row_timesteps(layout, 6, 0.25, 0.75, "cpu")
text_t = timestep[indices[layout["text_indices"]]]
assert torch.allclose(text_t, torch.full_like(text_t, 0.25))
@needs_h3_blocks
def test_patchify_round_trips_through_the_decoder_unpack():
from core.training.diffusion_h3_trainer import _patchify
latents = torch.randn(1, 24, 2, 4, 6)
rows = _patchify(latents, (1, 2, 2))
assert rows.shape == (2 * h3_rows_per_latent_frame(4, 6), 24 * 4)
back = rows.reshape(-1, 2, 2, 3, 24, 1, 2, 2).permute(0, 4, 1, 5, 2, 6, 3, 7)
assert torch.allclose(back.reshape(1, 24, 2, 4, 6), latents)
def test_audio_rows_are_channel_major_like_the_decoder_expects():
audio = torch.randn(H3_AUDIO_CHANNELS, 32, 3)
rows = audio.permute(0, 2, 1).reshape(-1, 32)
assert rows.shape == (H3_AUDIO_CHANNELS * 3, 32)
assert torch.allclose(rows[0], audio[0, :, 0])
assert torch.allclose(rows[3], audio[1, :, 0])
def test_the_velocity_target_is_data_ward():
# MiniMax-H3 predicts x0 = x_t + sigma * v, so v = latents - noise (opposite of the DiT trainer).
import inspect
from core.training import diffusion_h3_trainer
source = inspect.getsource(diffusion_h3_trainer._train_h3)
assert "clean_video - noise_video" in source
assert "noise_video - clean_video" not in source
assert "clean_audio - noise_audio" in source
def test_the_loss_includes_both_modalities():
import inspect
from core.training import diffusion_h3_trainer
source = inspect.getsource(diffusion_h3_trainer._train_h3)
assert "loss_video + loss_audio" in source
def test_the_row_timestep_plan_is_built_video_first():
# build_row_timesteps(video, audio): both plain floats, so a swap is silent.
import inspect
from core.training import diffusion_h3_trainer
source = inspect.getsource(diffusion_h3_trainer._train_h3)
assert "1.0 - sigma_video, 1.0 - sigma_audio" in source
assert "1.0 - sigma_audio, 1.0 - sigma_video" not in source
def test_one_base_u_drives_both_sigmas():
import inspect
from core.training import diffusion_h3_trainer
source = inspect.getsource(diffusion_h3_trainer._train_h3)
assert "u = rng.random()" in source
assert "_shifted_sigma(u, video_shift)" in source
assert "_shifted_sigma(u, _H3_AUDIO_SHIFT)" in source
def test_the_conditioning_phase_never_names_the_transformer():
# Naming it in load_components puts the 66 GB denoiser beside the 63 GiB conditioner.
from core.training.diffusion_h3_trainer import _H3_CONDITIONING_COMPONENTS
assert "transformer" not in _H3_CONDITIONING_COMPONENTS
assert "transformer_ref" not in _H3_CONDITIONING_COMPONENTS
assert set(_H3_CONDITIONING_COMPONENTS) == {
"text_encoder",
"tokenizer",
"processor",
"vae",
"audio_vae",
}
def test_the_component_grid_assertion_catches_a_moved_constant():
from core.training.diffusion_h3_trainer import _assert_component_grid
class _Cfg:
def __init__(self, **kw):
self.__dict__.update(kw)
good_vae = types.SimpleNamespace(
spatial_compression_ratio = H3_SPATIAL_COMPRESSION,
tokens_chunk_size = H3_LATENTS_PER_CHUNK,
config = _Cfg(clip_length = H3_FRAMES_PER_CHUNK, latent_channels = 24),
)
good_audio = types.SimpleNamespace(config = _Cfg(latent_channels = 32, sampling_rate = 32000))
_assert_component_grid(types.SimpleNamespace(vae = good_vae, audio_vae = good_audio))
bad_vae = types.SimpleNamespace(
spatial_compression_ratio = 8,
tokens_chunk_size = H3_LATENTS_PER_CHUNK,
config = _Cfg(clip_length = H3_FRAMES_PER_CHUNK, latent_channels = 24),
)
with pytest.raises(ValueError, match = "spatial compression"):
_assert_component_grid(types.SimpleNamespace(vae = bad_vae, audio_vae = good_audio))
def test_the_saved_adapter_carries_the_diffusers_transformer_prefix(tmp_path):
# Diffusers ships no MiniMaxH3LoraLoaderMixin, so the file is written directly. It must
# still be the ordinary single-file layout, or nothing can load it.
from safetensors.torch import load_file
from core.training.diffusion_h3_trainer import _save_lora
_save_lora(str(tmp_path), {"transformer_blocks.0.attn.to_q.lora_A.weight": torch.zeros(2, 2)})
saved = load_file(str(tmp_path / "pytorch_lora_weights.safetensors"))
assert list(saved) == ["transformer.transformer_blocks.0.attn.to_q.lora_A.weight"]
def test_the_hosted_prequant_denoiser_is_refused_as_a_training_base():
"""The hosted H3 prequant is a denoiser, not a pipeline, so it must be refused as a training base."""
from core.inference.video_families import detect_video_family
from core.training.diffusion_train_common import (
_component_only_repos,
resolve_trainable_family,
)
fam = detect_video_family("", override = "minimax-h3")
denoiser_repo = fam.prequant_repos[0][1]
assert _component_only_repos()[denoiser_repo.lower()][:2] == ("minimax-h3", "transformer")
with pytest.raises(ValueError) as exc:
resolve_trainable_family(denoiser_repo)
detail = str(exc.value)
assert "not a full model" in detail
assert fam.base_repo in detail
def test_the_real_h3_base_is_still_trainable():
"""The other side of the same coin: the base itself must not be caught by the refusal."""
from core.inference.video_families import detect_video_family
from core.training.diffusion_train_common import resolve_trainable_family
fam = detect_video_family("", override = "minimax-h3")
assert resolve_trainable_family(fam.base_repo) == "minimax-h3"
def _h3_cfg(**kw):
from core.training.diffusion_train_common import DiffusionLoraConfig
return DiffusionLoraConfig(
base_model = "MiniMaxAI/MiniMax-H3",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
**kw,
)
def test_resume_is_refused_rather_than_silently_starting_over():
"""run_h3_lora_training neither writes nor restores a resume bundle, so resume starts a fresh
optimization that overwrites the outputs it was meant to continue"""
with pytest.raises(ValueError, match = "resume_from_checkpoint is not supported"):
_h3_cfg(resume_from_checkpoint = "/tmp/o/checkpoint-100").normalized()
def test_save_steps_is_refused_rather_than_silently_ignored():
"""Periodic saves were accepted but never happened, so a stopped run had nothing to resume."""
with pytest.raises(ValueError, match = "save_steps is not supported"):
_h3_cfg(save_steps = 50).normalized()
def test_the_defaults_are_untouched():
"""Neither knob set is the normal case and must stay valid, or the family becomes untrainable."""
cfg = _h3_cfg().normalized()
assert cfg.save_steps == 0
assert cfg.resume_from_checkpoint is None
def test_an_image_family_keeps_its_checkpointing():
"""The refusal is scoped to the loop that lacks the support, not to training at large."""
from core.training.diffusion_train_common import DiffusionLoraConfig
cfg = DiffusionLoraConfig(
base_model = "stabilityai/stable-diffusion-xl-base-1.0",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
save_steps = 50,
).normalized()
assert cfg.save_steps == 50
def test_int8_training_applies_h3s_small_m_guards():
"""H3 int8 needs small-M guards: adaln_proj would reach M=1 and fail after the 66 GB base loads."""
from core.inference.diffusion_transformer_quant import (
exclude_tokens_for_scheme,
pad_tokens_for_scheme,
)
from core.training import diffusion_dit_trainer as dit
from core.training import diffusion_h3_trainer as h3
assert "adaln_proj" in exclude_tokens_for_scheme("int8", "minimax-h3")
assert "adaln_proj" not in exclude_tokens_for_scheme("int8", None)
assert pad_tokens_for_scheme("int8", "minimax-h3")
src = Path(h3.__file__).read_text()
assert "_int8_quantize_base(transformer, cfg.resolved_family, device = device)" in src
dit_src = Path(dit.__file__).read_text()
body = dit_src.split("def _int8_quantize_base", 1)[1].split("\ndef ", 1)[0]
# training keeps the baked list: the streamed-inference text-stream scope never reaches it
assert 'exclude_tokens_for_scheme("int8", family, baked = True)' in body
assert 'apply_small_m_padding(transformer, "int8", family)' in body
def test_int8_quantize_base_pads_the_families_small_m_linears(monkeypatch):
# Padding pass with the family must run AFTER quantize_, which reparents the Linears.
import torch.nn as nn
from core.training import diffusion_dit_trainer as dit
order: list = []
fake_ao = types.ModuleType("torchao.quantization")
fake_ao.Int8WeightOnlyConfig = lambda: "int8cfg"
fake_ao.quantize_ = lambda model, cfg, filter_fn = None: order.append("quantize")
monkeypatch.setitem(sys.modules, "torchao", types.ModuleType("torchao"))
monkeypatch.setitem(sys.modules, "torchao.quantization", fake_ao)
monkeypatch.setattr(
"core.inference.diffusion_transformer_quant.apply_small_m_padding",
lambda transformer, scheme, family, **kw: order.append(("pad", scheme, family)),
)
dit._int8_quantize_base(nn.Linear(4, 4), "minimax-h3")
assert order == ["quantize", ("pad", "int8", "minimax-h3")]
def test_a_non_default_lora_alpha_survives_the_export(tmp_path):
"""A non-default lora_alpha must survive export, carried as adapter metadata the loader reads back."""
from safetensors import safe_open
from core.training.diffusion_h3_trainer import _save_lora
_save_lora(
str(tmp_path),
{"transformer_blocks.0.attn.to_q.lora_A.weight": torch.zeros(2, 2)},
{"r": 16, "lora_alpha": 32, "target_modules": {"to_q"}},
)
with safe_open(str(tmp_path / "pytorch_lora_weights.safetensors"), framework = "pt") as f:
meta = f.metadata()
assert meta["format"] == "pt"
recorded = json.loads(meta["lora_adapter_metadata"])
assert recorded["transformer.lora_alpha"] == 32
assert recorded["transformer.r"] == 16
# A set is not JSON-serialisable; diffusers lists them, and so must this.
assert recorded["transformer.target_modules"] == ["to_q"]
def test_the_export_without_a_config_still_writes_a_plain_file(tmp_path):
from safetensors.torch import load_file
from core.training.diffusion_h3_trainer import _save_lora
_save_lora(str(tmp_path), {"transformer_blocks.0.attn.to_q.lora_A.weight": torch.zeros(2, 2)})
assert list(load_file(str(tmp_path / "pytorch_lora_weights.safetensors"))) == [
"transformer.transformer_blocks.0.attn.to_q.lora_A.weight"
]
def test_a_mostly_silent_soundtrack_is_refused_rather_than_padded(tmp_path):
"""A mostly silent soundtrack must be refused rather than zero-padded into the training window."""
import numpy as np
from core.training import diffusion_h3_clips as clips
target = clips.h3_audio_sample_count(clips.H3_FRAMES_PER_CHUNK)
class _Resampler:
def resample(self, frame):
return [] if frame is None else [frame]
class _Container:
def __init__(self, n):
self._n = n
def __enter__(self):
return self
def __exit__(self, *a):
return False
def decode(self, audio = 0):
block = types.SimpleNamespace(
# A real signal, not zeros: this test is about DURATION, and an all-zero window
# is separately refused for being silent, which would mask what it checks.
to_ndarray = lambda: np.full(
(self._n * clips.H3_AUDIO_CHANNELS,), 0.25, dtype = "float32"
)
)
return [block]
def fake_av(n):
return types.SimpleNamespace(
AudioResampler = lambda **kw: _Resampler(),
open = lambda path: _Container(n),
)
short_tail = target - int(0.002 * clips.H3_AUDIO_SAMPLING_RATE)
out = clips._decode_clip_audio(tmp_path / "a.mp4", target, fake_av(short_tail), np)
assert out.shape == (clips.H3_AUDIO_CHANNELS, target)
with pytest.raises(ValueError, match = "of audio for a"):
clips._decode_clip_audio(tmp_path / "a.mp4", target, fake_av(target // 10), np)
def test_a_soundtrack_that_is_silent_throughout_is_refused(tmp_path):
"""A fully silent soundtrack must be refused, but a quiet or mostly silent one with a sound is kept."""
import types
import numpy as np
from core.training import diffusion_h3_clips as clips
target = clips.h3_audio_sample_count(41)
class _Resampler:
def resample(self, frame):
return [] if frame is None else [frame]
def container_of(fill):
class _Container:
def __enter__(self):
return self
def __exit__(self, *a):
return False
def decode(self, audio = 0):
buf = fill(target)
return [types.SimpleNamespace(to_ndarray = lambda b = buf: b)]
return _Container()
def fake_av(fill):
return types.SimpleNamespace(
AudioResampler = lambda **kw: _Resampler(),
open = lambda path, _f = fill: container_of(_f),
)
def silent(n):
return np.zeros((n * clips.H3_AUDIO_CHANNELS,), dtype = "float32")
def dithered(n):
# Digital silence is not exact zeros after a round trip, so a 0.0 check would miss it.
return (silent(n) + 1e-7).astype("float32")
def one_real_sound(n):
buf = silent(n)
buf[: 64 * clips.H3_AUDIO_CHANNELS] = 0.4
return buf
def quiet(n):
return (silent(n) + 0.01).astype("float32")
for fill in (silent, dithered):
with pytest.raises(ValueError, match = "silent all the way through"):
clips._decode_clip_audio(tmp_path / "a.mp4", target, fake_av(fill), np)
for fill in (one_real_sound, quiet):
out = clips._decode_clip_audio(tmp_path / "a.mp4", target, fake_av(fill), np)
assert out.shape == (clips.H3_AUDIO_CHANNELS, target)
def test_the_knobs_h3_cannot_honour_are_refused_or_normalised():
"""Unsupported H3 knobs are refused if explicit, normalised if default, never silently dropped."""
from dataclasses import replace as _replace
from core.training.diffusion_train_common import h3_train_unsupported_reason
base = _h3_cfg().normalized()
assert h3_train_unsupported_reason(base) is None, "a default H3 request must start"
refused = {
"mixed_precision": ("no", "requires bf16"),
"train_batch_size": (2, "batch size 1"),
"cond_cache_dir": ("/tmp/cond", "conditioning cache"),
"cfg_dropout": (0.1, "guidance-distilled"),
"weighting_scheme": ("bell", "timestep-weighted"),
"resolution": (700, "multiples of"),
}
for field, (value, fragment) in refused.items():
reason = h3_train_unsupported_reason(_replace(base, **{field: value}))
assert reason and fragment in reason, f"{field} was accepted: {reason!r}"
from core.training.diffusion_train_common import DiffusionLoraConfig
other = DiffusionLoraConfig(
base_model = "black-forest-labs/FLUX.1-dev",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
mixed_precision = "no",
)
assert h3_train_unsupported_reason(other.normalized()) is None
def test_the_h3_preflight_runs_before_the_start_route_evicts_anything():
import inspect
import routes.training as tr
src = inspect.getsource(tr.start_diffusion_training)
# The CALL, not the docstring's mention of it.
assert src.index("h3_train_unsupported_reason") < src.index(
"asyncio.to_thread(_free_gpu_for_diffusion_training)"
)
def test_the_augmentation_knobs_record_what_h3_actually_does():
"""Run record must report only the augmentation that happens; refusing would 422 defaults."""
from dataclasses import replace as _replace
from core.training import diffusion_h3_trainer as h3
from core.training.diffusion_train_common import train_recipe_overrides
src = Path(h3.__file__).read_text()
assert "replace(cfg, **train_recipe_overrides(cfg))" in src
overrides = train_recipe_overrides(_h3_cfg().normalized())
assert overrides["center_crop"] is True and overrides["random_flip"] is False
cfg = _replace(_h3_cfg(), center_crop = True, random_flip = False)
assert cfg.center_crop is True and cfg.random_flip is False
def test_h3_is_advertised_as_trainable_with_the_precisions_it_has():
"""H3 must be advertised as trainable with its precisions, or the Train panel disables Start."""
from core.training.diffusion_train_common import family_train_infos
infos = {i["name"]: i for i in family_train_infos()}
h3 = infos.get("minimax-h3")
reference = next((infos[n] for n in ("flux.1", "ltx-2", "qwen-image") if n in infos), None)
if h3 is None or reference is None:
pytest.skip("this diffusers carries neither H3 nor a reference DiT family")
expected = [m for m in reference["precision_modes"] if m not in ("fp8", "mxfp8")]
assert h3["precision_modes"] == expected
if reference["precision_modes"]:
assert h3["precision_modes"], "an empty list disables Start in the Train panel"
assert h3["supports_compile"] is False
assert infos["sdxl"]["supports_compile"] is True
if reference["precision_modes"]:
assert reference["supports_compile"] is True
def test_an_over_long_clip_says_that_only_its_opening_trains(tmp_path, monkeypatch):
"""A longer clip trains only its first num_frames, latents cached once per run; the run must say so."""
import numpy as np
from core.training import diffusion_h3_clips as clips
notes: list = []
class _Frame:
def to_image(self):
from PIL import Image
return Image.new("RGB", (64, 64))
class _Stream:
average_rate = clips.H3_FPS
guessed_rate = clips.H3_FPS
duration = 10 * clips.H3_FPS
time_base = 1 / clips.H3_FPS
class _Container:
streams = types.SimpleNamespace(video = [_Stream()], audio = [object()])
def __enter__(self):
return self
def __exit__(self, *a):
return False
def decode(self, video = 0):
return [_Frame() for _ in range(10 * clips.H3_FPS)]
monkeypatch.setattr(
clips, "av", types.SimpleNamespace(open = lambda p: _Container()), raising = False
)
monkeypatch.setitem(sys.modules, "av", types.SimpleNamespace(open = lambda p: _Container()))
monkeypatch.setattr(
clips,
"_decode_clip_audio",
lambda path, target, av, np_: np.zeros((clips.H3_AUDIO_CHANNELS, target), "float32"),
)
clips.decode_clip(
tmp_path / "a.mp4",
num_frames = clips.H3_FRAMES_PER_CHUNK,
width = 64,
height = 64,
on_note = notes.append,
)
assert notes and "trains its first" in notes[0]
notes.clear()
_Stream.duration = clips.H3_FRAMES_PER_CHUNK
clips.decode_clip(
tmp_path / "a.mp4",
num_frames = clips.H3_FRAMES_PER_CHUNK,
width = 64,
height = 64,
on_note = notes.append,
)
assert notes == []
def test_the_precision_recorded_for_h3_is_the_one_its_loop_runs_in():
"""H3 must record the same effective mixed precision as the DiT loop it is byte-identical to."""
import inspect
from core.training import diffusion_dit_trainer, diffusion_h3_trainer
from core.training.diffusion_train_common import effective_mixed_precision
h3 = _cfg().normalized()
reference = DiffusionLoraConfig(
base_model = "black-forest-labs/FLUX.1-dev",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
mixed_precision = "bf16",
).normalized()
assert effective_mixed_precision(h3) == effective_mixed_precision(reference)
# The claim the equality rests on: the same weight-dtype rule in both loops, and no reader of
# mixed_precision in the H3 one.
dtype_rule = 'weight_dtype = torch.bfloat16 if device in ("cuda", "xpu") else torch.float32'
h3_src = inspect.getsource(diffusion_h3_trainer)
assert dtype_rule in h3_src
assert dtype_rule in inspect.getsource(diffusion_dit_trainer)
assert "mixed_precision" not in h3_src
def test_an_h3_run_can_never_record_a_precision_it_did_not_use():
"""fp16 is refused in validation, other non-bf16 by the start preflight; no checkpoint to record
into."""
from dataclasses import replace as _replace
from core.training.diffusion_train_common import h3_train_unsupported_reason
with pytest.raises(ValueError, match = "bf16"):
_cfg(mixed_precision = "fp16").normalized()
reason = h3_train_unsupported_reason(_replace(_cfg().normalized(), mixed_precision = "no"))
assert reason and "requires bf16" in reason
with pytest.raises(ValueError, match = "resume_from_checkpoint"):
_cfg(resume_from_checkpoint = "/tmp/out").normalized()
with pytest.raises(ValueError, match = "save_steps"):
_cfg(save_steps = 100).normalized()
def test_the_persisted_h3_recipe_is_the_one_the_loop_runs():
"""The persisted H3 recipe must be the one the loop runs, since the parent writes the run record."""
import inspect
from core.training.diffusion_training_service import DiffusionTrainingService
from core.training.diffusion_train_common import train_recipe_overrides
assert train_recipe_overrides(_cfg().normalized()) == {
"center_crop": True,
"random_flip": False,
"snr_gamma": None,
"cache_latents": True,
"cache_variants": 1,
# One packed clip canvas: no image buckets, whatever the request said.
"bucketing": False,
}
# Config-only: the other flow-matching loops disagree only on min-SNR, and SDXL on nothing.
other = DiffusionLoraConfig(
base_model = "black-forest-labs/FLUX.1-dev",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
).normalized()
assert train_recipe_overrides(other) == {"snr_gamma": None}
sdxl = DiffusionLoraConfig(
base_model = "stabilityai/stable-diffusion-xl-base-1.0",
data_dir = "/tmp/d",
output_dir = "/tmp/o",
instance_prompt = "p",
).normalized()
assert train_recipe_overrides(sdxl) == {}
from core.training import diffusion_h3_trainer
assert "train_recipe_overrides" in inspect.getsource(diffusion_h3_trainer)
start_src = inspect.getsource(DiffusionTrainingService.start)
assert "train_recipe_overrides" in start_src
assert "self._config.update(" in start_src
def test_the_strict_start_gate_probes_the_h3_transformer_not_modular_pipeline(monkeypatch):
"""Start gate must probe the H3 transformer class; ModularPipeline exists even in old diffusers."""
from core.inference.diffusion_families import family_pipeline_available, family_probe_class
from core.training.diffusion_train_common import (
_trainable_family_spec,
training_pipeline_import_error,
)
fam = _trainable_family_spec("minimax-h3")
assert fam is not None and fam.pipeline_class == "ModularPipeline"
assert family_probe_class(fam) == "MiniMaxH3Transformer3DModel"
old = types.ModuleType("diffusers")
old.__version__ = "0.36.0"
old.ModularPipeline = object # the generic entry point, present for several releases
old.FluxPipeline = object
monkeypatch.setitem(sys.modules, "diffusers", old)
assert family_pipeline_available(fam) is False
reason = training_pipeline_import_error("minimax-h3")
assert reason and "MiniMaxH3Transformer3DModel" in reason
assert training_pipeline_import_error("flux.1") is None
with pytest.raises(ValueError, match = "MiniMaxH3Transformer3DModel"):
_cfg().normalized()
def test_the_probe_still_fails_open_for_a_record_that_names_no_pipeline_class():
"""A probe record with no pipeline_class must fail open, not drop the repo from the picker."""
from core.inference.diffusion_families import family_pipeline_available, family_probe_class
assert family_probe_class(object()) == ""
assert family_pipeline_available(object()) is True
def test_a_local_modular_h3_pipeline_is_an_acceptable_training_base(tmp_path):
"""A local modular pipeline (modular_model_index.json only) is a valid H3 training base."""
from core.training.diffusion_train_common import _assert_trusted_base_model
modular = tmp_path / "MiniMax-H3"
modular.mkdir()
transformer = ["diffusers", "MiniMaxH3Transformer3DModel"]
manifest = {
"_class_name": "ModularPipeline",
"_blocks_class_name": "Blocks",
"transformer": transformer,
}
(modular / "modular_model_index.json").write_text(json.dumps(manifest))
(modular / "transformer").mkdir()
(modular / "transformer" / "config.json").write_text("{}")
(modular / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
_assert_trusted_base_model(str(modular), allow_modular = True)
with pytest.raises(ValueError, match = "model_index.json"):
_assert_trusted_base_model(str(modular))
empty = tmp_path / "not-a-pipeline"
empty.mkdir()
for allow in (True, False):
with pytest.raises(ValueError, match = "not a diffusers pipeline directory"):
_assert_trusted_base_model(str(empty), allow_modular = allow)
def test_the_start_route_reaches_the_same_modular_verdict_as_the_trainer():
"""Start route and H3 loop must agree on modular bases, or the route refuses what the loop can load."""
import inspect
from core.training import diffusion_h3_trainer
from core.training.diffusion_train_common import MODULAR_BASE_FAMILIES
from routes import training as training_routes
assert "minimax-h3" in MODULAR_BASE_FAMILIES
assert MODULAR_BASE_FAMILIES.isdisjoint({"flux.1", "qwen-image", "sdxl", "ltx-2"})
route_src = inspect.getsource(training_routes.start_diffusion_training)
assert "MODULAR_BASE_FAMILIES" in route_src
assert "_assert_trusted_base_model(\n config.get" in route_src
trainer_src = inspect.getsource(diffusion_h3_trainer)
assert "MODULAR_BASE_FAMILIES" in trainer_src
assert "allow_modular = True" not in trainer_src
def test_h3_advertises_that_it_cannot_checkpoint():
"""save_steps is REFUSED for a checkpointless family, not ignored, so a panel that keeps
offering "Checkpoint every" offers a value that rejects Start with nothing on the control
saying why. The family metadata already carries supports_compile for the same reason."""
from core.training.diffusion_train_common import CHECKPOINTLESS_FAMILIES, family_train_infos
infos = {info["name"]: info for info in family_train_infos()}
assert "minimax-h3" in CHECKPOINTLESS_FAMILIES
for name, info in infos.items():
assert info["supports_checkpoints"] == (name not in CHECKPOINTLESS_FAMILIES), name
with pytest.raises(ValueError, match = "save_steps is not supported"):
_cfg(save_steps = 50).normalized()
_cfg(save_steps = 0).normalized()
def test_the_batch_cap_survives_the_response_model():
"""The batch cap must be a declared response field, or Pydantic drops it before the clamp sees it."""
from core.training.diffusion_train_common import (
SINGLE_SEQUENCE_FAMILIES,
family_train_infos,
)
from models.training import DiffusionTrainableFamily
infos = {info["name"]: info for info in family_train_infos()}
assert "minimax-h3" in SINGLE_SEQUENCE_FAMILIES
for name, info in infos.items():
expected = 1 if name in SINGLE_SEQUENCE_FAMILIES else None
assert info["max_train_batch_size"] == expected, name
assert DiffusionTrainableFamily(**info).max_train_batch_size == expected, name
from core.training.diffusion_train_common import h3_train_unsupported_reason
assert "batch size 1" in (
h3_train_unsupported_reason(_cfg(train_batch_size = 2).normalized()) or ""
)
assert h3_train_unsupported_reason(_cfg(train_batch_size = 1).normalized()) is None
def test_the_h3_conditioner_load_carries_the_hub_token(monkeypatch):
"""Hub token must reach each component load; a gated base otherwise leaves components unset."""
from core.training import diffusion_h3_trainer as h3
seen: list[dict] = []
class _Placed:
def to(self, device):
return self
class _Pipe:
text_encoder = _Placed()
vae = _Placed()
audio_vae = _Placed()
def load_components(self, **kwargs):
seen.append(kwargs)
class _Modular:
@staticmethod
def from_pretrained(
path,
token = None,
**kw,
):
seen.append({"index_token": token, **kw})
return _Pipe()
monkeypatch.setitem(sys.modules, "diffusers", types.SimpleNamespace(ModularPipeline = _Modular))
monkeypatch.setattr(h3, "_assert_component_grid", lambda pipe: None)
monkeypatch.setattr("core.inference.diffusion.hub_cache_dir", lambda: "/live/hub")
cfg = types.SimpleNamespace(base_model = "unsloth/private-h3", hf_token = "hf_secret")
h3._load_conditioners(cfg, "cpu")
assert seen[0] == {"index_token": "hf_secret", "cache_dir": "/live/hub"}
component_loads = seen[1:]
assert len(component_loads) == 2
assert all(call.get("token") == "hf_secret" for call in component_loads), component_loads
# Pin cache_dir to the LIVE root: the import-time constant ignores a mid-session folder change.
assert all(call.get("cache_dir") == "/live/hub" for call in component_loads), component_loads
seen.clear()
h3._load_conditioners(
types.SimpleNamespace(base_model = "MiniMaxAI/MiniMax-H3", hf_token = None), "cpu"
)
assert all("token" not in call for call in seen[1:]), seen
@pytest.mark.parametrize("base_precision", ["bf16", "nf4"])
def test_the_h3_denoiser_load_is_pinned_to_the_live_cache(monkeypatch, base_precision):
"""The denoiser is the 145 GB half, so this is the expensive one to leave unpinned."""
from core.training import diffusion_h3_trainer as h3
seen: list[dict] = []
class _Model:
def to(self, device):
return self
class _Transformer:
@staticmethod
def from_pretrained(path, **kw):
seen.append(kw)
return _Model()
monkeypatch.setitem(
sys.modules,
"diffusers",
types.SimpleNamespace(
MiniMaxH3Transformer3DModel = _Transformer,
BitsAndBytesConfig = lambda **kw: kw,
),
)
monkeypatch.setattr("core.inference.diffusion.hub_cache_dir", lambda: "/live/hub")
cfg = types.SimpleNamespace(base_model = "MiniMaxAI/MiniMax-H3", hf_token = None)
h3._load_transformer(cfg, "cpu", base_precision)
assert len(seen) == 1
assert seen[0]["cache_dir"] == "/live/hub"
assert seen[0]["subfolder"] == "transformer"
def test_the_audio_decode_stops_at_the_training_window(tmp_path):
"""Audio decode must stop at the training window, not resample the whole recording first."""
import numpy as np
from core.training import diffusion_h3_clips as clips
target = clips.h3_audio_sample_count(clips.H3_FRAMES_PER_CHUNK)
decoded = 0
class _Resampler:
def resample(self, frame):
return [] if frame is None else [frame]
class _Container:
def __enter__(self):
return self
def __exit__(self, *a):
return False
def decode(self, audio = 0):
nonlocal decoded
for _ in range(4000): # an hour of audio behind a one-second window
decoded += 1
yield types.SimpleNamespace(
# Nonzero: a silent window is refused before where decoding STOPS can be asserted.
to_ndarray = lambda: np.full(
(target * clips.H3_AUDIO_CHANNELS,), 0.25, dtype = "float32"
)
)
av = types.SimpleNamespace(
AudioResampler = lambda **_kw: _Resampler(), open = lambda _p: _Container()
)
out = clips._decode_clip_audio(tmp_path / "a.mp4", target, av, np)
assert out.shape == (clips.H3_AUDIO_CHANNELS, target)
assert decoded == 1, f"decoded {decoded} blocks for a window one block wide"
def _stub_training_stack(monkeypatch):
"""Stubs the training-stack names _train_h3 binds on entry, so CI without diffusers still runs them."""
scheduler = types.ModuleType("diffusers.optimization")
scheduler.get_scheduler = lambda *_a, **_k: None
training_utils = types.ModuleType("diffusers.training_utils")
training_utils.cast_training_params = lambda *_a, **_k: None
peft_utils = types.ModuleType("peft.utils")
peft_utils.get_peft_model_state_dict = lambda *_a, **_k: {}
peft = types.ModuleType("peft")
peft.LoraConfig = object
peft.utils = peft_utils
for name, module in (
# Stub SUBMODULES only: a fake diffusers parent lacking MiniMaxH3Transformer3DModel would make
# resolve_trainable_family raise instead of skip.
("diffusers.optimization", scheduler),
("diffusers.training_utils", training_utils),
("peft", peft),
("peft.utils", peft_utils),
):
try:
importlib.import_module(name)
except Exception: # noqa: BLE001 -- absent or broken both mean "use the placeholder"
monkeypatch.setitem(sys.modules, name, module)
def _h3_cache_run(
monkeypatch,
*,
num_clips: int,
on_event = None,
):
"""Drive _train_h3 through phase 2 with a sentinel _load_transformer, so reaching it is observable."""
import torch
from core.training import diffusion_h3_trainer as h3
_stub_training_stack(monkeypatch)
class _Placed:
def to(self, _device):
return self
pipe = types.SimpleNamespace(
text_encoder = _Placed(), processor = None, vae = _Placed(), audio_vae = _Placed()
)
monkeypatch.setattr(h3, "_load_conditioners", lambda cfg, device: pipe)
monkeypatch.setattr(h3, "_encode_prompt", lambda *_a, **_k: torch.zeros(1, 8, 16))
monkeypatch.setattr(h3, "_dataset_canvas", lambda _path, _short_edge: (64, 64))
monkeypatch.setattr(h3, "decode_clip", lambda *_a, **_k: (None, None))
monkeypatch.setattr(
h3,
"_encode_video_stats",
lambda *_a: (torch.zeros(1, 4, 2, 8, 8), torch.zeros(1, 4, 2, 8, 8)),
)
num_audio = h3.h3_audio_latent_count(h3.H3_TRAIN_NUM_FRAMES)
monkeypatch.setattr(
h3,
"_encode_audio_latents",
lambda *_a: torch.zeros(1, h3.H3_AUDIO_LATENT_CHANNELS, num_audio),
)
def _no_transformer(*_a, **_k):
raise RuntimeError("reached phase 3")
monkeypatch.setattr(h3, "_load_transformer", _no_transformer)
cfg = _cfg(output_dir = "/tmp/h3-out").normalized()
pairs = [(f"/clips/{i}.mp4", "a caption") for i in range(num_clips)]
return lambda: h3._train_h3(
cfg,
pairs,
random.Random(0),
"cpu",
torch.float32,
on_event or (lambda *_a, **_k: None),
lambda: False,
lambda: True,
)
def test_h3_resumes_model_download_progress_after_latent_preparation(monkeypatch):
from core.training.diffusion_download_progress import TrainingDownloadProgress
monkeypatch.setenv("UNSLOTH_DIFFUSION_FORCE_LATENT_CACHE", "1")
events = []
monitor = TrainingDownloadProgress(
events.append,
sample = lambda: {"bytes_done": 1, "bytes_total": 2, "scope": "active_files"},
)
monitor.report({"type": "model_load_started"})
with pytest.raises(RuntimeError, match = "reached phase 3"):
_h3_cache_run(monkeypatch, num_clips = 1, on_event = monitor.report)()
monitor.poll()
assert any(event["type"] == "preparing" for event in events)
assert [event["type"] for event in events[-2:]] == [
"model_load_started",
"model_download_progress",
]
def test_the_h3_latent_cache_is_size_gated_like_the_image_trainers(monkeypatch):
"""H3 must size-gate its latent cache against the host-memory budget, as the image trainers do."""
from core.training import diffusion_train_common as common
monkeypatch.delenv("UNSLOTH_DIFFUSION_FORCE_LATENT_CACHE", raising = False)
monkeypatch.setattr(common, "_LATENT_CACHE_BUDGET_BYTES", 1)
with pytest.raises(ValueError, match = "latent cache") as exc:
_h3_cache_run(monkeypatch, num_clips = 4)()
assert "UNSLOTH_DIFFUSION_FORCE_LATENT_CACHE" in str(exc.value)
def test_the_h3_latent_cache_gate_honours_the_explicit_override(monkeypatch):
"""The gate is the AUTOMATIC default only, exactly as it is for the image trainers: a user who
has the RAM and says so gets the cache, and the run carries on into phase 3."""
from core.training import diffusion_train_common as common
monkeypatch.setenv("UNSLOTH_DIFFUSION_FORCE_LATENT_CACHE", "1")
monkeypatch.setattr(common, "_LATENT_CACHE_BUDGET_BYTES", 1)
with pytest.raises(RuntimeError, match = "reached phase 3"):
_h3_cache_run(monkeypatch, num_clips = 4)()
def _write_rotated_clip(
path,
*,
theta: int,
width: int = 640,
height: int = 360,
seconds: int = 2,
):
"""A real H.264+AAC clip whose display matrix says ``theta``, coded ``width`` x ``height``."""
av = pytest.importorskip("av")
np = pytest.importorskip("numpy")
with av.open(str(path), "w") as out:
video = out.add_stream("libx264", rate = H3_FPS)
video.width, video.height = width, height
video.pix_fmt = "yuv420p"
audio = out.add_stream("aac", rate = 48000)
if theta:
video.set_display_rotation(theta)
for i in range(H3_FPS * seconds):
# An asymmetric picture, so a wrong rotation cannot look like a right one.
img = np.zeros((height, width, 3), dtype = "uint8")
img[: height // 3, :, 0] = 255
img[:, : max(1, i * 4), 1] = 255
for packet in video.encode(av.VideoFrame.from_ndarray(img, format = "rgb24")):
out.mux(packet)
# An audible tone: the real decode refuses a fully silent soundtrack.
t = np.arange(48000 * seconds, dtype = "float32") / 48000.0
tone = (0.3 * np.sin(2 * np.pi * 440.0 * t)).astype("float32").reshape(1, -1)
frame = av.AudioFrame.from_ndarray(tone, format = "fltp", layout = "mono")
frame.sample_rate = 48000
for packet in audio.encode(frame):
out.mux(packet)
for packet in video.encode():
out.mux(packet)
for packet in audio.encode():
out.mux(packet)
def test_a_rotated_clip_reports_its_display_rotation(tmp_path):
"""PyAV yields coded frames with no display matrix applied, so read rotation or clips train sideways."""
av = pytest.importorskip("av")
from core.training.diffusion_h3_clips import display_rotation_degrees
clip = tmp_path / "portrait.mp4"
_write_rotated_clip(clip, theta = 90)
with av.open(str(clip)) as container:
stream = container.streams.video[0]
frame = next(container.decode(video = 0))
assert (frame.width, frame.height) == (640, 360), "the coded frame is still landscape"
assert display_rotation_degrees(frame, stream) == 270
def test_an_unrotated_clip_reports_no_rotation(tmp_path):
"""The common case must stay exactly as it was, matrix or no matrix."""
av = pytest.importorskip("av")
from core.training.diffusion_h3_clips import display_rotation_degrees
clip = tmp_path / "landscape.mp4"
_write_rotated_clip(clip, theta = 0)
with av.open(str(clip)) as container:
frame = next(container.decode(video = 0))
assert display_rotation_degrees(frame, container.streams.video[0]) == 0
def test_the_canvas_follows_the_displayed_orientation_not_the_coded_one(tmp_path):
"""``_dataset_canvas`` used to read ``codec_context`` alone, so a portrait clip picked a
LANDSCAPE canvas and every frame was then cover-cropped down to it -- the sides of the real
picture thrown away, on top of training it sideways."""
pytest.importorskip("av")
from core.training.diffusion_h3_trainer import _dataset_canvas
landscape = tmp_path / "landscape.mp4"
portrait = tmp_path / "portrait.mp4"
_write_rotated_clip(landscape, theta = 0)
_write_rotated_clip(portrait, theta = 90)
wide_w, wide_h = _dataset_canvas(str(landscape), 512)
tall_w, tall_h = _dataset_canvas(str(portrait), 512)
assert wide_w > wide_h, (wide_w, wide_h)
assert tall_h > tall_w, "a rotated clip must train on a portrait canvas"
assert (tall_w, tall_h) == (wide_h, wide_w)
def test_decode_clip_returns_the_rotated_picture(tmp_path):
"""End to end: the cached frames are the picture a player shows, not the coded one."""
np = pytest.importorskip("numpy")
pytest.importorskip("av")
from core.training.diffusion_h3_clips import decode_clip
clip = tmp_path / "portrait.mp4"
_write_rotated_clip(clip, theta = 90, seconds = 3)
frames, _waveform = decode_clip(clip, num_frames = 8, width = 64, height = 128)
assert frames.shape == (8, 128, 64, 3)
# The red band occupies the top third of the CODED frame. Rotated 90 CCW for display it
# moves to the left third, so the rotation is observable in the pixels rather than assumed.
first = frames[0].astype("int32")
left = first[:, : 64 // 3, 0].mean()
right = first[:, -(64 // 3) :, 0].mean()
assert left > right + 40, f"red band did not move to the left edge (left {left}, right {right})"
top = first[: 128 // 3, :, 0].mean()
assert left > top + 40, "the band is still along the top, so no rotation was applied"
def test_a_local_modular_pipeline_under_a_gguf_path_is_not_refused_as_gguf(tmp_path):
"""A local modular pipeline under a gguf path must not be refused as a GGUF repo."""
from core.training.diffusion_train_common import resolve_trainable_family
base = tmp_path / "gguf" / "MiniMax-H3"
base.mkdir(parents = True)
(base / "modular_model_index.json").write_text("{}", encoding = "utf-8")
assert resolve_trainable_family(str(base), model_family = "minimax-h3") == "minimax-h3"
def test_a_real_gguf_path_without_a_pipeline_is_still_refused(tmp_path):
"""The exemption is the index file, not the word: an actual GGUF pick must still be refused."""
from core.training.diffusion_train_common import resolve_trainable_family
base = tmp_path / "gguf" / "MiniMax-H3-GGUF"
base.mkdir(parents = True)
with pytest.raises(ValueError, match = "GGUF"):
resolve_trainable_family(str(base), model_family = "minimax-h3")
def test_the_advertised_h3_vram_floor_covers_the_measured_run_peak():
"""Advertised qlora_vram_gb must cover the whole-run peak (77.76 GB measured); cards must hold it."""
from core.training.diffusion_train_common import _FAMILY_TRAIN_SPECS
assert _FAMILY_TRAIN_SPECS["minimax-h3"]["qlora_vram_gb"] >= 78
def test_h3_accepts_every_compile_mode():
"""dynamic=True compiles one graph per block across caption lengths, so "on" is no longer refused."""
from dataclasses import replace as _replace
from core.training.diffusion_train_common import h3_train_unsupported_reason
base = _h3_cfg().normalized()
for mode in ("off", "on", "auto"):
assert h3_train_unsupported_reason(_replace(base, compile_transformer = mode)) is None, mode
@pytest.mark.parametrize("precision, expect_bnb", [("bf16", False), ("nf4", True), ("int8", False)])
def test_h3_routes_its_transformer_through_the_shared_regional_compile(
precision, expect_bnb, monkeypatch, tmp_path
):
"""H3 hands its transformer to the DiT compile wrapper after int8 conversion, before the optimizer."""
import torch
import core.training.diffusion_dit_trainer as dit
import core.training.diffusion_h3_trainer as diffusion_h3_trainer
from core.training.diffusion_h3_trainer import _train_h3
order: list[str] = []
class _Tiny(torch.nn.Module):
def __init__(self):
super().__init__()
self.proj = torch.nn.Linear(4, 4)
def add_adapter(self, _config):
self.lora = torch.nn.Linear(4, 4)
class _Pipe:
text_encoder = processor = vae = audio_vae = None
seen = {}
class _Stop(Exception):
pass
def _compile(transformer, cfg, base_is_bnb, device, on_event, base_precision):
order.append("compile")
seen.update(base_is_bnb = base_is_bnb, base_precision = base_precision)
return False
def _optimizer(*_a, **_k):
order.append("optimizer")
raise _Stop
monkeypatch.setattr(diffusion_h3_trainer, "_load_conditioners", lambda cfg, device: _Pipe())
monkeypatch.setattr(
diffusion_h3_trainer, "_encode_prompt", lambda pipe, cap, device: torch.zeros(1, 3, 8)
)
monkeypatch.setattr(diffusion_h3_trainer, "_dataset_canvas", lambda path, short: (64, 64))
monkeypatch.setattr(diffusion_h3_trainer, "decode_clip", lambda path, **k: (None, None))
lf = h3_video_latent_frames(H3_TRAIN_NUM_FRAMES)
na = h3_audio_latent_count(H3_TRAIN_NUM_FRAMES)
monkeypatch.setattr(
diffusion_h3_trainer,
"_encode_video_stats",
lambda vae, frames, device: (torch.zeros(1, 24, lf, 4, 4), torch.zeros(1, 24, lf, 4, 4)),
)
monkeypatch.setattr(
diffusion_h3_trainer,
"_encode_audio_latents",
lambda avae, wav, device: torch.zeros(2, 32, na),
)
monkeypatch.setattr(
diffusion_h3_trainer, "_load_transformer", lambda cfg, device, precision: _Tiny()
)
monkeypatch.setattr(
dit,
"_int8_quantize_base",
lambda transformer, family, device = None: order.append("int8"),
)
monkeypatch.setattr(dit, "_maybe_compile_transformer", _compile)
monkeypatch.setattr(dit, "_make_optimizer", _optimizer)
cfg = _replace_cfg(_h3_cfg(base_precision = precision, gradient_checkpointing = False))
# No diffusers in Backend CI: stub the two helpers _train_h3 imports, after the family check.
try:
import diffusers.optimization # noqa: F401
import diffusers.training_utils # noqa: F401
except ImportError:
def _cast_training_params(model, dtype):
for param in model.parameters():
if param.requires_grad:
param.data = param.to(dtype)
monkeypatch.setitem(sys.modules, "diffusers", types.ModuleType("diffusers"))
monkeypatch.setitem(
sys.modules,
"diffusers.optimization",
types.SimpleNamespace(get_scheduler = lambda *_a, **_k: None),
)
monkeypatch.setitem(
sys.modules,
"diffusers.training_utils",
types.SimpleNamespace(cast_training_params = _cast_training_params),
)
with pytest.raises(_Stop):
_train_h3(
cfg,
[("clip.mp4", "a caption")],
random.Random(0),
"cpu",
torch.float32,
lambda *_a, **_k: None,
lambda: False,
lambda: True,
)
assert seen == {"base_is_bnb": expect_bnb, "base_precision": precision}
assert order == (["int8"] if precision == "int8" else []) + ["compile", "optimizer"]
def _replace_cfg(cfg):
from dataclasses import replace as _replace
from core.training.diffusion_train_common import train_recipe_overrides
cfg = cfg.normalized()
return _replace(cfg, **train_recipe_overrides(cfg))