Archivo de configuración del dataloader¶

Aquí está el ejemplo más básico de un archivo de configuración del dataloader, como multidatabackend.example.json.

[
  {
    "id": "something-special-to-remember-by",
    "type": "local",
    "instance_data_dir": "/path/to/data/tree",
    "crop": true,
    "crop_style": "center",
    "crop_aspect": "square",
    "resolution": 1024,
    "minimum_image_size": 768,
    "maximum_image_size": 2048,
    "minimum_aspect_ratio": 0.50,
    "maximum_aspect_ratio": 3.00,
    "target_downsample_size": 1024,
    "resolution_type": "pixel_area",
    "prepend_instance_prompt": false,
    "instance_prompt": "something to label every image",
    "only_instance_prompt": false,
    "caption_strategy": "textfile",
    "cache_dir_vae": "/path/to/vaecache",
    "repeats": 0
  },
  {
    "id": "an example backend for text embeds.",
    "dataset_type": "text_embeds",
    "default": true,
    "type": "aws",
    "aws_bucket_name": "textembeds-something-yummy",
    "aws_region_name": null,
    "aws_endpoint_url": "https://foo.bar/",
    "aws_access_key_id": "wpz-764e9734523434",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_data_prefix": "",
    "cache_dir": ""
  }
]

Opciones de configuración¶

id¶

• Descripción: Identificador único para el dataset. Debe permanecer constante una vez definido, ya que lo vincula a sus entradas de seguimiento de estado.

disabled¶

• Valores: true | false
• Descripción: Cuando se establece en true, este dataset se omite por completo durante el entrenamiento. Útil para excluir temporalmente un dataset sin eliminar su configuración.
• Nota: También acepta la grafía disable.

dataset_type¶

• Valores: image | video | audio | caption | text_embeds | image_embeds | conditioning_image_embeds | conditioning
• Descripción: Los datasets image, video y audio contienen muestras de entrenamiento primarias. text_embeds contiene las salidas de la caché del encoder de texto, image_embeds contiene los latentes del VAE (cuando un modelo usa uno), y conditioning_image_embeds almacena embeddings de imagen de condicionamiento cacheados (por ejemplo, features de visión de CLIP). Cuando un dataset está marcado como conditioning, se puede emparejar con tu dataset image mediante la opción conditioning_data
• Nota: Los datasets de text y image embeds se definen de forma diferente a los datasets de imagen. Un dataset de text embeds almacena SOLO los objetos de text embed. Un dataset de imagen almacena los datos de entrenamiento.
• Nota: No combines imágenes y video en un único dataset. Sepáralos.

caption_file_extensions¶

El descubrimiento de descripciones acepta esta lista opcional no vacía de extensiones, por ejemplo ["jsonl"]. El valor predeterminado es ["txt", "json", "jsonl"]. Los JSON de metadatos y caché de grupos del propio backend siempre se excluyen, incluso al reiniciar con una lista de archivos existente.

data_generator¶

Solo válido para dataset_type: "caption" (singular). Este objeto opcional genera un PNG y su texto para cada descripción en cada resolución indicada, antes de las cachés de imágenes, embeddings de texto y VAE. Los resultados usan el entrenamiento normal de imágenes, sin necesitar un destilador. Sin este objeto, los datasets de descripciones siguen requiriendo un destilador que las acepte.

• resolutions (obligatorio): lista no vacía de cadenas WIDTHxHEIGHT, con dimensiones múltiplos de 32. Cada resolución crea <id>-generated-<resolution>, utiliza su lado corto nativo en píxeles y desactiva el recorte. La probability original se reparte entre los grupos.
• batch_size (predeterminado 1): lote de generación, independiente del lote de entrenamiento. Si se agota la memoria del acelerador, se reduce a la mitad el lote fallido de esa resolución y se repiten las mismas muestras con las mismas semillas. Los límites que funcionan se guardan en el manifiesto de generación. Un fallo de memoria con lote uno, o cualquier otro error, detiene la generación.
• num_inference_steps (predeterminado 40), guidance_scale (1.0) y seed (0): parámetros de inferencia. Qwen Image usa true_cfg_scale; los valores superiores a uno utilizan un prompt negativo vacío. La guía de validación no sustituye este valor.
• output_dir (opcional): predeterminado cache_dir/generated-captions/<id>. Los resultados se guardan bajo una huella de la receta y se reutilizan al reiniciar. Incluye descripciones, ajustes de inferencia, revisiones resueltas del Hub y tamaños/fechas de modificación de los pesos locales. No modifique el modelo durante la generación. Cambiar descripciones, modelo o inferencia crea otra caché; cambiar el lote no.

La generación usa el modelo base con adaptadores desactivados y libera únicamente el transformador cargado para el preprocesamiento. Los textos originales no cambian. La generación requiere una ejecución de preparación con un solo proceso; las ejecuciones con varios procesos y data_generator se rechazan antes de ingerir las descripciones. Para entrenamiento distribuido, use los directorios generados como datasets image normales con caption_strategy: "textfile", uno por resolución, crop: false, resolution_type: "pixel" y resolution igual al lado corto del grupo. Los datasets de descripciones sin generador requieren dataloader_prefetch=false para conservar la posición del muestreador en los checkpoints. Cambiar las descripciones, resoluciones o topología del dataset requiere iniciar otro entrenamiento; reutilizar la caché generada no hace compatibles esas reanudaciones de checkpoint.

Para descubrir descripciones locales, la salida generada debe quedar fuera del instance_data_dir de origen; los directorios superpuestos se rechazan antes del escaneo.

{
  "id": "assistant-images",
  "type": "local",
  "dataset_type": "caption",
  "instance_data_dir": "data/prompts",
  "caption_strategy": "textfile",
  "data_generator": {
    "batch_size": 2,
    "resolutions": ["512x512", "768x1024"],
    "num_inference_steps": 40,
    "guidance_scale": 1.0,
    "seed": 42
  }
}

default¶

• Solo aplica a dataset_type=text_embeds
• Si se establece en true, este dataset de text embeds será donde SimpleTuner almacene la caché de text embeds para, p. ej., embeds de prompts de validación. Como no se emparejan con datos de imagen, se necesita una ubicación específica donde terminen.

cache_dir¶

• Solo aplica a dataset_type=text_embeds y dataset_type=image_embeds
• Descripción: Especifica dónde se almacenan los archivos de caché de embeds para este dataset. Para text_embeds, aquí se escriben las salidas del encoder de texto. Para image_embeds, aquí se almacenan los latentes del VAE.
• Nota: Es diferente de cache_dir_vae, que se configura en datasets de imagen/video principales para indicar dónde va su caché VAE.

train_batch_size¶

• Comportamiento de entrenamiento: Los datasets primarios muestreados de forma independiente (image, video, audio, caption) usan el valor resuelto como tamaño del microbatch de entrenamiento. conditioning es información auxiliar emparejada; su valor resuelto todavía puede dimensionar los buckets de metadatos, pero no crea un microbatch de entrenamiento independiente ni cuenta por separado en las muestras de una actualización del optimizador.
• Descripción: Sobrescribe el --train_batch_size global para este dataset. En datasets primarios, el valor resuelto controla el microbatch del sampler, los buckets y el número instantáneo de muestras cuando se selecciona. En conditioning, solo afecta la preparación de metadatos y buckets. Déjalo sin definir para usar el valor global.
• Acumulación de gradiente: Una ventana de acumulación puede seleccionar datasets con distintos tamaños de microbatch resueltos. El total global de muestras de una actualización del optimizador es la suma de los tamaños reales de los microbatches locales en todos los microsteps de acumulación y ranks data-parallel; un dataset seleccionado sin override usa el valor global predeterminado en ese rank.
• Referencia global: El escalado del learning rate a nivel del trainer y otras configuraciones estáticas o informes que requieren un único batch size fijo siguen usando el --train_batch_size global. Por tanto, al mezclar overrides por dataset, la fórmula habitual del batch size global/efectivo es una referencia configurada, no el número exacto de muestras de cada actualización del optimizador.
• Gradient checkpointing: Gradient checkpointing no cambia la aritmética del batch size.
• Default: Usa el argumento --train_batch_size del trainer.

write_batch_size¶

• Solo aplica a dataset_type=text_embeds
• Descripción: Número de text embeds que se escriben en una sola operación por batch. Valores más altos pueden mejorar el throughput de escritura pero usan más memoria.
• Default: Usa el argumento --write_batch_size del trainer (normalmente 128).

text_encoder_batch_size¶

• Solo aplica a dataset_type=text_embeds
• Descripción: Número de captions que se codifican en un solo forward del encoder de texto al precomputar text embeddings no cacheados. Valores más altos pueden mejorar el throughput pero usan más VRAM.
• Default: Usa el argumento --text_encoder_batch_size del trainer (predeterminado 1).

text_cache_ondemand¶

• Solo aplica a dataset_type=text_embeds
• Valores: true | false
• Descripción: Omite el cálculo previo completo de embeddings de texto. Las entradas existentes se leen de este caché; los embeddings que falten se codifican durante el entrenamiento o la validación y se escriben en el caché.
• Nota: Cada dataset de imagen o vídeo asignado a este backend text_embeds hereda este comportamiento. Para usar otro comportamiento en determinados datasets de origen, crea otro backend text_embeds y asígnalo mediante el campo text_embeds del dataset de origen.

text_cache_disable¶

• Solo aplica a dataset_type=text_embeds
• Valores: true | false
• Descripción: Lee embeddings de texto existentes, pero no escribe los recién codificados. Las entradas que falten se codifican durante el entrenamiento o la validación, por lo que esta opción implica text_cache_ondemand.
• Nota: La opción global --text_cache_disable se aplica a todos los cachés de texto. Usa esta opción de backend cuando la opción global sea false y solo ciertos backends text_embeds deban evitar escrituras.

text_embeds¶

• Solo aplica a dataset_type=image
• Si no se configura, se usará el dataset text_embeds marcado como default. Si se configura con el id existente de un dataset text_embeds, se usará ese en su lugar. Permite asociar datasets de text embeds específicos a un dataset de imagen.

image_embeds¶

• Solo aplica a dataset_type=image
• Si no se configura, las salidas del VAE se almacenarán en el backend de imagen. En caso contrario, puedes establecerlo al id de un dataset image_embeds, y las salidas del VAE se almacenarán allí. Permite asociar el dataset image_embed a los datos de imagen.

conditioning_image_embeds¶

