MiniMax-H3

MiniMax-H3 генерирует видео и его звуковую дорожку одновременно. Единый трансформер выполняет денойзинг одной упакованной последовательности, содержащей текстовые условия, медиа для условий, а также целевые латенты видео и аудио. Отдельный вокодер и последующая обработка аудио отсутствуют: видео и аудио получаются в рамках одного и того же цикла денойзинга.

Оригинальные контрольные точки MiniMax-H3 можно найти в организации MiniMaxAI.

MiniMax-H3 интегрируется только в виде блоков Modular Diffusers, так же, как и Anima: сами блоки и их MiniMaxH3ModularPipeline составляют всю интеграцию, и части DiffusionPipeline здесь нет.

Раскладка контрольной точки

MiniMax-H3 был выпущен в виде двух разделов контрольных точек, которые разделяют все компоненты, кроме трансформера, поэтому конвертация в diffusers помещает оба в одно репозиторий:

Всё, кроме трансформера, а именно видео-VAE, аудио-VAE, кондиционер Qwen3-VL, его токенизатор и процессор, а также два планировщика, является общим и хранится один раз.

Кондиционером является Qwen3VLForConditionalGeneration, а MiniMax-H3 читает ненормализованное скрытое состояние после 50-го слоя декодера, а не последнего, поэтому используется полный опубликованный чекпоинт, при этом его головная часть языковой модели не задействуется.

Все три задачи представляют собой рабочие процессы единого MiniMaxH3Blocks, а в репозитории находится один modular_model_index.json, в котором каждый компонент указан со своим собственным спецификацией загрузки. Чтобы обслуживать одну задачу, передайте рабочий процесс в from_pretrained: он оставляет только блоки этого рабочего процесса, поэтому сигнатура пайплайна (pipe.doc) документирует именно входные данные этой задачи, объявляются только компоненты этой задачи, а load_components загружает ровно их подпапки — пайплайн t2va / fl2va никогда не обращается к transformer_ref/, а пайплайн ref2va — к transformer/.

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
pipe.load_components(dtype=torch.bfloat16)

pipe.doc показывает, что принимает и возвращает текущий конвейер: каждый входной параметр с его значением по умолчанию, ожидаемые компоненты и создаваемые выходные данные. Суженный до одного рабочего процесса, он описывает именно эту задачу, что является самым быстрым способом понять, что требуется для запроса, прежде чем его отправить.

Чтобы все рабочие процессы оставались доступными в одном конвейере, просто не указывайте аргумент workflow: тогда конвейер будет выбирать рабочий процесс для каждого вызова на основе переданных входных данных.

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")

Загрузка loading по-прежнему может выполняться по одному рабочему процессу за раз. Этот один вызов загружает transformer/ и все общие компоненты, которые используются как в t2va, так и в fl2va:

pipe.load_components(workflow="t2va", dtype=torch.bfloat16)

Обычный вызов load_components() без параметра workflow= загружает оба раздела трансформера по 61,7 ГБ, что позволяет одному конвейеру обслуживать все три сценария без повторного вызова загрузки. В сочетании с ComponentsManager и автоматическим выгрузкой (offloading) веса хранятся в оперативной памяти хоста, а менеджер переносит на ускоритель только то, что требуется на каждом шаге: когда денуизеру ref2va требуется устройство, стратегия выгрушает то, что освобождает достаточно места. Рецепты описаны в разделе Память.

Два планировщика

Видео- и аудиолатенты на каждом шаге внутри одного вызова трансформера следуют по двум разным расписаниям, поэтому блоки ожидают два экземпляра MiniMaxH3Scheduler: scheduler для видеолатентов (shift=12.0 в выпущенных контрольных точках) и audio_scheduler для аудиолатентов (shift=3.0).

Обе трансформерные партиции прошли дистилляцию с использованием guidance, поэтому это верно для любого рабочего процесса: guidance вшит в веса, guider отсутствует, как и negative_prompt и guidance_scale, а на каждом шаге выполняется ровно один прямой проход.

Ограничения генерации

• 24 fps, от 5 до 15 секунд. Значение num_frames округляется вверх до ближайшего числа вида 17 * n + 5, которое может декодировать видео-VAE, при этом итоговая длительность должна оставаться в указанном диапазоне.
• Короткая сторона 768 пикселей. Параметры height и width по умолчанию соответствуют собственному холсту MiniMax-H3 для соотношения сторон первого ключевого кадра (или 16:9, если его нет) и должны быть кратны 32.
• Один генератор, три выборки. Запрос сначала извлекает шум для ключевых кадров или референсного условия, затем шум для видео, затем шум для аудио — всё из переданного ему generator, поэтому два запуска из одного и того же состояния генератора возвращают одинаковое видео и звуковую дорожку. Передача latents или audio_latents заменяет соответствующую выборку.
• num_inference_steps учитывает точки сетки сигм, включая конечную 0, поэтому на одно вычисление модели меньше.

Память

