Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /main /es /training /cogvideox.md
mishig
1 day ago
preview code
download
raw
22.1 kB
# CogVideoX

CogVideoX es un modelo de generación de video a partir de texto centrado en la creación de videos más coherentes y alineados con un prompt. Lo logra mediante varios métodos.

- un autoencoder variacional 3D que comprime videos espacial y temporalmente, mejorando la tasa de compresión y la precisión del video.

- un bloque transformer experto para ayudar a alinear texto y video, y un módulo de atención completa 3D para capturar y crear videos espacial y temporalmente precisos.

La prueba real de la dimensión de instrucciones de video reveló que CogVideoX tiene buenos resultados en tema coherente, información dinámica, fondo coherente, información de objetos, movimiento fluido, color, escena, estilo de apariencia y estilo temporal, pero no logra buenos resultados con la acción humana, la relación espacial y múltiples objetos.

El ajuste fino con Diffusers puede ayudar a compensar estos resultados deficientes.

## Preparación de datos

Los scripts de entrenamiento aceptan datos en dos formatos.

El primer formato es adecuado para el entrenamiento a pequeña escala, y el segundo formato utiliza un formato CSV, que es más apropiado para el procesamiento de datos en streaming para el entrenamiento a gran escala. En el futuro, Diffusers admitirá la etiqueta `<Video>`.

### Formato pequeño

Dos archivos, donde uno contiene prompts separados por líneas y el otro contiene rutas separadas por líneas hacia los datos de video (la ruta a los archivos de video debe ser relativa a la ruta que se pasa al especificar `--instance_data_root`). ¡Echemos un vistazo a un ejemplo para entenderlo mejor!

Supongamos que has especificado `--instance_data_root` como `/dataset` y que este directorio contiene los archivos: `prompts.txt` y `videos.txt`.

El archivo `prompts.txt` debe contener prompts separados por líneas:

```
A black and white animated sequence featuring a rabbit, named Rabbity Ribfried, and an anthropomorphic goat in a musical, playful environment, showcasing their evolving interaction.
A black and white animated sequence on a ship's deck features a bulldog character, named Bully Bulldoger, showcasing exaggerated facial expressions and body language. The character progresses from confident to focused, then to strained and distressed, displaying a range of emotions as it navigates challenges. The ship's interior remains static in the background, with minimalistic details such as a bell and open door. The character's dynamic movements and changing expressions drive the narrative, with no camera movement to distract from its evolving reactions and physical gestures.
...
```

El archivo `videos.txt` debe contener rutas a archivos de video separadas por líneas. Tenga en cuenta que la ruta debe ser _relativa_ al directorio `--instance_data_root`.

```
videos/00000.mp4
videos/00001.mp4
...
```

En general, así se vería tu conjunto de datos si ejecutaras el comando `tree` en el directorio raíz del conjunto de datos:

```
/dataset
├── prompts.txt
├── videos.txt
├── videos
    ├── videos/00000.mp4
    ├── videos/00001.mp4
    ├── ...
```

Al usar este formato, `--caption_column` debe ser `prompts.txt` y `--video_column` debe ser `videos.txt`.

### Formato de transmisión

Podrías usar un único archivo CSV. Por el bien de este ejemplo, asume que tienes un archivo `metadata.csv`. El formato esperado es:

```
<CAPTION_COLUMN>,<PATH_TO_VIDEO_COLUMN>
"""A black and white animated sequence featuring a rabbit, named Rabbity Ribfried, and an anthropomorphic goat in a musical, playful environment, showcasing their evolving interaction.""","""00000.mp4"""
"""A black and white animated sequence on a ship's deck features a bulldog character, named Bully Bulldoger, showcasing exaggerated facial expressions and body language. The character progresses from confident to focused, then to strained and distressed, displaying a range of emotions as it navigates challenges. The ship's interior remains static in the background, with minimalistic details such as a bell and open door. The character's dynamic movements and changing expressions drive the narrative, with no camera movement to distract from its evolving reactions and physical gestures.""","""00001.mp4"""
...
```