• Aplica a dataset_type=image y dataset_type=video
• Cuando un modelo reporta requires_conditioning_image_embeds, establece esto al id de un dataset conditioning_image_embeds para almacenar embeddings de imagen de condicionamiento cacheados (por ejemplo, features de visión de CLIP para Wan 2.2 I2V). Si se omite, SimpleTuner escribe la caché en cache/conditioning_image_embeds/<dataset_id> por defecto, garantizando que ya no colisione con la caché VAE.
• Los modelos que necesitan estos embeds deben exponer un encoder de imagen a través de su pipeline principal. Si el modelo no puede suministrar el encoder, el preprocesamiento fallará pronto en lugar de generar archivos vacíos silenciosamente.

cache_dir_conditioning_image_embeds¶

• Override opcional para el destino de caché de conditioning image embed.
• Configúralo cuando quieras fijar la caché a una ubicación específica del filesystem o tener un backend remoto dedicado (dataset_type=conditioning_image_embeds). Si se omite, se usa automáticamente la ruta de caché descrita arriba.

conditioning_image_embed_batch_size¶

• Override opcional para el tamaño de batch usado al generar conditioning image embeds.
• Por defecto usa el argumento conditioning_image_embed_batch_size del trainer o el tamaño de batch del VAE cuando no se proporciona explícitamente.

Configuración de dataset de audio (dataset_type=audio)¶

Los backends de audio admiten un bloque audio dedicado para que los metadatos y el cálculo de buckets tengan en cuenta la duración. Ejemplo:

"audio": {
  "max_duration_seconds": 90,
  "channels": 2,
  "bucket_strategy": "duration",
  "duration_interval": 15,
  "truncation_mode": "beginning"
}

Cuando todos los datasets multimedia habilitados usan dataset_type: "audio", las familias de video con SUPPORTS_FAKE_VIDEO_STREAM activan automáticamente el entrenamiento solo de audio. LTX-2 usa su rama nativa de audio; MiniMax-H3 conserva un token espacial de video falso por frame latente y enmascara la pérdida de video. LoRA estándar selecciona AUDIO_LORA_TARGET automáticamente, salvo que se configure peft_lora_target_modules.

• bucket_strategy – actualmente duration es el valor por defecto y recorta clips en buckets espaciados uniformemente para que el muestreo por GPU respete el cálculo de batch.
• duration_interval – redondeo del bucket en segundos (por defecto 3 si no se configura). Con 15, un clip de 77 s queda en el bucket de 75 s. Esto evita que un clip largo deje a otras ranks sin muestras y fuerza el truncado al mismo intervalo.
• max_duration_seconds – los clips más largos que esto se omiten por completo durante el descubrimiento de metadatos, así que pistas excepcionalmente largas no consumen buckets inesperadamente.
• truncation_mode – determina qué parte del clip se conserva cuando ajustamos al intervalo del bucket. Opciones: beginning, end o random (default: beginning).
• audio_only – override de compatibilidad para el modo solo audio; las configuraciones compuestas solo por audio lo activan automáticamente en LTX-2 y MiniMax-H3.
• target_resolution – override legado; los streams falsos automáticos usan la geometría mínima del modelo.
• La configuración estándar de audio (número de canales, directorio de caché) se mapea directamente al backend de audio en tiempo de ejecución creado por simpletuner.helpers.data_backend.factory. Se evita el padding intencionalmente: los clips se truncan en lugar de extenderse para mantener el comportamiento consistente con entrenadores de difusión como ACE-Step.

Configuración de audio para entrenamiento S2V¶

El bloque audio se puede colocar en datasets de video para extraer audio automáticamente de los archivos de video. Para modelos que requieren entrenamiento S2V (Sound-to-Video) (ej: Wan S2V), este bloque se inyecta automáticamente. Para modelos que soportan pero no requieren audio (ej: LTX-2), debes agregar una sección audio explícitamente para optar — sin ella, solo se entrena video y la pérdida de audio se enmascara automáticamente.

{
  "id": "my-videos",
  "type": "local",
  "dataset_type": "video",
  "instance_data_dir": "datasets/videos",
  "cache_dir_vae": "cache/vae/videos",
  "audio": {
    "auto_split": true,
    "sample_rate": 16000,
    "channels": 1,
    "allow_zero_audio": false
  }
}

Esto crea automáticamente un dataset my-videos_audio y lo enlaza vía s2v_datasets.

Captions de audio (Hugging Face)¶

Para datasets de audio de Hugging Face, puedes especificar qué columnas forman el caption (prompt) y qué columna contiene las letras:

"config": {
    "audio_caption_fields": ["prompt", "tags"],
    "lyrics_column": "lyrics"
}

Durante el descubrimiento de metadatos, el loader registra sample_rate, num_samples, num_channels y duration_seconds para cada archivo. Los reportes de buckets en la CLI ahora hablan en muestras en lugar de imágenes, y los diagnósticos de dataset vacío enumerarán el bucket_strategy/duration_interval activo (más cualquier límite de max_duration_seconds) para que puedas ajustar intervalos sin entrar en los logs.

type¶

• Valores: aws | local | memory | csv | huggingface | webshart
• Descripción: Determina el backend de almacenamiento (local, memoria, csv o cloud) usado para este dataset.

Backends en memoria (tmpfs y RAM disk)¶

type: "memory" usa MemoryDataBackend, una subclase de LocalDataBackend respaldada por tmpfs en Linux o un RAM disk nativo en macOS. Solo está disponible para entradas de almacenamiento de caché con dataset_type: "text_embeds" o dataset_type: "image_embeds"; no puede usarse para datasets primarios de imagen, vídeo, audio, conditioning o evaluación. SimpleTuner monta un sistema de archivos vacío separado y copia allí el cache_dir configurado cuando ese directorio existe. Las lecturas y escrituras usan la copia residente en memoria y se descartan al liberarla; no se sincronizan con cache_dir.

{
  "id": "memory-vae-cache",
  "type": "memory",
  "dataset_type": "image_embeds",
  "cache_dir": "/cache/vae",
  "memory_filesystem_path": "/tmp/simpletuner-memory/vae",
  "memory_filesystem_size": "512G",
  "memory_filesystem_sudo": false
}

• memory_filesystem_path: Directorio de montaje vacío opcional. Por defecto se usa simpletuner-memory/<id del dataset> dentro del directorio temporal del sistema. Este directorio y cache_dir no deben superponerse ni contenerse entre sí.
• memory_filesystem_size: Capacidad del sistema de archivos en memoria, como 512G. Es opcional en Linux, donde se aplica el valor tmpfs predeterminado y se aceptan porcentajes como 80%. En macOS es obligatorio y debe ser un tamaño en bytes, no un porcentaje; SimpleTuner lo convierte al número de sectores de 512 bytes requerido por hdiutil.
• memory_filesystem_sudo: Solo Linux. Si es true, ejecuta mount y umount mediante sudo -n. Déjalo en false al ejecutar como root, algo habitual en contenedores. Al habilitarlo, sudo sin contraseña y no interactivo debe estar configurado previamente. Los RAM disks de macOS usan hdiutil y diskutil sin esta opción.

Los backends de memoria requieren Linux o macOS y suficiente RAM o swap para la caché existente y todos los embeddings escritos durante el entrenamiento. Son útiles para cachés grandes de latentes o embeddings de texto en sistemas con mucha memoria cuando las lecturas repetidas son el cuello de botella. Precargar una caché existente aumenta el tiempo de inicio; usa un cache_dir vacío o inexistente para comenzar con una caché vacía.

conditioning_type¶

• Valores: controlnet | mask | reference_strict | reference_loose
• Descripción: Especifica el tipo de condicionamiento para un dataset conditioning.
• controlnet: Entradas de condicionamiento ControlNet para entrenamiento con señal de control.
• mask: Máscaras binarias para entrenamiento de inpainting.
• reference_strict: Imágenes de referencia con alineación estricta de píxeles (para modelos de edición como Qwen Edit).
• reference_loose: Imágenes de referencia con alineación flexible.
• Nota de Flow-DPO: reference_strict también lo usa Flow-DPO para aportar los latentes rejected/lose de cada muestra preferred.

source_dataset_id¶

• Solo aplica a dataset_type=conditioning con conditioning_type de reference_strict, reference_loose o mask
• Descripción: Vincula un dataset de condicionamiento con su dataset fuente de imagen/video para alineación de píxeles. Cuando se establece, SimpleTuner duplica metadatos del dataset fuente para garantizar que las imágenes de condicionamiento se alineen con sus objetivos.
• Nota: Requerido para modos de alineación estricta; opcional para alineación flexible.

conditioning_data¶

• Valores: valor id de dataset de condicionamiento o un arreglo de valores id
• Descripción: Como se describe en la guía de ControlNet, un dataset image puede emparejarse con sus datos de ControlNet o máscaras de imagen mediante esta opción.
• Nota: Si tienes varios datasets de condicionamiento, puedes especificarlos como un arreglo de valores id. Al entrenar Flux Kontext, esto permite cambiar aleatoriamente entre condiciones o unir entradas para entrenar tareas avanzadas de composición multi-imagen.
• Flow-DPO: Empareja aquí un dataset reference_strict cuando uses --distillation_method=flow_dpo.

data_transforms¶

• Valores: un objeto de transform o un arreglo de objetos de transform
• Descripción: Expande un dataset fuente en uno o más datasets de entrenamiento generados antes de que empiece la configuración normal del dataloader. Los datasets generados se tratan como datasets primarios normales salvo que el transform pida explícitamente clonar metadatos.
• Identity transfer de audio: {"task": "identity_transfer", "method": "rvc"} está disponible para backends con dataset_type: "audio". Prepara un split de audio generado para transferencia de identidad vocal y usa el directorio de salida para artefactos de voz cacheados y archivos generados. Consulta Voice Cloning Data Transforms.
• Identity data: Pon la musica a convertir en el instance_data_dir del backend de audio, los ejemplos de la voz objetivo en model.identity_data_dir, y la ruta del split generado en target.instance_data_dir.
• Debug de stems: Define model.identity_stem_debug_dir para conservar previews vocals.wav y no_vocals.wav de la identidad separada que realmente usa el entrenamiento RVC. Sirve para revisar casos donde la salida suena como si los instrumentos se hubieran aprendido como parte de la voz.
• Estado: La implementación experimental incluye comprobaciones de manifiestos de caché, reutilización/subida de artefactos a Hub mediante el layout huggingface-hub-rvc, sharding de inicio compatible con DDP, logs locales de RVC y un trainer/converter compacto de voice-transfer de SimpleTuner. El modo full-song remix usa Demucs para separar voces; el modo vocal-stem no necesita separación.

instance_data_dir / aws_data_prefix¶

• Local: Ruta a los datos en el filesystem.
• AWS: Prefijo S3 de los datos en el bucket. aws_data_prefix puede ser una cadena para un prefijo o una lista de cadenas para escanear varios prefijos del mismo bucket.

caption_strategy¶

