Arquivo de configuração do dataloader¶

Aqui está o exemplo mais básico de um arquivo de configuração do 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": ""
  }
]

Opções de configuração¶

`id`¶

Descrição: Identificador único do dataset. Ele deve permanecer constante depois de definido, pois vincula o dataset às entradas de rastreamento de estado.

`disabled`¶

Valores: true | false
Descrição: Quando definido como true, este dataset é totalmente ignorado durante o treinamento. Útil para excluir temporariamente um dataset sem remover sua configuração.
Nota: Também aceita a grafia disable.

`dataset_type`¶

Valores: image | video | audio | caption | text_embeds | image_embeds | conditioning_image_embeds | conditioning
Descrição: Datasets image, video e audio contêm as amostras principais de treinamento. text_embeds contém as saídas do cache do text encoder, image_embeds contém os latentes do VAE (quando um modelo usa um), e conditioning_image_embeds armazenam embeddings de imagens de condicionamento em cache (como recursos de visão do CLIP). Quando um dataset é marcado como conditioning, é possível pareá-lo ao seu dataset image via a opção conditioning_data
Nota: Datasets de text embed e image embed são definidos de forma diferente de datasets de imagem. Um dataset de text embed armazena APENAS os objetos de text embed. Um dataset de imagem armazena os dados de treinamento.
Nota: Não combine imagens e vídeo em um único dataset. Separe-os.

`caption_file_extensions`¶

A descoberta de legendas aceita esta lista opcional e não vazia de extensões, por exemplo ["jsonl"]. O padrão é ["txt", "json", "jsonl"]. Os arquivos JSON de metadados e cache de buckets do próprio backend são sempre excluídos, inclusive ao reiniciar com uma lista de arquivos existente.

`data_generator`¶

Válido apenas para dataset_type: "caption" (singular). Este objeto opcional gera um PNG e sua legenda para cada texto em cada resolução listada, antes dos caches de imagens, embeddings de texto e VAE. Os resultados seguem o treinamento normal de imagens, sem exigir um destilador. Sem este objeto, datasets de legendas continuam exigindo um destilador que aceite legendas.

resolutions (obrigatório): lista não vazia de strings WIDTHxHEIGHT, com dimensões múltiplas de 32. Cada resolução cria <id>-generated-<resolution>, usa a dimensão nativa da menor borda e desativa recortes. A probability original é dividida entre os buckets.
batch_size (padrão 1): lote de geração, independente do lote de treinamento. Falta de memória do acelerador reduz pela metade o lote que falhou nessa resolução e repete as mesmas amostras com as mesmas sementes. Os limites bem-sucedidos ficam no manifesto de geração. Falta de memória com lote um, ou qualquer outro erro, interrompe a geração.
num_inference_steps (padrão 40), guidance_scale (1.0) e seed (0): parâmetros de inferência. Qwen Image usa true_cfg_scale; valores acima de um usam prompt negativo vazio. A configuração de orientação da validação não substitui esse valor.
output_dir (opcional): padrão cache_dir/generated-captions/<id>. Os resultados ficam em um diretório identificado pela receita e são reutilizados ao reiniciar. A identificação inclui legendas, parâmetros de inferência, revisões resolvidas do Hub e tamanhos/datas de modificação dos pesos locais. Não altere os arquivos do modelo durante a geração. Alterar legendas, modelo ou inferência cria outro cache; alterar o lote não.

A geração usa o modelo base com adaptadores desativados e libera somente o transformador carregado para o pré-processamento. As legendas originais não mudam. A geração exige uma execução de preparação com um único processo; execuções com vários processos e data_generator são rejeitadas antes da ingestão das legendas. Para treinamento distribuído, use os diretórios gerados como datasets image comuns, um por resolução, com caption_strategy: "textfile", crop: false, resolution_type: "pixel" e resolution igual ao lado menor do bucket. Datasets de legendas sem gerador exigem dataloader_prefetch=false para preservar a posição do amostrador nos checkpoints. Alterações nas legendas, resoluções ou topologia do dataset exigem um novo treinamento; reutilizar o cache gerado não torna essas retomadas de checkpoint compatíveis.

Na descoberta local de legendas, a saída gerada deve ficar fora do instance_data_dir de origem; diretórios sobrepostos são rejeitados antes da varredura.

{
  "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`¶

Aplica-se apenas a dataset_type=text_embeds
Se definido como true, este dataset de text embed será onde o SimpleTuner armazenará o cache de text embeds, por exemplo, para embeddings de prompts de validação. Como eles não se vinculam a dados de imagem, precisa haver um local específico para eles.

`cache_dir`¶

Aplica-se apenas a dataset_type=text_embeds e dataset_type=image_embeds
Descrição: Especifica onde os arquivos de cache de embeds são armazenados para este dataset. Para text_embeds, é onde as saídas do text encoder são gravadas. Para image_embeds, é onde os latentes do VAE são armazenados.
Nota: Diferente de cache_dir_vae, que é definido em datasets de imagem/vídeo primários para especificar onde o cache de VAE vai.

`train_batch_size`¶

Comportamento de treinamento: Datasets primários amostrados de forma independente (image, video, audio, caption) usam o valor resolvido como tamanho do microbatch de treinamento. conditioning é um dado auxiliar pareado; seu valor resolvido ainda pode dimensionar buckets de metadados, mas não cria um microbatch de treinamento independente nem entra separadamente na contagem de amostras da atualização do otimizador.
Descrição: Sobrescreve o --train_batch_size global para este dataset. Para datasets primários, o valor resolvido controla o microbatch do sampler, os buckets e a quantidade instantânea de amostras quando selecionado. Para conditioning, afeta apenas a preparação de metadados e buckets. Deixe sem definir para usar o valor global.
Acúmulo de gradientes: Uma janela de acúmulo pode selecionar datasets com tamanhos de microbatch resolvidos diferentes. O total global de amostras de uma atualização do otimizador é a soma dos tamanhos reais dos microbatches locais em todos os microsteps de acúmulo e ranks data-parallel; um dataset selecionado sem override usa o padrão global naquele rank.
Referência global: O escalonamento da learning rate no trainer e outras configurações estáticas ou relatórios que exigem um único batch size fixo continuam usando o --train_batch_size global. Portanto, ao misturar overrides por dataset, a fórmula de batch global/efetivo é uma referência configurada, não a contagem exata de amostras de cada atualização do otimizador.
Gradient checkpointing: Gradient checkpointing não altera a aritmética do batch size.
Padrão: Usa o argumento --train_batch_size do trainer.

`write_batch_size`¶

Aplica-se apenas a dataset_type=text_embeds
Descrição: Número de text embeds a serem gravados em uma única operação de batch. Valores maiores podem melhorar a vazão de escrita, mas usam mais memória.
Padrão: Usa o argumento --write_batch_size do trainer (tipicamente 128).

`text_encoder_batch_size`¶

Aplica-se apenas a dataset_type=text_embeds
Descrição: Número de captions codificadas em um único forward do text encoder ao pré-computar text embeddings não cacheados. Valores maiores podem melhorar a vazão, mas usam mais VRAM.
Padrão: Usa o argumento --text_encoder_batch_size do trainer (padrão 1).

`text_cache_ondemand`¶

Aplica-se apenas a dataset_type=text_embeds
Valores: true | false
Descrição: Ignora a pré-computação completa dos embeddings de texto. Entradas existentes são lidas deste cache; embeddings ausentes são codificados durante o treinamento ou a validação e gravados no cache.
Nota: Todo dataset de imagem ou vídeo associado a este backend text_embeds herda esse comportamento. Para usar outro comportamento em datasets de origem selecionados, crie outro backend text_embeds e associe-o pelo campo text_embeds do dataset de origem.

`text_cache_disable`¶

Aplica-se apenas a dataset_type=text_embeds
Valores: true | false
Descrição: Lê embeddings de texto existentes, mas não grava embeddings recém-codificados. Entradas ausentes são codificadas durante o treinamento ou a validação; portanto, esta opção implica text_cache_ondemand.
Nota: A opção global --text_cache_disable aplica-se a todos os caches de texto. Use esta opção de backend quando a opção global estiver falsa e apenas backends text_embeds selecionados não devam gravar.

`text_embeds`¶

Aplica-se apenas a dataset_type=image
Se não definido, o dataset text_embeds padrão será usado. Se definido como o id existente de um dataset text_embeds, ele usará esse. Permite associar datasets específicos de text embeds a um dataset de imagens.

`image_embeds`¶

Aplica-se apenas a dataset_type=image
Se não definido, as saídas do VAE serão armazenadas no backend de imagem. Caso contrário, você pode definir isso como o id de um dataset image_embeds, e as saídas do VAE serão armazenadas lá. Permite associar o dataset image_embed aos dados de imagem.

`conditioning_image_embeds`¶

Aplica-se a dataset_type=image e dataset_type=video
Quando um modelo reporta requires_conditioning_image_embeds, defina isso para o id de um dataset conditioning_image_embeds para armazenar embeddings de imagem de condicionamento em cache (por exemplo, recursos de visão do CLIP para Wan 2.2 I2V). Se não definido, o SimpleTuner grava o cache em cache/conditioning_image_embeds/<dataset_id> por padrão, garantindo que não conflite com o cache do VAE.
Modelos que precisam desses embeds devem expor um image encoder por meio do pipeline principal. Se o modelo não conseguir fornecer o encoder, o pré-processamento falhará cedo em vez de gerar arquivos vazios silenciosamente.

`cache_dir_conditioning_image_embeds`¶

Substituição opcional do destino do cache de conditioning image embeds.
Defina isso quando quiser fixar o cache em um local específico do sistema de arquivos ou tiver um backend remoto dedicado (dataset_type=conditioning_image_embeds). Quando omitido, o caminho de cache descrito acima é usado automaticamente.

`conditioning_image_embed_batch_size`¶

Substituição opcional do tamanho do batch usado ao gerar conditioning image embeds.
Usa por padrão o argumento do trainer conditioning_image_embed_batch_size ou o tamanho de batch do VAE quando não fornecido explicitamente.

Configuração de dataset de áudio (`dataset_type=audio`)¶

Backends de áudio suportam um bloco audio dedicado para que metadados e cálculo de buckets levem em conta a duração. Exemplo:

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

Quando todos os datasets de mídia habilitados usam dataset_type: "audio", famílias de vídeo com SUPPORTS_FAKE_VIDEO_STREAM entram automaticamente no treinamento apenas de áudio. LTX-2 usa seu branch nativo de áudio; MiniMax-H3 mantém um token espacial de vídeo falso por frame latente e mascara a loss de vídeo. LoRA padrão seleciona AUDIO_LORA_TARGET automaticamente, a menos que peft_lora_target_modules seja definido explicitamente.

bucket_strategy – atualmente duration é o padrão e trunca clipes em buckets espaçados de forma uniforme para que a amostragem por GPU respeite o cálculo de batch.
duration_interval – arredondamento de bucket em segundos (padrão 3 quando não definido). Com 15, um clipe de 77 s é colocado no bucket de 75 s. Isso impede que clipes longos únicos prejudiquem outros ranks e força truncamento no mesmo intervalo.
max_duration_seconds – clipes mais longos que isso são ignorados durante a descoberta de metadados para que faixas excepcionalmente longas não consumam buckets inesperadamente.
truncation_mode – determina qual parte do clipe é mantida quando ajustamos para o intervalo do bucket. Opções: beginning, end ou random (padrão: beginning).
audio_only – override de compatibilidade para modo apenas áudio; configurações somente de áudio o ativam automaticamente em LTX-2 e MiniMax-H3.
target_resolution – override legado; fake streams automáticos usam a geometria mínima de tokens do modelo.
Configurações padrão de áudio (contagem de canais, diretório de cache) mapeiam diretamente para o backend de áudio em runtime criado por simpletuner.helpers.data_backend.factory. O padding é intencionalmente evitado — clipes são truncados em vez de estendidos para manter o comportamento consistente com treinadores de difusão como o ACE-Step.

Configuração de áudio para treinamento S2V¶

O bloco audio pode ser colocado em datasets de vídeo para extrair áudio automaticamente dos arquivos de vídeo. Para modelos que requerem treinamento S2V (Sound-to-Video) (ex: Wan S2V), este bloco é injetado automaticamente. Para modelos que suportam mas não exigem áudio (ex: LTX-2), você deve adicionar uma seção audio explicitamente para optar — sem ela, apenas vídeo é treinado e a loss de áudio é mascarada automaticamente.

{
  "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
  }
}

