Treine uma LoRA de Personagem HunyuanVideo

Plataforma e Ferramentas

No Windows: habilite Hyper-V na BIOS, instale Ubuntu da Microsoft Store, rode dentro do WSL2. O blog Runpod tem um guia na nuvem (Runpod blog). Veja também configuração do diffusion-pipe.

Preparação do Dataset: De Clipes de Vídeo a Frames Legendados

Datasets de imagens (ponto de partida recomendado)

A comunidade trata LoRAs de personagem como uma tarefa de treinamento com imagens — alimente o diffusion-pipe com uma pasta de imagens estáticas, cada uma com uma .txt de legenda correspondente. O trainer faz cache de latentes e embeddings de texto uma vez, depois treina a LoRA do transformer sem recarregar o VAE ou codificadores de texto. Veja fluxo de trabalho de LoRA de personagem HunyuanVideo para princípios de design do dataset.

Diretrizes práticas (reportadas pela comunidade):

• Recorte para 512×512 (Civitai 9967). Upscaling para 512×512 antes do treinamento é encorajado; 1024×1024 empurra VRAM mais alto.
• Remova todo texto — logos, legendas, marcas d'água. Texto "estragou múltiplas LoRAs" gravando títulos no personagem (Civitai 9967).
• Cobertura pesada de rosto: priorize fotos claras do rosto; inclua 1–2 imagens com uma segunda pessoa (sexo oposto) para que o modelo não funda identidades (Civitai 9967).
• Proporção: proporções extremas (3:1) são ignoradas por padrão. Para incluí-las, defina max_ar = 2.5 no dataset.toml (Civitai 9967).

Datasets de clipes de vídeo

O diffusion-pipe ingere arquivos de vídeo diretamente via ImageIO (todos formatos exceto WebP multiframe). Cada clip é agrupado por contagem de frames, depois segmentado por video_clip_mode:

Frames são codificados pelo VAE e cacheados com embeddings de texto. Extração manual de frames não é necessária — aponte o config para arquivos .mp4/.mov com .txt de legenda correspondentes (diffusion-pipe README).

Limitação: Embeddings pré-cacheados significam que treinamento de LoRA do text-encoder não é suportado (diffusion-pipe README).

Legenda: Automatizando os Arquivos de Texto

Cada arquivo de mídia precisa de um .txt irmão (ex.: frame_001.png → frame_001.txt). A comunidade usa modelos de visão-linguagem para legenda em lote:

Rode seu legenda sobre o dataset, escreva um .txt por arquivo, verifique algumas amostras — qualidade da legenda afeta diretamente a fidelidade da LoRA. Veja guia de legenda.

Configurações do Trainer: Breakdown do Config diffusion-pipe

O config abaixo mescla padrões do diffusion-pipe com valores ajustados pela comunidade para LoRAs de personagem confiáveis em RTX série 40 (Civitai 9967).

# main_example.toml (adaptado)
output_dir = '/path/to/training_runs'
dataset = 'examples/dataset.toml'

epochs = 30
max_steps = 1500
micro_batch_size_per_gpu = 1
pipeline_stages = 1
gradient_accumulation_steps = 1
gradient_clipping = 1.0
warmup_steps = 100
lr_scheduler = 'constant'

# Economizadores de VRAM (ative todos para placas de 24 GB)
activation_checkpointing = 'unsloth'
blocks_to_swap = 20
PYTORCH_CUDA_ALLOC_CONF = 'expandable_segments:True'

video_clip_mode = 'single_beginning'
save_every_n_epochs = 2
checkpoint_every_n_minutes = 120

[model]
type = 'hunyuan-video'
transformer_path = '/path/to/hunyuan_video_720_cfgdistill_fp8_e4m3fn.safetensors'
vae_path = '/path/to/hunyuan_video_vae_bf16.safetensors'
llm_path = '/path/to/llava-llama-3-8b-text-encoder-tokenizer'
clip_path = '/path/to/clip-vit-large-patch14'
dtype = 'bfloat16'
transformer_dtype = 'float8'
timestep_sample_method = 'logit_normal'

[adapter]
type = 'lora'
rank = 32
dtype = 'bfloat16'

[optimizer]
type = 'adamw_optimi'
lr = 2e-4
betas = [0.9, 0.99]
weight_decay = 0.01
eps = 1e-8

Lançamento (RTX série 40) (Civitai 9967):

NCCL_P2P_DISABLE=1 NCCL_IB_DISABLE=1 \
deepspeed --num_gpus=1 train.py --deepspeed --config your_config.toml

Requisitos de VRAM: Treinamento vs. Inferência

Treinamento cabe em 24 GB enquanto inferência precisa de 30–60 GB porque treinamento roda em 512×512 (não 720p), processa uma amostra por vez, e mantém apenas os pesos LoRA do transformer na GPU. Quantização FP8, checkpointing unsloth, e troca de blocos reduzem memória ainda mais. Inferência deve segurar transformer completo, VAE, e ambos codificadores de texto na resolução alvo (Civitai 9967; HunyuanVideo GitHub).

Erros Comuns e Correções

FAQ

Quanta VRAM preciso para treinar uma LoRA HunyuanVideo?

19–20 GB em 512×512 com transformer FP8, checkpointing unsloth, e troca de blocos. Placa de 24 GB (RTX 3090/4090) tem folga confortável; 1024×1024 empurra para ~23 GB com pouca margem (Civitai 9967).

Posso treinar em GPU de 24 GB?

Sim. Comunidade reporta sucesso em RTX 3090/4090 (24 GB) em 512×512. Ative os três economizadores de VRAM: transformer_dtype = 'float8', activation_checkpointing = 'unsloth', blocks_to_swap = 20 (diffusion-pipe README).

Como extraio frames de vídeo para treinamento LoRA?

Você não extrai — o diffusion-pipe faz internamente. Coloque arquivos .mp4/.mov na pasta do dataset com .txt de legenda correspondentes, defina video_clip_mode = 'single_beginning' (padrão), e o trainer extrai, codifica, e cacheia frames automaticamente (diffusion-pipe README).

Qual modelo de legenda devo usar?

Florence-2 é o mais rápido e comum. Llama-Vision dá qualidade similar. Para clipes de vídeo, Meta Apollo funciona bem em segmentos curtos (Civitai 9967). Todos três são VLMs que você roda localmente ou via API para produzir um .txt por arquivo de mídia.

Qual o tamanho mínimo do dataset?

30 imagens é o piso da comunidade (Civitai 9967). Até 300+ funciona mas cada imagem aumenta tempo de cache e passos necessários.

Quanto tempo o treinamento leva?

1–2 horas em RTX série 40 para 500–1.500 passos em 512×512. Grande parte é a passagem única de cache de latentes/texto; re-execuções com mesmo dataset pulam cache via --trust_cache (diffusion-pipe README).

Qual taxa de aprendizado devo usar?

Padrão é 2×10⁻⁵; comunidade usa 2×10⁻⁴ (10× maior) para LoRAs de personagem com convergência mais rápida. Comece em 2×10⁻⁴ com warmup_steps = 100 (diffusion-pipe README).

O diffusion-pipe funciona no Windows?

Não nativamente. Paralelismo de pipeline DeepSpeed é difícil/impossível no Windows nativo. Use WSL2 (Ubuntu) com Hyper-V habilitado na BIOS, ou Linux/nuvem. O blog Runpod tem guia voltado para nuvem (Runpod blog). Para mais ajuda, veja dicas de otimização VRAM.

Para leitura adicional sobre otimização de modelo, veja melhores práticas de treinamento LoRA.