SimpleTuner 💹

ℹ️ 除非通过可选的 report_to、push_to_hub 标志或需手动配置的 Webhook，否则不会向任何第三方发送数据。

SimpleTuner 致力于简洁易懂，代码结构清晰明了。本代码库旨在作为学术交流的共享平台，欢迎各位贡献代码。

如果您想加入我们的社区，可以通过 Terminus 研究组在 Discord 上找到我们。如有任何问题，欢迎随时在 Discord 中与我们联系。

目录

• 设计哲学
• 教程
• 特性
  • 核心训练功能
  • 模型架构支持
  • 高级训练技术
  • 模型特定功能
  • 快速入门指南
• 硬件要求
• 工具集
• 安装与设置
• 故障排除

设计哲学

• 简单性：针对大多数使用场景提供良好的默认配置，减少不必要的调整。
• 通用性：适用于从小型数据集到大规模数据集的各种图像数量。
• 前沿特性：仅采用经过验证有效的功能，避免引入未经测试的新选项。

教程

在开始阅读 新的 Web UI 教程 或 类命令行教程 之前，请务必先完整浏览本 README 文件，因为其中包含了您可能需要首先了解的重要信息。

如果您希望在不阅读完整文档或使用任何 Web 界面的情况下进行手动配置的快速入门，可以参考 快速入门指南。

对于内存受限的系统，请参阅 DeepSpeed 文档，该文档介绍了如何使用 🤗Accelerate 配置 Microsoft 的 DeepSpeed 进行优化器状态卸载。若需了解基于 DTensor 的分片和上下文并行化技术，请阅读 FSDP2 指南，其中详细说明了 SimpleTuner 内部全新的 FullyShardedDataParallel v2 工作流程。

对于多节点分布式训练，此指南 将帮助您调整 INSTALL 和快速入门指南中的配置，使其适用于多节点训练，并针对包含数十亿张样本的大规模图像数据集进行优化。

---

特性

SimpleTuner 提供跨多种扩散模型架构的全面训练支持，且各项功能保持一致：

核心训练功能

• 用户友好的 Web UI：通过简洁的仪表盘管理整个训练流程。
• 多模态训练：统一的管道支持 图像、视频和音频 生成模型。
• 多 GPU 训练：自动优化的多 GPU 分布式训练。
• 高级缓存：将图像、视频、音频及标题嵌入缓存至磁盘，以加快训练速度。
• 宽高比分桶：支持不同尺寸和宽高比的图像/视频。
• 概念滑块：支持 LoRA/LyCORIS/全参数（通过 LyCORIS full）的滑块式微调，具备正/负/中性采样及每条提示语的强度控制；详情请参阅 滑块 LoRA 指南。
• 内存优化：大多数模型可在 24GB 显存的 GPU 上训练，许多模型甚至可以在 16GB 显存上通过优化实现训练。
• DeepSpeed 和 FSDP2 集成：利用优化器/梯度/参数分片、上下文并行注意力、梯度检查点和优化器状态卸载等技术，在较小显存的 GPU 上训练大型模型。
• S3 训练：直接从云存储（Cloudflare R2、Wasabi S3）加载数据进行训练。
• EMA 支持：采用指数移动平均权重，提升稳定性和质量。
• 自定义实验跟踪器：将 accelerate.GeneralTracker 放入 simpletuner/custom-trackers 目录，并使用 --report_to=custom-tracker --custom_tracker=<name> 参数。

多用户与企业级特性

SimpleTuner 包含一个完整的多用户训练平台，具备企业级功能——完全免费且开源，永久可用。

• 工作者编排：注册分布式 GPU 工作者，它们会自动连接到中央面板并接收 SSE 任务分发；支持临时（云端启动）和持久（始终在线）工作者；详情请参阅 工作者编排指南。
• SSO 集成：支持 LDAP/Active Directory 或 OIDC 提供商（Okta、Azure AD、Keycloak、Google）的身份验证；详情请参阅 外部认证指南。
• 基于角色的访问控制：提供四种默认角色（查看者、研究员、负责人、管理员），拥有 17 种以上细粒度权限；可通过 glob 模式定义资源规则，限制团队对配置、硬件或提供商的使用。
• 组织与团队：分层多租户结构，设有上限配额；组织级限制执行绝对最大值，而团队级限制则在组织范围内生效。
• 配额与支出限制：可在组织、团队或用户层面强制执行每日/每月成本上限、作业并发限制以及提交速率限制；可采取阻止、警告或需审批等措施。
• 带优先级的作业队列：五种优先级（低 → 严重），支持跨团队的公平调度，防止长时间等待的作业被饿死，并允许管理员覆盖优先级。
• 审批工作流：可根据规则触发对超出成本阈值、首次使用或特定硬件请求的作业的审批；可通过 UI、API 或邮件回复进行审批。
• 邮件通知：集成 SMTP/IMAP 协议，用于发送作业状态、审批请求、配额警告及完成提醒等通知。
• API 密钥与作用域权限：为 CI/CD 流水线生成具有有效期和有限作用域的 API 密钥。
• 审计日志：记录所有用户操作，并进行链式验证以满足合规要求；详情请参阅 审计指南。