Isso cria automaticamente um dataset my-videos_audio e o vincula via s2v_datasets.

Campo	Tipo	Padrão	Descrição
`audio.auto_split`	bool	true	Gera automaticamente dataset de áudio a partir de arquivos de vídeo. Padrão true quando a seção `audio` está presente. Para modelos que exigem S2V, padrão true mesmo sem seção `audio`.
`audio.source_from_video`	bool	false	(Auto-definido) Indica que o áudio é extraído do vídeo
`audio.allow_zero_audio`	bool	false	Gera áudio zerado para vídeos sem stream de áudio
`audio.audio_only`	bool	false	Override de compatibilidade; configurações somente de áudio ativam o modo automaticamente para LTX-2 e MiniMax-H3
`audio.target_resolution`	int	null	Override legado; o fake stream automático usa a geometria mínima de tokens da família
`audio.sample_rate`	int	16000	Taxa de amostragem alvo para extração de áudio
`audio.channels`	int	1	Número de canais de áudio (1=mono, 2=estéreo)
`audio.bucket_strategy`	string	"duration"	Estratégia de bucketing para amostras de áudio
`audio.duration_interval`	float	3.0	Intervalo de duração para agrupamento em buckets (segundos)
`audio.max_duration_seconds`	float	null	Duração máxima de áudio (arquivos mais longos são ignorados)
`audio.truncation_mode`	string	"beginning"	Como truncar áudio longo: "beginning", "end", "random"

Captions de áudio (Hugging Face)¶

Para datasets de áudio do Hugging Face, você pode especificar quais colunas formam a caption (prompt) e qual coluna contém as letras:

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

* audio_caption_fields: Junta múltiplas colunas para formar o prompt de texto (usado pelo text encoder). * lyrics_column: Especifica a coluna das letras (usada pelo lyric encoder).

Durante a descoberta de metadados, o loader registra sample_rate, num_samples, num_channels e duration_seconds para cada arquivo. Relatórios de buckets no CLI agora falam em amostras em vez de imagens, e diagnósticos de dataset vazio listarão o bucket_strategy/duration_interval ativo (além de qualquer limite max_duration_seconds) para que você ajuste os intervalos sem mergulhar nos logs.

`type`¶

Valores: aws | local | memory | csv | huggingface | webshart
Descrição: Determina o backend de armazenamento (local, memória, csv ou nuvem) usado para este dataset.

Backends em memória (tmpfs e RAM disk)¶

type: "memory" usa MemoryDataBackend, uma subclasse de LocalDataBackend baseada em tmpfs no Linux ou em um RAM disk nativo no macOS. Ele está disponível apenas para entradas de armazenamento de cache com dataset_type: "text_embeds" ou dataset_type: "image_embeds"; datasets primários de imagem, vídeo, áudio, conditioning e avaliação não podem usá-lo. O SimpleTuner monta um sistema de arquivos vazio separado e copia o cache_dir configurado quando esse diretório existe. Leituras e gravações usam a cópia residente em memória e são descartadas ao liberá-la; elas não são sincronizadas de volta para 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: Diretório de montagem vazio opcional. O padrão é simpletuner-memory/<id do dataset> dentro do diretório temporário do sistema. Esse diretório e cache_dir não podem se sobrepor nem conter um ao outro.
memory_filesystem_size: Capacidade do sistema de arquivos em memória, como 512G. É opcional no Linux, onde se aplica o padrão do tmpfs e percentuais como 80% são aceitos. No macOS é obrigatório e deve ser um tamanho em bytes, não um percentual; o SimpleTuner o converte para o número de setores de 512 bytes exigido pelo hdiutil.
memory_filesystem_sudo: Apenas Linux. Quando true, executa mount e umount por sudo -n. Deixe false ao executar como root. O sudo não interativo e sem senha deve estar configurado previamente quando habilitado. RAM disks do macOS usam hdiutil e diskutil sem esta opção.

Backends de memória exigem Linux ou macOS e RAM ou swap suficiente para o cache existente e todos os embeddings gravados durante o treinamento. São úteis para caches grandes de latentes ou embeddings de texto em sistemas com muita memória quando leituras repetidas são o gargalo. Pré-carregar um cache existente aumenta o tempo de inicialização; use um cache_dir vazio ou inexistente para iniciar com um cache vazio.

`conditioning_type`¶

Valores: controlnet | mask | reference_strict | reference_loose
Descrição: Especifica o tipo de condicionamento para um dataset conditioning.
controlnet: Entradas de condicionamento do ControlNet para treinamento de sinal de controle.
mask: Máscaras binárias para treinamento de inpainting.
reference_strict: Imagens de referência com alinhamento estrito de pixels (para modelos de edição como Qwen Edit).
reference_loose: Imagens de referência com alinhamento frouxo.
Nota Flow-DPO: reference_strict também é usado pelo Flow-DPO para fornecer os latentes rejected/lose de cada amostra preferred.

`source_dataset_id`¶

Aplica-se apenas a dataset_type=conditioning com conditioning_type de reference_strict, reference_loose ou mask
Descrição: Vincula um dataset de condicionamento ao dataset de imagem/vídeo de origem para alinhamento de pixels. Quando definido, o SimpleTuner duplica metadados do dataset de origem para garantir que as imagens de condicionamento se alinhem aos seus alvos.
Nota: Obrigatório para modos de alinhamento estrito; opcional para alinhamento frouxo.

`conditioning_data`¶

Valores: valor id do dataset de condicionamento ou um array de valores id
Descrição: Conforme descrito no guia do ControlNet, um dataset image pode ser pareado ao seu ControlNet ou dados de máscara de imagem via esta opção.
Nota: Se você tiver múltiplos datasets de condicionamento, pode especificá-los como um array de valores id. Ao treinar Flux Kontext, isso permite alternar aleatoriamente entre condições ou juntar entradas para treinar tarefas mais avançadas de composição multi-imagem.
Flow-DPO: Pareie aqui um dataset reference_strict ao usar --distillation_method=flow_dpo.

