LightX2V Quick Start Guide

LightX2V Quick Start Guide#

Welcome to LightX2V! This guide will help you quickly set up the environment and start using LightX2V for video generation.

๐Ÿ“‹ Table of Contents#

๐Ÿš€ System Requirements#

  • Operating System: Linux (Ubuntu 18.04+) or Windows 10/11

  • Python: 3.10 or higher

  • GPU: NVIDIA GPU with CUDA support, at least 8GB VRAM

  • Memory: 16GB or more recommended

  • Storage: At least 50GB available space

๐Ÿง Linux Environment Setup#

๐Ÿ Conda Environment Setup#

If you prefer to set up the environment yourself using Conda, please follow these steps:

Step 1: Clone Repository#

# Download project code
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V

Step 2: Create Conda Virtual Environment#

# Create and activate conda environment
conda create -n lightx2v python=3.11 -y
conda activate lightx2v

Step 3: Install Dependencies#

pip install -v -e .

Step 4: Install Attention Operators#

Option A: Flash Attention 2

git clone https://github.com/Dao-AILab/flash-attention.git --recursive
cd flash-attention && python setup.py install

Option B: Flash Attention 3 (for Hopper architecture GPUs)

cd flash-attention/hopper && python setup.py install

Option C: SageAttention 2 (Recommended)

git clone https://github.com/thu-ml/SageAttention.git
cd SageAttention && CUDA_ARCHITECTURES="8.0,8.6,8.9,9.0,12.0" EXT_PARALLEL=4 NVCC_APPEND_FLAGS="--threads 8" MAX_JOBS=32 pip install -v -e .

Step 4: Install Quantization Operators (Optional)#

Quantization operators are used to support model quantization, which can significantly reduce memory usage and accelerate inference. Choose the appropriate quantization operator based on your needs:

Option A: VLLM Kernels (Recommended) Suitable for various quantization schemes, supports FP8 and other quantization formats.

pip install vllm

Or install from source for the latest features:

git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -e .

Option B: SGL Kernels Suitable for SGL quantization scheme, requires torch == 2.8.0.

pip install sgl-kernel --upgrade

Option C: Q8 Kernels Suitable for Ada architecture GPUs (such as RTX 4090, L40S, etc.).

git clone https://github.com/KONAKONA666/q8_kernels.git
cd q8_kernels && git submodule init && git submodule update
python setup.py install

๐Ÿ’ก Note:

Step 5: Verify Installation#

import lightx2v
print(f"LightX2V Version: {lightx2v.__version__}")

๐ŸชŸ Windows Environment Setup#

Windows systems only support Conda environment setup. Please follow these steps:

๐Ÿ Conda Environment Setup#

Step 1: Check CUDA Version#

First, confirm your GPU driver and CUDA version:

nvidia-smi

Record the CUDA Version information in the output, which needs to be consistent in subsequent installations.

Step 2: Create Python Environment#

# Create new environment (Python 3.12 recommended)
conda create -n lightx2v python=3.12 -y

# Activate environment
conda activate lightx2v

๐Ÿ’ก Note: Python 3.10 or higher is recommended for best compatibility.

Step 3: Install PyTorch Framework#

Method 1: Download Official Wheel Package (Recommended)

  1. Visit the PyTorch Official Download Page

  2. Select the corresponding version wheel package, paying attention to matching:

    • Python Version: Consistent with your environment

    • CUDA Version: Matches your GPU driver

    • Platform: Select Windows version

Example (Python 3.12 + PyTorch 2.6 + CUDA 12.4):

# Download and install PyTorch
pip install torch-2.6.0+cu124-cp312-cp312-win_amd64.whl

# Install supporting packages
pip install torchvision==0.21.0 torchaudio==2.6.0

Method 2: Direct Installation via pip

# CUDA 12.4 version example
pip install torch==2.6.0+cu124 torchvision==0.21.0+cu124 torchaudio==2.6.0+cu124 --index-url https://download.pytorch.org/whl/cu124

Step 4: Install Windows Version vLLM#

Download the corresponding wheel package from vllm-windows releases.

Version Matching Requirements:

  • Python version matching

  • PyTorch version matching

  • CUDA version matching

# Install vLLM (please adjust according to actual filename)
pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl

Step 5: Install Attention Mechanism Operators#

Option A: Flash Attention 2

pip install flash-attn==2.7.2.post1

Option B: SageAttention 2 (Strongly Recommended)

Download Sources:

# Install SageAttention (please adjust according to actual filename)
pip install sageattention-2.1.1+cu126torch2.6.0-cp312-cp312-win_amd64.whl

โš ๏ธ Note: SageAttentionโ€™s CUDA version doesnโ€™t need to be strictly aligned, but Python and PyTorch versions must match.

Step 6: Clone Repository#

# Clone project code
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V

