このプロジェクトの概要
このリポジトリは、Apple Silicon上のTensorFold向けにMiniMax H3動画モデルをパッケージ化したものです。TensorFoldのH3ファミリーに、MLX int8 MetalカーネルとLightX2V Turboアダプターを組み合わせ、ステレオ音声と同期した動画を生成します。
このパックはテキストから動画への生成に対応し、バージョン1.1以降は、指定した最初のフレームを使った画像から動画への生成にも対応しています。256 GBメモリのMac Studio M5 Ultraで測定した場合、Turboアダプターを使うと5秒間の864x480クリップは約50秒で生成できます。文書化されたベンチマーク条件では、768x448クリップは約40秒かかります。
このリポジトリはサーバーや製品ではなく、開発用のレンダリング経路です。tensorfold generateコマンドはありません。付属スクリプトを通じて、レンダリングごとにモデルが読み込まれます。
主な機能
- テキストから動画: シーンを説明し、動画とステレオ音声を含むMP4を生成します。
- 画像から動画: 最初のフレームを指定し、その後に起こることを説明します。
- Turbo生成: LightX2Vアダプターにより、文書化された高速パスではレンダリングを3回のフォワード処理に短縮します。
- MLXおよびint8カーネル: 互換性のあるM5テンソルハードウェアでは、Transformerとデコーダーの一部の処理にint8 Metalカーネルを使用します。
- 再現可能なセットアップ: インストーラーはTensorFold、MLX、サポートライブラリ、モデルリビジョン、アダプターのチェックサムを固定します。
- ベースモデルの任意レンダリング: ベースモデルに近いレンダリングが必要な場合はアダプターを無効にし、約20サンプリングステップを使用できます。
ハードウェアとソフトウェアの要件
公開されている性能数値は、256 GBのユニファイドメモリを搭載し、macOS 27.0.1を実行する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パスでは、3回のフォワードパスを使用します。アダプターを無効にして20ステップのレンダリングを行うには、ADAPTER=none と POINTS=21 を設定します。
ADAPTER=none POINTS=21 bash scripts/generate.sh "A lantern glowing beside a forest path" base-model.mp4READMEでは、この設定はベースモデルに近い結果になると説明されています。一方、Turboは短時間で鮮明なフレームを生成できますが、人物が重複することがあります。同じシードを使っても、2つのモードで構図が異なる場合があります。
速度のトレードオフを理解する
最大の高速化は、20回ではなく3回のフォワードパスで実行するTurboアダプターによって得られます。int8 SwiGLU MLP、int8 QKV演算、アテンション出力、ビデオデコーダーのカーネルも、対応するM5テンソルハードウェアでは追加の高速化をもたらします。
記載された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テーブルを実行ごとに一度だけ射影し、重みを解放することで約24 GiBを節約できます。
画像から動画へのキャンバスを適切に選ぶ
最初の画像は構図を保つために自動的にクロップされるのではなく、引き伸ばされます。そのため、対象のアスペクト比に合わせて元画像を準備してください。これにより、縦長、横長、正方形のクリップを生成する際の不要な歪みを避けられます。
代替アダプターは慎重に使用する
ローダーはアダプターパスと POINTS=5 を指定してFastH3を読み込めます。たとえば ADAPTER=.../adapter_model.safetensors を使用します。READMEによると、このパスは864x480でテストされ、テストプロンプトでは76秒かかり、Turboよりも動きが多く見えました。1344x768向けに公開されていますが、プロジェクトではテストされていません。
品質比較を正しく解釈する
READMEでは、品質を包括的には評価していないことが強調されています。int8パスではbfloat16の構図を維持しながら細部が変わることがあり、3回のフォワードパスによるTurboレンダリングはbfloat16 Turboレンダリングと異なる場合があります。そのため、ベンチマーク表は測定した速度と一部の静止画を比較するものであり、動きや音声の品質が完全に同一になることを保証するものではありません。
ライセンスとプロジェクトの状況
このパックにはモデルの重みは含まれていません。MiniMax H3をダウンロードする前に、地域による除外事項を含むMiniMax H3 Community Licenseを確認してください。また、リポジトリのクレジットを確認し、必要に応じて元のMiniMax、TensorFold、MLX、H3、アダプター、および関連プロジェクトの作者を引用してください。
ここで使用されているH3ファミリーは、リリース済みのTensorFoldバージョンの一部ではなく、上流に提案されたドラフトのプルリクエストとして説明されています。そのため、セットアップを再現するには、記載されたリビジョンを固定することが重要です。
まとめ
このリポジトリを使うと、互換性のあるApple Silicon Mac上でMiniMax H3による動画生成をネイティブに実行できます。固定された環境をインストールしてモデルをダウンロードすれば、テキストから動画へのクリップをレンダリングしたり、初期フレームをアニメーション化したり、高速なTurboアダプターと20ステップのベースパスを切り替えたり、キャンバス、フレーム数、シード、プロンプトの設定を調整したりできます。メモリとストレージにはかなりの容量が必要になるため、公開されている処理時間は指定されたM5システムでの測定値であり、一般的な保証ではないことに注意してください。