ITADN
bghira/SimpleTuner
代码 动态 Issues502 合并请求1106 版本142
bghira/SimpleTuner · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

SimpleTuner 💹

ℹ️ 除通过可选标志 report_to、push_to_hub 或必须手动配置的 webhooks 外，不会向任何第三方发送数据。

SimpleTuner 以简洁为核心，专注于使代码易于理解。该代码库作为一项共享的学术练习，欢迎贡献。

如果您想加入我们的社区，可以通过 Terminus Research Group 在 Discord 上找到我们。 如果您有任何问题，请随时在那里联系我们。

image

目录

设计哲学

  • 简洁性：旨在为大多数用例提供良好的默认设置，从而减少调试需求。
  • 通用性：设计用于处理各种数量的图像——从小型数据集到大型集合。
  • 前沿功能：仅纳入经过验证有效的功能，避免添加未经验证的选项。

教程

在开始 新的 Web UI 教程 或 class 命令行教程 之前，请充分阅读本 README，因为本文档包含你可能需要先了解的重要信息。

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

对于内存受限的系统，请参阅 DeepSpeed 文档，其中解释了如何使用 🤗Accelerate 来配置 Microsoft 的 DeepSpeed 以实现优化器状态卸载。对于基于 DTensor 的分片和上下文并行，请阅读 FSDP2 指南，该指南涵盖了 SimpleTuner 内部新的 FullyShardedDataParallel v2 工作流。

对于多节点分布式训练，本指南 将帮助你调整 INSTALL 和 Quickstart 指南中的配置，使其适用于多节点训练，并针对包含数十亿样本的图像数据集进行优化。

功能

SimpleTuner 为多种扩散模型架构提供全面的训练支持，并保持一致的功能可用性：

核心训练功能

  • 用户友好的 Web UI - 通过精美的仪表盘管理您的整个训练生命周期
  • 多模态训练 - 针对图像、视频和音频生成模型的统一流水线
  • 多 GPU 训练 - 跨多个 GPU 的分布式训练，具备自动优化功能
  • 高级缓存 - 将图像、视频、音频和字幕嵌入缓存到磁盘以加快训练速度
  • CaptionFlow 集成 - 通过 Web UI 任务队列利用本地 GPU 生成数据集字幕，使用 bghira/CaptionFlow；请参阅 CaptionFlow 集成指南
  • 宽高比分桶 - 支持多种图像/视频尺寸和宽高比
  • 概念滑块 - 针对 LoRA/LyCORIS/全量（通过 LyCORIS full）的滑块友好型目标设定，支持正/负/中性采样和逐提示强度；请参阅 滑块 LoRA 指南
  • 内存优化 - 大多数模型可在 24G GPU 上训练，许多模型在优化后可在 16G 上训练
  • DeepSpeed & FSDP2 集成 - 通过优化器/梯度/参数分片、上下文并行注意力、梯度检查点和优化器状态卸载，在较小的 GPU 上训练大型模型
  • S3 训练 - 直接从云存储（Cloudflare R2, Wasabi S3）进行训练
  • EMA 支持 - 指数移动平均权重，以提升稳定性和质量
  • 自定义实验跟踪器 - 将 accelerate.GeneralTracker 放入 simpletuner/custom-trackers 并使用 --report_to=custom-tracker --custom_tracker=<name>

