Musubi Tuner

English | 日本語

目次

クリックすると展開します

• はじめに
  • スポンサー
  • スポンサー募集のお知らせ
  • 最近の更新
  • リリースについて
  • AIコーディングエージェントを使用する開発者の方へ
• 概要
  • ハードウェア要件
  • 特徴
  • ドキュメント
• インストール
  • pipによるインストール
  • uvによるインストール
  • Linux/MacOS
  • Windows
• モデルのダウンロード
• 使い方
  • データセット設定
  • 事前キャッシュと学習
  • Accelerateの設定
  • 学習と推論
• その他
  • SageAttentionのインストール方法
  • PyTorchのバージョンについて
• 免責事項
• コントリビューションについて
• ライセンス

はじめに

このリポジトリは、HunyuanVideo、Wan2.1/2.2、FramePack、FLUX.1 Kontext、FLUX.2 dev/klein、Qwen-Image、Z-ImageのLoRA学習用のコマンドラインツールです。このリポジトリは非公式であり、それらの公式リポジトリとは関係ありません。

リポジトリは開発中です。

スポンサー

このプロジェクトを支援してくださる企業・団体の皆様に深く感謝いたします。

スポンサー募集のお知らせ

このプロジェクトがお役に立ったなら、ご支援いただけると嬉しく思います。 GitHub Sponsorsで受け付けています。

最近の更新

GitHub Discussionsを有効にしました。コミュニティのQ&A、知識共有、技術情報の交換などにご利用ください。バグ報告や機能リクエストにはIssuesを、質問や経験の共有にはDiscussionsをご利用ください。Discussionはこちら

• 2026/06/24

  • Krea 2に実験的に対応しました（LoRA学習、推論）。PR #980
    • 詳細はドキュメントを参照してください。

• 2026/06/19

  • Ideogram4に実験的に対応しました（LoRA学習、推論）。PR #966 について、sdbds氏に深く感謝します。フォローアップは PR #975 および PR #977 で行われました。変更内容の詳細を確認されたい場合はPRをご覧ください。
    • 詳細はドキュメントを参照してください。
    • JSON形式のプロンプトが推奨されますが、自然言語での学習も可能なようです。
    • 学習設定の詳細は不明なためコミュニティからの情報共有を歓迎します。

• 2026/06/16

  • LoRA（LoHa/LoKr）学習向けに最適化したブロックスワップモード「H2D-only block swap」を追加しました。全アーキテクチャで利用できます。--block_swap_h2d_only で有効化します。PR #972
    • ベース凍結の学習ではCPUとGPU上のベース重みが同一のため、従来のブロックスワップにおけるdevice→host（D2H）コピーは完全に無駄になります。H2DのみのモードはCPUに恒久的なマスターコピーを保持し、常にhost→deviceのみを転送することで、D2H転送を完全に排除します。これにより学習スループットが向上することがあり、--fp8_base / --fp8_scaled 使用時に効果が最も大きくなります。
    • --gradient_checkpointing が必須です。ストリーミングに使うGPUリングバッファの数は --block_swap_ring_size で調整できます（デフォルト 2、1 でVRAM最小）。
    • ブロックスワップの全オプションをまとめたブロックスワップのドキュメントも新設しました。

• 2026/06/13

  • ネットワーク重みの保存精度を指定する --save_precision オプションを追加し、デフォルトの保存精度をfp32に変更しました。PR #967 rockerBOO氏に感謝します。
    • 破壊的変更：LoRAファイルの保存精度のデフォルトがfp32に変更されました。
    • 学習中のLoRA重みの精度を保って保存するための変更です。post-hoc EMA、マージ、抽出、重み解析などの後処理で有用です。
    • --mixed_precision bf16(fp16) で学習している場合、LoRAファイルのサイズが従来のおよそ2倍になることがあります。従来と同じ挙動にしたい場合は --save_precision bf16 （あるいはfp16）を指定してください。
    • 詳細はHunyuanVideoのドキュメントを参照してください。

• 2026/06/08

  • HiDream-O1-Imageに実験的に対応しました（LoRA学習、fine-tuning、推論）。PR #964
    • 詳細はドキュメントを参照してください。
    • オプションでDINOv3による補助的な知覚損失（perceptual loss）も利用できます。advanced configのドキュメントを参照してください。
    • この対応のベースとなったPR #947（および続くPR #955）について、sdbds氏に深く感謝します。変更内容の詳細を確認されたい場合はPRをご覧ください。

• 2026/05/22

  • コードベースの大規模な内部リファクタリングを行い、コードベースの品質と保守性を向上させました。PR #950
    • ユーザーの方には直接の影響がないよう配慮しました。詳細について、および不具合報告などはこちらのdiscussionまでお願いします。

