English | 日本語

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

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

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

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

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

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

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

• 2024/10/26

  • Qwen-Imageの学習で、バッチサイズが2以上で、--split_attnが指定されていない場合に、Attentionの計算が正しく行われない不具合を修正しました。PR #688
  • Wan、FramePack、Qwen-Imageの学習・推論スクリプトに--disable_numpy_memmapオプションを追加しました。PR #681 および PR #687。FurkanGozukara氏に感謝します。
    • このオプションを指定すると、モデルの読み込み時にnumpyのメモリマッピングを無効にします。一部の環境（RunPodなど）でモデル読み込みが高速化される可能性があります。ただし、RAM使用量が増加します。

• 2024/10/25

  • 制御画像を持つ画像データセットで、対象画像と制御画像の組み合わせが正しく読み込まれない不具合を修正しました。PR #684
    • 制御画像を持つ画像データセットをご利用の場合、latentキャッシュの再作成を行ってください。
    • 先頭のマッチだけで判断していたため、対象画像がa.png、ab.pngで、制御画像がa_1.png、ab_1.pngのとき、a.pngには、a_1.pngとab_1.pngが組み合わされてしまっていました。

• 2024/10/13

  • Qwen-Image-Edit、2509の推論スクリプトで、ピクセル単位での生成画像の一貫性を向上するReference Consistency Mask (RCM)機能を追加しました。[PR #643] (https://github.com/kohya-ss/musubi-tuner/pull/643)
    • RCMは、生成画像が制御画像と比較してわずかな位置ずれを起こす問題を解決します。詳細はQwen-Imageのドキュメントを参照してください。
  • あわせて同PRにて --resize_control_to_image_size オプションが指定されていない場合でも、コントロール画像が出力画像と同じサイズにリサイズされてしまう不具合を修正しました。生成画像が変化する可能性がありますので、オプションを確認してください。
  • FramePackの1フレーム推論で、--one_frame_auto_resizeオプションを追加しました。PR #646
    • 生成画像の解像度を自動的に調整します。--one_frame_inferenceを指定した場合にのみ有効です。詳細はFramePackの1フレーム推論のドキュメントを参照してください。

• 2024/10/05

  • エポックの切替をcollate_fnからDataLoaderの取得ループ開始前に変更しました。PR #601

  • これまでの実装ではエポックの最初のデータ取得後に、ARBバケットがシャッフルされます。そのため、エポックの最初のデータは前エポックのARBソート順で取得されます。これによりエポック内でデータの重複や欠落が起きていました。

  • 各DataSetでは__getitem__で共有エポックの変化を検知した直後にARBバケットをシャッフルします。これにより先頭サンプルから新しい順序で取得され、重複・欠落は解消されます。

  • シャッフルタイミングが前倒しになったため、同一シードでも旧実装と同一のサンプル順序にはなりません

  • 学習全体への影響

    • この修正はエポック境界における先頭サンプルの取り違いを解消するものです。複数エポックで見れば、各サンプルは最終的に欠落・重複なく使用されるため、学習全体に与える影響は軽微です。変更点は「エポック内の消費順序の整合性」を高めるものであり、長期的な学習挙動は同条件では実質的に変わりません（※極端に少ないエポック数や早期打ち切りの場合は順序による差異が観測される可能性があります）。

  • 高度な設定のドキュメントに、学習時のオプションを設定ファイルで指定する方法を追加しました。PR #630

  • ドキュメント構成を整理しました。データセット設定に関するドキュメントをdocs/dataset_config.mdに移動しました。

• 2024/10/03

  • 各学習スクリプトで用いられているblock swap機構を改善し、Windows環境における共有GPUメモリの使用量を大きく削減しました。PR #585
    • block swapのoffload先を共有GPUメモリからCPUメモリに変更しました。これによりトータルでのメモリ使用量は変わりませんが、共有GPUメモリの使用量が大幅に削減されます。
    • たとえば32GBのメインメモリでは、offloadできるのは16GBまででしたが、今回の変更により「32GB-他の使用量」までoffloadできるようになります。
    • 学習速度はわずかに低下します。技術的詳細はPR #585を参照してください。

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

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

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

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

セットアップ手順:

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

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

   @./.ai/claude.prompt.md
   

   Geminiの場合はこちらです：

   @./.ai/gemini.prompt.md
   

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

このアプローチにより、共有されたプロジェクトのコンテキストを活用しつつ、エージェントに与える指示を各ユーザーが自由に制御できます。CLAUDE.md と GEMINI.md はすでに .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

共通設定・その他:

• データセット設定
• 高度な設定
• 学習中のサンプル生成
• ツールとユーティリティ

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によるインストールは試験的なものです。フィードバックを歓迎します。

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

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

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

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

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

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

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

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が使われます。）

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

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のリポジトリをクローンします。

   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としてから再度実行してください。

   python setup.py install
   

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

--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のコードをコピー、改変して使用しています。