MiniMax-H3

Docker 형식은 이미지에 번들된 소스에서 플랫폼별 diffusion extra를 설치합니다. 컨디셔닝 요청에는 Variables 아래 Host media directory를 설정하세요. 빌더가 이를 /data/minimax-h3에 읽기 전용으로 마운트합니다. AMD와 Grace Blackwell은 현재 Python 형식만 제공하고, 다른 NVIDIA 레시피는 Docker도 제공합니다.

같은 일반 sglang serve 경로로 ModelScope를 쓰려면 복사한 명령 앞에 SGLANG_USE_MODELSCOPE=true를 붙이고 모델 경로를 MiniMax/MiniMax-H3로 바꾸세요. 선택한 variant와 토폴로지 플래그는 그대로 두세요.

플랫폼별 설치 세부사항은 SGLang Diffusion 설치 가이드를 참조하세요.

2. 모델 성능 (Model capabilities)

동기화된 오디오-비주얼 출력이나 레퍼런스 기반 생성이 가벼운 배포보다 중요할 때 H3를 선택하세요. 공개 레시피는 24 fps에서 768px 짧은 모서리, 4–15초를 대상으로 하며, 성능이 두 체크포인트 파티션으로 나뉘어 모든 모드를 서빙하려면 별도의 FL2VA와 Ref2VA 배포가 필요합니다.

비디오-투-비디오(V2V)는 지원되는 ref2va 사용 사례일 뿐 네 번째 task 값이 아닙니다. Ref2VA 파티션을 실행하고 conditions에 비디오 레퍼런스를 제공하세요. 하이브리드 ref2va 요청은 fl2va가 받는 것과 같은 정렬된 첫/마지막 키프레임을 포함할 수 있지만, 반드시 최소 하나의 레퍼런스 컨디션을 포함해야 합니다.

선택한 Hub의 루트 모델 ID를 사용하세요. Hugging Face의 MiniMaxAI/MiniMax-H3 또는 ModelScope의 MiniMax/MiniMax-H3. --model-variant로 체크포인트 variant를 선택합니다. fl2va는 t2va와 fl2va를 모두 서빙하고, ref2va는 레퍼런스-컨디셔닝 요청을 서빙합니다. SGLang이 체크포인트-디렉터리 매핑을 담당하므로 --model-path를 수동으로 다운로드한 하위 디렉터리에 지정하지 마세요.

3. 배포 세부사항 (Deployment details)

빌더는 합법적인 커스텀 GPU 수와 토폴로지를 받아들이며, 정확한 레시피가 end-to-end 검증을 끝내기 전까지 Unverified로 표시합니다. 정적 H3 헤드·파티션 위반은 sglang serve에 도달하기 전에 Copy를 비활성화합니다.

Grace Blackwell

빌더에서 GB300 또는 GB200을 선택하세요. 기본은 GPU 4개, Ulysses4, 상주 가중치를 갖춘 Linux ARM64 호스트 1대입니다. 이는 4-GPU 컴퓨트-트레이 레이아웃을 따릅니다. NVL72 랙은 단일 72-GPU 프로세스 호스트가 아닙니다.

4-GPU 호스트 2대를 쓰려면 Nodes = 2와 GPUs / node = 4로 설정하세요. 빌더는 각 호스트 안에 Ulysses4, 호스트 간 Ring2, 복제 인코더를 생성합니다. 양쪽 호스트에 같은 도달 가능한 Head address를 설정하고 node 랭크 0과 1을 사용하세요. 같은 SGLang 리비전과 의존성으로 생성된 명령을 호스트당 한 번 실행하세요. sglang serve가 선택한 가중치를 해석·다운로드하게 두세요.

GB200은 파생·미검증 레시피이지 측정된 GB300-동등 성능 주장이 아닙니다. 기준선은 네이티브 정밀도와 플랫폼-기본 어텐션을 유지하세요. B200/B300 양자화 측정과 H200 Cache-DiT 품질 감사는 Grace Blackwell 커버리지를 확립하지 않습니다.

GB300 end-to-end 커버리지는 현재 단일-호스트 FL2VA 텍스트-투-비디오(오디오 포함), 네이티브 정밀도, eager 실행, quality="lossless"를 포함합니다. Ref2VA와 다중-호스트 명령은 Unverified로 남습니다. 테스트된 워크로드는 GB300 측정 참조.

체크포인트와 어댑터 형식 (Checkpoint and adapter formats)

빌더가 생성한 명령으로 시작하세요. 아래 각 행은 같은 네이티브 SGLang 파이프라인 위의 오버레이입니다. 컴포넌트 저장소는 자체 config와 가중치를 기여하고, 가중치 파일은 기본 컴포넌트 config를 유지합니다. 저장소 레이아웃과 추론 동작은 별개의 계약입니다. 예를 들어 PEFT 파일은 일반 스타일 어댑터일 수도 timestep-증류 Turbo 어댑터일 수도 있습니다.

행들은 모든 교차곱을 나열하는 것이 아니라 구성(compose)합니다. 예를 들어 Turbo-merged INT8 ConvRot 체크포인트는 Turbo 샘플링 계약과 ConvRot 저장/백엔드 계약을 모두 충족해야 합니다.

H3의 Qwen3-VL 텍스트 인코더는 이미지 이해도 처리합니다. 별도 image_encoder 컴포넌트는 없습니다. 프롬프트 재작성용 선택적 generation-tail 파일이 아니라 컨디셔닝 체크포인트를 선택하세요. uncensored·Heretic 레이블은 가중치 수정을 설명하는 것이지 별도 로더나 출력 품질 보장이 아닙니다.

H3의 등록 컴포넌트 이름은 transformer, text_encoder, video_vae, audio_vae입니다. 짧은 --transformer-weights-path와 --text-encoder-path 별칭도 지원됩니다. conditioning_projection은 H3 텍스트-인코더 sidecar 키이지 독립 모델 컴포넌트가 아닙니다. 일반 video/audio VAE safetensors는 --component-weights-paths.video_vae 또는 --component-weights-paths.audio_vae를 쓸 수 있지만, SGLang은 현재 네이티브 양자화 H3 VAE 형식을 광고하지 않습니다.

사전 양자화 파일은 self-describing입니다. 그 행들을 --quantization 또는 --component-quantizations.*와 결합하지 마세요. byte-동일한 공식 full 가중치만(원본 모델, Diffusers 컴포넌트, 또는 weight-only 레이아웃에서 로드) 일관성 GT에 속합니다. Pruned·양자화·compact-encoder·LoRA 경로는 그 기준선과 감사된 quality="high" 계약 밖입니다. Packed·레이어별 혼합 형식은 행이 달리 말하지 않는 한 FSDP를 거부합니다. 백엔드 전역 제약은 Quantization 참조.

LoRA 텐서만으로는 실행-결합 릴리스를 이식 가능하게 만들지 못합니다. 스파스-어텐션/SLA 어댑터와 RAVEN 같은 causal-streaming 어댑터는 그에 맞는 어텐션·스트리밍 파이프라인도 필요합니다. SGLang의 표준 H3 LoRA 오버레이가 아닙니다. 마찬가지로 커스텀 샘플러를 요구하는 remix 체크포인트는 그 샘플러 계약을 재현할 수 있을 때만 커버됩니다. safetensors 레이아웃이 로드된다는 사실만으로는 부족합니다.

4-카드 H200 호스트에서 기본적으로 full BF16/FP32 모델을 상주로 유지하세요. 모델이 FSDP 없이도 맞으므로, 이 경로는 메모리 지향 FSDP 프로파일의 블록별 파라미터 all-gather를 피합니다:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --encoder-parallel auto \
  --performance-mode speed \
  --port 30010

순수 Ulysses4는 H200에서 용량 기본값일 뿐 아니라 측정된 더 빠른 토폴로지이기도 합니다. 아래 4×H100 TP2 + Ulysses2 레시피는 141 GB H200 카드에 맞지만, Ulysses all-to-all 교환을 블록당 두 번의 tensor-parallel all-reduce로 바꿔 GPU당 약 30 GB 낮은 최고 메모리에서 end-to-end로 더 느리게 측정됩니다. Benchmarks 섹션의 H200 토폴로지 비교를 참조하세요. H200에서 TP2 + Ulysses2는 의도적인 메모리 트레이드로 취급하세요, 지연 기본값이 아닙니다.

4×H100 80 GB의 경우 큰 packed 활성화와 상주 가중치 샤딩의 균형을 맞추세요. Qwen 인코더가 여전히 4개 GPU 전체에 접힐 때 TP2 + Ulysses2가 측정된 가장 빠른 무손실 토폴로지였습니다:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 4 \
  --tp-size 2 \
  --ulysses-degree 2 \
  --encoder-parallel auto \
  --performance-mode speed \
  --port 30010

순수 Ulysses4는 80 GB H100에서 전체 파이프라인을 상주로 유지하지 못했습니다. 더 낮은 상주 메모리가 마지막 몇 퍼센트 지연보다 중요할 때 --tp-size 4 --ulysses-degree 1을 사용하세요. FSDP는 여전히 검증된 용량 옵션입니다. 하지만 블록별 가중치 all-gather 때문에 H100 속도 기본값이 되지는 않습니다:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --encoder-parallel auto \
  --performance-mode speed \
  --use-fsdp-inference true \
  --port 30010

