0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Minimax H3のTeacher matchingのjsonl

0
Last updated at Posted at 2026-10-05

musubi-tunerのMinimax H3のLoRA学習でTeacher matchingなる学習方法がある。
documentには以下のように書かれている。

image.png

以下のこの記事内ではjsonlの書き方をやや簡略化して示している。jsonlの正確な書き方はdocument本文を参考ください。

0.本来

恐らく作者(kohya氏)が想定しているjsonlの感じは共通の参照画像を与え、学習画像データをtargetにするものと思われる。
(参照画像が前景(front.png)という設定画っぽい名前だし、学習画像フォルダと別フォルダにある)
image.png

image_path:"./img01.jpg", ref:"./common_ref.jpg"
image_path:"./img02.jpg", ref:"./common_ref.jpg"
image_path:"./img03.jpg", ref:"./common_ref.jpg"
...
image_path:"./img20.jpg", ref:"./common_ref.jpg"

この学習の場合、結局の学習結果はref2vaモデルに"./common_ref.jpg"を渡した結果を(参照画像無しで)再現する学習しているのと大差ないのではと思った。
もしそうなら、わざわざ300MBのLoRAを学習して読み込むのより、common_ref.jpgを読み込ませたref2vaの方がずっと手軽である。

さて、ここで別パターンの参照画像の渡し方を考えてみよう。

1.自己参照

一番簡単に思いつくパターンは学習データと同じ参照を与える場合である。
無論、documentには「subject-reference teacher に使う場合、参照は同じ被写体の別の写真にしてください。」という注意文から考えるに作者はこれを推奨していない。

image_path:"./img01.jpg", ref:"./img01.jpg"
image_path:"./img02.jpg", ref:"./img02.jpg"
image_path:"./img03.jpg", ref:"./img03.jpg"
...
image_path:"./img20.jpg", ref:"./img20.jpg"

2.ずらし参照

学習画像と参照画像のパスをずらし、必ず異なるデータを参照に取る。

この手法の欠点は必ずしも参照画像領域>学習画像領域とならない点である。
例えば参照画像が胸から上しか映っていなく、学習画像が全身画像の場合、参照画像に映ってない下半身をLoRAは学習する必要がある。

image_path:"./img01.jpg", ref:"./img02.jpg"
image_path:"./img02.jpg", ref:"./img03.jpg"
image_path:"./img03.jpg", ref:"./img04.jpg"
...
image_path:"./img19.jpg", ref:"./img20.jpg"
image_path:"./img20.jpg", ref:"./img01.jpg"

3.ランダムシャッフル参照

意味的には2.と同じであるが参照画像をランダムでシャッフルする。
学習画像の並びに偏りがある場合、偏りを軽減できるが、シャッフル後に参照画像が自己参照にならないよう少し留意しないといけない。

image_path:"./img01.jpg", ref:"./img14.jpg"
image_path:"./img02.jpg", ref:"./img07.jpg"
image_path:"./img03.jpg", ref:"./img19.jpg"
...
image_path:"./img20.jpg", ref:"./img04.jpg"

4.複数対応

参照画像は9枚まで渡せられるので、一枚だけではなく複数枚渡す。
複数枚渡すことで参照画像が胸像や顔のアップしかない場合の情報不足を低減できる。

欠点は参照画像上限が9枚であることである。(すべての学習画像を含む20枚参照とかはできない)

image_path:"./img01.jpg", ref:["./img14.jpg", "./img10.jpg", "./img08.jpg"]
image_path:"./img02.jpg", ref:["./img07.jpg", "./img13.jpg", "./img17.jpg"]
image_path:"./img03.jpg", ref:["./img19.jpg", "./img07.jpg", "./img11.jpg"]
...
image_path:"./img20.jpg", ref:["./img04.jpg", "./img09.jpg", "./img15.jpg"]

5.複数対応2

一つの画像に対して一枚の異なる参照画像を何度か指定する。
先にいうとひとつの学習画像に対して一通りしか書くことが出来ないので、このjsonlは動かない。
(多分キャッシュファイル名が重複する)

