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
"""Pure sd-cli argv builder for stable-diffusion.cpp; no torch, diffusers or subprocess imports, so
tests need no GPU, binary, or model files"""
from __future__ import annotations
import functools
import os
import re
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass, field
from typing import Optional
from core.inference.diffusion_memory import (
OFFLOAD_GROUP,
OFFLOAD_MODEL,
OFFLOAD_NONE,
OFFLOAD_SEQUENTIAL,
)
# Text-encoder flags per family, in supply order; keyed by DiffusionFamily.name, not sd.cpp.
_TE_FLAGS_BY_FAMILY: dict[str, tuple[str, ...]] = {
"z-image": ("--llm",),
"flux.2-klein": ("--llm",),
"flux.2-dev": ("--llm",),
"qwen-image": ("--qwen2vl",),
"qwen-image-edit": ("--qwen2vl",),
"qwen-image-layered": ("--qwen2vl",),
# 2.1 conditions on Qwen3-VL via --llm; --qwen2vl also enables Qwen2-VL's vision, the wrong
# door.
"qwen-image-2.1": ("--llm",),
# Qwen3-VL-4B through --llm, as qwen-image-2.1.
"flux.3-klein": ("--llm",),
"flux.3-klein-base": ("--llm",),
"krea-2": ("--llm",),
"flux.1": ("--clip_l", "--t5xxl"),
"flux.1-kontext": ("--clip_l", "--t5xxl"),
}
def text_encoder_flags_for_family(family_name: str) -> tuple[str, ...]:
"""sd-cli text-encoder flags for ``family_name`` (empty if unknown)."""
return _TE_FLAGS_BY_FAMILY.get(family_name, ())
# sd-cli image-gen mode (older txt2img); img2img is the same mode with --init-img.
DEFAULT_MODE = "img_gen"
@dataclass(frozen = True)
class SdCppModelFiles:
"""Resolved on-disk paths for one checkpoint's components. ``diffusion_model`` is required; the
rest are optional (a bundled single-file checkpoint still builds). None fields are omitted."""
diffusion_model: str
vae: Optional[str] = None
audio_vae: Optional[str] = None
clip_l: Optional[str] = None
clip_g: Optional[str] = None
t5xxl: Optional[str] = None
llm: Optional[str] = None
llm_vision: Optional[str] = None
qwen2vl: Optional[str] = None
tokenizer: Optional[str] = None
@dataclass(frozen = True)
class SdCppGenParams:
"""Generation parameters, mapped 1:1 onto sd-cli's sampling flags.
Image-conditioning fields cover the img_gen variants: ``init_img`` + ``strength`` = img2img,
+ ``mask`` = inpaint, ``ref_images`` = FLUX Kontext / Qwen-Image-Edit editing. ``lora_dir`` is
the LoRA directory; individual LoRAs are ``<lora:name:weight>`` tags in ``prompt``.
"""
prompt: str
negative_prompt: Optional[str] = None
# None: unset, so image runs let sd.cpp derive size; plain txt2img defaults to 1024x1024.
width: Optional[int] = None
height: Optional[int] = None
steps: Optional[int] = None
cfg_scale: Optional[float] = None
guidance: Optional[float] = None
seed: Optional[int] = None
sampling_method: Optional[str] = None
scheduler: Optional[str] = None
batch_count: int = 1
init_img: Optional[str] = None
strength: Optional[float] = None
mask: Optional[str] = None
ref_images: tuple[str, ...] = ()
lora_dir: Optional[str] = None
lora_apply_mode: Optional[str] = None
# Qwen-Image-Layered layer count; sd.cpp returns layers + 1 images (first = input reconstruction). None = its default 3.
qwen_image_layers: Optional[int] = None
@dataclass(frozen = True)
class SdCppVideoGenParams:
"""Video generation parameters for sd-cli's ``vid_gen`` mode.
Keyframes and Ref2VA references use separate denoiser partitions. Reference videos are
frame directories, and their WAV soundtracks are paired by index.
"""
prompt: str
width: int
height: int
num_frames: int
fps: int = 24
steps: Optional[int] = None
cfg_scale: float = 1.0
seed: Optional[int] = None
init_img: Optional[str] = None
end_img: Optional[str] = None
ref_images: tuple[str, ...] = ()
ref_videos: tuple[str, ...] = ()
ref_video_audios: tuple[str, ...] = ()
ref_audios: tuple[str, ...] = ()
# sd.cpp exposes only the video schedule shift.
flow_shift: Optional[float] = None
@dataclass(frozen = True)
class SdCppUpscaleParams:
"""Inputs for sd-cli's ESRGAN upscale mode (a separate run mode)."""
input_image: str
upscale_model: str
repeats: int = 1
tile_size: Optional[int] = None
# Fork patch (ggml-patches/0001): quantized matmuls with >= N rows use BF16 dequant + cuBLAS instead of int8 MMQ.
# Q8_0 only (Z-Image Turbo vs BF16, B200: LPIPS 0.0148 -> 0.0052); k-quants are weight-error bound. Ada/Ampere/Orin keep MMQ (2x faster).
# Read from the diffusion GGUF only (A100, Q8_0 DiT + Q4_K_M encoder: 1.57x); the env is process-wide, but prompt rows
# stay below it. Drop the env once the pin carries fork patch 0016, the build's own Q8_0-only default.
QUANT_CUBLAS_ENV = "GGML_CUDA_QUANT_CUBLAS_MIN_BATCH"
QUANT_CUBLAS_WEIGHT_TYPES = frozenset({"Q8_0"})
_UNQUANTIZED_GGUF_TYPES = frozenset({"F32", "F16", "BF16", "F64", "I8", "I16", "I32", "I64"})
def quant_cublas_min_batch(cuda_cc: tuple[int, int]) -> Optional[int]:
"""Rows from which ``cuda_cc`` takes the BF16 cuBLAS route, or None to keep MMQ."""
major, minor = int(cuda_cc[0]), int(cuda_cc[1])
if (major, minor) == (8, 0) or major in (9, 10):
return 1024
if major == 12:
return 4096
return None
def gguf_quantized_weight_types(path: Optional[str]) -> Optional[frozenset[str]]:
"""Quantized tensor types in the GGUF at ``path``, or None if unreadable. Reads only the mmapped tensor table."""
if not path or not str(path).lower().endswith(".gguf"):
return None
try:
from gguf import GGUFReader
reader = GGUFReader(str(path), "r")
return frozenset(t.tensor_type.name for t in reader.tensors) - _UNQUANTIZED_GGUF_TYPES
except Exception: # noqa: BLE001 -- unknown keeps the build's default (MMQ)
return None
def quant_cublas_env(
cuda_ccs: Sequence[tuple[int, int]],
environ: Optional[dict] = None,
weight_types: Optional[frozenset[str]] = None,
) -> dict[str, str]:
"""Set only if every card sd.cpp may pick agrees and the diffusion GGUF is all Q8_0; a user value wins."""
import os
environ = os.environ if environ is None else environ
if QUANT_CUBLAS_ENV in environ or not cuda_ccs:
return {}
if not weight_types or not weight_types <= QUANT_CUBLAS_WEIGHT_TYPES:
return {}
rows = {quant_cublas_min_batch(cc) for cc in cuda_ccs}
if len(rows) != 1 or None in rows:
return {}
return {QUANT_CUBLAS_ENV: str(rows.pop())}
# Native speed profiles. default/max: --diffusion-fa + --diffusion-conv-direct (exact); Metal/Vulkan/ROCm get fa only.
NATIVE_SPEED_OFF = "off"
NATIVE_SPEED_DEFAULT = "default"
NATIVE_SPEED_MAX = "max"
NATIVE_SPEED_MODES = (NATIVE_SPEED_OFF, NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX)
def native_speed_flags(
speed_mode: Optional[str],
backend_args: Optional[Sequence[str]] = None,
accelerator: Optional[str] = None,
binary: Optional[str] = None,
) -> list[str]:
"""sd-cli speed flags for a native speed mode (empty for off / None). Separate from offload:
``--diffusion-fa`` is a win in its own right. De-duplicated against offload at the call site.
``backend_args``: the other argv flags (``--backend`` picks the device); ``accelerator``: build class or None.
``binary``: on builds listing ``--conv-direct`` (master-963+) a rejected direct conv is sent as ``--conv-direct off``,
since an omitted flag means auto there (direct conv on for HIP MMA / Vulkan regardless of this policy)."""
mode = (speed_mode or NATIVE_SPEED_OFF).strip().lower()
if mode in ("", NATIVE_SPEED_OFF):
return []
if mode in (NATIVE_SPEED_DEFAULT, NATIVE_SPEED_MAX):
args = backend_args or ()
if not conv_direct_wanted(args, accelerator):
user_set = any(f in _CONV_DIRECT_FLAGS for f in args)
if not user_set and binary and sd_cpp_supports_conv_direct_mode(binary):
return ["--diffusion-fa", "--conv-direct", "off"]
return ["--diffusion-fa"]
return ["--diffusion-fa", "--diffusion-conv-direct"]
raise ValueError(f"native speed_mode must be one of {NATIVE_SPEED_MODES}, got '{speed_mode}'")
# Flags that already decide direct conv; a user-supplied one wins over the policy.
_CONV_DIRECT_FLAGS = ("--conv-direct", "--diffusion-conv-direct", "--vae-conv-direct")
_VALUED_SPEED_FLAGS = ("--conv-direct",)
def speed_flags_without(speed: Sequence[str], offload: Sequence[str]) -> list[str]:
"""``speed`` minus flags already in ``offload``, keeping a valued flag and its value together."""
out: list[str] = []
i = 0
while i < len(speed):
flag = speed[i]
width = 2 if flag in _VALUED_SPEED_FLAGS and i + 1 < len(speed) else 1
if flag not in offload:
out += list(speed[i : i + width])
i += width
return out
def sd_cpp_supports_conv_direct_mode(binary: str) -> bool:
"""True when ``binary --help`` lists ``--conv-direct``. Fails closed (older builds reject the unknown flag)."""
import os
try:
st = os.stat(binary)
except OSError:
return False
return _conv_direct_in_help(str(binary), st.st_size, st.st_mtime_ns)
@functools.lru_cache(maxsize = 16)
def _conv_direct_in_help(binary: str, size: int, mtime_ns: int) -> bool:
import re
from core.inference.sd_cpp_backend import _sd_cpp_probe_output
text = _sd_cpp_probe_output(binary, "--help")
return text is not None and re.search(r"(?<![\w-])--conv-direct\b", text) is not None
# Direct conv loses to im2col here: Vulkan (sd.cpp #2137, 10.9 -> 73.4 s) and HIP (#2085; gfx1151 never faster).
_CONV_DIRECT_SLOW_BACKENDS = ("vulkan", "rocm", "hip")
def conv_direct_wanted(backend_args: Sequence[str] = (), accelerator: Optional[str] = None) -> bool:
"""``UNSLOTH_SD_CPP_CONV_DIRECT`` = 1/0 forces it (Metal too); else off on Metal, and a ``--backend diffusion=``
pin beats ``accelerator``."""
import os
forced = (os.environ.get("UNSLOTH_SD_CPP_CONV_DIRECT") or "").strip().lower()
if forced in ("1", "on", "true", "yes"):
return True
if forced in ("0", "off", "false", "no"):
return False
if _runs_on_apple_metal(backend_args):
return False
args = list(backend_args)
target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
name = (target or accelerator or "").strip().lower().rstrip("0123456789")
return name not in _CONV_DIRECT_SLOW_BACKENDS
def _diffusion_backend(specs: Sequence[str]) -> Optional[str]:
"""The backend the diffusion module gets from ``--backend`` specs: ``diffusion=`` beats a bare default; None = auto-fit."""
explicit = default = None
for spec in specs:
for part in str(spec).split(","):
key, sep, value = part.strip().partition("=")
if not sep:
default = key or default
elif key.strip().lower() == "diffusion":
explicit = value.strip()
return explicit or default
def _runs_on_apple_metal(backend_args: Sequence[str] = ()) -> bool:
"""True when sd.cpp runs diffusion on Apple Metal (an explicit --backend decides, else Apple
Silicon not paravirtual); direct conv stays off since CONV_2D trips the GPU watchdog."""
import sys
if sys.platform != "darwin":
return False
args = list(backend_args)
target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
if target is not None:
return target.lower() != "cpu"
return apple_silicon_machine() and not metal_is_paravirtual()
@functools.lru_cache(maxsize = 1)
def apple_silicon_machine() -> bool:
"""True on an Apple Silicon Mac, including an x86_64 Python under Rosetta (``hw.optional.arm64``, as install.sh)."""
import platform
import sys
if sys.platform != "darwin":
return False
if platform.machine().lower() in ("arm64", "aarch64"):
return True
try:
import ctypes
import ctypes.util
libc = ctypes.CDLL(ctypes.util.find_library("c"))
value = ctypes.c_int(0)
size = ctypes.c_size_t(ctypes.sizeof(value))
if (
libc.sysctlbyname(
b"hw.optional.arm64", ctypes.byref(value), ctypes.byref(size), None, 0
)
== 0
):
return value.value == 1
except Exception: # noqa: BLE001 -- no answer means an Intel Mac
pass
return False
def forces_cpu_backend(device: Optional[str]) -> bool:
"""True when an sd.cpp run on resolved ``device`` is placed on the CPU backend (a paravirtual Mac GPU)."""
return device == "mps" and metal_is_paravirtual()
# Kill switch for the Metal text-encoder placement below (1/true keeps the encoder on Metal).
_METAL_TE_ON_GPU_ENV = "UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU"
@functools.lru_cache(maxsize = 1)
def metal_is_paravirtual() -> bool:
"""True when this Mac's Metal device is Apple's paravirtual GPU (a macOS VM). Reuses the llama.cpp probe."""
import sys
if sys.platform != "darwin":
return False
try:
from core.inference.llama_cpp import _metal_device_is_paravirtual
except Exception: # noqa: BLE001 -- no probe means no evidence of a VM
return False
try:
return bool(_metal_device_is_paravirtual())
except Exception: # noqa: BLE001
return False
def metal_text_encoder_flags() -> list[str]:
"""Placement flags for sd.cpp on Apple Metal, else nothing.
A paravirtual GPU gets ``--backend cpu``: the bundled ggml segfaults there on CPU-fallback buffers. Otherwise the
text encoder stays on the CPU (``--clip-on-cpu``) since ggml-metal can abort an LLM encoder;
``UNSLOTH_DIFFUSION_SD_CPP_METAL_TE_GPU=1`` keeps it on Metal."""
import os
import sys
if sys.platform != "darwin":
return []
if metal_is_paravirtual():
return list(CPU_BACKEND_FLAGS)
if os.environ.get(_METAL_TE_ON_GPU_ENV, "").strip().lower() in ("1", "true", "yes", "on"):
return []
return ["--clip-on-cpu"]
def metal_placement_flags(offload: Sequence[str]) -> list[str]:
"""``metal_text_encoder_flags()`` minus what ``offload`` already says.
``--backend cpu`` is a flag pair: per-item filtering would leave a dangling ``cpu``, so an explicit pin drops it."""
flags = metal_text_encoder_flags()
if flags == list(CPU_BACKEND_FLAGS):
return [] if "--backend" in offload else flags
return [f for f in flags if f not in offload]
# 1 / 0 forces sd.cpp's --mmap on / off; unset decides from the installed build (``mmap_flags``).
SD_CPP_MMAP_ENV = "UNSLOTH_DIFFUSION_SD_CPP_MMAP"
# Help text of builds whose --mmap still repacks CPU weights (older ones run them unrepacked: slower, other pixels).
CPU_MMAP_REPACK_HELP = "weights the CPU repacks are still loaded"
# leejet/stable-diffusion.cpp#2037 (master-907) maps mmapped weights through Metal device buffers. Older builds accept
# --mmap but hand Metal a CPU buffer it cannot address, so the flag is only safe from this build on.
METAL_MMAP_MIN_BUILD = 907
_INSTALL_RECORD = ".unsloth-sd-cpp-install.json"
# MOSS-Image negative-branch skip, matching diffusion_moss_image.reference_uncond_skip: SFT skips nothing; Base skips
# block 22 while sigma-percent is in 0 .. 0.5 (shift 5: steps 0-12 of 25). Builds without these --extra-sample-args keys
# ignore them and keep sd.cpp's default (block 22 every step); UNSLOTH_MOSS_REFERENCE_SKIP=0 sends nothing.
MOSS_REFERENCE_SKIP_ENV = "UNSLOTH_MOSS_REFERENCE_SKIP"
MOSS_BASE_UNCOND_SKIP_END = 0.5
def moss_is_base_checkpoint(*identities: Optional[str]) -> bool:
"""True when any repo id / folder / filename spells MOSS-Image-Base (separators folded); else the SFT default."""
for identity in identities:
folded = "".join(c for c in str(identity or "").lower() if c.isalnum())
if "mossimagebase" in folded:
return True
return False
def moss_uncond_skip_sample_args(*identities: Optional[str]) -> Optional[str]:
"""sd.cpp ``extra_sample_args`` for a MOSS-Image checkpoint, or None for the binary's every-step default."""
if (os.environ.get(MOSS_REFERENCE_SKIP_ENV) or "").strip().lower() in (
"0",
"off",
"false",
"no",
):
return None
if moss_is_base_checkpoint(*identities):
return f"moss_uncond_skip_start=0,moss_uncond_skip_end={MOSS_BASE_UNCOND_SKIP_END:g}"
return "moss_uncond_skip=false"
def sd_cpp_build_number(tag: Optional[str]) -> Optional[int]:
"""``N`` of a ``master-N-<sha>[-u<sha>]`` release tag, else None."""
import re
m = re.match(r"^master-(\d+)(?:-|$)", str(tag or "").strip())
return int(m.group(1)) if m else None
@functools.lru_cache(maxsize = 8)
def _installed_sd_cpp_tag(binary: str) -> Optional[str]:
"""The release tag Studio's installer recorded next to ``binary`` (the binary sits at or a few levels under the
install root). None for a binary the installer did not place (``SD_CLI_PATH``, PATH, a source build)."""
import json
from pathlib import Path
try:
path = Path(binary).resolve()
except Exception: # noqa: BLE001
return None
for parent in list(path.parents)[:3]:
try:
with open(parent / _INSTALL_RECORD, "r", encoding = "utf-8") as f:
rec = json.load(f)
except (OSError, ValueError):
continue
tag = rec.get("tag") if isinstance(rec, dict) else None
return tag if isinstance(tag, str) and tag else None
return None
def mac_mmap_flags(binary: Optional[str], extra_args: Optional[Sequence[str]] = None) -> list[str]:
"""``["--mmap"]`` on macOS when ``binary`` maps weights correctly on Metal, else nothing.
With it, GGUF / safetensors weights stay clean file-backed pages (Metal wraps them in place, the CPU backend reads
them in place) instead of a second anonymous copy, which on unified memory is the copy that swaps: upstream measured
a Qwen-Image 2.1 Q4_K_M peak footprint of 10.2 -> 1.4 GB on an M1 Pro, pixel-identical. Fails closed on a build it
cannot date; ``UNSLOTH_DIFFUSION_SD_CPP_MMAP`` = 1 / 0 forces it either way."""
import os
import sys
if sys.platform != "darwin" or "--mmap" in (extra_args or ()):
return []
forced = os.environ.get(SD_CPP_MMAP_ENV, "").strip().lower()
if forced in ("0", "false", "no", "off"):
return []
if forced in ("1", "true", "yes", "on"):
return ["--mmap"]
build = sd_cpp_build_number(_installed_sd_cpp_tag(str(binary))) if binary else None
return ["--mmap"] if build is not None and build >= METAL_MMAP_MIN_BUILD else []
@functools.lru_cache(maxsize = 8)
def _installed_sd_cpp_accelerator(binary: str) -> Optional[str]:
"""The accelerator class (``cpu`` / ``cuda`` / ``vulkan`` / ...) Studio's installer recorded next to ``binary``."""
import json
from pathlib import Path
try:
path = Path(binary).resolve()
except Exception: # noqa: BLE001
return None
for parent in list(path.parents)[:3]:
try:
with open(parent / _INSTALL_RECORD, "r", encoding = "utf-8") as f:
rec = json.load(f)
except (OSError, ValueError):
continue
accel = rec.get("accelerator") if isinstance(rec, dict) else None
return accel if isinstance(accel, str) and accel else None
return None
def sd_cpp_mmap_keeps_cpu_repack(binary: str) -> bool:
"""True when ``binary --help`` says its --mmap still repacks CPU weights. Fails closed."""
try:
st = os.stat(binary)
except OSError:
return False
return _cpu_mmap_repack_in_help(str(binary), st.st_size, st.st_mtime_ns)
@functools.lru_cache(maxsize = 16)
def _cpu_mmap_repack_in_help(binary: str, size: int, mtime_ns: int) -> bool:
from core.inference.sd_cpp_backend import _sd_cpp_probe_output
text = _sd_cpp_probe_output(binary, "--help")
return text is not None and CPU_MMAP_REPACK_HELP in text
def mmap_flags(
binary: Optional[str],
extra_args: Optional[Sequence[str]] = None,
backend_args: Optional[Sequence[str]] = None,
) -> list[str]:
"""``--mmap`` on macOS Metal-mmap builds and on CPU renders whose --mmap still repacks CPU weights (keeps
unrepacked weights file-backed: ~4.6 GB vs 13.3 GB anonymous, pixel-identical). GPU renders are left alone."""
import sys
if sys.platform == "darwin":
return mac_mmap_flags(binary, extra_args)
if "--mmap" in (extra_args or ()):
return []
forced = os.environ.get(SD_CPP_MMAP_ENV, "").strip().lower()
if forced in ("0", "false", "no", "off"):
return []
if forced in ("1", "true", "yes", "on"):
return ["--mmap"]
if not binary:
return []
args = [*(backend_args or ()), *(extra_args or ())]
target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
on_cpu = (
target.lower() == "cpu"
if target is not None
else _installed_sd_cpp_accelerator(str(binary)) == "cpu"
)
return ["--mmap"] if on_cpu and sd_cpp_mmap_keeps_cpu_repack(str(binary)) else []
# Everything on the CPU backend. sd.cpp prefers GPU -> integrated GPU -> CPU and only `--backend` changes which
# backend EXECUTES the graph (`--offload-to-cpu` moves parameters, not compute), so this is the one flag that removes
# ggml-metal entirely.
CPU_BACKEND_FLAGS: tuple[str, ...] = ("--backend", "cpu")
# Negative --max-vram auto-detects free VRAM per device; segments on its own.
GRAPH_CUT_VRAM_FLAGS: tuple[str, ...] = ("--max-vram", "-1")
# Upstream honours --stream-layers only under --offload-to-cpu (diffusion params on CPU); otherwise it warns and ignores the flag.
GRAPH_CUT_STREAM_FLAGS: tuple[str, ...] = ("--stream-layers",)
# The full set, for callers that already offload to CPU.
GRAPH_CUT_AUTO_FLAGS: tuple[str, ...] = GRAPH_CUT_VRAM_FLAGS + GRAPH_CUT_STREAM_FLAGS
# The committed "-1" is a placeholder (live server signatures compare on it); a launch swaps it for an explicit GiB
# budget read before the spawn, so the 2 GiB reserve also covers the child's own CUDA context and cuBLAS workspaces.
# Other negative values (UMA pinned-weight reserve) are applied by sd.cpp itself and never replaced.
GRAPH_CUT_BUDGET_RESERVE_BYTES = 2 << 30
GRAPH_CUT_MIN_BUDGET_BYTES = 1 << 30
GRAPH_CUT_RETRY_SCALE = 0.75
GRAPH_CUT_EXPLICIT_BUDGET_ENV = "UNSLOTH_SD_CPP_EXPLICIT_VRAM_BUDGET"
def explicit_vram_budget_enabled(env: Optional[dict] = None) -> bool:
"""Kill switch: ``UNSLOTH_SD_CPP_EXPLICIT_VRAM_BUDGET=0`` keeps sd.cpp's own "-1" free-VRAM reading."""
import os
environ = os.environ if env is None else env
return str(environ.get(GRAPH_CUT_EXPLICIT_BUDGET_ENV, "")).strip().lower() not in (
"0",
"false",
"no",
"off",
)
def graph_cut_budget_gib(
free_bytes: Optional[int],
*,
reserve_bytes: int = GRAPH_CUT_BUDGET_RESERVE_BYTES,
scale: float = 1.0,
) -> Optional[float]:
"""``--max-vram`` GiB for ``free_bytes`` free, or None (keep "-1"). Rounded DOWN so it never exceeds the plan."""
if free_bytes is None:
return None
budget = (int(free_bytes) - int(reserve_bytes)) * float(scale)
if budget < GRAPH_CUT_MIN_BUDGET_BYTES:
return None
return int(budget / float(1 << 30) * 100) / 100.0
def _format_gib(value: float) -> str:
return f"{value:.2f}"
def max_vram_value(flags: Sequence[str]) -> Optional[str]:
items = list(flags)
for i, flag in enumerate(items):
if flag == "--max-vram":
return items[i + 1] if i + 1 < len(items) else None
return None
def max_vram_is_auto(value: Optional[str]) -> bool:
if value is None or "=" in value or "," in value:
return False
try:
return float(value) < 0
except ValueError:
return False
def max_vram_is_placeholder(value: Optional[str]) -> bool:
"""Only the committed ``-1``; a computed UMA reserve (``-17.05``) is sd.cpp's to apply, not a placeholder."""
if not max_vram_is_auto(value):
return False
return float(value) == float(GRAPH_CUT_VRAM_FLAGS[1]) # type: ignore[arg-type]
def with_max_vram_budget(
flags: Sequence[str], budget: "Optional[float | dict[str, float]]"
) -> list[str]:
"""Replace only the ``-1`` placeholder (dict -> ``cuda0=6.25,cuda1=12.50``), never a user or UMA-fit value."""
out = list(flags)
if not budget:
return out
for i, flag in enumerate(out):
if flag != "--max-vram" or i + 1 >= len(out) or not max_vram_is_placeholder(out[i + 1]):
continue
if isinstance(budget, dict):
out[i + 1] = ",".join(f"{name}={_format_gib(gib)}" for name, gib in budget.items())
else:
out[i + 1] = _format_gib(float(budget))
return out
def explicit_max_vram_gib(flags: Sequence[str]) -> "Optional[float | dict[str, float]]":
value = max_vram_value(flags)
if value is None or max_vram_is_auto(value):
return None
try:
if "=" in value:
out: dict[str, float] = {}
for part in value.split(","):
name, _, gib = part.partition("=")
out[name.strip()] = float(gib)
return out
gib = float(value)
except ValueError:
return None
return gib if gib > 0 else None
def scaled_vram_budget(
budget: "float | dict[str, float]", scale: float
) -> "Optional[float | dict[str, float]]":
"""``budget * scale`` per device, or None once any device falls below ``GRAPH_CUT_MIN_BUDGET_BYTES``."""
floor_gib = GRAPH_CUT_MIN_BUDGET_BYTES / float(1 << 30)
def one(gib: float) -> Optional[float]:
value = int(float(gib) * float(scale) * 100) / 100.0
return value if value >= floor_gib else None
if isinstance(budget, dict):
out = {name: one(gib) for name, gib in budget.items()}
if not out or any(v is None for v in out.values()):
return None
return out # type: ignore[return-value]
return one(float(budget))
# Not the model manager's "cannot make enough memory available": completed renders print it too.
_DEVICE_OOM_MARKERS: tuple[str, ...] = (
"erroroutofdevicememory",
"out_of_device_memory",
"cudaerrormemoryallocation",
"hiperroroutofmemory",
"failed to allocate cuda",
"failed to allocate rocm",
"failed to allocate vulkan",
"failed to allocate metal",
"failed during workspace capacity check",
"failed during workspace allocation",
"failed during allocated capacity check",
)
# Bare "out of memory" counts only beside a device API name; host OOM is not cured by a smaller VRAM budget.
_DEVICE_OOM_CONTEXT: tuple[str, ...] = ("cuda", "hip", "rocm", "vulkan", "metal", "ggml_backend")
_HOST_OOM_MARKERS: tuple[str, ...] = (
"host malloc",
"host memory",
"out_of_host_memory",
"bad_alloc",
"cannot allocate memory",
)
def is_device_oom_text(text: Optional[str]) -> bool:
if not text:
return False
for line in str(text).lower().splitlines():
if any(marker in line for marker in _HOST_OOM_MARKERS):
continue
if any(marker in line for marker in _DEVICE_OOM_MARKERS):
return True
if "out of memory" in line and any(word in line for word in _DEVICE_OOM_CONTEXT):
return True
return False
# sd.cpp ``fail_segment`` capacity-check stages (ggml_runner.cpp); "workspace allocation" is an allocator failure.
_SEGMENT_REFUSAL_MARKERS: tuple[str, ...] = (
"failed during weight preparation",
"failed during workspace capacity check",
"failed during allocated capacity check",
)
# Allocator failures on the host RAM that weight preparation stages into, as well as on the device.
_ALLOCATION_FAILURE_MARKERS: tuple[str, ...] = (
*_HOST_OOM_MARKERS,
"erroroutofhostmemory",
"failed to allocate",
"backend buffer failed",
)
# sd.cpp fills free-512 MiB with cached weights, so each phase needs memory the last one released; half leaves it
# unclaimed when the driver reports the release late (Windows may defer destroying allocations).
IMAGE_VRAM_RETRY_SCALE = 0.5
def is_vram_refusal_text(text: Optional[str]) -> bool:
"""sd.cpp's model manager declined a segment for VRAM, and no allocation failed outright (that keeps its error)."""
lines = str(text or "").lower().splitlines()
if not any(marker in line for line in lines for marker in _SEGMENT_REFUSAL_MARKERS):
return False
return not any(
"failed during" not in line
and (
is_device_oom_text(line)
or any(marker in line for marker in _ALLOCATION_FAILURE_MARKERS)
)
for line in lines
)
def image_vram_retry_budget(
planned_free_mib: Optional[Mapping[str, int]], render_devices: Iterable[str] = ()
) -> Optional[str]:
"""``--max-vram`` for the image retry: half of each planned card's free VRAM (``CUDA0=..,CUDA1=..`` for several),
skipping cards under the floor. None if none qualifies or a ``render_devices`` card does not."""
planned = dict(planned_free_mib or {})
budgets: dict[str, float] = {}
for name, mib in planned.items():
gib = graph_cut_budget_gib(int(mib) << 20, reserve_bytes = 0, scale = IMAGE_VRAM_RETRY_SCALE)
if gib is not None:
budgets[name] = gib
if not budgets:
return None
known = {name.lower() for name in budgets}
if any(str(device).lower() not in known for device in render_devices):
return None
if len(planned) == 1:
return _format_gib(next(iter(budgets.values())))
return ",".join(f"{name}={_format_gib(gib)}" for name, gib in budgets.items())
def device_backend_flags(
device_name: Optional[str],
offload: Optional[list[str]] = None,
*,
te_device: Optional[str] = None,
vae_device: Optional[str] = None,
) -> list[str]:
"""Pins only modules the offload policy left on GPU, else sd.cpp uses ordinal 0 on mixed boxes; a later device flag would undo --clip-on-cpu."""
if not device_name:
return []
flags = offload or []
te = "cpu" if "--clip-on-cpu" in flags else (te_device or device_name)
vae = "cpu" if "--vae-on-cpu" in flags else (vae_device or device_name)
return ["--backend", f"diffusion={device_name},te={te},vae={vae}"]
def without_device_backend_flags(flags: Sequence[str]) -> list[str]:
"""Strips every --backend pair: sd.cpp concatenates repeats, so a CPU restart needs the pin gone; status and recipe read empty flags as no offload.
A two-card block split's ``--auto-fit`` / ``--max-vram`` belong to its pin and go with it."""
items = list(flags)
split = any(
f == "--backend" and i + 1 < len(items) and "&" in str(items[i + 1])
for i, f in enumerate(items)
)
paired = ("--backend", "--auto-fit", "--max-vram") if split else ("--backend",)
out: list[str] = []
skip = False
for flag in items:
if skip:
skip = False
continue
if flag in paired:
skip = True
continue
out.append(flag)
return out
# ggml-metal GGML_ABORTs on an unsupported op, killing sd-server mid-generation.
_GGML_UNSUPPORTED_OP_MARKERS = ("unsupported op", "ggml_abort")
def is_ggml_unsupported_op_abort(message: str) -> bool:
"""Only this abort signature is retried on CPU; OOM kills, real bugs, and corrupt checkpoints
are not."""
text = (message or "").lower()
return all(marker in text for marker in _GGML_UNSUPPORTED_OP_MARKERS)
def offload_flags(
policy: str,
*,
vae_tiling: bool = False,
diffusion_fa: bool = False,
vae_on_cpu: bool = True,
) -> list[str]:
"""vae_on_cpu=False drops only --vae-on-cpu, for families whose VAE cannot run on the CPU path."""
flags: list[str] = []
fa = diffusion_fa
tile = vae_tiling
if policy in (OFFLOAD_GROUP, OFFLOAD_MODEL, OFFLOAD_SEQUENTIAL):
flags.append("--offload-to-cpu")
fa = True
if policy in (OFFLOAD_MODEL, OFFLOAD_SEQUENTIAL):
flags.append("--clip-on-cpu")
if vae_on_cpu:
flags.append("--vae-on-cpu")
tile = True
if fa:
flags.append("--diffusion-fa")
if tile:
flags.append("--vae-tiling")
# Stable order, de-duplicated (a forced flag can coincide with a policy one).
seen: set[str] = set()
out: list[str] = []
for f in flags:
if f not in seen:
seen.add(f)
out.append(f)
return out
# sd-cli's own <lora:NAME:W> pattern; it loads an absolute NAME from anywhere, whatever --lora-model-dir says.
_LORA_TAG_RE = re.compile(r"<lora:([^:>]+):([^>]+)>")
def strip_lora_tags(prompt: str) -> str:
"""Removes every tag sd-cli would parse, to a fixed point so a split tag cannot reassemble, plus any dangling
``<lora:`` that could pair with a tag appended after it."""
out, prev = prompt, None
while prev != out:
prev = out
out = _LORA_TAG_RE.sub("", out).replace("<lora:", "")
if out == prompt:
return prompt
return re.sub(r"[ \t]{2,}", " ", out).strip()
def build_sd_cpp_command(
binary: str,
files: SdCppModelFiles,
params: SdCppGenParams,
*,
output_path: str,
offload: Optional[list[str]] = None,
threads: Optional[int] = None,
verbose: bool = False,
extra_args: Optional[list[str]] = None,
) -> list[str]:
"""``extra_args`` go last because sd.cpp's parser is last-wins, so a user can override any flag."""
if not files.diffusion_model:
raise ValueError("diffusion_model path is required")
if not (params.prompt or "").strip():
raise ValueError("prompt is required")
# A --mask without --init-img is invalid (inpaint needs a source image), so reject it here.
if params.mask and not params.init_img:
raise ValueError("init_img is required when mask is set (inpaint needs a source image)")
cmd: list[str] = [binary, "--mode", DEFAULT_MODE, "--diffusion-model", files.diffusion_model]
for flag, value in (
("--vae", files.vae),
("--clip_l", files.clip_l),
("--clip_g", files.clip_g),
("--t5xxl", files.t5xxl),
("--llm", files.llm),
("--llm_vision", files.llm_vision),
("--qwen2vl", files.qwen2vl),
("--tokenizer", files.tokenizer),
):
if value:
cmd += [flag, value]
# Tags are only honoured against a lora_dir the caller filled with validated adapters.
prompt = params.prompt if params.lora_dir else strip_lora_tags(params.prompt)
cmd += ["--prompt", prompt]
if params.negative_prompt:
cmd += ["--negative-prompt", params.negative_prompt]
if params.init_img:
cmd += ["--init-img", params.init_img]
if params.strength is not None:
cmd += ["--strength", _fmt_float(params.strength)]
if params.mask:
cmd += ["--mask", params.mask]
for ref in params.ref_images:
cmd += ["--ref-image", ref]
if params.qwen_image_layers is not None:
cmd += ["--qwen-image-layers", str(int(params.qwen_image_layers))]
# LoRA: the directory to scan; individual LoRAs are <lora:name:w> tags in prompt.
if params.lora_dir:
cmd += ["--lora-model-dir", params.lora_dir]
if params.lora_apply_mode:
cmd += ["--lora-apply-mode", params.lora_apply_mode]
# Unset dims are omitted for image-conditioned runs so sd.cpp derives size; txt2img defaults to 1024.
if params.width is not None or params.height is not None:
w = int(params.width) if params.width is not None else 1024
h = int(params.height) if params.height is not None else 1024
cmd += ["--width", str(w), "--height", str(h)]
elif not (params.init_img or params.ref_images):
cmd += ["--width", "1024", "--height", "1024"]
if params.steps is not None:
cmd += ["--steps", str(int(params.steps))]
if params.cfg_scale is not None:
cmd += ["--cfg-scale", _fmt_float(params.cfg_scale)]
if params.guidance is not None:
cmd += ["--guidance", _fmt_float(params.guidance)]
if params.sampling_method:
cmd += ["--sampling-method", str(params.sampling_method)]
if params.scheduler:
cmd += ["--scheduler", str(params.scheduler)]
if params.seed is not None:
cmd += ["--seed", str(int(params.seed))]
if params.batch_count and params.batch_count != 1:
# The runner collects only --output, so a CLI batch drops images; use the server API.
raise ValueError(
"sd-cli runs are single-image; use the sdcpp server API for batch generation."
)
cmd += ["--output", output_path]
if threads is not None:
cmd += ["--threads", str(int(threads))]
offload = list(offload or [])
if offload:
cmd += offload
cmd += metal_placement_flags(offload)
cmd += mmap_flags(binary, extra_args, offload)
if verbose:
cmd += ["-v"]
if extra_args:
cmd += list(extra_args)
return cmd
def build_sd_cpp_video_command(
binary: str,
files: SdCppModelFiles,
params: SdCppVideoGenParams,
*,
output_path: str,
offload: Optional[list[str]] = None,
threads: Optional[int] = None,
verbose: bool = False,
extra_args: Optional[list[str]] = None,
) -> list[str]:
"""Build one MiniMax-H3 audio-video ``sd-cli`` command (text-only, or keyframe-conditioned)."""
if not files.diffusion_model:
raise ValueError("diffusion_model path is required")
if not files.vae:
raise ValueError("MiniMax-H3 video generation requires a video VAE")
if not files.llm:
raise ValueError("MiniMax-H3 video generation requires its Qwen3-VL text encoder")
if not (params.prompt or "").strip():
raise ValueError("prompt is required")
if params.width <= 0 or params.height <= 0 or params.num_frames <= 0:
raise ValueError("width, height, and num_frames must be positive")
cmd = [
binary,
"--mode",
"vid_gen",
"--diffusion-model",
files.diffusion_model,
"--vae",
files.vae,
]
if files.audio_vae:
cmd += ["--audio-vae", files.audio_vae]
cmd += ["--llm", files.llm]
if files.llm_vision:
cmd += ["--llm_vision", files.llm_vision]
if files.tokenizer:
cmd += ["--tokenizer", files.tokenizer]
# Reject incompatible partitions before loading the model.
if (params.init_img or params.end_img) and (
params.ref_images or params.ref_videos or params.ref_audios
):
raise ValueError(
"MiniMax-H3 keyframes and references cannot be combined: they run against "
"different denoiser partitions."
)
if len(params.ref_video_audios) > len(params.ref_videos):
raise ValueError("each reference video soundtrack needs a reference video to pair with")
if params.init_img:
cmd += ["--init-img", params.init_img]
if params.end_img:
cmd += ["--end-img", params.end_img]
for ref in params.ref_images:
cmd += ["--ref-image", ref]
for ref in params.ref_videos:
cmd += ["--ref-video", ref]
for ref in params.ref_video_audios:
cmd += ["--ref-video-audio", ref]
for ref in params.ref_audios:
cmd += ["--ref-audio", ref]
cmd += [
"--prompt",
# Video has no LoRA selection, so no prompt tag is legitimate.
strip_lora_tags(params.prompt),
"--cfg-scale",
_fmt_float(params.cfg_scale),
"--width",
str(int(params.width)),
"--height",
str(int(params.height)),
"--rng",
"cpu",
"--fps",
str(int(params.fps)),
"--video-frames",
str(int(params.num_frames)),
]
if params.steps is not None:
cmd += ["--steps", str(int(params.steps))]
if params.flow_shift is not None:
cmd += ["--flow-shift", _fmt_float(params.flow_shift)]
if params.seed is not None:
cmd += ["--seed", str(int(params.seed))]
cmd += ["--output", output_path]
if threads is not None:
cmd += ["--threads", str(int(threads))]
offload = list(offload or [])
if offload:
cmd += offload
cmd += metal_placement_flags(offload)
cmd += mmap_flags(binary, extra_args, offload)
if verbose:
cmd.append("-v")
if extra_args:
cmd += list(extra_args)
return cmd
def build_sd_cpp_upscale_command(
binary: str,
params: SdCppUpscaleParams,
*,
output_path: str,
verbose: bool = False,
extra_args: Optional[list[str]] = None,
) -> list[str]:
"""Build the ``sd-cli --mode upscale`` argv (ESRGAN). A distinct run mode: input image + ESRGAN
model, no prompt or text encoders. ``repeats`` runs the upscaler N times (each a fixed scale)."""
if not params.input_image:
raise ValueError("input_image is required for upscale")
if not params.upscale_model:
raise ValueError("upscale_model is required for upscale")
# Reject repeats below 1 explicitly: a truthiness guard would swallow repeats=0 into sd-cli's one-pass default.
if params.repeats < 1:
raise ValueError("repeats must be >= 1 for upscale")
cmd: list[str] = [
binary,
"--mode",
"upscale",
"--init-img",
params.input_image,
"--upscale-model",
params.upscale_model,
]
if params.repeats != 1:
cmd += ["--upscale-repeats", str(int(params.repeats))]
if params.tile_size is not None:
cmd += ["--upscale-tile-size", str(int(params.tile_size))]
cmd += ["--output", output_path]
# Same paravirtual-GPU CPU placement as generation; an explicit --backend in extra_args wins.
if metal_is_paravirtual() and "--backend" not in (extra_args or ()):
cmd += list(CPU_BACKEND_FLAGS)
if verbose:
cmd += ["-v"]
if extra_args:
cmd += list(extra_args)
return cmd
def build_sd_cpp_server_command(
binary: str,
files: SdCppModelFiles,
*,
host: str,
port: int,
vae_format: Optional[str] = None,
offload: Optional[list[str]] = None,
native_speed: Optional[str] = None,
threads: Optional[int] = None,
scratch_dir: Optional[str] = None,
verbose: bool = False,
extra_args: Optional[list[str]] = None,
accelerator: Optional[str] = None,
) -> list[str]:
"""Those dir flags all point at ``scratch_dir``, which must exist: sd-server fails on a missing dir."""
if not files.diffusion_model:
raise ValueError("diffusion_model path is required")
cmd: list[str] = [binary, "--diffusion-model", files.diffusion_model]
for flag, value in (
("--vae", files.vae),
# Without it a resident H3 vid_gen server renders a silent clip.
("--audio-vae", files.audio_vae),
("--clip_l", files.clip_l),
("--clip_g", files.clip_g),
("--t5xxl", files.t5xxl),
("--llm", files.llm),
("--llm_vision", files.llm_vision),
("--qwen2vl", files.qwen2vl),
("--tokenizer", files.tokenizer),
):
if value:
cmd += [flag, value]
if vae_format:
cmd += ["--vae-format", vae_format]
cmd += ["--listen-ip", str(host), "--listen-port", str(int(port))]
if scratch_dir:
cmd += [
"--lora-model-dir",
scratch_dir,
"--hires-upscalers-dir",
scratch_dir,
"--embd-dir",
scratch_dir,
]
if threads is not None:
cmd += ["--threads", str(int(threads))]
offload = list(offload or [])
if offload:
cmd += offload
# De-dup speed flags against offload (may already include --diffusion-fa).
placement = metal_placement_flags(offload)
backend_args = [*offload, *placement, *(extra_args or ())]
cmd += speed_flags_without(
native_speed_flags(native_speed, backend_args, accelerator, binary), offload
)
cmd += placement
cmd += mmap_flags(binary, extra_args, offload)
if verbose:
cmd += ["-v"]
if extra_args:
cmd += list(extra_args)
return cmd
def build_img_gen_request(
*,
prompt: str,
negative_prompt: Optional[str] = None,
width: int = 1024,
height: int = 1024,
steps: Optional[int] = None,
seed: Optional[int] = None,
batch_count: int = 1,
sample_method: Optional[str] = None,
scheduler: Optional[str] = None,
flow_shift: Optional[float] = None,
cfg_scale: Optional[float] = None,
distilled_guidance: Optional[float] = None,
output_format: str = "png",
lora: Optional[list[dict]] = None,
ref_images: Optional[list[str]] = None,
qwen_image_layers: Optional[int] = None,
custom_sigmas: Optional[list[float]] = None,
hires: Optional[dict] = None,
extra_sample_args: Optional[str] = None,
) -> dict:
"""Guidance is split: FLUX distilled values go to distilled_guidance, real CFG scales to txt_cfg."""
if not str(prompt).strip():
raise ValueError("prompt is required")
guidance: dict = {}
if cfg_scale is not None:
guidance["txt_cfg"] = float(cfg_scale)
if distilled_guidance is not None:
guidance["distilled_guidance"] = float(distilled_guidance)
sample_params: dict = {}
if steps is not None:
sample_params["sample_steps"] = int(steps)
if sample_method:
sample_params["sample_method"] = str(sample_method)
if scheduler:
sample_params["scheduler"] = str(scheduler)
if flow_shift is not None:
sample_params["flow_shift"] = float(flow_shift)
if custom_sigmas:
# Same key the server's sample_params parser reads for sd-cli's --sigmas.
sample_params["custom_sigmas"] = [float(s) for s in custom_sigmas]
if guidance:
sample_params["guidance"] = guidance
if extra_sample_args:
sample_params["extra_sample_args"] = str(extra_sample_args)
req: dict = {
"prompt": prompt,
"negative_prompt": negative_prompt or "",
"width": int(width),
"height": int(height),
"batch_count": max(1, int(batch_count)),
"output_format": output_format,
}
if seed is not None:
req["seed"] = int(seed)
if sample_params:
req["sample_params"] = sample_params
# The server resolves lora paths against --lora-model-dir; prompt tags unsupported there.
if lora:
req["lora"] = lora
# Base64 PNGs in model order; no init_image/strength/mask: this is reference conditioning, not img2img.
if ref_images:
req["ref_images"] = list(ref_images)
if qwen_image_layers is not None:
req["qwen_image_layers"] = int(qwen_image_layers)
if hires:
req["hires"] = dict(hires)
return req
def sd_cli_output_paths(output_path: str, num_results: int) -> list[str]:
"""The files one ``sd-cli`` image run writes for ``--output output_path``: the path itself for a
single result, else ``<stem>_<i><ext>`` from 0 (``examples/cli/main.cpp`` ``save_results``).
A layered generation is the multi-result case: layers + 1 images from one run."""
if num_results <= 1:
return [output_path]
stem, dot, ext = output_path.rpartition(".")
if not dot or "/" in ext or "\\" in ext:
stem, ext = output_path, "png"
return [f"{stem}_{i}.{ext}" for i in range(num_results)]
H3_SERVER_REFS_ENV = "UNSLOTH_H3_SERVER_REFS"
# sd-cli's --ref-video reader (examples/cli/main.cpp load_images_from_dir): these extensions, byte-ordered names.
_SD_CLI_FRAME_EXTS = (".jpg", ".jpeg", ".png", ".bmp", ".webp")
# "0" = no family --scheduler / flow-shift variants (sd.cpp default schedule).
FAMILY_SCHEDULER_ENV = "UNSLOTH_SD_CPP_FAMILY_SCHEDULER"
def family_scheduler_enabled() -> bool:
value = os.environ.get(FAMILY_SCHEDULER_ENV, "").strip().lower()
return value not in ("0", "false", "no", "off")
def h3_server_refs_enabled() -> bool:
value = os.environ.get(H3_SERVER_REFS_ENV, "").strip().lower()
return value not in ("0", "false", "no", "off")
def h3_reference_media_keys(params: "SdCppVideoGenParams") -> tuple[str, ...]:
keys = []
if params.ref_videos:
keys.append("ref_videos")
if params.ref_video_audios:
keys.append("ref_video_audios")
if params.ref_audios:
keys.append("ref_audios")
return tuple(keys)
def h3_server_eligible(params: "SdCppVideoGenParams", *, server_refs: bool = False) -> bool:
return server_refs or not h3_reference_media_keys(params)
def sd_cli_frame_files(directory: str) -> list[str]:
entries = [
entry
for entry in os.scandir(directory)
if entry.is_file() and os.path.splitext(entry.name)[1].lower() in _SD_CLI_FRAME_EXTS
]
entries.sort(key = lambda entry: entry.name.encode("utf-8", "surrogateescape"))
return [entry.path for entry in entries]
def build_vid_gen_request(
params: "SdCppVideoGenParams",
*,
images_b64: Optional[dict[str, str]] = None,
ref_images_b64: Optional[list[str]] = None,
output_compression: int = 90,
ref_videos_b64: Optional[list[list[str]]] = None,
ref_video_audios_b64: Optional[list[str]] = None,
ref_audios_b64: Optional[list[str]] = None,
) -> dict:
"""POST body equal to build_sd_cpp_video_command (same pixels per seed); writes AVI, which needs no WebM build; --rng cpu is a server flag passed at spawn."""
if not (params.prompt or "").strip():
raise ValueError("prompt is required")
if params.width <= 0 or params.height <= 0 or params.num_frames <= 0:
raise ValueError("width, height, and num_frames must be positive")
inline_refs = {
"ref_videos": ref_videos_b64,
"ref_video_audios": ref_video_audios_b64,
"ref_audios": ref_audios_b64,
}
for key in h3_reference_media_keys(params):
if len(inline_refs[key] or ()) != len(getattr(params, key)):
raise ValueError(f"{key} must be sent inline to the sd-server vid_gen API")
if len(params.ref_video_audios) > len(params.ref_videos):
raise ValueError("each reference video soundtrack needs a reference video to pair with")
images = dict(images_b64 or {})
if (images.get("init_image") or images.get("end_image")) and (
ref_images_b64 or h3_reference_media_keys(params)
):
raise ValueError(
"MiniMax-H3 keyframes and references cannot be combined: they run against "
"different denoiser partitions."
)
sample_params: dict = {"guidance": {"txt_cfg": float(params.cfg_scale)}}
if params.steps is not None:
sample_params["sample_steps"] = int(params.steps)
if params.flow_shift is not None:
sample_params["flow_shift"] = float(params.flow_shift)
req: dict = {
"prompt": params.prompt,
"width": int(params.width),
"height": int(params.height),
"video_frames": int(params.num_frames),
"fps": int(params.fps),
"sample_params": sample_params,
"output_format": "avi",
"output_compression": int(output_compression),
}
if params.seed is not None:
req["seed"] = int(params.seed)
for key in ("init_image", "end_image"):
if images.get(key):
req[key] = images[key]
if ref_images_b64:
req["ref_images"] = list(ref_images_b64)
for key in h3_reference_media_keys(params):
req[key] = [list(item) if key == "ref_videos" else item for item in inline_refs[key]]
return req
def _fmt_float(value: float) -> str:
"""Compact float -> str: drop a trailing ``.0`` (``1.0`` -> ``1``) to keep logged commands tidy."""
f = float(value)
return str(int(f)) if f.is_integer() else repr(f)