Сам трансформатор занимает 61,7 ГБ в bfloat16, а conditioner Qwen3-VL — ещё 62,1 ГБ, поэтому способ загрузки зависит от аппаратного обеспечения. Уменьшение холста — самый мощный рычаг ускорения на любой конфигурации: height и width должны быть кратны 32, а разрешение 960x544 выполняется примерно в 2,3 раза быстрее на каждом шаге по сравнению с обученным разрешением 1344x768.

На одной карте на 80 ГБ зарегистрируйте компоненты в ComponentsManager и позвольте ему перемещать их на акселератор и с него:

import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="12GB")  # or "mps", "xpu", "cpu"
pipe.transformer.set_attention_backend("_flash_3_hub")  # Hopper, roughly 3x faster; kernels fetched from the Hub

На потребительской карте (24–32 ГБ) квантуйте два крупных компонента до int8 при загрузке и передавайте блоки трансформера из оперативной памяти CPU. Всё, что описано ниже, использует только поддерживаемые загрузчики, не требует патчей и работает напрямую из контрольной точки bfloat16:

import torch
from diffusers import MiniMaxH3Transformer3DModel, ModularPipeline, TorchAoConfig
from diffusers.hooks import apply_group_offloading
from transformers import Qwen3VLForConditionalGeneration
from transformers import TorchAoConfig as TransformersTorchAoConfig
from torchao.quantization import Int8WeightOnlyConfig

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.update_components(
    transformer=MiniMaxH3Transformer3DModel.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16,
        quantization_config=TorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=[
                "proj_in", "audio_proj_in", "context_embedder", "time_embedder", "time_proj",
                "token_refiner", "norm_out", "proj_out", "audio_proj_out",
            ],
        ),
        low_cpu_mem_usage=False,
    ),
    text_encoder=Qwen3VLForConditionalGeneration.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="text_encoder", dtype=torch.bfloat16,
        quantization_config=TransformersTorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=["model.visual", "model.language_model.embed_tokens", "model.language_model.norm", "lm_head"],
        ),
    ),
)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)

# version=2 int8 tensors are pinnable, which streamed offload needs, and freezing removes the one autograd
# path the quantized tensors cannot serve.
pipe.transformer.requires_grad_(False)
pipe.text_encoder.requires_grad_(False)

offload = dict(onload_device=torch.device("cuda"), offload_device=torch.device("cpu"), use_stream=True)
pipe.transformer.enable_group_offload(offload_type="block_level", num_blocks_per_group=1, **offload)
apply_group_offloading(pipe.text_encoder.model, offload_type="leaf_level", **offload)
pipe.vae.to("cuda")  # or "mps", "xpu", "cpu"
pipe.audio_vae.to("cuda")

На 12–16 ГБ тот же рецепт работает и с выгруженной группой видео-VAE (offload_type="leaf_level", без потока) и с небольшим холстом, например 960x544. Ожидайте, что веса будут находиться в оперативной памяти хоста: около 75 ГБ при int8.

При наличии двух карт ничего не нужно выгружать: разделите конвейер пополам и разместите каждую половину на своём устройстве.

import torch
from diffusers import ComponentsManager, ModularPipeline

workflow = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3").blocks.get_workflow("t2va")

