미니맥스 h3 설치방법 (MiniMax H3): 설치 환경, 실행 명령어, 오류 해결

미니맥스 H3(헤일로 3.0)가 2026년 8월 3일, Hugging Face에 오픈웨이트로 공개됐습니다. 텍스트·이미지·영상·오디오를 함께 이해하는 33B 옴니모달 모델이라, 프롬프트 하나로 768p 영상과 32kHz 스테레오 사운드를 동시에 뽑아냅니다. "영상은 나오는데 소리가 없다"는 기존 AI 영상 생성의 공통 아쉬움을 처음부터 다른 방식으로 푼 모델이라 개발자 커뮤니티에서도 화제가 되고 있습니다.

이 글은 공식 모델 카드와 발표 자료를 바탕으로 설치 환경, 실행 명령어, 오류 해결을 순서대로 정리합니다. 끝까지 읽으면 로컬 설치를 진행할지, 어떤 백엔드를 쓸지, 막히면 어디를 봐야 할지가 바로 정해집니다.

시작하기 전에 라이선스를 먼저 짚고 갑니다. 미니맥스 H3의 Community License는 한국, 미국, EU, 영국을 제외 지역(Excluded Territory)으로 규정합니다. 다시 말해 한국에서 이 가중치를 자체 호스팅으로 돌리는 것은 라이선스상 허용되지 않습니다. 이 글은 기술적 설치 방법을 정리하되, 한국 개발자가 실제로 쓸 수 있는 경로가 무엇인지도 함께 다룹니다.

0. 헤일로 웹앱으로 먼저 결과물 확인하기

로컬 설치는 GPU 사양부터 만만치 않습니다. 그래서 설치 환경을 다루기 전에, 가장 먼저 할 일은 미니맥스 H3가 어떤 결과를 내는지 직접 보는 것입니다. 공식 웹앱 헤일로(Hailuo)를 쓰면 GPU 없이 프롬프트만으로 테스트할 수 있습니다.

1. 미니맥스 H3 웹앱에 접속해 로그인

2. 생성 스튜디오에서 H3 모델 선택

3. 프롬프트 입력 — 만들고 싶은 장면을 자연어로 상세히 작성

4. 화면비·길이(4~15초)·해상도 설정

5. 생성 클릭 → 768p 영상 + 스테레오 사운드가 한 번에 출력

첫 테스트용 프롬프트 예시:

카페 테이블 위의 따뜻한 커피잔. 창밖으로 비가 내린다. 카메라가 천천히 커피잔에 다가가고, 증기와 빗소리, 은은한 재즈 배경음악이 자연스럽게 깔린다. 사실적인 조명, 16:9.

Rule of Thumb: H3는 오디오가 살아있는 짧은 클립이 강점입니다. 첫 테스트에서는 반드시 소리와 함께 쓰는 장면(빗소리, 발소리, 대화, 음악)을 프롬프트에 포함하세요. 무성 장면을 만들면 H3의 핵심 강점을 반도 못 끌어냅니다.

1. 설치 환경

1-1. 라이선스: 한국은 제외 지역

미니맥스 H3 오픈웨이트는 MiniMax H3 Community License로 배포됩니다. OSI 기준의 '오픈소스'가 아니라, 코드·학습 데이터·평가 방법은 닫힌 '오픈웨이트' 릴리스입니다. 개발자가 상업적으로 쓰기 전에 반드시 알아야 할 핵심 조항은 다음과 같습니다.

• 제외 지역: 미국, EU, 영국, 한국 — 이 지역에서는 가중치 사용·수정·배포 불가. 생성 결과물을 제외 지역 밖으로 내보내는 것도 제한됩니다.

• 매출 상한: 상업적 사용은 연매출 2,000만 달러 미만만 무료. 초과하면 미니맥스의 서면 허가를 받아야 합니다(api@minimax.io).

• 표기 의무: 미니맥스 H3를 쓴 상업 제품 UI에 '미니맥스 H3'를 눈에 띄게 표시해야 합니다.

• 모델 개선 금지: H3 또는 그 출력을 다른 AI 모델의 개선·증류에 사용할 수 없습니다.

• 준거법: 홍콩법. 라이선스는 사용자에게 보증을 주지 않고, 발생하는 책임은 사용자가 부담합니다.

한국 개발자에게는 첫 항목이 사실상 로컬 설치를 가로막는 조건입니다. 다만 호스팅 API와 온라인 생성 서비스는 한국을 포함해 전 세계에서 사용할 수 있고, 저장소의 신청 폼으로 별도 서면 허가를 요청하는 것도 가능합니다. 즉 "한국에서 미니맥스 H3를 못 쓴다"가 아니라 "자체 호스팅 경로만 제한된다"가 정확한 표현입니다.