2-카드 RTX 5090 호스트에서는 TP2를 사용하고 20개의 DiT 블록을 상주로 유지하세요. Layerwise 배치는 무손실입니다. 파라미터 배치와 전송 스케줄링을 바꿀 뿐 BF16/FP32 디노이징이나 VAE 연산은 바꾸지 않습니다. 이는 측정된 가장 빠른 32 GB 동작 지점입니다:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 2 \
  --tp-size 2 \
  --ulysses-degree 1 \
  --encoder-parallel auto \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder,vae \
  --dit-offload-prefetch-size 1 \
  --dit-layerwise-resident-layers 20 \
  --enable-torch-compile false \
  --port 30010

DiT 상주·프리페치 노브는 반복 실행되는 DiT 블록에만 적용됩니다. 텍스트 인코더와 비디오 VAE 디코더 블록은 상주 레이어 0개·1-레이어 프리페치를 사용합니다. 비디오 VAE 인코더는 그 인덱스된 down 블록이 실행 가능한 layerwise 훅을 호스팅할 수 없으므로 상주합니다. 대략 577 MiB의 오디오 VAE도 오프로드가 전송 오버헤드만 더하므로 상주합니다. 이 정확한 레시피는 2× RTX 5090(각 32 GB)과 377 GiB 호스트에서 검증됐습니다. 384 GiB급 머신을 사용하세요. 지연·메모리 비교는 아래 벤치마크 섹션에 있습니다.

단일 24 GB 컨슈머 카드(RTX 4090)에서는 DiT와 텍스트 인코더를 스트리밍하고 DiT linear 레이어를 온라인에서 kitchen_int8으로 양자화하세요. vae를 --layerwise-offload-components에서 빼세요. VAE 디코더를 layerwise 오프로드에 넣으면 167개 디코드 타일 각각에서 약 9 GiB를 다시 스트리밍합니다. 기본 어텐션은 fa(exact)로 유지하세요. 근사 백엔드는 opt-in입니다. Attention Backends 참조. 먼저 pip install comfy-kitchen으로 comfy-kitchen을 설치하세요.

sglang generate \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --quantization kitchen_int8 \
  --attention-backend fa \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder \
  --dit-offload-prefetch-size 1 \
  --dit-layerwise-resident-layers 0 \
  --enable-torch-compile false \
  --prompt "A cat walking on a sunny beach, gentle waves." \
  --save-output

같은 플래그가 sglang serve에서도 동작합니다. BF16 기준선에서는 --quantization을 빼세요. 다른 건 동일합니다. 스트리밍 오프로드가 오프로드 버퍼와 VAE 디코드로 설정되므로 어떤 경우든 GPU 최고는 약 18 GB입니다.

첫 실행은 선택한 모든 소스를 일반 Hub 경로로 해석합니다. 저장소가 인증을 요구하면 서버 환경에 Hugging Face 토큰을 내보내세요. 수동 사전 다운로드는 필요 없습니다.

MiniMax-H3에서 --performance-mode speed는 의도적으로 DiT를 eager로 유지합니다. 현재 torch.compile 경로는 모델의 수치 출력을 바꾸므로 권장 무손실 프리셋은 암시적으로 활성화하지 않습니다. 명시적 --enable-torch-compile true는 제어된 실험에 여전히 제공되지만 일관성 ground truth 생성에는 사용하지 마세요.

Singularity 하이브리드 가중치

Singularity는 FL/Ref 퓨전 파인튠이지 완전한 파이프라인 저장소가 아닙니다. 인코더와 VAE에는 공식 모델 ID를 유지하고 정확한 transformer 파일 하나를 선택하세요:

pip install comfy-kitchen

WEIGHTS=WarmBloodAban/Minimax-h3_Singularity/Minimax-h3_Singularity_ref2va_Pruned_v1.3_int8.safetensors
sglang serve --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant hybrid \
  --component-weights-paths.transformer "$WEIGHTS" \
  --num-gpus 2 --ulysses-degree 2 --performance-mode speed \
  --port 30000

Full INT8 체크포인트는 파일명을 Minimax-h3_Singularity_ref2va_v1.3_int8.safetensors로 바꾸세요. SGLang이 선택한 파일을 자동 다운로드합니다. 온라인 양자화 오버라이드를 추가하지 마세요. hybrid는 명시적 가중치 오버라이드를 요구합니다. 공식 Ref2VA 가중치를 멀티모드 모델로 바꾸지 않습니다. 요청 task와 conditions는 t2va에 conditions: [], fl2va에 키프레임 등 일반 의미를 유지합니다.

quality: "lossless"와 표준 50-포인트 일정으로 시작하세요. 여기서 lossless는 추가 요청-시간 근사를 비활성화합니다. INT8 양자화·프루닝·파인튜닝을 되돌리지는 않습니다. 저자의 권장 Ref2V Turbo LoRA는 별도의 선택적 어댑터이지 자동 추론된 4-스텝 일정이 아닙니다. 레퍼런스 충실도는 공식 모델과 다를 수 있습니다. LoRA 샘플링 계약을 적용하기 전에 저자 안내를 참조하세요.

고급: 사전 계산 AdaLN 캐시 (Advanced: precomputed AdaLN cache)

모델 카드는 약 13B H3 파라미터가 AdaLN 분기이며 그 출력을 추론용으로 사전 계산할 수 있다고 적었습니다. 공개 기본 체크포인트는 사용 가능한 캐시가 아니라 원본 분기를 포함합니다. 따라서 SGLang은 표준 경로를 기본으로 유지합니다.

고정 샘플링 일정을 가진 inference-only 배포에서 CUDA의 이미 실현된 transformer 디렉터리에서 캐시를 빌드한 뒤 일반 sglang serve 명령에 넘기세요. 이는 디노이징 공식을 바꾸지 않습니다. 캐시는 원본 AdaLN linears의 BF16 출력을 저장합니다.

python -m sglang.multimodal_gen.tools.build_minimax_h3_adaln_cache \
  --transformer-path "$TRANSFORMER_PATH" \
  --model-variant fl2va \
  --mode t2va \
  --num-inference-steps 50 \
  --flow-shift 12 \
  --audio-flow-shift 3 \
  --output /models/minimax-h3-fl2va-adaln-50step.safetensors

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --minimax-h3-adaln-cache-path /models/minimax-h3-fl2va-adaln-50step.safetensors \
  --num-gpus 4 \
  --tp-size 2 \
  --ulysses-degree 2 \
  --port 30010

$TRANSFORMER_PATH는 일반 SGLang/Hugging Face 스냅샷의 FL2VA/transformer 또는 Ref2VA/transformer 디렉터리입니다. 빌더는 두 번째 복사본을 다운로드하지 않습니다. 캐시는 생성에 사용된 스케줄러 설정만 커버합니다(mode, 스텝 수, flow shift, 컨디션 노이즈 값 포함). SGLang은 컨디셔닝을 조용히 바꾸는 대신 커버리지 밖 요청을 거부합니다. 캐시 모드는 일치하는 비양자화 체크포인트만 지원합니다.

고급: 호스트 캐시를 이용한 온라인 AdaLN 재구축

--minimax-h3-adaln-online true는 사전 빌드 아티팩트가 필요 없습니다. 서버가 24.2 GiB의 adaln_proj 가중치를 GPU에서 떨어뜨리고 각 요청의 AdaLN 출력을 체크포인트에서 on-demand로, 상주-가중치 경로와 bit-exact하게 계산합니다. 재구축 패스가 전체 24.2 GiB를 스트리밍하므로, 매 새 (task shape, num_inference_steps, flow_shift, audio_flow_shift) 조합의 첫 요청은 몇 초를 지불합니다. 이후 plan들은 pinned 호스트 캐시(--minimax-h3-adaln-host-cache-gb, 일정별 LRU, 랭크당 기본 8 GB)가 뒷받침하는 64-슬롯 GPU 슬래브(LRU per plan)에서 서빙되어 혼합-일정 서빙이 체크포인트를 다시 읽지 않습니다. 호스트 예산을 초과하는 plan 집합은 다음 발생 시 재계산됩니다. 전문가 탈출구는 환경 변수에 있습니다. SGLANG_DIFFUSION_MINIMAX_H3_ADALN_GPU_PLANS는 GPU 슬래브 크기를 조정하고(65 추론 스텝을 초과할 때만 필요) SGLANG_DIFFUSION_MINIMAX_H3_ADALN_FP32는 일회성 투영을 fp32로 계산합니다(실험적, 상주 가중치와 bit-비교 불가, production 전 end-to-end 검증). adaln_proj를 수정하는 LoRA 어댑터는 조용히 무시하는 대신 두 캐시 모드 모두에서 거부됩니다.

두 캐시 모드 모두 adaln_proj에서 파생된 값을 보유하므로 런타임 가중치 업데이트는 캐시가 따라갈 수 있을 때만 수용됩니다. 온라인 모드는 네이티브 adaln_proj safetensors를 나르는 대상 디렉터리의 디스크 업데이트를 받고 다른 것은 모두 거부합니다. sidecar는 오프라인으로 빌드되어 서버에서 재생성할 수 없으므로 가중치 업데이트는 아예 거부됩니다. 새 가중치로 sidecar를 재구축하고 재시작하세요.

Ascend NPU에서 MiniMax-H3 서빙

Ascend NPU의 경우 서버 시작 전에 NPU 설치 가이드를 따르세요.

아래 Ascend 명령은 보고된 성능 측정에 사용된 Cache-DiT 구성을 명시적으로 활성화합니다. 무손실 디노이징을 쓰려면 이 SGLANG_CACHE_DIT_* 변수를 제거하세요. 측정된 8-NPU·4-NPU 지연은 Benchmarks 섹션의 Ascend NPU 토폴로지 비교 참조.

측정된 지연 구성은 transformer를 NPU에 상주시키기 위해 --dit-cpu-offload false도 전달합니다. 디바이스 메모리 사용을 낮추는 게 CPU-to-NPU 전송 지연을 피하는 것보다 중요할 때는 이 플래그를 생략하세요.