text_manager = ComponentsManager()
text_manager.enable_auto_cpu_offload(device="cuda:1")
conditioner = workflow.sub_blocks.pop("text_encoder").init_pipeline(
    "MiniMaxAI/MiniMax-H3", components_manager=text_manager
)
conditioner.load_components(dtype=torch.bfloat16)

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda:0")
rest = workflow.init_pipeline("MiniMaxAI/MiniMax-H3", components_manager=manager)
rest.load_components(dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
state = conditioner(prompt=prompt)
results = rest(
    state=state,
    num_frames=124,
    generator=torch.Generator().manual_seed(42),
    output=["videos", "audio", "sampling_rate"],
)

Две карты по 80 ГБ запускают полную модель в bfloat16 следующим образом: каждая половина помещается на свою карту, поэтому после загрузки в память ничего не выгружается обратно в память хоста. Две карты по 48 ГБ делают то же самое с загрузкой int8, описанной выше, для обоих компонентов.

Текст и ключевые кадры

MiniMaxH3Blocks поддерживает генерацию видео и аудио по тексту, а также условное формирование по ключевым кадрам. Ключевым кадром может быть кадр, с которого начинается видео (image), кадр, на котором оно заканчивается (last_image), или оба.

import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import load_image
from diffusers.utils.export_utils import encode_video

# 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are
# registered in a manager that moves each one on and off as the blocks reach it. See [Memory](#memory).
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="fl2va", dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
# `output=` returns exactly the named outputs instead of the whole pipeline state.
outputs = ["videos", "audio", "sampling_rate"]

# Text to video + audio.
results = pipe(prompt=prompt, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

# First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe.
image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)
results = pipe(prompt=prompt, image=image, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_fl2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)

Видео и аудио генерируются совместно и возвращаются из вызова как отдельные выходные данные, videos и audio, наряду с sampling_rate, которое несёт звуковой дорожкой; их мультиплексирование в один файл остаётся на усмотрение вызывающего кода, например, с помощью encode_video().

Омни-ссылки

Рабочий процесс ref2va использует в качестве условия упорядоченный список эталонных данных: до 9 изображений, 3 видео и 3 аудиоклипов, всего 12. Порядок имеет семантическое значение. Он определяет метки эталонных данных в представлении промпта ("<Picture 1>", "<Audio 1>", "<Video 1>") и сдвигает общую аудио/видео ротационную шкалу времени, поэтому изменение порядка тех же эталонных данных представляет собой другой запрос.

В отличие от ключевых кадров выше, референсы не ограничивают генерируемую геометрию: они кодируются в собственном разрешении, а целевой холст по умолчанию имеет соотношение сторон 16:9, как у MiniMax-H3.

Для каждой модальности существует один класс-ссылка, каждый из которых хранит медиа в памяти и частоту, с которой передаются медиа:

Скорости — это то, от чего происходит вся пересэмплирование: кадры приводятся к собственным 24 fps модели MiniMax-H3 путём удаления и дублирования целых кадров, а волновая форма — к частоте дискретизации аудио-VAE. Медиа, записанное с собственными скоростями MiniMax-H3, проходит без изменений, поэтому только данные, созданные с другой скоростью, должны это указывать.

Ссылка (reference) формируется одним из двух способов: декодируется из медиафайла с помощью метода класса from_file или строится непосредственно из медиа, которые запрос уже хранит в памяти — именно так результат предыдущего поколения возвращается в процесс (см. Поколение как ссылка).

Блоки никогда не открывают медиафайл — декодирование пути является задачей вызывающего кода, как и везде в библиотеке. Каждый класс-ссылка выполняет это через класс-метод from_file, который принимает путь или URL (видео и аудио через PyAV) и возвращает ссылку, несущую частоты, сообщаемые контейнером — видео приносит с собой частоту кадров и звуковую дорожку. Предпочитайте from_file перед load_video(), который теряет частоту кадров: ссылка, построенная из кадров, чья реальная частота была потеряна, будет обусловлена с неправильной скоростью, и при этом ничего не будет выброшено.

import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import (
    MiniMaxH3AudioReference,
    MiniMaxH3ImageReference,
    MiniMaxH3VideoReference,
)
from diffusers.utils import load_video
from diffusers.utils.export_utils import encode_video

# `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
# checkpoint partition, and the manager moves each component on and off the accelerator in turn.
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

subject = MiniMaxH3ImageReference.from_file(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)

# Decoding a file brings its rates along: the video its own frame rate and its soundtrack, the clip its sample rate.
results = pipe(
    prompt="The character speaks in time with the reference recording, natural lip movement",
    references=[
        subject,
        MiniMaxH3VideoReference.from_file(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
        ),
        MiniMaxH3AudioReference.from_file("voice.wav"),
    ],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

# Frames a request already holds declare the rate they carry — `load_video` does not preserve it.
motion = load_video("motion_ref.mp4")
results = pipe(
    prompt="The subject walks toward camera, matching the reference video's shot rhythm",
    references=[subject, MiniMaxH3VideoReference(frames=motion, fps=30.0)],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_ref2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)

num_frames обязателен для ref2va. Чтобы сгенерировать видео точно такой же длины, как референсный звуковой дорожкой, вычислите его из клипа — round(samples / sample_rate * 24) — и он будет округлён вверх до ближайшего значения вида 17 * n + 5, которое может декодировать видео-VAE; итоговая длительность должна оставаться в пределах от 5 до 15 секунд, которые генерирует MiniMax-H3.

Поколение как эталон

Поскольку рабочие процессы используют один и тот же конвейер, результат генерации t2va можно сразу передать в качестве эталона для ref2va — и конструктор в памяти создан именно для такой передачи. Сгенерированные медиа уже соответствуют собственным частотам MiniMax-H3 (кадры с частотой 24 к/с, звуковая дорожка с частотой дискретизации аудио-VAE), поэтому для эталона не нужны аргументы частоты, и на пути передачи ничего не перекодируется через контейнер с потерями:

import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3VideoReference

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

# The full pipeline holds every workflow and picks one per call from the inputs. Loading without a
# `workflow=` brings both transformer partitions in one call, so the `ref2va` request that follows the
# `t2va` generation needs no further loading.
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

results = pipe(
    prompt="An astronaut hiking through the mountains, humming a tune",
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

reference = MiniMaxH3VideoReference(
    frames=results["videos"][0],
    audio=results["audio"][0],
    sample_rate=results["sampling_rate"],
)
results = pipe(
    prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
    references=[reference],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

MiniMaxH3ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.load_components(dtype=torch.bfloat16)

MiniMaxH3Blocks

MiniMaxH3ImageReference

MiniMaxH3VideoReference

MiniMaxH3AudioReference