Illustrious Kohya Dataset Bridge — Any Image Count

So you want to train an Illustrious LoRA, and you've decided to do it the hard way: inside ComfyUI, with Kohya's sd-scripts underneath. The fiddly part is never the model - it's the dataset. Kohya wants a dataset.json with a fussy structure (datasets → subsets → num_repeats, resolution, batch size), and hand-writing it is the chore that makes people give up. This node is the glue that writes it for you: point it at a folder of tagged images, hand it a TrainTools-MZ workspace, and out comes the config plus the step math.

What it's for

This is one node from a tiny "bridge" pack (ComfyUI-IllustriousLoRATools) that sits between two companions: BlackSnowSkill/wd14_batch_tagger for captions and MinusZoneAI/ComfyUI-TrainTools-MZ for the training. The pipeline it's built for: load images → WD14 tagger writes a .txt caption next to each one → this node validates them and emits the dataset config → TrainTools-MZ runs Kohya.

That tagger choice isn't incidental. Illustrious is an SDXL-lineage anime model trained on Danbooru data, so its prompt interface is comma-separated Danbooru tags - exactly what a WD14 tagger outputs. A Flux or Z-Image LoRA would want natural-language JoyCaption captions instead, and this whole workflow would be the wrong tool.

How it works

The node scans your source folder for PNG/JPG/JPEG/WEBP files, checks each image has a matching caption, works out repeats, and writes two files into the train workspace under ComfyUI's output/mz_train_workspaces/: the Kohya dataset.json and a dataset_audit.json (a plain-text log of image count, missing captions, and the steps math).

Fewer images → more repeats, so a 20-epoch run lands in a sane total-step range whatever your dataset size:

1–9 images:    10 repeats
10–19 images:   6
20–39 images:   4
40–79 images:   2
80+ images:     1

Total steps is then the standard formula: ceil(images × repeats ÷ batch_size) × epochs.

The inputs that matter

Most of the schema is set-and-forget once you load the author's example workflow, but a few deserve attention:

• workspace_config - the MZ_TT_SS_WorkspaceConfig object from TrainTools-MZ's MZ_KohyaSSInitWorkspace. The node reads the workspace name out of it and writes dataset.json into that workspace's folder.
• source_folder - where your images and their captions live. The workflow wires it from the BSS nodes via forceInput rather than letting you type a bare path; the node expands ~ and environment variables.
• captions_ready - a pure ordering gate. The node literally deletes the value without reading it (del captions_ready); wiring the WD14 tagger's output here just guarantees tagging finishes first. Don't hunt for a real signal in it.
• auto_repeats (on by default) vs manual_repeats - flip auto off to set repeats by hand when you want a fixed number for your set.
• require_every_caption (on by default) - the validator. Any image missing its caption aborts the run, listing up to ten offenders; turn it off while captioning incrementally and the missing ones just land in the audit file.

The rest are simple and well-named: resolution (default 1024 - Illustrious's native resolution), batch_size (default 1), fixed_epochs (default 20), and caption_extension (.txt or .caption).

Outputs

Six of them, mostly informational: dataset_config_path (absolute path to the dataset.json it just wrote), image_count, repeats, steps_per_epoch, total_steps, and ready (always true when it returns). In the shipped workflow only ready is wired anywhere - it gates TrainTools-MZ's trainer so nothing starts until the dataset is valid. The trainer reads dataset.json from the workspace itself.

Installing it

ComfyUI Manager (search "Illustrious LoRA Tools" or the pack title) is easiest, or the classic route:

cd ComfyUI/custom_nodes
git clone https://github.com/katorikonoe-ai/ComfyUI-IllustriousLoRATools

Then restart ComfyUI. That's it - no Python dependencies at all (requirements.txt is deliberately empty; the trainer and tagger live in the companion packs). Don't skip those, because this node does nothing without them:

git clone https://github.com/MinusZoneAI/ComfyUI-TrainTools-MZ
git clone https://github.com/BlackSnowSkill/wd14_batch_tagger

The pack also ships an annotated example workflow (examples/Illustrious_XL_LoRA_Trainer_AnyImages_20Epoch_v1.json) with all six stages chained - load it rather than rebuilding by hand. The node lives under "Katori/Illustrious LoRA".

Where people get burned

The recurring traps are caption-related. The caption must share the image's exact filename with a .txt extension (img_001.png needs img_001.txt), which is what the default WD14 tagger output produces - rename anything or mix extensions and the validator aborts with a clear "N image(s) have no caption" error. That failure is a feature: it catches the classic mistake of training silently on a half-captioned folder.

The other thing to internalize: 20 epochs saving every epoch means 20 LoRA checkpoints, and the last one is usually not the best - true across this whole training family, so keep every epoch and test your winner. And the auto-repeats ladder is a blunt heuristic for keeping total steps sane, not a magic formula. You reach for this node so a folder of tagged images goes from "write Kohya's config by hand" to "press queue" - a trade most of us make gladly.