8-NPU 호스트의 검증된 토폴로지는 Laser Attention을 쓴 TP2 + SP4입니다. laser_attn을 fa로 바꿔 Ascend Flash Attention을 사용할 수 있습니다.

SGLANG_CACHE_DIT_ENABLED=true \
SGLANG_CACHE_DIT_FN=2 \
SGLANG_CACHE_DIT_BN=1 \
SGLANG_CACHE_DIT_WARMUP=4 \
SGLANG_CACHE_DIT_RDT=0.4 \
SGLANG_CACHE_DIT_MC=4 \
SGLANG_CACHE_DIT_TAYLORSEER=true \
SGLANG_CACHE_DIT_TS_ORDER=2 \
HCCL_BUFFSIZE=256 sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-type diffusion \
  --model-variant fl2va \
  --dit-cpu-offload false \
  --num-gpus 8 \
  --tp-size 2 \
  --sp-degree 4 \
  --attention-backend laser_attn \
  --port 30088 \
  --component-residency text_encoder=layerwise-offload

4-NPU 호스트는 TP2 + SP2를 사용하세요:

SGLANG_CACHE_DIT_ENABLED=true \
SGLANG_CACHE_DIT_FN=2 \
SGLANG_CACHE_DIT_BN=1 \
SGLANG_CACHE_DIT_WARMUP=4 \
SGLANG_CACHE_DIT_RDT=0.4 \
SGLANG_CACHE_DIT_MC=4 \
SGLANG_CACHE_DIT_TAYLORSEER=true \
SGLANG_CACHE_DIT_TS_ORDER=2 \
HCCL_BUFFSIZE=256 sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-type diffusion \
  --model-variant fl2va \
  --dit-cpu-offload false \
  --num-gpus 4 \
  --tp-size 2 \
  --sp-degree 2 \
  --attention-backend laser_attn \
  --port 30088 \
  --component-residency text_encoder=layerwise-offload

4. 비디오와 오디오 생성 (Generate video and audio)

MiniMax-H3는 비동기 OpenAI 호환 비디오 엔드포인트를 사용합니다. 아래에서 생성 모드를 선택하고 작업을 제출한 뒤 상태를 폴링하고 완성된 MP4를 다운로드하세요.

```bash Command theme={null}
video_id=$(
  curl -sS -X POST http://127.0.0.1:30010/v1/videos \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMaxAI/MiniMax-H3",
      "prompt": "At night, while their owner sleeps in a bedroom, three cats march in loudly playing tiny brass instruments, then abruptly file out.",
      "seconds": 5,
      "task": "t2va",
      "conditions": [],
      "target": {
        "short_edge": 768,
        "aspect_ratio": "16:9",
        "duration_seconds": 5.0
      },
      "num_outputs_per_prompt": 1,
      "num_inference_steps": 50,
      "flow_shift": 12.0,
      "audio_flow_shift": 3.0,
      "seed": 1101
    }' |
    jq -r '.id'
)

while true; do
  status=$(curl -sS "http://127.0.0.1:30010/v1/videos/${video_id}" | jq -r '.status')
  [ "$status" = "completed" ] && break
  [ "$status" = "failed" ] && exit 1
  sleep 1
done

curl -sS -L "http://127.0.0.1:30010/v1/videos/${video_id}/content" \
  -o minimax-h3-t2va.mp4
```

출력 계약은 24 fps의 H.264 비디오와 32 kHz의 AAC 스테레오 오디오 스트림 하나를 담은 MP4입니다.

아래 요청은 서버-로컬 첫 프레임 하나를 사용합니다. 마지막 프레임은 `frame_index: -1`, 둘 다 컨디셔닝하려면 두 항목을 포함하세요.

제공된 이미지가 생성된 클립의 실제 첫/마지막 프레임이어야 할 때 FL2VA를 선택하세요. 이미지가 엔드포인트로 보존되지 않고 정체성·스타일·구도를 안내해야 할 때는 이미지 기반 Ref2VA를 대신 사용하세요. Ref2VA는 레퍼런스를 재구성하거나 크롭할 수 있습니다.

```bash Command theme={null}
curl -sS -X POST http://127.0.0.1:30010/v1/videos \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-H3",
    "prompt": "The supplied frame continues with calm, natural motion and synchronized ambient sound.",
    "seconds": 5,
    "task": "fl2va",
    "conditions": [
      {
        "type": "image",
        "uri": "file:///data/minimax-h3/first-frame.png",
        "role": "keyframe",
        "frame_index": 0
      }
    ],
    "target": {
      "short_edge": 768,
      "aspect_ratio": "auto",
      "duration_seconds": 5.0
    },
    "num_outputs_per_prompt": 1,
    "num_inference_steps": 50,
    "flow_shift": 12.0,
    "audio_flow_shift": 3.0,
    "seed": 2101
  }'
```

입력이 무성일 수 있으면 `type: "video"`를 사용하세요. 파일에 사운드트랙이 있으면 H3는 그것을 오디오 레퍼런스로도 사용합니다. 두 스트림이 모두 필요할 때만 `type: "video_audio"`를 사용하세요. 이 형태는 오디오 없는 입력을 거부합니다. 비주얼 스트림의 프롬프트 태그는 `<Video 1>`이고, 사용 가능한 사운드트랙은 `<Audio 1>`로 노출됩니다.

<Note>
  Ref2VA는 입력 비디오를 픽셀-정렬 편집 소스가 아니라 레퍼런스 자료로 취급합니다. 모션과 컷을 재합성하거나 재정렬할 수 있으며 디노이징-강도 제어를 노출하지 않습니다. 모든 소스 프레임이나 정확한 타이밍을 보존한다고 기대하지 마세요.
</Note>

더 긴 소스에서 세그먼트를 선택하려면 `conditions[].start_time_seconds`를 설정하세요. 기본은 `0`입니다. SGLang은 비주얼 스트림과 사운드트랙을 같은 오프셋으로 시크한 뒤 한 패스에서 요청된 대상 지속 시간을 최대로 디코드합니다. 소스는 중간 클립으로 재인코딩되지 않습니다.

```bash Command theme={null}
curl -sS -X POST http://127.0.0.1:30010/v1/videos \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-H3",
    "prompt": "Follow the motion and appearance of <Video 1>, changing the setting to a moonlit bedroom while preserving coherent timing.",
    "seconds": 5,
    "task": "ref2va",
    "conditions": [
      {
        "type": "video",
        "uri": "file:///data/minimax-h3/input.mp4",
        "role": "reference",
        "start_time_seconds": 35.0
      }
    ],
    "target": {
      "short_edge": 768,
      "aspect_ratio": "16:9",
      "duration_seconds": 5.0
    },
    "num_outputs_per_prompt": 1,
    "num_inference_steps": 50,
    "flow_shift": 12.0,
    "audio_flow_shift": 3.0,
    "seed": 4101
  }'
```

H3 V2V에는 `conditions[].uri`를 사용하세요. 일반 최상위 `video_path`, `video_url`, `video_reference` 업로드 필드는 H3 레퍼런스 컨디션으로 낮춰지지 않습니다.

여기서 이미지 컨디션은 픽셀-정렬 첫 프레임보다 시맨틱 레퍼런스 자료입니다. 정확한 시작 구도에서 스크린샷을 애니메이션할 때는 FL2VA 탭을 사용하세요.

```bash Command theme={null}
curl -sS -X POST http://127.0.0.1:30010/v1/videos \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-H3",
    "prompt": "Use <Picture 1> as the visual subject and <Audio 1> as the sound reference, with coherent natural motion.",
    "seconds": 5,
    "task": "ref2va",
    "conditions": [
      {
        "type": "image",
        "uri": "file:///data/minimax-h3/reference.png",
        "role": "reference"
      },
      {
        "type": "audio",
        "uri": "file:///data/minimax-h3/reference.mp3",
        "role": "reference"
      }
    ],
    "target": {
      "short_edge": 768,
      "aspect_ratio": "auto",
      "duration_seconds": 5.0
    },
    "num_outputs_per_prompt": 1,
    "num_inference_steps": 50,
    "flow_shift": 12.0,
    "audio_flow_shift": 3.0,
    "seed": 3101
  }'
```

T2VA 예제에서 사용한 것과 같은 작업-상태·콘텐츠 엔드포인트로 모든 컨디셔닝 요청을 폴링·다운로드하세요. 서버-로컬 file:// URI는 SGLang 서버 환경 안에서 보이는 파일을 가리켜야 합니다.

5. LoRA 레시피 (LoRA recipes)

H3는 네이티브 fused 어댑터와 표준 Diffusers/PEFT 어댑터를 모두 받습니다. 네이티브 어댑터는 blocks.*.attn.qkv_proj 같은 모듈을 대상으로 하고, PEFT 어댑터는 별도 to_q·to_k·to_v 투영과 default 어댑터 네임스페이스를 제공할 수 있습니다. SGLang이 두 레이아웃을 정규화합니다.

다음 고정된 FL2VA 어댑터는 뚜렷한 목적을 가집니다:

H3 요청 필드는 종단 zero를 포함한 sigma 그리드 점 수를 제어하므로 디노이징 루프는 모델 평가를 하나 적게 실행합니다. 이것이 8-스텝으로 설명되는 어댑터가 요청에서 9를, 4-스텝 어댑터가 5를 쓰는 이유입니다.

세 가지 모두 같은 실행 형태를 사용합니다. 여러 리비전을 발행하는 저장소에서는 파일명 고정이 필수이고, 재현 가능한 단일-파일 레시피에도 권장됩니다:

