Kohya's GUI

这是一个用于训练扩散模型的图形界面（GUI）与命令行（CLI）工具。

本项目为 Kohya 的 Stable Diffusion 训练脚本 提供了一套基于 Gradio 的易用图形界面（GUI）。
Stable Diffusion 训练让用户能够通过微调现有模型来自定义图像生成模型、创建独特的艺术风格，
以及训练 LoRA（低秩适配）等专用模型。

本 GUI 的主要特性包括：
* 易用的界面，可设置各种训练参数。
* 自动生成运行训练脚本所需的命令行（CLI）命令。
* 支持 LoRA、LoHa、LoKr、Dreambooth、微调（fine-tuning）和文本反转（Textual Inversion）训练。
* 支持多种基础模型：Stable Diffusion 1.5/2.x、SDXL、SD3、Flux.1、Lumina Image 2.0、Anima 和 HunyuanImage-2.1。
* LECO（概念擦除/编辑）训练。

同时支持 Linux 和 macOS。Linux 支持通过社区贡献持续维护，macOS 的兼容性可能有所差异。

目录

• 安装方式
• 本地安装概览
  • uv 与 pip 有什么区别？
• 云端安装概览
  • Colab
  • Runpod、Novita、Docker
• 离线 / 隔离网络的 GUI 外壳
• 自定义路径默认值
• 服务器选项
• allowed_paths
• 远程 / SSH：使用 --headless
• LoRA
• 训练期间生成示例图像
• 故障排除
• 页面文件限制
• 找不到名为 tkinter 的模块
• 在 TESLA V100 上训练 LORA - GPU 利用率问题
• SDXL 训练
• 掩码损失（Masked loss）
• 指南
• 使用 Accelerate Lora 选项卡选择 GPU ID
  • 在 GUI 中启动 Accelerate
  • 运行多个实例（Linux）
  • 监控进程
• 值得关注的 Fork
• 贡献
• 许可证
• 更新历史
• v26.0.0

安装方式

你可以在本地机器上运行 kohya_ss，也可以通过 Colab 或 Runpod 等云端方案运行。

• 如果你有配备 GPU 的电脑并希望完全掌控：使用 uv 或 pip 在本地安装。
• 如果你的系统不满足要求，或更喜欢基于浏览器的配置：使用 Colab 或 Runpod、Novita 等付费 GPU 服务商。
• 如果你是开发者或 DevOps 用户，也支持 Docker。

本地安装概览

你可以使用 uv 或 pip 方法在本地安装 kohya_ss。请根据你的平台和偏好选择其一：

uv 与 pip 有什么区别？

• uv 更快，依赖隔离更干净，如果你希望尽量减少安装麻烦，它是理想选择。
• pip 更传统，出现问题时更容易调试，并且与某些 IDE 或 Python 工具配合更好。
• 如果不确定：先试 uv。如果不行，再回退到 pip。

云端安装概览

🦒 Colab

如需无需本地安装的浏览器端训练，请使用此 Colab 笔记本：
https://github.com/camenduru/kohya_ss-colab

• 无需安装
• 免费使用（GPU 可用性可能有所不同）
• 由 camenduru 维护，而非原作者

Colab	说明
	kohya_ss_gui_colab

💡 如果遇到问题，请在 camenduru 的仓库中反馈。

特别感谢
感谢 camenduru 的宝贵贡献。

Runpod、Novita、Docker

这些选项适用于在托管 GPU 基础设施或容器上运行训练的用户。

• Runpod 配置 – 通过模板实现现成的 GPU 后台训练。
• Novita 配置 – 与 Runpod 类似，但集成在 Novita UI 中。
• Docker 配置 – 适用于使用容器化环境的开发者/系统管理员。

离线 / 隔离网络的 GUI 外壳

正常安装后，本地 Gradio UI 外壳 在使用核心资源时无需浏览器（或服务器进程）从第三方 CDN 主机拉取：

公开的 GitHub README.md 可能仍包含营销徽章；应用内的“关于 → README” 视图会移除远程图片，以便浏览器不加载它们。

