help="Model class to use (wan2.1: standard model, wan2.1_distill: distilled model for faster inference)",
)
)
parser.add_argument("--model_size",type=str,required=True,choices=["14b","1.3b"],help="Model type to use")
parser.add_argument("--model_size",type=str,required=True,choices=["14b","1.3b"],help="Model type to use")
parser.add_argument("--task",type=str,required=True,choices=["i2v","t2v"],help="Specify the task type. 'i2v' for image-to-video translation, 't2v' for text-to-video generation.")
parser.add_argument("--task",type=str,required=True,choices=["i2v","t2v"],help="Specify the task type. 'i2v' for image-to-video translation, 't2v' for text-to-video generation.")
Lightx2v is a lightweight video inference and generation engine that provides a web interface based on Gradio, supporting both Image-to-Video and Text-to-Video generation modes.
Lightx2v is a lightweight video inference and generation engine that provides a web interface based on Gradio, supporting both Image-to-Video and Text-to-Video generation modes.
## 📁 File Structure
```
LightX2V/app/
├── gradio_demo.py # English interface demo
├── gradio_demo_zh.py # Chinese interface demo
├── run_gradio.sh # Startup script
├── README.md # Documentation
├── saved_videos/ # Generated video save directory
└── inference_logs.log # Inference logs
```
This project contains two main demo files:
This project contains two main demo files:
-`gradio_demo.py` - English interface version
-`gradio_demo.py` - English interface version
-`gradio_demo_zh.py` - Chinese interface version
-`gradio_demo_zh.py` - Chinese interface version
## 🚀 Quick Start
## 🚀 Quick Start
### System Requirements
### Environment Requirements
- Python 3.10+ (recommended)
Follow the [Quick Start Guide](../getting_started/quickstart.md) to install the environment
- CUDA 12.4+ (recommended)
- At least 8GB GPU VRAM
- At least 16GB system memory (preferably at least 32GB)
- At least 128GB SSD solid-state drive (**💾 Strongly recommend using SSD solid-state drives to store model files! During "lazy loading" startup, significantly improves model loading speed and inference performance**)
-**Resource-constrained**: Prioritize distilled versions and lower resolutions
-**Resource-constrained**: Prioritize distilled versions and lower resolutions
-**Real-time applications**: Strongly recommend using distilled models (`wan2.1_distill`)
**🎯 Model Category Description**:
-**`wan2.1`**: Standard model, provides the best video generation quality, suitable for scenarios with extremely high quality requirements
-**`wan2.1_distill`**: Distilled model, optimized through knowledge distillation technology, significantly improves inference speed, maintains good quality while greatly reducing computation time, suitable for most application scenarios
### Startup Methods
### Startup Methods
#### Method 1: Using Startup Script (Recommended)
#### Method 1: Using Startup Script (Recommended)
**Linux Environment:**
```bash
```bash
# 1. Edit the startup script to configure relevant paths
# 1. Edit the startup script to configure relevant paths
cd app/
cd app/
...
@@ -79,41 +87,84 @@ vim run_gradio.sh
...
@@ -79,41 +87,84 @@ vim run_gradio.sh
# 2. Run the startup script
# 2. Run the startup script
bash run_gradio.sh
bash run_gradio.sh
# 3. Or start with parameters (recommended)
# 3. Or start with parameters (recommended using distilled models)
bash run_gradio.sh --task i2v --lang en --model_size 14b --port 8032
This document provides detailed instructions for deploying LightX2V locally on Windows environments.
## 📖 Overview
## System Requirements
This document provides detailed instructions for deploying LightX2V locally on Windows environments, including batch file inference, Gradio Web interface inference, and other usage methods.
Before getting started, please ensure your system meets the following requirements:
## 🚀 Quick Start
-**Operating System**: Windows 10/11
### Environment Requirements
-**Graphics Card**: NVIDIA GPU (with CUDA support)
-**VRAM**: At least 8GB VRAM
-**Memory**: At least 16GB RAM
-**Storage**: 20GB+ available disk space
-**Environment Manager**: Anaconda or Miniconda installed
-**Storage**: Strongly recommended to use SSD solid-state drives, mechanical hard drives will cause slow model loading
### Step 1: Check CUDA Version
#### Software Requirements
-**Operating System**: Windows 10/11
-**Python**: 3.12 or higher version
-**CUDA**: 12.4 or higher version
-**Dependencies**: Refer to LightX2V project's requirements_win.txt
First, verify your GPU driver and CUDA version by running the following command in Command Prompt:
### Installation Steps
```bash
1.**Clone Project**
nvidia-smi
```cmd
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
```
```
Note the **CUDA Version** displayed in the output, as you'll need to match this version during subsequent installations.
2.**Install Dependencies**
```cmd
### Step 2: Create Python Environment
pip install -r requirements_win.txt
Create an isolated conda environment, we recommend using Python 3.12:
```bash
# Create new environment (using Python 3.12 as example)
conda create -n lightx2v python=3.12 -y
# Activate environment
conda activate lightx2v
```
```
> 💡 **Tip**: Python 3.10 or higher is recommended for optimal compatibility.
3.**Download Models**
Refer to [Model Download Guide](../getting_started/quickstart.md) to download required models
### Step 3: Install PyTorch Framework
## 🎯 Usage Methods
#### Method 1: Download Official Wheel Packages (Recommended)
### Method 1: Using Batch File Inference
1. Visit the [PyTorch Official Wheel Download Page](https://download.pytorch.org/whl/torch/)
Refer to [Quick Start Guide](../getting_started/quickstart.md) to install environment, and use [batch files](https://github.com/ModelTC/LightX2V/tree/main/scripts/win) to run.
2. Select the appropriate wheel package, ensuring you match:
-**Python Version**: Must match your environment (cp312 means Python 3.12)
-**CUDA Version**: Must match your GPU driver
-**Platform**: Choose Windows version (win_amd64)
**Example for Python 3.12 + PyTorch 2.6 + CUDA 12.4:**
### Method 2: Using Gradio Web Interface Inference
```
#### Manual Gradio Configuration
torch-2.6.0+cu124-cp312-cp312-win_amd64.whl
```
After downloading, install the packages:
Refer to [Quick Start Guide](../getting_started/quickstart.md) to install environment, refer to [Gradio Deployment Guide](./deploy_gradio.md)
**⚠️ Important Note**: If using distilled models (model names containing StepDistill-CfgDistil field), please set `model_cls` to `wan2.1_distill`
After installation, we recommend running a verification script to ensure proper functionality:
> 📝 **Testing**: You can also run the [official test script](https://github.com/woct0rdho/SageAttention/blob/main/tests/test_sageattn.py) for more detailed functionality verification.
### Step 6: Get LightX2V Project Code
Clone the LightX2V project from GitHub and install Windows-specific dependencies:
```bash
# Clone project code
git clone https://github.com/ModelTC/LightX2V.git
# Enter project directory
cd LightX2V
# Install Windows-specific dependencies
pip install-r requirements_win.txt
```
> 🔍 **Note**: We use `requirements_win.txt` instead of the standard `requirements.txt` because Windows environments may require specific package versions or additional dependencies.
## Troubleshooting
### 1. CUDA Version Mismatch
**Symptoms**: CUDA-related errors occur
**Solutions**:
- Verify GPU driver supports required CUDA version
- Re-download matching wheel packages
- Use `nvidia-smi` to check maximum supported CUDA version
### 2. Dependency Conflicts
**Symptoms**: Package version conflicts or import errors
- Recreate environment and install dependencies strictly by version requirements
- Use virtual environments to isolate dependencies for different projects
### 3. Wheel Package Download Issues
**Symptoms**: Slow download speeds or connection failures
**Solutions**:
- Use download tools or browser for direct downloads
- Look for domestic mirror sources
- Check network connections and firewall settings
## Next Steps
After completing the environment setup, you can:
**🚀 Start Service**
- 📚 Check the [Quick Start Guide](../getting_started/quickstart.md)(skip environment installation steps)
Double-click to run the `start_lightx2v.bat` file, the script will:
- 🌐 Use the [Gradio Web Interface](./deploy_gradio.md) for visual operations (skip environment installation steps)
1. Automatically read configuration file
2. Verify model paths and file integrity
3. Start Gradio Web interface
4. Automatically open browser to access service
## Version Compatibility Reference
**💡 Usage Suggestion**: After opening the Gradio Web page, it's recommended to check "Auto-configure Inference Options", the system will automatically select appropriate optimization configurations for your machine. When reselecting resolution, you also need to re-check "Auto-configure Inference Options".
| Component | Recommended Version |
**⚠️ Important Note**: On first run, the system will automatically extract the environment file `env.zip`, which may take several minutes. Please be patient. Subsequent launches will skip this step. You can also manually extract the `env.zip` file to the current directory to save time on first startup.
|-----------|-------------------|
| Python | 3.12 |
| PyTorch | 2.6.0+cu124 |
| vLLM | 0.9.1+cu124 |
| SageAttention | 2.1.1+cu126torch2.6.0 |
| CUDA | 12.4+ |
---
### Method 3: Using ComfyUI Inference
💡 **Pro Tip**: If you encounter other issues, we recommend first checking whether all component versions match properly, as most problems stem from version incompatibilities.
Welcome to LightX2V! This guide will help you quickly set up the environment and start using LightX2V for video generation.
We recommend using a docker environment. Here is the [dockerhub](https://hub.docker.com/r/lightx2v/lightx2v/tags) for lightx2v. Please select the tag with the latest date, for example, 25061301.
-**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
### 🐳 Docker Environment (Recommended)
We strongly recommend using the Docker environment, which is the simplest and fastest installation method.
#### 1. Pull Image
Visit LightX2V's [Docker Hub](https://hub.docker.com/r/lightx2v/lightx2v/tags) and select a tag with the latest date, such as `25061301`:
```bash
# Pull the latest version of LightX2V image
docker pull lightx2v/lightx2v:25061301
docker pull lightx2v/lightx2v:25061301
```
#### 2. Run Container
```bash
docker run --gpus all -itd--ipc=host --name[container_name] -v[mount_settings] --entrypoint /bin/bash [image_id]
docker run --gpus all -itd--ipc=host --name[container_name] -v[mount_settings] --entrypoint /bin/bash [image_id]
```
```
If you want to set up the environment yourself using conda, you can refer to the following steps:
#### 3. Domestic Mirror Source (Optional)
For users in mainland China, if the network is unstable when pulling images, you can pull from [Duduniao](https://docker.aityp.com/r/docker.io/lightx2v/lightx2v):
> 💡 **Note**: The Hunyuan model needs to run under transformers version 4.45.2. If you don't need to run the Hunyuan model, you can skip the transformers version restriction.
# The Hunyuan model needs to run under this version of transformers. If you do not need to run the Hunyuan model, you can ignore this step.
> ⚠️ **Note**: SageAttention's CUDA version doesn't need to be strictly aligned, but Python and PyTorch versions must match.
#### Step 6: Clone Repository
```cmd
# Clone project code
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
# Install Windows-specific dependencies
pip install -r requirements_win.txt
```
## 🎯 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](https://huggingface.co/lightx2v/) 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](https://github.com/ModelTC/LightX2V/tree/main/configs), and scripts are available [here](https://github.com/ModelTC/LightX2V/tree/main/scripts).
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
```bash
# Run after modifying the path in the script
bash scripts/wan/run_wan_t2v.sh
bash scripts/wan/run_wan_t2v.sh
```
```
In addition to the existing input arguments in the script, there are also some necessary parameters in the `wan_t2v.json` file specified by `--config_json`. You can modify them as needed.
#### Windows Environment
```cmd
# Use Windows batch script
scripts\win\run_wan_t2v.bat
```
## 📞 Get Help
If you encounter problems during installation or usage, please:
1. Search for related issues in [GitHub Issues](https://github.com/ModelTC/LightX2V/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!
