Lora Dataset Prep

LoRA Dataset Preparation

Skill for preparing image datasets for Ostris AI Toolkit / Z-Image Turbo LoRA training.

Primary target: character LoRA. Also supports style, object, clothing, environment.

Two files in this skill folder:

• prepare_dataset.py — the tool (dry-run by default, --execute to apply)
• reference.md — full captioning guide: character LoRA formula, include/omit

tables, good/bad examples, per-type caption strategies, complete validation list. Read it whenever you write or review captions.

Quick Start

# Interactive mode — asks all questions:
python prepare_dataset.py

# One-liner dry-run (shows plan, does nothing):
python prepare_dataset.py --source ./raw_photos --output ./my_dataset \
    --type character --trigger mychar01

# Execute with template captions:
python prepare_dataset.py --source ./raw_photos --output ./my_dataset \
    --type character --trigger mychar01 --captions template --copy --execute

# Execute with VLM auto-captioning (requires: pip install anthropic):
python prepare_dataset.py --source ./raw_photos --output ./my_dataset \
    --type character --trigger mychar01 --captions vlm --execute

# With resize and repeats:
python prepare_dataset.py --source ./raw_photos --output ./my_dataset \
    --type character --trigger mychar01 --resize 1024 --repeats 10 --execute

# Validate an existing dataset after editing captions (read-only):
python prepare_dataset.py --validate-only --output ./my_dataset --trigger mychar01

What the Script Does

1. Scans the source folder for .jpg, .jpeg, .png images (WebP optional with --convert-webp; subfolders with --recursive)
2. Runs image quality checks: dimensions, blur detection, EXIF-rotation flags, duplicate detection
3. Copies (or moves) images into dataset/train/ with sequential zero-padded names
4. Optionally resizes images to target resolution (--resize)
5. Writes .txt sidecar caption files (template, minimal, VLM, or local auto-captioned)
6. Creates dataset/README.md and dataset/metadata.json
7. Validates the result (missing captions, empty captions, unsafe filenames, trigger presence, image quality)

Output Structure

my_dataset/
├── train/              (or N_trigger/ with --repeats N)
│   ├── 01.png
│   ├── 01.txt
│   ├── 02.png
│   ├── 02.txt
│   └── ...
├── raw/          ← originals (backup)
├── README.md
└── metadata.json

• 01, 02 for datasets under 100 images
• 001, 002 for datasets 100+ images
• No spaces, non-ASCII characters, emojis, or special chars in any filename

Options Reference

| Flag | Default | Notes | |---|---|---| | --source | (ask) | Folder with raw images | | --output | (ask) | Output dataset folder (created) | | --type | (ask) | character / style / object / clothing / environment | | --trigger | (ask) | Unique trigger token, e.g. mychar01 | | --captions | template | minimal / template / vlm / local | | --copy | yes | Copy files, keep originals | | --move | no | Move files, delete originals | | --no-backup | off | Skip raw/ backup | | --recursive | off | Scan subfolders too (hidden folders skipped; backup names are flattened) | | --convert-webp | off | Convert .webp to .png (needs Pillow) | | --resize PX | off | Resize shortest side to PX (e.g. 1024); bakes EXIF rotation into pixels. Needs Pillow | | --repeats N | off | Create N_trigger/ folder instead of train/ (kohya/Ostris repeats) | | --vlm-model | claude-sonnet-4-6 | Model for VLM captioning | | --local-model | Salesforce/blip-image-captioning-large | Model for local captioning (use microsoft/Florence-2-large for better quality) | | --no-quality-check | off | Skip image quality checks | | --blur-threshold N | 100 | Blur heuristic sensitivity; lower it on false positives, 0 disables | | --validate-only | off | Validate an existing dataset, read-only. Use with --output and --trigger (trigger auto-read from metadata.json if omitted) | | --execute | off | Actually run (default is dry-run) |

Caption Modes