使用 config.toml 自定义路径默认值

GUI 支持一个名为 config.toml 的配置文件，允许你为许多输入字段设置默认路径。这有助于避免每次启动 GUI 时重复手动选择目录。

config.toml 的用途：

• 为预训练模型、数据集、输出文件夹、LoRA 模型等预填默认目录路径。
• 通过让 GUI 记住你偏好的位置来简化工作流程。

如何使用与自定义：

1. 创建配置文件：
   • 在 kohya_ss 仓库的根目录中，你会找到一个名为 config example.toml 的文件。
   • 复制该文件，并将副本重命名为 config.toml。GUI 启动时会自动加载这个 config.toml 文件。
2. 编辑 config.toml：
   • 使用文本编辑器打开 config.toml。
   • 该文件使用 TOML（Tom's Obvious, Minimal Language）格式，由 key = "value" 键值对组成。
   • 根据你的本地目录结构修改各键的路径。
   • 重要提示：
     • 使用绝对路径（例如 C:/Users/YourName/StableDiffusion/Models 或 /home/yourname/sd-models）。
     • 或者，你可以使用相对于 kohya_ss 根目录的路径。
     • 确保使用正斜杠（/）作为路径分隔符，即使在 Windows 上也是如此，因为这通常与 TOML 和 Python 更兼容。
     • 确保指定的目录在你的系统中存在。

config.toml 的结构：

config.toml 文件可以包含多个节（section），通常对应不同的训练模式或通用设置。你可能希望设置的常见键包括：

• model_dir：加载基础 Stable Diffusion 模型的默认目录。
• lora_model_dir：保存和加载 LoRA 模型的默认目录。
• output_dir：训练输出（图像、日志、模型检查点）的默认基础目录。
• dataset_dir：如果你将所有数据集存放在一处，可设置此通用默认值。
• 不同训练选项卡（如 Dreambooth、Finetune、LoRA 等）的特定输入路径（例如 db_model_dir、ft_source_model_name_or_path）。

配置示例：

以下是你 config.toml 可能样子的示例片段：

# 通用设置
model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion"
lora_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Lora"
vae_dir = "C:/ai_stuff/stable-diffusion-webui/models/VAE"
output_dir = "C:/ai_stuff/kohya_ss_outputs"
logging_dir = "C:/ai_stuff/kohya_ss_outputs/logs"

# Dreambooth 专用路径
db_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion"
db_reg_image_dir = "C:/ai_stuff/datasets/dreambooth_regularization_images"
# 按需添加其他 db_... 路径

# Finetune 专用路径
ft_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion"
# 按需添加其他 ft_... 路径

# LoRA / LoCon 专用路径
lc_model_dir = "C:/ai_stuff/stable-diffusion-webui/models/Stable-diffusion" # LoRA 训练使用的基础模型
lc_output_dir = "C:/ai_stuff/kohya_ss_outputs/lora"
lc_dataset_dir = "C:/ai_stuff/datasets/my_lora_project"
# 按需添加其他 lc_... 路径

# 你可以在 `config example.toml` 文件中找到所有可用键的完整列表。
# 参考它以自定义 GUI 中所有受支持选项的路径。

使用自定义配置文件路径：

如果你希望为配置文件使用不同的名称或将其存放在其他位置，可以在启动 GUI 时通过 --config 命令行参数指定其路径：

• Windows：gui.bat --config D:/my_configs/kohya_settings.toml
• Linux/macOS：./gui.sh --config /home/user/my_configs/kohya_settings.toml

通过有效使用 config.toml，你可以显著加快训练设置过程。请始终参考 config example.toml 以获取最新可配置路径列表。

服务器选项

config.toml 文件也可用于配置 Gradio 服务器。

allowed_paths

allowed_paths 选项允许你指定应用程序可以访问的目录列表。如果你想将模型、数据集或其他文件存放在外部驱动器或应用程序根目录之外的位置，这将非常有用。

示例：

[server]
allowed_paths = ["/mnt/external_drive/models", "/home/user/datasets"]