# Install Windows-specific dependencies
pip install -r requirements_win.txt
pip install -v -e .

Step 7: Install Quantization Operators (Optional)#

By default, LightX2V uses Triton kernel for quantization inference, which is efficient and requires no additional dependencies. Just ensure that triton-windows is installed.

If you need to use other quantization operators, you can install the following options:

1. Install Windows Version of vLLM

Download the corresponding wheel package from vllm-windows releases.

Version Matching Requirements:

  • Python version match

  • PyTorch version match

  • CUDA version match

# Install vLLM (please adjust according to actual filename)
pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl

2. Install q8-kernels

For RTX 40 series GPUs, it is recommended to install q8_kernel==0.1.0:

git clone https://github.com/KONAKONA666/q8_kernels.git
cd q8_kernels && git submodule init && git submodule update
python setup.py install

For other GPUs, it is recommended to install q8_kernel==0.5.0. Please refer to LTX-Video-Q8-Kernels.

๐Ÿ’ก Note:

๐ŸŽฏ Inference Usage#

๐Ÿ“ฅ Model Preparation#

Before starting inference, you need to download the model files in advance. We recommend:

  • Download Source: Download models from LightX2V Official Hugging Face or other open-source model repositories

  • Storage Location: Itโ€™s recommended to store models on SSD disks for better read performance

  • Available Models: Including Wan2.1-I2V, Wan2.1-T2V, and other models supporting different resolutions and functionalities

๐Ÿ“ Configuration Files and Scripts#

The configuration files used for inference are available here, and scripts are available here.

You need to configure the downloaded model path in the run script. In addition to the input arguments in the script, there are also some necessary parameters in the configuration file specified by --config_json. You can modify them as needed.

๐Ÿš€ Start Inference#

Linux Environment#

# Run after modifying the path in the script
bash scripts/wan/run_wan_t2v.sh

Windows Environment#

# Use Windows batch script
scripts\win\run_wan_t2v.bat

Python Script Launch#

from lightx2v import LightX2VPipeline

pipe = LightX2VPipeline(
    model_path="/path/to/Wan2.1-T2V-14B",
    model_cls="wan2.1",
    task="t2v",
)

pipe.create_generator(
    attn_mode="sage_attn2",
    infer_steps=50,
    height=480,  # 720
    width=832,   # 1280
    num_frames=81,
    guidance_scale=5.0,
    sample_shift=5.0,
)

seed = 42
prompt = "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."
negative_prompt = "้•œๅคดๆ™ƒๅŠจ๏ผŒ่‰ฒ่ฐƒ่‰ณไธฝ๏ผŒ่ฟ‡ๆ›๏ผŒ้™ๆ€๏ผŒ็ป†่Š‚ๆจก็ณŠไธๆธ…๏ผŒๅญ—ๅน•๏ผŒ้ฃŽๆ ผ๏ผŒไฝœๅ“๏ผŒ็”ปไฝœ๏ผŒ็”ป้ข๏ผŒ้™ๆญข๏ผŒๆ•ดไฝ“ๅ‘็ฐ๏ผŒๆœ€ๅทฎ่ดจ้‡๏ผŒไฝŽ่ดจ้‡๏ผŒJPEGๅŽ‹็ผฉๆฎ‹็•™๏ผŒไธ‘้™‹็š„๏ผŒๆฎ‹็ผบ็š„๏ผŒๅคšไฝ™็š„ๆ‰‹ๆŒ‡๏ผŒ็”ปๅพ—ไธๅฅฝ็š„ๆ‰‹้ƒจ๏ผŒ็”ปๅพ—ไธๅฅฝ็š„่„ธ้ƒจ๏ผŒ็•ธๅฝข็š„๏ผŒๆฏๅฎน็š„๏ผŒๅฝขๆ€็•ธๅฝข็š„่‚ขไฝ“๏ผŒๆ‰‹ๆŒ‡่žๅˆ๏ผŒ้™ๆญขไธๅŠจ็š„็”ป้ข๏ผŒๆ‚ไนฑ็š„่ƒŒๆ™ฏ๏ผŒไธ‰ๆก่…ฟ๏ผŒ่ƒŒๆ™ฏไบบๅพˆๅคš๏ผŒๅ€’็€่ตฐ"
save_result_path="/path/to/save_results/output.mp4"

pipe.generate(
    seed=seed,
    prompt=prompt,
    negative_prompt=negative_prompt,
    save_result_path=save_result_path,
)

๐Ÿ’ก More Examples: For more usage examples including quantization, offloading, caching, and other advanced configurations, please refer to the examples directory.

๐Ÿ“ž Get Help#

If you encounter problems during installation or usage, please:

  1. Search for related issues in GitHub Issues

  2. Submit a new Issue describing your problem

๐ŸŽ‰ Congratulations! You have successfully set up the LightX2V environment and can now start enjoying video generation!