LORA_REPO=larryvrh/MiniMax-H3-Turbo-Lora
LORA_FILE=minimax_h3_turbo_v4_step600_ema.safetensors
LORA_NAME=h3-turbo-v4
LORA_SCALE=1.0
LORA_ALPHA_ARGS=()
# LightX2V only: LORA_ALPHA_ARGS=(--lora-alpha 8)

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --lora-path "$LORA_REPO" \
  --lora-weight-name "$LORA_FILE" \
  --lora-nickname "$LORA_NAME" \
  --lora-scale "$LORA_SCALE" \
  "${LORA_ALPHA_ARGS[@]}" \
  --lora-merge-mode auto \
  --port 30010

auto는 어댑터를 일반 상주 가중치에 병합해 스텝별 LoRA matmul을 피하지만, 전체 gather가 최고 메모리를 늘릴 수 있는 FSDP-샤드 가중치에는 동적 경로를 유지합니다. 상주 서버 하나가 기본과 LoRA 출력 사이를 반복 전환해야 할 때는 dynamic을 사용하세요.

표의 파일명·scale·요청 일정을 함께 사용하세요. 4-평가 LightX2V 레시피가 더 공격적인 지연/품질 트레이드오프입니다. 그 체크포인트는 rank 128이지만 파일과 저장소 메타데이터 양쪽에서 훈련 alpha를 생략하므로 저자의 레퍼런스 구현을 재현하려면 --lora-alpha 8이 필요합니다. 섬세한 시각 디테일 보존이 최소 지연보다 중요할 때는 Larry 8-평가 레시피로 시작하세요.

위 고정 파일은 FL2VA 파티션용으로 훈련됐으며 t2va 또는 fl2va 요청에 적용됩니다. LightX2V를 포함한 일부 저장소는 Ref2VA/Ref2V용 별도 파일을 발행합니다. ref2va 서버에는 FL2VA 파일을 재사용하는 대신 하나를 명시적으로 선택하세요. 그 Ref2VA 파일은 아직 이 페이지의 고정·검증 레시피가 아닙니다. 또한 증류 어댑터를 quality: "high"와 쌓지 마세요. 둘 다 디노이징을 바꾸며 그 조합은 품질 검증되지 않았습니다.

adaln_basis와 adaln_mean을 발행하는 AdaLN-pruned Diffusers 컴포넌트는 공개 full-width AdaLN 모듈에 대해 훈련된 LoRA도 소비할 수 있습니다. SGLang은 로드 시 그 어댑터 factor를 pruned 좌표에 투영합니다. 그 메타데이터가 없는 구조 수정 체크포인트는 여전히 fail-closed이고, packed GGUF 가중치는 LoRA와 호환되지 않습니다.

PDD 가속 LoRA (PDD acceleration LoRAs)

Alibaba PAI의 MiniMax-H3-Acc-LoRAs는 8개의 denoiser 평가를 위해 Parallel Decoding Distillation(PDD)을 사용합니다. 이 체크포인트에는 backbone LoRA 가중치와 interval별 출력 헤드가 들어 있습니다. backbone 가중치를 오프라인으로 병합한 뒤 서빙 전에 출력 헤드를 퓨즈하세요. 위 --lora-path 레시피는 이 준비 단계를 수행하지 않습니다.

어댑터와 원본 MiniMax-H3 transformer 가중치를 서버의 모델 variant에 맞추세요:

BASE_TRANSFORMER_DIR는 원본 모델의 BF16/FP32 transformer 가중치 파일을 담은 디렉터리이지 모델 루트나 LoRA 디렉터리가 아닙니다. MiniMaxAI/MiniMax-H3를 /path/to/MiniMax-H3에 다운로드했다면 T2VA/FL2VA에는 /path/to/MiniMax-H3/FL2VA/transformer, Ref2VA에는 /path/to/MiniMax-H3/Ref2VA/transformer를 사용하세요. 이 디렉터리는 model-*.safetensors, model.safetensors.index.json, config.json을 포함합니다. 빌더는 이 파일들을 읽고 원본 가중치를 그대로 두고 merged 가중치를 $PDD_DIR/transformer에 씁니다.

다음 예제는 FL2VA 가중치를 준비하고 TP2 + Ulysses4의 8개 NVIDIA CUDA GPU에서 서빙합니다:

BASE_TRANSFORMER_DIR=/path/to/MiniMax-H3/FL2VA/transformer
LORA_DIR=/path/to/h3-acc-loras
PDD_DIR=/path/to/h3-fl2va-pdd

hf download alibaba-pai/MiniMax-H3-Acc-LoRAs \
  MiniMax-H3-FL2VA-Acc-8Step.safetensors --local-dir "$LORA_DIR"

python3 -m sglang.multimodal_gen.tools.build_minimax_h3_pdd_weights \
  "$BASE_TRANSFORMER_DIR" \
  "$LORA_DIR/MiniMax-H3-FL2VA-Acc-8Step.safetensors" \
  "$PDD_DIR"

python3 -m sglang.multimodal_gen.tools.fuse_minimax_h3_pdd_heads \
  "$PDD_DIR" --video-shift 12.0 --audio-shift 3.0

SGLANG_DIFFUSION_MINIMAX_H3_PDD_HEADS="$PDD_DIR/pdd_fused_heads.safetensors" \
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --transformer-weights-path "$PDD_DIR/transformer" \
  --num-gpus 8 \
  --tp-size 2 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --port 30010

pdd_config.json을 transformer/ 디렉터리 밖, pdd_fused_heads.safetensors 옆에 두세요. Ref2VA에는 그 어댑터·기본 transformer, 별도 출력 디렉터리, --model-variant ref2va를 사용하세요.

비디오·오디오 생성의 요청을 num_inference_steps: 9, flow_shift: 12.0, audio_flow_shift: 3.0과 함께 사용하세요. 아홉 sigma 그리드 점은 여덟 번의 denoiser 평가를 줍니다. 이 설정은 fused heads와 일치해야 하며 서버는 다른 스텝 수나 shift를 거부합니다. 요청에는 quality: "lossless"를 사용하세요.

6. FastH3: 4-스텝 증류 프리뷰

FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree는 Video Sparse Attention(VSA)을 0.9 희소성·64-토큰 타일로 사용해 data-free로 훈련된 MiniMax-H3의 4-스텝 DMD2 증류입니다. T2VA 성능만 증류됐습니다. 요청은 task: "t2va"를 써야 하며 fl2va/ref2va 요청은 거부됩니다. 체크포인트는 MiniMax-H3 Community License를 상속합니다.

저장소를 --model-path로 직접 전달하세요. 평면 native-Diffusers 업로드는 등록된 모델 오버레이로 기본-H3 레이아웃에 실현됩니다. 유일한 비-심링크 단계는 첫 실행 시 약 10 GB 비디오 VAE의 일회성 재직렬화입니다.

sglang serve \
  --model-path FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree \
  --num-gpus 4 \
  --attention-backend video_sparse_attn_h3 \
  --attention-backend-config '{"VSA_sparsity": 0.9}' \
  --port 30010

요청은 기본 모델과 같은 비동기 비디오 엔드포인트를 사용하며 task: "t2va", conditions: [], 그리고 {"short_edge": 768, "aspect_ratio": "16:9", "duration_seconds": 5.0} 같은 target을 씁니다. 요청 기본은 num_inference_steps: 5입니다. 표준 shift-12/shift-3 sigma 그리드의 5개 점, 즉 4번의 증류 DiT 평가입니다. 다른 스텝 수는 거부됩니다.

video_sparse_attn_h3(VSA-H3)는 훈련된 희소 정책입니다. 체크포인트의 훈련된 to_gate_compress 압축 분기로 구동되는, 세그먼트-순수 prefix 타일과 (4, 4, 4) 비디오 타일 위의 in-tree Triton block-sparse 커널(SM90/SM100/SM103)입니다. DiT만 희소로 돕니다. 토큰 리파이너·텍스트 인코더·VAE는 밀집 기본을 유지합니다. Ulysses 시퀀스 병렬성이 지원됩니다. VSA_sparsity, vsa_mode, vsa_dense_first_n_steps, vsa_dense_layers는 Attention Backends 참조. 기본 H3에서 도는 모든 밀집 백엔드(fa, torch_sdpa, ...)는 VSA 플래그 없이도 FastH3 가중치에서 돌며, sglang generate는 sglang serve와 같은 플래그를 받습니다.

4× B300 레시피의 측정 지연은 FastH3 on B300에 있습니다.

FastH3는 증류 프리뷰에 적용되지 않는 배포 옵션을 조용히 무시하는 대신 거부합니다. --model-variant, quality: "high", fl2va/ref2va 요청, 그리고 VSA-H3에서는 1보다 큰 --ring-degree, torch.compile, breakable CUDA graph 실행이 거부됩니다.

7. VDN-H3: 하이브리드 어텐션, 8-스텝 증류

Video DeltaNet(VDN)은 near-lossless 품질을 유지하면서 linear attention 속도에 접근하는 하이브리드 어텐션 아키텍처입니다. 비디오-비디오 어텐션을 두 보완 분기로 나눕니다. 로컬 프레임 쌍용 sliding-window softmax 분기(연속 5개 잠재 프레임이 청크를 이루고 각 청크는 자신·이전·다음 청크에 어텐션하며 첫/마지막 프레임·텍스트·오디오는 밀집 유지)와 장기 컨텍스트용 양방향 linear 분기인 Video Delta Attention입니다. OpenVDN/vdn-minimax-h3는 이것을 MiniMax-H3에 적용합니다. 공개 stage-dmd-step-250 체크포인트는 변경되지 않은 H3 백본에 4.3 GB linear 분기와 OpenVDN 자체 8-스텝 DMD2 LoRA를 추가합니다. FL2VA 파티션이므로 t2va와 fl2va(첫·마지막·양쪽 키프레임)를 서빙합니다. ref2va는 거부됩니다. 가중치는 MiniMax-H3 Community License를 상속합니다.