1-2. 모델 구조와 하드웨어 요구사항

미니맥스 H3는 단일 체크포인트가 아니라 3개 모듈로 구성된 시스템입니다. 어떤 게 로컬에서 도는지부터 알아야 설치 범위가 보입니다.

H3-Base의 33B는 생성 담당('트렁크') 파라미터 수입니다. 인코더(Qwen3-VL-32B 기반)와 Visual/Audio VAE를 합친 전체 시스템은 약 60B, 표준 정밀도 가중치만 약 120GB입니다. GPU 메모리별 현실적인 기준은 아래와 같습니다.

공식 SGLang 배포는 GPU 4장(--num-gpus 4 --ulysses-degree 4)을 전제로 합니다. ComfyUI는 RTX 3060 12GB에서도 동적 VRAM 오프로딩으로 돌아가지만, 호스트 RAM이 64GB쯤은 필요하고 속도는 느립니다. "어떤 GPU가 있으면 되나"보다 "내 GPU로 어떤 수준까지 되나"를 먼저 계산하는 것이 효율적입니다.

1-3. 소프트웨어 준비물

• Python 3.10 이상 + CUDA 환경

• Hugging Face CLI: pip install -U "huggingface_hub[cli]"

• git

• 백엔드별: ComfyUI v0.31.0+ / SGLang 0.5.16+ / vLLM-Omni / diffusers

diffusers 경로로 갈 경우 FFmpeg도 필요합니다(영상·오디오 믹싱용).

1-4. 다운로드 용량과 디스크

• 최소 구동용(INT8 FL2VA 체크포인트 + 양자화 텍스트 인코더 + VAE 2종): 약 42.5GB

• 전체 저장소(Hugging Face 기준): 약 288GB (ComfyUI 미러는 343~498GB)

받기 전에 디스크 여유를 확인하세요. 모델 카드에 없는 추가 파일을 받다가 디스크가 차는 실수가 흔합니다.

2. 실행 명령어

2-1. 모델 다운로드

공식 저장소는 MiniMaxAI/MiniMax-H3입니다. Hugging Face CLI로 내려받습니다.

hf download MiniMaxAI/MiniMax-H3 --local-dir MiniMax-H3

릴리스에는 두 가지 BF16 체크포인트가 포함되어 있습니다.

각 체크포인트에는 processor, tokenizer, text_encoder, transformer, visual_vae, audio_vae가 포함되어 있습니다. 토크나이저나 컴포넌트 구성을 함부로 바꾸면 동작이 틀어질 수 있으니 모델 카드의 구성을 그대로 쓰세요.

2-2. 백엔드 선택

2-3. ComfyUI로 실행

MiniMaxH3-ComfyUI.zip을 받아 custom_nodes 폴더에 넣으면 됩니다. ComfyUI v0.31.0 이상에서 동작하고, T2V/I2V/R2V 워크플로 JSON 템플릿이 포함되어 있어 코드 없이 바로 구성할 수 있습니다.

속도가 아쉽다면 Turbo LoRA(MiniMaxAI/MiniMax-H3-Turbo-Lora)를 LoraLoader 노드로 모델 출력과 생성 노드 사이에 연결하고, strength_model을 1.0으로, num_inference_steps를 50→10~15로 줄이면 대략 2배 빨라집니다. 로컬 첫 실험은 FL2VA(T2V)부터 시작하는 것이 가장 진입 장벽이 낮습니다.

2-4. SGLang으로 서빙 (공식)

SGLang은 공식 모델 카드가 안내하는 서빙 도구입니다. H3 지원은 0.5.16 이후 버전에서 동작합니다.

git clone https://github.com/sgl-project/sglang.git
cd sglang
uv pip install -e "python[diffusion]"

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

Ref2VA는 --model-variant ref2va로 별도 서버를 띄워야 합니다. 공식 예시는 --num-gpus 4 --ulysses-degree 4처럼 멀티 GPU 환경을 전제로 하므로, 로컬 768p 생성에는 상당한 GPU 자원이 필요하다는 점을 미리 감안하세요.

2-5. vLLM-Omni / diffusers

vLLM은 일반판이 아니라 vLLM-Omni에서 미니맥스 H3를 지원합니다.

docker pull vllm/vllm-omni:minimax-h3