image_path:"./img01.jpg", ref:"./img14.jpg"
image_path:"./img02.jpg", ref:"./img07.jpg"
image_path:"./img03.jpg", ref:"./img19.jpg"
...
image_path:"./img20.jpg", ref:"./img04.jpg"

image_path:"./img01.jpg", ref:"./img10.jpg"
image_path:"./img02.jpg", ref:"./img13.jpg"
image_path:"./img03.jpg", ref:"./img07.jpg"
...
image_path:"./img20.jpg", ref:"./img09.jpg"

すなわち、動くようにするにはこんな感じでcopyファイルを生成すれば、同一対象画像の別参照画像の場合の画像学習が出来る。しかし、copyファイルを作成・管理するのが面倒である。

image_path:"./img01.jpg", ref:"./img14.jpg"
image_path:"./img02.jpg", ref:"./img07.jpg"
image_path:"./img03.jpg", ref:"./img19.jpg"
...
image_path:"./img20.jpg", ref:"./img04.jpg"

image_path:"./copy_img01.jpg", ref:"./copy_img10.jpg"
image_path:"./copy_img02.jpg", ref:"./copy_img13.jpg"
image_path:"./copy_img03.jpg", ref:"./copy_img07.jpg"
...
image_path:"./copy_img20.jpg", ref:"./copy_img09.jpg"

6.全パターン

学習画像20枚なら20x19=380通り全組み合わせをCacheする。
このような書き方(image_pathが被る)は現行出来ないし、無駄も多いのだが、参照画像は9枚という制限を取り払えるというメリットはある。
1epochが限りなく大きくなるが、epochではなくstepで学習期間を指定するなら問題はない。しかし、学習stepが500stepの場合、各cacheは1,2回しか使用されないので正直こんなに必要ない。あくまで例として挙げる。

image_path:"./img01.jpg", ref:"./img02.jpg"
image_path:"./img01.jpg", ref:"./img03.jpg"
image_path:"./img01.jpg", ref:"./img04.jpg"
...
image_path:"./img01.jpg", ref:"./img20.jpg"
...
image_path:"./img20.jpg", ref:"./img01.jpg"
image_path:"./img20.jpg", ref:"./img02.jpg"
image_path:"./img20.jpg", ref:"./img03.jpg"
...
image_path:"./img20.jpg", ref:"./img19.jpg"

7.複数画像を結合して一枚の画像に

参照画像9枚という制限を緩和するために複数画像を結合して一枚の画像に結合することによって上限を緩和できるかもしれない。例えば画像4枚ずつ結合すれば合計36枚まで参照に出来る。アイデアのみ。

8.複数画像をvideo化

参照画像が同じアスペクト比なら画像スライドショーをvideo化することで参照画像9枚という制限を突破できるかもしれない。ただ参照動画のTextEncoderに入るのは2fpsだった気がするので5sの動画だと10枚程度なので、あまり入れられる枚数は変わらない。アイデアのみ。

テスト

上記のjsonlでsubject-refのTeacher matchingのLoRA学習を試した結果を記す。
設定はSubject-reference teacherの値(--learning_rate 3e-4 --max_train_steps 500 他)。
学習画像は28枚であった。

・0.本来
共通参照の選定方法が分からないので試してない。
・1.自己参照
lossが非常に大きくて最初から最後まであまりlossが下がらなかった。キャラクター性の学習は一番良かったが、反面スタイルの劣化がひどく使い物にならない。
・2.ずらし参照
・3.ランダムシャッフル参照
lossはまあまあ、キャラクター性の学習もまあまあ。スタイルの劣化も酷くはない。
2と3は傾向として同程度だった。
・4.複数対応
試した中だとlossは一番小さく、loss推移も他と比較して安定した。キャラクター性の学習は2.3.と同程度。スタイルの劣化も酷くはない。自身と違う参照画像をランダムに3枚渡した場合。
・5.複数対応2
一つの画像を複数行記述した場合、エラーが出たので試さなかった。
・6.7.8.
試してない。