`data_transforms`¶

Valores: um objeto de transform ou um array de objetos de transform
Descrição: Expande um dataset fonte em um ou mais datasets de treinamento gerados antes da configuração normal do dataloader. Datasets gerados são tratados como datasets primários normais, a menos que o transform peça explicitamente clonagem de metadados.
Identity transfer de áudio: {"task": "identity_transfer", "method": "rvc"} está disponível para backends com dataset_type: "audio". Ele prepara um split de áudio gerado para transferência de identidade vocal e usa o diretório de saída para artefatos de voz em cache e arquivos gerados. Consulte Voice Cloning Data Transforms.
Identity data: Coloque a musica a converter no instance_data_dir do backend de audio, os exemplos da voz alvo em model.identity_data_dir, e o caminho do split gerado em target.instance_data_dir.
Debug de stems: Defina model.identity_stem_debug_dir para preservar previews vocals.wav e no_vocals.wav da identidade separada que o treino RVC realmente usou. Isso ajuda quando a saída soa como se instrumentos tivessem sido aprendidos como parte da voz.
Status: A implementação experimental inclui verificações de manifest de cache, reutilização/envio de artefatos para o Hub pelo layout huggingface-hub-rvc, sharding de inicialização compatível com DDP, logs locais de RVC e um trainer/converter compacto de voice-transfer do SimpleTuner. O modo full-song remix usa Demucs para separar vocais; o modo vocal-stem não precisa de separação.

`instance_data_dir` / `aws_data_prefix`¶

Local: Caminho para os dados no sistema de arquivos.
AWS: Prefixo S3 para os dados no bucket. aws_data_prefix pode ser uma string para um prefixo ou uma lista de strings para varrer vários prefixos no mesmo bucket.

`caption_strategy`¶

textfile exige que sua image.png esteja ao lado de uma image.txt que contém uma ou mais captions, separadas por novas linhas. Esses pares imagem+texto devem estar no mesmo diretório.
instanceprompt exige que um valor instance_prompt também seja fornecido e usará apenas esse valor como a caption de todas as imagens do conjunto.
filename usará uma versão convertida e limpa do nome do arquivo como caption, por exemplo, após trocar sublinhados por espaços.
parquet extrairá captions da tabela parquet que contém o restante dos metadados da imagem. Use o campo parquet para configurar isso. Veja Estratégia de captions Parquet.
webshart extrai captions dos metadados dos shards Webshart e exige type: "webshart" com metadata_backend: "webshart".

Tanto textfile quanto parquet suportam multi-captions: - textfiles são separadas por novas linhas. Cada nova linha será sua própria caption. - tabelas parquet podem ter um tipo iterável no campo.

`disable_multiline_split`¶

Quando definido como true, impede que arquivos de texto de caption sejam divididos por novas linhas em múltiplas variantes de caption.
Útil quando suas captions contêm quebras de linha intencionais que devem ser preservadas como uma única caption.
Padrão: false (captions são divididas por novas linhas)

`caption_shuffle`¶

Gera variantes embaralhadas determinísticas de captions baseadas em tags para aumento de dados. Isso ajuda o modelo a aprender que a ordem das tags não importa e reduz o overfitting em sequências específicas de tags.

Configuração:

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

Parâmetros:

enable (bool): Se deve habilitar o embaralhamento de captions. Padrão: false
count (int): Número de variantes embaralhadas a gerar por caption. Padrão: 1
seed (int): Seed para embaralhamento determinístico. Se não especificado, usa o valor global --seed.
split_on (string): Delimitador para dividir captions em tags. Opções: comma, space, period. Padrão: comma
position_start (int): Manter as primeiras N tags em sua posição original (útil para manter tags de assunto/estilo primeiro). Padrão: 0
include_original (bool): Se deve incluir a caption original não embaralhada junto com as variantes embaralhadas. Padrão: true

Exemplo:

Com 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"]

A primeira tag "dog" permanece fixa enquanto as tags restantes são embaralhadas.

Notas:

O embaralhamento é aplicado durante o pré-cache de embeddings de texto, então todas as variantes são calculadas de uma vez.
Durante o treinamento, uma variante é selecionada aleatoriamente por amostra.
Se uma caption tiver menos tags que position_start + 2, o embaralhamento é pulado (nada significativo para embaralhar).
Quando include_original: false mas o embaralhamento não é possível, a original é incluída mesmo assim com um aviso.

`metadata_backend`¶

Valores: discovery | parquet | huggingface | webshart
Descrição: Controla como o SimpleTuner descobre dimensões de imagem e outros metadados durante a preparação do dataset.
discovery (padrão): Examina arquivos de imagem reais para ler dimensões. Funciona com qualquer backend de armazenamento, mas pode ser lento para datasets grandes.
parquet: Lê dimensões de width_column e height_column em um arquivo parquet/JSONL, evitando acessar os arquivos. Veja Estratégia de captions Parquet.
huggingface: Usa metadados de datasets do Hugging Face. Veja Suporte a Hugging Face Datasets.
webshart: Usa metadados de shards Webshart, incluindo buckets de aspecto por amostra lógica e captions, sem escanear bytes de imagem.
Nota: Ao usar parquet, você também deve configurar o bloco parquet com width_column e height_column. Isso acelera drasticamente a inicialização para datasets grandes.

`metadata_update_interval`¶

Valores: Inteiro (segundos)
Descrição: Com que frequência (em segundos) atualizar os metadados do dataset durante o treinamento. Útil para datasets que podem mudar durante uma execução longa.
Padrão: Usa o argumento do trainer --metadata_update_interval.

Opções de corte¶

crop: Habilita ou desabilita o corte de imagem.
crop_style: Seleciona o estilo de corte (random, center, corner, face).
crop_aspect: Escolhe o aspecto do corte (closest, random, square ou preserve).
crop_aspect_buckets: Quando crop_aspect é definido como closest ou random, um bucket desta lista será selecionado. Por padrão, todos os buckets estão disponíveis (permitindo upscaling ilimitado). Use max_upscale_threshold para limitar o upscaling se necessário.

`resolution`¶

resolution_type=area: O tamanho final da imagem é determinado pela contagem de megapixels - um valor de 1.05 aqui corresponde a buckets de aspecto em torno de 1024^2 (1024x1024) de área total de pixels, ~1_050_000 pixels.
resolution_type=pixel_area: Como area, o tamanho final da imagem é pela área, mas medido em pixels em vez de megapixels. Um valor de 1024 aqui gerará buckets de aspecto em torno de 1024^2 (1024x1024) de área total de pixels, ~1_050_000 pixels.
resolution_type=pixel: O tamanho final da imagem será determinado pela menor borda ter este valor.

NOTA: Se as imagens são ampliadas, reduzidas ou cortadas, isso depende dos valores de minimum_image_size, maximum_target_size, target_downsample_size, crop e crop_aspect.

`minimum_image_size`¶

Quaisquer imagens cujo tamanho fique abaixo desse valor serão excluídas do treinamento.
Quando resolution é medida em megapixels (resolution_type=area), isso deve estar em megapixels também (ex.: 1.05 megapixels para excluir imagens abaixo de 1024x1024 de área)
Quando resolution é medida em pixels, você deve usar a mesma unidade aqui (ex.: 1024 para excluir imagens com lado menor abaixo de 1024px)
Recomendação: Mantenha minimum_image_size igual a resolution, a menos que você queira arriscar treinar com imagens que foram ampliadas de forma ruim.

`minimum_aspect_ratio`¶

Descrição: A proporção mínima da imagem. Se a proporção da imagem for menor que este valor, ela será excluída do treinamento.
Nota: Se o número de imagens qualificadas para exclusão for excessivo, isso pode desperdiçar tempo na inicialização, pois o trainer tentará escaneá-las e criar buckets se elas estiverem faltando nas listas de buckets.

Nota: Depois que as listas de aspecto e metadados forem construídas para o seu dataset, usar skip_file_discovery="vae aspect metadata" impedirá que o trainer escaneie o dataset na inicialização, economizando muito tempo.

`maximum_aspect_ratio`¶

Descrição: A proporção máxima da imagem. Se a proporção da imagem for maior que este valor, ela será excluída do treinamento.
Nota: Se o número de imagens qualificadas para exclusão for excessivo, isso pode desperdiçar tempo na inicialização, pois o trainer tentará escaneá-las e criar buckets se elas estiverem faltando nas listas de buckets.

Nota: Depois que as listas de aspecto e metadados forem construídas para o seu dataset, usar skip_file_discovery="vae aspect metadata" impedirá que o trainer escaneie o dataset na inicialização, economizando muito tempo.

`conditioning`¶

Valores: Array de objetos de configuração de condicionamento
Descrição: Gera automaticamente datasets de condicionamento a partir das suas imagens de origem. Cada tipo de condicionamento cria um dataset separado que pode ser usado para treinamento de ControlNet ou outras tarefas de condicionamento.
Nota: Quando especificado, o SimpleTuner criará automaticamente datasets de condicionamento com IDs como {source_id}_conditioning_{type}

Cada objeto de condicionamento pode conter: - type: O tipo de condicionamento a gerar (obrigatório) - params: Parâmetros específicos do tipo (opcional) - captions: Estratégia de caption para o dataset gerado (opcional) - Pode ser false (sem captions) - Uma string única (usada como instance prompt para todas as imagens) - Um array de strings (selecionado aleatoriamente para cada imagem) - Se omitido, as captions do dataset de origem são usadas

