Kohya_ss：面向扩散模型的 LoRA、DreamBooth 与文本反演训练 GUI 与命令行工具集｜部署与使用全指南

项目仓库： https://github.com/bmaltais/kohya_ss

开源协议：Apache License 2.0（见仓库 LICENSE.md） · 运行语言：Python（图形界面基于 Gradio，底层训练脚本为子模块 kohya-ss/sd-scripts） · 交付形态：本地 / 云 GPU 上运行的 Gradio 训练界面与命令行训练脚本 · 默认端口：GUI 7860，内置 TensorBoard 日志容器 6006 · 官方文档：项目 Wiki、LoRA 训练指南

非官方声明：本文是基于官方 README、docs/Installation/ 安装文档、docs/LoRA/ 训练指南、docker-compose.yaml、Dockerfile、config example.toml 与底层 sd-scripts 文档整理的部署使用指南，不代表项目官方立场。Stable Diffusion、SDXL、SD3、Flux、DreamBooth、LoRA、Textual Inversion 等名称归各自权利人所有；本文提及的基础模型权重、第三方打标模型、社区扩展与云 GPU 模板均遵循其自身许可协议与服务条款，使用者须自行确认合规边界。项目按现状（AS-IS）提供，本文不构成对训练效果、生成内容、商用授权或平台账号安全的任何担保。

1 项目简介

Kohya_ss（项目全称 Kohya's GUI）是 bmaltais 维护的开源图形界面，为 kohya-ss/sd-scripts 这套扩散模型训练脚本提供可视化参数配置层：使用者在 Gradio 界面中选择训练模式、填写模型与数据集路径、调整学习率、批次、优化器、采样器等参数后，界面自动生成并调用底层命令行脚本完成训练，也可以直接使用 sd-scripts 的命令行脚本在终端中运行。

README 自述定位为 “a GUI and CLI for training diffusion models”：界面负责参数组织、命令生成、数据集预处理（裁剪 / 翻转 / 打标 / 元数据生成）、训练过程采样图预览与日志查看；真正的模型训练计算由 sd-scripts 子模块中的 train_network.py、train_db.py、fine_tune.py、train_textual_inversion.py 等脚本完成。项目本身不附带任何基础模型权重，使用者需要自行准备合规获取的 Stable Diffusion 1.5/2.x、SDXL、SD3、Flux.1、Lumina Image 2.0、Anima、HunyuanImage-2.1 等基础模型作为训练起点。

1.1 核心信息一览

1.2 适用场景

• 在个人 NVIDIA 显卡工作站或云 GPU 实例上，为 Stable Diffusion 1.5/2.x、SDXL、SD3、Flux.1 等基础模型训练角色、画风、道具或特定概念的 LoRA（含 LoHa、LoKr、DyLoRA 等变体），训练完成后导出小体积权重供推理界面加载使用。
• 使用 DreamBooth 类方法把特定人物、角色或物体概念注入基础模型，可搭配正则化图像（Regularization Images）缓解语言漂移；也可以对模型做 全量微调（Fine-tuning） 与 Textual Inversion（文本反演 / 嵌入词训练）。
• 在图形界面内完成数据集整理：图片裁剪与分桶、左右翻转 / 色彩增强开关、BLIP 自动打标、WD14 标签器（含 wd-eva02-large-tagger-v3 等模型）批量打标、.txt / .caption 元数据文件生成与手动编辑、多分辨率数据集 TOML 配置。
• 在训练过程中按设定的步数 / 周期生成采样预览图，配合 TensorBoard 或 Weights & Biases 跟踪损失曲线；训练中途保存状态并断点续训；训练结束后把 LoRA 合并回基础模型，或把多个 LoRA 按比例合并。
• 通过界面的 Accelerate launch 标签页选择 GPU ID、关闭 / 开启多卡、设置混合精度与 CPU 线程数，在单机单卡或多卡环境下启动训练；远程 SSH / 云实例以 --headless 模式运行，避免原生文件对话框阻塞训练进程。

1.3 能力边界（官方口径）

• README 明确项目提供 “user-friendly Gradio-based Graphical User Interface (GUI) for Kohya's Stable Diffusion training scripts”：训练效果、显存占用、出图质量由基础模型权重、数据集质量、参数组合、显卡型号与采样设置共同决定，GUI 本身不承诺特定训练结果。
• README 支持平台口径为：Windows 为主；Linux 支持由社区贡献积极维护；macOS 兼容性可能因硬件与驱动而异；安装文档中 macOS 仅推荐 pip 方式，CUDA 通常不需要且可能不兼容 Apple Silicon GPU。
• 官方支持的基础模型清单以 README “Support for a wide range of base models” 小节为准；SDXL、SD3、Flux.1 等新一代模型的训练参数、分辨率与文本编码器口径与 SD1.x 不同，需分别参考 docs/LoRA/ 与 sd-scripts 对应文档，不能照搬 SD1.x 的配置。
• 官方仓库不托管、不分发基础模型权重；SD1.5/2.x、SDXL、SD3、Flux.1 等权重及其许可以各模型发布方（Stability AI、Stability AI SDXL 生态、Black Forest Labs、Hugging Face 模型卡等）为准。WD14 打标模型、BLIP 等预处理模型首次使用时按界面 / 脚本配置从 Hugging Face 拉取，许可各自独立。
• README 标注 masked loss（掩码损失）“The feature is not fully tested, so there may be bugs”，属于实验性能力；full_fp16、full_bf16、fp8_base 等在 config example.toml 中同样标注为 experimental。
• README 中的 Colab 笔记本由社区用户 camenduru 维护，“not the original author”，遇到问题应提交到该第三方仓库；Runpod、Novita 为官方文档列出的第三方 GPU 服务商模板；P2Enjoy/kohya_ss-docker、ashleykleynhans/kohya-docker 等属于社区 / 第三方 Docker 方案，不是本仓库官方镜像。
• 与 cloneofsimo 的 LoRA 仓库、d8ahazard 的 DreamBooth WebUI 扩展存在功能扩展上的不兼容（底层 sd-scripts 文档原文说明）；训练产出的 LoRA-C3Lier 需要配合 sd-webui-additional-networks 扩展才能在 AUTOMATIC1111 WebUI 中加载。