設定ミス、補足

--lr_warmup_steps 50は--lr_scheduler constant_with_warmupがなかったせいかエラー出たので実験では外した。
lossの大きさと学習勾配の大きさが比例するなら、lossが大きい(1.自己参照)なら学習率を下げ、lossが小さい(4.複数対応)なら大きな学習率を設定するべきだったのかもしれない。
また、documentではcaptionで容姿の特徴を書かないよう言われてたが普通に記述して学習していた。(トリガーワードのみで外見は書かない)。

そして、Teacher matchingのLoRAを適用して推論時にpromptに容姿の特徴を含む場合は、結果はそこそこ良かった(一方で完璧ではないし通常LoRA(Guidance loss使用時)との差も良く分からない)。
この推論時にpromptから容姿の特徴を除くと面影が残る程度であった。髪型や服装の一部は似ているが、キャラクター性は学習出来てない。容姿の特徴を除いたpromptでは・1.自己参照でのLoRA強度が通常LoRA(Guidance loss使用時)よりも強くはあったが。

追加で・4.複数対応の--max_train_steps 500を--max_train_steps 1500をした結果も見たが、容姿の特徴を含めたpromptで生成した時は500の時と差は正直それほど分からなかった。
容姿の特徴を除いたpromptで生成した時は途中の500,800,1100,1300,1500を見た。
1300stepのLoRA強度が一番強く、500stepより強い面影が観測できたものの、トリガーワードのみで完全に容姿を再現できたわけではない。
あとstepごとにLoRA強度のバラツキが大きいように感じた(epoch(28毎)と保存step(100毎)の区切りが違うから?)。

容姿の特徴を除いたprompt時のキャラクター性の強さ:
・1.自己参照の500step>・4.複数対応の1300step>通常LoRA(Guidance loss使用時)≃・4.複数対応の500step
(通常LoRAの終了epochはpromptに容姿の特徴を含む場合でキャラクター性を再現出来るくらいで決めている)

jsonl作成コード

jsonlを作るコードはchatgptに頼めば作ってくれる。自分が使ったコードを参考までに載せておく。ただ、jsonl内の指定pathはjsonlファイルからの相対pathになるのでちょっと注意する。

import argparse
import json
import random
from pathlib import Path


IMAGE_EXTENSIONS = {
    ".jpg",
    ".jpeg",
    ".png",
    ".webp",
    ".bmp",
}


def make_json_path(path):
    """
    JSONL用の相対パスに変換する。

    - Windowsでも / 区切りに統一
    - 先頭に ./ を付ける
    """
    return "./" + path.as_posix().lstrip("./")


def make_slide_references(images):
    """
    slide:
        image1 -> image2
        image2 -> image3
        ...
        imageN -> image1
    """
    n = len(images)

    return {
        image: [images[(i + 1) % n]]
        for i, image in enumerate(images)
    }


def make_random_sample_references(images):
    """
    random_sample:

    各targetにreferenceを1枚割り当てる。
    ただし、
      - 自分自身はreferenceにしない
      - 全画像がreferenceとして1回ずつ使われる
    ことを保証する。

    これはランダムなderangement(完全順列)を作っている。
    """

    n = len(images)

    while True:
        refs = images.copy()
        random.shuffle(refs)

        # 自己参照がないか確認
        if all(
            target != ref
            for target, ref in zip(images, refs)
        ):
            return {
                target: [ref]
                for target, ref in zip(images, refs)
            }


def make_multi_ref3_references(images):
    """
    multi_ref3:

    各targetに、自分自身以外の
    ランダムな3枚をreferenceとして付ける。

    referenceとしての登場回数は
    完全には均等にならない。
    """

    n = len(images)

    if n < 4:
        raise ValueError(
            "multi_ref3には最低4枚の画像が必要です。"
        )

    return {
        image: random.sample(
            [p for p in images if p != image],
            3,
        )
        for image in images
    }