• textfile requiere que tu image.png esté junto a un image.txt que contenga uno o más captions, separados por saltos de línea. Estos pares imagen+texto deben estar en el mismo directorio.
• instanceprompt requiere que se proporcione un valor para instance_prompt y usará solo este valor para el caption de cada imagen en el conjunto.
• filename usará una versión convertida y limpiada del nombre de archivo como su caption, p. ej., sustituyendo guiones bajos por espacios.
• parquet extraerá captions de la tabla parquet que contiene el resto de los metadatos de imagen. Usa el campo parquet para configurarlo. Consulta Estrategia de caption parquet.
• webshart extrae captions de los metadatos de shards Webshart y requiere type: "webshart" con metadata_backend: "webshart".

Tanto textfile como parquet soportan multi-captions: - Los textfiles se dividen por saltos de línea. Cada nueva línea será un caption independiente. - Las tablas parquet pueden tener un tipo iterable en el campo.

disable_multiline_split¶

• Cuando se establece a true, evita que los archivos de texto de caption se dividan por saltos de línea en múltiples variantes de caption.
• Útil cuando tus captions contienen saltos de línea intencionales que deben preservarse como un único caption.
• Por defecto: false (los captions se dividen por saltos de línea)

caption_shuffle¶

Genera variantes mezcladas determinísticas de captions basados en tags para aumento de datos. Esto ayuda al modelo a aprender que el orden de las tags no importa y reduce el sobreajuste a secuencias específicas de tags.

Configuración:

{
  "caption_shuffle": {
    "enable": true,
    "count": 3,
    "seed": 42,
    "split_on": "comma",
    "position_start": 1,
    "include_original": true
  }
}

Parámetros:

• enable (bool): Si se habilita el mezclado de captions. Por defecto: false
• count (int): Número de variantes mezcladas a generar por caption. Por defecto: 1
• seed (int): Semilla para mezclado determinístico. Si no se especifica, usa el valor global --seed.
• split_on (string): Delimitador para dividir captions en tags. Opciones: comma, space, period. Por defecto: comma
• position_start (int): Mantener las primeras N tags en su posición original (útil para mantener tags de sujeto/estilo al principio). Por defecto: 0
• include_original (bool): Si se incluye el caption original sin mezclar junto con las variantes mezcladas. Por defecto: true

Ejemplo:

Con split_on: "comma", position_start: 1, count: 2:

• Original: "dog, running, park, sunny day"
• Resultado: ["dog, running, park, sunny day", "dog, park, sunny day, running", "dog, sunny day, running, park"]

La primera tag "dog" permanece fija mientras las tags restantes se mezclan.

Notas:

• El mezclado se aplica durante el pre-cacheo de embeddings de texto, así que todas las variantes se calculan de una vez.
• Durante el entrenamiento, se selecciona una variante aleatoriamente por muestra.
• Si un caption tiene menos tags que position_start + 2, el mezclado se omite (nada significativo que mezclar).
• Cuando include_original: false pero el mezclado no es posible, se incluye el original de todos modos con una advertencia.

metadata_backend¶

• Valores: discovery | parquet | huggingface | webshart
• Descripción: Controla cómo SimpleTuner descubre dimensiones de imagen y otros metadatos durante la preparación del dataset.
• discovery (default): Escanea archivos de imagen reales para leer dimensiones. Funciona con cualquier backend de almacenamiento, pero puede ser lento para datasets grandes.
• parquet: Lee dimensiones desde width_column y height_column en un archivo parquet/JSONL, omitiendo acceso a archivos. Consulta Estrategia de caption parquet.
• huggingface: Usa metadatos de datasets de Hugging Face. Consulta Hugging Face Datasets Support.
• webshart: Usa metadatos de shards Webshart, incluidos buckets de aspecto por muestra lógica y captions, sin escanear bytes de imagen.
• Nota: Cuando usas parquet, también debes configurar el bloque parquet con width_column y height_column. Esto acelera drásticamente el inicio en datasets grandes.

metadata_update_interval¶

• Valores: Integer (segundos)
• Descripción: Con qué frecuencia (en segundos) refrescar metadatos del dataset durante el entrenamiento. Útil para datasets que puedan cambiar durante una ejecución larga.
• Default: Usa el argumento --metadata_update_interval del trainer.

Opciones de recorte¶

• crop: Habilita o deshabilita el recorte de imágenes.
• crop_style: Selecciona el estilo de recorte (random, center, corner, face).
• crop_aspect: Elige el aspecto de recorte (closest, random, square o preserve).
• crop_aspect_buckets: Cuando crop_aspect se establece en closest o random, se seleccionará un bucket de esta lista. Por defecto, todos los buckets están disponibles (permitiendo escalado ilimitado). Usa max_upscale_threshold para limitar el escalado si es necesario.

resolution¶

• resolution_type=area: El tamaño final de la imagen se determina por el conteo de megapíxeles: un valor de 1.05 aquí corresponderá a buckets de aspecto alrededor de 1024^2 (1024x1024) de área total de píxeles, ~1_050_000 píxeles.
• resolution_type=pixel_area: Como area, el tamaño final se determina por su área, pero mide en píxeles en lugar de megapíxeles. Un valor de 1024 aquí generará buckets de aspecto alrededor de 1024^2 (1024x1024) de área total de píxeles, ~1_050_000 píxeles.
• resolution_type=pixel: El tamaño final de la imagen se determinará por el borde más corto siendo este valor.

NOTA: Que las imágenes se escalen, reduzcan o recorten depende de los valores de minimum_image_size, maximum_target_size, target_downsample_size, crop y crop_aspect.

minimum_image_size¶

• Cualquier imagen cuyo tamaño final quede por debajo de este valor será excluida del entrenamiento.
• Cuando resolution se mide en megapíxeles (resolution_type=area), esto debe estar en megapíxeles también (p. ej., 1.05 megapíxeles para excluir imágenes bajo 1024x1024 de área)
• Cuando resolution se mide en píxeles, usa la misma unidad aquí (p. ej., 1024 para excluir imágenes con el borde más corto menor a 1024 px)
• Recomendación: Mantén minimum_image_size igual a resolution salvo que quieras arriesgarte a entrenar con imágenes mal escaladas.

minimum_aspect_ratio¶

• Descripción: La relación de aspecto mínima de la imagen. Si la relación de aspecto de la imagen es menor que este valor, se excluirá del entrenamiento.
• Nota: Si el número de imágenes que califican para exclusión es excesivo, esto podría desperdiciar tiempo en el arranque porque el trainer intentará escanearlas y hacer bucketing si faltan en las listas de buckets.

Nota: Una vez que las listas de aspecto y metadatos están construidas para tu dataset, usar skip_file_discovery="vae aspect metadata" evitará que el trainer escanee el dataset en el arranque, ahorrando mucho tiempo.

maximum_aspect_ratio¶

• Descripción: La relación de aspecto máxima de la imagen. Si la relación de aspecto de la imagen es mayor que este valor, se excluirá del entrenamiento.
• Nota: Si el número de imágenes que califican para exclusión es excesivo, esto podría desperdiciar tiempo en el arranque porque el trainer intentará escanearlas y hacer bucketing si faltan en las listas de buckets.

Nota: Una vez que las listas de aspecto y metadatos están construidas para tu dataset, usar skip_file_discovery="vae aspect metadata" evitará que el trainer escanee el dataset en el arranque, ahorrando mucho tiempo.

conditioning¶

• Valores: Arreglo de objetos de configuración de condicionamiento
• Descripción: Genera automáticamente datasets de condicionamiento a partir de tus imágenes fuente. Cada tipo de condicionamiento crea un dataset separado que puede usarse para entrenamiento de ControlNet u otras tareas de condicionamiento.
• Nota: Cuando se especifica, SimpleTuner creará automáticamente datasets de condicionamiento con IDs como {source_id}_conditioning_{type}

Cada objeto de condicionamiento puede contener: - type: El tipo de condicionamiento a generar (requerido) - params: Parámetros específicos del tipo (opcional) - captions: Estrategia de captions para el dataset generado (opcional) - Puede ser false (sin captions) - Una sola cadena (usada como instance prompt para todas las imágenes) - Un arreglo de cadenas (seleccionadas aleatoriamente para cada imagen) - Si se omite, se usan los captions del dataset de origen

Tipos de condicionamiento disponibles¶

superresolution¶

Genera versiones de baja calidad de las imágenes para entrenamiento de super-resolución:

{
  "type": "superresolution",
  "blur_radius": 2.5,
  "blur_type": "gaussian",
  "add_noise": true,
  "noise_level": 0.03,
  "jpeg_quality": 85,
  "downscale_factor": 2
}

sdr / logc3_sdr¶

Genera imágenes SDR/de referencia de condicionamiento para datasets de condicionamiento emparejados. El transform rec709 predeterminado normaliza y recorta entradas Rec.709 SDR ya existentes, igual que la ruta de acondicionamiento de referencia HDR IC-LoRA de LTX-2:

{
  "type": "sdr",
  "conditioning_type": "reference_strict",
  "transform": "rec709",
  "input_scale": 1.0,
  "exposure": 0.0,
  "captions": false
}

jpeg_artifacts¶

Crea artefactos de compresión JPEG para entrenamiento de eliminación de artefactos:

{
  "type": "jpeg_artifacts",
  "quality_mode": "range",
  "quality_range": [10, 30],
  "compression_rounds": 1,
  "enhance_blocks": false
}

depth / depth_midas¶

Genera mapas de profundidad usando modelos DPT:

{
  "type": "depth_midas",
  "model_type": "DPT"
}

random_masks / inpainting¶

Crea máscaras aleatorias para entrenamiento de inpainting:

{
  "type": "random_masks",
  "mask_types": ["rectangle", "circle", "brush", "irregular"],
  "min_coverage": 0.1,
  "max_coverage": 0.5,
  "output_mode": "mask"
}

canny / edges¶

Genera mapas de detección de bordes Canny:

{
  "type": "canny",
  "low_threshold": 100,
  "high_threshold": 200
}

Consulta la guía de ControlNet para más detalles sobre cómo usar estos datasets de condicionamiento.

Ejemplos¶

Dataset de video¶

Un dataset de video debería ser una carpeta de archivos de video (p. ej., mp4) y los métodos habituales de almacenamiento de captions.

[
  {
    "id": "disney-black-and-white",
    "type": "local",
    "dataset_type": "video",
    "crop": false,
    "resolution": 480,
    "minimum_image_size": 480,
    "maximum_image_size": 480,
    "target_downsample_size": 480,
    "resolution_type": "pixel_area",
    "cache_dir_vae": "cache/vae/ltxvideo/disney-black-and-white",
    "instance_data_dir": "datasets/disney-black-and-white",
    "disabled": false,
    "caption_strategy": "textfile",
    "metadata_backend": "discovery",
    "repeats": 0,
    "video": {
        "num_frames": 125,
        "min_frames": 125
    }
  },
  {
    "id": "text-embeds",
    "type": "local",
    "dataset_type": "text_embeds",
    "default": true,
    "cache_dir": "cache/text/ltxvideo",
    "disabled": false,
    "write_batch_size": 128
  }
]

