TL;DR

Usa diffusion-pipe en Linux o WSL2 — Windows nativo es difícil/imposible para el paralelismo de pipeline de DeepSpeed (diffusion-pipe README). Prepara 30–300 imágenes (Civitai 9967) (512×512, recortadas al personaje, sin texto) con captions .txt coincidentes; para clips de vídeo, diffusion-pipe extrae los fotogramas internamente con el modo single_beginning (diffusion-pipe README). Entrena con lr = 2×10⁻⁴ (diffusion-pipe README), LoRA rank 32, 500–1,500 pasos (Civitai 9967) (máximo 30 epochs) en una sola GPU; espera 1–2 horas en una tarjeta RTX serie 40 (Civitai 9967). Suelo de VRAM: ~19–20 GB a 512×512, ~23 GB a 1024×1024 con transformer fp8, activation checkpointing y batch de 1 (Civitai 9967). Consulta diffusion-pipe setup.

Entrenar un LoRA de personaje de HunyuanVideo

Plataforma y herramientas

En Windows: activa Hyper-V en la BIOS, instala Ubuntu desde Microsoft Store y ejecuta dentro de WSL2. El blog de Runpod tiene un tutorial en la nube (Runpod blog). Consulta también diffusion-pipe setup.

Preparación del dataset: de clips de vídeo a fotogramas con caption

Datasets de imágenes (punto de partida recomendado)

La comunidad trata los LoRAs de personaje como una tarea de entrenamiento de imágenes: alimenta a diffusion-pipe con una carpeta de imágenes estáticas, cada una con un caption .txt coincidente. El entrenador cachea los latents y embeddings de texto una vez, luego entrena el LoRA del transformer sin recargar el VAE ni los text encoders. Consulta character LoRA workflow para principios de diseño del dataset.

Directrices prácticas (reportadas por la comunidad):

• Recorta a 512×512 (Civitai 9967). Se recomienda subir la resolución a 512×512 antes de entrenar; 1024×1024 eleva el uso de VRAM.
• Elimina todo el texto — logotipos, subtítulos, marcas de agua. El texto "arruinó múltiples LoRAs" al grabar títulos en el personaje (Civitai 9967).
• Cobertura con rostros prominentes: prioriza tomas de rostro nítidas; incluye 1–2 imágenes con una segunda persona (sexo opuesto) para que el modelo no fusione identidades (Civitai 9967).
• Relación de aspecto: las relaciones extremas (3:1) se omiten por defecto. Para incluirlas, establece max_ar = 2.5 en dataset.toml (Civitai 9967).

Datasets de clips de vídeo

diffusion-pipe ingiere archivos de vídeo directamente vía ImageIO (todos los formatos excepto WebP multifotograma). Cada clip se agrupa por número de fotogramas, luego se segmenta según video_clip_mode:

Los fotogramas se codifican con el VAE y se cachean con embeddings de texto. No se necesita extracción manual de fotogramas — apunta la configuración a archivos .mp4/.mov con captions .txt coincidentes (diffusion-pipe README).

Limitación: los embeddings precacheados significan que no se admite el entrenamiento de LoRA del text encoder (diffusion-pipe README).

Captioning: automatizando los archivos de texto

Cada archivo multimedia necesita un .txt hermano (p. ej., frame_001.png → frame_001.txt). La comunidad usa modelos de visión-lenguaje para captioning por lotes:

Ejecuta tu captioner sobre el dataset, escribe un .txt por archivo, verifica algunas muestras — la calidad del caption afecta directamente a la fidelidad del LoRA. Consulta captioning guide.

Ajustes del entrenador: desglose de la configuración de diffusion-pipe

La siguiente configuración fusiona los valores por defecto de diffusion-pipe con valores ajustados por la comunidad para LoRAs de personaje fiables en RTX serie 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'

# Ahorradores de VRAM (actívalos todos para tarjetas 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

Lanzamiento (RTX serie 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: entrenamiento vs. inferencia

El entrenamiento cabe en 24 GB mientras la inferencia necesita 30–60 GB porque el entrenamiento se ejecuta a 512×512 (no 720p), procesa una muestra a la vez y mantiene solo los pesos del LoRA del transformer en la GPU. La cuantización FP8, el checkpointing unsloth y el intercambio de bloques reducen aún más la memoria. La inferencia debe mantener el transformer completo, el VAE y ambos text encoders a la resolución objetivo (Civitai 9967; HunyuanVideo GitHub).

Errores comunes y correcciones

FAQ

¿Cuánta VRAM necesito para entrenar un LoRA de HunyuanVideo?

19–20 GB a 512×512 con transformer FP8, checkpointing unsloth e intercambio de bloques. Una tarjeta de 24 GB (RTX 3090/4090) tiene margen cómodo; 1024×1024 sube a ~23 GB con poco margen (Civitai 9967).

¿Puedo entrenar en una GPU de 24 GB?

Sí. La comunidad reporta éxito en RTX 3090/4090 (24 GB) a 512×512. Activa los tres ahorradores de VRAM: transformer_dtype = 'float8', activation_checkpointing = 'unsloth', blocks_to_swap = 20 (diffusion-pipe README).

¿Cómo extraigo fotogramas del vídeo para el entrenamiento de LoRA?

No lo haces tú — diffusion-pipe lo hace internamente. Coloca archivos .mp4/.mov en tu carpeta del dataset con captions .txt coincidentes, establece video_clip_mode = 'single_beginning' (por defecto) y el entrenador extrae, codifica y cachea los fotogramas automáticamente (diffusion-pipe README).

¿Qué modelo de captioning debo usar?

Florence-2 es el más rápido y común. Llama-Vision da calidad similar. Para clips de vídeo, Meta Apollo funciona bien en segmentos cortos (Civitai 9967). Los tres son VLM que ejecutas localmente o vía API para producir un .txt por archivo multimedia.

¿Cuál es el tamaño mínimo del dataset?

30 imágenes es el suelo de la comunidad (Civitai 9967). Hasta 300+ funciona, pero cada imagen aumenta el tiempo de cacheo y los pasos necesarios.

¿Cuánto tiempo tarda el entrenamiento?

1–2 horas en RTX serie 40 para 500–1,500 pasos a 512×512. Gran parte de ese tiempo es la pasada única de cacheo de latents/texto; las reejecuciones con el mismo dataset omiten el cacheo vía --trust_cache (diffusion-pipe README).

¿Qué learning rate debo usar?

El valor por defecto es 2×10⁻⁵; la comunidad usa 2×10⁻⁴ (10× más alto) para LoRAs de personaje con convergencia más rápida. Comienza en 2×10⁻⁴ con warmup_steps = 100 (diffusion-pipe README).

¿Funciona diffusion-pipe en Windows?

No de forma nativa. El paralelismo de pipeline de DeepSpeed es difícil/imposible en Windows nativo. Usa WSL2 (Ubuntu) con Hyper-V activado, o Linux/nube. El blog de Runpod tiene una guía en la nube (Runpod blog). Para más ayuda, consulta VRAM optimization tips.

Para más lectura sobre optimización de modelos, consulta LoRA training best practices.