リリースについて

Musubi Tunerの解説記事執筆や、関連ツールの開発に取り組んでくださる方々に感謝いたします。このプロジェクトは開発中のため、互換性のない変更や機能追加が起きる可能性があります。想定外の互換性問題を避けるため、参照用としてリリースをお使いください。

最新のリリースとバージョン履歴はリリースページで確認できます。

AIコーディングエージェントを使用する開発者の方へ

このリポジトリでは、ClaudeやGeminiのようなAIエージェントが、プロジェクトの概要や構造を理解しやすくするためのエージェント向け文書（プロンプト）を用意しています。

これらを使用するためには、プロジェクトのルートディレクトリに各エージェント向けの設定ファイルを作成し、明示的に読み込む必要があります。

セットアップ手順:

1. プロジェクトのルートに CLAUDE.md や GEMINI.md、AGENTS.md ファイルを作成します。

2. CLAUDE.md 等に以下の行を追加して、リポジトリが推奨するプロンプトをインポートします（現在、両者はほぼ同じ内容です）：

   markdown @./.ai/claude.prompt.md

   Geminiの場合はこちらです：

   markdown @./.ai/gemini.prompt.md

   他のエージェント向けの設定ファイルでもそれぞれの方法でインポートしてください。

3. インポートした行の後に、必要な指示を適宜追加してください（例：Always respond in Japanese.）。

このアプローチにより、共有されたプロジェクトのコンテキストを活用しつつ、エージェントに与える指示を各ユーザーが自由に制御できます。CLAUDE.md、GEMINI.md および AGENTS.md （またClaude用の .mcp.json）はすでに .gitignore に記載されているため、リポジトリにコミットされることはありません。

概要

ハードウェア要件

• VRAM: 静止画での学習は12GB以上推奨、動画での学習は24GB以上推奨。
  • アーキテクチャ、解像度等の学習設定により異なります。12GBでは解像度 960x544 以下とし、--blocks_to_swap、--fp8_llm等の省メモリオプションを使用してください。
• メインメモリ: 64GB以上を推奨、32GB+スワップで動作するかもしれませんが、未検証です。

特徴

• 省メモリに特化
• Windows対応（Linuxでの動作報告もあります）
• マルチGPU学習（Accelerateを使用）、ドキュメントは後日追加予定

ドキュメント

各アーキテクチャの詳細、設定、高度な機能については、以下のドキュメントを参照してください。

アーキテクチャ別: - HunyuanVideo - Wan2.1/2.2 - Wan2.1/2.2 (1フレーム推論) - FramePack - FramePack (1フレーム推論) - FLUX.1 Kontext - Qwen-Image - Z-Image - HiDream-O1-Image - HunyuanVideo 1.5 - Kandinsky 5 - FLUX.2

共通設定・その他: - データセット設定 - 高度な設定 - 学習中のサンプル生成 - ブロックスワップ（省メモリのためのCPUオフロード） - ツールとユーティリティ - torch.compileの使用方法

インストール

pipによるインストール

Python 3.10以上を使用してください（3.10で動作確認済み）。

適当な仮想環境を作成し、ご利用のCUDAバージョンに合わせたPyTorchとtorchvisionをインストールしてください。

PyTorchはバージョン2.5.1以上を使用してください（補足）。

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

以下のコマンドを使用して、必要な依存関係をインストールします。

pip install -e .

オプションとして、FlashAttention、SageAttention（推論にのみ使用できます、インストール方法はこちらを参照）を使用できます。

また、ascii-magic（データセットの確認に使用）、matplotlib（timestepsの可視化に使用）、tensorboard（学習ログの記録に使用）、prompt-toolkitを必要に応じてインストールしてください。

prompt-toolkitをインストールするとWan2.1およびFramePackのinteractive modeでの編集に、自動的に使用されます。特にLinux環境でプロンプトの編集が容易になります。

pip install ascii-magic matplotlib tensorboard prompt-toolkit

uvによるインストール

uvを使用してインストールすることもできますが、uvによるインストールは試験的なものです。フィードバックを歓迎します。

Linux/MacOS

curl -LsSf https://astral.sh/uv/install.sh | sh

表示される指示に従い、pathを設定してください。

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

表示される指示に従い、PATHを設定するか、この時点でシステムを再起動してください。

モデルのダウンロード

モデルのダウンロード手順はアーキテクチャによって異なります。詳細はドキュメントセクションにある、各アーキテクチャのドキュメントを参照してください。

使い方

データセット設定

こちらを参照してください。

事前キャッシュ