• En la subsección video, tenemos las siguientes claves que podemos configurar:
• num_frames (opcional, int) es cuántos frames de datos entrenaremos.
  • A 25 fps, 125 frames son 5 segundos de video, salida estándar. Este debería ser tu objetivo.
• min_frames (opcional, int) determina la longitud mínima de un video que se considerará para entrenamiento.
  • Esto debería ser al menos igual a num_frames. No configurarlo garantiza que sea igual.
• max_frames (opcional, int) determina la longitud máxima de un video que se considerará para entrenamiento.
• is_i2v (opcional, bool) determina si el entrenamiento i2v se realizará en un dataset.
  • Esto se establece en True por defecto para LTX. Puedes desactivarlo, sin embargo.
• bucket_strategy (opcional, string) determina cómo se agrupan los videos en buckets:
  • aspect_ratio (default): Bucketing solo por relación de aspecto espacial (p. ej., 1.78, 0.75). Mismo comportamiento que los datasets de imagen.
  • resolution_frames: Bucketing por resolución y conteo de frames en formato WxH@F (p. ej., 1920x1080@125). Útil para entrenar en datasets con resoluciones y duraciones variables.
• frame_interval (opcional, int) cuando se usa bucket_strategy: "resolution_frames", los conteos de frames se redondean hacia abajo al múltiplo más cercano de este valor. Configúralo al factor de conteo de frames requerido por tu modelo (algunos modelos requieren que num_frames - 1 sea divisible por cierto valor).

Ajuste Automático de Conteo de Frames: SimpleTuner ajusta automáticamente los conteos de frames de video para satisfacer las restricciones específicas del modelo. Por ejemplo, LTX-2 requiere conteos de frames que satisfagan frames % 8 == 1 (p. ej., 49, 57, 65, 73, 81, etc.). Si tus videos tienen conteos de frames diferentes (p. ej., 119 frames), se recortan automáticamente al conteo de frames válido más cercano (p. ej., 113 frames). Los videos que se acortan a menos de min_frames después del ajuste se omiten con un mensaje de advertencia. Este ajuste automático evita errores de entrenamiento y no requiere ninguna configuración de tu parte.

Nota: Al usar bucket_strategy: "resolution_frames" con num_frames configurado, obtendrás un único bucket de frames y los videos más cortos que num_frames se descartarán. Quita num_frames si quieres múltiples buckets de frames con menos descartes.

Ejemplo de bucketing resolution_frames para datasets de video con resoluciones mezcladas:

{
  "id": "mixed-resolution-videos",
  "type": "local",
  "dataset_type": "video",
  "resolution": 720,
  "resolution_type": "pixel_area",
  "instance_data_dir": "datasets/videos",
  "video": {
      "bucket_strategy": "resolution_frames",
      "frame_interval": 25,
      "min_frames": 25,
      "max_frames": 250
  }
}

Esta configuración creará buckets como 1280x720@100, 1920x1080@125, 640x480@75, etc. Los videos se agrupan por su resolución de entrenamiento y conteo de frames (redondeado a los 25 frames más cercanos).

Configuración¶

    "minimum_image_size": 1024,
    "resolution": 1024,
    "resolution_type": "pixel"

Resultado¶

• Cualquier imagen con un borde más corto menor a 1024px se excluirá por completo del entrenamiento.
• Imágenes como 768x1024 o 1280x768 serían excluidas, pero 1760x1024 y 1024x1024 no.
• Ninguna imagen se escalará hacia arriba, porque minimum_image_size es igual a resolution

Configuración¶

    "minimum_image_size": 1024,
    "resolution": 1024,
    "resolution_type": "pixel_area" # different from the above configuration, which is 'pixel'

Resultado¶

• Si el área total de la imagen (ancho * alto) es menor que el área mínima (1024 * 1024), se excluirá del entrenamiento.
• Imágenes como 1280x960 no se excluirían porque (1280 * 960) es mayor que (1024 * 1024)
• Ninguna imagen se escalará hacia arriba, porque minimum_image_size es igual a resolution

Configuración¶

    "minimum_image_size": 0, # or completely unset, not present in the config
    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": false

Resultado¶

• Las imágenes se redimensionarán para que su borde más corto sea 1024px manteniendo la relación de aspecto
• No se excluirán imágenes por tamaño
• Las imágenes pequeñas se escalarán hacia arriba usando métodos ingenuos de PIL.resize que no se ven bien
• Se recomienda evitar el escalado hacia arriba salvo que lo hagas manualmente con un upscaler de tu elección antes de empezar el entrenamiento

maximum_image_size y target_downsample_size¶

Las imágenes no se redimensionan antes del recorte a menos que maximum_image_size y target_downsample_size estén configurados. En otras palabras, una imagen de 4096x4096 se recortará directamente a un objetivo de 1024x1024, lo cual puede ser indeseable.

• maximum_image_size especifica el umbral a partir del cual comenzará el redimensionado. Reducirá imágenes antes del recorte si son mayores que esto.
• target_downsample_size especifica qué tan grande será la imagen después del reescalado y antes del recorte.

Ejemplos¶

Configuración¶

    "resolution_type": "pixel_area",
    "resolution": 1024,
    "maximum_image_size": 1536,
    "target_downsample_size": 1280,
    "crop": true,
    "crop_aspect": "square"

Resultado¶

• Cualquier imagen con un área de píxeles mayor que (1536 * 1536) se redimensionará para que su área de píxeles sea aproximadamente (1280 * 1280) manteniendo su relación de aspecto original
• El tamaño final de la imagen se recortará aleatoriamente a un área de píxeles de (1024 * 1024)
• Útil para entrenar con, p. ej., datasets de 20 megapíxeles que necesitan reducirse de forma significativa antes del recorte para evitar una gran pérdida de contexto en la escena (como recortar una foto de una persona y quedarte solo con una pared de azulejos o una sección borrosa del fondo)

max_upscale_threshold¶

Por defecto, SimpleTuner escalará hacia arriba imágenes pequeñas para cumplir la resolución objetivo, lo que puede degradar la calidad. La opción max_upscale_threshold permite limitar este comportamiento de escalado.

• Default: null (permite escalado ilimitado)
• Cuando se configura: Filtra buckets de aspecto que requerirían escalado más allá del umbral especificado
• Rango de valores: Entre 0 y 1 (p. ej., 0.2 = permitir hasta 20% de escalado)
• Aplica a: Selección de buckets de aspecto cuando crop_aspect se establece en closest o random

Ejemplos¶

Configuración¶

    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": true,
    "crop_aspect": "random",
    "crop_aspect_buckets": [1.0, 0.5, 2.0],
    "max_upscale_threshold": null

Resultado¶

• Todos los buckets de aspecto están disponibles para selección
• Una imagen de 256x256 puede escalarse a 1024x1024 (4x de escala)
• Puede degradar la calidad en imágenes muy pequeñas

Configuración¶

    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": true,
    "crop_aspect": "random",
    "crop_aspect_buckets": [1.0, 0.5, 2.0],
    "max_upscale_threshold": 0.2

Resultado¶

• Solo están disponibles buckets de aspecto que requieran ≤20% de escalado
• Una imagen de 256x256 intentando escalar a 1024x1024 (4x = 300% de escalado) no tendría buckets disponibles
• Una imagen de 850x850 puede usar todos los buckets ya que 1024/850 ≈ 1.2 (20% de escalado)
• Ayuda a mantener la calidad de entrenamiento excluyendo imágenes mal escaladas

prepend_instance_prompt¶

• Cuando está habilitado, todos los captions incluirán el valor instance_prompt al inicio.

only_instance_prompt¶

• Además de prepend_instance_prompt, reemplaza todos los captions del dataset con una sola frase o palabra trigger.

timestep_sampling_offset¶

• Desplaza el muestreo de timesteps de flow-matching de este dataset hacia niveles de ruido más altos o más bajos. Se aplica al programa por defecto logit-normal (sigmoid).
• Un valor negativo sesga el muestreo hacia timesteps de menor ruido, centrando el entrenamiento en el detalle fino (por ejemplo, primeros planos o datos con mucha textura). Un valor positivo sesga hacia timesteps de mayor ruido, centrándose en la estructura general (por ejemplo, cuerpo entero o datos centrados en la composición).
• El valor se suma a la muestra normal previa al sigmoid; las magnitudes útiles suelen estar entre -1.0 y 1.0. Por defecto es 0.0 (sin sesgo, idéntico al comportamiento original).
• Como cada lote (batch) proviene de un único dataset, agrupa las imágenes por granularidad semántica en datasets separados y define un timestep_sampling_offset para cada uno.

repeats¶

• Especifica cuántas veces se ven todas las muestras del dataset durante una época. Útil para dar más impacto a datasets pequeños o maximizar el uso de objetos de caché VAE.
• Si tienes un dataset de 1000 imágenes frente a otro de 100 imágenes, probablemente quieras dar al dataset menor un repeats de 9 o más para llevarlo a 1000 imágenes muestreadas en total.

ℹ️ Este valor se comporta distinto a la misma opción en los scripts de Kohya, donde un valor de 1 significa sin repeats. Para SimpleTuner, un valor de 0 significa sin repeats. Resta uno de tu valor de configuración de Kohya para obtener el equivalente en SimpleTuner, de ahí que un valor de 9 resulte del cálculo (dataset_length + repeats * dataset_length).

Entrenamiento multi-GPU y tamaño del dataset¶

Cuando entrenas con múltiples GPUs, tu dataset debe ser lo bastante grande como para acomodar el tamaño efectivo de batch, calculado como:

effective_batch_size = train_batch_size del dataset × num_gpus × gradient_accumulation_steps

Este es un requisito de dimensionamiento de buckets por dataset. No significa que todos los datasets configurados se seleccionen en una ventana de acumulación ni describe el número exacto de muestras de una actualización del optimizador con tamaños mixtos.

Por ejemplo, con 4 GPUs, train_batch_size=4 en el dataset y gradient_accumulation_steps=1, necesitas al menos 16 muestras (después de aplicar repeats) en cada bucket de aspecto.

Importante: SimpleTuner lanzará un error si tu configuración de dataset produce cero batches utilizables. El mensaje de error mostrará: - Valores actuales de configuración (batch size, número de GPUs, repeats) - Qué buckets de aspecto tienen muestras insuficientes - El mínimo exacto de repeats requerido para cada bucket - Soluciones sugeridas

Sobresuscripción automática del dataset¶

