How bmaltais/kohya_ss works
Project Type and Purpose
• This is a specialized GUI tool (full-stack, single-page web app) built on Gradio that wraps and orchestrates Kohya’s Stable Diffusion training scripts (sd-scripts).
• Its primary function is to let users configure model-training parameters via a web interface, generate the corresponding CLI commands, execute them (locally or in container), and display results (logs, sample images).
File Structure
• Top-level “entry points”:
– gui.sh, gui.bat, gui.ps1, gui-uv.sh, gui-uv.bat – scripts to launch the Gradio server (legacy “pip” and UV/uvicorn-based methods)
– kohya_gui.py – main Python script that initializes the Gradio interface
– Dockerfile & docker-compose.yaml – containerization and deployment definitions
• Core backend package:
– kohya_gui/ – contains ~50 class_*.py modules (each GUI tab, configuration loader, command executor, logging, localization)
– tools/ – utility scripts to prepare images, presets, convert formats, etc.
– config example.toml & config_files/ – default and platform-specific settings for accelerate, Runpod
– presets/, models/, dataset/ – user data volumes for training inputs, model storage, outputs
• Supporting directories: docs/, examples/, test/, assets/ (JS, CSS for styling and localization)
Key Insights from README
• Front-end: Gradio UI that serves on port 7860 (can be shared or headless)
• Back-end: builds CLI commands and either shells out or imports sd-scripts with accelerate
• Deployment: supports native (Windows, Linux, macOS), Docker, Runpod, Novita
• Logging & monitoring: TensorBoard runs in a separate container via docker-compose
Main Components & Their Interactions
A. User’s Web Browser
– Interacts with Gradio front-end over HTTP(S).
B. Gradio Server (View)
– kohya_gui.py + assets/js/*.js + assets/style.css
– Renders pages, handles input forms, displays outputs.
C. Backend Controller (Controller)
– kohya_gui/class_*.py modules:
• class_basic_training, class_advanced_training – gather parameters
• class_command_executor – builds and launches CLI commands
• class_configuration_file – loads/saves config.toml or presets
• custom_logging – collects stdout/“TensorBoard logs” for UI
– tools/ scripts invoked as needed for preprocessing.
D. Training Engine (Model)
– External sd-scripts (train_network.py, train_db, train_lllite, etc.)
– Accelerate library orchestrates multi-GPU or single GPU runs.
– Huggingface-hub, diffusers – download/upload pre-trained models.
E. Data Storage & Volumes
– dataset/ (inputs, masks), models/ (checkpoints), outputs/ (sample images), logs/
– presets/ (default and user-provided JSON configurations)
F. Monitoring & Visualization
– TensorBoard: separate container in docker-compose, mounts same logs volume.
G. Containerization & Deployment
– Dockerfile: builds the image, installs dependencies, expects /dataset volume.
– docker-compose.yaml: kicks off Gradio container + TensorBoard container + optional Postgres or storage.
– Runpod/Novita templates wrap the same Docker logic.
H. External Services
– GitHub (code updates), Huggingface Hub (model weights), optional authentication for sharing.
Architectural Patterns & Design Principles
• MVC-inspired separation:
– View = Gradio front-end ( kohya_gui.py + assets )
– Controller = kohya_gui/class_*.py orchestration layer
– Model = CLI training scripts + data files + presets
• Plugin-style GUI tabs: each class_*.py is a self-contained tab/controller
• CLI wrapper pattern: generate shell commands or direct Python calls
• Volume-based configuration: config.toml, presets, environment files
• Container-first deployment with clear volume mounts and microservices (TensorBoard)