logger.info(f"Found Hugging Face model files in: {path}")
returnpath
raiseFileNotFoundError(f"No Hugging Face model files (.safetensors) found.\nPlease download the model from: https://huggingface.co/lightx2v/ or specify the model path in the configuration file.")
# wan2.2: filter files/dirs containing wan2.2 or Wan2.2
print(paths_to_check)
defis_valid(name):
forpathinpaths_to_check:
name_lower=name.lower()
ifos.path.exists(path):
if"wan2.2"notinname_lower:
logger.info(f"Found PyTorch model checkpoint: {path}")
returnFalse
returnpath
ifnotfp8_supportedand"fp8"inname_lower:
raiseFileNotFoundError(f"PyTorch model file '{filename}' not found.\nPlease download the model from https://huggingface.co/lightx2v/ or specify the model path in the configuration file.")
info="💡 **Automatically optimize GPU settings to match the current resolution. After changing the resolution, please re-check this option to prevent potential performance degradation or runtime errors.**",
info="Controls the chunk size for applying rotary embeddings. Larger values may improve performance but increase memory usage. Only effective if 'rotary_chunk' is checked.",
allow_custom_value=True,
visible=True,
)
)
unload_modules=gr.Checkbox(
# wan2.2 specific: high noise model + low noise model (hidden by default)
label="Unload Modules",
withgr.Row(visible=False)aswan22_row:
value=False,
high_noise_path_input=gr.Dropdown(
info="Unload modules (T5, CLIP, DIT, etc.) after inference to reduce GPU/CPU memory usage",
info="Select the numerical precision for critical model components like normalization and embedding layers. FP32 offers higher accuracy, while BF16 improves performance on compatible hardware.",
info="Controls the degree of distribution shift for samples. Larger values indicate more significant shifts.",
)
)
use_tiling_vae=gr.Checkbox(
cfg_scale=gr.Slider(
label="VAE Tiling Inference",
label="CFG Scale Factor",
value=False,
minimum=1,
info="Use VAE tiling inference to reduce GPU memory usage",
maximum=10,
step=1,
value=default_cfg_scale,
info="Controls the influence strength of the prompt. Higher values give more influence to the prompt. When value is 1, CFG is automatically disabled.",
)
)
gr.Markdown("### Feature Caching")
# Update enable_cfg based on cfg_scale
defupdate_enable_cfg(cfg_scale_val):
"""Automatically set enable_cfg based on cfg_scale value"""
ifcfg_scale_val==1:
returngr.update(value=False)
else:
returngr.update(value=True)
# Dynamically update CFG scale factor and enable_cfg when model path changes
info="Cache features during inference to reduce the number of inference steps",
maximum=30,
)
step=1,
teacache_thresh=gr.Slider(
value=16,
label="Tea Cache Threshold",
info="Frames per second of the video. Higher FPS results in smoother videos.",
value=0.26,
minimum=0,
maximum=1,
info="Higher acceleration may result in lower quality —— Setting to 0.1 provides ~2.0x acceleration, setting to 0.2 provides ~3.0x acceleration",
)
)
use_ret_steps=gr.Checkbox(
num_frames=gr.Slider(
label="Cache Only Key Steps",
label="Total Frames",
value=False,
minimum=16,
info="When checked, cache is written only at key steps where the scheduler returns results; when unchecked, cache is written at all steps to ensure the highest quality",
maximum=120,
step=1,
value=81,
info="Total number of frames in the video. More frames result in longer videos.",
)
)
enable_auto_config.change(
save_result_path=gr.Textbox(
fn=auto_configure,
label="Output Video Path",
inputs=[enable_auto_config,resolution],
value=generate_unique_filename(output_dir),
outputs=[
info="Must include .mp4 extension. If left blank or using the default value, a unique filename will be automatically generated.",
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("--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.")
logger.info(f"Found Hugging Face model files in: {path}")
returnpath
raiseFileNotFoundError(f"No Hugging Face model files (.safetensors) found.\nPlease download the model from: https://huggingface.co/lightx2v/ or specify the model path in the configuration file.")
logger.info(f"Found PyTorch model checkpoint: {path}")
returnFalse
returnpath
ifnotfp8_supportedand"fp8"inname_lower:
raiseFileNotFoundError(f"PyTorch model file '{filename}' not found.\nPlease download the model from https://huggingface.co/lightx2v/ or specify the model path in the configuration file.")
- ✅ [q8-kernel](https://github.com/KONAKONA666/q8_kernels)(only supports ADA architecture GPUs)
- ✅ [q8-kernel](https://github.com/KONAKONA666/q8_kernels)(only supports ADA architecture GPUs)
Install according to the project homepage tutorials for each operator as needed
Install according to the project homepage tutorials for each operator as needed.
### 🤖 Supported Models
### 📥 Model Download
#### 🎬 Image-to-Video Models
Refer to the [Model Structure Documentation](../getting_started/model_structure.md) to download complete models (including quantized and non-quantized versions) or download only quantized/non-quantized versions.
| Model Name | Resolution | Parameters | Features | Recommended Use |
| ✅ [Wan2.1-I2V-14B-720P-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-720P-StepDistill-CfgDistill-Lightx2v) | 720p | 14B | HD distilled version | High quality + fast inference |
#### 📝 Text-to-Video Models
```
models/
| Model Name | Parameters | Features | Recommended Use |
├── wan2.1_i2v_720p_lightx2v_4step.safetensors # Original precision
-**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
**📥 Model Download**:
Refer to the [Model Structure Documentation](./model_structure.md) to download complete models (including quantized and non-quantized versions) or download only quantized/non-quantized versions.
**Download Options**:
-**Complete Model**: When downloading complete models with both quantized and non-quantized versions, you can freely choose the quantization precision for DIT/T5/CLIP in the advanced options of the `Gradio` Web frontend.
#### wan2.2 Model Directory Structure
-**Non-quantized Version Only**: When downloading only non-quantized versions, in the `Gradio` Web frontend, the quantization precision for `DIT/T5/CLIP` can only be set to bf16/fp16. If you need to use quantized versions of models, please manually download quantized weights to the `i2v_model_path` or `t2v_model_path` directory where Gradio is started.
```
models/
├── wan2.2_i2v_A14b_high_noise_lightx2v_4step_1030.safetensors # high noise original precision
├── wan2.2_i2v_A14b_high_noise_fp8_e4m3_lightx2v_4step_1030.safetensors # high noise FP8 quantization
├── wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step_1030.safetensors # high noise INT8 quantization
├── wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step_1030_split # high noise INT8 quantization block storage directory
├── wan2.2_i2v_A14b_low_noise_lightx2v_4step.safetensors # low noise original precision
├── t5/clip/xlm-roberta-large/google # text and image encoder
├── vae/lightvae/lighttae # vae
└── config.json # Model configuration file
```
-**Quantized Version Only**: When downloading only quantized versions, in the `Gradio` Web frontend, the quantization precision for `DIT/T5/CLIP` can only be set to fp8 or int8 (depending on the weights you downloaded). If you need to use non-quantized versions of models, please manually download non-quantized weights to the `i2v_model_path` or `t2v_model_path` directory where Gradio is started.
**📝 Download Instructions**:
-**Note**: Whether you download complete models or partial models, the values for `i2v_model_path` and `t2v_model_path` parameters should be the first-level directory paths. For example: `Wan2.1-I2V-14B-480P-Lightx2v/`, not `Wan2.1-I2V-14B-480P-Lightx2v/int8`.
- Model weights can be downloaded from HuggingFace:
- Text and Image Encoders can be downloaded from [Encoders](https://huggingface.co/lightx2v/Encoderss)
- VAE can be downloaded from [Autoencoders](https://huggingface.co/lightx2v/Autoencoders)
- For `xxx_split` directories (e.g., `wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step_split`), which store multiple safetensors by block, suitable for devices with insufficient memory. For example, devices with 16GB or less memory should download according to their own situation.
| `--server_port` | int | ❌ | 7862 | Server port |
| `--server_port` | int | ❌ | 7862 | Server port |
| `--server_name` | str | ❌ | 0.0.0.0 | Server IP address |
| `--server_name` | str | ❌ | 0.0.0.0 | Server IP address |
| `--output_dir` | str | ❌ | ./outputs | Output video save directory |
**💡 Note**: Model type (wan2.1/wan2.2), task type (i2v/t2v), and specific model file selection are all configured in the Web interface.
## 🎯 Features
## 🎯 Features
### Basic Settings
### Model Configuration
-**Model Type**: Supports wan2.1 and wan2.2 model architectures
-**Task Type**: Supports Image-to-Video (i2v) and Text-to-Video (t2v) generation modes
-**Model Selection**: Frontend automatically identifies and filters available model files, supports automatic quantization precision detection
-**Encoder Configuration**: Supports selection of T5 text encoder, CLIP image encoder, and VAE decoder
-**Operator Selection**: Supports multiple attention operators and quantization matrix multiplication operators, system automatically sorts by installation status
### Input Parameters
#### Input Parameters
-**Prompt**: Describe the expected video content
-**Prompt**: Describe the expected video content
-**Negative Prompt**: Specify elements you don't want to appear
-**Negative Prompt**: Specify elements you don't want to appear
-**Input Image**: Upload input image required in i2v mode
-**CPU Offloading**: Transfers partial computation to CPU
-**Lazy Loading**: Loads model components on-demand, significantly reduces system memory consumption
-**Offload Granularity Control**: Fine-grained control of offloading strategies
#### Low-Precision Quantization
-**Attention Operators**: Flash Attention, Sage Attention, etc.
-**Quantization Operators**: vLLM, SGL, Q8F, etc.
-**Precision Modes**: FP8, INT8, BF16, etc.
#### VAE Optimization
-**Lightweight VAE**: Accelerates decoding process
-**VAE Tiling Inference**: Reduces memory usage
#### Feature Caching
The system automatically configures optimal inference options based on your hardware configuration (GPU VRAM and CPU memory) without manual adjustment. The best configuration is automatically applied on startup, including:
-**Tea Cache**: Caches intermediate features to accelerate generation
**💡 Tip**: Generally, after enabling "Auto-configure Inference Options", the system will automatically optimize parameter settings based on your hardware configuration, and performance issues usually won't occur. If you encounter problems, please refer to the following solutions:
@@ -178,7 +178,7 @@ class WanModel(CompiledMethodsMixin):
...
@@ -178,7 +178,7 @@ class WanModel(CompiledMethodsMixin):
ifos.path.exists(non_block_file):
ifos.path.exists(non_block_file):
safetensors_files=[non_block_file]
safetensors_files=[non_block_file]
else:
else:
raiseValueError(f"Non-block file not found in {safetensors_path}")
raiseValueError(f"Non-block file not found in {safetensors_path}. Please check the model path. Lazy load mode only supports loading chunked model weights.")
weight_dict={}
weight_dict={}
forfile_pathinsafetensors_files:
forfile_pathinsafetensors_files:
...
@@ -221,7 +221,7 @@ class WanModel(CompiledMethodsMixin):
...
@@ -221,7 +221,7 @@ class WanModel(CompiledMethodsMixin):
ifos.path.exists(non_block_file):
ifos.path.exists(non_block_file):
safetensors_files=[non_block_file]
safetensors_files=[non_block_file]
else:
else:
raiseValueError(f"Non-block file not found in {safetensors_path}, Please check the lazy load model path")
raiseValueError(f"Non-block file not found in {safetensors_path}. Please check the model path. Lazy load mode only supports loading chunked model weights.")