Para ajustar automáticamente repeats cuando tu dataset es más pequeño que el tamaño efectivo de batch, usa el flag --allow_dataset_oversubscription (documentado en OPTIONS.md).

Cuando está habilitado, SimpleTuner: - Calcula los repeats mínimos necesarios para cada bucket de aspecto insuficiente - Rellena solo esos buckets para cumplir el tamaño efectivo de batch - Registra una advertencia mostrando el ajuste - Respeta valores de repeats configurados manualmente - si configuras repeats explícitamente en tu configuración de dataset, se omitirá el ajuste automático

Esto es especialmente útil cuando: - Entrenas datasets pequeños (< 100 imágenes) - Usas un alto número de GPUs con datasets pequeños - Experimentas con distintos tamaños de batch sin reconfigurar datasets

Escenario de ejemplo: - Dataset: 25 imágenes - Configuración: 8 GPUs, train_batch_size=4, gradient_accumulation_steps=1 - Tamaño efectivo de batch: se requieren 32 muestras - Sin sobresuscripción: se lanza un error - Con --allow_dataset_oversubscription: repeats ajustado automáticamente a 1 (25 × 2 = 50 muestras)

max_num_samples¶

• Descripción: Limita el dataset a un número máximo de muestras. Cuando se establece, se selecciona un subconjunto aleatorio determinista del tamaño especificado del dataset completo.
• Caso de uso: Útil para grandes datasets de regularización donde deseas usar solo una parte de los datos para evitar dominar conjuntos de entrenamiento más pequeños.
• Selección determinista: La selección aleatoria usa el id del dataset como semilla, asegurando que el mismo subconjunto sea seleccionado entre sesiones de entrenamiento para reproducibilidad.
• Por defecto: null (sin límite, se usan todas las muestras)

Ejemplo¶

{
  "id": "regularization-data",
  "max_num_samples": 1000,
  ...
}

Esto seleccionará de forma determinista 1000 muestras del dataset, con la misma selección utilizada cada vez que se ejecute el entrenamiento.

start_epoch / start_step¶

• Programa cuándo un dataset empieza a muestrear.
• start_epoch (default: 1) controla por número de época; start_step (default: 0) controla por paso de optimizador (después de la acumulación de gradientes). Ambas condiciones deben cumplirse antes de extraer muestras.
• Al menos un dataset debe tener start_epoch<=1 y start_step<=1; de lo contrario, el entrenamiento fallará porque no hay datos disponibles al inicio.
• Los datasets que nunca cumplen su condición de inicio (por ejemplo, start_epoch más allá de --num_train_epochs) se omitirán y se anotarán en la model card.
• Las estimaciones de pasos en la barra de progreso son aproximadas cuando los datasets programados se activan a mitad de ejecución porque la longitud de la época puede aumentar cuando nuevos datos entran en línea.

end_epoch / end_step¶

• Programa cuándo un dataset deja de muestrear (complementando start_epoch/start_step).
• end_epoch (default: null = sin límite) detiene el muestreo después de esta época; end_step (default: null = sin límite) detiene el muestreo después de este paso de optimizador.
• Cualquiera de las condiciones que termine detendrá el dataset; funcionan de forma independiente.
• Útil para flujos de trabajo de aprendizaje curricular donde deseas:
• Entrenar con datos de baja resolución primero, luego cambiar a datos de mayor resolución.
• Eliminar gradualmente los datos de regularización después de cierto punto.
• Crear entrenamiento multi-etapa dentro de un solo archivo de configuración.

Ejemplo: Aprendizaje Curricular

[
  {
    "id": "lowres-512",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "/data/512",
    "end_step": 300
  },
  {
    "id": "highres-1024",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "/data/1024",
    "start_step": 300
  }
]

En este ejemplo, el dataset de 512px se usa para los pasos 1-300, luego el dataset de 1024px toma el control desde el paso 300 en adelante.

is_regularisation_data¶

• También puede escribirse is_regularization_data
• Habilita entrenamiento parent-teacher para que el objetivo de predicción prefiera el resultado del modelo base congelado para un dataset dado.
• La mayoría de familias de difusión requieren actualmente adaptadores LyCORIS.
• El entrenamiento language_model de MiniMax Music 3 admite lotes de regularización con LoRA PEFT estándar, incluida la selección de rutas XM. Su objetivo es la distribución de siguiente token del planner base congelado.

delete_unwanted_images¶

• Valores: true | false
• Descripción: Cuando está habilitado, las imágenes que fallen los filtros de tamaño o relación de aspecto (p. ej., por debajo de minimum_image_size o fuera de minimum_aspect_ratio/maximum_aspect_ratio) se eliminan permanentemente del directorio del dataset.
• Advertencia: Esto es destructivo y no se puede deshacer. Úsalo con cuidado.
• Default: Usa el argumento --delete_unwanted_images del trainer (default: false).

delete_problematic_images¶

• Valores: true | false
• Descripción: Cuando está habilitado, las imágenes que fallen durante la codificación VAE (archivos corruptos, formatos no compatibles, etc.) se eliminan permanentemente del directorio del dataset.
• Advertencia: Esto es destructivo y no se puede deshacer. Úsalo con cuidado.
• Default: Usa el argumento --delete_problematic_images del trainer (default: false).

delete_nsfw_images¶

• Valores: true | false
• Descripción: Cuando --enable_nsfw_check está habilitado, las muestras rechazadas por el clasificador NSFW se eliminan de este backend si el backend admite eliminación.
• Advertencia: Esto es destructivo y no se puede deshacer. Los datasets de Hugging Face son de solo lectura y solo se eliminan de los metadatos de la ejecución actual.
• Default: Usa el argumento --delete_nsfw_images del trainer (default: false).

Comprobaciones del clasificador NSFW durante el caché VAE¶

SimpleTuner puede escanear muestras de entrenamiento con clasificadores de imágenes de Hugging Face Transformers durante el preprocesamiento del caché VAE configurando --enable_nsfw_check=true. El escaneo ocurre después del bucket discovery y antes de la codificación VAE, por lo que las muestras rechazadas se eliminan de los buckets de metadatos actuales antes de escribir latents.

Para notas de privacidad, responsabilidad y contexto legal, consulta NSFW.es.md.

El escaneo solo se aplica a muestras sin caché que el caché VAE está a punto de procesar. Las entradas de caché VAE existentes se consideran confiables, y skip_file_discovery=vae omite la aplicación NSFW porque el trainer asume que el dataset ya fue preparado según la política del usuario. Los datasets de evaluación no se escanean.

Configuración de clasificadores: - --nsfw_check_models acepta una lista CSV de modelos estándar de clasificación de imágenes de Hugging Face Transformers. Adjunta umbrales por modelo con model/repo:threshold=0.5. - El valor predeterminado es Falconsai/nsfw_image_detection:threshold=0.5,AdamCodd/vit-base-nsfw-detector:threshold=0.5. - No se habilita trust_remote_code, y no se admiten clasificadores que requieran timm o código de modelo personalizado. - --nsfw_check_min_votes controla cuántos modelos configurados deben devolver NSFW para rechazar un frame.

Controles de alcance: - --nsfw_check_backend_types acepta valores type de backend como all, local, huggingface, csv o aws. - --nsfw_check_sample_types acepta valores dataset_type. El valor predeterminado es image,conditioning; agrega video para escanear datasets de video. - --delete_nsfw_images=true elimina muestras rechazadas de backends mutables. Cuando está deshabilitado, solo se eliminan de los metadatos de la ejecución actual.

Muestras de video y multi-frame: - --nsfw_check_video_frame_count controla cuántos frames se comprueban. - --nsfw_check_video_frame_selection puede ser uniform, first o middle. - --nsfw_check_video_min_flagged_frames controla cuántos frames comprobados deben rechazarse antes de rechazar toda la muestra.

Cada proceso de caché VAE escribe un reporte nsfw_classifier_report_rank*.json en el directorio de caché VAE cuando se escanean muestras. Los reportes incluyen umbrales de modelos, conteos agregados de veredictos, rutas de muestras rechazadas y conteos de eliminación.

La eliminación por backend puede habilitarse en multidatabackend.json:

{
  "id": "train",
  "type": "local",
  "dataset_type": "image",
  "instance_data_dir": "/data/training/images",
  "delete_nsfw_images": true
}

Ver Estadísticas de Filtrado¶

Cuando SimpleTuner procesa tu dataset, rastrea cuántos archivos fueron filtrados y por qué. Estas estadísticas se almacenan en el archivo de caché del dataset (aspect_ratio_bucket_indices_*.json) y pueden verse en la WebUI.

Estadísticas rastreadas: - total_processed: Número de archivos procesados - too_small: Archivos filtrados por estar debajo de minimum_image_size - too_long: Archivos filtrados por exceder límites de duración (audio/video) - metadata_missing: Archivos omitidos por falta de metadatos - not_found: Archivos que no se pudieron localizar - already_exists: Archivos ya en caché (no reprocesados) - nsfw: Archivos rechazados por el clasificador NSFW durante el preprocesamiento del caché VAE - other: Archivos filtrados por otras razones

Ver en la WebUI:

Al navegar por datasets en el explorador de archivos de la WebUI, seleccionar un directorio con un dataset existente mostrará estadísticas de filtrado si están disponibles. Esto ayuda a diagnosticar por qué tu dataset puede tener menos muestras utilizables de lo esperado.

Solución de problemas de archivos filtrados:

Si muchos archivos están siendo filtrados como too_small: 1. Verifica tu configuración de minimum_image_size — debe coincidir con resolution y resolution_type 2. Para resolution_type=pixel, minimum_image_size es la longitud mínima del borde más corto 3. Para resolution_type=area o pixel_area, minimum_image_size es el área total mínima

Consulta la sección Solución de Problemas a continuación para más detalles.

slider_strength¶

• Valores: Cualquier valor float (positivo, negativo o cero)
• Descripción: Marca un dataset para entrenamiento de slider LoRA, que aprende "opuestos" contrastivos para crear adaptadores de conceptos controlables.
• Valores positivos (p. ej., 0.5): "Más del concepto" — ojos más brillantes, sonrisa más marcada, etc.
• Valores negativos (p. ej., -0.5): "Menos del concepto" — ojos más apagados, expresión neutra, etc.
• Cero u omitido: Ejemplos neutrales que no empujan el concepto en ninguna dirección.
• Nota: Cuando los datasets tienen valores slider_strength, SimpleTuner rota los batches en un ciclo fijo: positivo → negativo → neutral. Dentro de cada grupo, las probabilidades estándar del backend siguen aplicando.
• Ver también: SLIDER_LORA.md para una guía completa sobre cómo configurar entrenamiento de slider LoRA.

vae_cache_clear_each_epoch¶