| Mode | What it writes | When to use | |---|---|---| | template | Varied templates with [BRACKET] placeholders (default) | Start here for any LoRA — fill in placeholders per image | | minimal | mychar01, portrait photo | Bare minimum; fill captions entirely by hand | | vlm | Auto-generated by Claude Vision API | Best quality — real descriptions of each image. Requires pip install anthropic and ANTHROPIC_API_KEY env var | | local | Auto-generated by a local model (Florence-2 or BLIP) | Offline captioning. Raw BLIP output must be rewritten by hand — see reference.md |

Template mode: always fill in [BRACKET] placeholders before training — they are not valid training captions. The script cannot see the images in this mode; it only creates structured templates.

VLM mode: captions are tailored to the LoRA type and follow the captioning rules automatically. If the API fails for an image, the script falls back to a template caption with a # VLM_FAILED marker; validation flags these.

Local mode: requires pip install transformers torch. The default BLIP model emits generic captions that violate the caption formula — read the warning section in reference.md before relying on it. Prefer --local-model microsoft/Florence-2-large.

Image Quality Checks

Runs automatically before processing (disable with --no-quality-check):

| Check | What it detects | Threshold | |---|---|---| | Dimensions | Images smaller than 512px on any side | min 512px | | EXIF rotation | Phone photos stored rotated with only an EXIF flag (train sideways as-is; --resize bakes the rotation in) | orientation ≠ 1 | | Blur | Blurry/out-of-focus images via edge variance | score Describe what you do NOT want the LoRA to learn. Everything not in the caption > gets bound to the trigger token.

FORMULA:
[trigger], [media type], [shot type] of a man/woman, [clothing], [pose/action],
[expression], [background/setting], [lighting]

INCLUDE:  clothing, pose, expression, angle, background, lighting, media type
OMIT:     face, eyes, skin, quality tags, repeated adjectives
LENGTH:   15–35 words
LANGUAGE: natural language, not tags
TRIGGER:  first word, once

Full guide with include/omit tables, good/bad examples, typical mistakes, and strategies for style/object/clothing/environment LoRA: reference.md.

Validation

After execution (or standalone via --validate-only) the script checks: image↔caption pairing, trigger presence and position, caption length (15–35 words target), unfilled [BRACKET] placeholders, filler phrases, multiple subjects, attribute-sticking (repeated phrases in ≥50% of captions), unsafe filenames, image size, blur, exact and near-duplicates, VLM_FAILED markers. Full list in reference.md.

Supported Formats

| Format | Support | |---|---| | .jpg, .jpeg, .png | native | | .webp | opt-in via --convert-webp (needs Pillow) | | Other | skipped, warned |

Avoid WebP in training datasets — some training pipelines cannot read it.

Optional Dependencies

| Package | What it enables | |---|---| | Pillow | WebP conversion, image resize, quality checks (dimensions, blur) | | anthropic | VLM auto-captioning via Claude Vision API (--captions vlm) | | transformers + torch | Local auto-captioning (--captions local, Florence-2 / BLIP) |

Install: pip install Pillow anthropic (plus pip install transformers torch for local mode)

Dataset Size Guidance (Z-Image Turbo)

| LoRA type | Min images | Recommended | Notes | |---|---|---|---| | Character | 15 | 15–30 (~20 optimal) | Varied angle/expression/lighting/background; avoid duplicates | | Object | 20 | 30–50 | Multi-angle + detail close-ups | | Clothing | 10 | 20–40 | On-body + flat lay + details | | Style | 30 | 50–100 | Diverse subjects in the style | | Environment | 30 | 50–100 | Wide + detail, varied lighting |

After Dataset Prep

1. Review captions — if VLM/local mode, check accuracy. If template mode, fill in [BRACKET] placeholders
2. Run validation — python prepare_dataset.py --validate-only --output ./my_dataset (read-only, never touches files)
3. Create training config — YAML for Ostris AI Toolkit with rank/steps/LR for your hardware
4. Set sample prompts using the trigger token — add 3–5 fixed-seed prompts to the config
5. Upload dataset to your training machine (local GPU or a cloud pod) and launch

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: afloy011-spec
• Source: afloy011-spec/lora-dataset-prep
• License: MIT

Install and usage instructions live in the source repository linked above.