MiniMax-H3

MiniMax-H3 tạo ra video và âm thanh của nó cùng lúc. Một transformer duy nhất khử nhiễu một chuỗi được đóng gói chứa điều kiện văn bản, phương tiện điều kiện, và các latent video và âm thanh đích. Không có vocoder riêng biệt và không có bước xử lý âm thanh sau: video và âm thanh được tạo ra từ cùng một vòng lặp khử nhiễu.

Bạn có thể tìm thấy các checkpoint MiniMax-H3 gốc dưới tổ chức MiniMaxAI.

MiniMax-H3 được tích hợp dưới dạng các khối Modular Diffusers duy nhất, giống như cách Anima được tích hợp: các khối và MiniMaxH3ModularPipeline của chúng là toàn bộ phần tích hợp, và không có nửa DiffusionPipeline.

Bố cục checkpoint

MiniMax-H3 được phát hành dưới dạng hai phân vùng checkpoint chia sẻ mọi thành phần ngoại trừ transformer, do đó quá trình chuyển đổi diffusers đặt cả hai vào một kho lưu trữ:

Mọi thứ ngoại trừ transformer, tức là video VAE, audio VAE, bộ điều kiện Qwen3-VL, tokenizer và processor của nó, cùng hai scheduler, đều được chia sẻ và chỉ lưu trữ một lần.

Bộ điều kiện là Qwen3VLForConditionalGeneration, và MiniMax-H3 đọc trạng thái ẩn chưa chuẩn hóa sau lớp decoder thứ 50 thay vì lớp cuối cùng, do đó toàn bộ checkpoint được phát hành được sử dụng với đầu mô hình ngôn ngữ không được dùng đến.

Cả ba tác vụ đều là các luồng công việc của MiniMaxH3Blocks, và kho lưu trữ chứa một modular_model_index.json đặt tên cho mọi thành phần cùng với thông số tải riêng của chúng. Để triển khai một tác vụ duy nhất, hãy truyền luồng công việc đó vào from_pretrained: nó chỉ giữ lại các khối của luồng công việc đó, nên chữ ký của pipeline (pipe.doc) mô tả chính xác các đầu vào của tác vụ đó, chỉ các thành phần của tác vụ đó được khai báo, và load_components chỉ lấy đúng các thư mục con của chúng — một pipeline t2va / fl2va sẽ không bao giờ chạm đến transformer_ref/, còn một pipeline ref2va sẽ không bao giờ chạm đến transformer/.

import torch
from diffusers import ModularPipeline

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

pipe.doc in ra những gì pipeline trước mặt bạn nhận vào và trả về — mọi đầu vào cùng giá trị mặc định, các thành phần mà nó kỳ vọng và các đầu ra mà nó tạo ra. Được rút gọn xuống một quy trình duy nhất, nó mô tả chính xác nhiệm vụ đó, đây là cách nhanh nhất để xem một yêu cầu cần gì trước khi thực hiện.

Để giữ mọi workflow khả dụng trên một pipeline duy nhất, hãy bỏ qua đối số workflow: khi đó pipeline sẽ tự chọn workflow cho từng lần gọi dựa trên các đầu vào được truyền vào.

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

Việc tải vẫn có thể được thực hiện theo từng quy trình một. Một lệnh gọi duy nhất này sẽ lấy transformer/ và tất cả các thành phần dùng chung, phục vụ cho cả t2va và fl2va:

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

Một lệnh load_components() đơn thuần không có workflow= sẽ tải cả hai phân vùng transformer 61.7GB, điều này cho phép một pipeline phục vụ cả ba workflow mà không cần thêm lệnh tải nào khác. Kết hợp nó với ComponentsManager và auto offloading: trọng số nằm trong RAM của host và trình quản lý chỉ chuyển lên bộ tăng tốc những gì mỗi bước cần, nên khi bộ khử nhiễu ref2va yêu cầu thiết bị, chiến lược sẽ offload bất kỳ thứ gì để giải phóng đủ dung lượng. Xem Memory để biết các công thức.