• Cuando está habilitado, todos los objetos de caché VAE se eliminan del filesystem al final de cada ciclo de repeats del dataset. Esto puede ser intensivo en recursos para datasets grandes, pero combinado con crop_style=random y/o crop_aspect=random querrás tenerlo habilitado para asegurar que muestreas un rango completo de recortes de cada imagen.
• De hecho, esta opción está habilitada por defecto cuando se usa bucketing aleatorio o recortes aleatorios.

vae_cache_ondemand¶

• Valores: true | false
• Descripción: Cuando se activa en un dataset, los latentes VAE que falten se codifican durante el entrenamiento y se escriben en la caché VAE de ese dataset en lugar de precalcularse al inicio.
• Nota: La opción global --vae_cache_ondemand sigue aplicándose a todos los datasets. Usa esta opción de dataset cuando la opción global sea false y solo ciertos datasets deban codificar latentes VAE bajo demanda.

vae_cache_disable¶

• Valores: true | false
• Descripción: Cuando está habilitado en un dataset, ese dataset codifica latentes VAE bajo demanda y no escribe en disco los latentes generados nuevos. Esto es útil para datasets grandes donde el espacio en disco es una preocupación o escribir no es práctico.
• Nota: La opción global --vae_cache_disable sigue aplicándose a todos los datasets. Usa esta opción de dataset para desactivar la escritura de caché VAE solo en datasets seleccionados cuando la opción global es falsa. La forma eliminada disable_vae_cache se rechaza; usa vae_cache_disable.

Elegir una estrategia de caché VAE¶

vae_cache_ondemand intercambia tiempo de inicio por trabajo durante el entrenamiento; no es una optimización de VRAM. Elige la estrategia por dataset según la reutilización esperada de la caché y si el VAE puede permanecer disponible durante el entrenamiento:

1. Dataset extremadamente grande y reutilizable: Configura vae_cache_ondemand=true cuando una pasada completa de precaché retrasaría demasiado el entrenamiento. El entrenamiento comienza sin esperar a todas las imágenes y cada latente que falta se escribe en la caché para reutilizarlo en visitas posteriores.
2. Dataset de resolución muy alta: Deja vae_cache_ondemand=false (y mantén falsa la opción global) cuando la codificación VAE podría causar un OOM con el modelo de entrenamiento cargado. El precaché de inicio predeterminado permite descargar el VAE antes del entrenamiento. Ni el modo bajo demanda ni vae_cache_disable resuelven esta limitación de memoria, porque ambos requieren codificación VAE durante el entrenamiento. El tiling o slicing del VAE puede reducir el pico de memoria durante el precaché inicial.
3. Dataset a escala web con poca reutilización esperada: Configura vae_cache_disable=true cuando el dataset contiene millones o miles de millones de imágenes y es poco probable que la ejecución prevista se acerque a una época. Las imágenes muestreadas se siguen codificando bajo demanda, pero se evitan las escrituras de caché y el crecimiento del almacenamiento cuando la mayoría de los latentes no volverían a leerse. Requiere la misma memoria del VAE durante el entrenamiento que la caché bajo demanda.

skip_file_discovery¶

• Probablemente no quieras configurar esto nunca; solo es útil para datasets muy grandes.
• Este parámetro acepta una lista separada por comas o espacios, p. ej., vae metadata aspect text para omitir el descubrimiento de archivos en una o más etapas de la configuración del loader.
• Es equivalente a la opción de línea de comandos --skip_file_discovery
• Es útil si tienes datasets que no necesitas que el trainer escanee en cada arranque, p. ej., sus latentes/embeds ya están completamente cacheados. Esto permite un inicio más rápido y reanudar el entrenamiento.

preserve_data_backend_cache¶

• Probablemente no quieras configurar esto nunca; solo es útil para datasets muy grandes en AWS.
• Al igual que skip_file_discovery, esta opción puede configurarse para evitar escaneos del filesystem innecesarios, largos y costosos al inicio.
• Toma un valor booleano, y si se establece en true, el archivo de caché de lista de filesystem generado no se eliminará al iniciar.
• Es útil para sistemas de almacenamiento muy grandes y lentos como S3 o discos duros locales SMR con tiempos de respuesta extremadamente lentos.
• Además, en S3, el listado del backend puede acumular costos y debería evitarse.

⚠️ Desafortunadamente, esto no puede configurarse si los datos se están cambiando activamente. El trainer no verá ningún dato nuevo que se agregue al conjunto; tendrá que hacer otro escaneo completo.

hash_filenames¶

• Los nombres de archivo de las entradas de caché VAE siempre se hashean. Esto no es configurable por el usuario y garantiza que datasets con nombres de archivo muy largos puedan usarse sin problemas de longitud de ruta. Cualquier configuración hash_filenames en tu configuración será ignorada.

Grounding (Anotaciones Espaciales)¶

El pipeline de grounding permite anotaciones de bounding box y mascara por entidad para el grounding espacial durante el entrenamiento. Esto es util para prevenir el sangrado de sujetos (subject bleeding) durante el fine-tuning con multiples sujetos.

Habilitando el grounding¶

Agrega un bloque grounding a cualquier dataset de imagen o video:

{
  "id": "my-dataset",
  "type": "local",
  "dataset_type": "image",
  "instance_data_dir": "/path/to/images",
  "grounding": {
    "enabled": true
  }
}

Tambien debes establecer --max_grounding_entities a un valor mayor que 0 (por ejemplo, 8) para habilitar el pipeline de grounding.

Auto-deteccion de bounding boxes¶

Si no tienes anotaciones .bbox preexistentes, puedes dejar que SimpleTuner las genere automaticamente usando Florence-2. Agrega un bloque auto_detect dentro de la configuracion grounding:

{
    "id": "my-images",
    "type": "local",
    "dataset_type": "image",
    "instance_data_dir": "/data/images",
    "grounding": {
        "enabled": true,
        "auto_detect": {
            "enabled": true,
            "model": "florence-community/Florence-2-large",
            "labels": ["person", "dog", "cat"],
            "batch_size": 4
        }
    }
}

La auto-deteccion se ejecuta una vez durante la configuracion del dataset. Las imagenes que ya tienen un archivo sidecar .bbox se omiten, por lo que puedes reanudar de forma segura despues de una interrupcion. El modelo se carga en el dispositivo del acelerador y se libera inmediatamente despues de completar la deteccion.

Nota: La auto-deteccion solo soporta backends type: "local".

Archivos sidecar .bbox¶

Coloca un archivo .bbox junto a cada imagen con el mismo nombre base.

El archivo .bbox soporta tres formatos: array JSON, JSON lines, formato txt YOLO.

Las coordenadas del bounding box estan normalizadas a [0, 1] en formato XYXY. El formato YOLO usa XYWH basado en el centro y se convierte automaticamente. El campo mask es opcional.

Columna bbox Parquet / HuggingFace¶

Para datasets parquet o HuggingFace, especifica un bbox_column en la configuracion del backend.

Filtrado de muestras¶

filter_func¶

filter_func puede configurarse en el nivel superior de cualquier backend de dataset para omitir muestras antes de construir buckets de metadatos y cachés VAE. Los backends de Hugging Face siguen aceptando la ubicación antigua huggingface.filter_func, pero el valor superior tiene prioridad si ambos existen.

Filtros admitidos:

• collection: lista permitida de coincidencia exacta para el campo collection de una fila.
• quality_thresholds: valores numéricos mínimos dentro de quality_column (por defecto, quality_assessment).
• min_width / min_height: dimensiones mínimas de fila cuando existen campos de ancho y alto.
• path_include / path_exclude: filtrado por nombre de archivo/ruta para datasets local, AWS, CSV, Hugging Face, parquet y Webshart. path_include es lista permitida y path_exclude lista bloqueada. Las exclusiones ganan si ambas coinciden.
• path_match: modo de coincidencia de rutas. auto (predeterminado para claves planas) usa subcadenas para texto normal, glob para * y ?, y regex para patrones con prefijo re:. También se puede usar contains, glob, regex o exact.

{
  "filter_func": {
    "path_include": ["clothing", "notable", "*/curated/*.jpg"],
    "path_exclude": ["watermark", "bad"],
    "path_match": "auto"
  }
}

La forma antigua anidada filter_func.path.include / exclude / mode sigue aceptándose para configs existentes, pero las nuevas configs deben usar las claves planas anteriores.

Filtrado de captions¶

caption_filter_list¶

• Solo para datasets de text embeds. Puede ser una lista JSON, una ruta a un archivo txt o una ruta a un documento JSON. Las cadenas de filtro pueden ser términos simples para eliminar de todos los captions, o pueden ser expresiones regulares. Además, se pueden usar entradas estilo sed s/buscar/reemplazar/ para reemplazar cadenas en el caption en lugar de simplemente eliminarlas.

Ejemplo de lista de filtros¶

Un ejemplo completo se encuentra aquí. Contiene cadenas comunes repetitivas y negativas que podrían devolver BLIP (variedad común), LLaVA y CogVLM.

Este es un ejemplo abreviado, que se explicará a continuación:

arafed
this .* has a
^this is the beginning of the string
s/this/will be found and replaced/

En orden, las líneas se comportan así:

• arafed (con un espacio al final) se eliminará de cualquier caption en el que se encuentre. Incluir un espacio al final hace que el caption se vea mejor, ya que no quedarán dobles espacios. Esto es innecesario, pero se ve bien.
• this .* has a es una expresión regular que eliminará cualquier cosa que contenga "this ... has a", incluyendo cualquier texto entre esas dos cadenas; .* es una expresión regular que significa "todo lo que encontremos" hasta que encuentre la cadena "has a", momento en el que deja de coincidir.
• ^this is the beginning of the string eliminará la frase "this is the beginning of the string" de cualquier caption, pero solo cuando aparezca al inicio del caption.
• s/this/will be found and replaced/ hará que la primera instancia del término "this" en cualquier caption sea reemplazada por "will be found and replaced".

❗Usa regex 101 para ayuda al depurar y probar expresiones regulares.

Técnicas avanzadas¶

Configuración avanzada de ejemplo¶