事前キャッシュの手順の詳細は、ドキュメントセクションにある各アーキテクチャのドキュメントを参照してください。

Accelerateの設定

accelerate configを実行して、Accelerateの設定を行います。それぞれの質問に、環境に応じた適切な値を選択してください（値を直接入力するか、矢印キーとエンターで選択、大文字がデフォルトなので、デフォルト値でよい場合は何も入力せずエンター）。GPU 1台での学習の場合、以下のように答えてください。

- In which compute environment are you running?: This machine
- Which type of machine are you using?: No distributed training
- Do you want to run your training on CPU only (even if a GPU / Apple Silicon / Ascend NPU device is available)?[yes/NO]: NO
- Do you wish to optimize your script with torch dynamo?[yes/NO]: NO
- Do you want to use DeepSpeed? [yes/NO]: NO
- What GPU(s) (by id) should be used for training on this machine as a comma-seperated list? [all]: all
- Would you like to enable numa efficiency? (Currently only supported on NVIDIA hardware). [yes/NO]: NO
- Do you wish to use mixed precision?: bf16

※場合によって ValueError: fp16 mixed precision requires a GPU というエラーが出ることがあるようです。この場合、6番目の質問（ What GPU(s) (by id) should be used for training on this machine as a comma-separated list? [all]:）に「0」と答えてください。（id 0、つまり1台目のGPUが使われます。）

学習と推論

学習と推論の手順はアーキテクチャによって大きく異なります。詳細な手順については、ドキュメントセクションにある対応するアーキテクチャのドキュメント、および各種の設定のドキュメントを参照してください。

その他

SageAttentionのインストール方法

sdbds氏によるWindows対応のSageAttentionのwheelが https://github.com/sdbds/SageAttention-for-windows で公開されています。triton をインストールし、Python、PyTorch、CUDAのバージョンが一致する場合は、Releasesからビルド済みwheelをダウンロードしてインストールすることが可能です。sdbds氏に感謝します。

参考までに、以下は、SageAttentionをビルドしインストールするための簡単な手順です。Microsoft Visual C++ 再頒布可能パッケージを最新にする必要があるかもしれません。

1. Pythonのバージョンに応じたtriton 3.1.0のwhellをこちらからダウンロードしてインストールします。

2. Microsoft Visual Studio 2022かBuild Tools for Visual Studio 2022を、C++のビルドができるよう設定し、インストールします。（上のRedditの投稿を参照してください）。

3. 任意のフォルダにSageAttentionのリポジトリをクローンします。 shell git clone https://github.com/thu-ml/SageAttention.git

4. スタートメニューから Visual Studio 2022 内の x64 Native Tools Command Prompt for VS 2022 を選択してコマンドプロンプトを開きます。

5. venvを有効にし、SageAttentionのフォルダに移動して以下のコマンドを実行します。DISTUTILSが設定されていない、のようなエラーが出た場合は set DISTUTILS_USE_SDK=1としてから再度実行してください。 shell python setup.py install

以上でSageAttentionのインストールが完了です。

PyTorchのバージョンについて

--attn_modeにtorchを指定する場合、2.5.1以降のPyTorchを使用してください（それより前のバージョンでは生成される動画が真っ黒になるようです）。

古いバージョンを使う場合、xformersやSageAttentionを使用してください。

免責事項

このリポジトリは非公式であり、サポートされているアーキテクチャの公式リポジトリとは関係ありません。また、このリポジトリは開発中で、実験的なものです。テストおよびフィードバックを歓迎しますが、以下の点にご注意ください：

• 実際の稼働環境での動作を意図したものではありません
• 機能やAPIは予告なく変更されることがあります
• いくつもの機能が未検証です
• 動画学習機能はまだ開発中です

問題やバグについては、以下の情報とともにIssueを作成してください：

• 問題の詳細な説明
• 再現手順
• 環境の詳細（OS、GPU、VRAM、Pythonバージョンなど）
• 関連するエラーメッセージやログ

コントリビューションについて

コントリビューションを歓迎します。 CONTRIBUTING.mdおよびCONTRIBUTING.ja.mdをご覧ください。

ライセンス

hunyuan_modelディレクトリ以下のコードは、HunyuanVideoのコードを一部改変して使用しているため、そちらのライセンスに従います。

wanディレクトリ以下のコードは、Wan2.1のコードを一部改変して使用しています。ライセンスはApache License 2.0です。

frame_packディレクトリ以下のコードは、frame_packのコードを一部改変して使用しています。ライセンスはApache License 2.0です。

他のコードはApache License 2.0に従います。一部Diffusersのコードをコピー、改変して使用しています。