2 功能特性

以下条目整理自官方 README、config example.toml、docs/LoRA/ 指南与底层 sd-scripts 训练文档；具体参数名称、默认值与界面标签位置以安装版本为准。

2.1 多种训练方式与网络结构

• LoRA（Low-Rank Adaptation）：在不改动基础模型主体权重的前提下，为指定层接入小型低秩网络，训练产物体积小、便于分发。底层脚本 train_network.py，--network_module=networks.lora；可选择 LoRA-LierLa（Linear 层与 1×1 Conv2d）与 LoRA-C3Lier（扩展到 3×3 Conv2d）两种类型。
• LoHa / LoKr：v26.0.0 更新记录提到针对 SDXL 与 Anima 的原生 LoHa / LoKr 训练支持（networks.loha / networks.lokr），依赖 lycoris_lora 包。
• DyLoRA：一次训练同时覆盖多个 rank，训练完成后可从模型中提取多个低秩 LoRA 便于挑选最佳 rank；模块 networks.dylora，通过 --network_args "unit=4" 等分位参数控制，配套 networks/extract_lora_from_dylora.py 提取脚本。
• DreamBooth：脚本 train_db.py，支持 Class+Identifier 与打标（Captioning）两种数据集组织方式，可搭配正则化图像与 prior_loss_weight 先验损失权重；支持文本编码器 + U-Net 微调。
• 全量微调（Fine-tuning）：脚本 fine_tune.py，面向较大规模数据集做整模型更新，数据集通过元数据文件组织标签与描述。
• Textual Inversion：脚本 train_textual_inversion.py，训练自定义嵌入词（token string），通过 --token_string、--init_word、--num_vectors_per_token 配置；训练产物为可被推理界面加载的 embedding 文件。
• LECO（概念擦除 / 编辑）：README 特性清单列出 LECO 训练，v26.0.0 更新记录说明支持 SD1.x/2.x 与 SDXL 的 LECO（concept erasure/editing）训练。
• 其他训练能力：v26.0.0 更新记录另列 Anima 全量微调、ControlNet-LLLite、SD1.5/SDXL 局部重绘模型训练、torch.compile、Qwen-Image VAE 2D、时间步可视化（--show_timesteps）、Resize LoRA 标签页的 --svd_lowrank_niter 等。

2.2 数据集整理与预处理工具

• 目录结构与重复次数：数据集按子目录组织，目录名前缀数字表示重复次数（如 30_cat 表示目录内每张图每轮重复 30 次）；同目录内与图片同名的 .txt / .caption 元数据文件存在时，概念名以文件内容为准而非目录名（官方 docs/image_folder_structure.md 口径）。
• Aspect Ratio Bucketing：按宽高比把图片分配到若干分辨率桶，避免强制裁剪到统一方形；可配置 min_bucket_reso、max_bucket_reso、bucket_reso_steps 与 bucket_no_upscale。
• 数据增强：flip_aug 左右翻转、color_aug 色彩增强；注意开启 latents 缓存时除翻转外的增强会被禁用（底层文档口径）。
• 自动打标：内置 BLIP 打标入口与 WD14 Tagger 标签页；WD14 可配置模型 repo_id（默认 SmilingWolf/wd-convnext-tagger-v3，v26.0.0 新增 wd-eva02-large-tagger-v3）、通用 / 角色阈值、标签分隔符、强制前缀 / 后缀、不期望标签剔除、评级标签 / 质量标签开关、ONNX 推理开关等（见 config example.toml 的 [wd14_caption] 段）。
• 手动打标与编辑：界面提供 Flux Kontext 手动打标工具（v26.0.0 更新记录：含宽高比修正、删除按钮、目标目录建议与分页修复）；元数据文件扩展名可在 caption_extension 配置。
• 图片预处理脚本：tools/resize_images_to_resolution.py 按多分辨率列表把原图缩小并复制关联元数据文件；底层文档说明小图直接用于训练无需放大，缩小后的教师数据有时可提高准确性。

2.3 训练参数与优化器体系