有关部署细节，请参阅 企业版指南。

模型架构支持

模型	参数量	PEFT LoRA	Lycoris	全秩	ControlNet	量化	流匹配	文本编码器
Stable Diffusion XL	3.5B	✓	✓	✓	✓	int8/nf4	✗	CLIP-L/G
Stable Diffusion 3	2B-8B	✓	✓	✓*	✓	int8/fp8/nf4	✓	CLIP-L/G + T5-XXL
Flux.1	12B	✓	✓	✓*	✓	int8/fp8/nf4	✓	CLIP-L + T5-XXL
Flux.2	32B	✓	✓	✓*	✗	int8/fp8/nf4	✓	Mistral-3 Small
ACE-Step	3.5B	✓	✓	✓*	✗	int8	✓	UMT5
HeartMuLa	3B	✓	✓	✓*	✗	int8	✗	无
Chroma 1	8.9B	✓	✓	✓*	✗	int8/fp8/nf4	✓	T5-XXL
Auraflow	6.8B	✓	✓	✓*	✓	int8/fp8/nf4	✓	UMT5-XXL
PixArt Sigma	0.6B-0.9B	✗	✓	✓	✓	int8	✗	T5-XXL
Sana	0.6B-4.8B	✗	✓	✓	✗	int8	✓	Gemma2-2B
Lumina2	2B	✓	✓	✓	✗	int8	✓	Gemma2
Kwai Kolors	5B	✓	✓	✓	✗	✗	✗	ChatGLM-6B
LTX Video	5B	✓	✓	✓	✗	int8/fp8	✓	T5-XXL
LTX Video 2	19B	✓	✓	✓*	✗	int8/fp8	✓	Gemma3
Wan Video	1.3B-14B	✓	✓	✓*	✗	int8	✓	UMT5
HiDream	17B (8.5B MoE)	✓	✓	✓*	✓	int8/fp8/nf4	✓	CLIP-L + T5-XXL + Llama
Cosmos2	2B-14B	✗	✓	✓	✗	int8	✓	T5-XXL
OmniGen	3.8B	✓	✓	✓	✗	int8/fp8	✓	T5-XXL
Qwen Image	20B	✓	✓	✓*	✗	int8/nf4（必需）	✓	T5-XXL
SD 1.x/2.x（旧版）	0.9B	✓	✓	✓	✓	int8/nf4	✗	CLIP-L

✓ = 支持，✗ = 不支持， = 需要 DeepSpeed 才能进行全秩训练*

高级训练技术

• TREAD - 针对 Transformer 模型的逐 token 掉落法，包括 Kontext 训练
• 掩码损失训练 - 结合分割/深度指导，实现更优的收敛效果
• 先验正则化 - 提升训练稳定性，确保角色一致性
• 梯度检查点 - 可配置间隔，优化内存与速度
• 损失函数 - 支持 L2、Huber、Smooth L1，并可进行调度
• SNR 加权 - 通过 Min-SNR gamma 加权改善训练动态
• 分组卸载 - Diffusers v0.33+ 提供模块组 CPU/磁盘暂存功能，可选 CUDA 流
• 验证适配器扫描 - 在验证过程中临时加载 LoRA 适配器（单个或 JSON 预设），以测量仅使用适配器或对比渲染的效果，而无需修改训练循环
• 外部验证钩子 - 替换内置验证流程或上传后步骤，使用自定义脚本，以便在另一块 GPU 上运行检查，或将中间产物转发至任意云服务商（详情）
• CREPA 正则化 - 视频 DiT 的跨帧表征对齐（指南）
• LoRA I/O 格式 - 可以按照标准 Diffusers 布局或 ComfyUI 风格的 diffusion_model.* 键来加载/保存 PEFT LoRA（Flux/Flux2/Lumina2/Z-Image 自动检测 ComfyUI 输入）

模型特有功能

