OneTrainer

OneTrainer 是您所有扩散模型训练需求的一站式解决方案。

功能特性

• 支持的模型: Z-Image、通义万相、FLUX.1、Flux.2 Dev 和 Klein、Chroma、Stable Diffusion 1.5、2.0、2.1、3.0、3.5、SDXL、Würstchen-v2、Stable Cascade、PixArt-Alpha、PixArt-Sigma、Sana、Hunyuan Video 以及修复类模型
• 模型格式: diffusers 和 ckpt 模型
• 训练方法: 全量微调、LoRA、嵌入
• 掩码训练: 让训练仅关注样本中的特定部分
• 自动备份: 在训练过程中定期完整备份您的训练进度，包括所有信息以便无缝继续训练
• 图像增强: 对每个图像样本应用随机变换，如旋转、亮度、对比度或饱和度调整，以快速创建更多样化的数据集
• TensorBoard: 简单的 TensorBoard 集成，用于跟踪训练进度
• 每张图片多个提示词: 在每个图像样本上使用多个不同的提示词进行训练
• 噪声调度重缩放: 基于论文 常见的扩散噪声调度和采样步数存在缺陷
• EMA: 训练您自己的 EMA 模型。可选地将 EMA 权重保留在 CPU 内存中，以减少显存占用
• 宽高比分桶: 自动同时在多种宽高比上进行训练。只需选择目标分辨率，分桶会自动创建
• 多分辨率训练: 同时训练多种分辨率
• 数据集工具: 使用 BLIP、BLIP2 和 WD-1.4 自动为您的数据集添加标题，或使用 ClipSeg 或 Rembg 为掩码训练创建掩码
• 模型工具: 通过简单的用户界面在不同模型格式之间进行转换
• 采样界面: 在训练过程中无需切换到其他应用程序即可对模型进行采样

[!注意] 安装后，请浏览我们的 📚 维基页面，获取必备技巧和教程。从这里开始！对于命令行使用，请参阅 CLI 模式章节。

安装

[!重要提示] 安装 OneTrainer 需要 Python >=3.10 且 <3.14。 您可以从 https://www.python.org/downloads/windows/ 下载 Python。 然后按照以下步骤操作。

自动安装

1. 克隆仓库 git clone https://github.com/Nerogar/OneTrainer.git
2. 运行：
   • Windows: 双击或执行 install.bat
   • Linux 和 Mac: 执行 install.sh

手动安装

1. 克隆仓库 git clone https://github.com/Nerogar/OneTrainer.git
2. 进入克隆后的目录 cd OneTrainer
3. 设置虚拟环境 python -m venv venv
4. 激活新创建的虚拟环境：
   • Windows: venv\scripts\activate
   • Linux 和 Mac: 根据您的 shell 类型，相应地激活虚拟环境
5. 安装依赖包 pip install -r requirements.txt

[!提示] 某些 Linux 发行版可能缺少必要的软件包。例如，在 Ubuntu 上您必须安装 libGL：

sudo apt-get update
sudo apt-get install libgl1

此外，有报告称 Alpine、Arch 和 Xubuntu Linux 可能缺少 tkinter。对于 Alpine，可通过 apk add py3-tk 安装；对于 Arch，则使用 sudo pacman -S tk。

更新

自动更新

• 运行 update.bat 或 update.sh

手动更新

1. 切换到包含仓库的文件夹 cd OneTrainer
2. 拉取最新更改 git pull
3. 激活虚拟环境 venv/scripts/activate
4. 重新安装所有依赖包 pip install -r requirements.txt --force-reinstall

使用方法

OneTrainer 可以在两种主要模式下使用：图形用户界面 (GUI) 和命令行界面 (CLI)，以实现更精细的控制。

如果您需要技术性较强的快速入门指南，请参阅 快速入门指南，若想获得更全面的概述，请参阅 概述文档。否则请访问 我们的维基。

GUI 模式

Windows

• 要启动界面，导航到 OneTrainer 文件夹并双击 start-ui.bat

Unix 系统

• 执行 start-ui.sh，GUI 就会弹出。

CLI 模式

如果您需要更多控制或无头方式，OT 也支持命令行界面。所有命令必须在安装时创建的活动虚拟环境中运行。

所有功能被拆分为位于 scripts 目录下的不同脚本。目前包括：

• train.py 中心训练脚本
• train_ui.py 训练用的用户界面
• caption_ui.py 用于手动或自动添加标题及为掩码训练创建掩码的用户界面
• convert_model_ui.py 模型转换用的用户界面
• convert_model.py 用于在不同模型格式之间进行转换的实用工具
• sample.py 用于对任何模型进行采样的实用工具
• create_train_files.py 用于仅通过 CLI 训练时创建所需文件的实用工具
• generate_captions.py 用于自动为您的数据集生成标题的实用工具
• generate_masks.py 用于自动为您的数据集创建掩码的实用工具
• calculate_loss.py 用于计算数据集中每张图像训练损失的实用工具

要了解不同参数的更多信息，请执行 <脚本名> -h。例如 python scripts\train.py -h

如果您使用的是 Mac 或 Linux，还可以阅读 启动脚本文档，以获取有关如何在您的系统上运行 OneTrainer 及其各种脚本的详细信息。

故障排除

