Musubi 引擎支持 Ideogram 4 LoRA 训练 #424

目标

让 Musubi 引擎支持 Ideogram 4 的 LoRA 训练，并在训练页提供对应模型入口（任务队列、日志、预览、缓存等沿用现有能力）。

对应路线图 docs/roadmap.md 3.2.0：「常规模型支持更新，包括评估通过 Musubi 接入 Ideogram-4；须独立完成本仓适配与验收」。

上游现状（已核实）

• musubi-tuner 自 v0.3.3（2026-06-19） 起支持 Ideogram 4 的 LoRA 训练 / 缓存 / 推理：ideogram4_train_network.py、ideogram4_cache_latents.py、ideogram4_cache_text_encoder_outputs.py、src/musubi_tuner/ideogram4/**、networks/lora_ideogram4.py。
• 我们 pin 的提交 e0cbd8f3（2026-08-13）已包含上述脚本；installer 会整包拷贝上游顶层 *.py + src/，因此不需要改上游，也不需要提前升 pin。
• 上游当前仅支持 LoRA（全量微调仍在未合并草案 PR）；LoRA 不能 merge 回 FP8 基底。上游文档 docs/ideogram4.md 标注为 experimental。

必须处理的上游缺陷（本仓需打补丁）

pin 版本的 src/musubi_tuner/ideogram4/ideogram4_utils.py 中，load_ideogram4_text_encoder() 在 _materialize_meta_tensors()（内部 to_empty()）之后没有重建 rotary embedding：非持久化的 inv_freq 缓冲不在 checkpoint 里，to_empty() 之后保持未初始化 → 文本编码器缓存为垃圾值，训练结果不可用。上游 v0.3.6（PR #1139）修复。

处理方式（建议）：沿用 model_assets.patch_krea2_tokenizer_path 的运行时源码补丁先例，打等价补丁；不升级 pin。升 pin = transformers 5.17 / diffusers 0.40 / torch 2.6 依赖大迁移 + krea2_train_network.py +159/−70 改动，已验收的 Krea 2 需全部重验，应作为独立任务另行评估。

范围与边界

• 权重：官方仅发量化权重（FP8 / NVFP4），无 BF16/FP16 DiT；组件为 cond DiT + uncond DiT（非对称 CFG）+ Qwen3-VL-8B TE + Flux2 VAE（Comfy-Org 单文件布局）。
• 许可：Ideogram Non-Commercial，权重在 HF 上 gated。整合包不得预置权重；下载/安装页需明示许可与来源，用户自行获取。
• 显存与缓存：9.3B FP8 DiT + Qwen3-VL-8B TE；TE 缓存 128 token ≈ 13.6 MB/图（1k 图 ≈ 13.6 GB，256 token 翻倍），需纳入缓存目录管理。
• 上游实验性：上游 issue #978 报告 TE 预缓存 OOM 与 resume 变慢，真机验收需覆盖这两个场景。

实现清单

后端（mikazuki/engines/musubi/）

• manifest.py：TRAIN_TYPES 增加 ideogram4-lora → ideogram4；CAPABILITIES.model_families 同步
• run.py：去掉写死的 model_train_type = "krea2-lora"，按 registry variant 分派
• adapter.py：NETWORK_MODULE 按模型族切换（musubi_tuner.networks.lora_ideogram4）、字段白名单与量化-only 约束（不加 krea2 专属的 bf16/fp8 配对规则）
• launcher.py / extension_state.py：三阶段脚本名与就绪检查按族取
• preflight.py：DiT / TE / VAE 组件检查与提示
• model_assets.py：ideogram4-lora 资源清单 + rotary 补丁
• utils/config_import.py：识别 ideogram4-lora 配置
• process.py：三阶段任务组（cache latents → cache TE → train）
• 测试：tests/test_musubi_backend.py、test_engine_registry.py、test_model_assets.py、test_config_import.py

前端

• mikazuki/schema/ideogram4-lora.ts（字段按上游 docs/ideogram4.md 定）
• frontend/src/training/modules.ts、params.ts、i18n、路由、Musubi 闸门页
• 前端测试

文档

• 训练文档（组件路径 / 许可 / 显存与缓存说明）
• CHANGELOG、docs/dev-progress.md、docs/roadmap.md 同步

验收标准

• 三阶段（cache latents → cache TE → train）真机跑通 3 步冒烟并保存 LoRA
• 预览采样正常；TE 缓存复用后二次启动不发散
• 前端模型入口、参数校验与预检报错正确；pytest + typecheck + lint + vitest 全绿
• 许可与「不预置权重」边界在界面与文档中明确

参考

• 上游文档：https://github.com/kohya-ss/musubi-tuner/blob/main/docs/ideogram4.md
• 本仓计划：docs/musubi-tuner-engine-plan.md
• 本仓先例：Krea 2 接入（Feat/kohya standalone env #392 之后的 musubi 引擎线）