• 基础训练参数：学习率 learning_rate、文本编码器学习率 learning_rate_te / learning_rate_te1 / learning_rate_te2、U-Net 与文本编码器分层学习率 unet_lr / text_encoder_lr、学习率调度器 lr_scheduler（linear、cosine、cosine_with_restarts、polynomial、constant、constant_with_warmup 等）、warmup、周期数、max_train_steps / max_train_epochs、批次大小 train_batch_size、梯度累积步数。
• 优化器：AdamW、AdamW8bit、PagedAdamW8bit、Lion、Lion8bit、PagedLion8bit、SGDNesterov / SGDNesterov8bit、DAdaptation、DAdaptAdam、DAdaptAdaGrad、DAdaptAdan、DAdaptAdanIP、DAdaptLion、DAdaptSGD、Prodigy、AdaFactor 等，也可通过类名引入 torch.optim 或其他模块优化器；optimizer_args 以 key=value 形式传参。
• 显存与精度控制：cache_latents / cache_latents_to_disk 缓存 VAE 输出、gradient_checkpointing 梯度检查点、xformers / sdp / none 交叉注意力选项、mixed_precision（fp16 / bf16 / fp8）、mem_eff_attn、vae_batch_size、max_data_loader_n_workers 等。
• 损失函数与噪声策略：loss_type（l2、huber、smooth_l1）、min_snr_gamma、noise_offset 与 adaptive_noise_scale、multires_noise_iterations / multires_noise_discount、ip_noise_gamma、masked_loss（实验性，使用 ControlNet 数据集掩码，R 通道 255 视为掩码）、debiased_estimation_loss、scale_v_pred_loss_like_noise_pred、v_pred_like_loss。
• 提示词与令牌：clip_skip、max_token_length（75 / 150 / 225）、weighted_captions 加权括号语法、shuffle_caption、caption_dropout_rate / caption_dropout_every_n_epochs、keep_tokens、weighted_captions、no_token_padding、stop_text_encoder_training。

2.4 采样预览、日志与模型产出

• 训练中采样图：可配置 sample_every_n_steps / sample_every_n_epochs 与 sample_prompts 提示词文件；提示词文件中 # 开头为注释行，单条提示词后可用 --n（负向提示词）、--w（宽）、--h（高）、--d（种子）、--l（CFG Scale）、--s（步数）指定本次采样参数，()、[] 提示词权重语法生效。
• 日志后端：log_with 可选 tensorboard、wandb、all 或关闭；log_tracker_name 为追踪任务名；WANDB API Key 在配置中提供；Docker 方案中 TensorBoard 由独立容器承载，界面内 “Start TensorBoard” 按钮在镜像中已隐藏。
• 保存策略：save_every_n_epochs / save_every_n_steps、save_last_n_steps、save_state / save_state_on_train_end（连同优化器状态保存以便断点续训）、save_model_as（ckpt、safetensors、diffusers、diffusers_safetensors）、save_precision（fp16、bf16、float）。
• Hugging Face 联动：可配置 huggingface_repo_id、仓库路径、类型、可见性与 token，训练结束自动上传模型与状态；支持 async_upload、resume_from_huggingface 从 HF 状态恢复（配置项见 [huggingface] 段，token 属于敏感凭据，不要写入公开配置或截图）。
• 模型合并工具：networks/merge_lora.py 把 LoRA 合并回 SD 基础模型或合并多个 LoRA 并按 --ratios 控制应用比例；networks/svd_merge_lora.py 用 SVD 近似合并不同 rank 的 LoRA；networks/extract_lora_from_models.py 从原始模型与微调模型的差异中提取 LoRA；networks/extract_lora_from_dylora.py 从 DyLoRA 模型拆分多个 rank。
• 模型元数据：[metadata] 段可配置模型标题、作者、描述、许可证与标签，写入导出模型的元信息中。

2.5 界面与工程化能力

• Gradio 参数面板：按训练模式分为对应标签页，参数以分组手风琴组织；v26.0.0 更新记录提到 “Expand all accordions” 选项、info= 提示改为悬停展开、工具按钮图标与输入框底部对齐等布局优化。
• config.toml 路径记忆：把基础模型目录、LoRA 模型目录、输出目录、数据集目录等常用路径写入配置文件，启动时自动回填各输入框，避免每次手动选择（详见第 8 节）。
• Accelerate launch 标签页：可关闭多卡复选框后指定 GPU ID；main_process_port、num_cpu_threads_per_process、num_machines、num_processes、混合精度、Dynamo 后端与模式均可在界面设置。
• 离线 / 空气隔离支持：README “Offline / air-gapped GUI shell” 小节说明：本地 Gradio 外壳（HTML/JS/CSS、主题字体、About 页）安装后不依赖第三方 CDN；安装本身仍需一次网络（或预置缓存 / 镜像）；打标、HF 模型、W&B、HF 上传按功能需要网络，硬离线训练时设置 HF_HUB_OFFLINE=1 与 TRANSFORMERS_OFFLINE=1。
• 多实例并行：README Guides 小节说明 Linux 上可在不同端口（如 7860、7861）分别启动多个 GUI 实例，用 nohup ./gui.sh --listen 0.0.0.0 --server_port <port> --headless > log.log 2>&1 & 后台运行，配合 tmux / screen 做终端跟踪。
• 多语言界面：--language 启动参数可设置自定义语言；localizations/ 目录存放界面本地化资源。

3 官方界面预览（省略）

按规程：经核验，官方 README、GitHub Wiki、仓库 docs/ 目录与官方文档页面均未提供当前 Gradio GUI 可下载的界面截图或品牌标识（README 仅含 shields.io 第三方状态徽章与 Colab 徽章；docs/train_README.md 内嵌图片为底层 sd-scripts 历史数据预处理插图，与当前 GUI 界面不一致，不作为本文配图）。本节省略，封面按规程留空；后续版本若官方新增界面截图，可在发布版本中补充。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python：pyproject.toml 口径 >=3.10,<3.12，.python-version 文件指定 3.11；Windows uv 安装文档指定安装 Python 3.11.9（64 位） 并勾选 “Add to PATH”；Linux pip 文档口径为 3.10.9 及以上且低于 3.13。uv 环境会读取仓库根目录 .python-version 指定的版本，可编辑该文件调整使用版本。
• Git：用于克隆仓库并拉取 sd-scripts 子模块；Windows 安装 git for Windows，Linux 通过发行版包管理器安装 `git`。克隆必须带 --recursive，否则 sd-scripts 子模块不会随仓库一起下载。
• NVIDIA 驱动与 CUDA Toolkit：Windows / Linux 官方安装文档均指定 CUDA Toolkit 12.8；Dockerfile 内按 CUDA 12.8 安装 cuda-nvcc-12-8，NVIDIA_REQUIRE_CUDA=cuda>=12.8。本机仍需安装与 PyTorch CUDA 版本匹配的显卡驱动；AMD 方案通过 --use-rocm 环境参数启动，Intel Arc 走 --use-ipex（旧标志名，Linux 取向），兼容性以对应需求清单为准。
• 可选 cuDNN：安装文档把 NVIDIA cuDNN 列为可选项，用于提升 30X0 / 40X0 系列训练速度、允许更大批次；pip 安装脚本菜单中可选 “Install cudnn files”。
• Windows 运行库：可选安装 Visual Studio Redistributables（vc_redist.x64.exe）。
• Linux 系统库（Ubuntu 22.04 及以后，来自 pip_linux 与 uv_linux 文档）：