Hai trình lập lịch

Latents video và audio đi theo hai lịch trình khác nhau trong một lần gọi transformer duy nhất cho mỗi bước, đó là lý do các khối mong đợi hai instance MiniMaxH3Scheduler: scheduler cho latents video (shift=12.0 trong các checkpoint đã phát hành) và audio_scheduler cho latents audio (shift=3.0).

Cả hai phân vùng transformer đều được chưng cất theo hướng dẫn, vì điều này đúng với mọi quy trình làm việc: hướng dẫn được tích hợp vào trọng số, không có bộ hướng dẫn, không có negative_prompt và không có guidance_scale, và mỗi bước chỉ chạy đúng một lần truyền thẳng.

Ràng buộc sinh

• 24 fps, 5 đến 15 giây. num_frames được làm tròn lên đến giá trị 17 * n + 5 gần nhất mà video VAE có thể giải mã, và thời lượng kết quả phải nằm trong khoảng đó.
• Cạnh ngắn 768 pixel. height và width mặc định là canvas riêng của MiniMax-H3 cho tỷ lệ khung hình của keyframe đầu tiên (hoặc 16:9 nếu không có) và phải là bội số của 32.
• Một generator, ba lần rút. Một yêu cầu sẽ rút nhiễu điều kiện keyframe hoặc tham chiếu trước tiên, sau đó là nhiễu video, rồi đến nhiễu âm thanh, tất cả đều từ generator được truyền vào, do đó hai lần chạy từ cùng một trạng thái generator sẽ trả về cùng một video và bản nhạc nền. Việc truyền latents hoặc audio_latents sẽ thay thế lần rút tương ứng.
• num_inference_steps đếm các điểm lưới sigma, bao gồm 0 cuối cùng, do đó nó dẫn đến ít một lần đánh giá mô hình hơn.

Bộ nhớ

Mô hình transformer đơn thuần chiếm 61,7 GB ở bfloat16 và bộ điều kiện Qwen3-VL chiếm thêm 62,1 GB, nên quy trình nạp phụ thuộc vào phần cứng. Kích thước khung hình nhỏ hơn là đòn bẩy tốc độ lớn nhất trên mọi cấu hình: height và width chỉ cần là bội số của 32, và 960x544 chạy nhanh hơn khoảng 2,3 lần mỗi bước so với 1344x768 được huấn luyện.

Trên một card 80 GB, đăng ký các thành phần trong ComponentsManager và để nó di chuyển chúng lên và xuống bộ tăng tốc:

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

Trên card tiêu dùng (24 đến 32 GB), hãy lượng tử hóa hai thành phần lớn xuống int8 khi chúng được nạp và stream các khối của transformer từ RAM CPU. Tất cả các nội dung bên dưới chỉ sử dụng các trình nạp được hỗ trợ, không cần vá, và hoạt động trực tiếp từ checkpoint 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")

Trên 12 đến 16 GB, cùng một công thức vẫn hoạt động khi nhóm video VAE cũng được offload (offload_type="leaf_level", không có stream) và một canvas nhỏ như 960x544. Hãy kỳ vọng các trọng số sẽ nằm trong RAM của host: khoảng 75 GB ở int8.

Với hai thẻ, không cần phải offload: chia pipeline thành hai phần và đặt mỗi phần trên một thiết bị riêng.

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"],
)

Hai thẻ 80 GB chạy đầy đủ bfloat16 theo cách này: mỗi nửa nằm gọn trên một thẻ riêng, nên không có gì bị đẩy ngược về bộ nhớ host một khi đã được nạp. Hai thẻ 48 GB làm tương tự với việc nạp int8 ở trên cho cả hai thành phần.

Văn bản và các khung hình chính

MiniMaxH3Blocks hỗ trợ tạo video và âm thanh từ văn bản cũng như điều kiện theo khung hình chính. Khung hình chính có thể là khung hình mà video bắt đầu (image), khung hình mà video kết thúc (last_image), hoặc cả hai.

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"],
)