Tipos de condicionamento disponíveis¶

`superresolution`¶

Gera versões de baixa qualidade das imagens para treinamento de super-resolução:

{
  "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`¶

Gera imagens SDR/de referência de condicionamento para datasets de condicionamento pareados. O transform rec709 padrão normaliza e recorta entradas Rec.709 SDR já existentes, igual ao caminho de condicionamento de referência HDR IC-LoRA do LTX-2:

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

Use transform: "srgb" quando os valores decodificados forem lineares e você quiser um proxy SDR de tela. Use transform: "logc3" (ou o alias logc3_sdr) apenas quando quiser amostras codificadas em LogC3. input_scale é aplicado antes da exposure e é útil quando os valores decodificados precisam de normalização. Este gerador atualmente opera em amostras de imagem que o backend de imagens do SimpleTuner consegue decodificar.

`jpeg_artifacts`¶

Cria artefatos de compressão JPEG para treinamento de remoção de artefatos:

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

`depth` / `depth_midas`¶

Gera mapas de profundidade usando modelos DPT:

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

Nota: A geração de profundidade exige GPU e roda no processo principal, o que pode ser mais lento do que geradores baseados em CPU.

`random_masks` / `inpainting`¶

Cria máscaras aleatórias para treinamento de inpainting:

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

`canny` / `edges`¶

Gera mapas de detecção de bordas Canny:

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

Veja o guia do ControlNet para mais detalhes sobre como usar esses datasets de condicionamento.

Exemplos¶

Dataset de vídeo¶

Um dataset de vídeo deve ser uma pasta de arquivos de vídeo (ex.: mp4) e os métodos usuais de armazenar 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
  }
]

Na subseção video, temos as seguintes chaves que podemos definir:
num_frames (opcional, int) é quantos frames de dados vamos treinar.
- A 25 fps, 125 frames são 5 segundos de vídeo, saída padrão. Este deve ser seu alvo.
min_frames (opcional, int) determina o comprimento mínimo de um vídeo que será considerado para treinamento.
- Isso deve ser pelo menos igual a num_frames. Não definir garante que ele será igual.
max_frames (opcional, int) determina o comprimento máximo de um vídeo que será considerado para treinamento.
is_i2v (opcional, bool) determina se o treinamento i2v será feito em um dataset.
- Isso é definido como True por padrão para LTX. Você pode desativar, porém.
bucket_strategy (opcional, string) determina como os vídeos são agrupados em buckets:
- aspect_ratio (padrão): Agrupa apenas pela proporção espacial (ex.: 1.78, 0.75). Mesmo comportamento que datasets de imagem.
- resolution_frames: Agrupa por resolução e contagem de frames no formato WxH@F (ex.: 1920x1080@125). Útil para treinar em datasets com resoluções e durações variadas.
frame_interval (opcional, int) ao usar bucket_strategy: "resolution_frames", a contagem de frames é arredondada para baixo para o múltiplo mais próximo desse valor. Defina isso como o fator de contagem de frames exigido pelo seu modelo (alguns modelos exigem que num_frames - 1 seja divisível por um certo valor).

Ajuste Automático de Contagem de Frames: SimpleTuner ajusta automaticamente as contagens de frames de vídeo para atender aos requisitos específicos do modelo. Por exemplo, LTX-2 requer contagens de frames que satisfaçam frames % 8 == 1 (ex.: 49, 57, 65, 73, 81, etc.). Se seus vídeos tiverem contagens de frames diferentes (ex.: 119 frames), eles serão automaticamente cortados para a contagem de frames válida mais próxima (ex.: 113 frames). Vídeos que ficam mais curtos que min_frames após o ajuste são ignorados com uma mensagem de aviso. Este ajuste automático previne erros de treinamento e não requer nenhuma configuração da sua parte.

Nota: Ao usar bucket_strategy: "resolution_frames" com num_frames definido, você terá um único bucket de frames e vídeos menores que num_frames serão descartados. Remova num_frames se você quiser múltiplos buckets de frames com menos descartes.

Exemplo usando bucketing resolution_frames para datasets de vídeo com resolução mista:

{
  "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
  }
}

Essa configuração criará buckets como 1280x720@100, 1920x1080@125, 640x480@75, etc. Os vídeos são agrupados pela resolução de treinamento e contagem de frames (arredondada para múltiplos de 25 frames).

Configuração¶

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

Resultado¶

Qualquer imagem com lado menor inferior a 1024px será completamente excluída do treinamento.
Imagens como 768x1024 ou 1280x768 seriam excluídas, mas 1760x1024 e 1024x1024 não.
Nenhuma imagem será ampliada, porque minimum_image_size é igual a resolution

Configuração¶

    "minimum_image_size": 1024,
    "resolution": 1024,
    "resolution_type": "pixel_area" # diferente da configuração acima, que é 'pixel'

Resultado¶

A área total da imagem (largura * altura) sendo menor que a área mínima (1024 * 1024) resultará na exclusão do treinamento.
Imagens como 1280x960 não seriam excluídas porque (1280 * 960) é maior que (1024 * 1024)
Nenhuma imagem será ampliada, porque minimum_image_size é igual a resolution

Configuração¶

    "minimum_image_size": 0, # ou completamente não definido, ausente na configuração
    "resolution": 1024,
    "resolution_type": "pixel",
    "crop": false

Resultado¶

As imagens serão redimensionadas para que o lado menor seja 1024px mantendo a proporção
Nenhuma imagem será excluída por tamanho
Imagens pequenas serão ampliadas usando métodos ingênuos de PIL.resize que não ficam bons
É recomendado evitar upscaling, a menos que seja feito manualmente com um upscaler de sua escolha antes de iniciar o treinamento

`maximum_image_size` e `target_downsample_size`¶

As imagens não são redimensionadas antes do corte a menos que maximum_image_size e target_downsample_size estejam ambos definidos. Em outras palavras, uma imagem 4096x4096 será cortada diretamente para um alvo 1024x1024, o que pode ser indesejável.

maximum_image_size especifica o limite em que o redimensionamento começará. Ele fará downsample das imagens antes do corte se elas forem maiores que isso.
target_downsample_size especifica o quão grande a imagem ficará após o reamostramento e antes do corte.

Exemplos¶

Configuração¶

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

Resultado¶

Qualquer imagem com área de pixels maior que (1536 * 1536) será redimensionada para que sua área de pixels fique aproximadamente (1280 * 1280) mantendo a proporção original
O tamanho final da imagem será um corte aleatório para uma área de pixels (1024 * 1024)
Útil para treinar em datasets, por exemplo, de 20 megapixels que precisam ser redimensionados consideravelmente antes do corte para evitar grande perda de contexto na imagem (como cortar uma foto de uma pessoa para apenas um azulejo de parede ou uma seção borrada do fundo)

`max_upscale_threshold`¶

Por padrão, o SimpleTuner fará upscaling de imagens pequenas para atender à resolução alvo, o que pode resultar em degradação de qualidade. A opção max_upscale_threshold permite limitar esse comportamento de upscaling.

Padrão: null (permite upscaling ilimitado)
Quando definido: Filtra buckets de aspecto que exigiriam upscaling além do limite especificado
Faixa de valor: Entre 0 e 1 (ex.: 0.2 = permitir até 20% de upscaling)
Aplica-se a: Seleção de bucket de aspecto quando crop_aspect é definido como closest ou random

Exemplos¶

Configuração¶

    "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 os buckets de aspecto estão disponíveis para seleção
Uma imagem 256x256 pode ser ampliada para 1024x1024 (escala 4x)
Pode resultar em degradação de qualidade para imagens muito pequenas

Configuração¶

    "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¶

Apenas buckets de aspecto que exigem ≤20% de upscaling estão disponíveis
Uma imagem 256x256 tentando escalar para 1024x1024 (4x = 300% de upscaling) não teria buckets disponíveis
Uma imagem 850x850 pode usar todos os buckets, já que 1024/850 ≈ 1.2 (20% de upscaling)
Ajuda a manter a qualidade do treinamento ao excluir imagens muito ampliadas

`prepend_instance_prompt`¶

Quando habilitado, todas as captions incluirão o valor de instance_prompt no início.

`only_instance_prompt`¶

Além de prepend_instance_prompt, substitui todas as captions do dataset por uma única frase ou palavra de ativação.

`timestep_sampling_offset`¶

Desloca a amostragem de timesteps de flow-matching deste dataset para níveis de ruído mais altos ou mais baixos. Aplica-se ao cronograma padrão logit-normal (sigmoid).
Um valor negativo enviesa a amostragem para timesteps de menor ruído, focando o treinamento em detalhes finos (por exemplo, close-ups ou dados com muita textura). Um valor positivo enviesa para timesteps de maior ruído, focando na estrutura geral (por exemplo, corpo inteiro ou dados voltados à composição).
O valor é somado à amostra normal antes do sigmoid; magnitudes úteis costumam ficar entre -1.0 e 1.0. O padrão é 0.0 (sem viés, idêntico ao comportamento original).
Como cada lote (batch) vem de um único dataset, agrupe as imagens por granularidade semântica em datasets separados e defina um timestep_sampling_offset para cada um.