저장소를 --model-path로 직접 전달하세요. 첫 실행 시 등록된 오버레이가 transformer 가중치에 두 어댑터를 사전 퓨즈(62 GB 쓰기)하고 linear 분기를 부착합니다. Qwen3-VL 컨디셔너와 VAE는 MiniMaxAI/MiniMax-H3에서 하드-링크됩니다. SGLANG_DIFFUSION_CACHE_ROOT를 Hugging Face 캐시와 같은 파일시스템에 최소 90 GB 여유로 두세요.

sglang serve \
  --model-path OpenVDN/vdn-minimax-h3 \
  --num-gpus 8 \
  --attention-backend hybrid_window_attn_h3 \
  --performance-mode speed \
  --warmup-num-frames 345 \
  --warmup-resolutions 1344x768 \
  --port 30010

--num-gpus 4, 2, 1은 벤치마크 표의 더 작은 Ulysses 레시피를 줍니다. sglang generate는 같은 플래그를 받습니다. --warmup-num-frames/--warmup-resolutions는 서빙할 클립 길이·캔버스에서 워밍업합니다. 없으면 첫 긴 요청이 2~3초의 allocator 성장과 커널 설정을 지불합니다.

요청은 기본 모델과 같은 비디오 엔드포인트를 사용합니다. task: "t2va"와 conditions: [], 또는 키프레임 컨디션으로 task: "fl2va", 그리고 {"short_edge": 768, "aspect_ratio": "16:9", "duration_seconds": 14.375}(345-프레임 논문 워크로드) 같은 target입니다. 기본 num_inference_steps: 9가 유일한 수용 값입니다. 아홉 sigma 그리드 점, 여덟 DiT forward. 각 키프레임은 약 2,000 밀집 행을 더하므로 fl2va forward는 t2va보다 조금 비쌉니다.

hybrid_window_attn_h3가 필요합니다. 밀집 백엔드는 linear 분기와 게이트를 조용히 건너뛰어 잘못된 모델을 만들 것입니다. Blackwell(SM100/SM103/SM120)에서 transformer는 기본적으로 온라인 MXFP8입니다. --quantization bf16은 그만둡니다. SM100 전에는 --quantization fp8이 기본 H3의 채널별 fp8 경로이고, SM80은 bf16 DiT(62 GB, --layerwise-offload-components 예산)를 돌립니다. Ampere와 Ada는 활성화되지만 벤치마크되지 않았습니다. Ulysses 시퀀스 병렬성은 지원됩니다. --model-variant, quality: "high", 1보다 큰 --ring-degree, torch.compile, breakable CUDA graph 실행은 거부됩니다. 백엔드의 --attention-backend-config 키는 Attention Backends에 있습니다.

1/2/4/8 B200의 측정 지연은 VDN-H3 on B200, RTX PRO 6000의 단일-카드·PCIe 다중-카드 수치는 VDN-H3 on RTX PRO 6000에 있습니다.

8. 샘플링과 출력 제어 (Sampling and output controls)

MiniMax-H3는 프롬프트당 둘 이상의 출력을 지원합니다. 비디오 API는 num_outputs_per_prompt(또는 OpenAI 호환 n)를 1~10까지 받습니다. 오프라인 생성은 --num-outputs-per-prompt N을 받고 --num-outputs N은 짧은 별칭입니다. 스칼라 시드는 seed + output_index로 결정적으로 확장돼 출력이 같은 노이즈를 재사용하지 않습니다.

같은-프롬프트 팬아웃은 텍스트 컨디셔닝을 재사용합니다. 검증된 2× RTX 5090 레시피에서 5-스텝 2-출력 요청은 1-출력 78.11초 대비 155.39초에 완료했고, 두 개의 뚜렷한 유효 MP4 파일을 만들었습니다. 독립 denoise·decode 패스는 이 32 GB 프로파일에서 최고 메모리를 묶기 위해 순차로 남습니다. 그룹 경로는 오케스트레이션 오버헤드를 본질적으로 더하지 않습니다. 서버당 메모리 효율보다 많은 variant의 낮은 wall-clock 지연이 중요할 때 서버 복제(replica)를 사용하세요.

예를 들어 아무 요청에 "num_outputs_per_prompt": 2를 설정하세요. 작업 완료 후 각 0-기반 variant를 선택해 두 출력을 다운로드합니다:

video_id="<completed-job-id>"
for variant in 0 1; do
  curl -sS -L \
    "http://127.0.0.1:30010/v1/videos/${video_id}/content?variant=${variant}" \
    -o "minimax-h3-${variant}.mp4"
done

품질 수준 선택 (Choose the quality level)

quality는 세 수준을 가진 누적 요청-범위 최적화 파라미터입니다:

• "lossless" (기본): 정확한 레퍼런스 경로. 출력이 레퍼런스 구현 및 CI ground truth와 bit-exact합니다.
• "extra-high": 전역 fusion-only 계층을 포함하지만 Cache-DiT나 다른 근사 최적화를 활성화하지 않습니다. MiniMax-H3는 현재 요청-게이트 fusion 사이트가 없으므로 denoise 경로가 lossless와 같습니다.
• "high": 감사된 가속 경로. 품질이 보장됩니다(감사된 Cache-DiT 구성이 lossless 대비 SSIM 0.931/PSNR 28.16 dB 측정)만 출력이 레퍼런스와 bit-동일하지 않습니다.

상주 서버 하나가 세 수준을 모두 서빙합니다. quality: "high" 요청은 배치 경계에서 감사된 Cache-DiT 정책을 마운트하고, 이후 quality: "lossless" 또는 "extra-high" 요청은 디노이징 전에 훅을 제거합니다.

검증된 서버를 한 번 시작하세요:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 4 \
  --tp-size 1 \
  --sp-degree 4 \
  --ulysses-degree 4 \
  --ring-degree 1 \
  --encoder-parallel auto \
  --performance-mode speed \
  --use-fsdp-inference false \
  --enable-torch-compile false \
  --port 30010

그리고 요청 수준을 선택하세요:

```json Request field theme={null}
{
  "quality": "lossless"
}
```

```json Request field theme={null}
{
  "quality": "extra-high"
}
```

```json Request field theme={null}
{
  "quality": "high"
}
```

측정된 트레이드오프:

이 수치는 4×H200에서 1344×768, 124-프레임, 24 fps T2VA, 50 추론 스텝, 비디오 flow shift 12, 오디오 flow shift 3, 세 고정 프롬프트/시드 쌍을 사용합니다. 프롬프트는 조용한 디테일 씬, 빠른 다중-주체 액션, 움직이는 클로즈업 초상화를 다룹니다. inference_time_s는 세 프롬프트에 걸쳐 평균됩니다.

SSIM·PSNR은 같은 프롬프트·시드에 대해 lossless 결과와 디코드·프레임-정렬된 출력을 비교합니다. 궤적 편차를 측정하지 절대 지각 품질은 측정하지 않습니다. high 경로는 다르지만 여전히 그럴듯한 실현을 만들 수 있습니다. 또한 결합 오디오-비디오 denoise 궤적도 바꾸는데 이 두 메트릭은 비디오만 다룹니다.

quality: "high"는 현재 위 정확한 워크로드와 4×H200 배포만 받습니다. 다른 하드웨어·task 모드·요청 형태·스텝 수·flow shift는 디노이징 전에 실패합니다. 오프라인 생성도 같은 수준 이름을 사용합니다. 예: sglang generate --quality high.

검증 경로 밖의 수동 Cache-DiT 실험에는 요청 quality 필드를 생략하고 --enable-cache-dit 또는 프로세스-전역 SGLANG_CACHE_DIT_* 기본값을 설정하세요. "lossless"와 "extra-high"를 포함한 명시적 quality는 H3를 일반 Cache-DiT 경로에서 벗어나게 합니다. 위 24 GB layerwise 레시피는 같은 스위치를 쓸 수 있습니다. 건너뛴 블록은 스트리밍되지 않습니다.

SGLANG_CACHE_DIT_ENABLED=true \
SGLANG_CACHE_DIT_FN=1 \
SGLANG_CACHE_DIT_BN=0 \
SGLANG_CACHE_DIT_WARMUP=4 \
SGLANG_CACHE_DIT_RDT=0.12 \
SGLANG_CACHE_DIT_MC=2 \
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant ref2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --encoder-parallel auto \
  --performance-mode speed \
  --port 30010

9. 기능 계약과 고급 레시피 (Feature contracts and advanced recipes)

생성된 명령에는 이미 권장 토폴로지와 인코더 설정이 들어 있습니다. 아래 상세 레퍼런스는 선택적 오버라이드를 적용하거나 그 설치·토폴로지 한계·검증 증거를 확인할 때만 사용하세요.