远程 / SSH：使用 --headless

当你在远程机器（SSH、Runpod、Docker、云 GPU）上运行 GUI 并在浏览器中打开时，请以 --headless 启动。

如果不使用它，原生操作系统对话框（easygui 覆盖确认、本地文件选择器）会在服务器进程中运行。通过 SSH 通常没有交互式显示，因此这些提示可能会无限期阻塞训练。

--headless 对远程使用有两点重要影响：

• 在 Gradio UI 中隐藏本地文件/文件夹选择按钮（改为手动输入路径）。
• 跳过 easygui 的“是否覆盖现有模型？”提示，如果输出名称已存在则直接覆盖。

示例：

# Linux / macOS
./gui.sh --listen 0.0.0.0 --server_port 7860 --headless

# Windows
gui.bat --listen 0.0.0.0 --server_port 7860 --headless

如果你在没有 --headless 的情况下通过 SSH 或无显示环境启动，进程会记录一条建议使用 --headless 的警告。没有单独的 --skip_overwrite 标志；在训练启动时使用 --headless 即可实现该行为。

LoRA

要训练 LoRA，目前可以使用 train_network.py 代码。你可以通过一体化 GUI 创建 LoRA 网络。

创建 LoRA 网络后，你可以安装此扩展后使用 auto1111 生成图像。

有关 LoRA 训练选项和高级配置的更多详细信息，请参阅我们的 LoRA 文档：
- LoRA 训练指南
- LoRA 训练选项

训练期间生成示例图像

提示词文件可能看起来像这样，例如：

# prompt 1
masterpiece, best quality, (1girl), in white shirts, upper body, looking at viewer, simple background --n low quality, worst quality, bad anatomy, bad composition, poor, low effort --w 768 --h 768 --d 1 --l 7.5 --s 28

# prompt 2
masterpiece, best quality, 1boy, in business suit, standing at street, looking back --n (low quality, worst quality), bad anatomy, bad composition, poor, low effort --w 576 --h 832 --d 2 --l 5.5 --s 40

以 # 开头的行是注释。你可以在提示词后使用 --n 等选项为生成的图像指定参数。可使用以下选项：

• --n：负向提示词，直到下一个选项为止。
• --w：指定生成图像的宽度。
• --h：指定生成图像的高度。
• --d：指定生成图像的种子（seed）。
• --l：指定生成图像的 CFG scale。
• --s：指定生成的步数。

提示词权重如 ( ) 和 [ ] 均可正常使用。

故障排除

如果遇到任何问题，请参考以下故障排除步骤。

页面文件限制

如果遇到与页面文件相关的 X 错误，你可能需要增大 Windows 中的页面文件大小限制。

找不到名为 tkinter 的模块

如果遇到提示找不到 tkinter 模块的错误，请尝试在系统上重新安装 Python 3.10。

在 TESLA V100 上训练 LORA - GPU 利用率问题

详情请参阅 TESLA V100 上的 LORA 训练故障排除。

SDXL 训练

有关 SDXL 训练的详细指导，请参阅官方 sd-scripts 文档以及我们的 LoRA 训练指南 中的相关章节。

掩码损失（Masked loss）

每个训练脚本都支持掩码损失。要启用掩码损失，请指定 --masked_loss 选项。

[!WARNING]
该功能尚未经过全面测试，可能存在 bug。如果发现问题，请提交 Issue。

使用 ControlNet 数据集来指定掩码。掩码图像应为 RGB 图像。R 通道中像素值 255 被视为掩码（仅对掩码像素计算损失），0 被视为非掩码。像素值 0-255 会被转换为 0-1（即像素值 128 被视为损失权重的一半）。数据集规范的详细信息请参阅 LLLite 文档。

指南

以下是从 issue 讨论中整理的指南。

使用 Accelerate Lora 选项卡选择 GPU ID

在 GUI 中启动 Accelerate

• 在你期望的端口上打开 kohya GUI。
• 打开 Accelerate launch 选项卡。
• 确保 Multi-GPU 复选框未勾选。
• 将 GPU IDs 设置为期望的 GPU（例如 1）。