`repeats`¶

Especifica quantas vezes todas as amostras do dataset são vistas durante uma época. Útil para dar mais impacto a datasets menores ou maximizar o uso de objetos de cache do VAE.
Se você tem um dataset com 1000 imagens vs um com 100 imagens, você provavelmente vai querer dar ao dataset menor um repeats de 9 ou maior para levá-lo a 1000 imagens totais amostradas.

ℹ️ Este valor se comporta de maneira diferente da mesma opção nos scripts do Kohya, onde um valor de 1 significa sem repetições. No SimpleTuner, um valor de 0 significa sem repetições. Subtraia um do valor do seu config do Kohya para obter o equivalente no SimpleTuner; portanto um valor 9 resulta do cálculo (dataset_length + repeats * dataset_length) .

Treinamento multi-GPU e dimensionamento de dataset¶

Ao treinar com múltiplas GPUs, seu dataset deve ser grande o suficiente para acomodar o tamanho efetivo do batch, calculado como:

effective_batch_size = train_batch_size do dataset × num_gpus × gradient_accumulation_steps

Esse é um requisito de dimensionamento de buckets por dataset. Ele não significa que todos os datasets configurados serão selecionados em uma janela de acúmulo nem descreve a contagem exata de amostras de uma atualização do otimizador com tamanhos mistos.

Por exemplo, com 4 GPUs, train_batch_size=4 no dataset e gradient_accumulation_steps=1, você precisa de pelo menos 16 amostras (após aplicar repeats) em cada bucket de aspecto.

Importante: O SimpleTuner lançará um erro se sua configuração de dataset produzir zero batches utilizáveis. A mensagem de erro mostrará: - Valores atuais de configuração (batch size, contagem de GPUs, repeats) - Quais buckets de aspecto têm amostras insuficientes - Repeats mínimos exatos necessários para cada bucket - Soluções sugeridas

Oversubscription automática de dataset¶

Para ajustar automaticamente repeats quando seu dataset é menor que o tamanho efetivo do batch, use a flag --allow_dataset_oversubscription (documentada em OPTIONS.md).

Quando habilitado, o SimpleTuner irá: - Calcular o mínimo de repeats necessário para cada bucket de aspecto insuficiente - Preencher apenas esses buckets para atender ao tamanho efetivo do batch - Registrar um aviso mostrando o ajuste - Respeitar valores de repeats definidos manualmente - se você configurar explicitamente repeats no seu config de dataset, o ajuste automático será ignorado

Isso é particularmente útil quando: - Treinar datasets pequenos (< 100 imagens) - Usar muitos GPUs com datasets pequenos - Experimentar diferentes tamanhos de batch sem reconfigurar datasets

Exemplo de cenário: - Dataset: 25 imagens - Configuração: 8 GPUs, train_batch_size=4, gradient_accumulation_steps=1 - Tamanho efetivo do batch: 32 amostras necessárias - Sem oversubscription: Erro lançado - Com --allow_dataset_oversubscription: Repeats ajustado automaticamente para 1 (25 × 2 = 50 amostras)

`max_num_samples`¶

Descrição: Limita o dataset a um número máximo de amostras. Quando definido, um subconjunto aleatório determinístico do tamanho especificado é selecionado do dataset completo.
Caso de uso: Útil para grandes datasets de regularização onde você deseja usar apenas uma parte dos dados para evitar sobrecarregar conjuntos de treinamento menores.
Seleção determinística: A seleção aleatória usa o id do dataset como semente, garantindo que o mesmo subconjunto seja selecionado entre sessões de treinamento para reprodutibilidade.
Padrão: null (sem limite, todas as amostras são usadas)

Exemplo¶

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

Isso selecionará deterministicamente 1000 amostras do dataset, com a mesma seleção usada toda vez que o treinamento for executado.

`start_epoch` / `start_step`¶

Agenda quando um dataset começa a amostrar.
start_epoch (padrão: 1) condiciona pelo número de épocas; start_step (padrão: 0) condiciona pelo step do otimizador (após gradient accumulation). Ambas as condições devem ser satisfeitas antes de amostrar.
Pelo menos um dataset deve ter start_epoch<=1 e start_step<=1; caso contrário, o treinamento dará erro porque não há dados disponíveis na inicialização.
Datasets que nunca atendem sua condição de início (por exemplo, start_epoch além de --num_train_epochs) serão ignorados e anotados no model card.
Estimativas de steps na barra de progresso são aproximadas quando datasets programados ativam no meio da execução, porque o tamanho da época pode aumentar quando novos dados entram.

`end_epoch` / `end_step`¶

Agenda quando um dataset para de amostrar (complementando start_epoch/start_step).
end_epoch (padrão: null = sem limite) para de amostrar após esta época; end_step (padrão: null = sem limite) para de amostrar após este step do otimizador.
Qualquer uma das condições que terminar irá parar o dataset; funcionam independentemente.
Útil para workflows de aprendizado curricular onde você deseja:
Treinar com dados de baixa resolução primeiro, depois mudar para dados de maior resolução.
Eliminar gradualmente dados de regularização após certo ponto.
Criar treinamento multi-estágio em um único arquivo de configuração.

Exemplo: Aprendizado 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
  }
]

Neste exemplo, o dataset de 512px é usado para steps 1-300, então o dataset de 1024px assume a partir do step 300 em diante.

`is_regularisation_data`¶

Também pode ser escrito como is_regularization_data
Habilita treinamento parent-teacher para que o alvo de predição prefira o resultado do modelo base congelado para um dado dataset.
A maioria das famílias de difusão atualmente requer adapters LyCORIS.
O treinamento language_model do MiniMax Music 3 suporta lotes de regularização com LoRA PEFT padrão, incluindo seleção de rota XM. O alvo é a distribuição de próximo token do planner base congelado.

`delete_unwanted_images`¶

Valores: true | false
Descrição: Quando habilitado, imagens que falham nos filtros de tamanho ou proporção (ex.: abaixo de minimum_image_size ou fora de minimum_aspect_ratio/maximum_aspect_ratio) são permanentemente deletadas do diretório do dataset.
Aviso: Isso é destrutivo e não pode ser desfeito. Use com cuidado.
Padrão: Usa o argumento do trainer --delete_unwanted_images (padrão: false).

`delete_problematic_images`¶

Valores: true | false
Descrição: Quando habilitado, imagens que falham durante a codificação VAE (arquivos corrompidos, formatos não suportados, etc.) são permanentemente deletadas do diretório do dataset.
Aviso: Isso é destrutivo e não pode ser desfeito. Use com cuidado.
Padrão: Usa o argumento do trainer --delete_problematic_images (padrão: false).

`delete_nsfw_images`¶

Valores: true | false
Descrição: Quando --enable_nsfw_check está habilitado, samples rejeitados pelo classificador NSFW são deletados deste backend se ele suportar deleção.
Aviso: Isso é destrutivo e não pode ser desfeito. Datasets Hugging Face são somente leitura e serão apenas removidos dos metadados da execução atual.
Padrão: Usa o argumento do trainer --delete_nsfw_images (padrão: false).

Verificações de classificador NSFW durante o cache VAE¶

O SimpleTuner pode escanear samples de treinamento com classificadores de imagem do Hugging Face Transformers durante o pré-processamento do cache VAE ao definir --enable_nsfw_check=true. A verificação acontece depois do bucket discovery e antes da codificação VAE, então samples rejeitados são removidos dos buckets de metadados atuais antes que latents sejam escritos.

Para notas de privacidade, responsabilidade e contexto legal, veja NSFW.pt-BR.md.

A verificação se aplica apenas a samples sem cache que o VAE cache está prestes a processar. Entradas de cache VAE existentes são confiadas, e skip_file_discovery=vae ignora o enforcement NSFW porque o trainer assume que o dataset já foi preparado segundo a política do usuário. Datasets de avaliação não são verificados.

Configuração dos classificadores: - --nsfw_check_models aceita uma lista CSV de modelos padrão de classificação de imagem do Hugging Face Transformers. Anexe thresholds por modelo com model/repo:threshold=0.5. - O padrão é Falconsai/nsfw_image_detection:threshold=0.5,AdamCodd/vit-base-nsfw-detector:threshold=0.5. - trust_remote_code não é habilitado, e classificadores que exigem timm ou código customizado não são suportados. - --nsfw_check_min_votes controla quantos modelos configurados precisam retornar NSFW para rejeitar um frame.

Controles de escopo: - --nsfw_check_backend_types aceita valores type de backend, como all, local, huggingface, csv ou aws. - --nsfw_check_sample_types aceita valores dataset_type. O padrão é image,conditioning; adicione video para verificar datasets de vídeo. - --delete_nsfw_images=true deleta samples rejeitados de backends mutáveis. Quando desabilitado, eles são apenas removidos dos metadados da execução atual.

Samples de vídeo e multi-frame: - --nsfw_check_video_frame_count controla quantos frames são verificados. - --nsfw_check_video_frame_selection pode ser uniform, first ou middle. - --nsfw_check_video_min_flagged_frames controla quantos frames verificados precisam ser rejeitados antes de rejeitar o sample inteiro.