sudo apt update
sudo apt install python3.11 python3.11-tk python3.11-venv git

python3.11-tk 对应运行时 tkinter 模块；官方 Troubleshooting 小节说明 No module called tkinter 报错时可在 Windows 上重装 Python 3.10 解决。

• 基础模型权重：首次训练前需要准备合规获取的基础模型（.ckpt / .safetensors 或 Diffusers 目录 / HF 模型 ID）、必要时的独立 VAE；模型不随仓库分发，下载与放置路径见 7.4 节。
• Docker 场景额外前提：Windows 需先安装 Docker Desktop、CUDA Toolkit、NVIDIA Windows 驱动并在 WSL2 下开启 GPU 支持；Linux / macOS 需安装 NVIDIA 显卡驱动与 NVIDIA Container Toolkit（Docker 说明文档链接口径）。

5.2 硬件与系统建议

5.3 端口与目录分配

注意：把 GUI 通过 --listen 0.0.0.0 或 --share 暴露到局域网 / 公网时，应同时使用 --username / --password 配置界面鉴权；远程 SSH、Runpod、Docker 等无显示环境必须加 --headless，否则原生覆盖确认弹窗与文件选择框会在服务端进程阻塞训练（README “Remote / SSH: use --headless” 小节原文说明）。

6 方式一：Docker Compose 一键部署（官方容器路径）

官方仓库根目录提供 Dockerfile 与 docker-compose.yaml，并在 docs/installation_docker.md 中给出预构建镜像与本地构建两条路径。容器默认以 --headless 启动，不自动打开浏览器，文件选择器不可用，需手动输入目录路径；TensorBoard 不在 GUI 镜像内，由 Compose 第二个独立服务启动。

6.1 前置准备

1. 按 5.1 节完成 Docker Desktop（Windows / WSL2）或 NVIDIA Container Toolkit（Linux）安装，并确认 docker --version、docker compose version 可执行。
2. 克隆仓库（含子模块）：

git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss

6.2 使用预构建镜像启动

docker compose up -d

编排文件中 kohya-ss-gui 服务使用镜像 ghcr.io/bmaltais/kohya-ss-gui:latest，build: 段同时保留本地构建上下文；首次启动会拉取镜像、准备挂载目录并以 --headless --noverify 启动 GUI。

服务与端口（来自 docker-compose.yaml）：

.env 仅含一行配置（官方仓库提供口径）：

TENSORBOARD_PORT=6006

6.3 本地构建镜像（修改源码或需要自定义环境时）

docker compose up -d --build

官方文档注明镜像构建可能需要约 20 分钟；Dockerfile 采用多阶段构建：基础阶段基于 python:3.11-slim-bookworm 安装 CUDA 12.8 必需组件，构建阶段用 uv 安装 torch==2.7.0+cu128、triton>=3.1.0、tensorflow>=2.16.1、onnxruntime-gpu==1.19.2 等大型依赖并做层缓存，最终阶段运行时安装 libgl1、libglib2.0-0、libjpeg62、libtcl8.6、libtk8.6、libgoogle-perftools-dev、dumb-init，以 UID 1000 启动，ENTRYPOINT 为 dumb-init --，CMD 为 python3 kohya_gui.py --listen 0.0.0.0 --server_port 7860 --headless --noverify。

6.4 访问与目录操作

1. 浏览器打开 http://localhost:7860/ 进入 GUI；日志监控另开 http://localhost:6006/ 查看 TensorBoard（官方 Docker 说明文档口径）。
2. 按 7.4 节把基础模型放入 ./models，数据集图片放入 ./dataset/images（或在 ./dataset 下按 8.2 节规则组织子目录），输出与日志自动落到 ./dataset/outputs、./dataset/logs。
3. 容器内文件选择器不可用：在界面路径输入框中手动填写容器内路径（如 /app/models、/dataset/images/30_cat）。

6.5 更新与停止

# 拉取最新预构建镜像并重启
docker compose down
docker compose up -d --pull always

# 本地构建方式更新：先检出新代码版本，再重建
git pull
docker compose down
docker compose up -d --build --pull always

官方 Docker 说明文档同时列出第三方 Linux 镜像 P2Enjoy/kohya_ss-docker 与 Runpod 专用镜像 ashleykleynhans/kohya-docker，均不属于本仓库官方分发，使用前须自行核验镜像来源与完整性。

7 方式二：本地源码安装与命令行运行

不使用容器时，官方提供 uv 与 pip 两条本地安装路径：uv 更快、依赖隔离更干净，官方在各平台安装文档中作为推荐；pip 更传统、便于排查问题与配合 IDE。两条路径都需要先克隆含子模块的源码仓库。