运行多个实例（Linux）

• 要跟踪多个进程，请在不同端口（例如 7860、7861）上使用单独的 kohya GUI 实例。
• 使用 nohup ./gui.sh --listen 0.0.0.0 --server_port <port> --headless > log.log 2>&1 & 启动实例。

监控进程

• 在单独的浏览器选项卡中打开每个 GUI。
• 如需终端访问，请通过 SSH 使用 tmux 或 screen 等工具。

更多详情请访问 GitHub issue。

值得关注的 Fork

要微调 HunyuanDiT 模型或创建 LoRA，请访问此 fork。

贡献

欢迎贡献！如果你希望为本项目做出贡献，请考虑以下事项：
- 如需报告 bug 或请求新功能，请在 GitHub Issues 页面 提交 issue。
- 如需提交代码更改，请发起 pull request。请确保你的更改经过充分测试，并遵循现有的代码风格。
- 如有安全相关问题，请参阅我们的 SECURITY.md 文件。

许可证

本项目采用 Apache License 2.0 许可证。详情请参阅 LICENSE.md 文件。

更新历史

此处仅详述即将发布的版本。已发布版本的完整历史请参阅 GitHub Releases。

v26.0.0

新增
- 支持 Lumina Image 2.0 LoRA（#3553）与完整微调（#3521、#3554）训练。
- 支持 Anima LoRA（#3541）、完整微调（#3523、#3551）、ControlNet-LLLite（#3549），以及高级选项：torch.compile、Qwen-Image VAE 2D、时间步可视化（#3542）。
- 为 SDXL 和 Anima 提供原生 LoHa/LoKr 训练（networks.loha/networks.lokr）（#3550）。
- 支持 HunyuanImage-2.1 LoRA 训练（#3537）。
- 为 SD1.x/2.x 和 SDXL 提供 LECO（概念擦除/编辑）训练（#3539）。
- 支持 SD1.5/SDXL 的 Inpainting 模型训练（#3540）。
- 在 GUI 中为 DiT 训练暴露 --show_timesteps / --show_timesteps_resolution，支持控制台/matplotlib 可视化模式（#3535）。
- 在 Resize LoRA 选项卡中暴露 --svd_lowrank_niter（#3534）。
- 在 WD14 tagger 中新增 wd-eva02-large-tagger-v3（#3315）。
- 为多分辨率数据集 TOML 配置添加应用内文档指引（#3536）。
- 新增“展开所有折叠面板”选项（#3310）。
- Flux Kontext 手动打标工具，包含宽高比校正、删除按钮、目标文件夹建议及分页修复（#3346 系列）。
- GUI 布局优化：info= 提示文本现在改为悬停显示而非始终显示，工具按钮图标与对应输入框底部对齐。

变更
- 将 sd-scripts 子模块升级至 v0.11.1，并针对其重构调整了 GUI 参数（#3519、#3520）。
- 将 lora_gui.py、leco_gui.py 及剩余 GUI 文件重构为 FIELD_REGISTRY + dict-adapter 模式，以保证位置参数安全（#3543、#3544、#3545、#3547、#3548）。
- 清理了 HunyuanImage-2.1 LoRA 参数传递的外观问题（#3555）。
- 为 XPU 升级了 PyTorch（#3366）。
- 更新了 Intel 软件包以兼容 oneAPI（#3341）。

修复
- 未激活 venv 时现在能正确找到控制台脚本（#3552）。
- 修复了使用系统 pip 时的依赖安装问题（#3515）。
- 通过跨平台 AVX 检查修复了非 x86 平台上的 TensorBoard 崩溃问题（#3345）。
- 修复了 Apple Silicon（M 系列）Mac 上的安装错误（#3353）。
- 修复了 README 中的失效文档链接（#3505）。
- 处理了 v0.11.1 升级、LoRA+/TI 及 FIELD_REGISTRY 相关 PR 中的评审反馈（#3518、#3533、#3546）。