多用户与企业级功能

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

  • Worker Orchestration - 注册分布式 GPU 工作节点，自动连接至中央面板并通过 SSE 接收任务分发；支持临时（云启动）和持久（常驻）工作节点；参见 Worker Orchestration Guide
  • SSO Integration - 通过 LDAP/Active Directory 或 OIDC 提供商（Okta, Azure AD, Keycloak, Google）进行身份验证；参见 External Auth Guide
  • Role-Based Access Control - 四个默认角色（Viewer, Researcher, Lead, Admin）及 17+ 细粒度权限；使用 glob 模式定义资源规则，以按团队限制配置、硬件或提供商
  • Organizations & Teams - 基于上限配额的层级式多租户结构；组织限制强制执行绝对最大值，团队限制在组织边界内运行
  • Quotas & Spending Limits - 在组织、团队或用户范围内强制执行成本上限（每日/每月）、任务并发限制和提交速率限制；操作包括阻止、警告或要求审批
  • Job Queue with Priorities - 五个优先级级别（Low → Critical），支持跨团队的公平份额调度、防止长等待任务饥饿以及管理员优先级覆盖
  • Approval Workflows - 可配置规则触发对超出成本阈值、首次使用用户或特定硬件请求任务的审批；可通过 UI、API 或邮件回复进行审批
  • Email Notifications - SMTP/IMAP 集成，用于任务状态、审批请求、配额警告和完成提醒
  • API 密钥与范围权限 - 为 CI/CD 流水线生成具有有效期和有限范围的 API 密钥
  • 审计日志 - 通过链式验证跟踪所有用户操作以满足合规要求；参见 审计指南

有关部署详情，请参阅 企业指南。

模型架构支持

SimpleTuner 支持以下模型系列。详细的训练功能支持情况请参阅 快速入门指南。

模型参数量许可证商业用途
ACE-Step3.5BApache-2.0是
Anima未指定CircleStone Labs 非商业许可证 v1.2否（模型）；允许输出
Auraflow6BApache-2.0是
Boogu-Image未指定Apache-2.0是
Chroma 18.9BApache-2.0是
Cosmos22B-14BNVIDIA 开放模型许可证是
Cosmos316B-65BOpenMDW-1.1是
DeepFloyd IF0.4B-4.3B 阶段DeepFloyd IF 许可证弃用软件
ERNIE-Image未指定Apache-2.0是
Flux.18B-12BApache-2.0 (schnell)；FLUX.1 [dev] 非商业许可证 (dev/Kontext)按检查点混合
Flux.24B-32BApache-2.0 (klein 4B)；FLUX 非商业许可证 (dev/klein 9B)按检查点混合
HeartMuLa3BSimpleTuner 中未指定参见上游条款
HiDream17B (8.5B MoE)MIT是
Hunyuan Video8.3BAGPL-3.0是（copyleft）
Ideogram 49BIdeogram 4 非商业否
Kandinsky 5.0 Image6B (lite)MIT是
Kandinsky 5.0 Video2B lite, 19B proMIT是
Kwai Kolors2.7BApache-2.0弃用软件
Krea2未指定Krea 2 社区许可证是（收入低于 100 万美元；需满足安全措施要求）
LongCat Image6BApache-2.0是
LongCat Video13.6BMIT是
LTX Video~2.5BApache-2.0是
LTX Video 219BApache-2.0是
Lumina22BApache-2.0是
Mage-Flow4BMIT是
OmniGen3.8BMIT是
PixArt Sigma0.6B-0.9BOpenRAIL++是（受限）
Qwen Image20BApache-2.0是
Sana0.6B-4.8BApache-2.0是
Sana Video2BApache-2.0是
SD 1.x/2.x (Legacy)0.9BOpenRAIL++是（受限）
Stable Diffusion 32B-8BStability AI Community License是（营收低于 100 万美元）
Stable Diffusion XL3.5BCreativeML OpenRAIL-M是（受限）
Stable Cascade (Stage C)1B, 3.6B priorNot specified in SimpleTunerAbandonware
Wan Video1.3B-14BApache-2.0是
Wan S2V14BApache-2.0是
Z-Image6BApache-2.0是
Z-Image Omni6BApache-2.0是
ZLab I13BMIT是

许可证值在可用时取自 SimpleTuner 模型助手，对于先前未指定的条目则取自上游模型卡片/许可证。Not specified in SimpleTuner 表示助手未指明许可证，且此处未总结上游条款；使用前请查阅上游模型卡片。