• Flux Kontext - 用于 Flux 模型的条件编辑和图像到图像训练
• PixArt 两阶段 - 支持 PixArt Sigma 的 eDiff 训练流程
• 流匹配模型 - 先进的调度机制，结合 beta 和均匀分布
• HiDream MoE - 混合专家门控损失增强
• T5 掩码训练 - 为 Flux 及兼容模型提升细节表现
• QKV 融合 - 内存与速度优化（Flux、Lumina2）
• TREAD 集成 - 大多数模型的可选性令牌路由
• Wan 2.x I2V - 提供高低阶段预设，并配备 2.1 时间嵌入回退方案（参见 Wan 快速入门）
• 无分类器引导 - 可选 CFG 重新引入，适用于蒸馏模型

快速入门指南

所有受支持的模型都提供详细的快速入门指南：

• TwinFlow 少步生成（RCGM）指南 - 启用 RCGM 辅助损失，用于少步或单步生成（流模型或通过 diff2flow 的扩散模型）
• Flux.1 指南 - 包含 Kontext 编辑支持和 QKV 融合
• Flux.2 指南 - 全新！ 最新的巨型 Flux 模型，配备 Mistral-3 文本编码器
• Z-Image 指南 - 基础版/Turbo LoRA 结合助手适配器 + TREAD 加速
• ACE-Step 指南 - 全新！ 音频生成模型训练（文本到音乐）
• HeartMuLa 指南 - 全新！ 自回归音频生成模型训练（文本到音频）
• Chroma 指南 - Lodestone 的流匹配 Transformer，配备 Chroma 特定调度
• Stable Diffusion 3 指南 - 完整训练及 ControlNet 支持的 LoRA 训练
• Stable Diffusion XL 指南 - 完整的 SDXL 训练流程
• Auraflow 指南 - 流匹配模型训练
• PixArt Sigma 指南 - DiT 模型，支持两阶段训练
• Sana 指南 - 轻量级流匹配模型
• Lumina2 指南 - 20亿参数的流匹配模型
• Kwai Kolors 指南 - 基于 SDXL，采用 ChatGLM 编码器
• LongCat-Video 指南 - 流匹配文本到视频及图像到视频，配备 Qwen-2.5-VL
• LongCat-Video 编辑指南 - 先条件化模式（图像到视频）
• LongCat-Image 指南 - 60亿参数的双语流匹配模型，配备 Qwen-2.5-VL 编码器
• LongCat-Image 编辑指南 - 图像编辑模式，需要参考潜变量
• LTX 视频指南 - 视频扩散模型训练
• Hunyuan Video 1.5 指南 - 83亿参数的流匹配 T2V/I2V 模型，带超分辨率阶段
• Wan 视频指南 - 视频流匹配模型，支持 TREAD 加速
• HiDream 指南 - MoE 模型，具备高级功能
• Cosmos2 指南 - 多模态图像生成
• OmniGen 指南 - 统一图像生成模型
• Qwen 图像指南 - 200亿参数的大规模训练
• Stable Cascade Stage C 指南 - 先验 LoRA，结合先验与解码器验证
• Kandinsky 5.0 图像指南 - 图像生成，使用 Qwen2.5-VL 和 Flux VAE
• Kandinsky 5.0 视频指南 - 视频生成，使用 HunyuanVideo VAE

---

硬件要求

一般要求

• NVIDIA: 推荐 RTX 3080 及以上（已测试至 H200）
• AMD: 已验证 7900 XTX 24GB 和 MI300X（相比 NVIDIA 内存占用更高）
• Apple: M3 Max 及以上，配备 24GB 以上统一内存，适用于 LoRA 训练

按模型大小划分的内存指南

• 大型模型（120亿+参数）: A100-80G 用于全秩训练，24GB 以上用于 LoRA/Lycoris 训练
• 中型模型（20亿–80亿参数）: 16GB 以上用于 LoRA 训练，40GB 以上用于全秩训练
• 小型模型（<20亿参数）: 12GB 以上足以应对大多数训练类型

注意: 量化（int8/fp8/nf4）可显著降低内存需求。请参阅各模型的 快速入门指南，以获取具体要求。

安装

对于大多数用户，SimpleTuner 可通过 pip 安装：

# 基础安装（仅 CPU 的 PyTorch）
pip install simpletuner

# CUDA 用户（NVIDIA 显卡）
pip install 'simpletuner[cuda]'

# CUDA 13 / Blackwell 用户（NVIDIA B 系列显卡）
pip install 'simpletuner[cuda13]' --extra-index-url https://download.pytorch.org/whl/cu130

# ROCm 用户（AMD 显卡）
pip install 'simpletuner[rocm]' --extra-index-url https://download.pytorch.org/whl/rocm7.1

# Apple Silicon 用户（M1/M2/M3/M4 Mac）
pip install 'simpletuner[apple]'