Cada processo de cache VAE escreve um relatório nsfw_classifier_report_rank*.json no diretório de cache VAE quando samples são verificados. Os relatórios incluem thresholds dos modelos, contagens agregadas de verdicts, caminhos de samples rejeitados e contagens de deleção.

A deleção por backend pode ser habilitada em multidatabackend.json:

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

Visualizando Estatísticas de Filtragem¶

Quando o SimpleTuner processa seu dataset, ele rastreia quantos arquivos foram filtrados e por quê. Essas estatísticas são armazenadas no arquivo de cache do dataset (aspect_ratio_bucket_indices_*.json) e podem ser visualizadas na WebUI.

Estatísticas rastreadas: - total_processed: Número de arquivos processados - too_small: Arquivos filtrados por estarem abaixo de minimum_image_size - too_long: Arquivos filtrados por excederem limites de duração (áudio/vídeo) - metadata_missing: Arquivos ignorados por falta de metadados - not_found: Arquivos que não puderam ser localizados - already_exists: Arquivos já no cache (não reprocessados) - nsfw: Arquivos rejeitados pelo classificador NSFW durante o pré-processamento do cache VAE - other: Arquivos filtrados por outros motivos

Visualizando na WebUI:

Ao navegar pelos datasets no navegador de arquivos da WebUI, selecionar um diretório com um dataset existente exibirá estatísticas de filtragem, se disponíveis. Isso ajuda a diagnosticar por que seu dataset pode ter menos amostras utilizáveis do que o esperado.

Solucionando problemas de arquivos filtrados:

Se muitos arquivos estão sendo filtrados como too_small: 1. Verifique sua configuração de minimum_image_size — deve corresponder a resolution e resolution_type 2. Para resolution_type=pixel, minimum_image_size é o comprimento mínimo da borda mais curta 3. Para resolution_type=area ou pixel_area, minimum_image_size é a área total mínima

Veja a seção Solução de Problemas abaixo para mais detalhes.

`slider_strength`¶

Valores: Qualquer valor float (positivo, negativo ou zero)
Descrição: Marca um dataset para treinamento de slider LoRA, que aprende "opostos" contrastivos para criar adapters de conceitos controláveis.
Valores positivos (ex.: 0.5): "Mais do conceito" — olhos mais brilhantes, sorriso mais forte, etc.
Valores negativos (ex.: -0.5): "Menos do conceito" — olhos mais opacos, expressão neutra, etc.
Zero ou omitido: Exemplos neutros que não empurram o conceito em nenhuma direção.
Nota: Quando datasets têm valores de slider_strength, o SimpleTuner alterna batches em um ciclo fixo: positivo → negativo → neutro. Dentro de cada grupo, as probabilidades padrão do backend ainda se aplicam.
Veja também: SLIDER_LORA.md para um guia completo sobre configuração de treinamento de slider LoRA.

`vae_cache_clear_each_epoch`¶

Quando habilitado, todos os objetos de cache do VAE são deletados do sistema de arquivos no final de cada ciclo de repeats do dataset. Isso pode ser intensivo em recursos para datasets grandes, mas combinado com crop_style=random e/ou crop_aspect=random você vai querer isso habilitado para garantir que uma faixa completa de cortes seja amostrada de cada imagem.
Na verdade, esta opção é habilitada por padrão ao usar bucketing ou cortes aleatórios.

`vae_cache_ondemand`¶

Valores: true | false
Descrição: Quando habilitado em um dataset, latentes VAE ausentes são codificados durante o treinamento e gravados no cache VAE desse dataset, em vez de serem pré-computados na inicialização.
Nota: A opção global --vae_cache_ondemand ainda se aplica a todos os datasets. Use esta opção de dataset quando a opção global estiver falsa e apenas datasets selecionados devam codificar latentes VAE sob demanda.

`vae_cache_disable`¶

Valores: true | false
Descrição: Quando habilitado em um dataset, esse dataset codifica latentes VAE sob demanda e não grava em disco os latentes recém-gerados. Isso é útil para datasets grandes em que espaço em disco é uma preocupação ou a escrita é impraticável.
Nota: A opção global --vae_cache_disable ainda se aplica a todos os datasets. Use esta opção de dataset para desativar a escrita do cache VAE apenas em datasets selecionados quando a opção global estiver falsa. A grafia removida disable_vae_cache é rejeitada; use vae_cache_disable.

Escolhendo uma estratégia de cache VAE¶

vae_cache_ondemand troca tempo de inicialização por trabalho durante o treinamento; não é uma otimização de VRAM. Escolha a estratégia por dataset com base no reuso esperado do cache e na possibilidade de manter o VAE disponível durante o treinamento:

Dataset extremamente grande e reutilizável: Defina vae_cache_ondemand=true quando uma passagem completa de pré-cache atrasaria demais o treinamento. O treinamento começa sem esperar por todas as imagens, e cada latente ausente é gravado no cache para ser reutilizado em acessos posteriores.
Dataset de resolução muito alta: Mantenha vae_cache_ondemand=false (e a opção global falsa) quando a codificação VAE puder causar OOM com o modelo de treinamento carregado. O pré-cache padrão na inicialização permite descarregar o VAE antes do treinamento. Nem o modo sob demanda nem vae_cache_disable resolvem essa limitação de memória, pois ambos exigem codificação VAE durante o treinamento. Tiling ou slicing do VAE pode reduzir o pico de memória durante o pré-cache inicial.
Dataset em escala web com pouco reuso esperado: Defina vae_cache_disable=true quando o dataset contiver milhões ou bilhões de imagens e for improvável que a execução planejada se aproxime de uma época. As imagens amostradas continuam sendo codificadas sob demanda, mas as gravações de cache e o crescimento do armazenamento são evitados quando a maioria dos latentes nunca seria lida novamente. O requisito de memória do VAE durante o treinamento é o mesmo do cache sob demanda.

`skip_file_discovery`¶

Você provavelmente não quer definir isso - ele é útil apenas para datasets muito grandes.
Este parâmetro aceita uma lista separada por vírgulas ou espaços de valores, por exemplo vae metadata aspect text para pular a descoberta de arquivos em uma ou mais etapas da configuração do loader.
Isso é equivalente à opção de linha de comando --skip_file_discovery
Isso é útil se você tiver datasets que não precisam ser escaneados pelo trainer a cada inicialização, por exemplo, seus latentes/embeds já estão totalmente em cache. Isso permite uma inicialização e retomada de treinamento mais rápidas.

`preserve_data_backend_cache`¶

Você provavelmente não quer definir isso - ele é útil apenas para datasets AWS muito grandes.
Assim como skip_file_discovery, esta opção pode ser definida para evitar escaneamentos de sistema de arquivos desnecessários, longos e caros na inicialização.
Ela recebe um valor booleano, e se definida como true, o arquivo de cache da lista do sistema de arquivos gerado não será removido no lançamento.
Isso é útil para sistemas de armazenamento muito grandes e lentos, como S3 ou discos rígidos locais SMR com tempos de resposta extremamente lentos.
Além disso, no S3, a listagem do backend pode acumular custos e deve ser evitada.

⚠️ Infelizmente, isso não pode ser definido se os dados estiverem sendo alterados ativamente. O trainer não verá novos dados adicionados ao pool; será necessário fazer outra varredura completa.

`hash_filenames`¶

Os nomes de arquivos das entradas do cache do VAE são sempre hash. Isso não é configurável pelo usuário e garante que datasets com nomes de arquivo muito longos possam ser usados facilmente sem problemas de comprimento de caminho. Qualquer configuração hash_filenames no seu arquivo será ignorada.

Grounding (Anotacoes Espaciais)¶

O pipeline de grounding permite anotacoes de bounding box e mascara por entidade para grounding espacial durante o treinamento. Isso e util para prevenir o sangramento de sujeitos (subject bleeding) durante o fine-tuning com multiplos sujeitos.

Habilitando o grounding¶

Adicione um bloco grounding a qualquer dataset de imagem ou video:

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

Voce tambem deve definir --max_grounding_entities para um valor maior que 0 (por exemplo, 8) para habilitar o pipeline de grounding.

Auto-deteccao de bounding boxes¶

Se voce nao possui anotacoes .bbox pre-existentes, pode deixar o SimpleTuner gera-las automaticamente usando Florence-2. Adicione um bloco auto_detect dentro da configuracao 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
        }
    }
}

Chave	Padrao	Descricao
`enabled`	`false`	Habilitar auto-deteccao.
`model`	`florence-community/Florence-2-large`	ID do modelo HuggingFace Florence-2.
`labels`	`[]`	Lista opcional de labels de entidades para deteccao guiada (usa `<OPEN_VOCABULARY_DETECTION>`). Quando vazia, Florence-2 gera automaticamente uma descricao de cada imagem e localiza as frases encontradas (usa `<CAPTION>` + `<CAPTION_TO_PHRASE_GROUNDING>`).
`batch_size`	`4`	Numero de imagens por lote de inferencia.

A auto-deteccao e executada uma vez durante a configuracao do dataset. Imagens que ja possuem um arquivo sidecar .bbox sao ignoradas, permitindo retomar com seguranca apos uma interrupcao. O modelo e carregado no dispositivo do acelerador e liberado imediatamente apos a conclusao da deteccao.

Nota: A auto-deteccao suporta apenas backends type: "local".