| 기능 | 검증 상태 | 비고 |
|---|---|---|
| Ulysses 시퀀스 병렬성 | Verified: 8× B200, 4× H200, 4× H100, MI300X/MI355X에서 Ulysses1/2/4/8 | `--ulysses-degree` 사용. Ring과 결합해 크로스-노드 확장. |
| Ring 시퀀스 병렬성 (크로스-노드) | Verified: 2 nodes of 8× H200 (Ulysses8 × Ring2) | `--ring-degree`를 `--nnodes`/`--node-rank`/`--dist-init-addr`와 함께 사용. Ring은 시퀀스를 노드 간 샤딩하고 Ulysses는 노드 내 헤드를 샤딩. H3의 packed multi-segment 어텐션은 노드 경계를 가로지르는 Ring만 지원. `--encoder-parallel replicate` 필요. |
| 텐서 병렬성 | Verified: B200 TP2 + Ulysses4; H100 TP2 + Ulysses2 및 TP4 + Ulysses1 | TP-로컬 헤드 수가 Ulysses 정도로 나누어질 때 `--tp-size`를 Ulysses와 결합. 4×H100에서 TP2 + Ulysses2가 측정된 속도 기본값. |
| FSDP 추론 | Verified: 4× B200 및 4× H100 + Ulysses4 | H3의 혼합 BF16/FP32 파라미터 정책 보존. |
| 상주 컴포넌트 | Verified: B200, H200, 4×H100 with TP, 1/2/4/8× MI300X·MI355X | 완전 워크로드가 맞을 때 권장 단일-요청 지연 경로. |
| CPU·layerwise 오프로드 | Verified: 2× RTX 5090 TP2; 1× RTX 4090 24 GB | Cache-DiT와 호환. 건너뛴 블록은 스트리밍되지 않음. |
| Breakable CUDA graph | Verified: B200 Ref2VA, opt-in | 캡처된 시그니처에 대해 eager 출력 일치가 관찰됨. 다른 형태·레퍼런스 집합은 재캡처. |
| `torch.compile` | Measured: H200, opt-in | Steady-state 이득이 측정 노이즈 아래였고 시작 증가·수치 출력 변화. 일관성 ground truth에 사용하지 마세요. |

검증된 병렬·배치·일치-시그니처 BCG 경로는 BF16/FP32 가중치와 디노이징 연산을 유지합니다. `torch.compile`이 위에 명시된 예외입니다. CI 일관성 ground truth 생성에는 항상 eager BF16/FP32 실행을 사용하세요.

검증된 1344×768 Ref2VA 프로파일에는 서버 워밍업과 레퍼런스-컨디셔닝 요청이 모두 캡처된 시그니처를 공유하도록 5504-행 텍스트 버킷을 사용하세요:

```bash Command theme={null}
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant ref2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --encoder-parallel auto \
  --performance-mode speed \
  --enable-breakable-cuda-graph true \
  --warmup-resolutions 1344x768 \
  --bcg-text-buckets 5504 \
  --port 30010
```

BCG는 일치하는 캡처 시그니처에 무손실이지만 캡처는 추가 GPU 메모리를 예약합니다. 다른 작업 프로파일·레퍼런스 집합·해상도·프롬프트 템플릿에 이 버킷을 재사용하기 전에 실시간 H3 텍스트 길이를 재측정하세요.

SageAttention은 양자화된 어텐션 연산을 사용하며 일관성 모드가 아닙니다. H3의 네이티브 packed-varlen Sage 경로를 선택하려면 의존성을 설치하고 `--attention-backend sage_attn`을 추가하세요. Hopper에서는 PyPI 2.2.0 빌드 대신 업스트림 SM90 바인딩 픽스를 설치하세요:

```bash Command theme={null}
pip install --force-reinstall \
  git+https://github.com/thu-ml/SageAttention.git@d9704247a5139ab4c03bf7fc6b35cc0e2cbb5ea4 \
  --no-build-isolation
```

백엔드는 서버-전역 기본입니다. 측정된 컴포넌트가 다른 커널을 필요로 할 때만 `--component-attention-backends`를 사용하고, 오버라이드에 이름 없는 컴포넌트에는 플랫폼 기본을 유지하세요.

```bash Command theme={null}
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant ref2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --encoder-parallel auto \
  --performance-mode speed \
  --quantization fp8 \
  --port 30010
```

H3는 비디오/오디오 patch 투영, timestep MLP, 최종 비디오/오디오 헤드를 자동으로 FP32로 유지합니다. 다른 모든 linear 레이어는 안정적인 full 모듈 접두사를 가지므로 추가 레이어를 비양자화로 유지할 수 있습니다:

```bash Command theme={null}
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant ref2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --encoder-parallel auto \
  --quantization fp8 \
  --quantization-ignored-layers blocks.0.attn token_refiner \
  --port 30010
```

<Warning>
  온라인 FP8은 근사이고 일관성 ground-truth 모드가 아닙니다. Cache-DiT와 결합할 수 있지만 근사가 중첩됩니다. 대상 워크로드에서 시각 품질·오디오 품질·메모리 사용·지연을 검증하세요. 이 레시피는 실제 H3 검증 실행에 사용된 상주 B200·B300 토폴로지로 제한됩니다.
</Warning>

단일 24 GB 카드에서는 FP8 대신 `kitchen_int8`을 사용하세요. Hub BF16 가중치에서 DiT 블록당 네 GEMM을 온라인으로 양자화하고(data-free, 캘리브레이션 없음) `comfy_kitchen.int8_linear`로 디스패치합니다. 양자화는 H3의 그룹화된 `qkv` 재정렬 후에 일어나므로 여기서 외부 사전 양자화 INT8 체크포인트를 로드하지 마세요.

```bash Command theme={null}
sglang generate \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --quantization kitchen_int8 \
  --attention-backend fa \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder \
  --dit-offload-prefetch-size 1 \
  --dit-layerwise-resident-layers 0 \
  --enable-torch-compile false \
  --prompt "A cat walking on a sunny beach, gentle waves." \
  --save-output
```

