Luisacaotica/ComfyUI-MiniMaxH3Mod

ComfyUI‑MiniMaxH3Mod – ComfyUI での MiniMax H3 のリファレンスモッドサポート

これは何か

• ビジュアルプログラミング UI ComfyUI 用の カスタムノードパック で、「RefMod」の作成、読み込み、検査、適用 のためのノードセットを追加します。これは MiniMax H3 モデル（画像、ビデオ、オーディオリファレンス）用の再利用可能なリファレンスバンドルです。
• これらのノードは MiniMax H3 を トレーニング したり、その拡散コアを置き換えたりしません。モデルの VAE で視覚/音声データをエンコードし、潜在テンソルを .safetensors ファイルに保存し、生成中にそれらの潜在変数をモデルにフィードバックするだけです。

主要な概念

概念	意味
RefMod	視覚、ビデオ、またはオーディオの潜在変数とメタデータ（トークン数、形状など）を含む .safetensors ファイル。
H3 RefMod を作成	単一の画像/ビデオ/オーディオを RefMod にエンコードします。
H3 RefMod Master を作成	視覚 と オーディオを一緒にエンコードし、単一のバンドルファイル（または 2 つの別々のファイル）を生成します。
H3 RefMod を適用	1 つ以上の読み込まれた RefMod を生成プロンプトと組み合わせ、保存された潜在変数を条件付けとして提供します。
H3 RefMods を読み込み / H3 RefMod Axis を読み込み	登録された refmods フォルダを参照し、選択したバンドルを出力する UI ウィジェット。
バンドル	複数のモダリティ（視覚 + オーディオ）をバージョン 5 形式で保持する単一の .safetensors ファイル。

主な機能（v0.2.6 時点）

• スタンドアロンクリエーター – H3 RefMod を作成 と H3 RefMod Master を作成 は、下流ノードなしで実行できます。details 文字列を返し、オプションでファイルを書き込みます。
• マスクリスト処理 – H3 RefMod マスクを収集 を使用すると、各マスクを元の解像度で保持したマスクのリストをクリエーターノードに供給できます。
• フルリファレンスビデオサンプリング – サンプリング前に因果フレーム数を指定でき、以前の 16 フレームのハードリミットを回避できます。
• コンパクトな追加型ローダー – ローダーノードは 1 つの可視スロットから始まります。+ RefMod を追加 をクリックすると、最大 8 つのスロットが表示され、各スロットに独自の すべて / 視覚 / オーディオ セレクターと強度コントロールがあります。
• 単一ファイルの視覚 + オーディオバンドル – save_layout=bundle を使用すると、Master ノードは視覚とオーディオの両方のリファレンスを含む 1 つの .safetensors ファイルを書き込みます。
• ライブラリとインスペクター UI – 保存された RefMod を検索/フィルタリングし、最初のフレームまたは完全なビデオをプレビューし、短いオーディオプレビューを聞き、トークン予算情報を確認できます。
• 予算ポリシー – truncate（デフォルト）は余分なトークンを自動的に削減します。error はトークン予算を超えると中止します。視覚用の max_tokens、オーディオ用の audio_max_tokens、および全体的な max_total_tokens 制限が別々にあります。
• RefMod を更新 – ComfyUI モデルリスト全体をリセットせずに、ファイルシステムからドロップダウンリストを更新します。
• クロスプラットフォームサポート – Windows と Apple Silicon（M5 Ultra、macOS 27、PyTorch 2.14）でテスト済み。オプションのビデオバックエンド（opencv-python、imageio）。

インストール

# 1️⃣ ComfyUI の custom_nodes フォルダにクローンします
 git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod \
    custom_nodes/ComfyUI-MiniMaxH3Mod
# 2️⃣ ComfyUI を再起動します（またはカスタムノードを再読み込みします）
# 3️⃣ 依存関係は ComfyUI‑Manager によって自動的にインストールされるか、次を実行します：
pip install -r custom_nodes/ComfyUI-MiniMaxH3Mod/requirements.txt

このパックには、MiniMax H3 をすでにサポートしている動作する ComfyUI インストール（つまり、ネイティブの H3 VAE と条件付けノード）が必要です。追加の MiniMax‑H3 コードはバンドルされていません。このモッドは既存の VAE とのみ通信します。

典型的なワークフロー

1. リファレンスを作成 – 画像、短いビデオ、またはオーディオクリップを H3 RefMod を作成（または Master）ノードにドロップします。max_tokens、budget_policy、mask/mask_list などを調整します。実行 を押すと、登録された refmods フォルダに .safetensors ファイルが表示されます。
2. リファレンスを読み込む – H3 RefMods を読み込み（または Axis バリアント）を使用して、保存されたファイルを選択します。複数のスロットを一度に読み込み、スロットごとの強度を設定できます。
3. 生成中に適用 – ローダー出力を H3 RefMod を適用 に接続し、結果の条件付けを通常の MiniMax H3 生成パイプライン（例：サンプラーノード）に供給します。モデルはテキストプロンプトとともに保存された潜在変数に注意を向けます。
4. 検査 / 調整 – H3 RefMod を検査 を開いてトークン数を表示し、保存された視覚/オーディオをプレビューし、再実行する前に強度を調整します。

制限と既知の問題

• 音声クローニングは機能しません – オーディオ抽出は機能しますが、現在の実装では話者のアイデンティティを確実に転送できません。
• トレーニングなし – 「トレーニング」ビジュアルモード（training / Compressed Reference）は、潜在プーリング + オプションのリファインメントステップにすぎません。LoRA やその他のモデルを トレーニングしません。
• トークン予算は厳格です – max_tokens（視覚）または audio_max_tokens を超えると、truncate を選択しない限り中止されます。予算は品質を保証しません。注意力コストを制限するだけです。
• 音声と視覚の同期は保証されません – バンドルは視覚とオーディオの潜在変数を別々に保存します。ソースファイルが提供する以上に時間的に整列されていません。
• ファイルシステムのみの永続化 – RefMod はディスク上の .safetensors として保存されます。ノードパックによってバージョン管理されません。
• プラットフォームの癖 – 主に Windows でテストされています。Apple Silicon サポートは存在しますが、すべてのワークフローをカバーしているとは限りません。

開始場所

• リポジトリにはデモバンドルが同梱されています：mods/vanellope_example.safetensors。インストール後、ローダードロップダウンに vanellope_example として表示されます。強度 1.0 で H3 RefMod を適用 に接続し、“a candy racer in a karting scene” のようなプロンプトを試してください。

さらに読む

• 完全な変更ログ：CHANGELOG.md
• 検証と既知の制限：REVIEW_FOLLOWUP.md
• バンドルファイル形式の詳細：BUNDLE_FORMAT.md

---

ComfyUI‑MiniMaxH3Mod は、MiniMax H3 用の ストレージと条件付けに焦点を当てた 拡張機能です。アーティストが視覚/音声リファレンスを一度キャプチャし、モデルを再トレーニングすることなく、後の生成で効率的に再利用できるようにします。