Arquivos sidecar `.bbox`¶

Coloque um arquivo .bbox ao lado de cada imagem com o mesmo nome base.

O arquivo .bbox suporta tres formatos: array JSON, JSON lines, formato txt YOLO.

As coordenadas do bounding box sao normalizadas para [0, 1] no formato XYXY. O formato YOLO usa XYWH baseado no centro e e convertido automaticamente. O campo mask e opcional.

Coluna bbox Parquet / HuggingFace¶

Para datasets parquet ou HuggingFace, especifique um bbox_column na configuracao do backend.

Filtragem de amostras¶

`filter_func`¶

filter_func pode ser configurado no nível superior de qualquer backend de dataset para pular amostras antes da criação dos buckets de metadados e caches VAE. Backends Hugging Face ainda aceitam o local antigo huggingface.filter_func, mas o valor de nível superior tem prioridade quando ambos existem.

Filtros suportados:

collection: lista permitida com correspondência exata para o campo collection de uma linha.
quality_thresholds: valores numéricos mínimos dentro de quality_column (padrão: quality_assessment).
min_width / min_height: dimensões mínimas da linha quando campos de largura e altura existem.
path_include / path_exclude: filtragem por nome de arquivo/caminho para datasets local, AWS, CSV, Hugging Face, parquet e Webshart. path_include é uma lista permitida e path_exclude uma lista bloqueada. Exclusões vencem se ambas coincidirem.
path_match: modo de correspondência de caminhos. auto (padrão para chaves planas) usa substring para texto simples, glob para * e ?, e regex para padrões com prefixo re:. Também é possível usar contains, glob, regex ou exact.

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

A forma antiga aninhada filter_func.path.include / exclude / mode continua aceita para configs existentes, mas novas configs devem usar as chaves planas acima.

Filtragem de captions¶

`caption_filter_list`¶

Apenas para datasets de text embeds. Pode ser uma lista JSON, um caminho para um arquivo txt ou um caminho para um documento JSON. Strings de filtro podem ser termos simples para remover de todas as captions, ou podem ser expressões regulares. Além disso, entradas no estilo sed s/search/replace/ podem ser usadas para substituir strings na caption em vez de simplesmente removê-las.

Exemplo de lista de filtros¶

Um exemplo completo pode ser encontrado aqui. Ele contém strings repetitivas e negativas comuns que seriam retornadas por BLIP (variações comuns), LLaVA e CogVLM.

Este é um exemplo reduzido, que será explicado abaixo:

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

Em ordem, as linhas se comportam da seguinte forma:

arafed (com um espaço ao final) será removido de qualquer caption em que for encontrado. Incluir um espaço ao final faz a caption ficar mais bonita, já que não sobrará espaço duplo. Isso não é necessário, mas fica bonito.
this .* has a é uma expressão regular que removerá qualquer coisa que contenha "this ... has a", incluindo qualquer texto entre essas duas strings; .* é uma expressão regular que significa "tudo o que encontramos" até encontrar a string "has a", quando para de casar.
^this is the beginning of the string removerá a frase "this is the beginning of the string" de qualquer caption, mas apenas quando ela aparecer no início da caption.
s/this/will be found and replaced/ fará com que a primeira ocorrência do termo "this" em qualquer caption seja substituída por "will be found and replaced".

❗Use regex 101 para ajuda ao depurar e testar expressões regulares.

Técnicas avançadas¶

Exemplo avançado de configuração¶

[
  {
    "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"
  }
]

Treinar diretamente a partir de uma lista de URLs em CSV¶

Nota: Seu CSV deve conter as captions para suas imagens.

⚠️ Este é um recurso avançado e experimental, e você pode encontrar problemas. Se isso acontecer, abra uma issue!

Em vez de baixar seus dados manualmente a partir de uma lista de URLs, talvez você queira conectá-los diretamente ao trainer.

Nota: É sempre melhor baixar os dados de imagem manualmente. Outra estratégia para economizar espaço em disco local pode ser tentar usar armazenamento em nuvem com caches locais de encoder.

Vantagens¶

Não é necessário baixar os dados diretamente
Pode usar o toolkit de captions do SimpleTuner para legendar diretamente a lista de URLs
Economiza espaço em disco, já que apenas image embeds (se aplicável) e text embeds são armazenados

Desvantagens¶

Requer uma varredura de buckets de aspecto custosa e potencialmente lenta, onde cada imagem é baixada e seus metadados coletados
As imagens baixadas são armazenadas em cache no disco, o que pode crescer muito. Esta é uma área de melhoria, pois o gerenciamento de cache nesta versão é bem básico, apenas grava e nunca deleta
Se seu dataset tiver muitas URLs inválidas, isso pode desperdiçar tempo ao retomar pois, atualmente, amostras ruins nunca são removidas da lista de URLs
Sugestão: Execute uma tarefa de validação de URLs antes e remova amostras ruins.

Configuração¶

Chaves obrigatórias:

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
    }
]

Estratégia de captions Parquet e datasets JSON Lines¶

⚠️ Este é um recurso avançado e não será necessário para a maioria dos usuários.

Ao treinar um modelo com um dataset muito grande, com centenas de milhares ou milhões de imagens, é mais rápido armazenar seus metadados dentro de um banco parquet em vez de arquivos txt - especialmente quando seus dados de treinamento são armazenados em um bucket S3.

Usar a estratégia de captions parquet permite nomear todos os seus arquivos pelo valor id e alterar a coluna de caption via um valor de configuração em vez de atualizar muitos arquivos de texto ou ter que renomear os arquivos para atualizar suas captions.

Aqui está um exemplo de configuração de dataloader que faz uso das captions e dos dados do 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"
}

Nesta configuração:

caption_strategy é definido como parquet.
metadata_backend é definido como parquet.
Uma nova seção, parquet, deve ser definida:
path é o caminho para o arquivo parquet ou JSONL.
filename_column é o nome da coluna na tabela que contém os nomes dos arquivos. Neste caso, usamos a coluna numérica id (recomendado).
caption_column é o nome da coluna na tabela que contém as captions. Neste caso, usamos a coluna cogvlm_caption. Para datasets LAION, isso seria o campo TEXT.
width_column e height_column podem ser colunas contendo strings, int, ou até um tipo de dados Series de uma única entrada, medindo as dimensões reais da imagem. Isso melhora notavelmente o tempo de preparação do dataset, pois não precisamos acessar as imagens reais para descobrir essa informação.
fallback_caption_column é um nome opcional de uma coluna na tabela que contém captions de fallback. Elas são usadas se o campo de caption principal estiver vazio. Neste caso, usamos a coluna tags.
identifier_includes_extension deve ser definido como true quando sua coluna de nome de arquivo contém a extensão da imagem. Caso contrário, a extensão será assumida como .png. É recomendado incluir extensões de arquivo na coluna de nome de arquivo da tabela.

⚠️ O suporte a parquet é limitado à leitura de captions. Você deve preencher separadamente uma fonte de dados com suas amostras de imagem usando "{id}.png" como nome do arquivo. Veja scripts no diretório scripts/toolkit/datasets para ideias.

Como em outras configurações de dataloader:

prepend_instance_prompt e instance_prompt se comportam normalmente.
Atualizar a caption de uma amostra entre execuções de treinamento vai armazenar o novo embed em cache, mas não remover o antigo (órfão).
Quando uma imagem não existe em um dataset, seu nome de arquivo será usado como sua caption e um erro será emitido.

Cache local com dataset na nuvem¶

Para maximizar o uso de armazenamento local NVMe caro, talvez você queira armazenar apenas os arquivos de imagem (png, jpg) em um bucket S3 e usar o armazenamento local para fazer cache dos mapas de recursos extraídos do(s) text encoder(s) e do VAE (se aplicável).

Neste exemplo de configuração:

Dados de imagem são armazenados em um bucket compatível com S3
Dados do VAE são armazenados em /local/path/to/cache/vae
Text embeds são armazenados em /local/path/to/cache/textencoder

⚠️ Lembre-se de configurar as outras opções do dataset, como resolution e 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: O dataset image_embeds não tem opções para definir caminhos de dados. Eles são configurados via cache_dir_vae no backend de imagem.

Suporte a Hugging Face Datasets¶

O SimpleTuner agora suporta carregar datasets diretamente do Hugging Face Hub sem baixar o dataset inteiro localmente. Esse recurso experimental é ideal para:

Datasets em grande escala hospedados no Hugging Face
Datasets com metadados e avaliações de qualidade embutidos
Experimentação rápida sem requisitos de armazenamento local

Para documentação completa sobre este recurso, consulte este documento.

Para um exemplo básico de como usar um dataset do Hugging Face, defina "type": "huggingface" na sua configuração de 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 a preparação do cache VAE, o Webshart processa todos os grupos de proporção de um shard antes de passar ao próximo. Isso reduz downloads repetidos quando o cache de shards inteiros não comporta todo o conjunto de dados. Amostras já armazenadas e amostras atribuídas a outros ranks são excluídas antes do agrupamento; a ordem do amostrador de treinamento permanece inalterada.

