Upload skills/dataset-utils/references/training-dataset.md with huggingface_hub

skills/dataset-utils/references/training-dataset.md

@@ -0,0 +1,85 @@
+# Сборка датасета для тренировки (SDXS / FLUX / ai-toolkit)
+
+Рецепт «от картинок до готового тренировочного датасета». Основан на
+`dataset.py` и `train.py` из AiArtLab/sdxs, работает и с ai-toolkit.
+
+## Формат
+
+- **Папка** с картинками + **парные `.txt` подписи** (`foo.jpg` → `foo.txt`).
+  В датасет попадают ТОЛЬКО картинки с `.txt` — без подписи файл игнорируется.
+- Подпись — одна строка: описание (Moondream) или danbooru-теги (WD14),
+  либо комбинация. Без мусорных префиксов вроде «The image depicts...».
+- Для SDXS финальный датасет — HF Dataset на диске с колонками:
+  `vae` (латент float32 `[4, H/8, W/8]`), `text` (подпись), `width`, `height`.
+  Латент получают заранее: `vae.encode(...)` → `(latent - shift_factor) / scaling_factor`.
+
+## Шаги
+
+```bash
+export DUTILS=~/.cache/dataset-utils
+```
+
+1. **Собрать картинки** — civitai (`$DUTILS/civitai/download_feed.py`) или свои.
+
+2. **Отсеять брак** — скан качества, раскладка по причинам:
+   ```bash
+   python3 "$DUTILS/quality/scan.py" --sort /путь/к/картинкам --copy -j 16 --no-good
+   ```
+   Оставить только `good/` (или то, что нужно), удалить/перенести остальное.
+
+3. **Разметить подписи** (GPU):
+   ```bash
+   python3 "$DUTILS/caption/caption.py" /путь/к/картинкам      # описания
+   python3 "$DUTILS/caption/wd14_tagger.py" /путь/к/картинкам  # danbooru-теги
+   ```
+   Пропустят уже размеченные. Проверить покрытие:
+   ```bash
+   ls /путь/к/картинкам/*.jpg | wc -l   # vs количество .txt
+   ```
+
+4. **Выбрать бакиты и нарезать**:
+   - SDXS-1B: `--min-size 320 --max-size 640 --step 64` (кроп сверху ⅓, как в dataset.py)
+   - FLUX / ~1MP: `--min-size 1024 --max-size 1152 --step 64`
+   ```bash
+   python3 "$DUTILS/resize/img_sizes.py" /путь/к/картинкам   # прикинуть размеры
+   python3 "$DUTILS/resize/preprocess_dataset.py" --input /путь/к/картинкам \
+       --output /путь/к/out --min-size 320 --max-size 640 --step 64
+   ```
+
+5. **Балансировка** (по желанию): разнообразные по бакиту / похожие на референс
+   ```bash
+   python3 "$DUTILS/resize/diverse_images.py" /путь/к/out --output /путь/к/bal --take 500 --pick 50
+   ```
+
+6. **Прекомпьют латентов** (для SDXS; у ai-toolkit прекомпьют встроен):
+   перегнать папку через VAE → HF Dataset `{vae, text, width, height}`,
+   сгруппированный по размеру батчами (см. `dataset.py` — чанки по ~10–20k,
+   по бакитам, потом `concatenate_datasets`).
+
+7. **Обучить**:
+   ```bash
+   # sdxs
+   python train.py --ds-path /путь/к/датасету --batch-size 16 --lr 5e-5
+   # ai-toolkit — указать папку датасета в GUI/job.yaml
+   ```
+
+## Важные детали (из sdxs dataset.py / train.py)
+
+- **Группировка по (width, height) обязательна**: семплер в train.py собирает
+  батчи только из одного бакита — без паддинга, экономия памяти и флопсов.
+- Кроп в dataset.py — `top = (h - crop_h) // 3, left = 0` (не центр!).
+- Только картинки с парным `.txt` попадают в датасет — проверяй покрытие
+  подписями ДО прекомпьюта, иначе половина датасета молча потеряется.
+- Аугментации текста в train: word dropout (p=0.05), caption dropout (p=0.10).
+- `empty_share` — доля пустых подписей для guidance-тренировки (в dataset.py = 0).
+- Латенты float32; под-чанки делятся, чтобы не упереться в лимит pyarrow
+  (~2.1 млрд элементов на колонку) — держи запас.
+
+## Типовой пайплайн
+
+```
+сбор (civitai) → scan.py (брак) → caption.py / wd14_tagger.py (подписи)
+  → preprocess_dataset.py (бакиты) → diverse_images.py (баланс)
+  → vae-прекомпьют → HF Dataset {vae,text,width,height}
+  → train.py / ai-toolkit
+```