7.1 克隆仓库

git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss

--recursive 必须保留：sd-scripts 以 Git 子模块形式位于仓库 sd-scripts/ 目录，依赖清单中 -e ./sd-scripts 以可编辑模式安装该子模块。若历史克隆漏拉子模块，可补执行：

git submodule update --init --recursive

7.2 Windows：uv 方式（官方推荐）

1. 安装 5.1 节列出的 Python 3.11.9、Git for Windows、CUDA Toolkit 12.8 与可选 vc_redist。
2. 在仓库根目录运行：

.\gui-uv.bat

脚本先检查本机 uv：未安装时按提示按 Y 自动安装，或先手动从 https://astral.sh/uv 安装 uv 后重跑。uv 受管环境会按 .python-version 与 uv.lock 准备解释器与依赖，并自动完成后续更新。 3. 带参数启动示例：

.\gui-uv.bat --listen 127.0.0.1 --server_port 7860 --inbrowser --share

7.3 Windows：pip 方式（传统虚拟环境 / Conda）

1. 安装 Python、Git、CUDA 12.8 与 vc_redist（见 docs/Installation/pip_windows.md）。
2. 运行安装脚本创建虚拟环境并校验依赖：

setup.bat

本机存在多个 Python 版本时可改用：

setup-3.10.bat

安装过程中会进入 Accelerate 配置交互；官方文档提示：除明确知道硬件需求外，使用脚本给出的默认值即可，GPU 显存大小不影响这些配置值。安装脚本菜单另可选择 “2. (Optional) Install cudnn files” 安装可选 cuDNN。 3. Conda 备选路径：

conda create -n kohyass python=3.10
conda activate kohyass
setup.bat

4. 启动 GUI：

gui.ps1 --listen 127.0.0.1 --server_port 7860 --inbrowser --share

或命令行：

gui.bat --listen 127.0.0.1 --server_port 7860 --inbrowser --share

也可以直接运行 Python 入口 kohya_gui.py，参数与上述脚本一致；gui.bat --help 查看完整参数。

7.4 Linux / macOS：uv 方式（Linux 推荐）

# 系统依赖（Ubuntu 22.04+）
sudo apt update
sudo apt install python3.11 python3.11-tk python3.11-venv git

git clone --recursive https://github.com/bmaltais/kohya_ss.git
cd kohya_ss
./gui-uv.sh

脚本同样会在未检测到 uv 时提示自动安装；远程 / SSH 环境必须加 --headless：

./gui-uv.sh --headless --listen 127.0.0.1 --server_port 7860 --inbrowser --share

7.5 Linux / macOS：pip 方式

chmod +x setup.sh
./setup.sh

chmod +x gui.sh
./gui.sh --listen 127.0.0.1 --server_port 7860 --inbrowser --share

Conda 备选（docs/Installation/pip_linux.md 口径）：

conda create -n kohyass python=3.11
conda activate kohyass
chmod +x setup.sh && ./setup.sh
chmod +x gui.sh && ./gui.sh

setup.sh -h / setup.sh --help 可查看 Runpod 等附加选项；setup.sh -d /your/custom/path 可覆盖安装目录；安装目录回退顺序为当前目录 → /opt/kohya_ss → $HOME/kohya_ss，macOS 默认回退到 $HOME/kohya_ss。

7.6 放置基础模型与数据集

1. 基础模型：把合规获取的 .ckpt / .safetensors 放入 models/Stable-diffusion（或在 config.toml 的 model_dir / lc_model_dir / db_model_dir 中指向其他目录）；独立 VAE 放入 models/vae 对应位置；Diffusers 模型可直接指定本地目录路径或 HF 模型 ID。
2. 数据集：按 8.2 节规则组织图片子目录与同名元数据文件；DreamBooth 正则化图像单独放在 reg_data_dir 指定目录。
3. 输出与日志：output_dir、logging_dir 在配置中指定；首次训练建议先用小批次、少步数跑通完整流程，再放大参数。

7.7 命令行直接运行训练脚本（CLI 路径）

GUI 生成的命令最终调用 sd-scripts 脚本；也可以在激活环境后直接用 accelerate 启动底层脚本。LoRA 示例（来自 docs/train_network_README-zh.md，路径与模型名按本机替换）：

accelerate launch --num_cpu_threads_per_process 1 train_network.py \
  --pretrained_model_name_or_path=<基础模型 .ckpt/.safetensors 或 Diffusers 目录> \
  --dataset_config=<数据集配置 .toml> \
  --output_dir=<模型输出目录> \
  --output_name=<训练模型文件名（不含扩展名）> \
  --save_model_as=safetensors \
  --prior_loss_weight=1.0 \
  --max_train_steps=400 \
  --learning_rate=1e-4 \
  --optimizer_type="AdamW8bit" \
  --xformers \
  --mixed_precision="fp16" \
  --cache_latents \
  --gradient_checkpointing \
  --save_every_n_epochs=1 \
  --network_module=networks.lora

DreamBooth 省内存示例（来自 docs/train_db_README-zh.md）：

accelerate launch --num_cpu_threads_per_process 1 train_db.py \
  --pretrained_model_name_or_path=<基础模型> \
  --dataset_config=<数据集 .toml> \
  --output_dir=<输出目录> \
  --output_name=<输出文件名> \
  --save_model_as=safetensors \
  --prior_loss_weight=1.0 \
  --max_train_steps=1600 \
  --learning_rate=1e-6 \
  --optimizer_type="AdamW8bit" \
  --xformers \
  --mixed_precision="fp16" \
  --cache_latents \
  --gradient_checkpointing