Video và audio được tạo đồng thời và được trả về từ cuộc gọi dưới dạng các đầu ra riêng biệt, videos và audio, bên cạnh sampling_rate mà bản nhạc nền mang theo; việc ghép chúng vào một tệp duy nhất được để lại cho người gọi, ví dụ bằng encode_video().

Tham chiếu toàn diện

Workflow ref2va điều kiện dựa trên một danh sách các tham chiếu có thứ tự: tối đa 9 hình ảnh, 3 video và 3 đoạn âm thanh, tổng cộng 12 mục. Thứ tự mang tính ngữ nghĩa. Nó gắn nhãn cho các tham chiếu trong cách trình bày prompt ("<Picture 1>", "<Audio 1>", "<Video 1>") và nó làm tiến bộ đồng hồ rotary âm thanh/video dùng chung, do đó việc sắp xếp lại cùng các tham chiếu đó sẽ tạo thành một yêu cầu khác.

Khác với các keyframe ở trên, các tham chiếu không ràng buộc hình học được tạo ra: chúng được mã hóa ở độ phân giải riêng của chúng và khung canvas đích mặc định là 16:9 của MiniMax-H3.

Có một lớp tham chiếu cho mỗi phương thức, mỗi lớp lưu trữ phương tiện trong bộ nhớ và tốc độ mà phương tiện mang theo:

Các tần số là nơi mọi thứ được lấy mẫu lại: các khung hình được chuyển sang 24 fps của chính MiniMax-H3 bằng cách loại bỏ và nhân bản toàn bộ các khung hình, còn dạng sóng được chuyển sang tần số lấy mẫu của VAE âm thanh. Phương tiện có tần số trùng với tần số của MiniMax-H3 sẽ đi qua mà không bị thay đổi, do đó chỉ dữ liệu được tạo ở tần số khác mới cần khai báo điều này.

Một tham chiếu được xây dựng theo một trong hai cách: giải mã từ tệp phương tiện bằng phương thức lớp from_file của lớp, hoặc được xây dựng trực tiếp từ phương tiện mà yêu cầu đã giữ trong bộ nhớ — đây là cách một thế hệ trước đó được phản hồi lại (xem Một thế hệ như một tham chiếu).

Các khối không bao giờ mở tệp media — việc giải mã đường dẫn là trách nhiệm của người gọi, giống như ở mọi nơi khác trong thư viện. Mỗi lớp tham chiếu thực hiện điều này thông qua classmethod from_file, nhận một đường dẫn hoặc URL (video và audio thông qua PyAV) và trả về một tham chiếu mang các tỷ lệ mà container báo cáo — một video sẽ kèm theo tỷ lệ khung hình và bản nhạc nền của nó. Nên dùng from_file thay vì load_video(), vì hàm này làm mất tỷ lệ khung hình: một tham chiếu được xây dựng từ các khung hình mà tỷ lệ thực của chúng đã bị mất sẽ được điều kiện hóa ở tốc độ sai, và không có gì báo lỗi.

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 là bắt buộc đối với ref2va. Để tạo video có độ dài chính xác bằng bản nhạc nền tham chiếu, hãy tính từ clip — round(samples / sample_rate * 24) — và giá trị này sẽ được làm tròn lên bội số tiếp theo của 17 * n + 5 mà VAE video có thể giải mã; độ dài kết quả phải nằm trong khoảng từ 5 đến 15 giây mà MiniMax-H3 tạo ra.

Một thế hệ như một tham chiếu

Vì các workflow chia sẻ một pipeline, một bản tạo t2va có thể được đưa trực tiếp trở lại làm tham chiếu ref2va — và bộ khởi tạo trong bộ nhớ được xây dựng chính xác cho việc chuyển giao này. Phương tiện được tạo ra đã ở đúng tốc độ của chính MiniMax-H3 (khung hình ở 24 fps, bản nhạc nền ở tốc độ lấy mẫu của VAE âm thanh), do đó tham chiếu không cần các đối số tốc độ và không có gì bị mã hóa lại qua một container mất mát trên đường đi:

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