lightx2v/Hy1.5-Distill-Models

lightx2v

Texto a video

Modelos destilados de 4 pasos para HunyuanVideo-1.5, optimizados para LightX2V y generación texto-a-video en 480p. Reducen la inferencia estándar de 50 pasos a 4 pasos sin CFG, con el objetivo de acelerar mucho la generación de video manteniendo buena calidad visual. Incluyen una versión base de 16,7 GB y una variante cuantizada FP8 de 8,85 GB para menor uso de VRAM.

Como usar

Instalación de LightX2V:
pip install -v git+https://github.com/ModelTC/LightX2V.git

O desde el código fuente:
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
pip install -v -e .

Descarga del modelo:
git lfs install
git clone https://huggingface.co/lightx2v/Hy1.5-Distill-Models

O descarga de un archivo individual:
pip install huggingface-hub
python -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='lightx2v/Hy1.5-Distill-Models', filename='hy1.5_t2v_480p_lightx2v_4step.safetensors', local_dir='./models')"

Uso base con LightX2V:
from lightx2v import LightX2VPipeline

pipe = LightX2VPipeline(
    model_path="/path/to/hunyuanvideo-1.5/",
    model_cls="hunyuan_video_1.5",
    transformer_model_name="480p_t2v",
    task="t2v",
    dit_original_ckpt="/path/to/hy1.5_t2v_480p_lightx2v_4step.safetensors"
)

pipe.enable_offload(
    cpu_offload=True,
    offload_granularity="block",
    text_encoder_offload=True,
    image_encoder_offload=False,
    vae_offload=False,
)

pipe.create_generator(
    attn_mode="sage_attn2",
    infer_steps=4,
    num_frames=81,
    guidance_scale=1,
    sample_shift=9.0,
    aspect_ratio="16:9",
    fps=16,
    denoising_step_list=[1000, 750, 500, 250]
)

pipe.generate(
    seed=123,
    prompt="A close-up shot captures a scene on a polished, light-colored granite kitchen counter...",
    negative_prompt="",
    save_result_path="/path/to/save_results/output.mp4",
)

Uso con cuantización FP8:
from lightx2v import LightX2VPipeline

pipe = LightX2VPipeline(
    model_path="/path/to/hunyuanvideo-1.5/",
    model_cls="hunyuan_video_1.5",
    transformer_model_name="480p_t2v",
    task="t2v",
    dit_original_ckpt="/path/to/hy1.5_t2v_480p_lightx2v_4step.safetensors"
)

pipe.enable_quantize(
    quant_scheme='fp8-sgl',
    dit_quantized=True,
    dit_quantized_ckpt="/path/to/hy1.5_t2v_480p_scaled_fp8_e4m3_lightx2v_4step.safetensors",
    text_encoder_quantized=False,
    text_encoder_quantized_ckpt="/path/to/hy15_qwen25vl_llm_encoder_fp8_e4m3_lightx2v.safetensors",
    image_encoder_quantized=False,
)

pipe.enable_offload(
    cpu_offload=True,
    offload_granularity="block",
    text_encoder_offload=True,
    image_encoder_offload=False,
    vae_offload=False,
)

pipe.create_generator(
    attn_mode="sage_attn2",
    infer_steps=4,
    num_frames=81,
    guidance_scale=1,
    sample_shift=9.0,
    aspect_ratio="16:9",
    fps=16,
    denoising_step_list=[1000, 750, 500, 250]
)

pipe.generate(
    seed=123,
    prompt="Your prompt here",
    negative_prompt="",
    save_result_path="/path/to/output.mp4",
)

Para FP8 se requiere instalar un kernel compatible:
# Requires torch == 2.8.0
pip install sgl-kernel --upgrade

Alternativa:
pip install vllm

Configuración crítica: infer_steps=4, guidance_scale=1 y denoising_step_list=[1000, 750, 500, 250]. Las llamadas enable_quantize() y enable_offload() deben ejecutarse antes de create_generator().

Funcionalidades

Generación texto-a-video en 480p basada en HunyuanVideo-1.5.
Destilación de inferencia de 50 pasos a 4 pasos, con una aceleración indicada de aproximadamente 25x frente al flujo estándar.
No requiere classifier-free guidance: debe usarse guidance_scale=1.
Incluye modelo base 4-step y versión FP8 cuantizada para reducir memoria y acelerar cómputo.
Compatible con LightX2V y diseñado para usar SageAttention 2 como modo de atención recomendado.
La versión FP8 puede reducir aproximadamente 50% el uso de memoria, manteniendo calidad visual según la ficha del modelo.
Requiere los pesos originales de HunyuanVideo-1.5 además del checkpoint destilado.

Casos de uso

Generación rápida de videos desde texto en 480p con HunyuanVideo-1.5.
Prototipado de pipelines texto-a-video con menor latencia que la inferencia estándar de 50 pasos.
Ejecución en GPUs de consumo mediante offloading y, opcionalmente, cuantización FP8 para reducir VRAM.
Aplicaciones de generación de video casi en tiempo real donde la velocidad sea más importante que usar el flujo completo de 50 pasos.
Despliegues de LightX2V que necesiten checkpoints destilados para producción o pruebas de rendimiento.