[
  {
    "id": "something-special-to-remember-by",
    "type": "local",
    "instance_data_dir": "/path/to/data/tree",
    "crop": false,
    "crop_style": "random|center|corner|face",
    "crop_aspect": "square|preserve|closest|random",
    "crop_aspect_buckets": [0.33, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75],
    "resolution": 1.0,
    "resolution_type": "area|pixel",
    "minimum_image_size": 1.0,
    "prepend_instance_prompt": false,
    "instance_prompt": "something to label every image",
    "only_instance_prompt": false,
    "caption_strategy": "filename|instanceprompt|parquet|textfile|webshart",
    "disable_multiline_split": false,
    "cache_dir_vae": "/path/to/vaecache",
    "vae_cache_clear_each_epoch": true,
    "probability": 1.0,
    "repeats": 0,
    "start_epoch": 1,
    "start_step": 0,
    "text_embeds": "alt-embed-cache",
    "image_embeds": "vae-embeds-example",
    "conditioning_image_embeds": "conditioning-embeds-example"
  },
  {
    "id": "another-special-name-for-another-backend",
    "type": "aws",
    "aws_bucket_name": "something-yummy",
    "aws_region_name": null,
    "aws_endpoint_url": "https://foo.bar/",
    "aws_access_key_id": "wpz-764e9734523434",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_data_prefix": "",
    "cache_dir_vae": "s3prefix/for/vaecache",
    "vae_cache_clear_each_epoch": true,
    "repeats": 0
  },
  {
      "id": "vae-embeds-example",
      "type": "local",
      "dataset_type": "image_embeds",
      "disabled": false,
  },
  {
      "id": "conditioning-embeds-example",
      "type": "local",
      "dataset_type": "conditioning_image_embeds",
      "disabled": false
  },
  {
    "id": "an example backend for text embeds.",
    "dataset_type": "text_embeds",
    "default": true,
    "type": "aws",
    "aws_bucket_name": "textembeds-something-yummy",
    "aws_region_name": null,
    "aws_endpoint_url": "https://foo.bar/",
    "aws_access_key_id": "wpz-764e9734523434",
    "aws_secret_access_key": "xyz-sdajkhfhakhfjd",
    "aws_data_prefix": "",
    "cache_dir": ""
  },
  {
    "id": "alt-embed-cache",
    "dataset_type": "text_embeds",
    "default": false,
    "type": "local",
    "cache_dir": "/path/to/textembed_cache"
  }
]

Entrenar directamente desde una lista de URLs en CSV¶

Nota: Tu CSV debe contener los captions de tus imágenes.

⚠️ Esta es una función avanzada y experimental, y puedes encontrarte con problemas. Si ocurre, por favor abre un issue.

En lugar de descargar manualmente tus datos desde una lista de URLs, quizá quieras conectarlos directamente al trainer.

Nota: Siempre es mejor descargar manualmente los datos de imagen. Otra estrategia para ahorrar espacio local en disco podría ser intentar usar almacenamiento en la nube con cachés de encoder locales.

Ventajas¶

• No es necesario descargar los datos directamente
• Puedes usar el toolkit de captions de SimpleTuner para captionar directamente la lista de URLs
• Ahorra espacio en disco, ya que solo se almacenan los image embeds (si aplica) y text embeds

Desventajas¶

• Requiere un escaneo de buckets de aspecto costoso y potencialmente lento donde cada imagen se descarga y se recolectan sus metadatos
• Las imágenes descargadas se cachean en disco, lo que puede crecer muchísimo. Esto es un área de mejora, ya que la gestión de caché en esta versión es muy básica, write-only/delete-never
• Si tu dataset tiene muchas URLs inválidas, esto puede desperdiciar tiempo al reanudar ya que, actualmente, las muestras malas nunca se eliminan de la lista de URLs
• Sugerencia: Ejecuta una tarea de validación de URLs previamente y elimina cualquier muestra inválida.

Configuración¶

Claves requeridas:

• type: "csv"
• csv_caption_column
• csv_cache_dir
• caption_strategy: "csv"

[
    {
        "id": "csvtest",
        "type": "csv",
        "csv_caption_column": "caption",
        "csv_file": "/Volumes/ml/dataset/test_list.csv",
        "csv_cache_dir": "/Volumes/ml/cache/csv/test",
        "cache_dir_vae": "/Volumes/ml/cache/vae/sdxl",
        "caption_strategy": "csv",
        "image_embeds": "image-embeds",
        "crop": true,
        "crop_aspect": "square",
        "crop_style": "center",
        "resolution": 1024,
        "maximum_image_size": 1024,
        "target_downsample_size": 1024,
        "resolution_type": "pixel",
        "minimum_image_size": 0,
        "disabled": false,
        "skip_file_discovery": "",
        "preserve_data_backend_cache": false
    },
    {
      "id": "image-embeds",
      "type": "local"
    },
    {
        "id": "text-embeds",
        "type": "local",
        "dataset_type": "text_embeds",
        "default": true,
        "cache_dir": "/Volumes/ml/cache/text/sdxl",
        "disabled": false,
        "preserve_data_backend_cache": false,
        "skip_file_discovery": "",
        "write_batch_size": 128
    }
]

Estrategia de captions parquet / datasets JSON Lines¶

⚠️ Esta es una función avanzada y no será necesaria para la mayoría de usuarios.

Cuando entrenas un modelo con un dataset muy grande que supera cientos de miles o millones de imágenes, lo más rápido es almacenar tus metadatos dentro de una base de datos parquet en lugar de archivos txt, especialmente cuando tus datos de entrenamiento están en un bucket S3.

Usar la estrategia de captions parquet te permite nombrar todos tus archivos por su valor id, y cambiar su columna de caption mediante un valor de configuración en lugar de actualizar muchos archivos de texto o renombrar archivos para actualizar sus captions.

Aquí tienes un ejemplo de configuración del dataloader que usa los captions y datos del dataset photo-concept-bucket:

{
  "id": "photo-concept-bucket",
  "type": "local",
  "instance_data_dir": "/models/training/datasets/photo-concept-bucket-downloads",
  "caption_strategy": "parquet",
  "metadata_backend": "parquet",
  "parquet": {
    "path": "photo-concept-bucket.parquet",
    "filename_column": "id",
    "caption_column": "cogvlm_caption",
    "fallback_caption_column": "tags",
    "width_column": "width",
    "height_column": "height",
    "identifier_includes_extension": false
  },
  "resolution": 1.0,
  "minimum_image_size": 0.75,
  "maximum_image_size": 2.0,
  "target_downsample_size": 1.5,
  "prepend_instance_prompt": false,
  "instance_prompt": null,
  "only_instance_prompt": false,
  "disable": false,
  "cache_dir_vae": "/models/training/vae_cache/photo-concept-bucket",
  "probability": 1.0,
  "skip_file_discovery": "",
  "preserve_data_backend_cache": false,
  "vae_cache_clear_each_epoch": true,
  "repeats": 1,
  "crop": true,
  "crop_aspect": "closest",
  "crop_style": "random",
  "crop_aspect_buckets": [1.0, 0.75, 1.23],
  "resolution_type": "area"
}

En esta configuración:

• caption_strategy se configura como parquet.
• metadata_backend se configura como parquet.
• Se debe definir una nueva sección, parquet:
• path es la ruta al archivo parquet o JSONL.
• filename_column es el nombre de la columna en la tabla que contiene los nombres de archivo. En este caso, usamos la columna numérica id (recomendado).
• caption_column es el nombre de la columna en la tabla que contiene los captions. En este caso, usamos la columna cogvlm_caption. Para datasets LAION, sería el campo TEXT.
• width_column y height_column pueden ser una columna que contenga cadenas, int o incluso un tipo Series de una sola entrada, midiendo las dimensiones reales de la imagen. Esto mejora notablemente el tiempo de preparación del dataset, ya que no necesitamos acceder a las imágenes reales para descubrir esta información.
• fallback_caption_column es un nombre opcional de una columna en la tabla que contiene captions de respaldo. Se usan si el campo de caption principal está vacío. En este caso, usamos la columna tags.
• identifier_includes_extension debe establecerse en true cuando tu columna de nombre de archivo contiene la extensión de imagen. De lo contrario, se asumirá la extensión .png. Se recomienda incluir extensiones de archivo en tu columna de nombres.

⚠️ La capacidad de soporte de parquet se limita a leer captions. Debes poblar por separado una fuente de datos con tus muestras de imagen usando "{id}.png" como nombre de archivo. Consulta scripts en el directorio scripts/toolkit/datasets para ideas.

Como en otras configuraciones de dataloader:

• prepend_instance_prompt y instance_prompt se comportan como de costumbre.
• Actualizar el caption de una muestra entre ejecuciones de entrenamiento cacheará el nuevo embed, pero no eliminará la unidad vieja (huérfana).
• Cuando una imagen no existe en un dataset, su nombre de archivo se usará como caption y se emitirá un error.

Caché local con dataset en la nube¶

Para maximizar el uso del costoso almacenamiento local NVMe, quizá quieras almacenar solo los archivos de imagen (png, jpg) en un bucket S3 y usar el almacenamiento local para cachear tus feature maps extraídos del/los encoder(es) de texto y del VAE (si aplica).

En este ejemplo de configuración:

• Los datos de imagen se almacenan en un bucket compatible con S3
• Los datos del VAE se almacenan en /local/path/to/cache/vae
• Los text embeds se almacenan en /local/path/to/cache/textencoder

⚠️ Recuerda configurar las otras opciones del dataset, como resolution y crop

[
    {
        "id": "data",
        "type": "aws",
        "aws_bucket_name": "text-vae-embeds",
        "aws_endpoint_url": "https://storage.provider.example",
        "aws_access_key_id": "exampleAccessKey",
        "aws_secret_access_key": "exampleSecretKey",
        "aws_region_name": null,
        "cache_dir_vae": "/local/path/to/cache/vae/",
        "caption_strategy": "parquet",
        "metadata_backend": "parquet",
        "parquet": {
            "path": "train.parquet",
            "caption_column": "caption",
            "filename_column": "filename",
            "width_column": "width",
            "height_column": "height",
            "identifier_includes_extension": true
        },
        "preserve_data_backend_cache": false,
        "image_embeds": "vae-embed-storage"
    },
    {
        "id": "vae-embed-storage",
        "type": "local",
        "dataset_type": "image_embeds"
    },
    {
        "id": "text-embed-storage",
        "type": "local",
        "dataset_type": "text_embeds",
        "default": true,
        "cache_dir": "/local/path/to/cache/textencoder/",
        "write_batch_size": 128
    }
]

Nota: El dataset image_embeds no tiene opciones para configurar rutas de datos. Esas se configuran mediante cache_dir_vae en el backend de imagen.

Soporte de Hugging Face Datasets¶

SimpleTuner ahora soporta cargar datasets directamente desde Hugging Face Hub sin descargar todo el dataset localmente. Esta función experimental es ideal para:

• Datasets a gran escala alojados en Hugging Face
• Datasets con metadatos y evaluaciones de calidad integrados
• Experimentación rápida sin requerimientos de almacenamiento local

Para documentación detallada sobre esta función, consulta este documento.

Para un ejemplo básico de cómo usar un dataset de Hugging Face, configura "type": "huggingface" en tu configuración del dataloader:

{
  "id": "my-hf-dataset",
  "type": "huggingface",
  "dataset_name": "username/dataset-name",
  "caption_strategy": "huggingface",
  "metadata_backend": "huggingface",
  "caption_column": "caption",
  "image_column": "image"
}

