comfyui-anima-slider-node

ComfyUI Anima Slider Node

Anima/Cosmos RFlow 向けの experimental text-only slider LoRA training を ComfyUI の custom node として実行するためのリポジトリです。

使い方

このフォルダを ComfyUI の custom_nodes 配下に置くか、シンボリックリンクしてください。

cd C:\path\to\ComfyUI\custom_nodes
git clone https://github.com/Shiba-2-shiba/Comfyui-anima-slider-node Comfyui-anima-slider-node

ComfyUI を再起動すると、training/anima slider に Train Anima Slider LoRA が追加されます。

ノードの入出力

入力:

• MODEL: ComfyUI でロードした diffusion model
• CLIP: ComfyUI でロードした text encoder
• VAE: ワークフロー互換用の入力。現在の text-only loss では画像 encode には使いません
• prompt_yaml: 同梱 prompts/*.yaml から選択
• custom_prompt_yaml_path: 任意の YAML を直接指定する場合に使用
• steps, lr, rank, alpha, network_preset, model_residency, lora_weight_dtype, width, height などの学習設定
• width=0, height=0: 選択した prompt YAML の width / height を使用します。既存ワークフローで 512 が保存されている場合は、YAML 解像度を使うために 0 へ戻してください。

出力:

• lora: ComfyUI の LORA_MODEL 型
• report_json: 学習 report JSON 文字列
• lora_path: 保存済み .safetensors
• report_path: 保存済み .json

LoRA と report は ComfyUI の output directory 配下に保存されます。output_lora_prefix の既定値は loras/anima_slider です。

学習時は、ComfyUI が MODEL に解決済みで持っている model_config.unet_config["image_model"] と num_blocks、および実際の diffusion_model.blocks 数から Anima variant を判定します。現状の対応は次の 2 種類です。

• anima_base_28: Anima base 系の 28 block モデル
• anima_2_9b_40: Anima 2.9B 系の 40 block モデル

それ以外の block 数や、num_blocks と実 block 数が一致しないロード状態は未対応としてエラーにします。保存される report JSON と .safetensors metadata には anima_variant, anima_block_count, lora_block_layout=native, target_model_signature が入ります。

互換性の目安:

• 28 block で学習した LoRA -> 28 block Anima base に通常の LoRA loader で適用
• 40 block で学習した LoRA -> 40 block Anima 2.9B に通常の LoRA loader で適用
• 28 block で学習した LoRA -> 40 block Anima 2.9B に Anima29BLoraLoader と preserved_blocks 指定で適用
• 40 block で学習した LoRA -> 28 block Anima base への縮退適用は未対応

QPOLA optimizer ノード

Train Anima Slider LoRA (QPOLA) は、既存ノードと同じ prompt、teacher、MSE loss、LoRA対象を使い、AdamWの代わりにQPOLA v1.0.4でtrainable LoRA weightを更新する実験ノードです。

要件:

• NVIDIA CUDA環境
• lora_weight_dtype=fp32（初期実装では固定）
• 同梱PTXをロードできるCUDA driver

QPOLA固有設定:

• lr: 既定値 1e-4。最初の比較候補は 3e-5, 1e-4, 3e-4 です。
• qpola_eps: 局所勾配スケール正規化用epsilon。既定値は 1e-8 です。
• qpola_low_vram: 各step後にCUDA allocator cacheを解放します。既定値は有効ですが、学習が遅くなる場合は無効化して比較してください。
• output_lora_prefix: 既定値は loras/anima_slider_qpola です。

QPOLAを初期化または実行できない場合、ノードはエラーで停止します。結果のoptimizerを偽らないため、AdamWへの自動フォールバックは行いません。report JSONとsafetensors metadataにはoptimizer種別とQPOLA versionが保存されます。

simple scheduler はdiffusion sigma列を作る設定であり、learning-rate schedulerではありません。QPOLA使用時も維持されます。

実装契約とA/B評価条件は QPOLA_NODE_SPEC.md を参照してください。

16GB VRAM向けの確認手順

16GB VRAMで高解像度学習を狙う場合は、network_preset=attn_mlp を維持し、model_residency=prefer_cuda と gradient_checkpointing=True を基本設定にしてください。dynamic はCUDA常駐が失敗する場合の最後の手段です。

lora_weight_dtype は既定の fp32 を推奨します。auto も fp32 の trainable LoRA weight を使います。VRAM をさらに削りたい場合だけ base または bf16 を試してください。ただし bf16 LoRA weight は小さい学習率の更新が丸めで消えやすく、品質確認が必須です。

推奨する切り分け順:

1. width=512, height=512, steps=1, prompt_indices=0
2. width=768, height=768, steps=1, prompt_indices=0
3. width=1024, height=1024, steps=1, prompt_indices=0, skip_initial_eval=True, skip_final_eval=True
4. 1024x1024の学習本体が通った後で、skip_initial_eval=False, skip_final_eval=False に戻してeval込みを確認

skip_initial_eval と skip_final_eval はOOM phaseを分けるための診断用です。品質評価の代替ではありません。report JSONには gradient_checkpointing, eval skip設定、setup後とtext adapter precompute後のCUDA memory diagnostics、各stepのphase timingsが記録されます。

Prompt YAML

YAML は list 形式です。

- target: "base prompt"
  positive: "base prompt, direction to enhance"
  unconditional: "base prompt, opposite direction"
  neutral: "base prompt"
  guidance_scale: 2.0
  action: enhance
  width: 1024
  height: 1024
  batch_size: 1

positive / unconditional / neutral は省略可能です。positive と neutral は target に、unconditional は空文字にフォールバックします。

注意

• この実装は anima-slider-experiment の flow slider trainer を ComfyUI 入力モデル向けに移植したものです。
• 画角や背景を保ちたい slider は、学習解像度を 512x512 のままにしないでください。chibi/skirt 系の縦長 full-body prompt では width=0, height=0 か、少なくとも width=896, height=1152 を推奨します。
• MODEL に LoRA wrapper を一時注入しますが、学習終了時に元の linear module へ戻します。
• steps の既定値は 600 です。bundled prompt は先頭6件を学習、末尾2件を評価向けに並べているため、通常は prompt_indices=0,1,2,3,4,5, eval_prompt_indices=6,7 を使ってください。短い smoke 確認だけ行う場合は、一時的に steps=3, width=512, height=512, prompt_indices=0,1,2,3 程度まで下げてください。
• model_residency=prefer_cuda は ComfyUI のロード後に base model を CUDA へ寄せる best-effort 設定です。OOM になる環境では dynamic に戻してください。
• lora_weight_dtype=base は旧挙動に近く、base model が bf16 なら LoRA weight も bf16 になります。sd-scripts の通常の Anima LoRA 学習に寄せるなら fp32 を使ってください。
• 16GB VRAMで1024x1024を狙う場合も、LoRA対象を attn_only へ削るのではなく、まず attn_mlp と gradient_checkpointing=True の組み合わせで確認してください。
• bundled prompt のうち年齢語を含む YAML は allow_unsafe_age_terms=True が必要な場合があります。

Third-party notice

QPOLA v1.0.4のoptimizer loader、CUDA source、PTXをApache License 2.0に基づいて同梱しています。ライセンスと由来は anima_slider_node/third_party/qpola/LICENSE および NOTICE.md を参照してください。