不同训练方式的学习率口径不同：LoRA 建议比 DreamBooth / 全量微调高，底层 LoRA 文档建议 1e-4 至 1e-3；DreamBooth 示例使用 1e-6；SDXL LoRA 参考 docs/LoRA/top_level.md 的 Adafactor 配置（learning_rate = 4e-7、constant_with_warmup、warmup 100 步）。脚本选项若文档滞后，以各脚本 --help 输出为准。

8 配置项说明

8.1 config.toml 界面默认值配置

仓库根目录的 config example.toml 复制为 config.toml 后由 GUI 自动加载；路径建议使用绝对路径，Windows 下也使用正斜杠 /；启动参数 --config <path> 可指定其他位置的配置文件。各段用途与高频键如下（完整键清单以 config example.toml 为准）：

8.2 数据集 TOML 配置（DreamBooth / LoRA / TI 通用）

数据集配置为独立 .toml 文件，在界面 dataset_config 或 CLI --dataset_config 指定。官方 docs/train_README.md 给出的 Class+Identifier 方法示例：

[general]
enable_bucket = true                        # 是否启用宽高比分桶

[[datasets]]
resolution = 512                            # 训练分辨率，方形填单值，矩形填 512,768
batch_size = 4                              # 批次大小

  [[datasets.subsets]]
  image_dir = 'C:\\hoge'                    # 训练目标图片目录
  class_tokens = 'hoge girl'                # 标识符 + 类别
  num_repeats = 10                          # 目标图每轮重复次数

  # 使用正则化图像时追加以下子集
  [[datasets.subsets]]
  is_reg = true
  image_dir = 'C:\\reg'                     # 正则化图像目录
  class_tokens = 'girl'                    # 正则化类别词
  num_repeats = 1                           # 正则化图重复次数，通常 1 即可

目录结构规则（docs/image_folder_structure.md）：

images/
├── 30_cat/            # 目录名前缀 30 为重复次数，cat 为概念名
│   ├── image1.jpg
│   ├── image1.txt    # 同名元数据存在时，概念名以 .txt/.caption 内容为准
│   ├── image2.png
│   └── image2.txt
├── 30_dog/
└── 40_black mamba/

regularization/
├── 1_cat/
│   ├── reg1.jpg
│   └── reg2.jpg
└── 1_dog/

支持图片格式：.png、.jpg、.jpeg、.webp、.bmp；一般无需预先缩放，超过训练分辨率的图片建议先用超分工具处理，约 3000×3000 像素以上的过大图片建议先缩小以避免报错（docs/train_README.md 口径）。

8.3 GUI 启动命令行参数