如需手动安装或开发环境搭建，请参阅 安装文档。

故障排除

可通过在环境配置文件（config/config.env）中添加 export SIMPLETUNER_LOG_LEVEL=DEBUG 来启用调试日志，以获得更详细的洞察。

若要分析训练循环的性能，设置 SIMPLETUNER_TRAINING_LOOP_LOG_LEVEL=DEBUG 将显示时间戳，帮助您识别配置中的任何问题。

有关可用选项的完整列表，请参阅 此文档。

SimpleTuner 快速上手指南

SimpleTuner 是一个专注于简洁性和易用性的开源 AI 训练工具，支持多种扩散模型架构（如 Flux、SD3、SDXL 等）的全量微调、LoRA 及 LyCORIS 训练。它提供友好的 Web UI 和多 GPU 分布式训练支持，旨在让复杂的模型训练变得简单高效。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04/22.04) 或 macOS。Windows 用户建议使用 WSL2。
• GPU: 推荐使用 NVIDIA GPU。
  • 显存要求：大多数模型可在 24GB 显存上运行；通过优化（如 DeepSpeed/FSDP2），部分模型可在 16GB 显存上运行。
  • 驱动：安装最新的 NVIDIA 驱动程序。
• Python: 版本 3.10 或更高。

前置依赖

确保已安装以下基础工具：

• git
• curl 或 wget
• NVIDIA CUDA Toolkit (通常随驱动自动安装，需确认 nvcc --version 可用)

注意：SimpleTuner 内部会自动管理 Python 虚拟环境和大部分深度学习依赖，无需手动预装 PyTorch。

安装步骤

1. 克隆仓库

git clone https://github.com/bghira/SimpleTuner.git
cd SimpleTuner

2. 创建并激活虚拟环境

建议使用 venv 或 conda 隔离环境。

python3 -m venv .venv
source .venv/bin/activate

3. 安装依赖

项目提供了标准的 requirements.txt。国内用户若遇到下载缓慢，可临时指定清华或阿里镜像源加速安装：

# 使用默认源安装
pip install -r requirements.txt

# 【推荐】国内用户使用清华源加速安装
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 初始化配置

运行初始化脚本来设置默认的 Accelerate 配置（可根据向导选择单卡或多卡模式）：

accelerate config

提示：如果是首次使用，按照屏幕提示选择默认选项即可，后续可在 Web UI 中调整详细参数。

基本使用

SimpleTuner 提供两种主要使用方式：Web UI 模式（推荐新手）和 命令行模式。

方式一：启动 Web UI（推荐）

这是最直观的管理方式，可通过浏览器配置数据集、模型参数并监控训练进度。

1. 启动服务

   python train.py --webui
   

   注：某些版本可能使用 python webui.py，请以实际目录文件为准，通常 train.py 包含入口。

2. 访问界面 终端会输出一个本地地址（默认为 http://127.0.0.1:8080），在浏览器中打开该地址。

3. 开始训练

   • 在 Dashboard 中新建项目。
   • 上传或链接你的数据集（支持本地路径或 S3 兼容存储）。
   • 选择预置模型（如 Flux.1, SDXL 等）。
   • 点击 "Start Training" 即可。

方式二：命令行快速启动

如果你熟悉命令行且希望快速开始一个标准的 LoRA 训练任务，可以使用以下最小化示例。

假设你已准备好：

• 数据集目录：./data/my_dataset
• 输出目录：./output/my_lora
• 模型名称：black-forest-labs/FLUX.1-dev (示例)

执行命令：

accelerate launch train.py \
  --pretrained_model_name_or_path="black-forest-labs/FLUX.1-dev" \
  --dataset_config="./data/my_dataset/config.json" \
  --output_dir="./output/my_lora" \
  --train_batch_size=1 \
  --gradient_accumulation_steps=4 \
  --mixed_precision="bf16" \
  --lora_rank=16 \
  --max_train_steps=1000 \
  --checkpointing_steps=500 \
  --report_to="tensorboard"

关键参数说明：

• --mixed_precision: 建议根据显卡型号设置为 bf16 (Ampere 架构及以上) 或 fp16。
• --lora_rank: LoRA 秩，数值越小显存占用越低，通常 16 或 32 为常用值。
• --dataset_config: 指向包含图像路径和标题的 JSON 配置文件。

下一步

完成上述步骤后，训练将自动开始。你可以在 output_dir 指定的文件夹中找到生成的模型权重文件（.safetensors 或 .pt）。对于更高级的功能（如多节点训练、DeepSpeed 优化、视频生成训练），请参考项目文档中的专项指南。