高级训练技术

  • TREAD - 针对 Transformer 模型的逐 Token 丢弃，包括 Kontext 训练
  • Masked loss training - 借助分割/深度引导实现更优的收敛
  • Prior regularization - 增强角色一致性下的训练稳定性
  • Gradient checkpointing - 可配置间隔以优化内存/速度
  • Loss functions - 支持调度的 L2、Huber、Smooth L1
  • SNR weighting - Min-SNR gamma 加权以改善训练动态
  • Group offloading - Diffusers v0.33+ 模块组 CPU/磁盘暂存，支持可选 CUDA 流
  • Validation adapter sweeps - 在验证期间临时挂载 LoRA 适配器（单个或 JSON 预设），以在不触及训练循环的情况下测量仅适配器或对比渲染
  • External validation hooks - 将内置验证流水线或上传后步骤替换为您自己的脚本，以便在另一块 GPU 上运行检查或将工件转发到您选择的任何云服务商（details)
  • AnyFlow distillation - 用于流匹配模型的 FlowMap 区间条件化，支持在线教师目标（guide)
  • CREPA regularization - 用于视频 DiT 的跨帧表示对齐（guide)
  • LoRA I/O formats - 以标准 Diffusers 布局或 ComfyUI 风格 diffusion_model.* 键加载/保存 PEFT LoRA（Flux/Flux2/Lumina2/Z-Image 自动检测 ComfyUI 输入）

Model-Specific Features

  • Flux Kontext - 用于 Flux 模型的编辑条件与图生图训练
  • Reference-input training - 针对 Flux Kontext、Flux.2、LTX Video 2、Qwen Edit、LongCat edit/I2V、Boogu edit、Hunyuan I2V 以及 Kandinsky I2I/I2V 的现有配对参考/编辑/I2V 路径
  • PixArt two-stage - 对 PixArt Sigma 的 eDiff 训练流水线支持
  • Flow matching models - 采用 beta/均匀分布的高级调度
  • HiDream MoE - Mixture of Experts 门控损失增强
  • T5 masked training - 为 Flux 及兼容模型增强精细细节
  • QKV fusion - 内存与速度优化（Flux、Lumina2）
  • TREAD integration - 适用于大多数模型的选择性 token 路由
  • Wan 2.x I2V - 高/低阶段预设以及 2.1 时间嵌入回退（参见 Wan 快速入门）
  • Classifier-free guidance - 针对蒸馏模型的可选 CFG 重新引入

Quickstart Guides

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

硬件要求

通用要求

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

按模型规模的显存指南

  • 大模型 (12B+): 全秩训练需 A100-80G，LoRA/Lycoris 需 24G+
  • 中等模型 (2B-8B): LoRA 需 16G+，全秩训练需 40G+
  • 小模型 (<2B): 12G+ 即可满足大多数训练类型

注意: 量化 (int8/fp8/nf4) 可显著降低显存需求。请参阅各自的 快速入门指南 以获取特定模型的显存要求。

安装

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

# Base installation (CPU-only PyTorch)
pip install simpletuner

# CUDA users (NVIDIA GPUs)
pip install 'simpletuner[cuda]'

# CUDA 13 / Blackwell users (NVIDIA B-series GPUs)
pip install 'simpletuner[cuda13]' --extra-index-url https://download.pytorch.org/whl/cu130

# CUDA 13 with TransformerEngine FP8 support
pip install 'simpletuner[cuda13-transformerengine]' --extra-index-url https://download.pytorch.org/whl/cu130

# ROCm users (AMD GPUs)
pip install 'simpletuner[rocm]' --extra-index-url https://download.pytorch.org/whl/rocm7.1

# Apple Silicon users (M1/M2/M3/M4 Macs)
pip install 'simpletuner[apple]'

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

故障排除

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

对于训练循环的性能分析，设置 SIMPLETUNER_TRAINING_LOOP_LOG_LEVEL=DEBUG 将显示时间戳，以突出配置中的任何问题。

如需查看可用选项的完整列表，请参阅此文档。