Datasets Webshart¶

Durante la preparación de la caché VAE, Webshart procesa todos los grupos de relación de aspecto de un shard antes de pasar al siguiente. Esto reduce las descargas repetidas cuando la caché de shards completos no puede contener todo el conjunto de datos. Las muestras ya almacenadas y las asignadas a otros ranks se excluyen antes de agrupar; el orden del muestreador de entrenamiento no cambia.

Los captions pueden ser cadenas, objetos JSON nativos o listas mixtas de ambos. Los objetos se conservan en los metadatos y la caché; cada objeto se convierte en un único prompt de texto JSON al preparar la entrada del codificador de texto. Sus campos no se tratan como variantes independientes. Usa una lista para las alternativas o webshart.caption_key para seleccionar un campo. Requiere una versión de webshart compatible con captions JSON nativos y funciona con el canonicalizador de captions estructurados de Ideogram.

Los datasets Webshart cargan shards tar estilo WebDataset mediante el paquete webshart. Este backend usa metadatos de muestra lógica para los buckets de aspecto, por lo que los sidecars JSON emparejados no se tratan como muestras entrenables.

{
  "id": "cc12m-webshart",
  "type": "webshart",
  "dataset_type": "image",
  "source": "laion/conceptual-captions-12m-webdataset",
  "metadata": "webshart/conceptual-captions-12m-webdataset-metadata",
  "caption_strategy": "webshart",
  "metadata_backend": "webshart",
  "webshart": {
    "cache_dir": "cache/webshart/cc12m-webshart",
    "shard_cache_gb": 25,
    "parallel_downloads": 4
  }
}

• source es obligatorio y apunta a una fuente que Webshart pueda descubrir.
• metadata es opcional y puede apuntar a metadatos separados con captions. Para repositorios Hugging Face de metadata como webshart/conceptual-captions-12m-webdataset-metadata, pasa el repo id; Webshart sigue el layout de subcarpetas del source, como data/.
• metadata_backend debe ser webshart; caption_strategy debe ser webshart o instanceprompt.
• webshart.cache_dir almacena la metadata de SimpleTuner y las caches de Webshart. shard_cache_gb y parallel_downloads se pasan a la cache de shards de Webshart; define shard_cache_gb como 0 para desactivar la cache de shards completos y mantener lecturas por rango indexadas.
• webshart.caption_key permite seleccionar campos de caption: usa "long_caption" para una clave o ["long_caption", "short_caption"] para recopilar varias en el orden indicado. Las claves son nombres literales que se buscan en los metadatos JSON de la muestra, después en los metadatos del índice y, finalmente, en las entradas con nombre de sus respectivos diccionarios captions; se usa la primera ubicación que contiene la clave. Los valores de texto y listas se convierten en variantes de caption, sin concatenarse en un único prompt. Se ignoran los valores ausentes o vacíos; con caption_strategy: "webshart", se omiten las muestras sin captions seleccionadas aunque tengan captions predeterminadas o un sidecar .txt. Omitir la opción conserva la búsqueda predeterminada. Se leen los sidecars JSON cuando su contenido no está en el índice. Las cachés de captions y buckets se separan según el selector configurado. En los ajustes Webshart de la WebUI, introduce una clave por línea. Las lecturas de sidecars JSON usan la caché de shards configurada en Webshart; la consulta de captions no decodifica ni materializa los datos de imagen.
• webshart_optimize_captions (grafía alternativa webshart_optimise_captions; también se acepta como optimize_captions/optimise_captions dentro del bloque webshart) sondea el layout de captions al arrancar y, cuando los captions residen en miembros tar sidecar .txt/.json en lugar del índice de metadata, los consolida una sola vez en la cache local de metadata de Webshart. Sin esta opción, los datasets con captions en sidecars (por ejemplo laion/conceptual-captions-12m-webdataset) pagan una lectura por rango por muestra cada vez que se enumeran los captions — al arrancar, al guardar checkpoints y al generar la model card. Los datasets cuya metadata ya incluye los captions omiten la consolidación automáticamente.

Optimizar captions por adelantado¶

La misma consolidación está disponible desde la CLI de Webshart, que además puede publicar la metadata reparada para que todos los consumidores del dataset se beneficien sin la opción en tiempo de ejecución:

webshart optimize-captions \
  --source organization/dataset \
  --metadata organization/dataset-metadata \
  --destination caption-metadata \
  --shard-cache-dir cache/shards \
  --push-to-hub organization/dataset-metadata

--destination escribe un árbol de metadata portátil por shard, y --push-to-hub lo sube a un repositorio de metadata; después apunta la opción metadata del dataloader a ese repositorio. --shard-cache-dir permite que la consolidación reutilice shards completamente cacheados en lugar de emitir una lectura por rango por cada sidecar.

Mapeo personalizado de relación de aspecto a resolución¶

Cuando SimpleTuner inicia por primera vez, genera listas de mapeo de aspecto específicas de resolución que vinculan un valor decimal de relación de aspecto con su tamaño de píxel objetivo.

Es posible crear un mapeo personalizado que fuerce al trainer a ajustarse a tu resolución objetivo en lugar de sus propios cálculos. Esta funcionalidad se ofrece bajo tu propio riesgo, ya que obviamente puede causar gran daño si se configura incorrectamente.

Para crear el mapeo personalizado:

• Crea un archivo que siga el ejemplo (abajo)
• Nombra el archivo usando el formato aspect_ratio_map-{resolution}.json
• Para un valor de configuración resolution=1.0 / resolution_type=area, el nombre del mapeo será aspect_resolution_map-1.0.json
• Coloca este archivo en la ubicación especificada como --output_dir
• Esta es la misma ubicación donde se encontrarán tus checkpoints e imágenes de validación.
• No se requieren flags ni opciones adicionales de configuración. Se descubrirá y usará automáticamente, siempre que el nombre y la ubicación sean correctos.

Configuración de ejemplo del mapeo¶

Este es un ejemplo de mapeo de relación de aspecto generado por SimpleTuner. No necesitas configurarlo manualmente, ya que el trainer creará uno automáticamente. Sin embargo, para control total sobre las resoluciones resultantes, estos mapeos se proporcionan como punto de partida para su modificación.

• El dataset tenía más de 1 millón de imágenes
• El resolution del dataloader se configuró en 1.0
• El resolution_type del dataloader se configuró en area

Esta es la configuración más común y la lista de buckets de aspecto entrenables para un modelo de 1 megapíxel.

{
    "0.07": [320, 4544],    "0.38": [640, 1664],    "0.88": [960, 1088],    "1.92": [1472, 768],    "3.11": [1792, 576],    "5.71": [2560, 448],
    "0.08": [320, 3968],    "0.4": [640, 1600],     "0.89": [1024, 1152],   "2.09": [1472, 704],    "3.22": [1856, 576],    "6.83": [2624, 384],
    "0.1": [320, 3328],     "0.41": [704, 1728],    "0.94": [1024, 1088],   "2.18": [1536, 704],    "3.33": [1920, 576],    "7.0": [2688, 384],
    "0.11": [384, 3520],    "0.42": [704, 1664],    "1.06": [1088, 1024],   "2.27": [1600, 704],    "3.44": [1984, 576],    "8.0": [3072, 384],
    "0.12": [384, 3200],    "0.44": [704, 1600],    "1.12": [1152, 1024],   "2.5": [1600, 640],     "3.88": [1984, 512],
    "0.14": [384, 2688],    "0.46": [704, 1536],    "1.13": [1088, 960],    "2.6": [1664, 640],     "4.0": [2048, 512],
    "0.15": [448, 3008],    "0.48": [704, 1472],    "1.2": [1152, 960],     "2.7": [1728, 640],     "4.12": [2112, 512],
    "0.16": [448, 2816],    "0.5": [768, 1536],     "1.36": [1216, 896],    "2.8": [1792, 640],     "4.25": [2176, 512],
    "0.19": [448, 2304],    "0.52": [768, 1472],    "1.46": [1216, 832],    "3.11": [1792, 576],    "4.38": [2240, 512],
    "0.24": [512, 2112],    "0.55": [768, 1408],    "1.54": [1280, 832],    "3.22": [1856, 576],    "5.0": [2240, 448],
    "0.26": [512, 1984],    "0.59": [832, 1408],    "1.83": [1408, 768],    "3.33": [1920, 576],    "5.14": [2304, 448],
    "0.29": [576, 1984],    "0.62": [832, 1344],    "1.92": [1472, 768],    "3.44": [1984, 576],    "5.71": [2560, 448],
    "0.31": [576, 1856],    "0.65": [832, 1280],    "2.09": [1472, 704],    "3.88": [1984, 512],    "6.83": [2624, 384],
    "0.34": [640, 1856],    "0.68": [832, 1216],    "2.18": [1536, 704],    "4.0": [2048, 512],     "7.0": [2688, 384],
    "0.38": [640, 1664],    "0.74": [896, 1216],    "2.27": [1600, 704],    "4.12": [2112, 512],    "8.0": [3072, 384],
    "0.4": [640, 1600],     "0.83": [960, 1152],    "2.5": [1600, 640],     "4.25": [2176, 512],
    "0.41": [704, 1728],    "0.88": [960, 1088],    "2.6": [1664, 640],     "4.38": [2240, 512],
    "0.42": [704, 1664],    "0.89": [1024, 1152],   "2.7": [1728, 640],     "5.0": [2240, 448],
    "0.44": [704, 1600],    "0.94": [1024, 1088],   "2.8": [1792, 640],     "5.14": [2304, 448]
}

Para modelos de Stable Diffusion 1.5 / 2.0-base (512px), el siguiente mapeo funciona:

{
    "1.3": [832, 640], "1.0": [768, 768], "2.0": [1024, 512],
    "0.64": [576, 896], "0.77": [640, 832], "0.79": [704, 896],
    "0.53": [576, 1088], "1.18": [832, 704], "0.85": [704, 832],
    "0.56": [576, 1024], "0.92": [704, 768], "1.78": [1024, 576],
    "1.56": [896, 576], "0.67": [640, 960], "1.67": [960, 576],
    "0.5": [512, 1024], "1.09": [768, 704], "1.08": [832, 768],
    "0.44": [512, 1152], "0.71": [640, 896], "1.4": [896, 640],
    "0.39": [448, 1152], "2.25": [1152, 512], "2.57": [1152, 448],
    "0.4": [512, 1280], "3.5": [1344, 384], "2.12": [1088, 512],
    "0.3": [448, 1472], "2.71": [1216, 448], "8.25": [2112, 256],
    "0.29": [384, 1344], "2.86": [1280, 448], "6.2": [1984, 320],
    "0.6": [576, 960]
}