`fa`는 정확한 어텐션을 유지합니다. 더 빠른 근사 DiT 경로는 `--attention-backend sol_attn` with `--attention-backend-config dense_backend=sage_attn,dense_steps=10` 및 `--component-attention-backends text_encoder=torch_sdpa,transformer=sol_attn`을 사용하세요. [Quantization](/docs/sglang-diffusion/quantization#kitchen-int8) 및 [Attention Backends](/docs/sglang-diffusion/attention_backends#sage-then-sol-hybrid) 참조.

<Warning>
  `kitchen_int8`는 Linear 수치를 바꿉니다. `sol_attn`/`sage_attn`은 어텐션 알고리즘도 바꿉니다. 둘 다 일관성 ground-truth 모드가 아닙니다. `comfy-kitchen`이 설치되지 않으면 BF16 경로는 변경되지 않습니다.
</Warning>

사전 양자화·compact H3 텍스트 인코더는 [체크포인트·어댑터 형식](#checkpoint-and-adapter-formats)에 한 번 나열됩니다. 컴포넌트-로컬 경로를 사용하며 DiT의 `--quantization` 설정을 절대 상속하지 않습니다. SGLang은 네이티브 Qwen3-VL 인코더를 만들기 전에 그 메타데이터를 읽고 선택한 형식·투영·토폴로지가 호환되지 않으면 fail-closed합니다.

`--component-attention-backends transformer=cube_sparse_attn`으로 H3 transformer에 선택하고 `local_cube_size`와 `topk_ratio_list` 둘 다로 `--attention-backend-config`를 전달하세요. 백엔드를 범위 지정하면 텍스트 인코더는 네이티브 백엔드에 남습니다:

```bash Command theme={null}
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant ref2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --performance-mode speed \
  --component-attention-backends transformer=cube_sparse_attn \
  --attention-backend-config '{"local_cube_size": [4, 4, 4], "topk_ratio_list": [1.0, 1.0, 0.8, 0.7, 0.6, 0.5, 0.5]}' \
  --port 30010
```

* `local_cube_size`는 이웃 잠재 토큰을 한 어텐션 블록으로 묶는 `(T, H, W)` 큐브입니다. 정확히 3개 항목이어야 합니다.
* `topk_ratio_list`는 스텝별 유지 비율을 설정하며 denoise 스텝당 정확히 하나의 항목, 각각 `(0, 1]`이어야 합니다. `1.0` 비율은 스텝을 H3 네이티브 밀집 어텐션 경로에 유지하고, 더 작은 값은 FlexAttention 희소 경로를 선택해 더 많은 블록을 버립니다.

큐브 라벨링은 좌표 기반입니다. FL2VA 키프레임은 대상 비디오의 위치 그리드를 공유하므로 같은 `(T, H, W)` 좌표의 키프레임 토큰과 대상 토큰은 같은 시맨틱 큐브 라벨을 받습니다. 중복 좌표는 시간 그리드를 확장하지 않습니다. 시맨틱 큐브가 여러 물리 어텐션 블록에 걸칠 수 있습니다. Ref2VA에서 독립 레퍼런스 이미지는 밀집으로 남고, 레퍼런스 비디오·대상 비디오는 별도 스트림별 할당량이 아니라 하나의 전역 TopK 후보 풀에 기여합니다.

<Warning>
  Cube sparse attention은 근사 백엔드이며 일관성 ground-truth 모드가 아닙니다. `topk_ratio_list` 길이는 denoise 스텝 수와 같아야 합니다. Ring 병렬성을 지원하지 않습니다. `--ring-degree` 없는 `--ulysses-degree`를 사용하세요. FlexAttention 라우팅 오버헤드가 짧은 시퀀스에서 희소-커널 절약보다 클 수 있으므로 대상 워크로드에서 지연과 시각·오디오 품질을 모두 벤치마크하세요.
</Warning>

전역 백엔드는 H3 DiT를 느리게 선택하므로 컴포넌트 오버라이드로 Qwen 텍스트 인코더를 호환 밀집 백엔드에 유지하세요:

```bash Command theme={null}
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --attention-backend subblock_sparse_attn \
  --component-attention-backends text_encoder=fa \
  --attention-backend-config '{"sparsity": 0.75, "skip_first_steps": 10}' \
  --port 30010
```

SM120에서는 `text_encoder=torch_sdpa`를 사용하세요. 기본 구성은 처음 10번의 denoise forward 후 최대 75%의 키 블록을 버립니다. 짧은 시퀀스·cross-attention·미지원 형태는 밀집 경로로 계속됩니다. `sparsity`와 `skip_first_steps`를 시각·오디오 품질 검사와 함께 조정하세요.

H100/H200(SM90)에서 `compute_mode=sage_fp8`은 희소 커널을 온라인 INT8 Q/K와 FP8 P/V 컴퓨트로 전환합니다. 선택적 커널을 설치하고 컴퓨트 모드를 추가하세요:

```bash Command theme={null}
pip install git+https://github.com/thu-ml/SpargeAttn.git --no-build-isolation

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --attention-backend subblock_sparse_attn \
  --component-attention-backends text_encoder=fa \
  --attention-backend-config '{"compute_mode": "sage_fp8", "sparsity": 0.75}' \
  --port 30010
```

<Warning>
  SubBlock 라우팅과 `sage_fp8` 둘 다 근사입니다. 일관성 ground truth에는 밀집 BF16 어텐션을 사용하고 대상 해상도·지속 시간·작업·체크포인트에서 선택한 희소성을 검증하세요.
</Warning>

Encoder DP는 호환 요청 배치의 처리량 정책입니다. TP1·DiT DP1을 요구하고 인코더 가중치를 복제하며 1-배치를 개선하지 않습니다:

```bash Overlay theme={null}
--encoder-parallel dp \
--batching-max-size 2
```

크로스-노드 선택기 레시피는 자동 fold 결정이 노드 경계를 인지하지 못하므로 이미 복제를 사용합니다:

```bash Overlay theme={null}
--encoder-parallel replicate
```

10. 구성 노트 (Configuration notes)

• MiniMax-H3는 표준 24 fps 출력을 만듭니다. 요청 지속 시간은 target.duration_seconds로 표현됩니다.
• target.duration_seconds는 4~15초(포함)여야 합니다. 명령 선택기는 검증된 5-초 프로파일을 기본으로 합니다.
• 공개 품질 레시피에는 768px 짧은 모서리를 사용하세요. 정렬된 출력 치수는 target.aspect_ratio에서 파생됩니다.
• flow_shift는 비디오 디퓨전을, audio_flow_shift는 오디오 디퓨전을 제어합니다.
• V2V는 task: "ref2va" + video 또는 video_audio 레퍼런스를 사용합니다. Ref2VA 파티션이 서빙하며 별도 공개 task 값이 아닙니다.
• conditions[].start_time_seconds는 비디오 레퍼런스의 음이 아닌 오프셋을 선택합니다. 그 비주얼·오디오 스트림은 항상 함께 시크됩니다.
• Ref2VA 컨디션 순서는 시맨틱이며 프롬프트의 1-기반 소재 태그와 일치해야 합니다. Ref2VA에서 target.aspect_ratio: "auto"는 레퍼런스 자산의 지오메트리를 상속하는 대신 모델의 16:9 폴백으로 해석됩니다.
• 증류 파이프라인은 단일 denoise 분기를 사용하므로 CFG 병렬성이 적용되지 않습니다. 비활성화로 두세요. 1보다 큰 CFG 정도는 요청 호환성을 위해 받아들여지지만 여분 랭크가 같은 분기만 재계산할 뿐 요청을 가속하지 않습니다. 명시적 CFG 비활성화 또는 크기 1 설정은 여전히 유효한 no-op입니다.
• 공개 비주얼 VAE 품질 레시피는 중첩 타일드 디코드를 사용합니다. SGLang은 기본으로 그 레시피를 유지하고 decode 그룹에 완전한 타일을 분배합니다. 이는 스케줄링을 바꿀 뿐 각 타일 내부 연산은 바꾸지 않습니다.
• H3는 --vae-config.parallel-decode-mode spatial과 spatial_shard를 거부합니다. 검증에서 출력 불일치가 발견됐습니다. 기본 공개 타일드 레시피를 사용하세요.
• 기본 --encoder-parallel auto를 유지하세요. 서버 기본 batching_max_size 1에서 peer-to-peer 접근이 있는 단일-노드 H100/H200/B200/B300 레시피는 Qwen 텍스트 인코더를 그렇지 않으면 유휴 Ulysses 랭크에 접습니다. 이는 DiT 텐서 병렬성과 별개입니다. 순수-TP 레시피는 이미 인코더를 TP 그룹에 샤딩하고 world fold를 추가하지 않습니다.
• 처리량 지향 서빙에는 DP (batched throughput) 를 선택하세요. 선택기는 --encoder-parallel dp를 편집 가능한 1보다 큰 --batching-max-size와 짝짓습니다. Encoder DP는 각 DiT 복제 안에 남고 encoder TP와 구성됩니다. 1-배치에는 이득이 없고 분할되지 않은 배포와 bitwise-동일하지 않습니다.
• 명시적 Fold는 측정된 고대역폭 단일-노드 토폴로지에서 단일-요청 지연과 인코더 메모리를 우선합니다. folding이나 encoder DP가 부적합할 때 Replicate를 호환 경로로 사용하세요.
• --use-fsdp-inference true는 DiT만 샤딩합니다. MiniMax-H3는 FSDP all-gather 중 patch·time·output 투영의 원래 FP32 dtype을 보존합니다.
• speed는 모델 컴포넌트를 상주로 유지하고, auto는 모델 인지 120 GiB 상주 임계값을 적용합니다. memory는 OOM 회피를 우선하고 실행 가능한 VAE 디코더를 기본 layerwise 집합에 포함합니다.
• Breakable CUDA graph 실행은 명시적 opt-in이며 권장 speed 프리셋의 일부가 아닙니다. --enable-breakable-cuda-graph, --warmup-resolutions의 모든 서빙 크기, 실시간 H3 컨디션 시퀀스를 커버하는 --bcg-text-buckets가 필요합니다. 검증된 1344×768 Ref2VA 레시피는 5504를 사용합니다.

11. 벤치마크 (Benchmarks)

선택기는 NVIDIA 데이터센터 GPU에서 상주·FSDP 프로파일을 노출합니다. GPU 수는 선택한 레시피의 속성입니다. 모든 플랫폼이 그만큼의 GPU를 요구한다는 주장이 아닙니다. 아래 상세 표는 수집된 측정이 있는 구성의 성능만 보고합니다:

GB300 single-host

Linux ARM64, SGLang main 15d2cbcc90fc, PyTorch 2.13.0+cu130, NCCL 2.29.7을 사용한 1 호스트 × 4 NVIDIA GB300에서 4개 요청. 소스 체크아웃은 lmsysorg/sglang:latest 안에서 python3 -m pip install -e "python[diffusion]" --upgrade로 설치됐습니다. 이는 소스-검증 환경이지 이미지의 번들 릴리스가 그 리비전을 포함한다는 주장이 아닙니다.

명령은 빌더의 GB300 기본과 일치합니다. Ulysses4, 상주 가중치, 자동 인코더 folding, 네이티브 BF16/FP32, 플랫폼-기본 Dynamic cuDNN/FA 어텐션, eager 실행. 모델은 sglang serve가 MiniMaxAI/MiniMax-H3에서 다운로드했습니다.

워크로드는 빌더의 cat-band 프롬프트, FL2VA T2VA, 768px 짧은 모서리의 5-초 요청, 50 추론 스텝, quality="lossless", 1-출력, 시드 1101을 사용합니다. 모든 MP4가 비디오·오디오를 담았고 full decode 검사를 통과했습니다.

이는 클라이언트-관측 완료 시간이며 최대 1초의 상태-폴링 지연을 포함합니다. 다운로드·모델 로딩·서버 워밍업은 제외됩니다. 배포 smoke/지연 측정이지 크로스-프레임워크 품질 감사·최소-GPU 주장·GB200/NVL72 확장 외삽이 아닙니다.

Ascend NPU 토폴로지 비교

두 토폴로지 모두 Laser Attention과 Ascend 실행 명령의 명시적 Cache-DiT 구성을 사용했고 --dit-cpu-offload false로 DiT를 상주로 유지했습니다. 측정 워크로드는 1344×768, 124 프레임, 24 fps, 50 추론 스텝의 5-초 T2VA 요청 하나였습니다.

이는 각 토폴로지의 개별 end-to-end 측정입니다. 8-NPU 토폴로지는 4-NPU보다 end-to-end 지연이 46.8% 낮았습니다.

B300 precision과 encoder placement

단일 8× B300 호스트의 12-구성 스윕으로, 두 체크포인트 파티션·두 transformer 정밀도·세 텍스트-인코더 배치를 모두 다룹니다. 한 요청이 얼마나 걸리고 메모리를 얼마나 쓰는지라는 한 질문에 답합니다.

측정된 것 (What was measured)

하드웨어. 8× NVIDIA B300 SXM6, 단일 노드.

모델. MiniMaxAI/MiniMax-H3, 공개 가중치 파티션 둘 다.

서빙 명령. 선택기가 B300에 내는 정확한 레시피 + 테스트 중인 오버레이 플래그 하나 또는 둘:

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --num-gpus 8 \
  --ulysses-degree 8 \
  --performance-mode speed \
  --host 0.0.0.0 \
  --port 30010

스윕 축은 --model-variant(fl2va/ref2va), --quantization(BF16은 설정 안 함 / fp8), --encoder-parallel(auto/fold/replicate)입니다. 12개 서버 사이에 다른 차이는 없습니다.

이것은 단일-요청 지연 스윕(batching_max_size: 1)이므로 encoder DP는 의도적으로 제외됩니다. 1-배치를 분배할 수 없습니다. 위 DP for a request batch 설정을 호환 다중-요청 배포에 사용하세요.

드라이버.

python3 -m sglang.multimodal_gen.benchmarks.bench_serving \
  --host 127.0.0.1 --port 30010 \
  --model MiniMaxAI/MiniMax-H3 \
  --dataset vbench --task text-to-video \
  --num-prompts 1 --max-concurrency 1 \
  --warmup-requests 1 --warmup-inference-steps 50 \
  --extra-body '{"task":"t2va","conditions":[],"target":{"short_edge":768,"aspect_ratio":"16:9","duration_seconds":5.0},"seconds":5,"flow_shift":12.0,"audio_flow_shift":3.0}'

워크로드 — 출력 지속 5.167 s, 해상도 1344×768, 프레임 124 @ 24 fps, 디노이징 스텝 50, flow_shift/audio_flow_shift 12.0/3.0, in-flight 요청 1, 측정 요청 셀당 1개(워밍업 1 후).

결과 (Results)

FL2VA와 Ref2VA, BF16/FP8, 인코더 auto/fold/replicate의 12개 조합. FL2VA BF16 auto가 19.04 s 지연·83,578 MB, FP8 auto가 18.03 s·51,926 MB. Ref2VA BF16 auto 29.12 s·83,968 MB, FP8 auto 27.12 s·52,816 MB. Load·warmup·peak/GPU는 표에 각 조합별로 나열됩니다.

H200 토폴로지 비교

같은 4-카드 H200 호스트가 표준 1344×768, 5-초, 50-스텝 T2VA 요청으로 두 무손실 상주 배치를 완료했습니다. Ulysses4가 H200 지연 기본으로 남습니다. 워밍업이 서빙 해상도를 커버하면 TP2 + Ulysses2보다 end-to-end 5.0% 빠릅니다. TP2 + Ulysses2는 DiT 가중치를 샤딩해 GPU당 최고 메모리를 약 30 GB 낮게 유지합니다.

H200 크로스-노드 확장

긴 레퍼런스·긴 지속은 packed 시퀀스 길이를 키우고, Ulysses만으로는 노드 하나의 GPU 수를 넘어 시퀀스 병렬성을 확장할 수 없습니다. H3는 노드-로컬 Ulysses와 크로스-노드 Ring을 결합합니다. 16 GPU 크로스-노드 명령(Ulysses8 × Ring2)은 T2VA denoise/스텝 0.749 → 0.477 s(−36.3%), Ref2VA/V2V 2.572 → 1.494 s(−41.9%)를 냈습니다. 파이프라이닝된 크로스-노드 경로는 단일-노드 8-GPU 기준선 대비 −47.0%였습니다.

H100 토폴로지 비교

같은 4-카드 H100 호스트가 세 무손실 배치를 완료했습니다. TP2 + Ulysses2가 가장 빨랐고(13.25 s, 66.04 GB), FSDP + Ulysses4(13.36 s, 57.01 GB), TP4 + Ulysses1(13.86 s, 49.80 GB) 순이었습니다.

RTX 5090 용량 실행 (2장)

검증된 2-카드 RTX 5090 호스트는 layerwise 오프로드와 함께 TP2를 사용했습니다. full 50-스텝, 1344×768, 5-초 요청이 559.67초에 완료됐습니다. 525.05초 디노이징 + 33.61초 디코딩, GPU당 26.3 GiB 샘플 최고. prefetch 1 resident 20이 선택 레시피(5-스텝 43.48 s, 추론 78.11 s)였고, prefetch 2는 측정 가능한 이득이 없었으며, Ulysses2·resident 10은 워밍업에 도달하지 못했습니다.

Consumer GPU 튜닝

컨슈머 하드웨어에서 결정적 질문은 어떤 카드를 갖고 있느냐가 아니라 그 뒤의 호스트 RAM이 얼마냐입니다. H3 가중치는 약 108 GB입니다(DiT 61.73 GB, 텍스트 인코더 46.18 GB). 모델 외에 정확히 한 플래그가 필요한 머신이 대부분입니다:

sglang serve --model-path MiniMaxAI/MiniMax-H3 --model-variant fl2va \
  --layerwise-offload-components dit,text_encoder,vae

VRAM 16 GB 이상이면 13초 디코드를 위해 --layerwise-resident-layers video_vae=36을, ~96 GB 호스트 RAM + VRAM 16 GB+면 6초 스텝을 위해 --dit-layerwise-resident-layers 4를 추가하세요. 페이지 상단의 빌더에 컨슈머 카드와 Host RAM 선택기가 있습니다.

Unified-memory 머신(DGX Spark, GB10, 128 GB CPU/GPU 공유)은 예외입니다. 플래그 없이 실행하세요. 자동 오프로드가 스스로 저서 명시적 레시피보다 denoise에서 2.1× 빨랐습니다.

두 예산, 그리고 각각이 사는 것 — 12 GB VRAM + 32 GB host 레시피 A(디노이즈 16.8–18.7 s/it), host는 넉넉하고 VRAM 16 GB 레시피 B(6.01 s/it).

32 GB 내부에서 가중치를 핀할 수 없어 각 디노이즈 스텝이 체크포인트 매핑에서 약 60 GiB를 복사합니다. 호스트에 가중치를 핀할 공간을 주는 것이 6.01 s를 만드는 것입니다. 두 제약 수치 모두 2 TB 호스트 메모리 머신에서 계측됐습니다. 실제 32 GB 호스트는 107.7 GiB를 캐시할 수 없어 더 느릴 것으로 기대하세요. NVMe는 권장이 아니라 요구사항입니다.

레시피 A — 12 GB VRAM + 32 GB host에 맞음

PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True \
sglang serve --model-path MiniMaxAI/MiniMax-H3 --model-variant fl2va \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder,vae \
  --layerwise-resident-layers video_vae=36

레시피 B — 호스트 메모리는 넉넉함 (빠른 경로)

sglang serve --model-path MiniMaxAI/MiniMax-H3 --model-variant fl2va \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder,vae \
  --dit-layerwise-resident-layers 4 \
  --layerwise-resident-layers video_vae=36

레시피 B는 ~112 GB의 호스트 메모리(DiT 61.56 GB, 텍스트 인코더 46.18 GB, VAE ~4.5 GB)를 핀합니다. 32 GB 머신에서는 쓰지 마세요.

무엇을 바꾸지 말아야 하는가 — video_vae=36은 디코드 동안만 모든 디코더 블록을 유지하고, expandable_segments 줄을 유지하며, --enable-torch-compile은 끄세요. 레시피 A의 플래그는 자동 정책이 스스로 골라야 할 것입니다.

시작 로그 읽기 — Layerwise offload: host memory available: N GiB, leaving N GiB of weights on the checkpoint mapping, Loaded video_vae: ... host mmap vs host pageable 세 줄을 예산과 대조해 첫 1분에 잘못 설정된 머신을 잡으세요. 디노이즈 후 요청이 죽으면 decode가 캡과 충돌하는 것입니다.

같은 가중치로 ComfyUI 대비 — 호스트 메모리가 넉넉하면 엔진이 가깝고 sglang이 앞섭니다(sglang Recipe B 6.01 s/it vs ComfyUI KSampler 6.58–6.59 s/it). 12 GB 안에서는 양쪽 모두 하드 캡에서 Recipe A가 전 호스트 크기에서 이깁니다(32 GB 235 s vs 276–302 s, 48 GB 218 s, 64 GB 180 s).

RTX 5090 단일 카드, 물리 데스크톱

Ryzen 9 9950X 데스크톱(32 GB RTX 5090, 60 GB RAM, 8 GB 스왑, Samsung 9100 PRO PCIe 5.0, Ubuntu 24.04)에서의 실행. sglang: text encoding 4.2 s, denoise 5.14–5.17 s, decode 6.4 s, request 112.2/112.1 s. ComfyUI --fast-disk --cache-none: 11.3 / 5.17–5.30 / 7.2 s, 145.9/145.6/140.9 s. 호스트 RAM이 숨길 트래픽 양을 결정하고, 어느 쪽 기본 명령도 이 머신에서 살아남지 못합니다.

RTX 4090 24 GB 단일-GPU 실행

RTX 4090 D 24 GB가 1344×768, 107-프레임, 20-NFE T2VA 워크로드(euler, torch.compile·스텝 캐싱 비활성)를 DiT·텍스트-인코더 layerwise 오프로드로 완료. GPU 최고 약 18 GB. kitchen_int8 + FA 1.34×, + sol_attn 1.81×, + sage_attn 2.32×, + Sage→Sol hybrid 2.48×. 기본은 kitchen_int8 + fa로 유지.

AMD Instinct 작업·확장 실행

AMD 레시피는 공개 BF16/FP32 정밀도 정책을 유지하고 AITER packed attention을 사용합니다. 선택기는 가장 빠른 측정 토폴로지, Ulysses degree 8의 8 GPU를 냅니다. MI355X T2VA 55.29 s / FL2VA 53.80 s / Ref2VA 41.38 s, MI300X는 각각 167.49 / 150.23 / 107.62 s. 확장은 8→1 GPU에서 MI355X 55.29 → 288.80 s, MI300X 167.49 → 978.09 s.

10. ComfyUI에서 실행 (Run in ComfyUI)

ComfyUI에서 MiniMax-H3를 실행하는 방법은 ComfyUI 문서와 모델 카드를 참조하세요.

더 알아보기 (Learn more)

• MiniMax-H3
• SGLang Diffusion 설치 가이드
• Quantization
• Attention Backends
• SGLang Diffusion 성능 최적화