如需一般故障排除或有任何疑问，请在 讨论区 提问，查看 维基 或加入我们的 Discord。

如果您遇到可复现的错误，首先应运行 update.bat 或 update.sh，并确认问题仍然可以复现。然后导出匿名化的调试信息，以帮助我们解决您遇到的问题，并将其作为 GitHub Issues 提交的一部分上传。

• 在 Windows 上，双击 export_debug.bat
• 在 Unix 系统上，执行 ./run-cmd.sh generate_debug_report

这两者都会生成一个 debug_report.log。

[!警告] 今后我们在处理 GitHub Issues 时都需要此文件。如果未能提供该文件，或未手动提供必要信息，大多数情况下该问题将被关闭。

贡献

我们欢迎任何形式的贡献。如果您计划添加新功能，请先在 GitHub 上发起讨论，或加入我们的 Discord 服务器，以便我们协调工作，避免重复劳动。有关贡献的更多信息，请参阅 这里。

在开始查看代码之前，建议您先阅读关于项目结构的说明 这里。

如需深入讨论，建议您加入 Discord 服务器。

此外，您还需要为当前用户安装所需的开发依赖项，并启用 Git 提交钩子，具体命令如下（适用于所有平台：Windows、Linux 和 Mac）：

[!重要提示] 请务必在未激活虚拟环境或 Conda 环境的情况下运行这些命令，因为 pre-commit 应该安装在任何环境之外。

cd OneTrainer
pip install -r requirements-dev.txt
pre-commit install

现在，您的每次提交都会自动检查常见的错误和代码风格问题，这样代码评审人员就可以专注于您更改的架构设计，而无需浪费时间在样式或格式问题上，从而大大提高您的拉取请求被快速、顺利接受的机会。

相关项目

• MGDS：一个基于节点图理念构建的 PyTorch 自定义数据集实现。
• Stability Matrix：一款多功能安装工具，用于封装和安装包括 OneTrainer 在内的多种扩散模型软件包。
• Visions of Chaos：一套机器学习工具集合，其中也包含 OneTrainer。
• StableTuner：一款现已停止维护（已归档）的 Stable Diffusion 训练应用。OneTrainer 受到 StableTuner 的诸多启发，如果没有它，OneTrainer 也就不会存在了。

OneTrainer 快速上手指南

OneTrainer 是一款专为扩散模型（Diffusion Models）训练打造的一站式解决方案，支持从 SD1.5 到 FLUX.2、Hunyuan Video 等多种主流模型的微调、LoRA 训练及嵌入训练。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows、Linux 或 macOS
• Python 版本：必须为 3.10 ≤ Python < 3.14
  • 下载地址：Python 官网
• Git：用于克隆代码仓库
• Linux 用户额外依赖：
  • Ubuntu/Debian: sudo apt-get install libgl1
  • Alpine: apk add py3-tk
  • Arch Linux: sudo pacman -S tk

提示：国内用户在安装 Python 包时，建议配置清华或阿里镜像源以加速下载： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

您可以选择自动安装（推荐）或手动安装。

方式一：自动安装（推荐）

1. 克隆仓库

   git clone https://github.com/Nerogar/OneTrainer.git
   

2. 执行安装脚本 进入目录并运行对应系统的脚本，它将自动创建虚拟环境并安装依赖。

   • Windows: 双击 install.bat 或在终端执行：

     cd OneTrainer
     install.bat
     

   • Linux / macOS:

     cd OneTrainer
     chmod +x install.sh
     ./install.sh
     

方式二：手动安装

如果您需要更精细的控制，请按以下步骤操作：

1. 克隆并进入目录

   git clone https://github.com/Nerogar/OneTrainer.git
   cd OneTrainer
   

2. 创建并激活虚拟环境

   python -m venv venv
   

   • Windows: venv\scripts\activate
   • Linux / macOS: source venv/bin/activate

3. 安装依赖

   pip install -r requirements.txt
   # 国内加速示例
   # pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

OneTrainer 提供图形界面（GUI）和命令行（CLI）两种模式。

1. 启动图形界面 (GUI)

这是最直观的使用方式，适合大多数用户进行模型训练、数据集标注和采样。

• Windows: 双击 start-ui.bat 或在终端运行：

  start-ui.bat
  

• Linux / macOS: 确保已激活虚拟环境，然后运行：

  ./start-ui.sh
  

启动后，您将在界面中配置训练参数、选择模型（如 FLUX.1, SDXL 等）、设置数据集路径并开始训练。

2. 命令行模式 (CLI)

适用于无头服务器运行或需要脚本化控制的场景。所有命令必须在激活虚拟环境下执行。

核心脚本位于 scripts 目录，常用命令如下：

• 开始训练:

  python scripts/train.py --config_path path/to/config.json
  

  (注：通常先通过 GUI 生成配置文件，或使用 create_train_files.py 辅助生成)

• 查看帮助参数:

  python scripts/train.py -h
  

• 其他实用工具:

  • 自动标注数据集：python scripts/generate_captions.py
  • 生成掩码（用于局部训练）：python scripts/generate_masks.py
  • 模型格式转换：python scripts/convert_model.py
  • 模型采样测试：python scripts/sample.py

下一步：安装完成后，强烈建议访问 官方 Wiki 查看详细的功能教程和参数说明。