As legendas podem ser strings, objetos JSON nativos ou listas mistas dos dois. Os objetos são preservados nos metadados e no cache; cada objeto vira um único prompt de texto JSON ao preparar a entrada do codificador de texto. Os campos não são tratados como variantes separadas. Use uma lista para alternativas ou webshart.caption_key para selecionar um campo. Isso exige uma versão do webshart com suporte a legendas JSON nativas e funciona com o canonicalizador de legendas estruturadas do Ideogram.

Datasets Webshart carregam shards tar no estilo WebDataset pelo pacote webshart. Esse backend usa metadados de amostras lógicas para bucketing de aspecto, então sidecars JSON pareados não são tratados como amostras treináveis.

{
  "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 é obrigatório e aponta para uma fonte que o Webshart consiga descobrir.
metadata é opcional e pode apontar para metadados separados com captions. Para repos Hugging Face de metadata como webshart/conceptual-captions-12m-webdataset-metadata, passe o repo id; o Webshart segue o layout de subpastas do source, como data/.
metadata_backend deve ser webshart; caption_strategy deve ser webshart ou instanceprompt.
webshart.cache_dir armazena os metadados do SimpleTuner e os caches do Webshart. shard_cache_gb e parallel_downloads são passados ao cache de shards do Webshart; defina shard_cache_gb como 0 para desativar o cache de shards completos e manter leituras por intervalo indexadas.
webshart.caption_key permite selecionar campos de caption: use "long_caption" para uma chave ou ["long_caption", "short_caption"] para coletar várias na ordem indicada. As chaves são nomes literais, buscados nos metadados JSON da amostra, depois nos metadados do índice e, por fim, nas entradas nomeadas dos respectivos dicionários captions; vale o primeiro local que contém a chave. Valores de texto e listas tornam-se variantes de caption, sem serem concatenados em um único prompt. Valores ausentes ou vazios são ignorados; com caption_strategy: "webshart", amostras sem captions selecionadas são ignoradas mesmo que tenham captions padrão ou um sidecar .txt. Omitir a opção mantém a busca padrão. Sidecars JSON são lidos quando seu conteúdo não está no índice. As caches de captions e buckets são separadas conforme o seletor configurado. Nas configurações Webshart da WebUI, insira uma chave por linha. A leitura de sidecars JSON usa o cache de shards configurado no Webshart; a busca de captions não decodifica nem materializa os dados de imagem.
webshart_optimize_captions (grafia alternativa webshart_optimise_captions; também aceito como optimize_captions/optimise_captions dentro do bloco webshart) sonda o layout de captions na inicialização e, quando os captions ficam em membros tar sidecar .txt/.json em vez do índice de metadados, consolida-os uma única vez no cache local de metadados do Webshart. Sem essa opção, datasets com captions em sidecars (por exemplo laion/conceptual-captions-12m-webdataset) pagam uma leitura por intervalo por amostra sempre que os captions são enumerados — na inicialização, nos checkpoints e na geração do model card. Datasets cujos metadados já embutem os captions pulam a consolidação automaticamente.

Otimizando captions com antecedência¶

A mesma consolidação está disponível na CLI do Webshart, que também pode publicar os metadados reparados para que todos os consumidores do dataset se beneficiem sem a opção em tempo de execução:

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 grava uma árvore de metadados portátil por shard, e --push-to-hub a envia para um repositório de metadata; depois aponte a opção metadata do dataloader para esse repositório. --shard-cache-dir permite que a consolidação reutilize shards totalmente em cache em vez de emitir uma leitura por intervalo para cada sidecar.

Mapeamento personalizado de proporção para resolução¶

Quando o SimpleTuner inicia pela primeira vez, ele gera listas de mapeamento de aspecto específicas de resolução que vinculam um valor decimal de proporção a seu tamanho de pixel alvo.

É possível criar um mapeamento personalizado que force o trainer a se ajustar à sua resolução alvo escolhida em vez de seus próprios cálculos. Essa funcionalidade é fornecida por sua conta e risco, pois pode causar grande dano se configurada incorretamente.

Para criar o mapeamento personalizado:

Crie um arquivo que siga o exemplo (abaixo)
Nomeie o arquivo usando o formato aspect_ratio_map-{resolution}.json
Para um valor de configuração resolution=1.0 / resolution_type=area, o nome do arquivo de mapeamento será aspect_resolution_map-1.0.json
Coloque esse arquivo no local especificado como --output_dir
Este é o mesmo local onde seus checkpoints e imagens de validação serão encontrados.
Nenhum flag ou opção adicional de configuração é necessário. Ele será descoberto e usado automaticamente, desde que o nome e o local estejam corretos.

Exemplo de configuração de mapeamento¶

Este é um exemplo de mapeamento de proporção gerado pelo SimpleTuner. Você não precisa configurá-lo manualmente, pois o trainer criará um automaticamente. No entanto, para controle total sobre as resoluções resultantes, esses mapeamentos são fornecidos como ponto de partida para modificação.

O dataset tinha mais de 1 milhão de imagens
O resolution do dataloader foi definido como 1.0
O resolution_type do dataloader foi definido como area

Esta é a configuração mais comum e a lista de buckets de aspecto treináveis para um modelo de 1 megapixel.

{
    "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 Stable Diffusion 1.5 / 2.0-base (512px), o mapeamento a seguir 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]
}

Arquivo de configuração do dataloader¶

Opções de configuração¶

id¶

disabled¶

dataset_type¶

caption_file_extensions¶

data_generator¶

default¶

cache_dir¶

train_batch_size¶

write_batch_size¶

text_encoder_batch_size¶

text_cache_ondemand¶

text_cache_disable¶

text_embeds¶

image_embeds¶

conditioning_image_embeds¶

cache_dir_conditioning_image_embeds¶

conditioning_image_embed_batch_size¶

Configuração de dataset de áudio (dataset_type=audio)¶

Configuração de áudio para treinamento S2V¶

Captions de áudio (Hugging Face)¶

type¶

Backends em memória (tmpfs e RAM disk)¶

conditioning_type¶

source_dataset_id¶

conditioning_data¶

data_transforms¶

instance_data_dir / aws_data_prefix¶

caption_strategy¶

disable_multiline_split¶

caption_shuffle¶

metadata_backend¶

metadata_update_interval¶

Opções de corte¶

resolution¶

minimum_image_size¶

minimum_aspect_ratio¶

maximum_aspect_ratio¶

conditioning¶

Tipos de condicionamento disponíveis¶

superresolution¶

sdr / logc3_sdr¶

jpeg_artifacts¶

depth / depth_midas¶

random_masks / inpainting¶

canny / edges¶

Exemplos¶

Dataset de vídeo¶

Configuração¶

Resultado¶

Configuração¶

Resultado¶

Configuração¶

Resultado¶

maximum_image_size e target_downsample_size¶

Exemplos¶

Configuração¶

Resultado¶

max_upscale_threshold¶

Exemplos¶

Configuração¶

Resultado¶

Configuração¶

Resultado¶

prepend_instance_prompt¶

only_instance_prompt¶

timestep_sampling_offset¶

repeats¶

Treinamento multi-GPU e dimensionamento de dataset¶

Oversubscription automática de dataset¶

max_num_samples¶

Exemplo¶

start_epoch / start_step¶

end_epoch / end_step¶

is_regularisation_data¶

delete_unwanted_images¶

delete_problematic_images¶

delete_nsfw_images¶

Verificações de classificador NSFW durante o cache VAE¶

`id`¶

`disabled`¶

`dataset_type`¶

`caption_file_extensions`¶

`data_generator`¶

`default`¶

`cache_dir`¶

`train_batch_size`¶

`write_batch_size`¶

`text_encoder_batch_size`¶

`text_cache_ondemand`¶

`text_cache_disable`¶

`text_embeds`¶

`image_embeds`¶

`conditioning_image_embeds`¶

`cache_dir_conditioning_image_embeds`¶

`conditioning_image_embed_batch_size`¶

Configuração de dataset de áudio (`dataset_type=audio`)¶

`type`¶

`conditioning_type`¶

`source_dataset_id`¶

`conditioning_data`¶

`data_transforms`¶

`instance_data_dir` / `aws_data_prefix`¶

`caption_strategy`¶

`disable_multiline_split`¶

`caption_shuffle`¶

`metadata_backend`¶

`metadata_update_interval`¶

`resolution`¶

`minimum_image_size`¶

`minimum_aspect_ratio`¶

`maximum_aspect_ratio`¶

`conditioning`¶

`superresolution`¶

`sdr` / `logc3_sdr`¶

`jpeg_artifacts`¶

`depth` / `depth_midas`¶

`random_masks` / `inpainting`¶

`canny` / `edges`¶

`maximum_image_size` e `target_downsample_size`¶

`max_upscale_threshold`¶

`prepend_instance_prompt`¶

`only_instance_prompt`¶

`timestep_sampling_offset`¶

`repeats`¶

`max_num_samples`¶

`start_epoch` / `start_step`¶

`end_epoch` / `end_step`¶

`is_regularisation_data`¶

`delete_unwanted_images`¶

`delete_problematic_images`¶

`delete_nsfw_images`¶

`slider_strength`¶

`vae_cache_clear_each_epoch`¶

`vae_cache_ondemand`¶

`vae_cache_disable`¶

`skip_file_discovery`¶

`preserve_data_backend_cache`¶

`hash_filenames`¶

Arquivos sidecar `.bbox`¶

`filter_func`¶

`caption_filter_list`¶