H3 Multimodal LoRA Training

面向 MiniMax H3 的多模态 LoRA 训练、审计与交付技能。它把视频、立体声音频、参考图像/视频/音频、真 Ref2VA 条件训练、低显存后端、检查点选择和推理验证组织为一条可执行、可追溯、失败即停止的十步证据链。

项目不是参数合集，也不把“LoRA 能加载”当成“参考条件参与过训练”。每项能力必须对应固定源码、解析后的配置、真实运行证据和推理 round-trip；缺少证据时会明确拒绝或降级。

独立社区项目，非 MiniMax、ModelScope、AI Toolkit 或 SimpleTuner 官方产品。模型、训练器、数据集和衍生权重分别受其自身许可证约束。

为什么需要这个项目

H3 是联合音视频模型，训练风险不止是显存不足：目标媒体与参考媒体可能混用，音频可能被静默丢弃，CFG 蒸馏能力可能漂移，profile 字段可能没有真正进入后端，最终检查点也可能弱于中间检查点。

本项目将这些问题变成可检查的工程契约：

• load_compatible、condition_trained、audio_trained 分开记录；
• manifest、授权台账、审计报告、训练 profile、后端配置和启动计划逐层哈希绑定；
• 未识别字段、后端不兼容值或重复配置来源直接失败，不做静默 fallback；
• 训练前重新检查后端 Git SHA 和关键源码文件哈希；
• 生成样片必须通过 ffprobe 的视频/音频流验证，非空文件不等于有效推理；
• 标准 LoRA 是生产基线，新算法必须通过实现、权重、单变量和推理四道门禁。

已实现能力

AI Toolkit 与 SimpleTuner 必须在 profile 中提供目标推理宿主的 argv 模板和媒体要求，才会生成可完成第 10 步的启动计划。项目不会虚构一个未经上游验证的推理 CLI。

十步证据链

flowchart LR
    A[1 目标] --> B[2 权利/环境]
    B --> C[3 路线]
    C --> D[4 数据契约]
    D --> E[5 审计+字幕]
    E --> F[6 实验锁]
    F --> G[7 配置解析]
    G --> H[8 烟雾训练]
    H --> I[9 检查点选择]
    I --> J[10 推理验证/交付]

前一层证据不成立，后一层不能标记为完成。详细操作定义见 SKILL.md。

快速开始

技能脚本只使用 Python 标准库；实际训练依赖由所选后端提供。建议同时安装 ffprobe，否则媒体审计和最终推理验证无法形成完整证据。

git clone https://github.com/chengyansen-ai/h3-multimodal-lora-training.git
cd h3-multimodal-lora-training

python scripts/h3_project.py init \
  --root ./my-h3-project \
  --name first-ref2va-lora \
  --route true_ref2va \
  --backend diffsynth \
  --model-mode ref2va

将 examples/ 中的模板复制到项目规定位置并填写。数据与授权准备完成后：

python scripts/lint_captions.py \
  --manifest ./my-h3-project/data/manifest.jsonl \
  --route true_ref2va \
  --output ./my-h3-project/reports/04-caption-lint.json

python scripts/audit_dataset.py \
  --manifest ./my-h3-project/data/manifest.jsonl \
  --rights-ledger ./my-h3-project/records/02-rights.json \
  --project-root ./my-h3-project \
  --route true_ref2va \
  --hash-media \
  --output ./my-h3-project/reports/05-data-audit.json

完成第 6 步实验锁后，从固定提交的本地后端生成真实配置：

python scripts/prepare_backend.py \
  --root ./my-h3-project \
  --backend-repo /path/to/pinned/backend

AI Toolkit 和 SimpleTuner 还需增加 --materialize hardlink；跨文件系统可改用 symlink 或 copy。

GPU 操作需要显式本地确认：

python scripts/run_backend.py \
  --root ./my-h3-project \
  --authorization-token I_AUTHORIZE_H3_GPU_TRAINING \
  --timeout-seconds 7200

python scripts/validate_lora.py \
  --weights ./my-h3-project/runs/selected.safetensors \
  --project-root ./my-h3-project \
  --authorization-token I_AUTHORIZE_H3_GPU_INFERENCE

确认字符串只是防误启动门禁，不是账户密钥。

配置解析与算法门禁

training-profile.json 是用户意图，resolved-profile.json 是经过后端契约约束的语义。v1.1 会记录 requested/resolved/defaulted/rejected，并强制 H3 的关键约束：24 fps、17n+5、尺寸可被 32 整除、x0-noise、视频/音频 shift 12/3、共享基础噪声、BF16 和冻结模块策略。目标模块、alpha 与 optimizer 会写入各后端实际字段；SimpleTuner 使用其 Diffusers 运行时模块名，不能直接复制 DiffSynth 模块名。

当前算法口径：

• 生产默认：标准 LoRA；
• 已接入的基座保持：DiffSynth DeCFG preset adapter、AI Toolkit assistant LoRA、SimpleTuner h3_drift；
• 受控研究：rsLoRA、LoRA+、DoRA、PiSSA、LoftQ、LoKr/LyCORIS、Min-SNR、DMD2、稀疏注意力、trajectory-level LoRA；
• 任何研究算法都不能仅凭论文或配置字段升级为默认。

完整论证见 算法选型 和 H3 数学与保护项。

研究与验证状态

2026-08-26 的发现性扫描覆盖 1,172 条公开索引记录（来源间可能重叠），并对 50 余个高信号官方页面、源码文件、配置、模型卡和社区案例做了深读。扫描用于寻找风险和假设，不能代替源码或 GPU 复现。方法与计数口径见 社区证据快照。

v1.1 本地质量门禁：

这些结果证明工程契约和失败保护逻辑，不代表已在所有显卡、操作系统、数据集或未来上游版本完成 H3 33B 实训。当前结论、限制和复验命令见 质量报告。

项目结构

├── SKILL.md                  # 十步技能入口
├── scripts/                  # 11 个标准库工具与测试
├── assets/                   # 13 个项目模板
├── references/               # 后端、数据、数学、算法、评估与来源
├── docs/                     # 研究方法、社区证据与质量报告
└── .github/                  # CI、PR 与 Issue 证据模板

贡献、安全与许可证

• 贡献前请阅读 CONTRIBUTING.md，后端能力变化必须附完整 Git SHA 与可复现证据；
• 不要提交训练媒体、人物/声音隐私、模型权重、缓存、环境转储或真实密钥；
• 漏洞请按 SECURITY.md 使用私密报告；
• 本仓库采用 MIT License，第三方许可证边界见 THIRD_PARTY_NOTICES.md。

主要上游：MiniMax H3 · DiffSynth-Studio · AI Toolkit · SimpleTuner