이 프로젝트가 하는 일
이 저장소는 Apple Silicon에서 TensorFold용 MiniMax H3 비디오 모델을 패키징합니다. TensorFold의 H3 제품군과 MLX int8 Metal 커널, LightX2V Turbo 어댑터를 결합하여 동기화된 스테레오 오디오가 포함된 비디오를 생성합니다.
이 패키지는 텍스트-비디오를 지원하며, 버전 1.1부터는 제공된 첫 프레임을 사용하는 이미지-비디오도 지원합니다. 측정된 Mac Studio M5 Ultra(메모리 256 GB)에서는 Turbo 어댑터 사용 시 5초 길이의 864x480 클립을 약 50초 만에 생성합니다. 문서화된 벤치마크 조건에서는 768x448 클립에 약 40초가 걸립니다.
이 저장소는 서버나 제품이 아니라 개발용 렌더링 경로입니다. tensorfold generate 명령은 없으며, 포함된 스크립트를 통해 렌더링할 때마다 모델을 로드합니다.
주요 기능
- 텍스트-비디오: 장면을 설명하면 비디오와 스테레오 오디오가 포함된 MP4를 생성합니다.
- 이미지-비디오: 첫 프레임을 제공하고 이후에 일어날 일을 설명합니다.
- Turbo 생성: LightX2V 어댑터는 문서화된 고속 경로에서 렌더링을 3회의 정방향 연산으로 줄입니다.
- MLX 및 int8 커널: 호환되는 M5 텐서 하드웨어에서는 일부 트랜스포머 및 디코더 연산에 int8 Metal 커널을 사용합니다.
- 재현 가능한 설정: 설치 프로그램이 TensorFold, MLX, 지원 라이브러리, 모델 리비전 및 어댑터 체크섬을 고정합니다.
- 선택적 기본 모델 렌더링: 기본 모델에 더 가까운 렌더링이 필요하면 어댑터를 비활성화하고 약 20회의 샘플링 단계를 사용할 수 있습니다.
하드웨어 및 소프트웨어 요구 사항
공개된 성능 수치는 macOS 27.0.1에서 실행되는 256 GB 통합 메모리의 Mac Studio M5 Ultra에서 측정되었습니다. 프로젝트 문서에 따르면 최소 128 GB의 메모리가 필요하며, 어댑터 병합 시 최대 메모리 사용량이 약 103 GB에 이를 수 있습니다. 어댑터를 사용하지 않을 때의 최대 메모리 사용량은 약 65 GB입니다.
int8 커널에는 Metal 4 텐서 연산이 필요하므로, 보고된 가속 성능은 호환되는 M5 하드웨어를 대상으로 합니다. 이러한 연산을 지원하지 않는 시스템에서는 H3 제품군이 bfloat16으로 실행되며, README에 설명된 C 기반 대안보다 느릴 수 있습니다.
Homebrew, Python 3.11, uv, FFmpeg도 필요합니다. MiniMax H3 모델 다운로드 용량은 약 144 GB이며 Turbo 어댑터는 약 1.96 GB입니다.
프로젝트 설치
저장소를 복제하고 필요한 호스트 도구를 설치합니다.
git clone https://github.com/drowzeys/keys-Mac-TensorFold-MiniMax-H3-MLX.git
cd keys-Mac-TensorFold-MiniMax-H3-MLX
brew install python@3.11 uv ffmpeg일괄 설정 스크립트를 실행합니다.
bash oneshot-setup.sh설치 프로그램은 ~/.local/opt/tensorfold-h3에 격리된 환경을 만들고 H3 제품군과 고정된 의존성 잠금 파일을 포함한 TensorFold 0.6.5를 설치합니다. Docker를 사용할 수 있으면 프로젝트의 GHCR 사전 빌드 캐리어에서 체크섬이 검증된 TensorFold 페이로드를 가져옵니다. 그렇지 않으면 Git에서 일치하는 소스 커밋을 가져옵니다.
설정 과정에서는 필요한 minimax-h3-mlx 리비전도 복제하고, MiniMax H3 FL2VA 파티션을 ~/h3-models/MiniMax-H3에 다운로드하며, Turbo 어댑터를 다운로드하고, 테스트 클립을 outputs/test.mp4로 렌더링합니다.
재설치하지 않고 기존 설치를 확인하려면 다음을 실행합니다.
bash oneshot-setup.sh --verify초기 테스트 렌더링을 건너뛰려면 다음을 사용합니다.
bash oneshot-setup.sh --no-render
PREFIX 및 H3_MODEL_DIR 환경 변수를 통해 기본 설치 위치와 모델 위치를 변경할 수 있습니다.
텍스트-비디오 클립 생성
프롬프트와 출력 파일 이름을 지정하여 scripts/generate.sh를 사용합니다.
bash scripts/generate.sh "A hummingbird hovering over red flowers, soft wing hum" out.mp4기본 경로는 구성된 Turbo 어댑터와 저장소의 기본 생성 설정을 사용합니다. 프롬프트에는 시각적 장면과 필요한 경우 의도한 오디오를 함께 설명합니다.
결정론적인 변형을 생성하려면 시드를 지정하고 지원되는 캔버스를 선택합니다.
WIDTH=768 HEIGHT=448 SEED=7 bash scripts/generate.sh "A quiet train crossing a snowy valley at dawn" out.mp4프롬프트를 텍스트 파일에 저장할 수도 있습니다. 이 경우 프롬프트 인수에 빈 값을 전달하고 PROMPT_FILE을 설정합니다.
PROMPT_FILE=prompts/black-mirror-scene.txt SEED=2077 bash scripts/generate.sh "" out.mp4이미지-비디오 클립 생성
FIRST_FRAME을 이미지 파일로 설정합니다. 이미지가 첫 프레임이 되며, 프롬프트는 이어지는 움직임이나 사건을 설명합니다.
FIRST_FRAME=photo.jpg WIDTH=1344 HEIGHT=768 bash scripts/generate.sh "She turns to the camera and smiles" out.mp4이미지는 선택한 캔버스에 맞게 늘어나므로, 가로세로 비율이 일치하는 크기를 선택하거나 렌더링 전에 이미지를 자르십시오. README에서는 16:9 콘텐츠에 1344x768, 9:16 콘텐츠에 768x1344, 정사각형 콘텐츠에 768x768을 권장합니다.
MiniMax 스타일의 이미지-비디오 프롬프트에서는 다음과 같이 첫 프레임을 명시할 수 있습니다.
For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced. The subject walks through the doorway and looks toward the window.첫 프레임 생성은 Turbo 어댑터와 20단계 기본 경로에서 사용할 수 있습니다. 마지막 프레임 및 참조 이미지 모드는 이 패키지에 연결되어 있지 않습니다.
제어 프레임, 해상도 및 샘플링
프레임 수는 17n + 5 형식을 따라야 합니다. README에는 56, 73, 90, 124, 192, 243, 362 프레임을 포함한 지원 예시가 나와 있습니다. 가로와 세로는 32의 배수여야 하며, 출시된 모델의 제한은 전체 캔버스 기준 최대 768x1344픽셀입니다.
빠른 Turbo 경로는 세 번의 포워드 연산을 사용합니다. 어댑터를 비활성화하고 20단계 렌더링을 사용하려면 ADAPTER=none과 POINTS=21을 설정합니다.
ADAPTER=none POINTS=21 bash scripts/generate.sh "A lantern glowing beside a forest path" base-model.mp4README는 이 설정이 기본 모델에 더 가깝다고 설명합니다. Turbo는 선명한 프레임을 빠르게 생성할 수 있지만 때때로 인물이 중복될 수 있습니다. 같은 시드를 사용해도 두 모드에서 서로 다른 구도가 생성될 수 있습니다.
속도상의 절충점 이해하기
가장 큰 속도 향상은 20회 대신 Turbo 어댑터가 세 번의 포워드 연산을 사용하는 데서 나옵니다. 지원되는 M5 텐서 하드웨어에서는 int8 SwiGLU MLP, int8 QKV 연산, 어텐션 출력 및 비디오 디코더 커널이 추가적인 성능 향상을 제공합니다.
문서화된 864x480 벤치마크에서 Turbo 경로는 디노이징에 약 27.6초, 텍스트 인코딩, 로딩 및 양자화, 디코딩을 포함한 전체 작업에 약 50초가 걸렸습니다. 같은 비교에서 20단계 TensorFold int8 렌더링은 전체 작업에 약 210초가 걸렸습니다.
이 수치는 특정 하드웨어를 기준으로 하므로 보편적인 값으로 간주해서는 안 됩니다. 또한 저장소에서는 측정된 int8 플래시 방식의 대안이 유용한 속도 향상을 제공하지 못했기 때문에 어텐션 자체는 여전히 MLX 스케일드 닷 프로덕트 어텐션을 사용한다고 설명합니다.
고급 설정 및 워크플로 팁
사전 빌드된 캐리어 사용
설치 프로그램은 GHCR 캐리어를 사용할 수 있지만, 이 캐리어는 Mac 런타임이 아닙니다. 컨테이너 내부에서는 Metal이 실행되지 않으며, 캐리어는 네이티브 설치에 필요한 TensorFold 휠, 종속성 잠금 파일, 생성 스크립트 및 체크섬만 제공합니다.
docker pull ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1
docker run --rm -v "$PWD":/out ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1 cp -a /payload/. /out/payload/캐리어를 다시 빌드하고 푸시하려면 저장소에서 다음 명령을 제공합니다.
PUSH=1 bash scripts/build-carrier.sh메모리 사용량 고려
모델 로딩과 어댑터 병합에는 많은 메모리가 필요합니다. 렌더링을 시작하기 전에 불필요한 애플리케이션을 닫으세요. 특히 Turbo 어댑터를 사용할 때 중요합니다. 저장소에 따르면 실행마다 AdaLN 테이블을 한 번 투영하고 가중치를 해제하면 측정된 경로에서 약 24GiB를 절약할 수 있습니다.
이미지-비디오 캔버스에 맞는 설정 선택
첫 이미지는 구도를 유지하도록 자동으로 잘리는 대신 늘어나므로, 대상 화면 비율에 맞게 원본 이미지를 준비하세요. 이렇게 하면 세로형, 가로형 또는 정사각형 클립을 생성할 때 원치 않는 왜곡을 방지할 수 있습니다.
대체 어댑터는 신중하게 사용
로더는 어댑터 경로와 POINTS=5를 사용해 FastH3를 읽을 수 있습니다. 예를 들어 ADAPTER=.../adapter_model.safetensors를 사용할 수 있습니다. README에 따르면 이 경로는 864x480에서 테스트되었고, 테스트 프롬프트에 76초가 걸렸으며 Turbo보다 더 복잡하게 보였습니다. 이 경로는 1344x768용으로 게시되었지만 프로젝트에서는 해당 설정을 테스트하지 않았습니다.
품질 비교를 올바르게 해석
README는 품질이 종합적으로 평가되지 않았다고 강조합니다. int8 경로는 bfloat16의 구도를 유지하면서 세부 사항을 변경할 수 있으며, 세 번의 포워드 연산을 사용하는 Turbo 렌더링은 bfloat16 Turbo 렌더링과 다를 수 있습니다. 따라서 벤치마크 표는 동일한 동작이나 오디오 품질을 보장하는 것이 아니라 측정된 속도와 일부 스틸 이미지를 비교합니다.
라이선스 및 프로젝트 상태
이 패키지에는 모델 가중치가 포함되어 있지 않습니다. MiniMax H3를 다운로드하기 전에 영토별 제외 조항을 포함한 MiniMax H3 Community License를 읽으세요. 또한 저장소의 크레딧을 검토하고, 필요에 따라 원본 MiniMax, TensorFold, MLX, H3, 어댑터 및 관련 프로젝트 작성자를 인용하세요.
여기서 사용되는 H3 제품군은 출시된 TensorFold 버전에 포함된 것이 아니라 제안된 업스트림 초안 풀 리퀘스트로 설명되어 있습니다. 따라서 설정을 재현하려면 문서에 명시된 리비전을 고정하는 것이 중요합니다.
결론
이 저장소는 호환되는 Apple Silicon Mac에서 MiniMax H3 비디오 생성을 네이티브로 실행할 수 있는 집중적인 방법을 제공합니다. 고정된 환경을 설치하고 모델을 다운로드한 후 텍스트-비디오 클립을 렌더링하고, 첫 프레임을 애니메이션으로 만들며, 빠른 Turbo 어댑터와 20단계 기본 경로 사이를 전환하고, 캔버스, 프레임 수, 시드 및 프롬프트 설정을 조정할 수 있습니다. 상당한 메모리와 저장 공간이 필요할 수 있으며, 게시된 실행 시간은 일반적인 보장이 아니라 지정된 M5 시스템에서 측정된 값으로 참고하세요.