来自 docs/Installation/*.md 与 kohya_gui.py 参数表，gui.sh / gui-uv.sh / gui.bat / gui-uv.bat / gui.ps1 与直接运行 kohya_gui.py 通用：

8.4 常用环境变量

不要把 Hugging Face token、W&B API Key、界面账号口令写进 config.toml 并提交到公开仓库或截图分享；凭据应通过本机私有文件、环境变量或反向代理层注入。

9 常用运维命令

以下命令按本地 Linux / macOS 路径给出；Windows 对应操作在资源管理器双击批处理，或在已激活虚拟环境的命令行中执行等效命令。

9.1 启动、停止与重启

# uv 方式本地启动（Linux）
./gui-uv.sh

# 带参数：本机监听、指定端口、自动开浏览器
./gui-uv.sh --listen 127.0.0.1 --server_port 7860 --inbrowser

# 远程 / SSH / 云实例：必须 --headless
./gui.sh --headless --listen 0.0.0.0 --server_port 7860

# 直接 Python 入口（参数同上）
python kohya_gui.py --help

REM Windows uv 方式
.\gui-uv.bat --listen 127.0.0.1 --server_port 7860 --inbrowser

REM Windows pip 方式
gui.bat --listen 127.0.0.1 --server_port 7860 --inbrowser

• 停止：在运行窗口按 Ctrl+C，或关闭命令行窗口；Docker 方式执行 docker compose stop kohya-ss-gui。
• 重启：关闭当前进程后重新执行启动脚本；修改 config.toml、切换基础模型目录、更换启动参数后需要重启生效。
• 多实例并行（Linux，README Guides 口径）：

nohup ./gui.sh --listen 0.0.0.0 --server_port 7860 --headless > log7860.log 2>&1 &
nohup ./gui.sh --listen 0.0.0.0 --server_port 7861 --headless > log7861.log 2>&1 &

9.2 更新仓库与依赖

# 本地 uv 方式：拉取代码后重跑启动脚本，环境更新自动完成
git pull
./gui-uv.sh

# 本地 pip 方式：拉取代码后重跑安装脚本
git pull
./setup.sh        # Windows: setup.bat

# Docker 预构建镜像
docker compose down
docker compose up -d --pull always

# Docker 本地构建
git pull
docker compose down
docker compose up -d --build --pull always

9.3 日志查看与监控

# TensorBoard（本地 pip / uv 方式，环境已安装 tensorboard 时）
tensorboard --logdir=logs
# 浏览器访问 http://localhost:6006/

# W&B 训练追踪：在界面 log_with 中选择 wandb 并填入 API Key，任务名由 log_tracker_name 指定

# 后台实例日志（多实例并行场景）
tail -f log7860.log

Docker 场景下 TensorBoard 由 Compose 独立服务承载，访问 http://localhost:6006/；GUI 镜像内不含 TensorBoard，界面内对应启动按钮在容器中已隐藏（Docker 说明文档口径）。

9.4 备份与恢复

建议定期备份以下内容：

# 打包配置与预设（不含大模型与数据集）
tar -czf kohya-config-backup.tar.gz config.toml presets/

恢复时把备份文件放回对应目录即可；模型目录可通过 config.toml 键值指向备份位置，不必复制回仓库目录。

9.5 状态检查与排障辅助

# 查看仓库当前提交
git rev-parse --short HEAD

# 查看工作区改动状态
git status

# 重新同步子模块（补拉 sd-scripts 时）
git submodule update --init --recursive

# 依赖校验关闭启动（环境已就绪时）
./gui.sh --noverify

# 查看 GUI 启动参数帮助
./gui.sh --help

# 训练前用 --debug_dataset 检查图片与提示词是否正确加载
# （底层 sd-scripts 选项；Linux 环境下不显示图片，按 Esc 退出、S 下一批、E 下一周期）

10 常见故障排查

以下问题整理自 README Troubleshooting 小节、docs/Installation/ 文档、docs/troubleshooting_tesla_v100.md 与底层训练文档；排查时先用最小场景（默认参数、单张图片、小批次、少步数）复现，再逐项加回变量定位。

10.1 No module named tkinter

• 现象：启动时报缺少 tkinter 模块。
• 处理：README Troubleshooting 口径为在 Windows 上重装 Python 3.10；Linux 对应安装 python3.11-tk（见 5.1 节系统依赖命令）。uv 环境版本由 .python-version 控制，重装后确认解释器与系统 Tk 库版本匹配。

10.2 Windows 页面文件（Page File）上限报错

• 现象：训练过程中出现与页面文件相关的 X 错误或内存不足。
• 处理：README Troubleshooting 口径为在 Windows 系统设置中调大虚拟内存（页面文件）上限；同时检查 train_batch_size、分辨率与 max_data_loader_n_workers 是否超出内存承受范围。

10.3 TESLA V100 上 LoRA 训练 GPU 利用率偏低

• 现象：V100 训练时 GPU 占用率低、等待明显。
• 处理：官方 docs/troubleshooting_tesla_v100.md 与 Guides 小节给出两项建议：在 Accelerate launch 标签页取消多卡复选框后用 GPU ID 指定目标显卡；使用 AdamW8bit 优化器并在显存允许范围内增大批次大小，可在不超显存的前提下把 GPU 利用率提升到约 70%–80%。

10.4 CUDA 检测失败 / 显卡未被识别

• 排查顺序：先执行 nvidia-smi 确认驱动与显卡可见；再确认 PyTorch CUDA 版本与驱动匹配（Dockerfile 口径 cu128；本地依赖清单 requirements_linux.txt 使用 torch==2.7.0+cu128）；启动参数中误加 --use-rocm 或 --use-ipex 会切换到其他后端，NVIDIA 环境应保持不指定。
• 多显卡环境在 Accelerate launch 标签页的 GPU IDs 中填写目标卡号；未指定时按默认设备运行。
• CPU / 非 NVIDIA 场景不应期望 GPU 训练性能；官方文档未提供脱离显卡驱动的 CPU 训练优化参数。

10.5 依赖版本冲突、安装脚本失败

• uv 与 pip 二选一，不要在同一虚拟环境中混用两套安装结果；uv 受管环境由 uv.lock 锁定版本，pip 方式由 requirements.txt、requirements_windows.txt、requirements_linux.txt、requirements_*.txt 分平台约束。
• 安装失败时先核对 Python 版本是否在 >=3.10,<3.12 范围内；numpy 约束为 >=1.26.0,<2（requirements.txt 注释说明 TF/ONNX 栈与 scipy 1.11 需要 NumPy 1.x），环境内若被其他包升级到 NumPy 2.x 会引发连锁冲突。
• 系统 pip 直接安装出现问题时，优先使用官方 setup.bat / setup.sh 脚本在独立虚拟环境内安装；Apple Silicon 安装问题见 v26.0.0 修复记录中 “Fixed installation error on Apple Silicon (M-series) Macs”，升级到最新提交后再复现。

10.6 数据集格式 / 目录结构错误

• 确认子目录命名为 重复次数_概念名（如 30_cat），重复次数为正整数；正则化图像子集在 TOML 中用 is_reg = true 标记。
• 同名 .txt / .caption 存在时概念名以元数据文件内容为准；训练前用 --debug_dataset 核对替换后的 token 与图片配对是否正确。
• 图片格式仅限 .png、.jpg、.jpeg、.webp、.bmp；其余格式需先转换。过大图片先缩小再入数据集。
• 中文与特殊字符路径：官方文档未专门给出中文路径兼容性说明，建议数据集、模型与输出目录统一使用英文小写、数字与正斜杠 /，避免编码差异导致脚本读取失败；config.toml 路径同样使用正斜杠。

10.7 显存不足（OOM）

• 依次尝试：降低 train_batch_size 到 1；开启 gradient_checkpointing；使用 cache_latents（与色彩 / 随机裁剪等增强互斥）；optimizer_type 切换为 AdamW8bit / PagedAdamW8bit；降低 max_resolution 与分桶上限；降低 vae_batch_size；max_data_loader_n_workers 降到 1~2 释放主内存。
• SDXL LoRA 按 docs/LoRA/top_level.md 建议至少 12GB 显存，并优先使用 --network_train_unet_only 避免双文本编码器带来的意外训练结果；PyTorch 2 相比 PyTorch 1 显存占用更低（同文档口径）。
• 底层文档中的 full_fp16 为实验性功能，官方注明精度明显下降、训练失败概率上升，仅在显存极限场景自行评估使用。

10.8 模型下载 / 打标模型拉取失败

• 首次使用 WD14 Tagger、BLIP 或指定 HF 基础模型时需要联网下载对应模型；网络不通时检查代理、镜像源与 HF 连通性。
• 硬离线环境预置模型缓存后设置 HF_HUB_OFFLINE=1、TRANSFORMERS_OFFLINE=1；此时不要在界面中触发需要新模型的功能。
• 基础模型路径写错会在训练启动阶段报加载失败；核对 --pretrained_model_name_or_path 指向的 .ckpt / .safetensors / Diffusers 目录 / HF ID 是否存在且可读。

10.9 远程 / SSH / 容器训练进程被弹窗阻塞

• 现象：--headless 未加时，原生 easygui 覆盖确认框、本地文件选择框在无显示环境的服务端进程等待交互，训练挂起不推进。
• 处理：README 明确要求远程机器（SSH、Runpod、Docker、云 GPU）启动时一律加 --headless；该参数同时隐藏界面文件选择按钮、跳过覆盖确认直接覆盖同名输出。容器内文件选择器不可用，需手动输入容器内路径。

10.10 训练日志 / 采样图异常

• 采样提示词文件中 # 为注释行；--n、--w、--h、--d、--l、--s 只对紧随其后的本条提示词生效；负向提示词与参数之间不要混入多余注释。
• TensorBoard 端口冲突时修改 .env 中 TENSORBOARD_PORT；本地方式 tensorboard --logdir=logs 指向的目录需与训练 logging_dir 一致。
• 训练产物找不到时，先核对 output_dir 与 output_name；save_every_n_epochs / save_every_n_steps 为 0 时不按周期保存，只有训练结束才输出最终模型。

10.11 常见报错快速对照

11 风险与合规说明

11.1 开源许可与分发边界

• Kohya_ss 代码本体采用 Apache License 2.0（仓库 LICENSE.md），允许使用、修改与分发，但需保留版权声明与许可证副本；二次修改后的分发应遵循 Apache 2.0 的通知与变更标注要求。
• 底层 sd-scripts 为独立 Git 子模块，其许可证以子模块仓库为准；lycoris-lora、bitsandbytes、xformers、diffusers、transformers 等第三方 Python 包各自遵循其上游许可证，商用前应逐项核对。
• 官方仓库不提供任何基础模型权重；Stable Diffusion 1.5/2.x、SDXL、SD3、Flux.1、Lumina Image 2.0、Anima、HunyuanImage-2.1 等基础模型及其衍生 LoRA、DreamBooth 产物的许可由对应模型发布方模型卡规定，部分模型仅限研究 / 非商业用途，部分商用需要额外授权。

11.2 训练素材肖像权与人格权益

• 用于训练的人物照片、肖像、角色立绘、漫画截图、影视剧帧、名人照片等素材可能涉及肖像权、著作权、商标权与人格权益；使用他人肖像训练专属 LoRA 并公开传播、商用，应取得肖像权人与相关权利人授权，不得训练用于冒充、伪造、诽谤或生成深度伪造内容。
• 数据集来源（自拍自拍素材、公版 / CC0 素材、已授权素材、网络爬取素材）应留存来源记录；正则化图像同样受上述权利约束。
• 官方与本文均不对训练数据集的权利瑕疵承担责任，素材合规由使用者自行判断与承担。

11.3 模型版权与商用许可

• 训练得到的 LoRA / DreamBooth / Fine-tuning 模型属于对基础模型权重的派生修改，其可商用范围同时受基础模型许可证与训练素材权利双重约束；基础模型禁止商用时，派生模型通常同样禁止商用。
• 发布训练产物时应在模型卡中注明基础模型、训练方式、素材来源、所用工具与许可证；不得在未授权情况下把他人训练好的 LoRA 改名重新分发。
• 模型元数据 [metadata] 段中的 metadata_license、metadata_author、metadata_tags 应如实填写；W&B、Hugging Face 上传公开仓库前再次核对可见性设置。

11.4 数据隐私与凭据安全

• 训练数据中如包含个人照片、聊天记录、身份证件、内部文档等隐私信息，应在收集、训练、上传与发布各环节做最小化处理；公开数据集与公开模型不得夹带未脱敏个人信息。
• Hugging Face token、W&B API Key、GUI --username / --password 等凭据属于敏感信息，禁止写入 config.toml、公开截图、日志或文章；提交到版本库前检查配置文件与预设目录是否误含密钥。
• 通过 --listen 0.0.0.0、--share 或反向代理暴露到公网的训练界面必须配置鉴权；未鉴权的界面等价于把本机模型、数据集与训练能力开放给任意访问者。

11.5 使用风险与免责声明

• 训练存在过拟合、灾难性遗忘、构图崩坏、肤色 / 解剖结构错误等技术风险；实验性参数（masked_loss、full_fp16、full_bf16、fp8_base 等）官方已标注可能存在缺陷，启用前自行评估风险。
• 模型生成内容的合法性、合规性与平台传播规则由使用者承担；本工具不内置内容审核，发布到社交平台、电商、广告等场景前应自行审核并遵守目标平台条款。
• 本文依据当前版本官方资料整理，模型体系、依赖版本、参数名称与硬件口径会随版本演进变化；命令、路径与配置以安装版本仓库 docs/、--help 输出与官方 Wiki 最新说明为准。本文按现状（AS-IS）提供，不构成对训练效果、商用授权、账号安全或第三方服务可用性的任何担保。