SimpleTuner 训练脚本选项¶
概览¶
本指南以易读方式介绍 SimpleTuner train.py 中可用的命令行选项。这些选项提供高度可定制性，使你能按需求训练模型。
Kubeflow 单 GPU 服务器选项¶
可选的 Kubeflow 集成将 GPU 准入委托给 Kueue，并通过 Kubeflow Trainer 创建一次性 Worker。使用 pip install 'simpletuner[kubernetes]' 安装，然后在集群内运行服务器：
simpletuner server --mode trainer --kubeflow \
--kubeflow-namespace training \
--kubeflow-runtime simpletuner-worker \
--kubeflow-queue gpu-training \
--kubeflow-worker-image registry.example.com/simpletuner:latest \
--kubeflow-orchestrator-url http://simpletuner-server.training.svc:8001
--kubeflow-poll-interval 控制 TrainJob 调谐频率，默认为五秒。集群管理员负责提供 TrainingRuntime、Kueue 队列、ServiceAccount 权限、镜像拉取配置以及共享模型/数据存储。
JSON 配置文件格式¶
默认 JSON 文件名为 config.json，键名与下方 --arguments 一致。JSON 中不需要前导 --，但也可以保留。
需要可直接运行的示例？请查看 simpletuner/examples/README.md 中的预置。
简易配置脚本（推荐）¶
可使用 simpletuner configure 命令生成包含理想默认值的 config.json。
修改现有配置¶
configure 可接收一个兼容的 config.json，以交互方式修改训练设置：
其中 foo 为你的配置环境；若未使用环境，直接用 config/config.json。
⚠️ 若所在地区无法方便访问 Hugging Face Hub，请在
~/.bashrc或~/.zshrc（取决于你的$SHELL）中添加HF_ENDPOINT=https://hf-mirror.com。
🌟 核心模型配置¶
--model_type¶
- 内容：选择 LoRA 或全量微调。
- 选项：lora, full.
- 默认：lora
- 若使用 lora，
--lora_type决定使用 PEFT 还是 LyCORIS。部分模型（PixArt）仅支持 LyCORIS 适配器。
--model_family¶
- 内容：指定训练的模型架构。
- 选项：pixart_sigma, flux, flux3_image, sd3, sdxl, kolors, legacy
--model_flavour¶
选择 --model_family 中的检查点变体。qwen_image 的默认值是 v2.1（Qwen/Qwen-Image-2.1）。若要训练旧架构，请明确设置 v1.0、v2.0 或现有的 edit-* 版本；适配器、嵌入缓存和潜变量缓存不能与 2.1 互换。参阅 Qwen Image 快速入门。
使用 model_family: "flux3_image" 训练 5.6B 参数的图像 Transformer。默认变体 klein-base 加载 black-forest-labs/flux-3-image-klein-base；klein 加载蒸馏模型 black-forest-labs/flux-3-image-klein。下载前请先取得所选仓库的访问权限。参见 FLUX [Kom]munity 许可证。
moss_image 默认的 sft 变体加载 OpenMOSS-Team/MOSS-Image-SFT。使用 OpenMOSS-Team/MOSS-Image-Base 时，设置 model_flavour: "base"。训练示例采用 512×512 等效面积。参阅 MOSS-Image 快速入门。
选择 model_flavour: "sft-edit" 或 "base-edit"，即可使用参考图像训练。这两个变体从对应的 SFT 或 Base 检查点开始，通过适配器学习参考图像条件。可从 simpletuner/examples/moss_image/sft-edit/default/peft-lora 或 moss_image/base-edit/default/peft-lora 开始；两者均采用每批一个目标、512 等效分辨率训练、REPA 和数据集验证。
--lora_format¶
- 内容：选择 LoRA 检查点的加载/保存键格式。
- 选项：
diffusers（默认），comfyui - 说明：
diffusers为标准 PEFT/Diffusers 格式。comfyui会转换为 ComfyUI 风格键（diffusion_model.*，含lora_A/lora_B与.alpha张量）。Flux、Flux2、Lumina2、Z-Image 即便保持diffusers也会自动识别 ComfyUI 输入，但若希望保存时强制 ComfyUI 输出，请设为comfyui。
--minimax_music_train_component¶
- 内容：选择接受训练的 MiniMax Music 3 组件。
- 选项：
transformer（默认）、language_model - 说明：
transformer在缓存的 Flow-VAE latent 上训练流匹配音乐 DiT（标准路径）。language_model使用 RVQ 语义码的下一 token 交叉熵训练 Qwen3 自回归阶段。对于dataset_type=audio，SimpleTuner 会在 VAE 缓存阶段用 MiniMax Music DAV 和默认 v4 RVQ 编码器把原始 waveform 编成代码。数据集仍可提供预计算的原始逐码本音频 token（audio_tokens或audio_tokens_path，形状为[frames, codebooks]），以及prompt（或tags）和lyrics。仅支持标准 PEFT LoRA，--lora_format comfyui会被拒绝，且训练器内验证音频被禁用——请从保存的检查点渲染。
--minimax_music_lm_max_frames¶
- 内容：在
--minimax_music_train_component=language_model时，以 25Hz 音频帧为单位限制prefix和独立random窗口。 - 默认：
0（训练完整曲目） - 说明：
- 一帧为 40 毫秒；7500 帧即五分钟。
continuation使用下方独立的目标帧数和时长设置。- 被截断的样本不会获得音频结束目标，因此模型不会被教导提前停止。
--minimax_music_lm_window_mode¶
- 内容：选择语言模型训练序列的构造方式。
- 选项：
prefix（默认）、random、continuation - 说明：
prefix使用曲目开头。它最能保持完整歌词的合理性，但较短上限主要会教模型学习前奏。random在 collate 时采样一个连续 RVQ 窗口，把开始/结束/总时长文本加入 prompt；对被截取的窗口会省略完整歌词，除非样本提供lyrics_window。continuation采样有界的可见片段，仅对末尾目标帧计算损失。- 独立
random需要正数--minimax_music_lm_max_frames；continuation不使用该选项。
--minimax_music_lm_target_frames¶
- 内容：在
continuation中，设置可见片段末尾有多少个 25Hz 帧接受下一 token 损失。 - 默认：
128（一个原生 RVQ 分段，即 5.12 秒） - 说明：更早的可见帧保留为因果上下文，并从交叉熵中屏蔽。
--minimax_music_lm_continuation_crop_mode¶
- 内容：选择
continuation可见片段的起点。 - 选项：
full（默认）、random - 说明：
full总是从歌曲第 0 帧开始，并在配置的时长范围内采样终点。random可以省略曲目开头，但会在监督目标前保留至少一个原生 128 帧上下文分段，并把位置加入 prompt。- 定位随机片段会省略完整歌词，除非样本提供
lyrics_window。过短曲目会回退到完整前缀。
--minimax_music_lm_min_duration_seconds¶
- 内容：设置
continuation中模型可见片段的最短时长。 - 默认：
5.12 - 说明：按原生 128 帧（5.12 秒）间隔向上取整。随机片段为了保留上下文可能更长。
--minimax_music_lm_max_duration_seconds¶
- 内容：在不更改缓存 RVQ 曲目的情况下，限制
continuation的模型可见时长。 - 默认：
0（使用可用曲目长度） - 说明：
- 正数上限按原生 128 帧间隔向下取整。
- 对
random，上限必须容纳监督目标和至少一个上下文分段。 - 只有采样片段到达真实曲目末尾时，才添加音频结束目标。
- 当终止和非终止片段都可用时，25% 的 continuation 样本会显式选择真实曲目末尾；其余 75% 在有效的非终止终点或偏移中均匀采样，因此 EOS 监督不会随曲目变长而变稀。
--minimax_music_rvq_encoder_model_name_or_path¶
- 内容：仅用于 MiniMax Music
language_model训练：包含 RVQ 编码器的 Hub 仓库或本地目录，用于将缓存的 DAV 音频 latent 转成逐码本音频代码。 - 默认：
SimpleTuner/open-rvq-encoder-minimax-music3-169m-v4 - 相关：
--minimax_music_rvq_encoder_subfolder默认是final；--minimax_music_rvq_encoder_revision可固定 Hub revision。 - 说明：默认包包含
rvq_encoder_config.json、rvq_encoder.safetensors和 muP base-shape 元数据。只有在使用为 MiniMax Music 3 codebook 训练的兼容 RVQ 编码器时才更改。
--minimax_music_rvq_encoder_subfolder¶
- 内容：RVQ 编码器仓库或本地目录中的子文件夹。
- 默认：
final - 说明：所选文件夹必须包含
rvq_encoder_config.json、rvq_encoder.safetensors以及所需的 muP base-shape 元数据。
--minimax_music_rvq_encoder_revision¶
- 内容：
--minimax_music_rvq_encoder_model_name_or_path的可选 Hub revision。 - 默认：未设置；如果提供了主
--revision，则使用它。 - 说明：当 RVQ 编码器需要与 MiniMax Music 3 基础 checkpoint 分开固定版本时使用。
--minimax_music_rvq_vae_model_name_or_path¶
- 内容：仅用于 MiniMax Music
language_model训练：VAE 缓存时在 RVQ 编码器之前使用的 DAV/audio VAE 仓库、本地目录或dav.pth文件。 - 默认：未设置；先使用
--pretrained_vae_model_name_or_path，然后使用SimpleTuner/MiniMax-Music-3-Encoder。 - 说明：这是 waveform 到 DAV latent 的编码阶段。随后 RVQ 编码器会把这些 DAV latent 转成全局 LM 学习预测的代码张量。
--minimax_music_lm_adapter¶
- 内容：预缓存 DiT 条件时应用于 Qwen3 规划器的语言模型 LoRA 路径（带
language_model.前缀键的pytorch_lora_weights.safetensors，由--minimax_music_train_component=language_model产生）。 - 相关：
--minimax_music_lm_adapter_strength（默认1.0）缩放适配器增量。 - 说明：更换适配器或强度时请使用新的文本嵌入缓存目录；缓存不会自动失效。
--minimax_music_lm_precache_mode¶
- 内容：Qwen3 规划器为 DiT 训练生成缓存条件的方式。
- 选项：
text-only（默认）、audio-only、audio+text - 说明：
text-only从 caption 和歌词自回归采样（原有行为），隐藏状态描述的是规划器想象的曲目而非训练音频。audio-only将样本的真实 RVQ 码（audio_tokens_path元数据，原始逐码本索引）教师强制通过规划器，无文本前缀；audio+text前置 caption 和歌词。两者都使逐帧隐藏状态与 DAV latent 一一对齐，并将码截断到 VAE 缓存覆盖的音频窗口。- 更换模式时请使用新的文本嵌入缓存目录。
--minimax_h3_target_mode¶
- 内容：控制 MiniMax-H3 是否包含目标音频行。
- 选项：
auto,video,av - 默认：
auto - 说明：
auto在检测到已启用的音频数据时解析为av，否则解析为video。验证使用相同的数据检测默认值。- 如需让 auto-split 或显式音频 backend 进行联合音视频训练，请在 data backend 条目中将
minimax_h3_target_mode或h3_target_mode设为av。
--minimax_h3_sparse_attention¶
- 内容：为 MiniMax-H3 目标视频 token 启用实验性的、training-aware 的 3D block sparse attention。
- 选项：
disabled、moba3d - 默认值：
disabled - 相关选项：
minimax_h3_sparse_block_shape：用逗号或x分隔的(T,H,W)维度，乘积必须为 128。默认值：1,8,16。minimax_h3_sparse_video_kv_fraction：每个目标视频 query block 选择的目标视频 KV blocks 比例。默认值：0.5。minimax_h3_sparse_share_heads：在 attention heads 之间共享路由。默认值：false。minimax_h3_sparse_start_layer：保持更早的 transformer layers 使用 dense attention。默认值：0。- 说明：
- 文本、音频、reference context 和非目标 queries 保持 dense。
- 需要 CUDA FlexAttention。Ulysses context parallelism 支持
context_parallel_strategy=alltoall；ring context parallelism 和 TREAD 不兼容。 - MiniMax 尚未公开 H3 的精确 sparse routing 配置。该近似实现用于可控 fine-tuning 实验，不保证性能提升。
--fuse_qkv_projections¶
- 内容：融合注意力块中的 QKV 投影，提高硬件效率。
- 说明：仅在手动安装 Flash Attention 3 的 NVIDIA H100 或 H200 上可用。
--offload_during_startup¶
- 内容：在 VAE 缓存期间将文本编码器权重卸载到 CPU。
- 原因：对 HiDream、Wan 2.1 等大模型，加载 VAE 缓存时可能 OOM。该选项不影响训练质量，但在超大文本编码器或慢 CPU 下可能显著延长启动时间，故默认关闭。
--offload_during_save¶
- 内容：在
save_hooks.py准备检查点时，将整条管线临时迁移到 CPU，确保 FP8/量化权重在设备外写入。 - 原因：保存 fp8-quanto 可能导致显存突增（例如
state_dict()序列化时）。该选项在训练期间保持模型在加速器上，仅在触发保存时短暂卸载以避免 CUDA OOM。 - 提示：仅在保存因 OOM 失败时启用；保存后模型会自动迁回以继续训练。
--delete_model_after_load¶
- 内容：模型加载进内存后，从 Hugging Face 缓存中删除模型文件。
- 原因：减少按 GB 计费的存储开销。模型加载到 VRAM/RAM 后，磁盘缓存直到下次运行前都不需要。以牺牲后续运行的网络带宽来换取存储节省。
- 说明：
- 启用验证时不会删除 VAE，因为生成验证图像需要它。
- 文本编码器在数据后端工厂完成启动（嵌入缓存后）被删除。
- Transformer/UNet 在加载后立即删除。
- 多节点环境下，仅每个节点的 local-rank 0 执行删除。为处理共享网络存储中的竞态，删除失败会被静默忽略。
- 不影响训练检查点，仅影响预训练基础模型缓存。
--text_embed_full_cache¶
- 内容：在 text embed cache 中保存完整的 raw text encoder 输出。
- 默认值：
False - 原因：默认值允许按模型定制的紧凑 cache 布局。例如，Ideogram 4 会在写入 cache 文件前，通过 transformer 中冻结的
llm_cond_norm和llm_cond_proj层投影 13 层 Qwen hidden-state 堆栈；这些层在 LoRA 和 full transformer 训练中都会保持冻结。 - 何时使用：用于调试缓存兼容性、确实需要 raw 未投影的 text encoder features，或在改造类似 Ideogram 的架构进行从零训练且 text projection 不是固定预训练组件时启用。
--text_cache_ondemand¶
- 内容：跳过完整的文本缓存预计算，在训练或验证请求缺失的提示词嵌入时再进行编码。
- 默认值：
False - 行为：仍会读取已有缓存条目，并写入新编码的缺失条目。文本编码器会保持加载，因为启动后仍需要使用。
- 数据加载器覆盖：
text_embeds后端可通过"text_cache_ondemand": true独立启用。
--cosmos3_reasoner_component¶
- 内容：Cosmos3 冻结 reasoner 组件的 Hugging Face repo id 或本地路径。
- 默认值：
auto - 用途：Cosmos3 文本缓存使用此组件写入逐层 reasoner K/V 条目。
- 自动选项：
SimpleTuner/cosmos3-component-reasoning-layers-bf16-edge、SimpleTuner/cosmos3-component-reasoning-layers-bf16-nano、SimpleTuner/cosmos3-component-reasoning-layers-bf16-super、SimpleTuner/cosmos3-component-reasoning-layers-bf16-super-i2v、SimpleTuner/cosmos3-component-reasoning-layers-bf16-super-t2i。 - 说明：Cosmos3 会强制使用按需文本缓存，因为 reasoner 缓存键包含样本几何信息。
--cosmos3_generator_component¶
- 内容：Cosmos3 仅生成 transformer 组件的 Hugging Face repo id 或本地路径。
- 默认值：
auto - 用途：
auto会选择匹配的 Edge、Nano、Super、Super-I2V 或 Super-T2I 组件。 - 自动选项：
SimpleTuner/cosmos3-component-generation-layers-bf16-edge、SimpleTuner/cosmos3-component-generation-layers-bf16-nano、SimpleTuner/cosmos3-component-generation-layers-bf16-super、SimpleTuner/cosmos3-component-generation-layers-bf16-super-i2v、SimpleTuner/cosmos3-component-generation-layers-bf16-super-t2i。 - 说明：该组件省略 transformer 内部的 reasoner 权重，并需要 reasoner K/V 条目。
--text_cache_disable¶
- 内容：禁止所有文本嵌入缓存写入，同时保留对已有条目的读取。
- 默认值：
False - 行为：隐含启用
--text_cache_ondemand；缺失嵌入会在请求时编码，但不会存储。 - 数据加载器覆盖：当全局选项为 false 时，可在单个
text_embeds后端设置"text_cache_disable": true。
--trust_remote_code¶
- 内容：当 checkpoint 依赖上游自定义类时，允许 Transformers 和 tokenizer 执行模型仓库中的自定义 Python 代码。
- 默认值：
False - 原因：ACE-Step v1.5 checkpoint 需要它，因为上游仓库包含自定义的
AutoModel和 tokenizer 代码。 - 警告：仅对你信任的模型仓库启用此选项。
--diffusion_blocks_config¶
- 作用：JSON 对象或 JSON 文件路径，用于启用 diffusion Transformer 分块训练。
- 必填键：
layers_per_block设置每个噪声区间执行的最大连续 denoiser 层数。 - 可选键：
overlap（默认0.05）、blocks_to_train、block_paths、timestep_boundaries。 - 行为：每个 batch 采样一个噪声块，只执行对应层组，并为 DDP 自动启用 unused-parameter 检测。
- 限制：仅支持 Transformer denoiser。详见 DiffusionBlocks。
--musubi_blocks_to_swap¶
- 内容：为 LongCat-Video、Wan、LTXVideo、Kandinsky5-Video、Qwen-Image、Flux、Flux.2、zlab i1、Cosmos2Image、HunyuanVideo、Krea 2 提供 Musubi 块交换。将最后 N 个 Transformer 块保留在 CPU，并在前向中按块流式加载权重。
- 默认：
0（禁用） - 说明：Musubi 风格权重卸载，会降低吞吐以换取显存节省，且在启用梯度时会跳过。
- 说明：Musubi 风格权重卸载，通过降低吞吐换取显存节省；启用梯度时会跳过。
--musubi_block_swap_device¶
- 内容：存放交换的 Transformer 块的设备字符串（如
cpu、cuda:0）。 - 默认：
cpu - 说明：仅当
--musubi_blocks_to_swap> 0 时生效。
--ramtorch¶
- 内容：将
nn.Linear层替换为 RamTorch 的 CPU 流式实现。 - 原因：在 CPU 内存共享 Linear 权重并流式传到加速器，以降低显存压力。
- 说明：
- 需要 CUDA 或 ROCm（不支持 Apple/MPS）。
- 自动启用
--set_grads_to_none。
--ramtorch_target_modules¶
- 内容：逗号分隔的 glob 模式，用于限制哪些 Linear 模块转换为 RamTorch。
- 默认：未提供模式时转换所有 Linear 层。
- 说明：
- 使用
fnmatchglob 语法匹配完整模块名或类名。 - 模式必须包含末尾的
.*通配符才能匹配块内的层。例如，transformer_blocks.0.*匹配块 0 内的所有层，而transformer_blocks.*匹配所有 transformer 块。不带.*的裸名称如transformer_blocks.0也可以工作（会自动展开），但建议使用明确的通配符形式以提高清晰度。 - 示例：
"transformer_blocks.*,single_transformer_blocks.0.*,single_transformer_blocks.1.*"
--ramtorch_text_encoder¶
- 内容：对所有文本编码器 Linear 层应用 RamTorch 替换。
- 默认：
False
--ramtorch_vae¶
- 内容：仅对 VAE 的 mid-block Linear 层进行 RamTorch 转换（实验性）。
- 默认：
False - 说明：VAE 的上下采样卷积块保持不变。
--ramtorch_controlnet¶
- 内容：训练 ControlNet 时对其 Linear 层应用 RamTorch 替换。
- 默认：
False
--ramtorch_transformer_percent¶
- 内容：使用 RamTorch 卸载的 transformer Linear 层的百分比（0-100）。
- 默认：
100（所有符合条件的层） - 原因：允许部分卸载以平衡显存节省与性能。较低的值保留更多层在 GPU 上以加快训练，同时仍减少内存使用。
- 说明：层按模块遍历顺序从头开始选择。可与
--ramtorch_target_modules结合使用。
--ramtorch_text_encoder_percent¶
- 内容：使用 RamTorch 卸载的文本编码器 Linear 层的百分比（0-100）。
- 默认：
100（所有符合条件的层） - 原因：当启用
--ramtorch_text_encoder时，允许部分卸载文本编码器。 - 说明：仅在启用
--ramtorch_text_encoder时适用。
--ramtorch_disable_sync_hooks¶
- 内容：禁用 RamTorch 层后添加的 CUDA 同步钩子。
- 默认：
False（同步钩子已启用） - 原因：同步钩子修复了 RamTorch 乒乓缓冲系统中可能导致非确定性输出的竞争条件。禁用可能提高性能，但有结果不正确的风险。
- 说明：仅在同步钩子出现问题或想要测试时才禁用。
--ramtorch_disable_extensions¶
- 内容：仅对 Linear 层应用 RamTorch，跳过 Embedding/RMSNorm/LayerNorm/Conv。
- 默认：
True（扩展已禁用） - 原因：SimpleTuner 将 RamTorch 扩展到 Linear 层之外，包括 Embedding、RMSNorm、LayerNorm 和 Conv 层。使用此选项禁用这些扩展，仅卸载 Linear 层。
- 说明：可能减少显存节省，但有助于调试扩展层类型的问题。
--pretrained_model_name_or_path¶
- 内容：预训练模型路径或 https://huggingface.co/models 上的标识符。
- 原因：指定训练起点的基础模型。可用
--revision与--variant选择仓库中的特定版本。也支持 SDXL、Flux、SD3.x 的单文件.safetensors路径。
--pretrained_transformer_model_name_or_path¶
- 内容：可选的预训练 transformer 权重路径，或 https://huggingface.co/models 上的标识符。
- 默认：
None（对于支持此覆盖项的加载器，transformer 来源仍跟随--pretrained_model_name_or_path） - 原因：当 transformer 组件位于独立仓库、本地目录或不同于基础模型包的 checkpoint 中时使用。
- 说明：如果 transformer 权重位于该路径下的子目录中，请与
--pretrained_transformer_subfolder配合使用。
--pretrained_t5_model_name_or_path¶
- 内容：预训练 T5 模型路径或 https://huggingface.co/models 上的标识符。
- 原因：训练 PixArt 时，可指定 T5 权重来源，以避免切换基础模型时重复下载。
--pretrained_gemma_model_name_or_path¶
- 内容：预训练 Gemma 模型路径或 https://huggingface.co/models 上的标识符。
- 原因：训练 Gemma 系模型（例如 LTX-2、Sana、Lumina2）时，可单独指定 Gemma 权重来源，而无需更换基础扩散模型路径。
--qwen_text_encoder_model_name_or_path¶
- 内容：预训练 Qwen 文本编码器模型路径，或 https://huggingface.co/models 上的标识符。
- 默认：
None（使用所选模型定义的 Qwen 文本编码器来源）。 - 原因：用于在 Qwen 系模型家族中共享或替换 Qwen 文本编码器，而无需编辑 Hugging Face 缓存。
- 说明：此选项适用于只有一个 Qwen 文本编码器的模型家族。如果某个模型家族定义了多个 Qwen 编码器，该选项会被忽略，SimpleTuner 会记录警告。
--max_grounding_entities¶
- 每张图像用于 GLIGEN 风格空间标注的最大 grounding 实体数。默认值：0（禁用）。典型值：4-16。
--pretrained_grounding_model_name_or_path¶
- 用于按实体提取图像特征的可选预训练模型。默认值：None。
--custom_text_encoder_intermediary_layers¶
- 内容：覆盖 FLUX.2 模型中从文本编码器提取的隐藏状态层。
- 格式：层索引的 JSON 数组，例如
[10, 20, 30] - 默认值：未设置时使用模型特定默认值：
- FLUX.2-dev (Mistral-3)：
[10, 20, 30] - FLUX.2-klein (Qwen3)：
[9, 18, 27] - 原因：允许尝试不同的文本编码器隐藏状态组合，用于自定义对齐或研究目的。
- 注意：此选项为实验性功能，仅适用于 FLUX.2 模型。更改层索引会使已缓存的文本嵌入失效，需要重新生成。层数必须与模型期望的输入一致（3 层）。
--gradient_checkpointing¶
- 内容：训练过程中按层计算并累积梯度，以降低显存峰值，但训练会变慢。
--gradient_checkpointing_interval¶
- 内容：transformer block checkpointing 的模型相关 interval。1 基本等同于启用
--gradient_checkpointing。 - 说明：Flux、Flux.2、Flux.3 Image Klein、Krea 2、LTXVideo2、MageFlow、Qwen Image 2.1、Z-Image 和 Wan 在 whole-block 路径上使用连续的 n 个 block chunk。其他支持此选项的模型族可能仍使用旧的“每第 n 个 block checkpoint”行为。更大的连续分组保存更少的边界状态，但仍需重算 checkpoint 内的 block。请测量速度与峰值显存的取舍，参见 Segmented Checkpointing。
--gradient_checkpointing_segment_stride¶
- 内容：在支持 segmented whole-block 路径的模型上，每隔 n 个 block 启动一个 checkpointed segment。
- 示例：设置
--gradient_checkpointing_interval=2且--gradient_checkpointing_segment_stride=4时，SimpleTuner 会 checkpoint 两个 block，然后正常运行接下来的两个 block，如此重复。 - 说明：仅在已安装的 SimpleTuner 版本中暴露 segmented whole-block 支持的模型族上生效。不支持的模型族会记录 warning 并忽略该值。stride 必须大于或等于 interval。参见 Segmented Checkpointing。
--gradient_checkpointing_backend¶
- 选项：
torch、torch-ffn、unsloth、unsloth-ffn - 内容：选择 gradient checkpointing 的实现方式和范围。
torch（默认）：checkpoint 整个受支持 block，并在 backward 重算 activation。torch-ffn：在有清晰 FFN 边界的模型上，只 checkpoint feed-forward 部分。unsloth：checkpoint 整个受支持 block，并把保存的 tensor 卸载到 CPU。unsloth-ffn：只 checkpoint feed-forward 部分，并把保存的 tensor 卸载到 CPU。- 说明：仅在启用
--gradient_checkpointing时生效。unsloth变体需要 CUDA。FFN-only 变体目前支持 Chroma、Flux、Krea 2、LTXVideo2、MageFlow、Wan 和 Z-Image；模型不支持该 scope 时会直接报错。实测 tradeoff 见 Unsloth-style checkpointing。
--gradient_checkpointing_offload_attention¶
- 内容：在有清晰 attention/FFN 边界的模型上，把 attention 侧保存的 activations 卸载到 CPU。
- 原因：当传输比重算 attention 更便宜时，可降低 VRAM，且不需要支付完整 attention 重算成本。
- 说明：它可以单独启用。也可与模型支持的任意 checkpoint backend 组合。仅在已安装的 SimpleTuner 版本中暴露清晰 attention/FFN 边界的模型族上生效；不支持的模型会直接报错。
--gradient_checkpointing_offload_pin_memory_max_buckets¶
- 默认值：
12 - 内容：activation offload 可使用的 pinned CPU tensor bucket 最大数量。
- 原因：pinned memory 有利于 CPU/GPU 传输，但可变分辨率和文本长度会产生少见 tensor 形状。达到上限后，新的 bucket 形状会改用普通 CPU memory。
- 说明：设为
0可关闭 activation offload 的 pinned-memory pooling。
--gradient_checkpointing_offload_prefetch¶
- 默认值：
false - 内容：学习 offloaded activations 的 backward restore 顺序，并把可能下一个需要的 tensor 预取回 GPU。
- 原因：JIT H2D restore 通常很难重叠。顺序稳定后，prefetch 可把部分传输隐藏在 backward compute 后面。
- 说明：实验性功能，并且只在启用
--gradient_checkpointing_offload_attention时生效。
--refiner_training¶
- 内容：启用自定义混合专家模型系列训练。详情参见 Mixture-of-Experts。
精度¶
--quantize_via¶
- 选项：
cpu、accelerator、pipeline accelerator可能稍快，但在 Flux 等大模型上 24G 卡可能 OOM。cpu量化约需 30 秒。（默认）pipeline将量化交给 Diffusers，通过--quantization_config或管线可用的预设（如nf4-bnb、int8-torchaofp8-torchao、int8-quanto、.gguf检查点）。
--base_model_precision¶
- 内容：降低模型精度并用更少内存训练。支持三种量化后端：BitsAndBytes（pipeline）、TorchAO（pipeline 或手动）、Optimum Quanto（pipeline 或手动）。
Diffusers 管线预设¶
nf4-bnb通过 Diffusers 加载 4-bit NF4 BitsAndBytes 配置（仅 CUDA）。需要bitsandbytes与支持 BnB 的 diffusers。int4-torchao、int8-torchaofp8-torchao、fp8wo-torchao通过 Diffusers 使用 TorchAoConfig（CUDA）。需要torchao与较新的 diffusers/transformers。int8-quanto、int4-quanto、int2-quanto、fp8-quanto、fp8uz-quanto通过 Diffusers 使用 QuantoConfig。Diffusers 会将 FP8-NUZ 映射为 float8 权重；如需 NUZ 变体请使用手动 quanto 量化。.gguf检查点会被自动检测，并在可用时使用GGUFQuantizationConfig加载。需安装较新的 diffusers/transformers 以支持 GGUF。
Optimum Quanto¶
由 Hugging Face 提供的 optimum-quanto 在所有支持平台上表现可靠。
int8-quanto兼容性最好，通常效果也最佳- 在 RTX4090 及其它 GPU 上训练最快
- CUDA 设备对 int8/int4 使用硬件加速 matmul
- int4 仍然非常慢
- 支持
TRAINING_DYNAMO_BACKEND=inductor（torch.compile()） fp8uz-quanto是 CUDA 与 ROCm 的实验性 fp8 变体- 在 AMD Instinct 等新架构上支持更好
- 在 4090 上训练可能略快于
int8-quanto，但推理更慢（慢 1 秒） - 支持
TRAINING_DYNAMO_BACKEND=inductor（torch.compile()） fp8-quanto目前不使用 fp8 matmul，且在 Apple 系统不可用- CUDA/ROCm 仍缺少硬件 fp8 matmul，可能明显慢于 int8
- 使用 MARLIN 内核进行 fp8 GEMM
- 与 dynamo 不兼容，尝试组合时会自动禁用 dynamo
TorchAO¶
PyTorch 的新库 AO，可将线性层与 2D 卷积（如 unet 结构）替换为量化版本。
int8-torchao将内存占用降低到与 Quanto 各精度级别相当- 撰写时在 Apple MPS 上略慢（11s/iter），Quanto 为 9s/iter
- 不使用
torch.compile时，在 CUDA 上与int8-quanto速度与内存相当，ROCm 速度未知 - 使用
torch.compile时慢于int8-quanto fp8-nativeandfp8-torchao需要支持 FP8 scaled matmul 的 Ada Lovelace（RTX 40/L40S）、Hopper（H100/H200）或更新的加速器fp8-transformerengine会把符合条件的 Linear 层替换为 TransformerEngine FP8 模块，并用 TE FP8 autocast 包装模型 forward。使用pip install 'simpletuner[transformerengine]'安装；此 preset 面向 Ada Lovelace、Hopper 或更新的 CUDA 加速器。
优化器¶
TorchAO 提供通用 4bit/8bit 优化器：ao-adamw8bit、ao-adamw4bit
还提供面向 Hopper（H100 或更高）的优化器：ao-adamfp8、ao-adamwfp8
SDNQ（SD.Next Quantization Engine）¶
SDNQ 是针对训练优化的量化库，支持 AMD（ROCm）、Apple（MPS）、NVIDIA（CUDA）。它提供随机舍入与量化优化器状态，实现高效量化训练。
推荐精度等级¶
推荐精度等级¶
全量微调（更新模型权重）：
- uint8-sdnq - 内存节省与训练质量的最佳平衡
- uint16-sdnq - 更高精度，追求最高质量（例如 Stable Cascade）
- int16-sdnq - 有符号 16-bit 备选
- fp16-sdnq - 量化 FP16，结合 SDNQ 优势的最高精度
- fp8-sdnq - 使用 SDNQ 原生 FP8 matmul 的 FP8 权重，面向 H100/H200 级加速器
LoRA 训练（冻结基础模型权重）：
- int8-sdnq - 有符号 8-bit，通用选择
- int6-sdnq, int5-sdnq - 更低精度，更小内存
- uint5-sdnq, uint4-sdnq, uint3-sdnq, uint2-sdnq - 激进压缩
注记： int7-sdnq 可用但不推荐（慢，且比 int8 小不了多少）。
重要： 低于 5-bit 精度时，SDNQ 会自动启用 8 步 SVD（奇异值分解）以保持质量。SVD 量化更慢且非确定，因此 Disty0 在 Hugging Face 提供预量化的 SVD 模型。SVD 在训练中增加计算开销，所以对权重会更新的全量微调应避免使用。
关键特性： - 跨平台：在 AMD、Apple、NVIDIA 上表现一致 - 训练优化：使用随机舍入减少量化误差累积 - 内存高效：支持量化优化器状态缓冲 - 解耦矩阵乘：权重精度与 matmul 精度独立（支持 INT8/FP8/FP16 matmul）
SDNQ Native Matmul 选项¶
--sdnq_weights_dtype- 覆盖 SDNQ 存储 dtype，例如float8_e4m3fn、int8或uint4。--sdnq_quantized_matmul_dtype- Matmul dtype：auto、int8、float8_e4m3fn、fp8、float16或fp16。--sdnq_group_size- 量化 group size。-1表示整张量 static matmul；fp8-sdnq默认使用-1。--sdnq_use_quantized_matmul- 启用或禁用 SDNQ quantized matmul。未设置时，fp8-sdnq仅在 SDNQ compile 模式和 FP8 matmul 支持都可用时使用原生 FP8 matmul；其他 preset 跟随 SDNQ compile 可用性。--sdnq_compile_mode-auto、compile或eager。控制 SDNQ 内部torch.compile的使用。目前 SDNQ quantized matmul 需要 compile 模式；eager 模式使用 dequantized matmul。--sdnq_use_static_quantization、--sdnq_use_stochastic_rounding、--sdnq_dequantize_fp32- 覆盖 SDNQ 训练量化默认值。--sdnq_use_svd、--sdnq_svd_rank、--sdnq_svd_steps- 配置低 bit SDNQ preset 的 SVDQuant。--sdnq_use_hadamard、--sdnq_hadamard_group_size- 启用并配置 SDNQ Hadamard rotation。--sdnq_modules_to_not_convert、--sdnq_modules_to_not_use_matmul- JSON 数组、文件路径或逗号分隔的 module pattern。--sdnq_modules_dtype_dict、--sdnq_modules_quant_config- 用于逐模块 dtype/quantization 覆盖的 JSON 对象或文件路径。
SDNQ 优化器¶
SDNQ 提供可选量化状态缓冲的优化器以进一步节省内存：
sdnq-adamw- 带量化状态缓冲的 AdamW（uint8，group_size=32）sdnq-adamw+no_quant- 不量化状态的 AdamW（对比用）sdnq-adafactor- 带量化状态缓冲的 Adafactorsdnq-came- 带量化状态缓冲的 CAMEsdnq-lion- 带量化状态缓冲的 Lionsdnq-muon- 带量化状态缓冲的 Muonsdnq-muon+quantized_matmul- Muon 在 zeropower 计算中使用 INT8 matmul
所有 SDNQ 优化器默认使用随机舍入，可通过 --optimizer_config 设置如 use_quantized_buffers=false 以禁用状态量化。
Muon 特定选项：
- use_quantized_matmul - 在 zeropower_via_newtonschulz5 中启用 INT8/FP8/FP16 matmul
- quantized_matmul_dtype - matmul 精度：int8（消费级 GPU）、fp8（数据中心）、fp16
- zeropower_dtype - zeropower 计算精度（当 use_quantized_matmul=True 时忽略）
- 使用 muon_ 或 adamw_ 前缀为 Muon 与 AdamW 回退设置不同值
预量化模型： Disty0 在 huggingface.co/collections/Disty0/sdnq 提供预量化 uint4 SVD 模型。正常加载后，在导入 SDNQ 后调用 convert_sdnq_model_to_training() 进行转换（必须在加载前导入 SDNQ 以注册 Diffusers）。
检查点说明： SDNQ 训练模型会同时保存为训练恢复用的 PyTorch 原生格式（.pt）与推理用的 safetensors 格式。由于 SDNQ 的 SDNQTensor 使用自定义序列化，恢复训练必须使用原生格式。
磁盘节省提示： 可仅保留量化权重，需要推理时使用 SDNQ 的 dequantize_sdnq_training.py 进行反量化。
--quantization_config¶
- 内容：在
--quantize_via=pipeline时，用于覆盖 Diffusersquantization_config的 JSON 对象或文件路径。 - 方式：接受内联 JSON（或文件）定义组件级配置，键可包含
unet、transformer、text_encoder或default。 - 示例：
{
"unet": {"load_in_4bit": true, "bnb_4bit_quant_type": "nf4", "bnb_4bit_compute_dtype": "bfloat16"},
"text_encoder": {"quant_type": {"group_size": 128}}
}
该示例在 UNet 上启用 4-bit NF4 BnB，并在文本编码器上启用 TorchAO int4。
Torch Dynamo¶
在 WebUI 中启用 torch.compile()，前往 Hardware → Accelerate (advanced) 并将 Torch Dynamo Backend 设为你偏好的编译器（如 inductor）。额外开关可选择优化 mode、启用 dynamic shape 防护，或开启 regional compilation 以加快深层 Transformer 的冷启动。
相同配置可在 config/config.env 中表达：
可选与 --dynamo_mode=max-autotune 或 UI 中暴露的其他 Dynamo 参数搭配以细调。
注意训练前几个步骤会比平时慢，因为后台正在编译。
要将设置持久化到 config.json，添加等效键：
{
"dynamo_backend": "inductor",
"dynamo_mode": "max-autotune",
"dynamo_fullgraph": false,
"dynamo_dynamic": false,
"dynamo_use_regional_compilation": true
}
省略你希望继承 Accelerate 默认值的项（例如省略 dynamo_mode 以使用自动选择）。
--dynamo_wrapper¶
选择 TorchInductor 的 host wrapper。cpp 为默认值并减少调度开销；python 保留旧版本行为。该选择会写入 Mega-Cache 文件名和 manifest。
--dynamo_cache_export¶
累积 PyTorch Mega-Cache blob 的可选路径。SimpleTuner 会在编译前加载兼容 blob，在第一个成功的优化器步骤后导出，并在每次 checkpoint 和关闭时检查新的 artifact key。<路径>.manifest.json 会记录 PyTorch/Triton/GPU 运行时和 SHA256。未覆盖的 shape 会正常编译，其产物会加入下一次导出。只应加载可信的缓存 blob。
当该值是目录、以路径分隔符结尾或没有扩展名时，SimpleTuner 会根据模型、运行时、加速器和影响计算图的配置生成稳定文件名，并在 Hub 上查找同名文件。
--dynamo_cache_export_after_first_step¶
为 true（默认）时，在第一个成功的优化器步骤后导出 Mega-Cache。设为 false 只会跳过这次早期导出；checkpoint 和训练结束导出仍会执行。
--dynamo_hub_repo_id¶
用于获取和发布 --dynamo_cache_export blob 的可选 Hugging Face 仓库。Blob 与 manifest 会在一次 commit 中上传；不存在的仓库会创建为 private。Hub 故障不会中止训练，本地导出仍会保留。
--attention_mechanism¶
支持多种注意力机制，兼容性与权衡不同：
diffusers使用 PyTorch 原生 SDPA 内核。xformers在模型暴露enable_xformers_memory_efficient_attention时启用 Meta 的 xformers 注意力内核（训练+推理）。flash-attn、flash-attn-2、flash-attn-3、flash-attn-3-varlen接入 Diffusers 的attention_backend，将注意力路由到 FlashAttention v½/3 内核。需安装对应的flash-attn/flash-attn-interface，且 FA3 目前需要 Hopper GPU。flex选择 PyTorch 2.5 的 FlexAttention 后端（CUDA 上 FP16/BF16）。需单独编译/安装 Flex 内核，见 documentation/attention/FLEX.md。kohaku-fa在 SM86 Ampere GPU（RTX 30 系列/A40）、Ada GPU（RTX 40 系列/L40S，sm_89）、H100（sm_90）和 RTX Blackwell（sm_120）上使用本地 CuTe 内核，在 B200/B300（sm_100/sm_103）上使用内置的 KohakuFA 内核。CuTe 可通过pip install "simpletuner[attention-cute]"安装，需要 PyTorch >= 2.11、CUTLASS DSL >= 4.8、TVM FFI >= 0.1.14、Ninja >= 1.11 和 C++17 编译器。原生扩展在首次使用时编译。B200/B300 需要 PyTorch >= 2.9 和 Triton >= 3.7。无需外部注意力包。直接 PyTorch SDPA 和 Diffusers 原生注意力均使用此后端。支持同类型 FP16/BF16 Q/K/V、布尔掩码、1..512 的头维度和分组查询注意力；拒绝 FP32 输入、加性掩码、dropout、上下文并行和 MiniMax-H3 稀疏注意力。CuTe 分别保存未缩放的行最大值与对数归一化项，使用中心化的 FP32 反向修正，并在 FP32 累加后缩放梯度。RTX Blackwell 使用中心化反向传播和针对该架构调整的分块配置。kohaku-fa-auto是默认的自动训练策略。安装所需依赖后，它为兼容的 CUDA 调用选择 Kohaku；CPU/MPS、不支持的 GPU、FP32、dropout、加性掩码、不支持的头维度和模型功能使用原生 SDPA。评估保留原生注意力路径。选中的 Kohaku 导入、编译和内核错误不会被隐藏。显式设置diffusers可让所有调用使用原生 SDPA。更高精度的计算可能增加训练步耗时；测量中，H100 上编译后的 Flux 和 MiniMax 模块分别比原生 SDPA 慢约 7.9% 和 6.0%。 自动 CuTe 选择支持 sm_86/sm_89/sm_90/sm_120，中心化反向传播可保留饱和注意力中的微小梯度；B200/B300 在此策略下使用原生 SDPA。metal-flash-attention在 Apple Silicon 上使用 Universal Metal Flash Attention 的 PyTorch custom-op 后端。请先安装 UMFA 的examples/pytorch-custom-op-ffi包；SimpleTuner 通过 PyTorch 的 MPS SDPA dispatcher 路由注意力，当前 UMFA build 会注册该 dispatcher。符合条件的 MPS FP32/FP16/BF16 4D SDPA 调用 —— 任意 head 数量（含 single-head）、任意 sequence length、transposed FLUX-style layouts、最多 4D 的 bool/additive masks、以及 causal 调用（含训练 —— causal backward 通过精确梯度一致性验证） —— 会直接编码进 PyTorch 的 MPS command stream，没有每次调用的同步；FP16/BF16 输入使用原生低精度 kernel，不会提升为 FP32。带 dropout 或enable_gqa的调用会 fallback 到 PyTorch SDPA；旧的PrivateUse1build 会被torch.device("mps")tensors 绕过。SimpleTuner 会在启动时做 FP32/FP16/BF16 forward 和 autograd 数值一致性检查，以及 causal forward parity，并拒绝数值不匹配或不暴露get_dispatch_stats()的 UMFA build。metal-flash-attention-int8和metal-flash-attention-int4会通过set_quantization_mode(ext.QUANT_INT8, ext.QUANT_BLOCK_WISE)或set_quantization_mode(ext.QUANT_INT4, ext.QUANT_BLOCK_WISE)设置 UMFA 的全局 blockwise quantization mode，切换 backend 时清除该模式，并需要额外的启动检查来确认输出连接 autograd、multi-head 梯度有限、dispatcher-level bool/additive mask 支持且没有 PyTorch fallback。运行中可使用metal_sdpa_extension.get_dispatch_stats()确认fp32_instream（量化别名则为quantized_autograd）增加且pytorch_fallback保持为0；all-true bool masks 还会增加mask_all_true_skipped。扩展还提供rope_scaled_dot_product_attention，一个符合 FLUX.1/FLUX.2/Krea2/Z-Image interleaved-pair rotary 约定的融合 RoPE+SDPA 入口；训练走融合 autograd（backward 中对 dQ/dK 应用逆旋转）；需要梯度的带 mask 或 GQA 调用则 fallback 到 eager 旋转。cudnn、native-efficient、native-flash、native-math、native-npu、native-xla选择torch.nn.attention.sdpa_kernel暴露的对应 SDPA 后端。适合需要确定性（native-math）、CuDNN SDPA 内核或厂商原生加速器（NPU/XLA）的场景。sla启用 Sparse–Linear Attention (SLA)，提供可调的稀疏/线性混合内核，训练与验证均可使用。- 选择该后端前请安装 SLA 包（例如
pip install -e ~/src/SLA）。 - SimpleTuner 会将 SLA 学到的投影权重保存到每个检查点内的
sla_attention.pt，恢复与推理时需保留该文件以保持 SLA 状态。 - 由于骨干网络围绕 SLA 的混合稀疏/线性行为进行调优，推理时也需要 SLA。详见
documentation/attention/SLA.md。 - 如需实验，可使用
--sla_config '{"topk":0.15,"blkq":32,"tie_feature_map_qk":false}'（JSON 或 Python dict）覆盖 SLA 默认运行时设置。 sageattention、sageattention-int8-fp16-triton、sageattention-int8-fp16-cuda、sageattention-int8-fp8-cuda包装对应的 SageAttention 内核。这些面向推理，必须配合--sageattention_usage防止误用于训练。- 简单来说，SageAttention 可降低推理计算量。
ℹ️ Flash/Flex/PyTorch 后端选择依赖 Diffusers 的
attention_backend分发器，因此目前主要受益于已启用该路径的 Transformer 风格模型（Flux、Wan 2.x、LTXVideo、QwenImage 等）。经典 SD/SDXL UNet 仍直接使用 PyTorch SDPA。
使用 --sageattention_usage 启用 SageAttention 训练需谨慎，因为其自定义 CUDA 实现不会为 QKV 线性层追踪或传播梯度。
- 这会导致这些层完全未训练，可能引发模型崩塌，或仅在短期训练中带来轻微改善。
📰 Publishing¶
--push_to_hub¶
- 内容：提供后，训练完成会将模型上传至 Hugging Face Hub。使用
--push_checkpoints_to_hub还会推送每个中间检查点。
--push_to_hub_background¶
- 内容：使用后台工作线程上传至 Hugging Face Hub，使检查点推送不会暂停训练循环。
- 原因：Hub 上传异步进行，同时训练与验证继续运行。最终上传仍会在结束前等待，以确保失败可见。
--webhook_config¶
- 内容：Webhook 目标配置（如 Discord、自定义端点），用于实时接收训练事件。
- 原因：允许通过外部工具和看板监控训练进度，在关键阶段接收通知。
- 说明：可在训练前设置
SIMPLETUNER_JOB_ID环境变量以填充 webhook payload 的job_id字段： 对接多个训练任务的监控工具可据此识别事件来源。若未设置 SIMPLETUNER_JOB_ID，webhook payload 中 job_id 为 null。
--publishing_config¶
- 内容：可选 JSON/dict/文件路径，描述非 Hugging Face 的发布目标（S3 兼容存储、Backblaze B2、Azure Blob Storage、Dropbox）。
- 原因：与
--webhook_config解析方式一致，可将产物分发到 Hub 之外。发布在验证后由主进程使用当前output_dir执行。 - 说明：这些目标可与
--push_to_hub叠加使用。启用前请在.venv中安装相应 SDK（例如boto3、azure-storage-blob、dropbox）。完整示例见documentation/publishing/README.md。
--hub_model_id¶
- 内容：Hugging Face Hub 模型名称与本地结果目录名。
- 原因：该值用作
--output_dir下的目录名称。若设置--push_to_hub，这将成为 Hugging Face Hub 上的模型名。
--model_card_base_model¶
- 作用：在生成的模型卡和通用 LoRA 推理示例中使用的 Hugging Face 基础模型仓库 ID。
- 默认值：未设置；当
--pretrained_model_name_or_path是 Hub ID 时使用该值。本地路径会替换为<model_family>/unknown-model。 - 适用情况：从本地或容器内置检查点训练且已知原始仓库时设置。此选项只更改发布的元数据，不会改变训练时加载的权重。请使用
black-forest-labs/flux-3-image-klein-base这样的仓库 ID，而不是文件路径或 URL。
--modelspec_comment¶
- 内容：嵌入到 safetensors 文件元数据中的文本，键为
modelspec.comment - 默认值：None（禁用）
- 说明：
- 在外部模型查看器（ComfyUI、模型信息工具）中可见
- 接受字符串或字符串数组（用换行符连接）
- 支持
{env:VAR_NAME}占位符用于环境变量替换 - 在写入元数据时支持
{current_step}、{current_epoch}和{timestamp} {timestamp}使用 UTC ISO 8601 值- 每个检查点使用保存时的当前配置值
示例（字符串）：
示例（数组，多行）：
--disable_benchmark¶
- 内容：禁用启动时在 step 0 的验证/基准测试。其输出会拼接到训练模型验证图像的左侧。
📂 数据存储与管理¶
--data_backend_config¶
- 内容：SimpleTuner 数据集配置路径。
- 原因：可将不同存储介质上的多个数据集组合到同一训练会话中。
- 说明：
- 从
config.json和config.toml读取的字符串值支持{env:VAR_NAME} - 被引用的
multidatabackend.json内部字符串值也支持{env:VAR_NAME} - 示例：配置示例见 multidatabackend.json.example，更多信息见 此文档。
--override_dataset_config¶
- 内容：提供后允许 SimpleTuner 忽略缓存配置与当前配置之间的差异。
- 原因：SimpleTuner 首次在数据集上运行时会创建缓存文档，其中包含数据集配置（包括
crop与resolution等）。随意或误改这些值可能导致训练随机崩溃，因此不建议使用该参数，最好通过其他方式解决配置差异。
--data_backend_sampling¶
- 内容：多数据后端时可选择不同采样策略。
- 选项：
uniform- v0.9.8.1 及更早版本的行为，不考虑数据集长度，只按手动概率权重采样。auto-weighting- 默认行为，使用数据集长度均匀采样各数据集，以保持整体分布均匀。- 当数据集大小不同但希望模型均衡学习时必须使用。
- 但 Dreambooth 图像与正则化集的正确采样需要手动调整
repeats。
--vae_cache_scan_behaviour¶
- 内容：配置完整性扫描的行为。
- 原因：数据集可能在多个训练阶段被错误配置，例如误删
.json缓存并改用方形裁剪配置，导致缓存不一致。可在multidatabackend.json中设置scan_for_errors=true进行修复。扫描时会根据--vae_cache_scan_behaviour决定如何修复不一致：recreate（默认）删除异常缓存以重建，sync则更新桶元数据以匹配真实样本。推荐值：recreate。
--enable_nsfw_check¶
- 内容：在 VAE 缓存预处理期间启用 NSFW 分类器强制检查。
- 默认值：
false。 - 说明：只扫描 VAE 缓存即将处理的未缓存样本。已有 VAE 缓存和
skip_file_discovery=vae会被信任，不会重新扫描。 - 更多信息：隐私和责任说明见 NSFW.zh.md，VAE 缓存细节见 DATALOADER.zh.md#nsfw-classifier-checks-during-vae-caching。
--nsfw_check_models¶
- 内容：Hugging Face Transformers 图像分类模型的 CSV 列表。可用
:threshold=0.5为单个模型指定阈值。 - 默认值：
Falconsai/nsfw_image_detection:threshold=0.5,AdamCodd/vit-base-nsfw-detector:threshold=0.5。 - 说明：仅支持标准 Transformers 模型。不会启用
trust_remote_code，也不会加载依赖timm的分类器。
--nsfw_check_min_votes¶
- 内容：一帧被拒绝前，必须返回 NSFW 结果的分类器数量。
- 默认值：
2。 - 说明：必须至少为
1，且不能大于已配置分类器数量。
--nsfw_check_backend_types¶
- 内容：需要扫描的数据后端
type值 CSV 列表。 - 默认值：
all。 - 示例：
local,huggingface,csv,aws。
--nsfw_check_sample_types¶
- 内容：需要扫描的数据集
dataset_type值 CSV 列表。 - 默认值：
image,conditioning。 - 说明：评估数据集不会被扫描。
--delete_nsfw_images¶
- 内容：后端支持删除时，删除被 NSFW 分类器拒绝的源样本。
- 默认值：
false。 - 说明：禁用时，拒绝样本只会从当前运行的元数据中移除，源数据集文件保留。
--nsfw_check_video_frame_count¶
- 内容：从视频或多帧 conditioning 输入中抽样的帧数。
- 默认值：
3。
--nsfw_check_video_frame_selection¶
- 内容：视频 NSFW 检查的帧选择模式。
- 默认值：
uniform。 - 选项：
uniform、first、middle。
--nsfw_check_video_min_flagged_frames¶
- 内容：拒绝整个样本前，必须被拒绝的已检查视频帧数。
- 默认值：
1。
--dataloader_prefetch¶
- 内容：提前加载批次。
- 原因：当批次较大时，从磁盘（即使是 NVMe）加载会导致训练“停顿”，影响 GPU 利用率。启用预取会保持批次缓冲，便于即时加载。
⚠️ 这主要适用于 H100 或更高、低分辨率且 I/O 成为瓶颈的场景。对大多数用途而言属于不必要的复杂度。
--dataloader_prefetch_qlen¶
- 内容：增减内存中缓存的批次数。
- 原因：启用预取后，默认每个 GPU/进程保留 10 个条目。该值可调以增加或减少预取批次数。
--dataloader_prefetch_device_threshold_mb¶
- 内容：指定 dataloader 预取进行页锁定并通过专用 CUDA 流传输的最小 CPU 唯一批次载荷（MiB）。
0表示禁用设备暂存。 - 原因：非常大的缓存嵌入可能会使主机到设备的传输与模型计算串行执行。此选项让传输与 GPU 计算重叠。
- 内存：每个暂存的队列条目都会同时消耗固定主机内存和加速器内存。请从
dataloader_prefetch_qlen: 2开始，并在增大前进行性能分析。 - 兼容性：需要
dataloader_prefetch: true和 CUDA。不支持与上下文并行同时使用。
--compress_disk_cache¶
- 内容：压缩磁盘上的 VAE 与文本嵌入缓存。
- 原因：DeepFloyd、SD3、PixArt 使用的 T5 编码器生成的文本嵌入很大，短或重复字幕会产生大量空白。启用
--compress_disk_cache可节省最多 75% 空间，平均约 40%。
⚠️ 需要手动删除已有缓存目录，以便训练器以压缩方式重建。
🌈 图像与文本处理¶
许多设置通过 dataloader 配置 控制，但以下设置为全局生效。
--resolution_type¶
- 内容：指定 SimpleTuner 使用
area面积计算还是pixel边长计算。pixel_area为混合方式，用像素代替百万像素表示area。 - 选项：
resolution_type=pixel_arearesolution设为 1024 时，会内部映射为准确面积以便高效分桶。- 结果尺寸示例：1024x1024、1216x832、832x1216
resolution_type=pixel- 数据集内所有图像会将短边缩放到该分辨率，可能导致较高显存占用。
- 结果尺寸示例：1024x1024、1766x1024、1024x1766
resolution_type=area- 已弃用。请使用
pixel_area。
- 已弃用。请使用
--resolution¶
- 内容：输入图像分辨率（短边像素长度）
- 默认：1024
- 说明：若数据集未设置分辨率，该值为全局默认。
--validation_resolution¶
- 内容：输出图像分辨率（像素），或
widthxheight格式（如1024x1024）。可用逗号分隔多个分辨率。 - 原因：验证阶段生成的所有图像都将使用该分辨率。适用于训练分辨率与验证分辨率不同的场景。
--validation_method¶
- 内容：选择验证运行方式。
- 选项：
simpletuner-local（默认）使用内置管线；external-script运行用户提供的可执行文件。 - 原因：可将验证交给外部系统，无需本地管线暂停训练。
--validation_external_script¶
- 内容：当
--validation_method=external-script时运行的可执行命令。使用 shell 风格切分，请正确引用命令字符串。 - 占位符：可嵌入这些 token（
.format格式）以传递训练上下文。缺失值默认替换为空字符串（除非另有说明）： {local_checkpoint_path}→output_dir下最新检查点目录（至少存在一个检查点）。{local_checkpoint_path}→output_dir下最新检查点目录（至少存在一个检查点）。{global_step}→ 当前全局步数。{tracker_run_name}→--tracker_run_name的值。{tracker_project_name}→--tracker_project_name的值。{model_family}→--model_family的值。{model_type}/{lora_type}→ 模型类型与 LoRA 变体。{huggingface_path}→--hub_model_id的值（若已设置）。{remote_checkpoint_path}→ 最近一次上传的远程 URL（验证钩子为空）。- 任意
validation_*配置值（例如validation_num_inference_steps、validation_guidance、validation_noise_scheduler）。 - 示例：
--validation_external_script="/opt/tools/validate.sh {local_checkpoint_path} {global_step}"
--validation_external_background¶
- 内容：启用后，
--validation_external_script会在后台启动（fire-and-forget）。 - 原因：无需等待外部脚本即可继续训练；该模式不检查退出码。
--post_upload_script¶
- 每次内置验证完成后（WebUI 手动验证、定时验证或基础模型基准测试），如果未配置发布提供者，也会运行此脚本。此时，
{local_checkpoint_path}为output_dir（无需检查点），{remote_checkpoint_path}为空。已配置的提供者仍在每次成功上传后运行一次钩子，并使用其返回的路径；上传失败不会触发本地钩子。跳过、失败或中止的验证，以及外部脚本的启动，都不会触发此完成钩子。 - 内容：每个发布目标与 Hugging Face Hub 上传完成后运行的可执行脚本（最终模型与检查点上传）。异步运行，不阻塞训练。
- 占位符：与
--validation_external_script相同的替换，加上{remote_checkpoint_path}（提供者返回的 URI），可用于将发布 URL 传递给下游系统。 - 说明：
- 脚本按提供者/上传逐次运行；错误会记录但不会中止训练。
- 即使没有远程上传也会调用，可用于本地自动化（例如在另一块 GPU 上推理）。
- SimpleTuner 不会读取脚本结果；如需记录指标或图像，请直接写入你的追踪器。
- 示例：
--post_upload_script='/opt/hooks/notify.sh {remote_checkpoint_path} {tracker_project_name} {tracker_run_name}'/opt/hooks/notify.sh向追踪系统提交的示例： - 可用示例：
simpletuner/examples/_shared/external-validation/replicate_post_upload.py展示 Replicate 钩子，使用{remote_checkpoint_path}、{model_family}、{model_type}、{lora_type}、{huggingface_path}在上传后触发推理。simpletuner/examples/_shared/external-validation/wavespeed_post_upload.py展示 WaveSpeed 钩子，使用相同占位符并包含异步轮询。simpletuner/examples/_shared/external-validation/fal_post_upload.py展示 fal.ai Flux LoRA 钩子（需要FAL_KEY）。simpletuner/examples/_shared/external-validation/use_second_gpu.py在第二块 GPU 上运行 Flux LoRA 推理，即使没有远程上传也能工作。
--post_checkpoint_script¶
- 内容：每个检查点目录写入磁盘后立即运行的可执行文件（在任何上传开始之前）。在主进程中异步运行。
- 占位符：与
--validation_external_script相同的替换，包括{local_checkpoint_path}、{global_step}、{tracker_run_name}、{tracker_project_name}、{model_family}、{model_type}、{lora_type}、{huggingface_path}以及任何validation_*值。该钩子中{remote_checkpoint_path}为空。 - 说明：
- 对定期/手动/滚动检查点都会触发，保存完成即执行。
- 适合触发本地自动化（复制到其他卷、运行评估作业），无需等待上传完成。
- 示例：
--deepfloyd_validation_pipeline_mode¶
- 内容：控制 DeepFloyd 验证时的阶段串联方式。
- 选项：
auto,trained-stage,full-pipeline - 默认值：
auto - 原因：
auto在提示词验证中运行 DeepFloyd stage I → stage II；显式使用数据集图片验证时只运行正在训练的阶段。需要保持单阶段验证时使用trained-stage，需要强制加载前后固定阶段时使用full-pipeline。
--deepfloyd_validation_stage1_model¶
- 内容：通过完整管线验证正在训练的 stage II 时使用的固定 stage I 模型。
- 默认值：
DeepFloyd/IF-I-XL-v1.0
--deepfloyd_validation_stage2_model¶
- 内容：通过完整管线验证正在训练的 stage I 时使用的固定 stage II 模型。
- 默认值：
DeepFloyd/IF-II-M-v1.0
--deepfloyd_validation_stage3_mode¶
- 内容：DeepFloyd stage II 之后可选的最终放大器。
- 选项：
none,sd-x4-upscaler - 默认值：
none - 原因：DeepFloyd 未发布的 stage III 本质上是 4x 放大器。
sd-x4-upscaler使用stabilityai/stable-diffusion-x4-upscaler承担这个角色。
--deepfloyd_validation_stage3_model¶
- 内容：当
--deepfloyd_validation_stage3_mode=sd-x4-upscaler时使用的模型仓库。 - 默认值：
stabilityai/stable-diffusion-x4-upscaler
--deepfloyd_validation_stage1_num_inference_steps¶
- 内容：可选的 stage I 验证步数覆盖。
- 默认值：使用
--validation_num_inference_steps，stage I 最多 30 步。
--deepfloyd_validation_stage2_num_inference_steps¶
- 内容：可选的 stage II 验证步数覆盖。
- 默认值：使用
--validation_num_inference_steps
--deepfloyd_validation_stage1_guidance¶
- 内容：可选的 stage I 验证 guidance 覆盖。
- 默认值：使用
--validation_guidance
--deepfloyd_validation_stage2_guidance¶
- 内容：可选的 stage II 验证 guidance 覆盖。
- 默认值：使用
--validation_guidance
--deepfloyd_validation_stage3_guidance¶
- 内容：可选的 SD x4 放大器 guidance 覆盖。
- 默认值：使用
--validation_guidance
--deepfloyd_validation_stage3_noise_level¶
- 内容：传给 SD x4 放大器的噪声级别。
- 默认值：
100
--wan_validation_load_other_stage¶
- 内容：验证时加载 Wan 2.2 的相反阶段。
- 默认值：
false - 原因：Wan 2.2 以及 AnimeGen 等兼容的分阶段模型可以单独训练任一阶段。启用后会加载固定的配对阶段，使验证使用完整的双阶段管线，并在配置的边界处切换 denoiser。
--sdxl_validation_pipeline_mode¶
- 选项：
trained-stage,full-pipeline - 默认值：
trained-stage - 内容：选择 SDXL 验证只运行已训练阶段，还是运行拆分的 base/refiner 管线。
- 原因：
full-pipeline会让 stage 1 以 latent 输出运行到1 - refiner_training_strength，然后从同一 schedule 边界继续运行 stage 2。
--sdxl_validation_stage1_model¶
- 内容：full-pipeline 验证使用已训练 stage 2 模型进行 refine 时加载的固定 SDXL stage 1/base 模型。
- 默认值：从所选 SDXL 版本推断，通常是
stabilityai/stable-diffusion-xl-base-1.0
--sdxl_validation_stage2_model¶
- 内容：full-pipeline 验证先运行已训练 stage 1 模型时加载的固定 SDXL stage 2/refiner 模型。
- 默认值：从所选 SDXL 版本推断，通常是
stabilityai/stable-diffusion-xl-refiner-1.0
--pixart_validation_pipeline_mode¶
- 选项：
trained-stage,full-pipeline - 默认值：
trained-stage - 内容：选择 PixArt 验证只运行已训练阶段，还是运行 v0.7 拆分管线。
- 原因：
full-pipeline会让 stage 1 以 latent 输出运行到1 - refiner_training_strength，然后从同一 schedule 边界继续运行 stage 2。
--pixart_validation_stage1_model¶
- 内容：full-pipeline 验证使用已训练 stage 2 模型进行 refine 时加载的固定 PixArt stage 1 模型。
- 默认值：
terminusresearch/pixart-900m-1024-ft-v0.7-stage1
--pixart_validation_stage2_model¶
- 内容：full-pipeline 验证先运行已训练 stage 1 模型时加载的固定 PixArt stage 2 模型。
- 默认值：
terminusresearch/pixart-900m-1024-ft-v0.7-stage2
--validation_adapter_path¶
- 内容：在计划验证时临时加载单个 LoRA 适配器。
- 格式：
- Hugging Face 仓库：
org/repo或org/repo:weight_name.safetensors（默认pytorch_lora_weights.safetensors）。 - 指向 safetensors 适配器的本地文件或目录路径。
- 说明：
- 与
--validation_adapter_config互斥，同时提供会报错。 - 适配器仅在验证运行期间挂载（基线训练权重不变）。
--validation_adapter_name¶
- 内容：对
--validation_adapter_path加载的临时适配器指定可选标识。 - 原因：控制日志/Web UI 中的标注方式，保证多个适配器顺序测试时名称可预测。
--validation_adapter_strength¶
- 内容：启用临时适配器时的强度倍率（默认
1.0）。 - 原因：无需改变训练状态即可在验证中尝试更轻/更重的 LoRA 缩放；接受任意大于零的值。
--validation_adapter_mode¶
- 选项：
adapter_only、comparison、none - 内容：
adapter_only：仅用临时适配器运行验证。comparison：同时生成基础模型与启用适配器的样本，便于并排对比。none：跳过适配器挂载（保留 CLI 参数但禁用功能）。
--validation_adapter_config¶
- 内容：描述多个验证适配器组合的 JSON 文件或内联 JSON。
- 格式：可为数组，或包含
runs数组的对象。每个条目可包含： label: 在日志/UI 中显示的友好名称。path: Hugging Face 仓库 ID 或本地路径（同--validation_adapter_path）。adapter_name: 每个适配器的可选标识。strength: 可选标量覆盖。target_stage: 此适配器的可选多阶段验证目标。支持的别名取决于模型；常见值包括one、two、stage1、stage2以及 Wan 的high/low。adapters/paths: 在同一次运行中加载多个适配器的对象/字符串数组。- 说明：
- 提供该配置后，单适配器选项（
--validation_adapter_path、--validation_adapter_name、--validation_adapter_strength、--validation_adapter_mode）在 UI 中会被忽略/禁用。 - 每个 run 会逐个加载，并在下一个 run 开始前完全卸载。
--validation_preview¶
- 内容：使用 Tiny AutoEncoder 在扩散采样中流式输出验证预览
- 默认：False
- 原因：实时预览验证图像生成过程。通过轻量 Tiny AutoEncoder 解码并通过 webhook 回调发送，使你无需等待完整生成。
- 说明：
- 仅适用于支持 Tiny AutoEncoder 的模型家族（如 Flux、SDXL、SD3）
- 需要 webhook 配置以接收预览图像
- 使用
--validation_preview_steps控制预览频率
--validation_preview_steps¶
- 内容：验证预览解码与流式输出的间隔
- 默认：1
- 原因：控制验证采样中解码中间潜变量的频率。设为更高值（如 3）可减少 Tiny AutoEncoder 解码开销。
- 示例：当
--validation_num_inference_steps=20且--validation_preview_steps=5时，生成过程在 5、10、15、20 步各收到 1 张预览图，共 4 张。
--evaluation_type¶
- 内容：在验证期间启用 CLIP 评估生成图像。
- 原因：CLIP 分数计算生成图像特征与验证提示词之间的距离，可用于判断提示词一致性是否提升，但需要大量验证提示词才有意义。
- 选项："none" 或 "clip"
- 调度：使用
--eval_steps_interval进行步数调度，或--eval_epoch_interval进行 epoch 调度（如0.5表示每个 epoch 多次）。若两者都设定，训练器会记录警告并同时运行。
--eval_loss_disable¶
- 内容：在验证期间禁用评估损失计算。
- 原因：配置评估数据集后会自动计算损失；若启用 CLIP 评估，两者都会运行。此标志可在保留 CLIP 的同时关闭评估损失。
--validation_using_datasets¶
- 内容：使用训练数据集中的图像进行验证，而非纯文本到图像生成。
- 原因：启用图像到图像（img2img）或图像到视频（i2v）验证模式，模型使用训练图像作为条件输入。适用于：
- 测试需要输入图像的编辑/修复模型
- 评估模型对图像结构的保留程度
- 支持双重文本到图像和图像到图像工作流的模型（如 Flux2、LTXVideo2）
- I2V 视频模型（HunyuanVideo、WAN、Kandinsky5Video）：使用图像数据集中的图像作为视频生成验证的首帧条件输入
- 注意：
- 需要模型注册
IMG2IMG或IMG2VIDEO管线 - 可与
--eval_dataset_id结合从特定数据集获取图像 - 对于 i2v 模型，这允许使用简单的图像数据集进行验证，而无需设置训练时使用的复杂条件数据集配对
- Flux Kontext 不使用此标志进行验证；请保持其关闭，并使用
--eval_dataset_id选择编辑数据集，Kontext 会自动加载其配对的参考数据集 - 去噪强度由正常的验证时间步设置控制
--validation_input¶
- 内容：验证输入图像路径和提示词的 JSON 列表，例如
[{"path": "/data/val/frame.png", "prompt": "缓慢向前推进的镜头"}]。 - 原因：无需创建验证数据集即可进行图像条件验证。
- 注意：
- 每个条目必须包含
path和prompt；可选的shortname或name用于控制输出标签。 - 准备验证提示词时，图像路径必须在本地存在。
- 设置后，这些条目会作为验证输入图像使用，而不是从数据集中发现验证样本。
--eval_dataset_id¶
- 内容：用于评估/验证图像来源的特定数据集 ID。
- 原因：使用
--validation_using_datasets或基于条件的验证时，控制哪个数据集提供输入图像： - 无此选项时，从所有训练数据集随机选择图像
- 有此选项时，仅使用指定数据集进行验证输入
- 注意：
- 数据集 ID 必须与数据加载器配置中的已配置数据集匹配
- 适用于使用专用评估数据集保持评估一致性
- 对于条件模型，数据集的条件数据（如有）也会被使用
- 对于 Flux Kontext，这是选择验证数据集的正确方式；不要启用
--validation_using_datasets
理解条件化和验证模式¶
SimpleTuner 为使用条件输入（参考图像、控制信号等）的模型支持三种主要范式：
1. 需要条件化的模型¶
部分模型没有条件输入无法运行：
- Flux Kontext：编辑式训练始终需要参考图像
- ControlNet 训练：需要控制信号图像
对于这些模型，条件数据集是强制性的。WebUI 将条件选项显示为必需，没有它们训练将失败。
Flux Kontext 的验证也始终走这条基于条件的路径。使用 --eval_dataset_id 选择用于验证的编辑数据集，并保持 --validation_using_datasets 为关闭状态。
2. 支持可选条件化的模型¶
部分模型可在文本到图像和图像到图像两种模式下运行：
- Flux2：支持可选参考图像的双重 T2I/I2I 训练
- LTXVideo2：支持可选首帧条件的 T2V 和 I2V（图像到视频）
- LongCat-Video：支持可选帧条件
- HunyuanVideo i2v：支持首帧条件的 I2V（型号：
i2v-480p、i2v-720p等） - WAN i2v：支持首帧条件的 I2V
- Kandinsky5Video i2v：支持首帧条件的 I2V
对于这些模型，你可以添加条件数据集但不是必需的。WebUI 将条件选项显示为可选。
I2V 验证快捷方式：对于 i2v 视频模型，你可以使用 --validation_using_datasets 配合图像数据集（通过 --eval_dataset_id 指定）直接获取验证条件图像，而无需设置训练时使用的完整条件数据集配对。
3. 验证模式¶
| 模式 | 标志 | 行为 |
|---|---|---|
| 文本到图像/视频 | （默认） | 仅从文本提示生成 |
| 基于数据集（img2img） | --validation_using_datasets |
对数据集中的图像部分去噪 |
| 基于数据集（i2v） | --validation_using_datasets |
对于 i2v 视频模型，使用图像作为首帧条件 |
| 基于条件 | （配置条件时自动） | 验证时使用条件输入 |
组合模式：当模型支持条件化且 --validation_using_datasets 已启用时：
- 验证系统从数据集获取图像
- 如果这些数据集有条件数据，会自动使用
- 使用 --eval_dataset_id 控制哪个数据集提供输入
I2V 模型与 --validation_using_datasets：对于 i2v 视频模型（HunyuanVideo、WAN、Kandinsky5Video），启用此标志允许你使用简单的图像数据集进行验证。图像作为首帧条件输入用于生成验证视频，无需复杂的条件数据集配对设置。
Flux Kontext 与 --validation_using_datasets：不要启用此标志。Kontext 是纯编辑模型，验证会通过其常规的成对图像 + 条件数据集路径运行。请改用 --eval_dataset_id 选择编辑数据集。
条件数据类型¶
不同模型期望不同的条件数据：
| 类型 | 模型 | 数据集设置 |
|---|---|---|
conditioning |
ControlNet, Control | 数据集配置中 type: conditioning |
image |
Flux Kontext | type: image（标准图像数据集） |
latents |
Flux, Flux2 | 条件自动 VAE 编码 |
--caption_strategy¶
- 内容：派生图像字幕的策略。选项：
textfile,filename,parquet,instanceprompt - 原因：决定训练图像的字幕生成方式。
textfile使用与图像同名的.txt文件内容filename对文件名做清理后作为字幕parquet需要数据集中存在 parquet 文件，默认使用caption列，除非指定parquet_caption_column。如未提供parquet_fallback_caption_column，所有字幕都必须存在。instanceprompt使用数据集配置中的instance_prompt作为所有图像的提示词。
--conditioning_multidataset_sampling¶
- 内容：多条件数据集的采样方式。选项：
combined,random - 原因：当训练使用多个条件数据集（如多参考图或控制信号）时，决定如何使用它们：
combined将条件输入拼接在一起，训练时同时展示。适用于多图合成任务。random每个样本随机选择一个条件数据集，在训练中切换条件。- 说明：使用
combined时不能在条件数据集中定义单独的captions，会使用源数据集的字幕。 - 另见：DATALOADER.md 获取多条件数据集配置说明。
--flux3_prompt_upsample¶
默认值: false
此选项默认关闭。启用后，SimpleTuner 会下载独立的 Qwen3.5-9B 模型（权重约 19 GB），在缓存文本嵌入之前扩写正向提示词。编辑任务会使用配对参考图。负向提示词、dropout 空描述和原始描述文件均保持不变。
请预留额外系统内存和预处理时间。扩写模型与文本编码器轮流使用 GPU，生成的嵌入会在训练中复用。SimpleTuner 将扩写嵌入与原始嵌入分别保存，再次选择相同参考图时可复用缓存结果。
--moss_image_auto_json¶
使用 MOSS-Image 原生 summary/items JSON 布局格式编码正向描述。默认值：false。普通描述会封装为 JSON，不会凭空添加物体位置；现有布局会被验证并序列化。空提示词和负向提示词保持不变。
--moss_image_prompt_upsample¶
在缓存文本嵌入前，使用视觉语言模型将正向描述扩写为详细的原生 JSON 布局。默认值：false。根据训练图像生成描述和边界框，并使用实际分桶尺寸。验证提示词也会扩写，同时启用原生 JSON 转换。
--moss_image_prompt_upsampler_model_id¶
描述模型的仓库或本地路径。默认值：Qwen/Qwen3.5-27B。与 moss_image_prompt_upsample 配合使用。默认模型需要 80 GB GPU 和额外系统内存，与文本编码器轮流使用 GPU。更换模型或启用 JSON 后会使用独立的嵌入缓存。
--moss_image_validation_shift¶
MOSS-Image 验证时的推理流偏移，默认 5.0。偏移仅应用一次，基础网格从噪声均匀下降到零；偏移为 1 的四步网格为 [1, 0.75, 0.5, 0.25, 0]，与 AnyFlow 训练轨迹一致。训练使用未偏移的 1,000 点网格，以及技术报告附录 A.2中的截断、重新缩放 logit-normal 分布和 1% 均匀混合。flow_sigmoid_scale 乘以原生标准差 0.95；设为零时使用点质量分布加均匀混合。仍可显式选择均匀、beta、三次密度或自定义时间步方案。
--moss_image_uncond_skip_layers¶
在 MOSS-Image 负向 CFG 分支跳过的 Transformer 层 JSON 列表，层号从零开始，范围为 0 至 41。默认值：[22]，遵循项目采样配方。设为 [] 使用标准 CFG。正向分支通过 validation_guidance_skip_layers 和 validation_guidance_skip_scale 单独配置。
--krea2_reference_latents¶
- 内容：启用 Krea 2 reference dataset 训练。
- 原因：启用后，Krea 2 在缓存 Qwen3VL prompt embeddings 时使用配对的条件图像，并在训练时把该条件图像的 clean VAE latents 追加到 transformer token 序列中。
- 数据集设置：主 image dataset 的
conditioning_data应指向配对的 conditioning dataset。目标图像和参考图像的文件名必须匹配。 - 范围：这是 Krea 2 的模型侧选项。它不会生成 conditioning datasets；请使用常规 dataloader reference-dataset 设置。
LTX-2 验证选项¶
--ltx2_validation_pipeline_mode：选择 LTX-2 validation 只运行 trained model（trained-stage），还是运行两阶段 spatial upscaler validation pipeline（spatial-upscale）。--ltx2_validation_spatial_upsampler_model：LTX-2 spatial latent upsampler 的 Hugging Face repo、本地目录或本地.safetensors文件。默认Lightricks/LTX-2.3。--ltx2_validation_spatial_upsampler_filename：当 model 选项指向 repo 或目录时使用的 upsampler 文件名。默认ltx-2.3-spatial-upscaler-x2-1.1.safetensors。--ltx2_validation_audio_guidance：验证时用于 LTX-2 音频 latents 的可选独立 CFG guidance scale。未设置时复用--validation_guidance；需要 Comfy 风格 dual CFG 的视频/音频独立 scale 时设置它。- spatial-upscale 的行为：Stage 1 以请求的验证分辨率一半生成 video latents，spatial upsampler 将 latents 放大 2 倍，stage 2 使用 LTX-2 stage-2 sigma schedule 在请求分辨率重新去噪。
- 限制：Spatial-upscale validation 只用于 video；
--validation_audio_only会保持常规单阶段 validation 路径。
LTX-2 条件选项¶
这些是 LTX-2 训练的可选高级设置。可以在 JSON/TOML 配置中使用下面的名称，也可以使用对应的 CLI flag，例如 --ltx2_first_frame_conditioning_probability。
- 目标 token 内在条件：选中的目标视频 token 会从 clean latent 复制，token timestep 设为
0，并从 video loss 中排除。 ltx2_intrinsic_conditioning：条件对象的 JSON 数组，例如[{"type":"first_frame","probability":1.0}]。支持的type值为first_frame、prefix、suffix、spatial_crop、mask。- 简写键：
ltx2_first_frame_conditioning_probability、ltx2_prefix_conditioning_probability、ltx2_prefix_conditioning_frames、ltx2_suffix_conditioning_probability、ltx2_suffix_conditioning_frames、ltx2_mask_conditioning_probability。 - 对于
mask，值1表示 clean conditioning/no loss；值0表示正常 noisy training。 - IC-LoRA 参考缩放：
ltx2_reference_spatial_scale_factor和ltx2_reference_temporal_scale_factor调整参考 token 坐标。未设置时会从 reference/target latent 尺寸推断空间缩放。 - IC-LoRA 验证参考：
validation_ltx2_video_conditioning是用于验证的本地 reference video JSON 列表，例如[{"path":"data/reference.mp4","strength":1.0}]。 - 范围：这些设置只控制模型侧的 LTX-2 条件行为。Dataset pairing、mask files、reference datasets、WebUI controls、dataset templates 需要单独配置。
🎛 训练参数¶
--num_train_epochs¶
- 内容：训练轮数（全图像被看到的次数）。设为 0 时由
--max_train_steps优先。 - 原因：决定图像重复次数，影响训练时长。更多 epoch 更易过拟合，但可能需要以学习目标概念。合理范围通常为 5–50。
--max_train_steps¶
- 内容：训练步数上限。设为 0 时由
--num_train_epochs优先。 - 原因：用于缩短训练时长。
--strict_epoch_limit¶
- 内容：当 epoch 计数达到
--num_train_epochs时停止训练，即使尚未达到--max_train_steps。 - 原因：对于显式设置
--max_train_steps、并希望继续经过额外 epoch 直到达到步数上限的训练，请关闭此选项。--max_train_steps=0的训练始终按 epoch 驱动，并使用严格 epoch 上限。
--learning_rate¶
- 内容：潜在 warmup 后的初始学习率。
- 原因：学习率类似于梯度更新的“步长”。太高会越过解，太低则无法到达理想解。
full调优的最小值可能低至1e-7，最大约1e-6；lora调优最小1e-5，最大可到1e-3。高学习率时建议配合 EMA 与 warmup（见--use_ema、--lr_warmup_steps、--lr_scheduler）。
--lr_scheduler¶
- 内容：随时间调整学习率的方式。
- 选项：constant, constant_with_warmup, cosine, cosine_with_restarts, polynomial（推荐）, linear
- 原因：模型受益于持续的学习率调整以探索损失景观。默认使用 cosine，可在两个极值间平滑过渡。恒定学习率易过高导致发散或过低导致陷入局部最小。polynomial 与 warmup 配合最佳，会逐渐接近
learning_rate，随后减速并在末尾接近--lr_end。
--optimizer¶
- 内容：训练使用的优化器。
- 选项：adamw_bf16, ao-adamw8bit, ao-adamw4bit, ao-adamfp8, ao-adamwfp8, adamw_schedulefree, adamw_schedulefree+aggressive, adamw_schedulefree+no_kahan, optimi-stableadamw, optimi-adamw, optimi-lion, optimi-radam, optimi-ranger, optimi-adan, optimi-adam, optimi-sgd, soap, bnb-adagrad, bnb-adagrad8bit, bnb-adam, bnb-adam8bit, bnb-adamw, bnb-adamw8bit, bnb-adamw-paged, bnb-adamw8bit-paged, bnb-lion, bnb-lion8bit, bnb-lion-paged, bnb-lion8bit-paged, bnb-ademamix, bnb-ademamix8bit, bnb-ademamix-paged, bnb-ademamix8bit-paged, prodigy
注记：部分优化器在非 NVIDIA 硬件上可能不可用。
--optimizer_config¶
- 内容：调整优化器设置。
- 原因：优化器设置众多，无法为每个提供单独 CLI 参数。可用逗号分隔的键值覆盖默认设置。
- 示例：为 prodigy 设置
d_coef：--optimizer_config=d_coef=0.1
注记：优化器 betas 使用专用参数
--optimizer_beta1与--optimizer_beta2覆盖。
--train_batch_size¶
- 内容：训练数据加载器的全局默认批大小。主要数据集可以用自己的
train_batch_size覆盖采样器微批大小；没有覆盖值的数据集使用此值。 - 原因：影响内存消耗、收敛质量与训练速度。批越大结果通常越好，但过大可能导致过拟合或训练不稳定，并延长训练时间。需要实验，通常希望在不降低训练速度的前提下尽量用满显存。
- 静态配置：训练器级学习率缩放，以及其他必须使用单个固定批大小的配置或报告，即使数据集覆盖了微批大小，也仍使用此全局值。
- 梯度累积：当选中的数据集具有不同的解析后微批大小时，一次优化器更新的全局样本总数，是所有累积微步和所有数据并行 rank 上实际本地微批大小之和。被选中且没有覆盖值的数据集在对应 rank 上使用此全局默认值。常用的全局/有效批大小公式仍是配置参考值，而不是每次更新的准确样本数。梯度检查点不改变这一计算方式。
--gradient_accumulation_steps¶
- 内容：在执行反向/更新前累积的更新步数，相当于将工作分摊到多个批次以节省内存，但增加训练耗时。
- 原因：适用于更大的模型或数据集。
注记：使用梯度累积时，不要为任何优化器启用 fused backward pass。
--allow_dataset_oversubscription¶
- 内容：当某个纵横比桶小于该数据集的 bucket 大小要求时，自动调整
repeats。 - 原因：避免多 GPU 配置下因数据集不足而训练失败。
- 工作方式：
- 计算每个数据集的 bucket 大小要求：
解析后的数据集 train_batch_size × num_gpus × gradient_accumulation_steps - 若某些纵横比桶样本数少于该数据集的 bucket 大小要求，则自动增加
repeats - 仅在数据集配置未显式设置
repeats时生效 - 记录警告说明调整原因与结果
- 适用场景：
- 小数据集（< 100 张）+ 多 GPU
- 试验不同 batch 大小而无需重配数据集
- 在收集完整数据集前做原型验证
- 示例：25 张图像、8 GPU、
train_batch_size=4时，该数据集的 bucket 大小要求为 32。该标志会自动设定repeats=1，提供 50 样本（25 × 2）。 - 说明：不会覆盖 dataloader 配置中手动设置的
repeats。与--disable_bucket_pruning类似，此标志在不产生意外行为的前提下提供便利。
更多关于多 GPU 数据集规模的细节见 DATALOADER.md。
🛠 高级优化¶
--use_ema¶
- 内容：在训练期间维护权重的指数移动平均，相当于定期将模型“回合并”到自身。
- 原因：可提升训练稳定性，但会增加系统资源开销，并略微增加训练时间。
--ema_device¶
- 选项：
cpu,accelerator；默认：cpu - 内容：选择 EMA 权重在更新间存放的位置。
- 原因：放在加速器上更新最快但占用显存；放在 CPU 上可降低显存压力，但除非设置
--ema_cpu_only，否则会产生权重传输。
--ema_cpu_only¶
- 内容：当
--ema_device=cpu时，阻止 EMA 权重在更新时搬回加速器。 - 原因：节省大规模 EMA 的主机-设备传输时间与显存占用。若
--ema_device=accelerator则无效，因为权重已在加速器上。
--ema_foreach_disable¶
--ema_foreach_disable¶
- 内容：禁用 EMA 更新中对
torch._foreach_*内核的使用。 - 原因：某些后端或硬件组合在 foreach 操作上有问题。禁用后回退到标量实现，更新会略慢。
--ema_update_interval¶
- 内容：降低 EMA 影子参数的更新频率。
- 原因：对许多工作流而言每步更新并不必要。例如
--ema_update_interval=100仅每 100 个优化步更新一次 EMA，可减少--ema_device=cpu或--ema_cpu_only时的开销。
--ema_decay¶
- 内容：控制 EMA 更新时的平滑系数。
- 原因：较高值（例如
0.999）响应更慢但更稳定；较低值（例如0.99）更快适应新信号。
--ema_warmup_steps¶
- 内容：在配置的 optimizer step 之前把当前权重复制到 EMA，然后直接切换到
--ema_decay。 - 原因：匹配那些推迟 EMA smoothing、但不希望 EMA 停留在初始化权重上的训练配方。默认值
0保留 SimpleTuner 现有的 EMA ramp。
--snr_gamma¶
- 内容：使用 min-SNR 加权损失因子。
- 原因：Minimum SNR gamma 按时间步位置调整损失权重。噪声较大的时间步贡献降低，噪声较小的时间步贡献提高。原论文推荐值为 5，但可用 1 到 20。通常 20 被视为上限，超过 20 数学上变化不大。1 为最强权重。
--use_soft_min_snr¶
- 内容：使用更渐进的损失权重进行训练。
- 原因：像素扩散模型若不使用特定损失权重会退化。对 DeepFloyd 而言，soft-min-snr-gamma 基本必需。潜在扩散模型可能也有效，但小规模实验中可能产生模糊结果。
--flow_cubic_schedule_weights¶
- 内容：根据 0 到 1 之间等距点上的非负权重定义密度，并从中采样流匹配时间步。可使用 JSON 数组或逗号分隔值。零个或一个权重表示均匀分布，两个权重表示线性密度，三个及以上使用单调三次 Hermite 插值。
- 原因：无需把调度离散为固定时间步，即可将训练集中在指定噪声区域。模型原生时间步约定和已配置的 flow schedule shift 仍然生效。
- 冲突：不能与
--flow_use_uniform_schedule、--flow_use_beta_schedule、--flux_fast_schedule或--flow_custom_timesteps同时使用。 - 示例：
"flow_cubic_schedule_weights": [0.1, 1.0, 0.3, 2.0]
--diff2flow_enabled¶
- 内容：为 epsilon 或 v-prediction 模型启用 Diffusion-to-Flow 桥接。
- 原因：允许以标准扩散目标训练的模型在不改变架构的情况下使用流匹配目标（noise - latents）。
- 说明：实验性功能。
--diff2flow_loss¶
- 内容：使用 Flow Matching 损失替代原生预测损失进行训练。
- 原因：与
--diff2flow_enabled一起启用时，将损失计算于 flow 目标（noise - latents），而非模型原生目标（epsilon 或 velocity）。 - 说明：需要
--diff2flow_enabled。
--mixflow_enabled¶
- 内容：为 Flow Matching 模型启用 MixFlow 减速插值后训练。
- 原因：在不改变模型架构的情况下调整时间步采样和插值速度。
- 说明：不能与其他时间步调度同时使用。参见 MixFlow 指南。
--mixflow_gamma¶
- 内容：控制 MixFlow 减速插值范围。
- 范围：
0.0到1.0；默认值：0.8。 - 说明：
0.0保留标准插值，但仍使用 MixFlow 时间步采样。
--scheduled_sampling_max_step_offset¶
- 内容：训练中“rollout”的最大步数。
- 原因：启用计划采样（Rollout），让模型在训练过程中生成自身输入数步，帮助纠正错误并减少暴露偏差。
- 默认：0（禁用）。设置为正整数（如 5 或 10）启用。
--scheduled_sampling_strategy¶
- 内容：选择 rollout 偏移的策略。
- 选项：
uniform,biased_early,biased_late。 - 默认：
uniform。 - 原因：控制 rollout 长度分布。
uniform均匀采样；biased_early偏短；biased_late偏长。
--scheduled_sampling_probability¶
- 内容：对某个样本应用非零 rollout 偏移的概率。
- 默认：0.0。
- 原因：控制计划采样的应用频率。0.0 即使
max_step_offset> 0 也会禁用；1.0 表示每个样本都应用。
--scheduled_sampling_prob_start¶
- 内容：概率爬坡起始值。
- 默认：0.0。
--scheduled_sampling_prob_end¶
- 内容：概率爬坡终止值。
- 默认：0.5。
--scheduled_sampling_ramp_steps¶
- 内容：从
prob_start过渡到prob_end的步数。 - 默认：0（无爬坡）。
--scheduled_sampling_start_step¶
- 内容：开始计划采样爬坡的全局步数。
- 默认：0.0。
--scheduled_sampling_ramp_shape¶
- 内容：概率爬坡形状。
- 选项：
linear,cosine。 - 默认：
linear。
--scheduled_sampling_sampler¶
- 内容：rollout 生成步骤所用的求解器。
- 选项：
unipc,euler,dpm。 - 默认：
unipc。
--scheduled_sampling_order¶
- 内容：rollout 使用的求解器阶数。
- 默认：2。
--scheduled_sampling_reflexflow¶
- 内容：在 flow-matching 模型的计划采样中启用 ReflexFlow 风格增强（抗漂移 + 频率补偿权重）。
- 原因：通过方向正则与偏差感知重加权降低 flow-matching 模型 rollout 的暴露偏差。
- 默认：当
--scheduled_sampling_max_step_offset> 0 时，对 flow-matching 模型自动启用；可用--scheduled_sampling_reflexflow=false覆盖。
--scheduled_sampling_reflexflow_alpha¶
- 内容：来自暴露偏差的频率补偿权重缩放系数。
- 默认：1.0。
- 原因：值越大，rollout 中暴露偏差更大的区域权重越高。
--scheduled_sampling_reflexflow_beta1¶
- 内容：ReflexFlow 抗漂移（方向）正则项的权重。
- 默认：10.0。
- 原因：控制 flow-matching 模型在计划采样中预测方向与目标干净样本对齐的强度。
--scheduled_sampling_reflexflow_beta2¶
- 内容：ReflexFlow 频率补偿（损失重加权）项的权重。
- 默认：1.0。
- 原因：缩放重加权后的 flow-matching 损失，对应 ReflexFlow 论文中的 β₂。
🎯 iREPA（改进的表示对齐）¶
iREPA 使用卷积投影器和逐帧空间归一化，在表示对齐中保留空间结构。它改进 Transformer 的 CREPA 和 UNet 的 U-REPA。参见 iREPA 指南。
--irepa_enabled¶
- 类型：布尔标志
- 默认值：
false - 作用：使用 iREPA 空间操作升级已启用的 CREPA 或 U-REPA 路径。
- 说明：Transformer 还需启用
crepa_enabled，UNet 还需启用urepa_enabled。 - 训练模式：完整模型或标准 PEFT LoRA。LyCORIS 无法保存辅助投影器，因此不受支持。
--irepa_spatial_norm_alpha¶
- 类型：浮点数
- 默认值：
0.6 - 作用：在除以空间标准差之前，缩放教师特征的均值减法。
- 说明：
0.6是 latent-diffusion 参考设置；1.0会完全中心化每个通道。
--irepa_projector_kernel_size¶
- 类型：整数（
1、3、5或7） - 默认值：
3 - 作用：设置对齐投影器的空间卷积核。
🎯 CREPA（Cross-frame Representation Alignment）¶
CREPA 是一种用于视频扩散模型微调的正则化技术，通过将隐藏状态与相邻帧的预训练视觉特征对齐来提升时间一致性。基于论文 "Cross-Frame Representation Alignment for Fine-Tuning Video Diffusion Models"。
--crepa_enabled¶
- 内容：训练时启用 CREPA 正则化。
- 原因：通过将 DiT 隐藏状态与相邻帧的 DINOv2 特征对齐，提高视频帧之间的语义一致性。
- 默认：
false - 注意：仅适用于 Transformer 扩散模型（DiT 风格）。UNet 模型（SDXL、SD1.5、Kolors）请使用 U-REPA。
--crepa_block_index¶
- 内容：用于对齐的 Transformer 块隐藏状态索引。
- 原因：论文建议 CogVideoX 使用块 8，Hunyuan Video 使用块 10。较早的块往往效果更好，因为它们充当 DiT 的“编码器”部分。
- 必需：启用 CREPA 时必需。
--crepa_lambda¶
- 内容：CREPA 对齐损失相对于主训练损失的权重。
- 原因：控制对齐正则对训练的影响强度。论文对 CogVideoX 使用 0.5，对 Hunyuan Video 使用 1.0。
- 默认：
0.5
--crepa_adjacent_distance¶
- 内容：邻帧对齐距离
d。 - 原因：按论文公式 6，\(K = \{f-d, f+d\}\) 定义要对齐的邻帧。
d=1时，每帧与其相邻帧对齐。 - 默认：
1
--crepa_adjacent_tau¶
- 内容：指数距离权重的温度系数。
- 原因：通过 \(e^{-|k-f|/\tau}\) 控制对齐权重随帧距的衰减速度。值越小越强调近邻帧。
- 默认：
1.0
--crepa_cumulative_neighbors¶
- 内容：使用累计模式而非邻接模式。
- 原因：
- 邻接模式（默认）：仅与距离正好为
d的帧对齐（对应论文的 \(K = \{f-d, f+d\}\)） - 累计模式：与距离 1 到
d的所有帧对齐，梯度更平滑 - 默认：
false
--crepa_normalize_neighbour_sum¶
- 内容：按帧权重和对邻帧加权和进行归一化。
- 原因：使
crepa_alignment_score保持在 [-1, 1] 并让损失尺度更直观。这是对论文公式 (6) 的实验性偏离。 - 默认：
false
--crepa_normalize_by_frames¶
- 内容：按帧数对对齐损失归一化。
- 原因：保证不同视频长度下损失尺度一致。禁用时更长视频会获得更强对齐信号。
- 默认：
true
--crepa_spatial_align¶
- 内容：当 DiT 与编码器 token 数不同，使用空间插值对齐。
- 原因：DiT 隐藏状态与 DINOv2 特征可能具有不同空间分辨率。启用后使用双线性插值对齐，禁用则回退到全局池化。
- 默认：
true
--crepa_model¶
- 内容：用于特征提取的预训练编码器。
- 原因：论文使用 DINOv2-g（ViT-Giant）。更小的 DINO 变体占用更少内存，而 Qwen-VL 教师可提供更强的语义视觉特征。
- 默认：
dinov2_vitg14 - 选项：
dinov2_vitg14,dinov2_vitb14,dinov2_vits14,qwen3-vl-4b,qwen2.5-vl-7b，或 Hugging Face Qwen-VL 模型 ID。
--crepa_encoder_frames_batch_size¶
- 内容：外部特征编码器并行处理的帧数。0 或负数表示整批全部帧同时处理；若不能整除，剩余会作为更小批次处理。
- 原因：外部视觉编码器可通过切片批处理帧来减少显存占用（速度降低）。
- 默认：
-1
--crepa_use_backbone_features¶
- 内容：跳过外部编码器，在扩散模型内部将学生块与教师块对齐。
- 原因：当主干已经包含更强语义层可监督时，可避免加载 DINOv2。
- 默认：
false
--crepa_feature_source¶
- 内容：选择 CREPA 的教师信号来源。
- 原因：
encoder用于经典外部编码器路径，backbone用于内部块到块对齐，self_flow用于 Self-Flow 的更干净 EMA 教师视图。 - 选项：
encoder,backbone,self_flow - 默认：
encoder
--crepa_self_flow¶
- 内容：启用 Self-Flow 模式的旧布尔别名。
- 原因：为了兼容旧配置而保留，但新配置更推荐使用
crepa_feature_source=self_flow。 - 默认：
false - 注意：它与
crepa_use_backbone_features冲突，也会与指向其他模式的crepa_feature_source冲突。
--crepa_self_flow_mask_ratio¶
- 内容：在 Self-Flow 中接收替代 timestep 的 token 比例。
- 原因：控制更干净 token 与更高噪声 token 之间的信息不对称程度。较高数值会增强自监督信号，但也可能让训练不稳定。
- 默认：
0.1 - 范围：
0.0到0.5
--crepa_teacher_block_index¶
- 内容：使用主干特征或 Self-Flow 时的教师块索引。
- 原因：无需外部编码器即可让早期学生块对齐到更深教师块。Self-Flow 明确要求它，以便 EMA 教师读取更深的语义层。
- 默认：在 backbone 模式下未提供时使用
crepa_block_index；在 Self-Flow 模式下为必填。
--crepa_encoder_image_size¶
- 内容：编码器输入分辨率。
- 原因：DINOv2 在训练分辨率上效果最好。巨型模型使用 518x518。
- 默认：
518
--crepa_scheduler¶
- 内容：训练过程中 CREPA 系数的衰减调度方式。
- 原因：允许在训练进行时逐渐降低 CREPA 正则化强度，防止对深层编码器特征过拟合。
- 选项：
constant、linear、cosine、polynomial - 默认：
constant
--crepa_warmup_steps¶
- 内容：将 CREPA 权重从 0 线性升至
crepa_lambda的步数。 - 原因：渐进预热有助于在 CREPA 正则化生效前稳定早期训练。
- 默认：
0
--crepa_decay_steps¶
- 内容：衰减总步数（预热后）。设为 0 则在整个训练过程中衰减。
- 原因：灵活控制衰减的时间跨度。
- 默认：
0（使用max_train_steps）
--crepa_lambda_end¶
- 内容：衰减完成后的最终 CREPA 权重。
- 原因：设为 0 可在训练末期有效禁用 CREPA，适用于 text2video 等可能产生伪影的场景。
- 默认：
0.0
--crepa_power¶
- 内容：多项式衰减的幂因子。1.0 = 线性，2.0 = 二次，以此类推。
- 原因：控制衰减曲线形状。
- 默认：
1.0
--crepa_cutoff_step¶
- 内容：硬截止步数，超过此步后禁用 CREPA。
- 原因：适用于模型时序对齐收敛后禁用 CREPA 的场景。
- 默认：
0（无基于步数的截止）
--crepa_similarity_threshold¶
- 内容：触发 CREPA 截止的相似度 EMA 阈值。
- 原因：当对齐分数（
crepa_alignment_score）的指数移动平均达到此值时，CREPA 被禁用以防止对深层编码器特征过拟合。对于 text2video 训练尤其有用。除非启用crepa_normalize_neighbour_sum，否则对齐分数可能超过 1.0。 - 默认：None（禁用）
--crepa_similarity_ema_decay¶
- 内容：相似度跟踪的指数移动平均衰减因子。
- 原因：控制相似度指标的平滑程度。
- 默认：
0.99
--crepa_threshold_mode¶
- 内容：达到相似度阈值后的行为。
- 选项：
permanent（一旦达到阈值，CREPA 保持关闭）、recoverable（若相似度下降，CREPA 重新启用） - 默认：
permanent
配置示例¶
# 启用 CREPA 用于视频微调
crepa_enabled = true
crepa_block_index = 8 # 根据模型调整
crepa_lambda = 0.5
crepa_adjacent_distance = 1
crepa_adjacent_tau = 1.0
crepa_cumulative_neighbors = false
crepa_normalize_neighbour_sum = false
crepa_normalize_by_frames = true
crepa_spatial_align = true
crepa_model = "dinov2_vitg14" # 或使用 "qwen3-vl-4b" 获取 Qwen-VL 视觉特征
crepa_encoder_frames_batch_size = -1
crepa_use_backbone_features = false
# crepa_teacher_block_index = 16
crepa_encoder_image_size = 518
# CREPA 调度（可选）
# crepa_scheduler = "cosine" # 衰减类型：constant、linear、cosine、polynomial
# crepa_warmup_steps = 100 # CREPA 生效前的预热步数
# crepa_decay_steps = 1000 # 衰减步数（0 = 整个训练过程）
# crepa_lambda_end = 0.0 # 衰减后的最终权重
# crepa_cutoff_step = 5000 # 硬截止步数（0 = 禁用）
# crepa_similarity_threshold = 0.9 # 基于相似度的截止
# crepa_threshold_mode = "permanent" # permanent 或 recoverable
🎯 U-REPA（UNet 表征对齐）¶
U-REPA 是用于 UNet 扩散模型（SDXL、SD1.5、Kolors）的正则化方法。它将 UNet 中间块特征与预训练视觉特征对齐，并加入流形损失以保持相对相似性结构。
--urepa_enabled¶
- 内容：训练时启用 U-REPA 正则化。
- 原因：使用冻结的视觉编码器对齐 UNet 中间块特征。
- 默认：
false - 注意：仅适用于 UNet 模型（SDXL、SD1.5、Kolors）。
--urepa_lambda¶
- 内容：U-REPA 对齐损失权重（相对于主训练损失）。
- 原因：控制对齐正则强度。
- 默认：
0.5
--urepa_manifold_weight¶
- 内容：流形损失相对于对齐损失的权重。
- 原因：强调特征相对相似性结构（论文默认 3.0）。
- 默认：
3.0
--urepa_model¶
- 内容：冻结视觉编码器的 torch hub 标识符。
- 原因：默认 DINOv2 ViT-G/14；较小模型（如
dinov2_vits14）速度更快。 - 默认：
dinov2_vitg14
--urepa_encoder_image_size¶
- 内容：视觉编码器预处理的输入分辨率。
- 原因：使用编码器原生分辨率（DINOv2 ViT-G/14 为 518，ViT-S/14 为 224）。
- 默认：
518
--urepa_use_tae¶
- 内容：使用 Tiny AutoEncoder 代替完整 VAE 解码。
- 原因：更快、显存占用更低，但解码质量较低。
- 默认：
false
--urepa_scheduler¶
- 内容：U-REPA 系数随训练衰减的调度方式。
- 原因：允许训练过程中逐渐降低 U-REPA 强度。
- 选项：
constant、linear、cosine、polynomial - 默认：
constant
--urepa_warmup_steps¶
- 内容：将 U-REPA 权重从 0 线性升至
urepa_lambda的步数。 - 原因：渐进预热有助于稳定早期训练。
- 默认：
0
--urepa_decay_steps¶
- 内容：衰减总步数（预热之后）。设为 0 表示在整个训练过程中衰减。
- 原因：控制衰减阶段的持续时间。
- 默认：
0（使用max_train_steps）
--urepa_lambda_end¶
- 内容：衰减完成后的最终 U-REPA 权重。
- 原因：设为 0 可在训练末期有效禁用 U-REPA。
- 默认：
0.0
--urepa_power¶
- 内容：多项式衰减的幂指数。1.0 = 线性，2.0 = 二次等。
- 原因：更高值会在早期衰减更快、后期更慢。
- 默认：
1.0
--urepa_cutoff_step¶
- 内容：超过该步数后硬截止禁用 U-REPA。
- 原因：当模型收敛后可关闭 U-REPA。
- 默认：
0（无步数截止）
--urepa_similarity_threshold¶
- 内容：触发 U-REPA 截止的相似度 EMA 阈值。
- 原因：当相似度（
urepa_similarity）的指数移动平均达到该值时禁用 U-REPA，以防止过拟合。 - 默认：None（禁用）
--urepa_similarity_ema_decay¶
- 内容：相似度跟踪的指数移动平均衰减因子。
- 原因：较高值更平滑（0.99 ≈ 100 步窗口），较低值响应更快。
- 默认：
0.99
--urepa_threshold_mode¶
- 内容：达到相似度阈值后的行为。
- 选项：
permanent（一旦达到阈值，U-REPA 保持关闭）、recoverable（若相似度下降，U-REPA 重新启用） - 默认：
permanent
配置示例¶
# 启用 U-REPA 用于 UNet 微调（SDXL、SD1.5、Kolors）
urepa_enabled = true
urepa_lambda = 0.5
urepa_manifold_weight = 3.0
urepa_model = "dinov2_vitg14"
urepa_encoder_image_size = 518
urepa_use_tae = false
# U-REPA 调度（可选）
# urepa_scheduler = "cosine" # 衰减类型：constant、linear、cosine、polynomial
# urepa_warmup_steps = 100 # U-REPA 生效前的预热步数
# urepa_decay_steps = 1000 # 衰减步数（0 = 整个训练过程）
# urepa_lambda_end = 0.0 # 衰减后的最终权重
# urepa_cutoff_step = 5000 # 硬截止步数（0 = 禁用）
# urepa_similarity_threshold = 0.9 # 基于相似度的截止
# urepa_threshold_mode = "permanent" # permanent 或 recoverable
🔄 检查点与恢复¶
--checkpoint_step_interval（别名：--checkpointing_steps）¶
- 内容：保存训练状态检查点的间隔（步数）。
- 原因：有助于恢复训练与推理。每 n 次迭代会通过 Diffusers 文件布局保存
.safetensors部分检查点。
Internal Guidance¶
Internal Guidance 使用与最终 output head 相同的 denoising target 监督早期 diffusion-transformer block。参见 Internal Guidance。
--internal_guidance_enabled¶
- 作用：启用辅助 denoising head 和 loss。
- 支持：使用标准 PEFT LoRA 或完整训练的 diffusion transformer。不支持 UNet、autoregressive 和 LyCORIS。
- 默认：
false
--internal_guidance_loss_weight¶
- 作用：Intermediate loss 权重。
- 默认：
0.5，必须大于 0。
--internal_guidance_block_index¶
- 作用：从 0 开始的 transformer block。
- 默认：Transformer 深度的四分之一。
--validation_internal_guidance_scale¶
- 作用：Validation sampling 时应用
intermediate + scale * (final - intermediate)。 - 默认：
1.0（禁用）；参考实现使用1.4。
Explorative Modeling (XM)¶
XM 会评估多个训练候选，并只对最能解释每个监督样本或 token block 的候选进行反向传播。所选 target 需要对应模型家族实现支持。用户指南见 Explorative Modeling。
--xm_enabled¶
- 作用：启用 XM 候选选择。
- 默认：
false
--xm_candidate_count¶
- 作用：每个样本要评分的 noise 或 route latent 候选数量。
- 默认：
1；启用 XM 时必须至少为2。
--xm_training_target¶
- 作用：候选类型。Diffusion/flow 模型使用
noise，AR/RVQ planner 使用route。 - 选项：
noise、route - 默认：
noise
--xm_selection_scope¶
- 作用：按
sample或 token/frameblock选择获胜候选。 - 默认：
sample
--xm_block_size¶
- 作用：Block-level XM 使用的 token 或 frame span。
0表示使用完整监督序列。 - 默认：
0
NextLat¶
NextLat 添加一个小型辅助 predictor，把每个捕获的 hidden token 映射到下一个 hidden token。它要求 transformer 模型家族能通过 SimpleTuner hidden-state buffer 暴露 hidden states。用户指南见 NextLat。
--nextlat_enabled¶
- 作用：启用 NextLat hidden-state prediction。
- 默认：
false
--nextlat_block_index¶
- 作用：要捕获的 0-based transformer block。
- 默认：
-1，表示使用最后一个支持的 block。
--nextlat_weight¶
- 作用：NextLat 辅助 loss 的权重。
- 默认：
0.0；启用 NextLat 时必须大于 0。
--nextlat_state_loss¶
- 作用：预测下一个 hidden state 的距离函数。
- 选项：
smooth_l1、mse - 默认：
smooth_l1
--nextlat_kl_weight¶
- 作用：当模型家族为预测 hidden state 提供 logits head 时使用的可选 KL 一致性权重。
- 默认：
0.0
🔁 LayerSync（隐藏状态自对齐）¶
LayerSync 通过在同一 Transformer 内让“学生”层对齐更强的“教师”层，使用隐藏 token 的余弦相似度进行对齐。
--layersync_enabled¶
- 内容：启用同一模型内两个 Transformer 块之间的 LayerSync 隐藏状态对齐。
- 备注：会分配隐藏状态缓冲区；若缺少必需参数，启动时会报错。
- 默认：
false
--layersync_student_block¶
- 内容：作为学生锚点的 Transformer 块索引。
- 索引：接受 LayerSync 论文式 1-based 深度或 0-based 层编号；实现会先尝试
idx-1，再尝试idx。 - 必需：启用 LayerSync 时必需。
--layersync_teacher_block¶
- 内容：作为教师目标的 Transformer 块索引（可以比学生更深）。
- 索引：与学生块一致，优先 1-based，再回退 0-based。
- 默认：未设置时使用学生块，使损失变为自相似。
--layersync_lambda¶
- 内容：LayerSync 学生/教师隐藏状态之间的余弦对齐损失权重（负余弦相似度）。
- 影响：缩放叠加在主损失上的辅助正则项；值越大越推动学生 token 向教师 token 对齐。
- 上游名称：原始 LayerSync 代码库中的
--reg-weight。 - 必需：启用 LayerSync 时必须大于 0（否则训练终止）。
- 默认：启用 LayerSync 时为
0.2（与参考仓库一致），否则为0.0。
上游选项映射（LayerSync → SimpleTuner）:
- --encoder-depth → --layersync_student_block（上游接受 1-based 深度，也可 0-based 层索引）
- --gt-encoder-depth → --layersync_teacher_block（推荐 1-based；未设置时默认为学生）
- --reg-weight → --layersync_lambda
注记：LayerSync 在计算相似度前总是先对教师隐藏状态执行 detach，与参考实现一致。它依赖能输出 Transformer 隐藏状态的模型（SimpleTuner 中的大多数 Transformer 主干），并在每个步骤增加隐藏状态缓冲区的内存开销；显存紧张时请禁用。
--checkpoint_epoch_interval¶
- 内容：每完成 N 个 epoch 进行检查点保存。
- 原因：补充按步保存，确保在多数据集采样导致步数变化时，仍能在 epoch 边界捕获状态。
--resume_from_checkpoint¶
- 内容：指定是否以及从何处恢复训练。接受
latest、本地检查点名称/路径或 S3/R2 URI。 - 原因：允许从已保存的状态继续训练，可手动指定或使用最新可用检查点。
- 远程恢复：提供完整 URI (
s3://bucket/jobs/.../checkpoint-100) 或相对 bucket 的 key (jobs/.../checkpoint-100)。latest仅适用于本地output_dir。 - 要求：远程恢复需要在 publishing_config 中提供可读取检查点的 S3 配置（bucket + credentials）。
- 注意：远程检查点必须包含
checkpoint_manifest.json（由较新的 SimpleTuner 运行生成）。检查点由unet与可选unet_ema子目录组成。unet可直接放入 Diffusers 布局的 SDXL 模型中，像普通模型一样使用。
ℹ️ PixArt、SD3、Hunyuan 等 Transformer 模型使用
transformer与transformer_ema子目录名称。
--init_lora_step¶
- 内容：从
--init_lora加载的纯模型 adapter 继续全局步数计数。 - 使用时机：仅在完整 trainer checkpoint 不可用、但 LoRA 权重仍然保留时使用。
- 自动推断：省略此选项时，如果本地
--init_lorasafetensors 文件包含global_stepmetadata，SimpleTuner 会使用该值。显式值（包括0）会覆盖 metadata。 - 要求：必须为非负数且小于
--max_train_steps；需要--init_lora，且不能与--resume_from_checkpoint同时使用。 - 状态：checkpoint 与 validation 的节奏从该步数继续，但 optimizer、sampler 和 RNG state 会重新开始。
constant与constant_with_warmuplearning-rate schedule 会恢复到对应步数。
--init_lora_ema¶
- 内容：加载与
--init_lora对应的 SimpleTuner 原始ema_model.ptstate。 - 要求：需要
--init_lora和--use_ema=true。 - 注意：这里需要的是 checkpoint 保存的原始 EMA state，而不是导出的 EMA LoRA safetensors 文件。
--delete_invalid_checkpoints¶
- 内容：恢复时删除无法加载的本地检查点。
- 行为：使用
--resume_from_checkpoint=latest时，SimpleTuner 会删除无效的本地检查点并尝试下一个最新检查点。新的检查点会在保存恢复所需文件后写入.guard文件，因此当存在较旧的 guarded 检查点时，可以丢弃缺少该 guard 的较新检查点。 - 安全性：只会删除
output_dir下的本地检查点目录。显式检查点路径在删除后仍会抛出原始加载失败。 - 默认：
false
--disk_low_threshold¶
- 内容：检查点保存和 TorchInductor 图编译（包括重新编译）前所需的最小可用磁盘空间。
- 原因：提前检测空间不足，并对检查点或编译器缓存所在的文件系统执行配置的操作。
- 格式：大小字符串，如
100G、50M、1T、500K，或纯字节数。 - 默认：无（功能禁用）
- 范围：每个执行编译的进程都会检查
TORCHINDUCTOR_CACHE_DIR（或 PyTorch 默认目录），以及配置的独立TRITON_CACHE_DIR。这只是预检查，不会预留空间：编译开始后仍可能耗尽空间，后端初始化也可能在检查前写入。请设置足够支持编译的阈值。磁盘检查不会恢复 CUDA 内存不足错误，也不会重试失败的编译。
--disk_low_action¶
- 内容：磁盘空间低于阈值时采取的操作。
- 选项：
stop、wait、script - 默认：
stop - 行为：
stop：立即停止训练并显示错误消息。wait：每 30 秒循环检查直到空间可用。可能无限等待。script：运行--disk_low_script指定的脚本以释放空间。
--disk_low_script¶
- 内容：磁盘空间不足时运行的清理脚本路径。
- 原因：允许在磁盘空间不足时自动清理（如删除旧检查点、清除缓存）。
- 注意：仅在
--disk_low_action=script时使用。脚本必须可执行。如果脚本失败或未能释放足够空间，训练将停止并报错。 - 默认：无
📊 日志与监控¶
--logging_dir¶
- 内容：TensorBoard 日志目录。
- 原因：便于监控训练进度与性能指标。
--report_to¶
- 内容：指定结果与日志的上报平台。
- 原因：启用本地或外部监控。
simpletuner会在output_dir中写入 JSONL、运行清单、验证媒体元数据和独立 HTML 报告。多个 tracker 使用逗号分隔。 - 选项：simpletuner, wandb, tensorboard, swanlab, comet_ml, custom-tracker, none
--validation_image_format¶
- 内容：保存到
output_dir/validation_images的图像格式。 - 选项：png, webp, jpeg
- 默认值：png
--validation_image_quality¶
- 内容：WebP 和 JPEG 的质量，范围 1 到 100。
- 默认值：90。PNG 会忽略此项。
环境配置变量¶
上述选项大多适用于 config.json，但有些条目必须在 config.env 中设置。
TRAINING_NUM_PROCESSES应设置为系统中的 GPU 数量。多数场景下已足够启用 DistributedDataParallel（DDP）。如果不想使用config.env，可在config.json中设置num_processes。TRAINING_DYNAMO_BACKEND默认no，但可设置为任意支持的 torch.compile 后端（例如inductor,aot_eager,cudagraphs），并与--dynamo_mode、--dynamo_fullgraph或--dynamo_use_regional_compilation配合微调。SIMPLETUNER_LOG_LEVEL默认INFO，设置为DEBUG可在debug.log中记录更多问题报告信息。SIMPLETUNER_ALLOW_MODIFYING_BSZ=1在从检查点恢复时跳过采样器 batch_size 不匹配检查。仅在您有意在不同训练轮次间更改train_batch_size并接受采样器状态不一致的风险时使用。等效于--i_know_what_i_am_doing。VENV_PATH可设置为 Python 虚拟环境的位置（如果不在常见.venv目录）。ACCELERATE_EXTRA_ARGS可留空，或包含额外参数，例如--multi_gpu或 FSDP 专用标志。
这是一个基础概览，旨在帮助你快速上手。完整选项列表与更详细说明请参阅完整规范：
命令行参考¶
用法¶
usage: train.py [-h] --model_family
{kolors,auraflow,omnigen,flux,deepfloyd,cosmos2image,sana,qwen_image,pixart_sigma,sdxl,sd1x,sd2x,wan,hidream,sd3,lumina2,ltxvideo}
[--model_flavour MODEL_FLAVOUR] [--controlnet [CONTROLNET]]
[--pretrained_model_name_or_path PRETRAINED_MODEL_NAME_OR_PATH]
--output_dir OUTPUT_DIR [--logging_dir LOGGING_DIR]
--model_type {full,lora} [--seed SEED]
[--resolution RESOLUTION]
[--resume_from_checkpoint RESUME_FROM_CHECKPOINT]
[--prediction_type {epsilon,v_prediction,sample,flow_matching,flow_map}]
[--pretrained_vae_model_name_or_path PRETRAINED_VAE_MODEL_NAME_OR_PATH]
[--vae_dtype {default,fp32,fp16,bf16}]
[--vae_cache_ondemand [VAE_CACHE_ONDEMAND]]
[--accelerator_cache_clear_interval ACCELERATOR_CACHE_CLEAR_INTERVAL]
[--aspect_bucket_rounding {1,2,3,4,5,6,7,8,9}]
[--base_model_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}]
[--text_encoder_1_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}]
[--text_encoder_2_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}]
[--text_encoder_3_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}]
[--text_encoder_4_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}]
[--gradient_checkpointing_interval GRADIENT_CHECKPOINTING_INTERVAL]
[--gradient_checkpointing_segment_stride GRADIENT_CHECKPOINTING_SEGMENT_STRIDE]
[--offload_during_startup [OFFLOAD_DURING_STARTUP]]
[--quantize_via {cpu,accelerator,pipeline}]
[--quantization_config QUANTIZATION_CONFIG]
[--fuse_qkv_projections [FUSE_QKV_PROJECTIONS]]
[--control [CONTROL]]
[--controlnet_custom_config CONTROLNET_CUSTOM_CONFIG]
[--controlnet_model_name_or_path CONTROLNET_MODEL_NAME_OR_PATH]
[--tread_config TREAD_CONFIG]
[--pretrained_transformer_model_name_or_path PRETRAINED_TRANSFORMER_MODEL_NAME_OR_PATH]
[--pretrained_transformer_subfolder PRETRAINED_TRANSFORMER_SUBFOLDER]
[--pretrained_unet_model_name_or_path PRETRAINED_UNET_MODEL_NAME_OR_PATH]
[--pretrained_unet_subfolder PRETRAINED_UNET_SUBFOLDER]
[--pretrained_t5_model_name_or_path PRETRAINED_T5_MODEL_NAME_OR_PATH]
[--pretrained_gemma_model_name_or_path PRETRAINED_GEMMA_MODEL_NAME_OR_PATH]
[--qwen_text_encoder_model_name_or_path QWEN_TEXT_ENCODER_MODEL_NAME_OR_PATH]
[--revision REVISION] [--variant VARIANT]
[--base_model_default_dtype {bf16,fp32}]
[--unet_attention_slice [UNET_ATTENTION_SLICE]]
[--num_train_epochs NUM_TRAIN_EPOCHS]
[--max_train_steps MAX_TRAIN_STEPS]
[--train_batch_size TRAIN_BATCH_SIZE]
[--learning_rate LEARNING_RATE] --optimizer
{adamw_bf16,ao-adamw8bit,ao-adamw4bit,ao-adamfp8,ao-adamwfp8,adamw_schedulefree,adamw_schedulefree+aggressive,adamw_schedulefree+no_kahan,optimi-stableadamw,optimi-adamw,optimi-lion,optimi-radam,optimi-ranger,optimi-adan,optimi-adam,optimi-sgd,soap,prodigy}
[--optimizer_config OPTIMIZER_CONFIG]
[--lr_scheduler {linear,sine,cosine,cosine_with_restarts,polynomial,constant,constant_with_warmup}]
[--gradient_accumulation_steps GRADIENT_ACCUMULATION_STEPS]
[--lr_warmup_steps LR_WARMUP_STEPS]
[--checkpoints_total_limit CHECKPOINTS_TOTAL_LIMIT]
[--gradient_checkpointing [GRADIENT_CHECKPOINTING]]
[--train_text_encoder [TRAIN_TEXT_ENCODER]]
[--text_encoder_lr TEXT_ENCODER_LR]
[--lr_num_cycles LR_NUM_CYCLES] [--lr_power LR_POWER]
[--use_soft_min_snr [USE_SOFT_MIN_SNR]] [--use_ema [USE_EMA]]
[--ema_device {accelerator,cpu}]
[--ema_cpu_only [EMA_CPU_ONLY]]
[--ema_update_interval EMA_UPDATE_INTERVAL]
[--ema_foreach_disable [EMA_FOREACH_DISABLE]]
[--ema_decay EMA_DECAY] [--lora_rank LORA_RANK]
[--lora_alpha LORA_ALPHA] [--lora_type {standard,lycoris}]
[--lora_dropout LORA_DROPOUT]
[--lora_init_type {default,gaussian,loftq,olora,pissa}]
[--peft_lora_mode {standard,singlora}]
[--peft_lora_target_modules PEFT_LORA_TARGET_MODULES]
[--singlora_ramp_up_steps SINGLORA_RAMP_UP_STEPS]
[--init_lora INIT_LORA] [--init_lora_step INIT_LORA_STEP]
[--init_lora_ema INIT_LORA_EMA]
[--lycoris_config LYCORIS_CONFIG]
[--init_lokr_norm INIT_LOKR_NORM]
[--flux_lora_target {mmdit,context,context+ffs,all,all+ffs,ai-toolkit,tiny,nano,controlnet,all+ffs+embedder,all+ffs+embedder+controlnet}]
[--use_dora [USE_DORA]]
[--resolution_type {pixel,area,pixel_area}]
--data_backend_config DATA_BACKEND_CONFIG
[--caption_strategy {filename,textfile,instance_prompt,parquet}]
[--conditioning_multidataset_sampling {combined,random}]
[--instance_prompt INSTANCE_PROMPT]
[--parquet_caption_column PARQUET_CAPTION_COLUMN]
[--parquet_filename_column PARQUET_FILENAME_COLUMN]
[--ignore_missing_files [IGNORE_MISSING_FILES]]
[--vae_cache_scan_behaviour {recreate,sync}]
[--vae_enable_slicing [VAE_ENABLE_SLICING]]
[--vae_enable_tiling [VAE_ENABLE_TILING]]
[--vae_enable_patch_conv [VAE_ENABLE_PATCH_CONV]]
[--vae_batch_size VAE_BATCH_SIZE]
[--caption_dropout_probability CAPTION_DROPOUT_PROBABILITY]
[--tokenizer_max_length TOKENIZER_MAX_LENGTH]
[--validation_step_interval VALIDATION_STEP_INTERVAL]
[--validation_epoch_interval VALIDATION_EPOCH_INTERVAL]
[--validate_after_step VALIDATE_AFTER_STEP]
[--validate_after_epoch VALIDATE_AFTER_EPOCH]
[--disable_benchmark [DISABLE_BENCHMARK]]
[--validation_prompt VALIDATION_PROMPT]
[--validation_input VALIDATION_INPUT]
[--num_validation_images NUM_VALIDATION_IMAGES]
[--num_eval_images NUM_EVAL_IMAGES]
[--eval_steps_interval EVAL_STEPS_INTERVAL]
[--eval_epoch_interval EVAL_EPOCH_INTERVAL]
[--eval_timesteps EVAL_TIMESTEPS]
[--eval_dataset_pooling [EVAL_DATASET_POOLING]]
[--evaluation_type {none,clip}]
[--pretrained_evaluation_model_name_or_path PRETRAINED_EVALUATION_MODEL_NAME_OR_PATH]
[--validation_guidance VALIDATION_GUIDANCE]
[--validation_num_inference_steps VALIDATION_NUM_INFERENCE_STEPS]
[--validation_on_startup [VALIDATION_ON_STARTUP]]
[--validation_using_datasets [VALIDATION_USING_DATASETS]]
[--validation_torch_compile [VALIDATION_TORCH_COMPILE]]
[--validation_guidance_real VALIDATION_GUIDANCE_REAL]
[--validation_no_cfg_until_timestep VALIDATION_NO_CFG_UNTIL_TIMESTEP]
[--validation_negative_prompt VALIDATION_NEGATIVE_PROMPT]
[--validation_randomize [VALIDATION_RANDOMIZE]]
[--validation_seed VALIDATION_SEED]
[--validation_disable [VALIDATION_DISABLE]]
[--validation_prompt_library [VALIDATION_PROMPT_LIBRARY]]
[--user_prompt_library USER_PROMPT_LIBRARY]
[--eval_dataset_id EVAL_DATASET_ID]
[--validation_stitch_input_location {left,right}]
[--validation_guidance_rescale VALIDATION_GUIDANCE_RESCALE]
[--validation_disable_unconditional [VALIDATION_DISABLE_UNCONDITIONAL]]
[--validation_guidance_skip_layers VALIDATION_GUIDANCE_SKIP_LAYERS]
[--validation_guidance_skip_layers_start VALIDATION_GUIDANCE_SKIP_LAYERS_START]
[--validation_guidance_skip_layers_stop VALIDATION_GUIDANCE_SKIP_LAYERS_STOP]
[--validation_guidance_skip_scale VALIDATION_GUIDANCE_SKIP_SCALE]
[--validation_lycoris_strength VALIDATION_LYCORIS_STRENGTH]
[--validation_noise_scheduler {ddim,ddpm,euler,euler-a,unipc,dpm++,perflow}]
[--validation_num_video_frames VALIDATION_NUM_VIDEO_FRAMES]
[--validation_audio_only [VALIDATION_AUDIO_ONLY]]
[--validation_resolution VALIDATION_RESOLUTION]
[--validation_seed_source {cpu,gpu}]
[--i_know_what_i_am_doing [I_KNOW_WHAT_I_AM_DOING]]
[--flow_sigmoid_scale FLOW_SIGMOID_SCALE]
[--flux_fast_schedule [FLUX_FAST_SCHEDULE]]
[--flow_use_uniform_schedule [FLOW_USE_UNIFORM_SCHEDULE]]
[--flow_use_beta_schedule [FLOW_USE_BETA_SCHEDULE]]
[--flow_beta_schedule_alpha FLOW_BETA_SCHEDULE_ALPHA]
[--flow_beta_schedule_beta FLOW_BETA_SCHEDULE_BETA]
[--flow_cubic_schedule_weights FLOW_CUBIC_SCHEDULE_WEIGHTS]
[--flow_schedule_shift FLOW_SCHEDULE_SHIFT]
[--flow_schedule_auto_shift [FLOW_SCHEDULE_AUTO_SHIFT]]
[--mixflow_enabled [MIXFLOW_ENABLED]]
[--mixflow_gamma MIXFLOW_GAMMA]
[--audio_flow_schedule_shift AUDIO_FLOW_SCHEDULE_SHIFT]
[--flow_custom_timesteps FLOW_CUSTOM_TIMESTEPS]
[--flow_timesteps_mode {fixed-list,round-robin}]
[--flux_guidance_mode {constant,random-range}]
[--flux_attention_masked_training [FLUX_ATTENTION_MASKED_TRAINING]]
[--flux_guidance_value FLUX_GUIDANCE_VALUE]
[--flux_guidance_min FLUX_GUIDANCE_MIN]
[--flux_guidance_max FLUX_GUIDANCE_MAX]
[--t5_padding {zero,unmodified}]
[--sd3_clip_uncond_behaviour {empty_string,zero}]
[--sd3_t5_uncond_behaviour {empty_string,zero}]
[--soft_min_snr_sigma_data SOFT_MIN_SNR_SIGMA_DATA]
[--mixed_precision {no,fp16,bf16,fp8}]
[--attention_mechanism {diffusers,xformers,flash-attn,flash-attn-2,flash-attn-3,flash-attn-3-varlen,flex,kohaku-fa,kohaku-fa-auto,metal-flash-attention,metal-flash-attention-int8,metal-flash-attention-int4,cudnn,native-efficient,native-flash,native-math,native-npu,native-xla,sla,sageattention,sageattention-int8-fp16-triton,sageattention-int8-fp16-cuda,sageattention-int8-fp8-cuda}]
[--sageattention_usage {training,inference,training+inference}]
[--disable_tf32 [DISABLE_TF32]]
[--set_grads_to_none [SET_GRADS_TO_NONE]]
[--noise_offset NOISE_OFFSET]
[--noise_offset_probability NOISE_OFFSET_PROBABILITY]
[--input_perturbation INPUT_PERTURBATION]
[--input_perturbation_steps INPUT_PERTURBATION_STEPS]
[--lr_end LR_END] [--lr_scale [LR_SCALE]]
[--lr_scale_sqrt [LR_SCALE_SQRT]]
[--strict_epoch_limit [STRICT_EPOCH_LIMIT]]
[--freeze_encoder_before FREEZE_ENCODER_BEFORE]
[--freeze_encoder_after FREEZE_ENCODER_AFTER]
[--freeze_encoder_strategy {before,between,after}]
[--layer_freeze_strategy {none,bitfit}]
[--fully_unload_text_encoder [FULLY_UNLOAD_TEXT_ENCODER]]
[--save_text_encoder [SAVE_TEXT_ENCODER]]
[--text_encoder_limit TEXT_ENCODER_LIMIT]
[--prepend_instance_prompt [PREPEND_INSTANCE_PROMPT]]
[--only_instance_prompt [ONLY_INSTANCE_PROMPT]]
[--data_aesthetic_score DATA_AESTHETIC_SCORE]
[--delete_unwanted_images [DELETE_UNWANTED_IMAGES]]
[--delete_problematic_images [DELETE_PROBLEMATIC_IMAGES]]
[--disable_bucket_pruning [DISABLE_BUCKET_PRUNING]]
[--disable_segmented_timestep_sampling [DISABLE_SEGMENTED_TIMESTEP_SAMPLING]]
[--preserve_data_backend_cache [PRESERVE_DATA_BACKEND_CACHE]]
[--override_dataset_config [OVERRIDE_DATASET_CONFIG]]
[--cache_dir CACHE_DIR] [--cache_dir_text CACHE_DIR_TEXT]
[--text_cache_ondemand [TEXT_CACHE_ONDEMAND]]
[--text_cache_disable [TEXT_CACHE_DISABLE]]
[--cache_dir_vae CACHE_DIR_VAE]
[--compress_disk_cache [COMPRESS_DISK_CACHE]]
[--aspect_bucket_disable_rebuild [ASPECT_BUCKET_DISABLE_REBUILD]]
[--keep_vae_loaded [KEEP_VAE_LOADED]]
[--skip_file_discovery SKIP_FILE_DISCOVERY]
[--data_backend_sampling {uniform,auto-weighting}]
[--image_processing_batch_size IMAGE_PROCESSING_BATCH_SIZE]
[--write_batch_size WRITE_BATCH_SIZE]
[--read_batch_size READ_BATCH_SIZE]
[--text_encoder_batch_size TEXT_ENCODER_BATCH_SIZE]
[--enable_multiprocessing [ENABLE_MULTIPROCESSING]]
[--max_workers MAX_WORKERS]
[--aws_max_pool_connections AWS_MAX_POOL_CONNECTIONS]
[--torch_num_threads TORCH_NUM_THREADS]
[--dataloader_prefetch [DATALOADER_PREFETCH]]
[--dataloader_prefetch_qlen DATALOADER_PREFETCH_QLEN]
[--dataloader_prefetch_device_threshold_mb DATALOADER_PREFETCH_DEVICE_THRESHOLD_MB]
[--aspect_bucket_worker_count ASPECT_BUCKET_WORKER_COUNT]
[--aspect_bucket_alignment {8,16,24,32,64}]
[--minimum_image_size MINIMUM_IMAGE_SIZE]
[--maximum_image_size MAXIMUM_IMAGE_SIZE]
[--target_downsample_size TARGET_DOWNSAMPLE_SIZE]
[--max_upscale_threshold MAX_UPSCALE_THRESHOLD]
[--metadata_update_interval METADATA_UPDATE_INTERVAL]
[--debug_aspect_buckets [DEBUG_ASPECT_BUCKETS]]
[--debug_dataset_loader [DEBUG_DATASET_LOADER]]
[--print_filenames [PRINT_FILENAMES]]
[--print_sampler_statistics [PRINT_SAMPLER_STATISTICS]]
[--timestep_bias_strategy {earlier,later,range,none}]
[--timestep_bias_begin TIMESTEP_BIAS_BEGIN]
[--timestep_bias_end TIMESTEP_BIAS_END]
[--timestep_bias_multiplier TIMESTEP_BIAS_MULTIPLIER]
[--timestep_bias_portion TIMESTEP_BIAS_PORTION]
[--training_scheduler_timestep_spacing {leading,linspace,trailing}]
[--inference_scheduler_timestep_spacing {leading,linspace,trailing}]
[--loss_type {l2,huber,smooth_l1}]
[--huber_schedule {snr,exponential,constant}]
[--huber_c HUBER_C] [--snr_gamma SNR_GAMMA]
[--masked_loss_probability MASKED_LOSS_PROBABILITY]
[--hidream_use_load_balancing_loss [HIDREAM_USE_LOAD_BALANCING_LOSS]]
[--hidream_load_balancing_loss_weight HIDREAM_LOAD_BALANCING_LOSS_WEIGHT]
[--adam_beta1 ADAM_BETA1] [--adam_beta2 ADAM_BETA2]
[--optimizer_beta1 OPTIMIZER_BETA1]
[--optimizer_beta2 OPTIMIZER_BETA2]
[--optimizer_cpu_offload_method {none}]
[--gradient_precision {unmodified,fp32}]
[--adam_weight_decay ADAM_WEIGHT_DECAY]
[--adam_epsilon ADAM_EPSILON] [--prodigy_steps PRODIGY_STEPS]
[--max_grad_norm MAX_GRAD_NORM]
[--grad_clip_method {value,norm}]
[--optimizer_offload_gradients [OPTIMIZER_OFFLOAD_GRADIENTS]]
[--fuse_optimizer [FUSE_OPTIMIZER]]
[--optimizer_release_gradients [OPTIMIZER_RELEASE_GRADIENTS]]
[--push_to_hub [PUSH_TO_HUB]]
[--push_to_hub_background [PUSH_TO_HUB_BACKGROUND]]
[--push_checkpoints_to_hub [PUSH_CHECKPOINTS_TO_HUB]]
[--publishing_config PUBLISHING_CONFIG]
[--hub_model_id HUB_MODEL_ID]
[--model_card_private [MODEL_CARD_PRIVATE]]
[--model_card_safe_for_work [MODEL_CARD_SAFE_FOR_WORK]]
[--model_card_note MODEL_CARD_NOTE]
[--model_card_base_model MODEL_CARD_BASE_MODEL]
[--modelspec_comment MODELSPEC_COMMENT]
[--report_to {simpletuner,tensorboard,wandb,swanlab,comet_ml,custom-tracker,none}]
[--checkpoint_step_interval CHECKPOINT_STEP_INTERVAL]
[--checkpoint_epoch_interval CHECKPOINT_EPOCH_INTERVAL]
[--checkpointing_rolling_steps CHECKPOINTING_ROLLING_STEPS]
[--checkpointing_use_tempdir [CHECKPOINTING_USE_TEMPDIR]]
[--delete_invalid_checkpoints [DELETE_INVALID_CHECKPOINTS]]
[--checkpoints_rolling_total_limit CHECKPOINTS_ROLLING_TOTAL_LIMIT]
[--tracker_run_name TRACKER_RUN_NAME]
[--tracker_project_name TRACKER_PROJECT_NAME]
[--tracker_image_layout {gallery,table}]
[--enable_watermark [ENABLE_WATERMARK]]
[--framerate FRAMERATE]
[--seed_for_each_device [SEED_FOR_EACH_DEVICE]]
[--snr_weight SNR_WEIGHT]
[--rescale_betas_zero_snr [RESCALE_BETAS_ZERO_SNR]]
[--webhook_config WEBHOOK_CONFIG]
[--webhook_reporting_interval WEBHOOK_REPORTING_INTERVAL]
[--distillation_method {lcm,dcm,dmd,perflow,flow_dpo,anyflow,assistant_lora,h3_drift,self_transcendence}]
[--distillation_config DISTILLATION_CONFIG]
[--ema_validation {none,ema_only,comparison}]
[--local_rank LOCAL_RANK] [--ltx_train_mode {t2v,i2v}]
[--ltx_i2v_prob LTX_I2V_PROB]
[--ltx_partial_noise_fraction LTX_PARTIAL_NOISE_FRACTION]
[--ltx_protect_first_frame [LTX_PROTECT_FIRST_FRAME]]
[--offload_param_path OFFLOAD_PARAM_PATH]
[--offset_noise [OFFSET_NOISE]]
[--quantize_activations [QUANTIZE_ACTIVATIONS]]
[--refiner_training [REFINER_TRAINING]]
[--refiner_training_invert_schedule [REFINER_TRAINING_INVERT_SCHEDULE]]
[--refiner_training_strength REFINER_TRAINING_STRENGTH]
[--sdxl_refiner_uses_full_range [SDXL_REFINER_USES_FULL_RANGE]]
[--sana_complex_human_instruction SANA_COMPLEX_HUMAN_INSTRUCTION]
The following SimpleTuner command-line options are available:
参数¶
options:
-h, --help show this help message and exit
--model_family {kolors,auraflow,omnigen,flux,deepfloyd,cosmos2image,sana,qwen_image,pixart_sigma,sdxl,sd1x,sd2x,wan,hidream,sd3,lumina2,ltxvideo,ace_step,heartmula}
The base model architecture family to train
--model_flavour MODEL_FLAVOUR
Specific variant of the selected model family.
ACE-Step 的 flavour 包括 `base`、`v15-turbo`、
`v15-base` 和 `v15-sft`。v1.5 flavour 现已支持训练和
内置验证音频生成，并且对上游仓库需要
`--trust_remote_code`。
--controlnet [CONTROLNET]
Train ControlNet (full or LoRA) branches alongside the
primary network.
--pretrained_model_name_or_path PRETRAINED_MODEL_NAME_OR_PATH
Optional override of the model checkpoint. Leave blank
to use the default path for the selected model
flavour.
--output_dir OUTPUT_DIR
Directory where model checkpoints and logs will be
saved
--logging_dir LOGGING_DIR
Directory for TensorBoard logs
--model_type {full,lora}
Choose between full model training or LoRA adapter
training
--seed SEED Seed used for deterministic training behaviour
--resolution RESOLUTION
Resolution for training images
--resume_from_checkpoint RESUME_FROM_CHECKPOINT
Select checkpoint to resume training from
--prediction_type {epsilon,v_prediction,sample,flow_matching,flow_map}
The parameterization type for the diffusion model
--pretrained_vae_model_name_or_path PRETRAINED_VAE_MODEL_NAME_OR_PATH
Path to pretrained VAE model
--vae_dtype {default,fp32,fp16,bf16}
Precision for VAE encoding/decoding. Lower precision
saves memory.
--vae_cache_ondemand [VAE_CACHE_ONDEMAND]
Process VAE latents during training instead of
precomputing them
--vae_cache_disable [VAE_CACHE_DISABLE]
Implicitly enables on-demand caching and disables
writing embeddings to disk.
--accelerator_cache_clear_interval ACCELERATOR_CACHE_CLEAR_INTERVAL
Clear the cache from VRAM every X steps to prevent
memory leaks
--aspect_bucket_rounding {1,2,3,4,5,6,7,8,9}
Number of decimal places to round aspect ratios to for
bucket creation
--base_model_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}
Precision for loading the base model. Lower precision
saves memory.
--text_encoder_1_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}
Precision for text encoders. Lower precision saves
memory.
--text_encoder_2_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}
Precision for text encoders. Lower precision saves
memory.
--text_encoder_3_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}
Precision for text encoders. Lower precision saves
memory.
--text_encoder_4_precision {no_change,int8-quanto,int4-quanto,int2-quanto,int8-torchao,int8dq-torchao,int8dq-int4-torchao,nf4-bnb,int4-torchao,fp8-quanto,fp8uz-quanto,fp8-native,fp8-torchao,fp8wo-torchao,fp8-int4-torchao,fp8-transformerengine}
Precision for text encoders. Lower precision saves
memory.
--gradient_checkpointing_interval GRADIENT_CHECKPOINTING_INTERVAL
Checkpoint every N transformer blocks
--gradient_checkpointing_segment_stride GRADIENT_CHECKPOINTING_SEGMENT_STRIDE
Start a checkpointed segment every N transformer blocks
--offload_during_startup [OFFLOAD_DURING_STARTUP]
Offload text encoders to CPU during VAE caching
--quantize_via {cpu,accelerator,pipeline}
Where to perform model quantization
--quantization_config QUANTIZATION_CONFIG
JSON or file path describing Diffusers quantization
config for pipeline quantization
--fuse_qkv_projections [FUSE_QKV_PROJECTIONS]
Enables Flash Attention 3 when supported; otherwise
falls back to PyTorch SDPA.
--control [CONTROL] Enable channel-wise control style training
--controlnet_custom_config CONTROLNET_CUSTOM_CONFIG
Custom configuration for ControlNet models
--controlnet_model_name_or_path CONTROLNET_MODEL_NAME_OR_PATH
Path to ControlNet model weights to preload
--tread_config TREAD_CONFIG
Configuration for TREAD training method
--diffusion_blocks_config DIFFUSION_BLOCKS_CONFIG
Configuration for DiffusionBlocks training
--pretrained_transformer_model_name_or_path PRETRAINED_TRANSFORMER_MODEL_NAME_OR_PATH
Path to pretrained transformer model
--pretrained_transformer_subfolder PRETRAINED_TRANSFORMER_SUBFOLDER
Subfolder containing transformer model weights
--pretrained_unet_model_name_or_path PRETRAINED_UNET_MODEL_NAME_OR_PATH
Path to pretrained UNet model
--pretrained_unet_subfolder PRETRAINED_UNET_SUBFOLDER
Subfolder containing UNet model weights
--pretrained_t5_model_name_or_path PRETRAINED_T5_MODEL_NAME_OR_PATH
Path to pretrained T5 model
--pretrained_gemma_model_name_or_path PRETRAINED_GEMMA_MODEL_NAME_OR_PATH
Path to pretrained Gemma model
--qwen_text_encoder_model_name_or_path QWEN_TEXT_ENCODER_MODEL_NAME_OR_PATH
Path to pretrained Qwen text encoder model
--revision REVISION Git branch/tag/commit for model version
--variant VARIANT Model variant (e.g., fp16, bf16)
--base_model_default_dtype {bf16,fp32}
Default precision for quantized base model weights
--unet_attention_slice [UNET_ATTENTION_SLICE]
Enable attention slicing for SDXL UNet
--num_train_epochs NUM_TRAIN_EPOCHS
Number of times to iterate through the entire dataset
--max_train_steps MAX_TRAIN_STEPS
Maximum number of training steps (0 = use epochs
instead)
--train_batch_size TRAIN_BATCH_SIZE
Number of samples processed per forward/backward pass
(per device).
--learning_rate LEARNING_RATE
Base learning rate for training
--optimizer {adamw_bf16,ao-adamw8bit,ao-adamw4bit,ao-adamfp8,ao-adamwfp8,adamw_schedulefree,adamw_schedulefree+aggressive,adamw_schedulefree+no_kahan,optimi-stableadamw,optimi-adamw,optimi-lion,optimi-radam,optimi-ranger,optimi-adan,optimi-adam,optimi-sgd,soap,prodigy}
Optimization algorithm for training
--optimizer_config OPTIMIZER_CONFIG
Comma-separated key=value pairs forwarded to the
selected optimizer
--lr_scheduler {linear,sine,cosine,cosine_with_restarts,polynomial,constant,constant_with_warmup}
How learning rate changes during training
--gradient_accumulation_steps GRADIENT_ACCUMULATION_STEPS
Number of steps to accumulate gradients
--lr_warmup_steps LR_WARMUP_STEPS
Number of steps to gradually increase LR from 0
--checkpoints_total_limit CHECKPOINTS_TOTAL_LIMIT
Maximum number of checkpoints to keep on disk
--gradient_checkpointing [GRADIENT_CHECKPOINTING]
Trade compute for memory during training
--train_text_encoder [TRAIN_TEXT_ENCODER]
Also train the text encoder (CLIP) model
--text_encoder_lr TEXT_ENCODER_LR
Separate learning rate for text encoder
--lr_num_cycles LR_NUM_CYCLES
Number of cosine annealing cycles
--lr_power LR_POWER Power for polynomial decay scheduler
--use_soft_min_snr [USE_SOFT_MIN_SNR]
Use soft clamping instead of hard clamping for Min-SNR
--use_ema [USE_EMA] Maintain an exponential moving average copy of the
model during training.
--ema_device {accelerator,cpu}
Where to keep the EMA weights in-between updates.
--ema_cpu_only [EMA_CPU_ONLY]
Keep EMA weights exclusively on CPU even when
ema_device would normally move them.
--ema_update_interval EMA_UPDATE_INTERVAL
Update EMA weights every N optimizer steps
--ema_foreach_disable [EMA_FOREACH_DISABLE]
Fallback to standard tensor ops instead of
torch.foreach updates.
--ema_decay EMA_DECAY
Smoothing factor for EMA updates (closer to 1.0 =
slower drift).
--lora_rank LORA_RANK
Dimension of LoRA update matrices
--lora_alpha LORA_ALPHA
Scaling factor for LoRA updates
--lora_type {standard,lycoris}
LoRA implementation type
--lora_dropout LORA_DROPOUT
LoRA dropout randomly ignores neurons during training.
This can help prevent overfitting.
--lora_init_type {default,gaussian,loftq,olora,pissa}
The initialization type for the LoRA model
--peft_lora_mode {standard,singlora}
PEFT LoRA training mode
--peft_lora_target_modules PEFT_LORA_TARGET_MODULES
JSON array (or path to a JSON file) listing PEFT
LoRA target module names. Overrides preset targets.
--singlora_ramp_up_steps SINGLORA_RAMP_UP_STEPS
Number of ramp-up steps for SingLoRA
--slider_lora_target [SLIDER_LORA_TARGET]
Route LoRA training to slider-friendly targets
(self-attn + conv/time embeddings). Only affects
standard PEFT LoRA.
--init_lora INIT_LORA
Specify an existing LoRA or LyCORIS safetensors file
to initialize the adapter
--init_lora_step INIT_LORA_STEP
Continue global-step accounting from a model-only LoRA
checkpoint without optimizer state
--init_lora_ema INIT_LORA_EMA
Load a raw SimpleTuner EMA state alongside init_lora
--lycoris_config LYCORIS_CONFIG
Path to LyCORIS configuration JSON file
--init_lokr_norm INIT_LOKR_NORM
Perturbed normal initialization for LyCORIS LoKr
layers
--flux_lora_target {mmdit,context,context+ffs,all,all+ffs,ai-toolkit,tiny,nano,controlnet,all+ffs+embedder,all+ffs+embedder+controlnet}
Which layers to train in Flux models
--use_dora [USE_DORA]
Enable DoRA (Weight-Decomposed LoRA)
--resolution_type {pixel,area,pixel_area}
How to interpret the resolution value
--data_backend_config DATA_BACKEND_CONFIG
Select a saved dataset configuration (managed in
Datasets & Environments tabs)
--caption_strategy {filename,textfile,instance_prompt,parquet}
How to load captions for images
--conditioning_multidataset_sampling {combined,random}
How to sample from multiple conditioning datasets
--instance_prompt INSTANCE_PROMPT
Instance prompt for training
--parquet_caption_column PARQUET_CAPTION_COLUMN
Column name containing captions in parquet files
--parquet_filename_column PARQUET_FILENAME_COLUMN
Column name containing image paths in parquet files
--ignore_missing_files [IGNORE_MISSING_FILES]
Continue training even if some files are missing
--vae_cache_scan_behaviour {recreate,sync}
How to scan VAE cache for missing files
--vae_enable_slicing [VAE_ENABLE_SLICING]
Enable VAE attention slicing for memory efficiency
--vae_enable_tiling [VAE_ENABLE_TILING]
Enable VAE tiling for large images
--vae_enable_patch_conv [VAE_ENABLE_PATCH_CONV]
Enable patch-based 3D conv for HunyuanVideo VAE to
reduce peak VRAM (slight slowdown)
--vae_batch_size VAE_BATCH_SIZE
Batch size for VAE encoding during caching
--caption_dropout_probability CAPTION_DROPOUT_PROBABILITY
Caption dropout will randomly drop captions and, for
SDXL, size conditioning inputs based on this
probability
--tokenizer_max_length TOKENIZER_MAX_LENGTH
Override the tokenizer sequence length (advanced).
--validation_step_interval VALIDATION_STEP_INTERVAL
Run validation every N training steps (deprecated alias: --validation_steps)
--validation_epoch_interval VALIDATION_EPOCH_INTERVAL
Run validation every N training epochs
--validate_after_step VALIDATE_AFTER_STEP
Skip scheduled validation until the global training
step reaches this value
--validate_after_epoch VALIDATE_AFTER_EPOCH
Skip scheduled validation until the training epoch
reaches this value
--disable_benchmark [DISABLE_BENCHMARK]
Skip generating baseline comparison images before
training starts
--validation_prompt VALIDATION_PROMPT
Prompt to use for validation images
--validation_input VALIDATION_INPUT
JSON list of validation input image paths and prompts
--num_validation_images NUM_VALIDATION_IMAGES
Number of images to generate per validation
--num_eval_images NUM_EVAL_IMAGES
Number of images to generate for evaluation metrics
--eval_steps_interval EVAL_STEPS_INTERVAL
Run evaluation every N training steps
--eval_epoch_interval EVAL_EPOCH_INTERVAL
Run evaluation every N training epochs (decimals run
multiple times per epoch)
--eval_timesteps EVAL_TIMESTEPS
Number of timesteps for evaluation
--eval_dataset_pooling [EVAL_DATASET_POOLING]
Combine evaluation metrics from all datasets into a
single chart
--evaluation_type {none,clip}
Type of evaluation metrics to compute
--pretrained_evaluation_model_name_or_path PRETRAINED_EVALUATION_MODEL_NAME_OR_PATH
Path to pretrained model for evaluation metrics
--validation_guidance VALIDATION_GUIDANCE
CFG guidance scale for validation images
--validation_num_inference_steps VALIDATION_NUM_INFERENCE_STEPS
Number of diffusion steps for validation renders
--validation_on_startup [VALIDATION_ON_STARTUP]
Run validation on the base model before training
starts
--validation_using_datasets [VALIDATION_USING_DATASETS]
Use random images from training datasets for
validation
--validation_torch_compile [VALIDATION_TORCH_COMPILE]
Use torch.compile() on validation pipeline for speed
--validation_guidance_real VALIDATION_GUIDANCE_REAL
CFG value for distilled models (e.g., FLUX schnell)
--validation_no_cfg_until_timestep VALIDATION_NO_CFG_UNTIL_TIMESTEP
Skip CFG for initial timesteps (Flux only)
--validation_negative_prompt VALIDATION_NEGATIVE_PROMPT
Negative prompt for validation images
--validation_randomize [VALIDATION_RANDOMIZE]
Use random seeds for each validation
--validation_seed VALIDATION_SEED
Fixed seed for reproducible validation images
--validation_disable [VALIDATION_DISABLE]
Completely disable validation image generation
--validation_prompt_library [VALIDATION_PROMPT_LIBRARY]
使用 SimpleTuner 内置 prompt 库。音乐/音频的
caption + lyrics prompt 可使用 "audio"。
--user_prompt_library USER_PROMPT_LIBRARY
自定义 JSON prompt 库路径。条目可使用 prompt 或
caption，并可选提供 lyrics。
--eval_dataset_id EVAL_DATASET_ID
Specific dataset to use for evaluation metrics
--validation_stitch_input_location {left,right}
Where to place input image in img2img validations
--validation_guidance_rescale VALIDATION_GUIDANCE_RESCALE
CFG rescale value for validation
--validation_disable_unconditional [VALIDATION_DISABLE_UNCONDITIONAL]
Disable unconditional image generation during
validation
--validation_guidance_skip_layers VALIDATION_GUIDANCE_SKIP_LAYERS
JSON list of transformer layers to skip during
classifier-free guidance
--validation_guidance_skip_layers_start VALIDATION_GUIDANCE_SKIP_LAYERS_START
Starting layer index to skip guidance
--validation_guidance_skip_layers_stop VALIDATION_GUIDANCE_SKIP_LAYERS_STOP
Ending layer index to skip guidance
--validation_guidance_skip_scale VALIDATION_GUIDANCE_SKIP_SCALE
Scale guidance strength when applying layer skipping
--validation_lycoris_strength VALIDATION_LYCORIS_STRENGTH
Strength multiplier for LyCORIS validation
--validation_noise_scheduler {ddim,ddpm,euler,euler-a,unipc,dpm++,perflow}
Noise scheduler for validation
--validation_num_video_frames VALIDATION_NUM_VIDEO_FRAMES
Number of frames for video validation
--validation_audio_only [VALIDATION_AUDIO_ONLY]
Disable video generation during validation and emit
audio only
--validation_resolution VALIDATION_RESOLUTION
Override resolution for validation images (pixels or
megapixels)
--validation_seed_source {cpu,gpu}
Source device used to generate validation seeds
--i_know_what_i_am_doing [I_KNOW_WHAT_I_AM_DOING]
Unlock experimental overrides and bypass built-in
safety limits. Also bypasses the sampler batch-size
mismatch check on resume (same effect as
SIMPLETUNER_ALLOW_MODIFYING_BSZ=1).
--flow_sigmoid_scale FLOW_SIGMOID_SCALE
Scale factor for sigmoid timestep sampling for flow-
matching models.
--flux_fast_schedule [FLUX_FAST_SCHEDULE]
Use experimental fast schedule for Flux training
--flow_use_uniform_schedule [FLOW_USE_UNIFORM_SCHEDULE]
Use uniform schedule instead of sigmoid for flow-
matching
--flow_use_beta_schedule [FLOW_USE_BETA_SCHEDULE]
Use beta schedule instead of sigmoid for flow-matching
--flow_beta_schedule_alpha FLOW_BETA_SCHEDULE_ALPHA
Alpha value for beta schedule (default: 2.0)
--flow_beta_schedule_beta FLOW_BETA_SCHEDULE_BETA
Beta value for beta schedule (default: 2.0)
--flow_cubic_schedule_weights FLOW_CUBIC_SCHEDULE_WEIGHTS
Sample flow timesteps from a smooth density through
equally spaced non-negative weights. Use a JSON array
or comma-separated values; zero or one weight produces
a uniform distribution.
--flow_schedule_shift FLOW_SCHEDULE_SHIFT
Shift the noise schedule for flow-matching models
--flow_schedule_auto_shift [FLOW_SCHEDULE_AUTO_SHIFT]
Auto-adjust schedule shift based on image resolution
--mixflow_enabled [MIXFLOW_ENABLED]
Enable MixFlow slowed-interpolation post-training for
flow-matching models.
--mixflow_gamma MIXFLOW_GAMMA
Set the MixFlow slowed-interpolation range coefficient
(default: 0.8).
--audio_flow_schedule_shift AUDIO_FLOW_SCHEDULE_SHIFT
Shift the audio noise schedule for flow-matching
models with audio latents
--flow_custom_timesteps FLOW_CUSTOM_TIMESTEPS
Override flow-matching timestep sampling with a fixed
comma-separated list. The list is interpreted as
sigmas only when every value is in [0,1]; otherwise
all values are interpreted as timesteps [0,1000].
--flow_timesteps_mode {fixed-list,round-robin}
Select how flow_custom_timesteps values are assigned
to samples.
--flux_guidance_mode {constant,random-range}
Guidance mode for Flux training
--flux_attention_masked_training [FLUX_ATTENTION_MASKED_TRAINING]
Enable attention masked training for Flux models
--flux_guidance_value FLUX_GUIDANCE_VALUE
Guidance value for constant mode
--flux_guidance_min FLUX_GUIDANCE_MIN
Minimum guidance value for random-range mode
--flux_guidance_max FLUX_GUIDANCE_MAX
Maximum guidance value for random-range mode
--t5_padding {zero,unmodified}
Padding behavior for T5 text encoder
--sd3_clip_uncond_behaviour {empty_string,zero}
How SD3 handles unconditional prompts
--sd3_t5_uncond_behaviour {empty_string,zero}
How SD3 T5 handles unconditional prompts
--soft_min_snr_sigma_data SOFT_MIN_SNR_SIGMA_DATA
Sigma data for soft min SNR weighting
--mixed_precision {no,fp16,bf16,fp8}
Precision for training computations
--attention_mechanism {diffusers,xformers,flash-attn,flash-attn-2,flash-attn-3,flash-attn-3-varlen,flex,kohaku-fa,kohaku-fa-auto,metal-flash-attention,metal-flash-attention-int8,metal-flash-attention-int4,cudnn,native-efficient,native-flash,native-math,native-npu,native-xla,sla,sageattention,sageattention-int8-fp16-triton,sageattention-int8-fp16-cuda,sageattention-int8-fp8-cuda}
Attention computation backend
--sageattention_usage {training,inference,training+inference}
When to use SageAttention
--disable_tf32 [DISABLE_TF32]
Force IEEE FP32 precision (disables TF32) using
PyTorch's fp32_precision controls when available
--set_grads_to_none [SET_GRADS_TO_NONE]
Set gradients to None instead of zero
--noise_offset NOISE_OFFSET
Add noise offset to training
--noise_offset_probability NOISE_OFFSET_PROBABILITY
Probability of applying noise offset
--input_perturbation INPUT_PERTURBATION
Add additional noise only to the inputs fed to the
model during training
--input_perturbation_steps INPUT_PERTURBATION_STEPS
Only apply input perturbation over the first N steps
with linear decay
--lr_end LR_END A polynomial learning rate will end up at this value
after the specified number of warmup steps
--lr_scale [LR_SCALE]
Scale the learning rate by the number of GPUs,
gradient accumulation steps, and batch size
--lr_scale_sqrt [LR_SCALE_SQRT]
If using --lr_scale, use the square root of (number of
GPUs * gradient accumulation steps * batch size)
--strict_epoch_limit [STRICT_EPOCH_LIMIT]
Stop training when the epoch counter reaches
--num_train_epochs, even if --max_train_steps
has not been reached
--freeze_encoder_before FREEZE_ENCODER_BEFORE
When using 'before' strategy, we will freeze layers
earlier than this
--freeze_encoder_after FREEZE_ENCODER_AFTER
When using 'after' strategy, we will freeze layers
later than this
--freeze_encoder_strategy {before,between,after}
When freezing the text encoder, we can use the
'before', 'between', or 'after' strategy
--layer_freeze_strategy {none,bitfit}
When freezing parameters, we can use the 'none' or
'bitfit' strategy
--fully_unload_text_encoder [FULLY_UNLOAD_TEXT_ENCODER]
If set, will fully unload the text_encoder from memory
when not in use
--save_text_encoder [SAVE_TEXT_ENCODER]
If set, will save the text encoder after training
--text_encoder_limit TEXT_ENCODER_LIMIT
When training the text encoder, we want to limit how
long it trains for to avoid catastrophic loss
--prepend_instance_prompt [PREPEND_INSTANCE_PROMPT]
When determining the captions from the filename,
prepend the instance prompt as an enforced keyword
--only_instance_prompt [ONLY_INSTANCE_PROMPT]
Use the instance prompt instead of the caption from
filename
--data_aesthetic_score DATA_AESTHETIC_SCORE
Since currently we do not calculate aesthetic scores
for data, we will statically set it to one value. This
is only used by the SDXL Refiner
--delete_unwanted_images [DELETE_UNWANTED_IMAGES]
If set, will delete images that are not of a minimum
size to save on disk space for large training runs
--delete_problematic_images [DELETE_PROBLEMATIC_IMAGES]
If set, any images that error out during load will be
removed from the underlying storage medium
--disable_bucket_pruning [DISABLE_BUCKET_PRUNING]
When training on very small datasets, you might not
care that the batch sizes will outpace your image
count. Setting this option will prevent SimpleTuner
from deleting your bucket lists that do not meet the
minimum image count requirements. Use at your own
risk, it may end up throwing off your statistics or
epoch tracking
--disable_segmented_timestep_sampling [DISABLE_SEGMENTED_TIMESTEP_SAMPLING]
By default, the timestep schedule is divided into
roughly `train_batch_size` number of segments, and
then each of those are sampled from separately. This
improves the selection distribution, but may not be
desired in certain training scenarios, eg. when
limiting the timestep selection range
--preserve_data_backend_cache [PRESERVE_DATA_BACKEND_CACHE]
For very large cloud storage buckets that will never
change, enabling this option will prevent the trainer
from scanning it at startup, by preserving the cache
files that we generate. Be careful when using this,
as, switching datasets can result in the preserved
cache being used, which would be problematic.
Currently, cache is not stored in the dataset itself
but rather, locally. This may change in a future
release
--override_dataset_config [OVERRIDE_DATASET_CONFIG]
When provided, the dataset's config will not be
checked against the live backend config
--cache_dir CACHE_DIR
The directory where the downloaded models and datasets
will be stored
--cache_dir_text CACHE_DIR_TEXT
This is the path to a local directory that will
contain your text embed cache
--text_cache_ondemand [TEXT_CACHE_ONDEMAND]
在训练期间按需编码缺失的文本嵌入，而不是预计算完整文本缓存。
已有条目会被复用，新编码的缺失条目会写入缓存。
--text_cache_disable [TEXT_CACHE_DISABLE]
禁止文本缓存写入，并按需编码缺失嵌入。已有缓存条目仍会读取。
该选项隐含启用 --text_cache_ondemand。
--text_embed_full_cache [TEXT_EMBED_FULL_CACHE]
Store full raw text encoder outputs in the text embed
cache. This opts out of model-specific cache size
optimisations, such as Ideogram 4's frozen text
projection cache.
--cache_dir_vae CACHE_DIR_VAE
This is the path to a local directory that will
contain your VAE outputs
--compress_disk_cache [COMPRESS_DISK_CACHE]
If set, will gzip-compress the disk cache for Pytorch
files. This will save substantial disk space, but may
slow down the training process
--aspect_bucket_disable_rebuild [ASPECT_BUCKET_DISABLE_REBUILD]
When using a randomised aspect bucket list, the VAE
and aspect cache are rebuilt on each epoch. With a
large and diverse enough dataset, rebuilding the
aspect list may take a long time, and this may be
undesirable. This option will not override
vae_cache_clear_each_epoch. If both options are
provided, only the VAE cache will be rebuilt
--keep_vae_loaded [KEEP_VAE_LOADED]
If set, will keep the VAE loaded in memory. This can
reduce disk churn, but consumes VRAM during the
forward pass
--skip_file_discovery SKIP_FILE_DISCOVERY
Comma-separated values of which stages to skip
discovery for. Skipping any stage will speed up
resumption, but will increase the risk of errors, as
missing images or incorrectly bucketed images may not
be caught. Valid options: aspect, vae, text, metadata
--data_backend_sampling {uniform,auto-weighting}
When using multiple data backends, the sampling
weighting can be set to 'uniform' or 'auto-weighting'
--image_processing_batch_size IMAGE_PROCESSING_BATCH_SIZE
When resizing and cropping images, we do it in
parallel using processes or threads. This defines how
many images will be read into the queue before they
are processed
--write_batch_size WRITE_BATCH_SIZE
When using certain storage backends, it is better to
batch smaller writes rather than continuous
dispatching. In SimpleTuner, write batching is
currently applied during VAE caching, when many small
objects are written. This mostly applies to S3, but
some shared server filesystems may benefit as well.
Default: 64
--read_batch_size READ_BATCH_SIZE
Used by the VAE cache to prefetch image data. This is
the number of images to read ahead
--text_encoder_batch_size TEXT_ENCODER_BATCH_SIZE
Batch size used when precomputing uncached text
embeddings. A value of 1 preserves the original one-
caption-per-forward behavior.
--enable_multiprocessing [ENABLE_MULTIPROCESSING]
If set, will use processes instead of threads during
metadata caching operations
--max_workers MAX_WORKERS
How many active threads or processes to run during VAE
caching
--aws_max_pool_connections AWS_MAX_POOL_CONNECTIONS
When using AWS backends, the maximum number of
connections to keep open to the S3 bucket at a single
time
--torch_num_threads TORCH_NUM_THREADS
The number of threads to use for PyTorch operations.
This is not the same as the number of workers
--dataloader_prefetch [DATALOADER_PREFETCH]
When provided, the dataloader will read-ahead and
attempt to retrieve latents, text embeds, and other
metadata ahead of the time when the batch is required,
so that it can be immediately available
--dataloader_prefetch_qlen DATALOADER_PREFETCH_QLEN
Set the number of prefetched batches
--dataloader_prefetch_device_threshold_mb DATALOADER_PREFETCH_DEVICE_THRESHOLD_MB
Minimum CPU batch payload in MiB to page-lock and
transfer on a dedicated CUDA stream during dataloader
prefetch; 0 disables device staging
--aspect_bucket_worker_count ASPECT_BUCKET_WORKER_COUNT
The number of workers to use for aspect bucketing.
This is a CPU-bound task, so the number of workers
should be set to the number of CPU threads available.
If you use an I/O bound backend, an even higher value
may make sense. Default: 12
--aspect_bucket_alignment {8,16,24,32,64}
When training diffusion models, the image sizes
generally must align to a 64 pixel interval
--minimum_image_size MINIMUM_IMAGE_SIZE
The minimum resolution for both sides of input images
--maximum_image_size MAXIMUM_IMAGE_SIZE
When cropping images that are excessively large, the
entire scene context may be lost, eg. the crop might
just end up being a portion of the background. To
avoid this, a maximum image size may be provided,
which will result in very-large images being
downsampled before cropping them. This value uses
--resolution_type to determine whether it is a pixel
edge or megapixel value
--target_downsample_size TARGET_DOWNSAMPLE_SIZE
When using --maximum_image_size, very-large images
exceeding that value will be downsampled to this
target size before cropping
--max_upscale_threshold MAX_UPSCALE_THRESHOLD
Limit upscaling of small images to prevent quality
degradation (opt-in). When set, filters out aspect
buckets requiring upscaling beyond this threshold.
For example, 0.2 allows up to 20% upscaling. Default
(None) allows unlimited upscaling. Must be between 0
and 1.
--metadata_update_interval METADATA_UPDATE_INTERVAL
When generating the aspect bucket indicies, we want to
save it every X seconds
--debug_aspect_buckets [DEBUG_ASPECT_BUCKETS]
If set, will print excessive debugging for aspect
bucket operations
--debug_dataset_loader [DEBUG_DATASET_LOADER]
If set, will print excessive debugging for data loader
operations
--print_filenames [PRINT_FILENAMES]
If any image files are stopping the process eg. due to
corruption or truncation, this will help identify
which is at fault
--print_sampler_statistics [PRINT_SAMPLER_STATISTICS]
If provided, will print statistics about the dataset
sampler. This is useful for debugging
--timestep_bias_strategy {earlier,later,range,none}
Strategy for biasing timestep sampling
--timestep_bias_begin TIMESTEP_BIAS_BEGIN
Beginning of timestep bias range
--timestep_bias_end TIMESTEP_BIAS_END
End of timestep bias range
--timestep_bias_multiplier TIMESTEP_BIAS_MULTIPLIER
Multiplier for timestep bias probability
--timestep_bias_portion TIMESTEP_BIAS_PORTION
Portion of training steps to apply timestep bias
--training_scheduler_timestep_spacing {leading,linspace,trailing}
Timestep spacing for training scheduler
--inference_scheduler_timestep_spacing {leading,linspace,trailing}
Timestep spacing for inference scheduler
--loss_type {l2,huber,smooth_l1}
Loss function for training
--huber_schedule {snr,exponential,constant}
Schedule for Huber loss transition threshold
--huber_c HUBER_C Transition point between L2 and L1 regions for Huber
loss
--snr_gamma SNR_GAMMA
SNR weighting gamma value (0 = disabled)
--masked_loss_probability MASKED_LOSS_PROBABILITY
Probability of applying masked loss weighting per
batch
--hidream_use_load_balancing_loss [HIDREAM_USE_LOAD_BALANCING_LOSS]
Apply experimental load balancing loss when training
HiDream models.
--hidream_load_balancing_loss_weight HIDREAM_LOAD_BALANCING_LOSS_WEIGHT
Strength multiplier for HiDream load balancing loss.
--adam_beta1 ADAM_BETA1
First moment decay rate for Adam optimizers
--adam_beta2 ADAM_BETA2
Second moment decay rate for Adam optimizers
--optimizer_beta1 OPTIMIZER_BETA1
First moment decay rate for optimizers
--optimizer_beta2 OPTIMIZER_BETA2
Second moment decay rate for optimizers
--optimizer_cpu_offload_method {none}
Method for CPU offloading optimizer states
--gradient_precision {unmodified,fp32}
Precision for gradient computation
--adam_weight_decay ADAM_WEIGHT_DECAY
L2 regularisation strength for Adam-family optimizers.
--adam_epsilon ADAM_EPSILON
Small constant added for numerical stability.
--prodigy_steps PRODIGY_STEPS
Number of steps Prodigy should spend adapting its
learning rate.
--max_grad_norm MAX_GRAD_NORM
Gradient clipping threshold to prevent exploding
gradients.
--grad_clip_method {value,norm}
Strategy for applying max_grad_norm during clipping.
--optimizer_offload_gradients [OPTIMIZER_OFFLOAD_GRADIENTS]
Move optimizer gradients to CPU to save GPU memory.
--fuse_optimizer [FUSE_OPTIMIZER]
Enable fused kernels when offloading to reduce memory
overhead.
--optimizer_release_gradients [OPTIMIZER_RELEASE_GRADIENTS]
Free gradient tensors immediately after optimizer step
when using Optimi optimizers.
--push_to_hub [PUSH_TO_HUB]
Automatically upload the trained model to your Hugging
Face Hub repository.
--push_to_hub_background [PUSH_TO_HUB_BACKGROUND]
Run Hub uploads in a background worker so training is
not blocked while pushing.
--push_checkpoints_to_hub [PUSH_CHECKPOINTS_TO_HUB]
Upload intermediate checkpoints to the same Hugging
Face repository during training.
--publishing_config PUBLISHING_CONFIG
Optional JSON/file path describing additional
publishing targets (S3/Backblaze B2/Azure Blob/Dropbox).
--hub_model_id HUB_MODEL_ID
If left blank, SimpleTuner derives a name from the
project settings when pushing to Hub.
--model_card_private [MODEL_CARD_PRIVATE]
Create the Hugging Face repository as private instead
of public.
--model_card_safe_for_work [MODEL_CARD_SAFE_FOR_WORK]
Remove the default NSFW warning from the generated
model card on Hugging Face Hub.
--model_card_base_model MODEL_CARD_BASE_MODEL
Base repository for model-card metadata when training from a local checkpoint.
--model_card_note MODEL_CARD_NOTE
Optional note that appears at the top of the generated
model card.
--modelspec_comment MODELSPEC_COMMENT
Text embedded in safetensors file metadata as
modelspec.comment, visible in external model viewers.
--report_to {simpletuner,tensorboard,wandb,swanlab,comet_ml,custom-tracker,none}
Where to log training metrics
--checkpoint_step_interval CHECKPOINT_STEP_INTERVAL
Save model checkpoint every N steps (deprecated alias: --checkpointing_steps)
--checkpoint_epoch_interval CHECKPOINT_EPOCH_INTERVAL
Save model checkpoint every N epochs
--checkpointing_rolling_steps CHECKPOINTING_ROLLING_STEPS
Rolling checkpoint window size for continuous
checkpointing
--checkpointing_use_tempdir [CHECKPOINTING_USE_TEMPDIR]
Use temporary directory for checkpoint files before
final save
--delete_invalid_checkpoints [DELETE_INVALID_CHECKPOINTS]
Delete local checkpoints that cannot be loaded while
resuming.
--checkpoints_rolling_total_limit CHECKPOINTS_ROLLING_TOTAL_LIMIT
Maximum number of rolling checkpoints to keep
--tracker_run_name TRACKER_RUN_NAME
Name for this training run in tracking platforms
--tracker_project_name TRACKER_PROJECT_NAME
Project name in tracking platforms
--tracker_image_layout {gallery,table}
How validation images are displayed in trackers
--enable_watermark [ENABLE_WATERMARK]
Add invisible watermark to generated images
--framerate FRAMERATE
Framerate for video model training
--seed_for_each_device [SEED_FOR_EACH_DEVICE]
Use a unique deterministic seed per GPU instead of
sharing one seed across devices.
--snr_weight SNR_WEIGHT
Weight factor for SNR-based loss scaling
--rescale_betas_zero_snr [RESCALE_BETAS_ZERO_SNR]
Rescale betas for zero terminal SNR
--webhook_config WEBHOOK_CONFIG
Path to webhook configuration file
--webhook_reporting_interval WEBHOOK_REPORTING_INTERVAL
Interval for webhook reports (seconds)
--distillation_method {lcm,dcm,dmd,perflow,flow_dpo,anyflow,assistant_lora,h3_drift,self_transcendence}
Method for model distillation
Distillation methods cannot be combined with
--train_text_encoder.
--distillation_config DISTILLATION_CONFIG
Path to distillation configuration file
--ema_validation {none,ema_only,comparison}
Control how EMA weights are used during validation
runs.
--local_rank LOCAL_RANK
Local rank for distributed training
--ltx_train_mode {t2v,i2v}
Training mode for LTX models
--ltx_i2v_prob LTX_I2V_PROB
Probability of using image-to-video training for LTX
--ltx_partial_noise_fraction LTX_PARTIAL_NOISE_FRACTION
Fraction of noise to add for LTX partial training
--ltx_protect_first_frame [LTX_PROTECT_FIRST_FRAME]
Protect the first frame from noise in LTX training
--offload_param_path OFFLOAD_PARAM_PATH
Path to offloaded parameter files
--offset_noise [OFFSET_NOISE]
Enable offset-noise training
--quantize_activations [QUANTIZE_ACTIVATIONS]
Quantize model activations during training
--refiner_training [REFINER_TRAINING]
Enable refiner model training mode
--refiner_training_invert_schedule [REFINER_TRAINING_INVERT_SCHEDULE]
Invert the noise schedule for refiner training
--refiner_training_strength REFINER_TRAINING_STRENGTH
Strength of refiner training
--sdxl_refiner_uses_full_range [SDXL_REFINER_USES_FULL_RANGE]
Use full timestep range for SDXL refiner
--sana_complex_human_instruction SANA_COMPLEX_HUMAN_INSTRUCTION
Complex human instruction for Sana model training
--distillation_method=assistant_lora¶
选择 --distillation_method=assistant_lora，使用字幕数据集和禁用适配器后新生成的基础模型输出训练正向辅助适配器。目前支持 Qwen Image 2.1。distillation_config.assistant_lora 接受 num_inference_steps（40）、resolutions（[[1024, 1024]]，宽在前、高在后，均为 32 的倍数）和 seed（42）。需要预缓存文本嵌入，不缓存终态潜变量。参见 Qwen 指南。
字幕数据集要求 dataloader_prefetch: false，确保检查点游标对应已消费的字幕。恢复时若字幕标识或内容、批量、重复次数、打乱设置、种子、梯度累积或分布式布局发生变化，将报错。 辅助 LoRA 检查点同样拒绝更改生成种子、分辨率列表或教师推理步数。
Assistant LoRA 和 AnyFlow 会临时将 Dynamo 每段代码的编译缓存上限提高到至少 32，以容纳教师、训练和验证变体。用户设置的更高上限会保留；退出时（包括发生错误时）恢复原来的上限。