def make_multi_target3_references(images):
    """
    multi_target3:

    random_sampleを3回独立して作る。

    各roundでは
      - 自分自身をreferenceにしない
      - 各画像がreferenceとして1回ずつ登場

    したがって全体では各画像が
    referenceとして3回ずつ登場する。

    同じtargetに同じreferenceが複数回
    選ばれる可能性がある。
    """

    result = {
        image: []
        for image in images
    }

    for _ in range(3):

        refs = make_random_sample_references(images)

        for target in images:
            result[target].extend(
                refs[target]
            )

    return result


def main():

    parser = argparse.ArgumentParser(
        description="Generate MiniMax-H3 image JSONL"
    )

    parser.add_argument(
        "--image_dir",
        type=Path,
        help="画像フォルダ",
    )

    parser.add_argument(
        "-o",
        "--output",
        type=Path,
        default=Path("image.jsonl"),
        help="出力JSONL",
    )

    parser.add_argument(
        "--mode",
        choices=[
            "same",
            "slide",
            "random_sample",
            "multi_ref3",
            "multi_target3",
        ],
        default="random_sample",
        help="reference生成方式",
    )

    parser.add_argument(
        "--seed",
        type=int,
        default=42,
        help="random seed",
    )

    args = parser.parse_args()

    random.seed(args.seed)

    image_dir = args.image_dir

    # ---------------------------------
    # 画像一覧
    # ---------------------------------

    images = sorted(
        p
        for p in image_dir.iterdir()
        if p.is_file()
        and p.suffix.lower() in IMAGE_EXTENSIONS
    )

    if len(images) < 2:
        raise ValueError(
            "画像は最低2枚必要です。"
        )

    print(f"Found {len(images)} images.")
    print(f"Mode: {args.mode}")

    # ---------------------------------
    # reference生成
    # ---------------------------------

    if args.mode == "same":

        references_for = {
            image: [image]
            for image in images
        }

    elif args.mode == "slide":

        references_for = make_slide_references(
            images
        )

    elif args.mode == "random_sample":

        references_for = (
            make_random_sample_references(
                images
            )
        )

    elif args.mode == "multi_ref3":

        references_for = (
            make_multi_ref3_references(
                images
            )
        )

    elif args.mode == "multi_target3":

        references_for = (
            make_multi_target3_references(
                images
            )
        )

    else:
        raise ValueError(
            f"Unknown mode: {args.mode}"
        )

    # ---------------------------------
    # JSONL生成
    # ---------------------------------

    with args.output.open(
        "w",
        encoding="utf-8",
    ) as f:

        for image_path in images:

            caption_path = (
                image_path.with_suffix(".txt")
            )

            if caption_path.exists():
                caption = (
                    caption_path.read_text(
                        encoding="utf-8"
                    ).strip()
                )
            else:
                caption = ""

            references = references_for[
                image_path
            ]

            record = {
                "image_path": make_json_path(
                    image_path
                ),
                "caption": caption,
                "references": [
                    {
                        "type": "image",
                        "path": make_json_path(ref),
                    }
                    for ref in references
                ],
            }

            f.write(
                json.dumps(
                    record,
                    ensure_ascii=False,
                )
                + "\n"
            )

    # ---------------------------------
    # 結果表示
    # ---------------------------------

    print(
        f"Written: {args.output}"
    )

    for image in images:
        refs = references_for[image]

        print(
            f"{image.name} -> "
            + ", ".join(
                p.name for p in refs
            )
        )


if __name__ == "__main__":
    main()

まとめ:

musubi-tunerのjsonlについてどのような学習画像と参照画像のペアの書き方が存在するかを考えてみた。
また、自分のmusubi-tunerのTeacher matchingの結果を参考までに残しておく。

推論時にpromptに容姿の特徴を含む場合は、通常LoRA(Guidance loss使用時)と同程度の結果が得られた。
しかし、(学習captionがトリガーワードのみではなかったためか)、容姿の特徴を除いたprompt時でキャラクター性の強さは確かに設定次第で通常LoRAよりは強かったものの、キャラクター性は完全には再現は出来なかった。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?