NVIDIA 외에 AMD(ROCm) 공식 이미지(vllm/vllm-omni-rocm:minimax-h3)도 제공됩니다. FL2VA/Ref2VA 파티션당 서버를 하나씩 띄우는 구조입니다.

diffusers로 Python 제어가 필요하다면 huggingface/diffusers의 H3 지원 커밋을 설치합니다.

python -m pip install "git+https://github.com/huggingface/diffusers.git@abc5e9bf71fd38f53cd471bc3acaa84bc5ecbfdc" transformers accelerate safetensors torchao sentencepiece av

영상·오디오 텐서가 분리되어 반환되므로, H.264 + 스테레오 AAC 믹싱은 PyAV/FFmpeg로 처리해야 합니다.

2-6. 2K를 얻는 하이브리드 워크플로

"로컬에서 돌리니 화질이 아쉽다"는 순간이 옵니다. 이때 필요한 게 하이브리드 방식입니다.

로컬 H3-Base (768p 생성) + 미니맥스 API (H3-Context-IR 입력 정리 + H3-Regenerate-2K 2K 재생성)

오픈웨이트만으로는 2K까지 도달할 수 없습니다. 완전한 2K 워크플로는 공식 API를 섞어야 합니다. 반대로 768p 수준이면 로컬로 충분하니, 생성 비용을 크게 아끼면서 자체 파이프라인을 돌릴 수 있다는 것이 오픈웨이트의 실용적 가치입니다. 공식 API 가격(폐쇄 베타 기준)은 2K 약 $0.13/초, 768p 약 $0.09/초 수준입니다.

3. 오류 해결

문제 1: VRAM 부족 (OOM)

• 증상: CUDA out of memory 반복

• 원인: 33B 파라미터를 일반 VRAM에 통째로 올리려 함

• 해결: INT8 양자화 + 작은 캔버스로 시도, 호스트 RAM 오프로드 활용, 불가하면 온라인 생성/API로 전환

문제 2: 8GB GPU에서 너무 느림

• 증상: 클립 1개에 수십 분 이상

• 원인: 레이어 단위 오프로드로 인한 병목

• 해결: Turbo LoRA + 스텝 수 축소로 최대한 끌어내고, 실서비스는 온라인 생성으로

문제 3: SGLang 버전 오류

• 증상: ModuleNotFoundError 또는 속성 없음 에러

• 원인: H3 지원 전 버전 사용

• 해결: SGLang 0.5.16 이상, 가능하면 소스/개발 이미지로 설치

문제 4: Ref2VA 실행 실패

• 증상: FL2VA 서버에 ref2va 요청이 들어가 실패

• 원인: variant 미지정

• 해결: --model-variant ref2va로 별도 서버 실행

문제 5: 오디오가 안 나옴

• 증상: 영상만 생성되고 소리가 없음

• 원인: 프롬프트에 소리 요소가 없거나 오디오 VAE 누락

• 해결: 빗소리·대화·음악 같은 소리 요소를 프롬프트에 명시, 오디오 VAE 체크포인트 포함 여부 확인

문제 6: 2K가 안 나옴

• 증상: 로컬 출력이 768p에서 멈춤

• 원인: H3-Regenerate-2K가 API 전용

• 해결: 공식 API 하이브리드 워크플로 사용

문제 7: 모델 카드 구성이 바뀌어 동작이 틀어짐

• 증상: 토크나이저·컴포넌트 변경 후 결과가 이상해짐

• 원인: 기본 구성 외 커스텀

• 해결: 모델 카드의 구성을 그대로 사용. 컴포넌트는 교체하지 않기

문제 8: 한국 지역 라이선스 제한

• 증상: 자체 호스팅 사용이 라이선스상 허용되지 않음

• 원인: 한국이 Excluded Territory

• 해결: 온라인 생성/호스팅 API 사용, 또는 저장소의 서면 허가 신청

4. 실전 판단: 로컬 vs API vs 웹앱

마무리: 로컬 설치 vs 온라인 생성

미니맥스 H3 로컬 설치는 환경(VRAM 24GB 이상이 현실적) → 다운로드 → 백엔드 선택 → 2K는 API 하이브리드의 흐름입니다. 다만 한국은 라이선스 제외 지역이라, 결과물을 가장 빠르게 확인하고 싶다면 미니맥스 H3 온라인 생성이 더 현실적입니다. 영문 자료와 해외 팀 기준으로는 미니맥스 H3 스튜디오를 참고할 수 있습니다.

같은 프롬프트로 온라인 생성 결과를 먼저 확인해 보면, 로컬 설치를 진행할지 말지 판단이 훨씬 빨라집니다.