En este caso, `--instance_data_root` debe ser la ubicación donde se almacenan los videos y `--dataset_name` debe ser una ruta a una carpeta local o un conjunto de datos compatible con [load_dataset](https://huggingface.co/docs/datasets/main/en/package_reference/loading_methods#datasets.load_dataset) alojado en el Hub. Si tienes videos de partidas de Minecraft en `https://huggingface.co/datasets/my-awesome-username/minecraft-videos`, debes especificar `my-awesome-username/minecraft-videos`.

Al usar este formato, `--caption_column` debe ser `<CAPTION_COLUMN>` y `--video_column` debe ser `<PATH_TO_VIDEO_COLUMN>`.

No se limita estrictamente al formato CSV. Cualquier formato es válido siempre que el método `load_dataset` admita el formato de archivo para cargar una columna básica `<PATH_TO_VIDEO_COLUMN>` y `<CAPTION_COLUMN>`. La razón para realizar estas acrobacias de organización de datos al cargar datos de video es que `load_dataset` no admite por completo todos los tipos de formatos de video.

> [!NOTE]
> CogVideoX funciona mejor con prompts largos y descriptivos, aumentados con LLM, para la generación de video. Recomendamos preprocesar los videos generando primero un resumen con un VLM y luego aumentando los prompts con un LLM. Para generar las descripciones anteriores, utilizamos [MiniCPM-V-26](https://huggingface.co/openbmb/MiniCPM-V-2_6) y [Llama-3.1-8B-Instruct](https://huggingface.co/meta-llama/Meta-Llama-3.1-8B-Instruct). Un ejemplo muy básico y sin adornos de este proceso está disponible [aquí](https://gist.github.com/a-r-r-o-w/4dee20250e82f4e44690a02351324a4a). La recomendación oficial para aumentar los prompts es [ChatGLM](https://huggingface.co/THUDM?search_models=chatglm) y se considera adecuado un largo de 50 a 100 palabras.

>![NOTE] Se espera que su conjunto de datos ya esté preprocesado. De lo contrario, se puede realizar un preprocesamiento básico manipulando los siguientes parámetros: `--height`, `--width`, `--fps`, `--max_num_frames`, `--skip_frames_start` y `--skip_frames_end`. Actualmente, todos los videos de su conjunto de datos deben contener el mismo número de fotogramas de video al usar un tamaño de lote de entrenamiento > 1.

## Entrenamiento

Debes configurar tu entorno de desarrollo instalando los requisitos necesarios. Los siguientes paquetes son obligatorios:
- Torch 2.0 o superior, según las funciones de entrenamiento que estés utilizando (es posible que se requieran las versiones más recientes o nocturnas para el entrenamiento cuantizado/deepspeed)
- `pip install diffusers transformers accelerate peft huggingface_hub` para todo lo relacionado con modelado y entrenamiento
- `pip install datasets decord` para cargar datos de entrenamiento de video
- `pip install bitsandbytes` para usar los optimizadores Adam o AdamW de 8 bits para un entrenamiento optimizado en memoria
- `pip install wandb` opcionalmente para supervisar los registros de entrenamiento
- `pip install deepspeed` opcionalmente para el entrenamiento con [DeepSpeed](https://github.com/microsoft/DeepSpeed)
- `pip install prodigyopt` opcionalmente, si deseas usar el optimizador Prodigy para el entrenamiento

Para asegurarse de que puede ejecutar correctamente las últimas versiones de los scripts de ejemplo, le recomendamos encarecidamente **instalar desde el código fuente** y mantener la instalación actualizada, ya que actualizamos los scripts de ejemplo con frecuencia e instalamos algunos requisitos específicos de cada ejemplo. Para hacer esto, ejecute los siguientes pasos en un nuevo entorno virtual:

Antes de ejecutar el script, asegúrate de instalar la biblioteca desde el código fuente:
```bash
git clone https://github.com/huggingface/diffusers
cd diffusers
pip install -e .
```

 

Luego, navegue a la carpeta de ejemplo que contiene el script de entrenamiento e instale las dependencias requeridas para el script que está utilizando:

- PyTorch

```bash
cd examples/cogvideo
pip install -r requirements.txt
```

Y inicializa un entorno de [🤗 Accelerate](https://github.com/huggingface/accelerate/) con:

```bash
accelerate config
```

O para una configuración predeterminada de accelerate sin responder preguntas sobre su entorno

```bash
accelerate config default
```

O si tu entorno no admite una shell interactiva (p. ej., un notebook)

```python
from accelerate.utils import write_basic_config
write_basic_config()
```

Al ejecutar `accelerate config`, si usas torch.compile, es posible obtener mejoras de velocidad significativas. La biblioteca PEFT se utiliza como backend para el entrenamiento con LoRA, así que asegúrate de tener `peft>=0.6.0` instalado en tu entorno.

Si deseas subir tu modelo al Hub después de completar el entrenamiento con una tarjeta de modelo bien presentada, asegúrate de haber iniciado sesión:

```bash
hf auth login
# Alternatively, you could upload your model manually using:
# hf upload my-cool-account-name/my-cool-lora-name /path/to/awesome/lora
```

Asegúrate de que tus datos estén preparados como se describe en [Preparación de datos](#data-preparation). Cuando estés listo, ¡puedes comenzar el entrenamiento!

Suponiendo que estás entrenando con 50 videos de un concepto similar, hemos encontrado que 1500-2000 pasos funcionan bien. Sin embargo, la recomendación oficial es de 100 videos con un total de 4000 pasos. Suponiendo que estás entrenando en una sola GPU con un `--train_batch_size` de `1`:
- 1500 pasos en 50 videos corresponderían a `30` épocas de entrenamiento
- 4000 pasos en 100 vídeos corresponderían a `40` épocas de entrenamiento

```bash
#!/bin/bash
GPU_IDS="0"
accelerate launch --gpu_ids $GPU_IDS examples/cogvideo/train_cogvideox_lora.py \
  --pretrained_model_name_or_path THUDM/CogVideoX-2b \
  --cache_dir <CACHE_DIR> \
  --instance_data_root <PATH_TO_WHERE_VIDEO_FILES_ARE_STORED> \
  --dataset_name my-awesome-name/my-awesome-dataset \
  --caption_column <CAPTION_COLUMN> \
  --video_column <PATH_TO_VIDEO_COLUMN> \
  --id_token <ID_TOKEN> \
  --validation_prompt "<ID_TOKEN> Spiderman swinging over buildings:::A panda, dressed in a small, red jacket and a tiny hat, sits on a wooden stool in a serene bamboo forest. The panda's fluffy paws strum a miniature acoustic guitar, producing soft, melodic tunes. Nearby, a few other pandas gather, watching curiously and some clapping in rhythm. Sunlight filters through the tall bamboo, casting a gentle glow on the scene. The panda's face is expressive, showing concentration and joy as it plays. The background includes a small, flowing stream and vibrant green foliage, enhancing the peaceful and magical atmosphere of this unique musical performance" \
  --validation_prompt_separator ::: \
  --num_validation_videos 1 \
  --validation_epochs 10 \
  --seed 42 \
  --rank 64 \
  --lora_alpha 64 \
  --mixed_precision fp16 \
  --output_dir /raid/aryan/cogvideox-lora \
  --height 480 --width 720 --fps 8 --max_num_frames 49 --skip_frames_start 0 --skip_frames_end 0 \
  --train_batch_size 1 \
  --num_train_epochs 30 \
  --checkpointing_steps 1000 \
  --gradient_accumulation_steps 1 \
  --learning_rate 1e-3 \
  --lr_scheduler cosine_with_restarts \
  --lr_warmup_steps 200 \
  --lr_num_cycles 1 \
  --enable_slicing \
  --enable_tiling \
  --optimizer Adam \
  --adam_beta1 0.9 \
  --adam_beta2 0.95 \
  --max_grad_norm 1.0 \
  --report_to wandb
```

Para hacer un mejor seguimiento de nuestros experimentos de entrenamiento, estamos utilizando las siguientes banderas en el comando anterior:
* `--report_to wandb` asegurará que las ejecuciones de entrenamiento se rastreen en Weights and Biases. Para usarlo, asegúrate de instalar `wandb` con `pip install wandb`.
* `validation_prompt` y `validation_epochs` para permitir que el script realice algunas ejecuciones de inferencia de validación. Esto nos permite comprobar cualitativamente si el entrenamiento avanza como se espera.

No es necesario establecer el `<ID_TOKEN>`. Según algunas pruebas limitadas, hemos encontrado que funciona mejor (ya que se asemeja al entrenamiento de [Dreambooth](./dreambooth)) que sin él. Cuando se proporciona, el `<ID_TOKEN>` se añade al principio de cada prompt. Por lo tanto, si tu `<ID_TOKEN>` era `"DISNEY"` y tu prompt era `"Spiderman swinging over buildings"`, el prompt efectivo utilizado en el entrenamiento sería `"DISNEY Spiderman swinging over buildings"`. Cuando no se proporciona, ya sea que entrenes sin ningún token adicional o que amplíes tu conjunto de datos para aplicar el token donde desees antes de comenzar el entrenamiento.

> [!NOTE]
> Puedes pasar `--use_8bit_adam` para reducir los requisitos de memoria del entrenamiento.

> [!IMPORTANT]
> Los siguientes ajustes se probaron en el momento de añadir el soporte para el entrenamiento de LoRA de CogVideoX: - Nuestras pruebas se realizaron principalmente con CogVideoX-2b. Trabajaremos con CogVideoX-5b y CogVideoX-5b-I2V pronto - Un conjunto de datos compuesto por 70 videos de entrenamiento con resoluciones de `200 x 480 x 720` (F x H x W). A partir de esto, utilizando el salto de fotogramas en la preprocesación de datos, creamos dos conjuntos de datos más pequeños de 49 y 16 fotogramas para una experimentación más rápida y porque el límite máximo recomendado por el equipo de CogVideoX es de 49 fotogramas. De los 70 videos, creamos tres grupos de 10, 25 y 50 videos. Todos los videos eran similares en cuanto a la naturaleza del concepto que se estaba entrenando. - 25 o más videos funcionaron mejor para entrenar nuevos conceptos y estilos. - Descubrimos que es mejor entrenar con un token de identificador que se puede especificar como `--id_token`. Esto es similar al entrenamiento tipo Dreambooth, pero el ajuste fino normal sin dicho token también funciona. - El concepto entrenado parecía funcionar bastante bien cuando se combinaba con prompts completamente no relacionados. Esperamos resultados aún mejores si se realiza un ajuste fino de CogVideoX-5B. - El repositorio original utiliza un `lora_alpha` de `1`. Encontramos que esto no era adecuado en muchas ejecuciones, posiblemente debido a la diferencia en los backends de modelado y los ajustes de entrenamiento. Nuestra recomendación es establecer el `lora_alpha` en `rank` o `rank // 2`. - Si estás entrenando con datos cuyas descripciones generan malos resultados con el modelo original, un `rank` de 64 o superior es bueno y también es la recomendación del equipo detrás de CogVideoX. Si las generaciones ya son moderadamente buenas con tus descripciones de entrenamiento, un `rank` de 16/32 debería funcionar. Encontramos que establecer el rank demasiado bajo, por ejemplo `4`, no es ideal y no produce resultados prometedores. - Los autores de CogVideoX recomiendan 4000 pasos de entrenamiento y 100 videos de entrenamiento en total para lograr el mejor resultado. Si bien eso podría dar los mejores resultados, encontramos en nuestra experimentación limitada que 2000 pasos y 25 videos también podrían ser suficientes. - Al usar el optimizador Prodigy para el entrenamiento, se pueden seguir las recomendaciones de este blog [este](https://huggingface.co/blog/sdxl_lora_advanced_script). Prodigy tiende a sobreajustarse rápidamente. En mis pruebas muy limitadas, encontré que una tasa de aprendizaje de `0.5` es adecuada, además de `--prodigy_use_bias_correction`, `prodigy_safeguard_warmup` y `--prodigy_decouple`. - La tasa de aprendizaje recomendada por los autores de CogVideoX y de nuestra experimentación con Adam/AdamW está entre `1e-3` y `1e-4` para un conjunto de datos de 25 o más videos.
>
> Tenga en cuenta que nuestras pruebas no son exhaustivas debido al tiempo limitado para la exploración. Nuestra recomendación sería experimentar con las distintas opciones y parámetros para encontrar la mejor configuración para sus datos.
## Inferencia
Una vez que hayas entrenado un modelo lora, la inferencia se puede realizar simplemente cargando los pesos lora en el `CogVideoXPipeline`.
```python
import torch
from diffusers import CogVideoXPipeline
from diffusers.utils import export_to_video
pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-2b", dtype=torch.float16)
# pipe.load_lora_weights("/path/to/lora/weights", adapter_name="cogvideox-lora") # Or,
pipe.load_lora_weights("my-awesome-hf-username/my-awesome-lora-name", adapter_name="cogvideox-lora") # If loading from the HF Hub
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Assuming lora_alpha=32 and rank=64 for training. If different, set accordingly
pipe.set_adapters(["cogvideox-lora"], [32 / 64])

prompt = "A vast, shimmering ocean flows gracefully under a twilight sky, its waves undulating in a mesmerizing dance of blues and greens. The surface glints with the last rays of the setting sun, casting golden highlights that ripple across the water. Seagulls soar above, their cries blending with the gentle roar of the waves. The horizon stretches infinitely, where the ocean meets the sky in a seamless blend of hues. Close-ups reveal the intricate patterns of the waves, capturing the fluidity and dynamic beauty of the sea in motion."
frames = pipe(prompt, guidance_scale=6, use_dynamic_cfg=True).frames[0]
export_to_video(frames, "output.mp4", fps=8)
```
## Reducir el uso de memoria
Durante las pruebas con la biblioteca diffusers, se habilitaron todas las optimizaciones incluidas en la biblioteca diffusers. Este esquema no se ha probado en cuanto al uso real de memoria en dispositivos fuera de las arquitecturas **NVIDIA A100 / H100**. En general, este esquema se puede adaptar a todos los dispositivos de la **arquitectura NVIDIA Ampere** y superiores. Si se deshabilitan las optimizaciones, el consumo de memoria se multiplicará, con un uso de memoria pico de aproximadamente 3 veces el valor de la tabla. Sin embargo, la velocidad aumentará aproximadamente 3-4 veces. Puede deshabilitar selectivamente algunas optimizaciones, entre ellas:
```
pipe.enable_sequential_cpu_offload()
pipe.vae.enable_slicing()
pipe.vae.enable_tiling()
```
+ Para la inferencia con múltiples GPU, la optimización `enable_sequential_cpu_offload()` debe desactivarse.
+ El uso de modelos INT8 ralentizará la inferencia, lo cual se hace para adaptarse a GPUs con menos memoria manteniendo una pérdida mínima de calidad de video, aunque la velocidad de inferencia disminuirá significativamente.
+ El modelo CogVideoX-2B se entrenó con precisión `FP16` y todos los modelos CogVideoX-5B se entrenaron con precisión `BF16`. Recomendamos usar la precisión con la que se entrenó el modelo para la inferencia.
+ [PytorchAO](https://github.com/pytorch/ao) y [Optimum-quanto](https://github.com/huggingface/optimum-quanto/) se pueden usar para cuantizar los módulos del codificador de texto, el transformer y el VAE, reduciendo así los requisitos de memoria de CogVideoX. Esto permite ejecutar el modelo en Colabs T4 gratuitos o en GPUs con menos memoria. Además, ten en cuenta que la cuantización de TorchAO es totalmente compatible con `torch.compile`, lo que puede mejorar significativamente la velocidad de inferencia. La precisión FP8 debe usarse en dispositivos con NVIDIA H100 o superior, lo que requiere la instalación desde el código fuente de los paquetes Python `torch`, `torchao`, `diffusers` y `accelerate`. Se recomienda CUDA 12.4.
+ Las pruebas de velocidad de inferencia también utilizaron el esquema de optimización de memoria anterior. Sin la optimización de memoria, la velocidad de inferencia aumenta aproximadamente un 10%. Solo la versión del modelo de `diffusers` admite la cuantización.
+ El modelo solo admite entradas en inglés; otros idiomas pueden traducirse al inglés para su uso mediante refinamiento con un modelo de gran escala.
+ El uso de memoria del ajuste fino de modelos se prueba en un entorno `8 * H100`, y el programa utiliza automáticamente la optimización `Zero 2`. Si en la tabla se indica un número específico de GPUs, se deben usar ese número o más GPUs para el ajuste fino.
 | **Atributo**                        | **CogVideoX-2B**                                                       | **CogVideoX-5B**                                                       |
| ------------------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Nombre del modelo**                       | CogVideoX-2B                                                           | CogVideoX-5B                                                           |
| **Precisión de inferencia**              | FP16* (recomendado), BF16, FP32, FP8*, INT8, INT4 no compatible         | BF16 (recomendado), FP16, FP32, FP8*, INT8, INT4 no compatible         |
| **VRAM para inferencia en una sola GPU**        | FP16: Usando diffusers 12,5 GB* INT8: Usando diffusers con torchao 7,8 GB* | BF16: Usando diffusers 20.7GB* INT8: Usando diffusers con torchao 11.4GB* |
| **VRAM para inferencia con múltiples GPU**         | FP16: Usando diffusers 10GB*                                             | BF16: Uso de 15 GB con diffusers*                                             |
| **Velocidad de inferencia**                  | Un solo A100: ~90 segundos, Un solo H100: ~45 segundos                      | Un solo A100: ~180 segundos, Un solo H100: ~90 segundos                     |
| **Precisión del ajuste fino**            | FP16                                                                   | BF16                                                                   |
| **Consumo de VRAM durante el ajuste fino**     | 47 GB (bs=1, LORA) 61 GB (bs=2, LORA) 62GB (bs=1, SFT)                 | 63 GB (bs=1, LORA) 80 GB (bs=2, LORA) 75GB (bs=1, SFT)                 |
Xet Storage Details

Size:: 22.1 kB
Xet hash:: 7c57a4bc0ba29c71f8aa8c32d150d9c4ccd8ee03d83af7caa55d3d1cba75a5c0
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.