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 が追加されます。

Anima 2.9B用の正式採用学習ワークフローと設定一覧・提供原本を同梱しています。

ノードの入出力

入力:

• 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 配下に保存されます。

LoRA名の自動入力

通常版・QPOLA版とも、新規ノードの追加時とプロンプトの選択変更時に、output_lora_prefix へプロンプトのファイル名を反映します。

• 例: prompts-anima-breast_size_slider_v4.yaml → loras/anima_breast_size_slider_v4
• 自動入力後は、_test01 などを自由に追記・修正できます。実行時は編集した名前を使います。
• 別のプロンプトへ切り替えると、手動の追記部分も含めて新しい名前に置き換わります。同じ選択値の再確定では置き換えません。
• 保存済みワークフローの読み込みやノードの複製では、保存された名前を維持します。既存の loras/anima_age_slider も維持するため、自動入力を使うには一度別のプロンプトへ切り替えてください。
• custom_prompt_yaml_path が入力されている場合は、そのファイル名を優先します（例: C:\prompts\my_trial.yaml → loras/my_trial）。この間、同梱プロンプトの選択変更では名前を更新しません。カスタムパスを空欄に戻すと、選択中の同梱プロンプト名を反映します。
• 自動入力する保存先は loras/ です。保存時の連番・拡張子は従来どおり付加されます。

更新後は ComfyUI を再起動し、ブラウザーを再読み込みしてください。この自動入力はUI拡張の機能です。APIからの実行では、指定された output_lora_prefix をそのまま使用します。

学習時は、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: UIでは上記のルールでプロンプト名を自動入力します。Pythonスキーマ上の既定値は 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

全身年齢スライダーの正規版は老齢化（旧v9）と幼齢化（旧v10）です。両方ともenhance_onlyで学習し、プラスのLoRA強度を使います。設定・旧版からの移行と、他のスライダーへ適用する単方向化・プロンプト調整の調査手順を参照してください。

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 を使ってください。

診断ログとクラウド確認手順

Anima のテキスト由来 Slider LoRA 学習において、逆伝播や演算境界の挙動を追跡するための構造化診断ログが利用可能です。

デバッグの有効化

環境変数を設定して ComfyUI を再起動します。

• Paperspace / Jupyter Notebook の場合: ComfyUI 起動セルより前に以下を実行してください。

  import os
  os.environ["ANIMA_SLIDER_DEBUG"] = "1"
  os.environ["ANIMA_SLIDER_DEBUG_SYNC"] = "0"
  

• Shell / Terminal の場合:

  export ANIMA_SLIDER_DEBUG=1
  export ANIMA_SLIDER_DEBUG_SYNC=0
  

※ 通常運用時は ANIMA_SLIDER_DEBUG=0（既定値）で使用してください。debug=0 ではラッパー計測やスナップショット等のオーバーヘッドは一切発生しません。

クラウド確認A（短縮実行）の推奨設定

| 項目 | 最初の確認 | 次の確認 | |---|---|---| | width / height | 512 / 512 | 512 / 512、その後1024 / 1024 | | steps | 1 | 3、その後1024では1 | | prompt_indices | 0 | 0 | | skip_initial_eval / skip_final_eval | True / True | True / True | | gradient_checkpointing | True | True | | seed UI | fixed | fixed | | seed | 676193269724873 | 同じ | | output_lora_prefix | loras/anima_autograd_smoke | 同じ |

ログは [AnimaSliderDebug] プレフィックス付きの 1 行 1 イベント JSON として出力されます。

UI自動入力の開発用テスト

追加依存なしで、Node.jsの標準テスト機能を使って名前変換・選択変更・保存値の復元を検証できます。

node --experimental-vm-modules --test tests/test_lora_name_sync.mjs

ComfyUI画面の描画確認はこのテストに含みません。

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 を参照してください。