Skip to content

GitLab

Commit a1ebc651 authored by xuwx1's avatar xuwx1
Browse files

updata lightx2v

parent 5a4db490
Pipeline #3149 canceled with stages
Hide whitespace changes
Inline Side-by-side
Showing with 2955 additions and 0 deletions
docs/ZH_CN/source/deploy_guides/deploy_local_windows.md 0 → 100644
View file @ a1ebc651
# Windows 本地部署指南
## 📖 概述
本文档将详细指导您在Windows环境下完成LightX2V的本地部署配置，包括批处理文件推理、Gradio Web界面推理等多种使用方式。
## 🚀 快速开始
### 环境要求
#### 硬件要求
- **GPU**: NVIDIA GPU，建议 8GB+ VRAM
- **内存**: 建议 16GB+ RAM
- **存储**: 强烈建议使用 SSD 固态硬盘，机械硬盘会导致模型加载缓慢
## 🎯 使用方式
### 方式一：使用批处理文件推理
参考[快速开始文档](../getting_started/quickstart.md)安装环境，并使用[批处理文件](https://github.com/ModelTC/LightX2V/tree/main/scripts/win)运行。
### 方式二：使用Gradio Web界面推理
#### 手动配置Gradio
参考[快速开始文档](../getting_started/quickstart.md)安装环境，参考[Gradio部署指南](./deploy_gradio.md)
#### 一键启动Gradio（推荐）
**📦 下载软件包**
- [夸克网盘](https://pan.quark.cn/s/8af1162d7a15)
**📁 目录结构**
解压后，确保目录结构如下：
```
├── env/ # LightX2V 环境目录
├── LightX2V/ # LightX2V 项目目录
├── start_lightx2v.bat # 一键启动脚本
├── lightx2v_config.txt # 配置文件
├── LightX2V使用说明.txt # LightX2V使用说明
├── outputs/ # 生成的视频保存目录
└── models/ # 模型存放目录
```
**📥 下载模型**:
可参考[模型结构文档](../getting_started/model_structure.md)或者[gradio部署文档](./deploy_gradio.md)下载完整模型（包含量化和非量化版本）或仅下载量化/非量化版本。
**📋 配置参数**
编辑 `lightx2v_config.txt` 文件，根据需要修改以下参数：
```ini
# 界面语言 (zh: 中文, en: 英文)
lang=zh
# 服务器端口
port=8032
# GPU设备ID (0, 1, 2...)
gpu=0
# 模型路径
model_path=models/
```
**🚀 启动服务**
双击运行 `start_lightx2v.bat` 文件，脚本将：
1. 自动读取配置文件
2. 验证模型路径和文件完整性
3. 启动 Gradio Web 界面
4. 自动打开浏览器访问服务
![Gradio中文界面](../../../../assets/figs/portabl_windows/pic_gradio_zh.png)
**⚠️ 重要提示**:
- **页面显示问题**: 如果网页打开空白或显示异常，请运行 `pip install --upgrade gradio` 升级Gradio版本。
### 方式三：使用ComfyUI推理
此说明将指导您如何下载与使用便携版的Lightx2v-ComfyUI环境，如此可以免去手动配置环境的步骤，适用于想要在Windows系统下快速开始体验使用Lightx2v加速视频生成的用户。
#### 下载Windows便携环境：
- [百度网盘下载](https://pan.baidu.com/s/1FVlicTXjmXJA1tAVvNCrBw?pwd=wfid)，提取码：wfid
便携环境中已经打包了所有Python运行相关的依赖，也包括ComfyUI和LightX2V的代码及其相关依赖，下载后解压即可使用。
解压后对应的文件目录说明如下：
```shell
lightx2v_env
├──📂 ComfyUI # ComfyUI代码
├──📂 portable_python312_embed # 独立的Python环境
└── run_nvidia_gpu.bat # Windows启动脚本（双击启动）
```
#### 启动ComfyUI
直接双击run_nvidia_gpu.bat文件，系统会打开一个Command Prompt窗口并运行程序，一般第一次启动时间会比较久，请耐心等待，启动完成后会自动打开浏览器并出现ComfyUI的前端界面。
![i2v示例工作流](../../../../assets/figs/portabl_windows/pic1.png)
LightX2V-ComfyUI的插件使用的是，[ComfyUI-Lightx2vWrapper](https://github.com/ModelTC/ComfyUI-Lightx2vWrapper)，示例工作流可以从此项目中获取。
#### 已测试显卡（offload模式）
- 测试模型`Wan2.1-I2V-14B-480P`
| 显卡型号 | 任务类型 | 显存容量 | 实际最大显存占用 | 实际最大内存占用 |
|:----------|:-----------|:-----------|:-------- |:---------- |
| 3090Ti | I2V | 24G | 6.1G | 7.1G |
| 3080Ti | I2V | 12G | 6.1G | 7.1G |
| 3060Ti | I2V | 8G | 6.1G | 7.1G |
| 4070Ti Super | I2V | 16G | 6.1G | 7.1G |
| 4070 | I2V | 12G | 6.1G | 7.1G |
| 4060 | I2V | 8G | 6.1G | 7.1G |
#### 环境打包和使用参考
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI)
- [Portable-Windows-ComfyUI-Docs](https://docs.comfy.org/zh-CN/installation/comfyui_portable_windows#portable-%E5%8F%8A%E8%87%AA%E9%83%A8%E7%BD%B2)
docs/ZH_CN/source/deploy_guides/deploy_service.md 0 → 100644
View file @ a1ebc651
# 服务化部署
lightx2v 提供异步服务功能。代码入口点在 [这里](https://github.com/ModelTC/lightx2v/blob/main/lightx2v/api_server.py)
### 启动服务
```shell
# 修改脚本中的路径
bash scripts/start_server.sh
```
`--port 8000` 选项表示服务将绑定到本地机器的 `8000` 端口。您可以根据需要更改此端口。
### 客户端发送请求
```shell
python scripts/post.py
```
服务端点：`/v1/tasks/`
`scripts/post.py` 中的 `message` 参数如下：
```python
message = {
"prompt": "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage.",
"negative_prompt": "镜头晃动，色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走",
"image_path": ""
}
```
1. `prompt`、`negative_prompt` 和 `image_path` 是视频生成的基本输入。`image_path` 可以是空字符串，表示不需要图像输入。
### 客户端检查服务器状态
```shell
python scripts/check_status.py
```
服务端点包括：
1. `/v1/service/status` 用于检查服务状态。返回服务是 `busy` 还是 `idle`。服务只有在 `idle` 时才接受新请求。
2. `/v1/tasks/` 用于获取服务器接收和完成的所有任务。
3. `/v1/tasks/{task_id}/status` 用于获取指定 `task_id` 的任务状态。返回任务是 `processing` 还是 `completed`。
### 客户端随时停止服务器上的当前任务
```shell
python scripts/stop_running_task.py
```
服务端点：`/v1/tasks/running`
终止任务后，服务器不会退出，而是返回等待新请求的状态。
### 在单个节点上启动多个服务
在单个节点上，您可以使用 `scripts/start_server.sh` 启动多个服务（注意同一 IP 下的端口号必须不同），或者可以使用 `scripts/start_multi_servers.sh` 同时启动多个服务：
```shell
num_gpus=8 bash scripts/start_multi_servers.sh
```
其中 `num_gpus` 表示要启动的服务数量；服务将从 `--start_port` 开始在连续端口上运行。
### 多个服务之间的调度
```shell
python scripts/post_multi_servers.py
```
`post_multi_servers.py` 将根据服务的空闲状态调度多个客户端请求。
### API 端点总结
| 端点 | 方法 | 描述 |
|------|------|------|
| `/v1/tasks/` | POST | 创建视频生成任务 |
| `/v1/tasks/form` | POST | 通过表单创建视频生成任务 |
| `/v1/tasks/` | GET | 获取所有任务列表 |
| `/v1/tasks/{task_id}/status` | GET | 获取指定任务状态 |
| `/v1/tasks/{task_id}/result` | GET | 获取指定任务的结果视频文件 |
| `/v1/tasks/running` | DELETE | 停止当前运行的任务 |
| `/v1/files/download/{file_path}` | GET | 下载文件 |
| `/v1/service/status` | GET | 获取服务状态 |
docs/ZH_CN/source/deploy_guides/for_low_latency.md 0 → 100644
View file @ a1ebc651
# 低延迟场景部署
在低延迟的场景，我们会追求更快的速度，忽略显存和内存开销等问题。我们提供两套方案：
## 💡 方案一：步数蒸馏模型的推理
该方案可以参考[步数蒸馏文档](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/step_distill.html)
🧠 **步数蒸馏**是非常直接的视频生成模型的加速推理方案。从50步蒸馏到4步，耗时将缩短到原来的4/50。同时，该方案下，仍然可以和以下方案结合使用：
1. [高效注意力机制方案](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/attention.html)
2. [模型量化](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/quantization.html)
## 💡 方案二：非步数蒸馏模型的推理
步数蒸馏需要比较大的训练资源，以及步数蒸馏后的模型，可能会出现视频动态范围变差的问题。
对于非步数蒸馏的原始模型，我们可以使用以下方案或者多种方案结合的方式进行加速：
1. [并行推理](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/parallel.html) 进行多卡并行加速。
2. [特征缓存](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/cache.html) 降低实际推理步数。
3. [高效注意力机制方案](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/attention.html) 加速 Attention 的推理。
4. [模型量化](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/quantization.html) 加速 Linear 层的推理。
5. [变分辨率推理](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/method_tutorials/changing_resolution.html) 降低中间推理步的分辨率。
## 💡 使用Tiny VAE
在某些情况下，VAE部分耗时会比较大，可以使用轻量级VAE进行加速，同时也可以降低一部分显存。
```python
{
"use_tae": true,
"tae_path": "/path to taew2_1.pth"
}
```
taew2_1.pth 权重可以从[这里](https://github.com/madebyollin/taehv/raw/refs/heads/main/taew2_1.pth)下载
## ⚠️ 注意
有一部分的加速方案之间目前无法结合使用，我们目前正在致力于解决这一问题。
如有问题，欢迎在 [🐛 GitHub Issues](https://github.com/ModelTC/lightx2v/issues) 中进行错误报告或者功能请求
docs/ZH_CN/source/deploy_guides/for_low_resource.md 0 → 100644
View file @ a1ebc651
# Lightx2v 低资源部署指南
## 📋 概述
本指南专门针对硬件资源受限的环境，特别是**8GB显存 + 16/32GB内存**的配置，详细说明如何成功运行Lightx2v 14B模型进行480p和720p视频生成。
Lightx2v是一个强大的视频生成模型，但在资源受限的环境下需要精心优化才能流畅运行。本指南将为您提供从硬件选择到软件配置的完整解决方案，确保您能够在有限的硬件条件下获得最佳的视频生成体验。
## 🎯 目标硬件配置详解
### 推荐硬件规格
**GPU要求**:
- **显存**: 8GB (RTX 3060/3070/4060/4060Ti 等)
- **架构**: 支持CUDA的NVIDIA显卡
**系统内存**:
- **最低要求**: 16GB DDR4
- **推荐配置**: 32GB DDR4/DDR5
- **内存速度**: 建议3200MHz及以上
**存储要求**:
- **类型**: 强烈推荐NVMe SSD
- **容量**: 至少50GB可用空间
- **速度**: 读取速度建议3000MB/s以上
**CPU要求**:
- **核心数**: 建议8核心及以上
- **频率**: 建议3.0GHz及以上
- **架构**: 支持AVX2指令集
## ⚙️ 核心优化策略详解
### 1. 环境优化
在运行Lightx2v之前，建议设置以下环境变量以优化性能：
```bash
# CUDA内存分配优化
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
# 启用CUDA Graph模式，提升推理性能
export ENABLE_GRAPH_MODE=true
# 使用BF16精度推理，减少显存占用（默认FP32精度）
export DTYPE=BF16
```
**优化说明**:
- `expandable_segments:True`: 允许CUDA内存段动态扩展，减少内存碎片
- `ENABLE_GRAPH_MODE=true`: 启用CUDA Graph，减少内核启动开销
- `DTYPE=BF16`: 使用BF16精度，在保持质量的同时减少显存占用
### 2. 量化策略
量化是低资源环境下的关键优化技术，通过降低模型精度来减少内存占用。
#### 量化方案对比
**FP8量化** (推荐用于RTX 40系列):
```python
# 适用于支持FP8的GPU，提供更好的精度
dit_quant_scheme = "fp8" # DIT模型量化
t5_quant_scheme = "fp8" # T5文本编码器量化
clip_quant_scheme = "fp8" # CLIP视觉编码器量化
```
**INT8量化** (通用方案):
```python
# 适用于所有GPU，内存占用最小
dit_quant_scheme = "int8" # 8位整数量化
t5_quant_scheme = "int8" # 文本编码器量化
clip_quant_scheme = "int8" # 视觉编码器量化
```
### 3. 高效算子选择指南
选择合适的算子可以显著提升推理速度和减少内存占用。
#### 注意力算子选择
**推荐优先级**:
1. **[Sage Attention](https://github.com/thu-ml/SageAttention)** (最高优先级)
2. **[Flash Attention](https://github.com/Dao-AILab/flash-attention)** (通用方案)
#### 矩阵乘算子选择
**ADA架构显卡** (RTX 40系列):
推荐优先级:
1. **[q8-kernel](https://github.com/KONAKONA666/q8_kernels)** (最高性能，仅支持ADA架构)
2. **[sglang-kernel](https://github.com/sgl-project/sglang/tree/main/sgl-kernel)** (平衡方案)
3. **[vllm-kernel](https://github.com/vllm-project/vllm)** (通用方案)
**其他架构显卡**:
1. **[sglang-kernel](https://github.com/sgl-project/sglang/tree/main/sgl-kernel)** (推荐)
2. **[vllm-kernel](https://github.com/vllm-project/vllm)** (备选)
### 4. 参数卸载策略详解
参数卸载技术允许模型在CPU和磁盘之间动态调度参数，突破显存限制。
#### 三级卸载架构
```python
# 磁盘-CPU-GPU三级卸载配置
cpu_offload=True # 启用CPU卸载
t5_cpu_offload=True # 启用T5编码器CPU卸载
offload_granularity=phase # DIT模型细粒度卸载
t5_offload_granularity=block # T5编码器细粒度卸载
lazy_load = True # 启用延迟加载机制
num_disk_workers = 2 # 磁盘I/O工作线程数
```
#### 卸载策略详解
**延迟加载机制**:
- 模型参数按需从磁盘加载到CPU
- 减少运行时内存占用
- 支持大模型在有限内存下运行
**磁盘存储优化**:
- 使用高速SSD存储模型参数
- 按照block分组存储模型文件
- 参考转换脚本[文档](https://github.com/ModelTC/lightx2v/tree/main/tools/convert/readme_zh.md)，转换时指定`--save_by_block`参数
### 5. 显存优化技术详解
针对720p视频生成的显存优化策略。
#### CUDA内存管理
```python
# CUDA内存清理配置
clean_cuda_cache = True # 及时清理GPU缓存
rotary_chunk = True # 旋转位置编码分块计算
rotary_chunk_size = 100 # 分块大小，可根据显存调整
```
#### 分块计算策略
**旋转位置编码分块**:
- 将长序列分成小块处理
- 减少峰值显存占用
- 保持计算精度
### 6. VAE优化详解
VAE (变分自编码器) 是视频生成的关键组件，优化VAE可以显著提升性能。
#### VAE分块推理
```python
# VAE优化配置
use_tiling_vae = True # 启用VAE分块推理
```
#### 轻量级VAE
```python
# VAE优化配置
use_tae = True
tae_path = "/path to taew2_1.pth"
```
taew2_1.pth 权重可以从[这里](https://github.com/madebyollin/taehv/raw/refs/heads/main/taew2_1.pth)下载
**VAE优化效果**:
- 标准VAE: 基准性能，100%质量保持
- 标准VAE分块: 降低显存，增加推理时间，100%质量保持
- 轻量VAE: 极低显存，视频质量有损
### 7. 模型选择策略
选择合适的模型版本对低资源环境至关重要。
#### 推荐模型对比
**蒸馏模型** (强烈推荐):
- ✅ **[Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v)**
- ✅ **[Wan2.1-I2V-14B-720P-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-720P-StepDistill-CfgDistill-Lightx2v)**
#### 性能优化建议
使用上述蒸馏模型时，可以进一步优化性能：
- 关闭CFG: `"enable_cfg": false`
- 减少推理步数: `infer_step: 4`
- 参考配置文件: [config](https://github.com/ModelTC/LightX2V/tree/main/configs/distill)
## 🚀 完整配置示例
### 预配置模板
- **[14B模型480p视频生成配置](https://github.com/ModelTC/lightx2v/tree/main/configs/offload/disk/wan_i2v_phase_lazy_load_480p.json)**
- **[14B模型720p视频生成配置](https://github.com/ModelTC/lightx2v/tree/main/configs/offload/disk/wan_i2v_phase_lazy_load_720p.json)**
- **[1.3B模型720p视频生成配置](https://github.com/ModelTC/LightX2V/tree/main/configs/offload/block/wan_t2v_1_3b.json)**
- 1.3B模型推理瓶颈是T5 encoder，配置文件专门针对T5进行优化
**[启动脚本](https://github.com/ModelTC/LightX2V/tree/main/scripts/wan/run_wan_i2v_lazy_load.sh)**
## 📚 参考资源
- [参数卸载机制文档](../method_tutorials/offload.md) - 深入了解卸载技术原理
- [量化技术指南](../method_tutorials/quantization.md) - 量化技术详细说明
- [Gradio部署指南](deploy_gradio.md) - Gradio部署详细说明
## ⚠️ 重要注意事项
1. **硬件要求**: 确保您的硬件满足最低配置要求
2. **驱动版本**: 建议使用最新的NVIDIA驱动 (535+)
3. **CUDA版本**: 确保CUDA版本与PyTorch兼容 (建议CUDA 11.8+)
4. **存储空间**: 预留足够的磁盘空间用于模型缓存 (至少50GB)
5. **网络环境**: 首次下载模型需要稳定的网络连接
6. **环境变量**: 务必设置推荐的环境变量以优化性能
**技术支持**: 如遇到问题，请提交Issue到项目仓库。
docs/ZH_CN/source/deploy_guides/lora_deploy.md 0 → 100644
View file @ a1ebc651
# LoRA 模型部署与相关工具
LoRA (Low-Rank Adaptation) 是一种高效的模型微调技术，通过低秩矩阵分解显著减少可训练参数数量。LightX2V 全面支持 LoRA 技术，包括 LoRA 推理、LoRA 提取和 LoRA 合并等功能。
## 🎯 LoRA 技术特性
- **灵活部署**：支持动态加载和移除 LoRA 权重
- **多种格式**：支持多种 LoRA 权重格式和命名约定
- **工具完善**：提供完整的 LoRA 提取、合并工具链
## 📜 LoRA 推理部署
### 配置文件方式
在配置文件中指定 LoRA 路径：
```json
{
"lora_configs": [
{
"path": "/path/to/your/lora.safetensors",
"strength": 1.0
}
]
}
```
**配置参数说明：**
- `lora_path`: LoRA 权重文件路径列表，支持多个 LoRA 同时加载
- `strength_model`: LoRA 强度系数 (alpha)，控制 LoRA 对原模型的影响程度
### 命令行方式
直接在命令行中指定 LoRA 路径（仅支持加载单个 LoRA）：
```bash
python -m lightx2v.infer \
--model_cls wan2.1 \
--task t2v \
--model_path /path/to/model \
--config_json /path/to/config.json \
--lora_path /path/to/your/lora.safetensors \
--lora_strength 0.8 \
--prompt "Your prompt here"
```
### 多LoRA配置
要使用多个具有不同强度的LoRA，请在配置JSON文件中指定：
```json
{
"lora_configs": [
{
"path": "/path/to/first_lora.safetensors",
"strength": 0.8
},
{
"path": "/path/to/second_lora.safetensors",
"strength": 0.5
}
]
}
```
### 支持的 LoRA 格式
LightX2V 支持多种 LoRA 权重命名约定：
| 格式类型 | 权重命名 | 说明 |
|----------|----------|------|
| **标准 LoRA** | `lora_A.weight`, `lora_B.weight` | 标准的 LoRA 矩阵分解格式 |
| **Down/Up 格式** | `lora_down.weight`, `lora_up.weight` | 另一种常见的命名约定 |
| **差值格式** | `diff` | `weight` 权重差值 |
| **偏置差值** | `diff_b` | `bias` 权重差值 |
| **调制差值** | `diff_m` | `modulation` 权重差值 |
### 推理脚本示例
**步数蒸馏 LoRA 推理：**
```bash
# T2V LoRA 推理
bash scripts/wan/run_wan_t2v_distill_4step_cfg_lora.sh
# I2V LoRA 推理
bash scripts/wan/run_wan_i2v_distill_4step_cfg_lora.sh
```
**音频驱动 LoRA 推理：**
```bash
bash scripts/wan/run_wan_i2v_audio.sh
```
### API 服务中使用 LoRA
在 API 服务中通过 [config 文件](wan_t2v_distill_4step_cfg_lora.json) 指定，对 [scripts/server/start_server.sh](https://github.com/ModelTC/lightx2v/blob/main/scripts/server/start_server.sh) 中的启动命令进行修改：
```bash
python -m lightx2v.api_server \
--model_cls wan2.1_distill \
--task t2v \
--model_path $model_path \
--config_json ${lightx2v_path}/configs/distill/wan_t2v_distill_4step_cfg_lora.json \
--port 8000 \
--nproc_per_node 1
```
## 🔧 LoRA 提取工具
使用 `tools/extract/lora_extractor.py` 从两个模型的差异中提取 LoRA 权重。
### 基本用法
```bash
python tools/extract/lora_extractor.py \
--source-model /path/to/base/model \
--target-model /path/to/finetuned/model \
--output /path/to/extracted/lora.safetensors \
--rank 32
```
### 参数说明
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--source-model` | str | ✅ | - | 基础模型路径 |
| `--target-model` | str | ✅ | - | 微调后模型路径 |
| `--output` | str | ✅ | - | 输出 LoRA 文件路径 |
| `--source-type` | str | ❌ | `safetensors` | 基础模型格式 (`safetensors`/`pytorch`) |
| `--target-type` | str | ❌ | `safetensors` | 微调模型格式 (`safetensors`/`pytorch`) |
| `--output-format` | str | ❌ | `safetensors` | 输出格式 (`safetensors`/`pytorch`) |
| `--rank` | int | ❌ | `32` | LoRA 秩值 |
| `--output-dtype` | str | ❌ | `bf16` | 输出数据类型 |
| `--diff-only` | bool | ❌ | `False` | 仅保存权重差值，不进行 LoRA 分解 |
### 高级用法示例
**提取高秩 LoRA：**
```bash
python tools/extract/lora_extractor.py \
--source-model /path/to/base/model \
--target-model /path/to/finetuned/model \
--output /path/to/high_rank_lora.safetensors \
--rank 64 \
--output-dtype fp16
```
**仅保存权重差值：**
```bash
python tools/extract/lora_extractor.py \
--source-model /path/to/base/model \
--target-model /path/to/finetuned/model \
--output /path/to/weight_diff.safetensors \
--diff-only
```
## 🔀 LoRA 合并工具
使用 `tools/extract/lora_merger.py` 将 LoRA 权重合并到基础模型中，以进行后续量化等操作。
### 基本用法
```bash
python tools/extract/lora_merger.py \
--source-model /path/to/base/model \
--lora-model /path/to/lora.safetensors \
--output /path/to/merged/model.safetensors \
--alpha 1.0
```
### 参数说明
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--source-model` | str | ✅ | 无 | 基础模型路径 |
| `--lora-model` | str | ✅ | 无 | LoRA 权重路径 |
| `--output` | str | ✅ | 无 | 输出合并模型路径 |
| `--source-type` | str | ❌ | `safetensors` | 基础模型格式 |
| `--lora-type` | str | ❌ | `safetensors` | LoRA 权重格式 |
| `--output-format` | str | ❌ | `safetensors` | 输出格式 |
| `--alpha` | float | ❌ | `1.0` | LoRA 合并强度 |
| `--output-dtype` | str | ❌ | `bf16` | 输出数据类型 |
### 高级用法示例
**部分强度合并：**
```bash
python tools/extract/lora_merger.py \
--source-model /path/to/base/model \
--lora-model /path/to/lora.safetensors \
--output /path/to/merged_model.safetensors \
--alpha 0.7 \
--output-dtype fp32
```
**多格式支持：**
```bash
python tools/extract/lora_merger.py \
--source-model /path/to/base/model.pt \
--source-type pytorch \
--lora-model /path/to/lora.safetensors \
--lora-type safetensors \
--output /path/to/merged_model.safetensors \
--output-format safetensors \
--alpha 1.0
```
docs/ZH_CN/source/getting_started/benchmark.md 0 → 100644
View file @ a1ebc651
# 基准测试
由于要展示一些视频的播放效果和详细的性能对比，您可以在这个[🔗 页面](https://github.com/ModelTC/LightX2V/blob/main/docs/ZH_CN/source/getting_started/benchmark_source.md)获得更好的展示效果以及相对应的文档内容。
docs/ZH_CN/source/getting_started/benchmark_source.md 0 → 100644
View file @ a1ebc651
# 🚀 基准测试
> 本文档展示了LightX2V在不同硬件环境下的性能测试结果，包括H200和RTX 4090平台的详细对比数据。
---
## 🖥️ H200 环境 (~140GB显存)
### 📋 软件环境配置
| 组件 | 版本 |
|:-----|:-----|
| **Python** | 3.11 |
| **PyTorch** | 2.7.1+cu128 |
| **SageAttention** | 2.2.0 |
| **vLLM** | 0.9.2 |
| **sgl-kernel** | 0.1.8 |
---
### 🎬 480P 5s视频测试
**测试配置:**
- **模型**: [Wan2.1-I2V-14B-480P-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-Lightx2v)
- **参数**: `infer_steps=40`, `seed=42`, `enable_cfg=True`
#### 📊 性能对比表
| 配置 | 推理时间(s) | GPU显存占用(GB) | 加速比 | 视频效果 |
|:-----|:----------:|:---------------:|:------:|:--------:|
| **Wan2.1 Official** | 366 | 71 | 1.0x | <video src="https://github.com/user-attachments/assets/24fb112e-c868-4484-b7f0-d9542979c2c3" width="200px"></video> |
| **FastVideo** | 292 | 26 | **1.25x** | <video src="https://github.com/user-attachments/assets/26c01987-441b-4064-b6f4-f89347fddc15" width="200px"></video> |
| **LightX2V_1** | 250 | 53 | **1.46x** | <video src="https://github.com/user-attachments/assets/7bffe48f-e433-430b-91dc-ac745908ba3a" width="200px"></video> |
| **LightX2V_2** | 216 | 50 | **1.70x** | <video src="https://github.com/user-attachments/assets/0a24ca47-c466-433e-8a53-96f259d19841" width="200px"></video> |
| **LightX2V_3** | 191 | 35 | **1.92x** | <video src="https://github.com/user-attachments/assets/970c73d3-1d60-444e-b64d-9bf8af9b19f1" width="200px"></video> |
| **LightX2V_3-Distill** | 14 | 35 | **🏆 20.85x** | <video src="https://github.com/user-attachments/assets/b4dc403c-919d-4ba1-b29f-ef53640c0334" width="200px"></video> |
| **LightX2V_4** | 107 | 35 | **3.41x** | <video src="https://github.com/user-attachments/assets/49cd2760-4be2-432c-bf4e-01af9a1303dd" width="200px"></video> |
---
### 🎬 720P 5s视频测试
**测试配置:**
- **模型**: [Wan2.1-I2V-14B-720P-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-720P-Lightx2v)
- **参数**: `infer_steps=40`, `seed=1234`, `enable_cfg=True`
#### 📊 性能对比表
| 配置 | 推理时间(s) | GPU显存占用(GB) | 加速比 | 视频效果 |
|:-----|:----------:|:---------------:|:------:|:--------:|
| **Wan2.1 Official** | 974 | 81 | 1.0x | <video src="https://github.com/user-attachments/assets/a28b3956-ec52-4a8e-aa97-c8baf3129771" width="200px"></video> |
| **FastVideo** | 914 | 40 | **1.07x** | <video src="https://github.com/user-attachments/assets/bd09a886-e61c-4214-ae0f-6ff2711cafa8" width="200px"></video> |
| **LightX2V_1** | 807 | 65 | **1.21x** | <video src="https://github.com/user-attachments/assets/a79aae87-9560-4935-8d05-7afc9909e993" width="200px"></video> |
| **LightX2V_2** | 751 | 57 | **1.30x** | <video src="https://github.com/user-attachments/assets/cb389492-9b33-40b6-a132-84e6cb9fa620" width="200px"></video> |
| **LightX2V_3** | 671 | 43 | **1.45x** | <video src="https://github.com/user-attachments/assets/71c3d085-5d8a-44e7-aac3-412c108d9c53" width="200px"></video> |
| **LightX2V_3-Distill** | 44 | 43 | **🏆 22.14x** | <video src="https://github.com/user-attachments/assets/9fad8806-938f-4527-b064-0c0b58f0f8c2" width="200px"></video> |
| **LightX2V_4** | 344 | 46 | **2.83x** | <video src="https://github.com/user-attachments/assets/c744d15d-9832-4746-b72c-85fa3b87ed0d" width="200px"></video> |
---
## 🖥️ RTX 4090 环境 (~24GB显存)
### 📋 软件环境配置
| 组件 | 版本 |
|:-----|:-----|
| **Python** | 3.9.16 |
| **PyTorch** | 2.5.1+cu124 |
| **SageAttention** | 2.1.0 |
| **vLLM** | 0.6.6 |
| **sgl-kernel** | 0.0.5 |
| **q8-kernels** | 0.0.0 |
---
### 🎬 480P 5s视频测试
**测试配置:**
- **模型**: [Wan2.1-I2V-14B-480P-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-Lightx2v)
- **参数**: `infer_steps=40`, `seed=42`, `enable_cfg=True`
#### 📊 性能对比表
| 配置 | 推理时间(s) | GPU显存占用(GB) | 加速比 | 视频效果 |
|:-----|:----------:|:---------------:|:------:|:--------:|
| **Wan2GP(profile=3)** | 779 | 20 | **1.0x** | <video src="https://github.com/user-attachments/assets/ba548a48-04f8-4616-a55a-ad7aed07d438" width="200px"></video> |
| **LightX2V_5** | 738 | 16 | **1.05x** | <video src="https://github.com/user-attachments/assets/ce72ab7d-50a7-4467-ac8c-a6ed1b3827a7" width="200px"></video> |
| **LightX2V_5-Distill** | 68 | 16 | **11.45x** | <video src="https://github.com/user-attachments/assets/5df4b8a7-3162-47f8-a359-e22fbb4d1836" width="200px"></video> |
| **LightX2V_6** | 630 | 12 | **1.24x** | <video src="https://github.com/user-attachments/assets/d13cd939-363b-4f8b-80d9-d3a145c46676" width="200px"></video> |
| **LightX2V_6-Distill** | 63 | 12 | **🏆 12.36x** | <video src="https://github.com/user-attachments/assets/f372bce4-3c2f-411d-aa6b-c4daeb467d90" width="200px"></video> |
---
### 🎬 720P 5s视频测试
**测试配置:**
- **模型**: [Wan2.1-I2V-14B-720P-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-720P-Lightx2v)
- **参数**: `infer_steps=40`, `seed=1234`, `enable_cfg=True`
#### 📊 性能对比表
| 配置 | 推理时间(s) | GPU显存占用(GB) | 加速比 | 视频效果 |
|:-----|:----------:|:---------------:|:------:|:--------:|
| **Wan2GP(profile=3)** | -- | OOM | -- | <video src="--" width="200px"></video> |
| **LightX2V_5** | 2473 | 23 | -- | <video src="https://github.com/user-attachments/assets/0e83b146-3297-4c63-831c-8462cc657cad" width="200px"></video> |
| **LightX2V_5-Distill** | 183 | 23 | -- | <video src="https://github.com/user-attachments/assets/976d0af0-244c-4abe-b2cb-01f68ad69d3c" width="200px"></video> |
| **LightX2V_6** | 2169 | 18 | -- | <video src="https://github.com/user-attachments/assets/cf9edf82-53e1-46af-a000-79a88af8ad4a" width="200px"></video> |
| **LightX2V_6-Distill** | 171 | 18 | -- | <video src="https://github.com/user-attachments/assets/e3064b03-6cd6-4c82-9e31-ab28b3165798" width="200px"></video> |
---
## 📖 配置说明
### 🖥️ H200 环境配置说明
| 配置 | 技术特点 |
|:-----|:---------|
| **Wan2.1 Official** | 基于[Wan2.1官方仓库](https://github.com/Wan-Video/Wan2.1)的原始实现 |
| **FastVideo** | 基于[FastVideo官方仓库](https://github.com/hao-ai-lab/FastVideo)，使用SageAttention2后端优化 |
| **LightX2V_1** | 使用SageAttention2替换原生注意力机制，采用DIT BF16+FP32(部分敏感层)混合精度计算，在保持精度的同时提升计算效率 |
| **LightX2V_2** | 统一使用BF16精度计算，进一步减少显存占用和计算开销，同时保持生成质量 |
| **LightX2V_3** | 引入FP8量化技术显著减少计算精度要求，结合Tiling VAE技术优化显存使用 |
| **LightX2V_3-Distill** | 在LightX2V_3基础上使用4步蒸馏模型(`infer_steps=4`, `enable_cfg=False`)，进一步减少推理步数并保持生成质量 |
| **LightX2V_4** | 在LightX2V_3基础上加入TeaCache(teacache_thresh=0.2)缓存复用技术，通过智能跳过冗余计算实现加速 |
### 🖥️ RTX 4090 环境配置说明
| 配置 | 技术特点 |
|:-----|:---------|
| **Wan2GP(profile=3)** | 基于[Wan2GP仓库](https://github.com/deepbeepmeep/Wan2GP)实现，使用MMGP优化技术。profile=3配置适用于至少32GB内存和24GB显存的RTX 3090/4090环境，通过牺牲显存来适应有限的内存资源。使用量化模型：[480P模型](https://huggingface.co/DeepBeepMeep/Wan2.1/blob/main/wan2.1_image2video_480p_14B_quanto_mbf16_int8.safetensors)和[720P模型](https://huggingface.co/DeepBeepMeep/Wan2.1/blob/main/wan2.1_image2video_720p_14B_quanto_mbf16_int8.safetensors) |
| **LightX2V_5** | 使用SageAttention2替换原生注意力机制，采用DIT FP8+FP32(部分敏感层)混合精度计算，启用CPU offload技术，将部分敏感层执行FP32精度计算，将DIT推理过程中异步数据卸载到CPU上，节省显存，offload粒度为block级别 |
| **LightX2V_5-Distill** | 在LightX2V_5基础上使用4步蒸馏模型(`infer_steps=4`, `enable_cfg=False`)，进一步减少推理步数并保持生成质量 |
| **LightX2V_6** | 在LightX2V_3基础上启用CPU offload技术，将部分敏感层执行FP32精度计算，将DIT推理过程中异步数据卸载到CPU上，节省显存，offload粒度为block级别 |
| **LightX2V_6-Distill** | 在LightX2V_6基础上使用4步蒸馏模型(`infer_steps=4`, `enable_cfg=False`)，进一步减少推理步数并保持生成质量 |
---
## 📁 配置文件参考
基准测试相关的配置文件和运行脚本可在以下位置获取：
| 类型 | 链接 | 说明 |
|:-----|:-----|:-----|
| **配置文件** | [configs/bench](https://github.com/ModelTC/LightX2V/tree/main/configs/bench) | 包含各种优化配置的JSON文件 |
| **运行脚本** | [scripts/bench](https://github.com/ModelTC/LightX2V/tree/main/scripts/bench) | 包含基准测试的执行脚本 |
---
> 💡 **提示**: 建议根据您的硬件配置选择合适的优化方案，以获得最佳的性能表现。
docs/ZH_CN/source/getting_started/model_structure.md 0 → 100644
View file @ a1ebc651
# 模型格式与加载指南
## 📖 概述
LightX2V 是一个灵活的视频生成推理框架，支持多种模型来源和格式，为用户提供丰富的选择：
- ✅ **Wan 官方模型**：直接兼容 Wan2.1 和 Wan2.2 官方发布的完整模型
- ✅ **单文件模型**：支持 LightX2V 发布的单文件格式模型（包含量化版本）
- ✅ **LoRA 模型**：支持加载 LightX2V 发布的蒸馏 LoRA
本文档将详细介绍各种模型格式的使用方法、配置参数和最佳实践。
---
## 🗂️ 格式一：Wan 官方模型
### 模型仓库
- [Wan2.1 Collection](https://huggingface.co/collections/Wan-AI/wan21-68ac4ba85372ae5a8e282a1b)
- [Wan2.2 Collection](https://huggingface.co/collections/Wan-AI/wan22-68ac4ae80a8b477e79636fc8)
### 模型特点
- **官方保证**：Wan-AI 官方发布的完整模型，质量最高
- **完整组件**：包含所有必需的组件（DIT、T5、CLIP、VAE）
- **原始精度**：使用 BF16/FP32 精度，无量化损失
- **兼容性强**：与 Wan 官方工具链完全兼容
### Wan2.1 官方模型
#### 目录结构
以 [Wan2.1-I2V-14B-720P](https://huggingface.co/Wan-AI/Wan2.1-I2V-14B-720P) 为例：
```
Wan2.1-I2V-14B-720P/
├── diffusion_pytorch_model-00001-of-00007.safetensors # DIT 模型分片 1
├── diffusion_pytorch_model-00002-of-00007.safetensors # DIT 模型分片 2
├── diffusion_pytorch_model-00003-of-00007.safetensors # DIT 模型分片 3
├── diffusion_pytorch_model-00004-of-00007.safetensors # DIT 模型分片 4
├── diffusion_pytorch_model-00005-of-00007.safetensors # DIT 模型分片 5
├── diffusion_pytorch_model-00006-of-00007.safetensors # DIT 模型分片 6
├── diffusion_pytorch_model-00007-of-00007.safetensors # DIT 模型分片 7
├── diffusion_pytorch_model.safetensors.index.json # 分片索引文件
├── models_t5_umt5-xxl-enc-bf16.pth # T5 文本编码器
├── models_clip_open-clip-xlm-roberta-large-vit-huge-14.pth # CLIP 编码器
├── Wan2.1_VAE.pth # VAE 编解码器
├── config.json # 模型配置
├── xlm-roberta-large/ # CLIP tokenizer
├── google/ # T5 tokenizer
├── assets/
└── examples/
```
#### 使用方法
```bash
# 下载模型
huggingface-cli download Wan-AI/Wan2.1-I2V-14B-720P \
--local-dir ./models/Wan2.1-I2V-14B-720P
# 配置启动脚本
model_path=./models/Wan2.1-I2V-14B-720P
lightx2v_path=/path/to/LightX2V
# 运行推理
cd LightX2V/scripts
bash wan/run_wan_i2v.sh
```
### Wan2.2 官方模型
#### 目录结构
以 [Wan2.2-I2V-A14B](https://huggingface.co/Wan-AI/Wan2.2-I2V-A14B) 为例：
```
Wan2.2-I2V-A14B/
├── high_noise_model/ # 高噪声模型目录
│ ├── diffusion_pytorch_model-00001-of-00009.safetensors
│ ├── diffusion_pytorch_model-00002-of-00009.safetensors
│ ├── ...
│ ├── diffusion_pytorch_model-00009-of-00009.safetensors
│ └── diffusion_pytorch_model.safetensors.index.json
├── low_noise_model/ # 低噪声模型目录
│ ├── diffusion_pytorch_model-00001-of-00009.safetensors
│ ├── diffusion_pytorch_model-00002-of-00009.safetensors
│ ├── ...
│ ├── diffusion_pytorch_model-00009-of-00009.safetensors
│ └── diffusion_pytorch_model.safetensors.index.json
├── models_t5_umt5-xxl-enc-bf16.pth # T5 文本编码器
├── Wan2.1_VAE.pth # VAE 编解码器
├── configuration.json # 模型配置
├── google/ # T5 tokenizer
├── assets/ # 示例资源（可选）
└── examples/ # 示例文件（可选）
```
#### 使用方法
```bash
# 下载模型
huggingface-cli download Wan-AI/Wan2.2-I2V-A14B \
--local-dir ./models/Wan2.2-I2V-A14B
# 配置启动脚本
model_path=./models/Wan2.2-I2V-A14B
lightx2v_path=/path/to/LightX2V
# 运行推理
cd LightX2V/scripts
bash wan22/run_wan22_moe_i2v.sh
```
### 可用模型列表
#### Wan2.1 官方模型列表
| 模型名称 | 下载链接 |
|---------|----------|
| Wan2.1-I2V-14B-720P | [链接](https://huggingface.co/Wan-AI/Wan2.1-I2V-14B-720P) |
| Wan2.1-I2V-14B-480P | [链接](https://huggingface.co/Wan-AI/Wan2.1-I2V-14B-480P) |
| Wan2.1-T2V-14B | [链接](https://huggingface.co/Wan-AI/Wan2.1-T2V-14B) |
| Wan2.1-T2V-1.3B | [链接](https://huggingface.co/Wan-AI/Wan2.1-T2V-1.3B) |
| Wan2.1-FLF2V-14B-720P | [链接](https://huggingface.co/Wan-AI/Wan2.1-FLF2V-14B-720P) |
| Wan2.1-VACE-14B | [链接](https://huggingface.co/Wan-AI/Wan2.1-VACE-14B) |
| Wan2.1-VACE-1.3B | [链接](https://huggingface.co/Wan-AI/Wan2.1-VACE-1.3B) |
#### Wan2.2 官方模型列表
| 模型名称 | 下载链接 |
|---------|----------|
| Wan2.2-I2V-A14B | [链接](https://huggingface.co/Wan-AI/Wan2.2-I2V-A14B) |
| Wan2.2-T2V-A14B | [链接](https://huggingface.co/Wan-AI/Wan2.2-T2V-A14B) |
| Wan2.2-TI2V-5B | [链接](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B) |
| Wan2.2-Animate-14B | [链接](https://huggingface.co/Wan-AI/Wan2.2-Animate-14B) |
### 使用提示
> 💡 **量化模型使用**：如需使用量化模型，可参考[模型转换脚本](https://github.com/ModelTC/LightX2V/blob/main/tools/convert/readme_zh.md)进行转换，或直接使用下方格式二中的预转换量化模型
>
> 💡 **显存优化**：对于 RTX 4090 24GB 或更小显存的设备，建议结合量化技术和 CPU 卸载功能：
> - 量化配置：参考[量化技术文档](../method_tutorials/quantization.md)
> - CPU 卸载：参考[参数卸载文档](../method_tutorials/offload.md)
> - Wan2.1 配置：参考 [offload 配置文件](https://github.com/ModelTC/LightX2V/tree/main/configs/offload)
> - Wan2.2 配置：参考 [wan22 配置文件](https://github.com/ModelTC/LightX2V/tree/main/configs/wan22) 中以 `4090` 结尾的配置
---
## 🗂️ 格式二：LightX2V 单文件模型（推荐）
### 模型仓库
- [Wan2.1-LightX2V](https://huggingface.co/lightx2v/Wan2.1-Distill-Models)
- [Wan2.2-LightX2V](https://huggingface.co/lightx2v/Wan2.2-Distill-Models)
### 模型特点
- **单文件管理**：单个 safetensors 文件，易于管理和部署
- **多精度支持**：提供原始精度、FP8、INT8 等多种精度版本
- **蒸馏加速**：支持 4-step 快速推理
- **工具兼容**：兼容 ComfyUI 等其他工具
**示例**：
- `wan2.1_i2v_720p_lightx2v_4step.safetensors` - 720P 图生视频原始精度
- `wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step.safetensors` - 720P 图生视频 FP8 量化
- `wan2.1_i2v_480p_int8_lightx2v_4step.safetensors` - 480P 图生视频 INT8 量化
- ...
### Wan2.1 单文件模型
#### 场景 A：下载单个模型文件
**步骤 1：选择并下载模型**
```bash
# 创建模型目录
mkdir -p ./models/wan2.1_i2v_720p
# 下载 720P 图生视频 FP8 量化模型
huggingface-cli download lightx2v/Wan2.1-Distill-Models \
--local-dir ./models/wan2.1_i2v_720p \
--include "wan2.1_i2v_720p_lightx2v_4step.safetensors"
```
**步骤 2：手动组织其他模块**
目录结构如下
```
wan2.1_i2v_720p/
├── wan2.1_i2v_720p_lightx2v_4step.safetensors # 原始精度
└── t5/clip/vae/config.json/xlm-roberta-large/google等其他组件 # 需要手动组织
```
**步骤 3：配置启动脚本**
```bash
# 在启动脚本中设置（指向包含模型文件的目录）
model_path=./models/wan2.1_i2v_720p
lightx2v_path=/path/to/LightX2V
# 运行脚本
cd LightX2V/scripts
bash wan/run_wan_i2v_distill_4step_cfg.sh
```
> 💡 **提示**：当目录下只有一个模型文件时，LightX2V 会自动加载该文件。
#### 场景 B：下载多个模型文件
当您下载了多个不同精度的模型到同一目录时，需要在配置文件中明确指定使用哪个模型。
**步骤 1：下载多个模型**
```bash
# 创建模型目录
mkdir -p ./models/wan2.1_i2v_720p_multi
# 下载原始精度模型
huggingface-cli download lightx2v/Wan2.1-Distill-Models \
--local-dir ./models/wan2.1_i2v_720p_multi \
--include "wan2.1_i2v_720p_lightx2v_4step.safetensors"
# 下载 FP8 量化模型
huggingface-cli download lightx2v/Wan2.1-Distill-Models \
--local-dir ./models/wan2.1_i2v_720p_multi \
--include "wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step.safetensors"
# 下载 INT8 量化模型
huggingface-cli download lightx2v/Wan2.1-Distill-Models \
--local-dir ./models/wan2.1_i2v_720p_multi \
--include "wan2.1_i2v_720p_int8_lightx2v_4step.safetensors"
```
**步骤 2：手动组织其他模块**
目录结构如下：
```
wan2.1_i2v_720p_multi/
├── wan2.1_i2v_720p_lightx2v_4step.safetensors # 原始精度
├── wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step.safetensors # FP8 量化
└── wan2.1_i2v_720p_int8_lightx2v_4step.safetensors # INT8 量化
└── t5/clip/vae/config.json/xlm-roberta-large/google等其他组件 # 需要手动组织
```
**步骤 3：在配置文件中指定模型**
编辑配置文件（如 `configs/distill/wan_i2v_distill_4step_cfg.json`）：
```json
{
// 使用原始精度模型
"dit_original_ckpt": "./models/wan2.1_i2v_720p_multi/wan2.1_i2v_720p_lightx2v_4step.safetensors",
// 或使用 FP8 量化模型
// "dit_quantized_ckpt": "./models/wan2.1_i2v_720p_multi/wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step.safetensors",
// "dit_quantized": true,
// "dit_quant_scheme": "fp8-vllm",
// 或使用 INT8 量化模型
// "dit_quantized_ckpt": "./models/wan2.1_i2v_720p_multi/wan2.1_i2v_720p_int8_lightx2v_4step.safetensors",
// "dit_quantized": true,
// "dit_quant_scheme": "int8-vllm",
// 其他配置...
}
```
### 使用提示
> 💡 **配置参数说明**：
> - **dit_original_ckpt**：用于指定原始精度模型（BF16/FP32/FP16）的路径
> - **dit_quantized_ckpt**：用于指定量化模型（FP8/INT8）的路径，需配合 `dit_quantized` 和 `dit_quant_scheme` 参数使用
**步骤 4：启动推理**
```bash
cd LightX2V/scripts
bash wan/run_wan_i2v_distill_4step_cfg.sh
```
### Wan2.2 单文件模型
#### 目录结构要求
使用 Wan2.2 单文件模型时，需要手动创建特定的目录结构：
```
wan2.2_models/
├── high_noise_model/ # 高噪声模型目录（必须）
│ └── wan2.2_i2v_A14b_high_noise_lightx2v_4step.safetensors # 高噪声模型文件
└── low_noise_model/ # 低噪声模型目录（必须）
│ └── wan2.2_i2v_A14b_low_noise_lightx2v_4step.safetensors # 低噪声模型文件
└── t5/vae/config.json/xlm-roberta-large/google等其他组件 # 需要手动组织
```
#### 场景 A：每个目录下只有一个模型文件
```bash
# 创建必需的子目录
mkdir -p ./models/wan2.2_models/high_noise_model
mkdir -p ./models/wan2.2_models/low_noise_model
# 下载高噪声模型到对应目录
huggingface-cli download lightx2v/Wan2.2-Distill-Models \
--local-dir ./models/wan2.2_models/high_noise_model \
--include "wan2.2_i2v_A14b_high_noise_scaled_fp8_e4m3_lightx2v_4step.safetensors"
# 下载低噪声模型到对应目录
huggingface-cli download lightx2v/Wan2.2-Distill-Models \
--local-dir ./models/wan2.2_models/low_noise_model \
--include "wan2.2_i2v_A14b_low_noise_scaled_fp8_e4m3_lightx2v_4step.safetensors"
# 配置启动脚本（指向父目录）
model_path=./models/wan2.2_models
lightx2v_path=/path/to/LightX2V
# 运行脚本
cd LightX2V/scripts
bash wan22/run_wan22_moe_i2v_distill.sh
```
> 💡 **提示**：当每个子目录下只有一个模型文件时，LightX2V 会自动加载。
#### 场景 B：每个目录下有多个模型文件
当您在 `high_noise_model/` 和 `low_noise_model/` 目录下分别放置了多个不同精度的模型时，需要在配置文件中明确指定。
```bash
# 创建目录
mkdir -p ./models/wan2.2_models_multi/high_noise_model
mkdir -p ./models/wan2.2_models_multi/low_noise_model
# 下载高噪声模型的多个版本
huggingface-cli download lightx2v/Wan2.2-Distill-Models \
--local-dir ./models/wan2.2_models_multi/high_noise_model \
--include "wan2.2_i2v_A14b_high_noise_*.safetensors"
# 下载低噪声模型的多个版本
huggingface-cli download lightx2v/Wan2.2-Distill-Models \
--local-dir ./models/wan2.2_models_multi/low_noise_model \
--include "wan2.2_i2v_A14b_low_noise_*.safetensors"
```
**目录结构**：
```
wan2.2_models_multi/
├── high_noise_model/
│ ├── wan2.2_i2v_A14b_high_noise_lightx2v_4step.safetensors # 原始精度
│ ├── wan2.2_i2v_A14b_high_noise_fp8_e4m3_lightx2v_4step.safetensors # FP8 量化
│ └── wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors # INT8 量化
└── low_noise_model/
│ ├── wan2.2_i2v_A14b_low_noise_lightx2v_4step.safetensors # 原始精度
│ ├── wan2.2_i2v_A14b_low_noise_fp8_e4m3_lightx2v_4step.safetensors # FP8 量化
│ └── wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors # INT8 量化
└── t5/vae/config.json/xlm-roberta-large/google等其他组件 # 需要手动组织
```
**配置文件设置**：
```json
{
// 使用原始精度模型
"high_noise_original_ckpt": "./models/wan2.2_models_multi/high_noise_model/wan2.2_i2v_A14b_high_noise_lightx2v_4step.safetensors",
"low_noise_original_ckpt": "./models/wan2.2_models_multi/low_noise_model/wan2.2_i2v_A14b_low_noise_lightx2v_4step.safetensors",
// 或使用 FP8 量化模型
// "high_noise_quantized_ckpt": "./models/wan2.2_models_multi/high_noise_model/wan2.2_i2v_A14b_high_noise_fp8_e4m3_lightx2v_4step.safetensors",
// "low_noise_quantized_ckpt": "./models/wan2.2_models_multi/low_noise_model/wan2.2_i2v_A14b_low_noise_fp8_e4m3_lightx2v_4step.safetensors",
// "dit_quantized": true,
// "dit_quant_scheme": "fp8-vllm"
// 或使用 INT8 量化模型
// "high_noise_quantized_ckpt": "./models/wan2.2_models_multi/high_noise_model/wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors",
// "low_noise_quantized_ckpt": "./models/wan2.2_models_multi/low_noise_model/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
// "dit_quantized": true,
// "dit_quant_scheme": "int8-vllm"
}
```
### 使用提示
> 💡 **配置参数说明**：
> - **high_noise_original_ckpt** / **low_noise_original_ckpt**：用于指定原始精度模型（BF16/FP32/FP16）的路径
> - **high_noise_quantized_ckpt** / **low_noise_quantized_ckpt**：用于指定量化模型（FP8/INT8）的路径，需配合 `dit_quantized` 和 `dit_quant_scheme` 参数使用
### 可用模型列表
#### Wan2.1 单文件模型列表
**图生视频模型（I2V）**
| 文件名 | 精度 | 说明 |
|--------|------|------|
| `wan2.1_i2v_480p_lightx2v_4step.safetensors` | BF16 | 4步模型原始精度 |
| `wan2.1_i2v_480p_scaled_fp8_e4m3_lightx2v_4step.safetensors` | FP8 | 4步模型FP8 量化 |
| `wan2.1_i2v_480p_int8_lightx2v_4step.safetensors` | INT8 | 4步模型INT8 量化 |
| `wan2.1_i2v_480p_scaled_fp8_e4m3_lightx2v_4step_comfyui.safetensors` | FP8 | 4步模型ComfyUI 格式 |
| `wan2.1_i2v_720p_lightx2v_4step.safetensors` | BF16 | 4步模型原始精度 |
| `wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step.safetensors` | FP8 | 4步模型FP8 量化 |
| `wan2.1_i2v_720p_int8_lightx2v_4step.safetensors` | INT8 | 4步模型INT8 量化 |
| `wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step_comfyui.safetensors` | FP8 | 4步模型ComfyUI 格式 |
**文生视频模型（T2V）**
| 文件名 | 精度 | 说明 |
|--------|------|------|
| `wan2.1_t2v_14b_lightx2v_4step.safetensors` | BF16 | 4步模型原始精度 |
| `wan2.1_t2v_14b_scaled_fp8_e4m3_lightx2v_4step.safetensors` | FP8 | 4步模型FP8 量化 |
| `wan2.1_t2v_14b_int8_lightx2v_4step.safetensors` | INT8 | 4步模型INT8 量化 |
| `wan2.1_t2v_14b_scaled_fp8_e4m3_lightx2v_4step_comfyui.safetensors` | FP8 | 4步模型ComfyUI 格式 |
#### Wan2.2 单文件模型列表
**图生视频模型（I2V）- A14B 系列**
| 文件名 | 精度 | 说明 |
|--------|------|------|
| `wan2.2_i2v_A14b_high_noise_lightx2v_4step.safetensors` | BF16 | 高噪声模型-4步原始精度 |
| `wan2.2_i2v_A14b_high_noise_scaled_fp8_e4m3_lightx2v_4step.safetensors` | FP8 | 高噪声模型-4步FP8量化 |
| `wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors` | INT8 | 高噪声模型-4步INT8量化 |
| `wan2.2_i2v_A14b_low_noise_lightx2v_4step.safetensors` | BF16 | 低噪声模型-4步原始精度 |
| `wan2.2_i2v_A14b_low_noise_scaled_fp8_e4m3_lightx2v_4step.safetensors` | FP8 | 低噪声模型-4步FP8量化 |
| `wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors` | INT8 | 低噪声模型-4步INT8量化 |
> 💡 **使用提示**：
> - Wan2.2 模型采用双噪声架构，需要同时下载高噪声（high_noise）和低噪声（low_noise）模型
> - 详细的目录组织方式请参考上方"Wan2.2 单文件模型"部分
---
## 🗂️ 格式三：LightX2V LoRA 模型
LoRA（Low-Rank Adaptation）模型提供了一种轻量级的模型微调方案，可以在不修改基础模型的情况下实现特定效果的定制化。
### 模型仓库
- **Wan2.1 LoRA 模型**：[lightx2v/Wan2.1-Distill-Loras](https://huggingface.co/lightx2v/Wan2.1-Distill-Loras)
- **Wan2.2 LoRA 模型**：[lightx2v/Wan2.2-Distill-Loras](https://huggingface.co/lightx2v/Wan2.2-Distill-Loras)
### 使用方式
#### 方式一：离线合并
将 LoRA 权重离线合并到基础模型中，生成新的完整模型文件。
**操作步骤**：
参考 [模型转换文档](https://github.com/ModelTC/lightx2v/tree/main/tools/convert/readme_zh.md) 进行离线合并。
**优点**：
- ✅ 推理时无需额外加载 LoRA
- ✅ 性能更优
**缺点**：
- ❌ 需要额外存储空间
- ❌ 切换不同 LoRA 需要重新合并
#### 方式二：在线加载
在推理时动态加载 LoRA 权重，无需修改基础模型。
**LoRA 应用原理**：
```python
# LoRA 权重应用公式
# lora_scale = (alpha / rank)
# W' = W + lora_scale * B @ A
# 其中：B = up_proj (out_features, rank)
# A = down_proj (rank, in_features)
if weights_dict["alpha"] is not None:
lora_scale = weights_dict["alpha"] / lora_down.shape[0]
elif alpha is not None:
lora_scale = alpha / lora_down.shape[0]
else:
lora_scale = 1.0
```
**配置方法**：
**Wan2.1 LoRA 配置**：
```json
{
"lora_configs": [
{
"path": "wan2.1_i2v_lora_rank64_lightx2v_4step.safetensors",
"strength": 1.0,
"alpha": null
}
]
}
```
**Wan2.2 LoRA 配置**：
由于 Wan2.2 采用双模型架构（高噪声/低噪声），需要分别为两个模型配置 LoRA：
```json
{
"lora_configs": [
{
"name": "low_noise_model",
"path": "wan2.2_i2v_A14b_low_noise_lora_rank64_lightx2v_4step.safetensors",
"strength": 1.0,
"alpha": null
},
{
"name": "high_noise_model",
"path": "wan2.2_i2v_A14b_high_noise_lora_rank64_lightx2v_4step.safetensors",
"strength": 1.0,
"alpha": null
}
]
}
```
**参数说明**：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `path` | LoRA 模型文件路径 | 必填 |
| `strength` | LoRA 强度系数，范围 [0.0, 1.0] | 1.0 |
| `alpha` | LoRA 缩放因子，`null` 时使用模型内置值 | null |
| `name` | （仅 Wan2.2）指定应用到哪个模型 | 必填 |
**优点**：
- ✅ 灵活切换不同 LoRA
- ✅ 节省存储空间
- ✅ 可动态调整 LoRA 强度
**缺点**：
- ❌ 推理时需额外加载时间
- ❌ 略微增加显存占用
---
## 📚 相关资源
### 官方仓库
- [LightX2V GitHub](https://github.com/ModelTC/LightX2V)
- [LightX2V 单文件模型仓库](https://huggingface.co/lightx2v/Wan2.1-Distill-Models)
- [Wan-AI 官方模型仓库](https://huggingface.co/Wan-AI)
### 模型下载链接
**Wan2.1 系列**
- [Wan2.1 Collection](https://huggingface.co/collections/Wan-AI/wan21-68ac4ba85372ae5a8e282a1b)
**Wan2.2 系列**
- [Wan2.2 Collection](https://huggingface.co/collections/Wan-AI/wan22-68ac4ae80a8b477e79636fc8)
**LightX2V 单文件模型**
- [Wan2.1-Distill-Models](https://huggingface.co/lightx2v/Wan2.1-Distill-Models)
- [Wan2.2-Distill-Models](https://huggingface.co/lightx2v/Wan2.2-Distill-Models)
### 文档链接
- [量化技术文档](../method_tutorials/quantization.md)
- [参数卸载文档](../method_tutorials/offload.md)
- [配置文件示例](https://github.com/ModelTC/LightX2V/tree/main/configs)
---
通过本文档，您应该能够：
✅ 理解 LightX2V 支持的所有模型格式
✅ 根据需求选择合适的模型和精度
✅ 正确下载和组织模型文件
✅ 配置启动参数并成功运行推理
✅ 解决常见的模型加载问题
如有其他问题，欢迎在 [GitHub Issues](https://github.com/ModelTC/LightX2V/issues) 中提问。
docs/ZH_CN/source/getting_started/quickstart.md 0 → 100644
View file @ a1ebc651
# LightX2V 快速入门指南
欢迎使用 LightX2V！本指南将帮助您快速搭建环境并开始使用 LightX2V 进行视频生成。
## 📋 目录
- [系统要求](#系统要求)
- [Linux 系统环境搭建](#linux-系统环境搭建)
- [Docker 环境（推荐）](#docker-环境推荐)
- [Conda 环境搭建](#conda-环境搭建)
- [Windows 系统环境搭建](#windows-系统环境搭建)
- [推理使用](#推理使用)
## 🚀 系统要求
- **操作系统**: Linux (Ubuntu 18.04+) 或 Windows 10/11
- **Python**: 3.10 或更高版本
- **GPU**: NVIDIA GPU，支持 CUDA，至少 8GB 显存
- **内存**: 建议 16GB 或更多
- **存储**: 至少 50GB 可用空间
## 🐧 Linux 系统环境搭建
### 🐳 Docker 环境（推荐）
我们强烈推荐使用 Docker 环境，这是最简单快捷的安装方式。
#### 1. 拉取镜像
访问 LightX2V 的 [Docker Hub](https://hub.docker.com/r/lightx2v/lightx2v/tags)，选择一个最新日期的 tag，比如 `25111101-cu128`：
```bash
docker pull lightx2v/lightx2v:25111101-cu128
```
我们推荐使用`cuda128`环境，以获得更快的推理速度，若需要使用`cuda124`环境，可以使用带`-cu124`后缀的镜像版本：
```bash
docker pull lightx2v/lightx2v:25101501-cu124
```
#### 2. 运行容器
```bash
docker run --gpus all -itd --ipc=host --name [容器名] -v [挂载设置] --entrypoint /bin/bash [镜像id]
```
#### 3. 中国镜像源（可选）
对于中国大陆地区，如果拉取镜像时网络不稳定，可以从阿里云上拉取：
```bash
# cuda128
docker pull registry.cn-hangzhou.aliyuncs.com/yongyang/lightx2v:25111101-cu128
# cuda124
docker pull registry.cn-hangzhou.aliyuncs.com/yongyang/lightx2v:25101501-cu124
```
### 🐍 Conda 环境搭建
如果您希望使用 Conda 自行搭建环境，请按照以下步骤操作：
#### 步骤 1: 克隆项目
```bash
# 下载项目代码
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
```
#### 步骤 2: 创建 conda 虚拟环境
```bash
# 创建并激活 conda 环境
conda create -n lightx2v python=3.11 -y
conda activate lightx2v
```
#### 步骤 3: 安装依赖及代码
```bash
pip install -v -e .
```
#### 步骤 4: 安装注意力机制算子
**选项 A: Flash Attention 2**
```bash
git clone https://github.com/Dao-AILab/flash-attention.git --recursive
cd flash-attention && python setup.py install
```
**选项 B: Flash Attention 3（用于 Hopper 架构显卡）**
```bash
cd flash-attention/hopper && python setup.py install
```
**选项 C: SageAttention 2（推荐）**
```bash
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 .
```
#### 步骤 4: 安装量化算子（可选）
量化算子用于支持模型量化功能，可以显著降低显存占用并加速推理。根据您的需求选择合适的量化算子：
**选项 A: VLLM Kernels（推荐）**
适用于多种量化方案，支持 FP8 等量化格式。
```bash
pip install vllm
```
或者从源码安装以获得最新功能：
```bash
git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -e .
```
**选项 B: SGL Kernels**
适用于 SGL 量化方案，需要 torch == 2.8.0。
```bash
pip install sgl-kernel --upgrade
```
**选项 C: Q8 Kernels**
适用于 Ada 架构显卡（如 RTX 4090、L40S 等）。
```bash
git clone https://github.com/KONAKONA666/q8_kernels.git
cd q8_kernels && git submodule init && git submodule update
python setup.py install
```
> 💡 **提示**:
> - 如果不需要使用量化功能，可以跳过此步骤
> - 量化模型可以从 [LightX2V HuggingFace](https://huggingface.co/lightx2v) 下载
> - 更多量化相关信息请参考 [量化文档](method_tutorials/quantization.html)
#### 步骤 5: 验证安装
```python
import lightx2v
print(f"LightX2V 版本: {lightx2v.__version__}")
```
## 🪟 Windows 系统环境搭建
Windows 系统仅支持 Conda 环境搭建方式，请按照以下步骤操作：
### 🐍 Conda 环境搭建
#### 步骤 1: 检查 CUDA 版本
首先确认您的 GPU 驱动和 CUDA 版本：
```cmd
nvidia-smi
```
记录输出中的 **CUDA Version** 信息，后续安装时需要保持版本一致。
#### 步骤 2: 创建 Python 环境
```cmd
# 创建新环境（推荐 Python 3.12）
conda create -n lightx2v python=3.12 -y
# 激活环境
conda activate lightx2v
```
> 💡 **提示**: 建议使用 Python 3.10 或更高版本以获得最佳兼容性。
#### 步骤 3: 安装 PyTorch 框架
**方法一：下载官方 wheel 包（推荐）**
1. 访问 [PyTorch 官方下载页面](https://download.pytorch.org/whl/torch/)
2. 选择对应版本的 wheel 包，注意匹配：
- **Python 版本**: 与您的环境一致
- **CUDA 版本**: 与您的 GPU 驱动匹配
- **平台**: 选择 Windows 版本
**示例（Python 3.12 + PyTorch 2.6 + CUDA 12.4）：**
```cmd
# 下载并安装 PyTorch
pip install torch-2.6.0+cu124-cp312-cp312-win_amd64.whl
# 安装配套包
pip install torchvision==0.21.0 torchaudio==2.6.0
```
**方法二：使用 pip 直接安装**
```cmd
# CUDA 12.4 版本示例
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
```
#### 步骤 4: 安装 Windows 版 vLLM
从 [vllm-windows releases](https://github.com/SystemPanic/vllm-windows/releases) 下载对应的 wheel 包。
**版本匹配要求：**
- Python 版本匹配
- PyTorch 版本匹配
- CUDA 版本匹配
```cmd
# 安装 vLLM（请根据实际文件名调整）
pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl
```
#### 步骤 5: 安装注意力机制算子
**选项 A: Flash Attention 2**
```cmd
pip install flash-attn==2.7.2.post1
```
**选项 B: SageAttention 2（强烈推荐）**
**下载源：**
- [Windows 专用版本 1](https://github.com/woct0rdho/SageAttention/releases)
- [Windows 专用版本 2](https://github.com/sdbds/SageAttention-for-windows/releases)
```cmd
# 安装 SageAttention（请根据实际文件名调整）
pip install sageattention-2.1.1+cu126torch2.6.0-cp312-cp312-win_amd64.whl
```
> ⚠️ **注意**: SageAttention 的 CUDA 版本可以不严格对齐，但 Python 和 PyTorch 版本必须匹配。
#### 步骤 6: 克隆项目
```cmd
# 克隆项目代码
git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
# 安装 Windows 专用依赖
pip install -r requirements_win.txt
pip install -v -e .
```
#### 步骤 7: 安装量化算子（可选）
量化算子用于支持模型量化功能，可以显著降低显存占用并加速推理。
**安装 VLLM（推荐）：**
从 [vllm-windows releases](https://github.com/SystemPanic/vllm-windows/releases) 下载对应的 wheel 包并安装。
```cmd
# 安装 vLLM（请根据实际文件名调整）
pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl
```
> 💡 **提示**:
> - 如果不需要使用量化功能，可以跳过此步骤
> - 量化模型可以从 [LightX2V HuggingFace](https://huggingface.co/lightx2v) 下载
> - 更多量化相关信息请参考 [量化文档](method_tutorials/quantization.html)
#### 步骤 8: 验证安装
```python
import lightx2v
print(f"LightX2V 版本: {lightx2v.__version__}")
```
## 🎯 推理使用
### 📥 模型准备
在开始推理之前，您需要提前下载好模型文件。我们推荐：
- **下载源**: 从 [LightX2V 官方 Hugging Face](https://huggingface.co/lightx2v/)或者其他开源模型库下载模型
- **存储位置**: 建议将模型存储在 SSD 磁盘上以获得更好的读取性能
- **可用模型**: 包括 Wan2.1-I2V、Wan2.1-T2V 等多种模型，支持不同分辨率和功能
### 📁 配置文件与脚本
推理会用到的配置文件都在[这里](https://github.com/ModelTC/LightX2V/tree/main/configs)，脚本都在[这里](https://github.com/ModelTC/LightX2V/tree/main/scripts)。
需要将下载的模型路径配置到运行脚本中。除了脚本中的输入参数，`--config_json` 指向的配置文件中也会包含一些必要参数，您可以根据需要自行修改。
### 🚀 开始推理
#### Linux 环境
```bash
# 修改脚本中的路径后运行
bash scripts/wan/run_wan_t2v.sh
```
#### Windows 环境
```cmd
# 使用 Windows 批处理脚本
scripts\win\run_wan_t2v.bat
```
#### Python脚本启动
```python
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,
)
```
## 📞 获取帮助
如果您在安装或使用过程中遇到问题，请：
1. 在 [GitHub Issues](https://github.com/ModelTC/LightX2V/issues) 中搜索相关问题
2. 提交新的 Issue 描述您的问题
---
🎉 **恭喜！** 现在您已经成功搭建了 LightX2V 环境，可以开始享受视频生成的乐趣了！
docs/ZH_CN/source/index.rst 0 → 100644
View file @ a1ebc651
欢迎了解 Lightx2v!
==================
.. figure:: ../../../assets/img_lightx2v.png
:width: 80%
:align: center
:alt: Lightx2v
:class: no-scaled-link
.. raw:: html
<div align="center" style="font-family: charter;">
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
<a href="https://deepwiki.com/ModelTC/lightx2v"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
<a href="https://lightx2v-en.readthedocs.io/en/latest"><img src="https://img.shields.io/badge/docs-English-99cc2" alt="Doc"></a>
<a href="https://lightx2v-zhcn.readthedocs.io/zh-cn/latest"><img src="https://img.shields.io/badge/文档-中文-99cc2" alt="Doc"></a>
<a href="https://hub.docker.com/r/lightx2v/lightx2v/tags"><img src="https://badgen.net/badge/icon/docker?icon=docker&label" alt="Docker"></a>
</div>
<div align="center" style="font-family: charter;">
<strong>LightX2V: 一个轻量级的视频生成推理框架</strong>
</div>
LightX2V 是一个轻量级的视频生成推理框架，集成多种先进的视频生成推理技术，统一支持 文本生成视频 (T2V)、图像生成视频 (I2V) 等多种生成任务及模型。X2V 表示将不同的输入模态（X，如文本或图像）转换（to）为视频输出（V）。
GitHub: https://github.com/ModelTC/lightx2v
HuggingFace: https://huggingface.co/lightx2v
文档列表
-------------
.. toctree::
:maxdepth: 1
:caption: 快速入门
快速入门 <getting_started/quickstart.md>
模型结构 <getting_started/model_structure.md>
基准测试 <getting_started/benchmark.md>
.. toctree::
:maxdepth: 1
:caption: 方法教程
模型量化 <method_tutorials/quantization.md>
特征缓存 <method_tutorials/cache.md>
注意力机制 <method_tutorials/attention.md>
参数卸载 <method_tutorials/offload.md>
并行推理 <method_tutorials/parallel.md>
变分辨率推理 <method_tutorials/changing_resolution.md>
步数蒸馏 <method_tutorials/step_distill.md>
自回归蒸馏 <method_tutorials/autoregressive_distill.md>
视频帧插值 <method_tutorials/video_frame_interpolation.md>
.. toctree::
:maxdepth: 1
:caption: 部署指南
低延迟场景部署 <deploy_guides/for_low_latency.md>
低资源场景部署 <deploy_guides/for_low_resource.md>
Lora模型部署 <deploy_guides/lora_deploy.md>
服务化部署 <deploy_guides/deploy_service.md>
Gradio部署 <deploy_guides/deploy_gradio.md>
ComfyUI部署 <deploy_guides/deploy_comfyui.md>
本地windows电脑部署 <deploy_guides/deploy_local_windows.md>
docs/ZH_CN/source/method_tutorials/attention.md 0 → 100644
View file @ a1ebc651
# 注意力机制
## LightX2V支持的注意力机制
| 名称 | 类型名称 | GitHub 链接 |
|--------------------|------------------|-------------|
| Flash Attention 2 | `flash_attn2` | [flash-attention v2](https://github.com/Dao-AILab/flash-attention) |
| Flash Attention 3 | `flash_attn3` | [flash-attention v3](https://github.com/Dao-AILab/flash-attention) |
| Sage Attention 2 | `sage_attn2` | [SageAttention](https://github.com/thu-ml/SageAttention) |
| Radial Attention | `radial_attn` | [Radial Attention](https://github.com/mit-han-lab/radial-attention) |
| Sparge Attention | `sparge_ckpt` | [Sparge Attention](https://github.com/thu-ml/SpargeAttn) |
---
## 配置示例
注意力机制的config文件在[这里](https://github.com/ModelTC/lightx2v/tree/main/configs/attentions)
通过指定--config_json到具体的config文件，即可以测试不同的注意力机制
比如对于radial_attn，配置如下：
```json
{
"self_attn_1_type": "radial_attn",
"cross_attn_1_type": "flash_attn3",
"cross_attn_2_type": "flash_attn3"
}
```
如需更换为其他类型，只需将对应值替换为上述表格中的类型名称即可。
tips: radial_attn因为稀疏算法原理的限制只能用在self attention
如需进一步定制注意力机制的行为，请参考各注意力库的官方文档或实现代码。
docs/ZH_CN/source/method_tutorials/autoregressive_distill.md 0 → 100644
View file @ a1ebc651
# 自回归蒸馏
自回归蒸馏是 LightX2V 中的一个技术探索，通过训练蒸馏模型将推理步数从原始的 40-50 步减少到 **8 步**，在实现推理加速的同时能够通过 KV Cache 技术生成无限长视频。
> ⚠️ 警告：目前自回归蒸馏的效果一般，加速效果也没有达到预期，但是可以作为一个长期的研究项目。目前 LightX2V 仅支持 T2V 的自回归模型。
## 🔍 技术原理
自回归蒸馏通过 [CausVid](https://github.com/tianweiy/CausVid) 技术实现。CausVid 针对 1.3B 的自回归模型进行步数蒸馏、CFG蒸馏。LightX2V 在其基础上，进行了一系列扩展：
1. **更大的模型**：支持 14B 模型的自回归蒸馏训练；
2. **更完整的数据处理流程**：生成 50,000 个提示词-视频对的训练数据集；
具体实现可参考 [CausVid-Plus](https://github.com/GoatWu/CausVid-Plus)。
## 🛠️ 配置文件说明
### 配置文件
在 [configs/causvid/](https://github.com/ModelTC/lightx2v/tree/main/configs/causvid) 目录下提供了配置选项：
| 配置文件 | 模型地址 |
|----------|------------|
| [wan_t2v_causvid.json](https://github.com/ModelTC/lightx2v/blob/main/configs/causvid/wan_t2v_causvid.json) | https://huggingface.co/lightx2v/Wan2.1-T2V-14B-CausVid |
### 关键配置参数
```json
{
"enable_cfg": false, // 关闭CFG以提升速度
"num_fragments": 3, // 一次生成视频的段数，每段5s
"num_frames": 21, // 每段视频的帧数，谨慎修改！
"num_frame_per_block": 3, // 每个自回归块的帧数，谨慎修改！
"num_blocks": 7, // 每段视频的自回归块数，谨慎修改！
"frame_seq_length": 1560, // 每帧的编码长度，谨慎修改！
"denoising_step_list": [ // 去噪时间步列表
999, 934, 862, 756, 603, 410, 250, 140, 74
]
}
```
## 📜 使用方法
### 模型准备
将下载好的模型（`causal_model.pt` 或者 `causal_model.safetensors`）放到 Wan 模型根目录的 `causvid_models/` 文件夹下即可
- 对于 T2V：`Wan2.1-T2V-14B/causvid_models/`
### 推理脚本
```bash
bash scripts/wan/run_wan_t2v_causvid.sh
```
docs/ZH_CN/source/method_tutorials/cache.md 0 → 100644
View file @ a1ebc651
# 特征缓存
由于要展示一些视频的播放效果，你可以在这个[🔗 页面](https://github.com/ModelTC/LightX2V/blob/main/docs/ZH_CN/source/method_tutorials/cache_source.md)获得更好的展示效果以及相对应的文档内容。
docs/ZH_CN/source/method_tutorials/cache_source.md 0 → 100644
View file @ a1ebc651
# 特征缓存
## 缓存加速算法
- 在扩散模型的推理过程中，缓存复用是一种重要的加速算法。
- 其核心思想是在部分时间步跳过冗余计算，通过复用历史缓存结果提升推理效率。
- 算法的关键在于如何决策在哪些时间步进行缓存复用，通常基于模型状态变化或误差阈值动态判断。
- 在推理过程中，需要缓存如中间特征、残差、注意力输出等关键内容。当进入可复用时间步时，直接利用已缓存的内容，通过泰勒展开等近似方法重构当前输出，从而减少重复计算，实现高效推理。
### TeaCache
`TeaCache`的核心思想是通过对相邻时间步输入的**相对L1**距离进行累加，当累计距离达到设定阈值时，判定当前时间步不使用缓存复用；相反，当累计距离未达到设定阈值时则使用缓存复用加速推理过程。
- 具体来说，算法在每一步推理时计算当前输入与上一步输入的相对L1距离，并将其累加。
- 当累计距离未超过阈值，说明模型状态变化不明显，则直接复用最近一次缓存的内容，跳过部分冗余计算。这样可以显著减少模型的前向计算次数，提高推理速度。
实际效果上，TeaCache 在保证生成质量的前提下，实现了明显的加速。在单卡H200上，加速前后的用时与视频对比如下：
<table>
<tr>
<td align="center">
加速前：58s
</td>
<td align="center">
加速后：17.9s
</td>
</tr>
<tr>
<td align="center">
<video src="https://github.com/user-attachments/assets/1781df9b-04df-4586-b22f-5d15f8e1bff6" width="100%"></video>
</td>
<td align="center">
<video src="https://github.com/user-attachments/assets/e93f91eb-3825-4866-90c2-351176263a2f" width="100%"></video>
</td>
</tr>
</table>
- 加速比为：**3.24**
- config：[wan_t2v_1_3b_tea_480p.json](https://github.com/ModelTC/lightx2v/tree/main/configs/caching/teacache/wan_t2v_1_3b_tea_480p.json)
- 参考论文：[https://arxiv.org/abs/2411.19108](https://arxiv.org/abs/2411.19108)
### TaylorSeer Cache
`TaylorSeer Cache`的核心在于利用泰勒公式对缓存内容进行再次计算，作为缓存复用时间步的残差补偿。
- 具体做法是在缓存复用的时间步，不仅简单地复用历史缓存，还通过泰勒展开对当前输出进行近似重构。这样可以在减少计算量的同时，进一步提升输出的准确性。
- 泰勒展开能够有效捕捉模型状态的微小变化，使得缓存复用带来的误差得到补偿，从而在加速的同时保证生成质量。
`TaylorSeer Cache`适用于对输出精度要求较高的场景，能够在缓存复用的基础上进一步提升模型推理的表现。
<table>
<tr>
<td align="center">
加速前：57.7s
</td>
<td align="center">
加速后：41.3s
</td>
</tr>
<tr>
<td align="center">
<video src="https://github.com/user-attachments/assets/2d04005c-853b-4752-884b-29f8ea5717d2" width="100%"></video>
</td>
<td align="center">
<video src="https://github.com/user-attachments/assets/270e3624-c904-468c-813e-0c65daf1594d" width="100%"></video>
</td>
</tr>
</table>
- 加速比为：**1.39**
- config：[wan_t2v_taylorseer](https://github.com/ModelTC/lightx2v/tree/main/configs/caching/taylorseer/wan_t2v_taylorseer.json)
- 参考论文：[https://arxiv.org/abs/2503.06923](https://arxiv.org/abs/2503.06923)
### AdaCache
`AdaCache`的核心思想是根据指定block块中的部分缓存内容，动态调整缓存复用的步长。
- 算法会分析相邻两个时间步在特定 block 内的特征差异，根据差异大小自适应地决定下一个缓存复用的时间步间隔。
- 当模型状态变化较小时，步长自动加大，减少缓存更新频率；当状态变化较大时，步长缩小，保证输出质量。
这样可以根据实际推理过程中的动态变化，灵活调整缓存策略，实现更高效的加速和更优的生成效果。AdaCache 适合对推理速度和生成质量都有较高要求的应用场景。
<table>
<tr>
<td align="center">
加速前：227s
</td>
<td align="center">
加速后：83s
</td>
</tr>
<tr>
<td align="center">
<video src="https://github.com/user-attachments/assets/33b2206d-17e6-4433-bed7-bfa890f9fa7d" width="100%"></video>
</td>
<td align="center">
<video src="https://github.com/user-attachments/assets/084dbe3d-6ff3-4afc-9a7c-453ec53b3672" width="100%"></video>
</td>
</tr>
</table>
- 加速比为：**2.73**
- config：[wan_i2v_ada](https://github.com/ModelTC/lightx2v/tree/main/configs/caching/adacache/wan_i2v_ada.json)
- 参考论文：[https://arxiv.org/abs/2411.02397](https://arxiv.org/abs/2411.02397)
### CustomCache
`CustomCache`综合了`TeaCache`和`TaylorSeer Cache`的优势。
- 它结合了`TeaCache`在缓存决策上的实时性和合理性，通过动态阈值判断何时进行缓存复用.
- 同时利用`TaylorSeer`的泰勒展开方法对已缓存内容进行利用。
这样不仅能够高效地决定缓存复用的时机，还能最大程度地利用缓存内容，提升输出的准确性和生成质量。实际测试表明，`CustomCache`在多个内容生成任务上，生成的视频质量优于单独使用`TeaCache、TaylorSeer Cache`或`AdaCache`的方案，是目前综合性能最优的缓存加速算法之一。
<table>
<tr>
<td align="center">
加速前：57.9s
</td>
<td align="center">
加速后：16.6s
</td>
</tr>
<tr>
<td align="center">
<video src="https://github.com/user-attachments/assets/304ff1e8-ad1c-4013-bcf1-959ac140f67f" width="100%"></video>
</td>
<td align="center">
<video src="https://github.com/user-attachments/assets/d3fb474a-79af-4f33-b965-23d402d3cf16" width="100%"></video>
</td>
</tr>
</table>
- 加速比为：**3.49**
- config：[wan_t2v_custom_1_3b](https://github.com/ModelTC/lightx2v/tree/main/configs/caching/custom/wan_t2v_custom_1_3b.json)
## 使用方式
特征缓存的config文件在[这里](https://github.com/ModelTC/lightx2v/tree/main/configs/caching)
通过指定--config_json到具体的config文件，即可以测试不同的cache算法
[这里](https://github.com/ModelTC/lightx2v/tree/main/scripts/cache)有一些运行脚本供使用。
docs/ZH_CN/source/method_tutorials/changing_resolution.md 0 → 100644
View file @ a1ebc651
# 变分辨率推理
## 概述
变分辨率推理是一种优化去噪过程的技术策略，通过在不同的去噪阶段采用不同的分辨率来提升计算效率并保持生成质量。该方法的核心思想是：在去噪过程的前期使用较低分辨率进行粗略去噪，在后期切换到正常分辨率进行精细化处理。
## 技术原理
### 分阶段去噪策略
变分辨率推理基于以下观察：
- **前期去噪**：主要处理粗糙的噪声和整体结构，不需要过多的细节信息
- **后期去噪**：专注于细节优化和高频信息恢复，需要完整的分辨率信息
### 分辨率切换机制
1. **低分辨率阶段**（前期）
- 将输入降采样到较低分辨率（如原尺寸的0.75）
- 执行初始的去噪步骤
- 快速移除大部分噪声，建立基本结构
2. **正常分辨率阶段**（后期）
- 将第一步的去噪结果上采样回原始分辨率
- 继续执行剩余的去噪步骤
- 恢复细节信息，完成精细化处理
### U型分辨率策略
如果在刚开始的去噪步，降低分辨率，可能会导致最后的生成的视频和正常推理的生成的视频，整体差异偏大。因此可以采用U型的分辨率策略，即最一开始保持几步的原始分辨率，再降低分辨率推理。
## 使用方式
变分辨率推理的config文件在[这里](https://github.com/ModelTC/LightX2V/tree/main/configs/changing_resolution)
通过指定--config_json到具体的config文件，即可以测试变分辨率推理。
可以参考[这里](https://github.com/ModelTC/LightX2V/blob/main/scripts/changing_resolution)的脚本运行。
### 举例1：
```
{
"infer_steps": 50,
"changing_resolution": true,
"resolution_rate": [0.75],
"changing_resolution_steps": [25]
}
```
表示总步数为50，1到25步的分辨率为0.75倍原始分辨率，26到最后一步的分辨率为原始分辨率。
### 举例2：
```
{
"infer_steps": 50,
"changing_resolution": true,
"resolution_rate": [1.0, 0.75],
"changing_resolution_steps": [10, 35]
}
```
表示总步数为50，1到10步的分辨率为原始分辨率，11到35步的分辨率为0.75倍原始分辨率，36到最后一步的分辨率为原始分辨率。
通常来说，假设`changing_resolution_steps`为[A, B, C]，去噪的起始步为1，总步数为X，则推理会被分成4个部分。
分别是，(0, A], (A, B]. (B, C], (C, X]，每个部分是左开右闭集合。
docs/ZH_CN/source/method_tutorials/offload.md 0 → 100644
View file @ a1ebc651
# 参数卸载
## 📖 概述
Lightx2v 实现了先进的参数卸载机制，专为在有限硬件资源下处理大型模型推理而设计。该系统通过智能管理不同内存层次中的模型权重，提供了优秀的速度-内存平衡。
**核心特性：**
- **分block/phase卸载**：高效地以block/phase为单位管理模型权重，实现最优内存使用
- **Block**：Transformer模型的基本计算单元，包含完整的Transformer层（自注意力、交叉注意力、前馈网络等），是较大的内存管理单位
- **Phase**：Block内部的更细粒度计算阶段，包含单个计算组件（如自注意力、交叉注意力、前馈网络等），提供更精细的内存控制
- **多级存储支持**：GPU → CPU → 磁盘层次结构，配合智能缓存
- **异步操作**：使用 CUDA 流实现计算和数据传输的重叠
- **磁盘/NVMe 序列化**：当内存不足时支持二级存储
## 🎯 卸载策略
### 策略一：GPU-CPU 分block/phase卸载
**适用场景**：GPU 显存不足但系统内存充足
**工作原理**：在 GPU 和 CPU 内存之间以block或phase为单位管理模型权重，利用 CUDA 流实现计算和数据传输的重叠。Block包含完整的Transformer层，而Phase则是Block内部的单个计算组件。
<div align="center">
<img alt="GPU-CPU block/phase卸载流程图" src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/figs/offload/fig1_zh.png" width="75%">
</div>
<div align="center">
<img alt="Swap操作" src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/figs/offload/fig2_zh.png" width="75%">
</div>
<div align="center">
<img alt="Swap思想" src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/figs/offload/fig3_zh.png" width="75%">
</div>
**Block vs Phase 说明**：
- **Block粒度**：较大的内存管理单位，包含完整的Transformer层（自注意力、交叉注意力、前馈网络等），适合内存充足的情况，减少管理开销
- **Phase粒度**：更细粒度的内存管理，包含单个计算组件（如自注意力、交叉注意力、前馈网络等），适合内存受限的情况，提供更灵活的内存控制
**关键特性：**
- **异步传输**：使用三个不同优先级的CUDA流实现计算和传输的并行
- 计算流(priority=-1)：高优先级，负责当前计算
- GPU加载流(priority=0)：中优先级，负责从CPU到GPU的预取
- CPU加载流(priority=0)：中优先级，负责从GPU到CPU的卸载
- **预取机制**：提前将下一个block/phase加载到 GPU
- **智能缓存**：在 CPU 内存中维护权重缓存
- **流同步**：确保数据传输和计算的正确性
- **Swap操作**：计算完成后轮换block/phase位置，实现连续计算
### 策略二：磁盘-CPU-GPU 分block/phase卸载（延迟加载）
**适用场景**：GPU 显存和系统内存都不足
**工作原理**：在策略一的基础上引入磁盘存储，实现三级存储层次（磁盘 → CPU → GPU）。CPU继续作为缓存池，但大小可配置，适用于CPU内存受限的设备。
<div align="center">
<img alt="磁盘-CPU-GPU 分block/phase卸载工作流程" src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/figs/offload/fig4_zh.png" width="75%">
</div>
<div align="center">
<img alt="工作步骤" src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/figs/offload/fig5_zh.png" width="75%">
</div>
**关键特性：**
- **延迟加载**：模型权重按需从磁盘加载，避免一次性加载全部模型
- **智能缓存**：CPU内存缓冲区使用FIFO策略管理，可配置大小
- **多线程预取**：使用多个磁盘工作线程并行加载
- **异步传输**：使用CUDA流实现计算和数据传输的重叠
- **Swap轮换**：通过位置轮换实现连续计算，避免重复加载/卸载
**工作步骤**：
- **磁盘存储**：模型权重按block存储在SSD/NVMe上，每个block一个.safetensors文件
- **任务调度**：当需要某个block/phase时，优先级任务队列分配磁盘工作线程
- **异步加载**：多个磁盘线程并行从磁盘读取权重文件到CPU内存缓冲区
- **智能缓存**：CPU内存缓冲区使用FIFO策略管理缓存，可配置大小
- **缓存命中**：如果权重已在缓存中，直接传输到GPU，无需磁盘读取
- **预取传输**：缓存中的权重异步传输到GPU内存（使用GPU加载流）
- **计算执行**：GPU上的权重进行计算（使用计算流），同时后台继续预取下一个block/phase
- **Swap轮换**：计算完成后轮换block/phase位置，实现连续计算
- **内存管理**：当CPU缓存满时，自动淘汰最早使用的权重block/phase
## ⚙️ 配置参数
### GPU-CPU 卸载配置
```python
config = {
"cpu_offload": True,
"offload_ratio": 1.0, # 卸载比例（0.0-1.0）
"offload_granularity": "block", # 卸载粒度："block"或"phase"
"lazy_load": False, # 禁用延迟加载
}
```
### 磁盘-CPU-GPU 卸载配置
```python
config = {
"cpu_offload": True,
"lazy_load": True, # 启用延迟加载
"offload_ratio": 1.0, # 卸载比例
"offload_granularity": "phase", # 推荐使用phase粒度
"num_disk_workers": 2, # 磁盘工作线程数
"offload_to_disk": True, # 启用磁盘卸载
}
```
**智能缓存关键参数：**
- `max_memory`：控制CPU缓存大小，影响缓存命中率和内存使用
- `num_disk_workers`：控制磁盘加载线程数，影响预取速度
- `offload_granularity`：控制缓存粒度（block或phase），影响缓存效率
- `"block"`：以完整的Transformer层为单位进行缓存管理
- `"phase"`：以单个计算组件为单位进行缓存管理
**非 DIT 模型组件（T5、CLIP、VAE）的卸载配置：**
这些组件的卸载行为遵循以下规则：
- **默认行为**：如果没有单独指定，T5、CLIP、VAE 会跟随 `cpu_offload` 的设置
- **独立配置**：可以为每个组件单独设置卸载策略，实现精细控制
**配置示例**：
```json
{
"cpu_offload": true, // DIT 模型卸载开关
"t5_cpu_offload": false, // T5 编码器独立设置
"clip_cpu_offload": false, // CLIP 编码器独立设置
"vae_cpu_offload": false // VAE 编码器独立设置
}
```
在显存受限的设备上，建议采用渐进式卸载策略：
1. **第一步**：仅开启 `cpu_offload`，关闭 `t5_cpu_offload`、`clip_cpu_offload`、`vae_cpu_offload`
2. **第二步**：如果显存仍不足，逐步开启 T5、CLIP、VAE 的 CPU 卸载
3. **第三步**：如果显存仍然不够，考虑使用量化 + CPU 卸载或启用 `lazy_load`
**实践经验**：
- **RTX 4090 24GB + 14B 模型**：通常只需开启 `cpu_offload`，其他组件卸载需要手动设为 `false`，同时使用 FP8 量化版本
- **更小显存的 GPU**：需要组合使用量化、CPU 卸载和延迟加载
- **量化方案**：建议参考[量化技术文档](../method_tutorials/quantization.md)选择合适的量化策略
**配置文件参考**：
- **Wan2.1 系列模型**：参考 [offload 配置文件](https://github.com/ModelTC/lightx2v/tree/main/configs/offload)
- **Wan2.2 系列模型**：参考 [wan22 配置文件](https://github.com/ModelTC/lightx2v/tree/main/configs/wan22) 中以 `4090` 结尾的配置文件
## 🎯 使用建议
- 🔄 GPU-CPU分block/phase卸载：适合GPU显存不足(RTX 3090/4090 24G)但系统内存(>64/128G)充足
- 💾 磁盘-CPU-GPU分block/phase卸载：适合GPU显存(RTX 3060/4090 8G)和系统内存(16/32G)都不足
- 🚫 无Offload：适合高端硬件配置，追求最佳性能
## 🔍 故障排除
### 常见问题及解决方案
1. **磁盘I/O瓶颈**
- 解决方案：使用NVMe SSD，增加num_disk_workers
2. **内存缓冲区溢出**
- 解决方案：增加max_memory或减少num_disk_workers
3. **加载超时**
- 解决方案：检查磁盘性能，优化文件系统
**注意**：本卸载机制专为Lightx2v设计，充分利用了现代硬件的异步计算能力，能够显著降低大模型推理的硬件门槛。
docs/ZH_CN/source/method_tutorials/parallel.md 0 → 100644
View file @ a1ebc651
# 并行推理
LightX2V 支持分布式并行推理，能够利用多个 GPU 进行推理。DiT部分支持两种并行注意力机制：**Ulysses** 和 **Ring**，同时还支持 **Cfg 并行推理**。并行推理，显著降低推理耗时和减轻每个GPU的显存开销。
## DiT 并行配置
### 1. Ulysses 并行
**配置方式：**
```json
"parallel": {
"seq_p_size": 4,
"seq_p_attn_type": "ulysses"
}
```
### 2. Ring 并行
**配置方式：**
```json
"parallel": {
"seq_p_size": 4,
"seq_p_attn_type": "ring"
}
```
## Cfg 并行配置
**配置方式：**
```json
"parallel": {
"cfg_p_size": 2
}
```
## 混合并行配置
**配置方式：**
```json
"parallel": {
"seq_p_size": 4,
"seq_p_attn_type": "ulysses",
"cfg_p_size": 2
}
```
## 使用方式
并行推理的config文件在[这里](https://github.com/ModelTC/lightx2v/tree/main/configs/dist_infer)
通过指定--config_json到具体的config文件，即可以测试并行推理
[这里](https://github.com/ModelTC/lightx2v/tree/main/scripts/dist_infer)有一些运行脚本供使用。
docs/ZH_CN/source/method_tutorials/quantization.md 0 → 100644
View file @ a1ebc651
# 模型量化技术
## 📖 概述
LightX2V 支持对 DIT、T5 和 CLIP 模型进行量化推理，通过降低模型精度来减少显存占用并提升推理速度。
---
## 🔧 量化模式
| 量化模式 | 权重量化 | 激活量化 | 计算内核 | 适用硬件 |
|--------------|----------|----------|----------|----------|
| `fp8-vllm` | FP8 通道对称 | FP8 通道动态对称 | [VLLM](https://github.com/vllm-project/vllm) | H100/H200/H800, RTX 40系等 |
| `int8-vllm` | INT8 通道对称 | INT8 通道动态对称 | [VLLM](https://github.com/vllm-project/vllm) | A100/A800, RTX 30/40系等 |
| `fp8-sgl` | FP8 通道对称 | FP8 通道动态对称 | [SGL](https://github.com/sgl-project/sglang/tree/main/sgl-kernel) | H100/H200/H800, RTX 40系等 |
| `int8-sgl` | INT8 通道对称 | INT8 通道动态对称 | [SGL](https://github.com/sgl-project/sglang/tree/main/sgl-kernel) | A100/A800, RTX 30/40系等 |
| `fp8-q8f` | FP8 通道对称 | FP8 通道动态对称 | [Q8-Kernels](https://github.com/KONAKONA666/q8_kernels) | RTX 40系, L40S等 |
| `int8-q8f` | INT8 通道对称 | INT8 通道动态对称 | [Q8-Kernels](https://github.com/KONAKONA666/q8_kernels) | RTX 40系, L40S等 |
| `int8-torchao` | INT8 通道对称 | INT8 通道动态对称 | [TorchAO](https://github.com/pytorch/ao) | A100/A800, RTX 30/40系等 |
| `int4-g128-marlin` | INT4 分组对称 | FP16 | [Marlin](https://github.com/IST-DASLab/marlin) | H200/H800/A100/A800, RTX 30/40系等 |
| `fp8-b128-deepgemm` | FP8 分块对称 | FP8 分组对称 | [DeepGemm](https://github.com/deepseek-ai/DeepGEMM) | H100/H200/H800, RTX 40系等|
---
## 🔧 量化模型获取
### 方式一：下载预量化模型
从 LightX2V 模型仓库下载预量化的模型：
**DIT 模型**
从 [Wan2.1-Distill-Models](https://huggingface.co/lightx2v/Wan2.1-Distill-Models) 下载预量化的 DIT 模型：
```bash
# 下载 DIT FP8 量化模型
huggingface-cli download lightx2v/Wan2.1-Distill-Models \
--local-dir ./models \
--include "wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step.safetensors"
```
**Encoder 模型**
从 [Encoders-LightX2V](https://huggingface.co/lightx2v/Encoders-Lightx2v) 下载预量化的 T5 和 CLIP 模型：
```bash
# 下载 T5 FP8 量化模型
huggingface-cli download lightx2v/Encoders-Lightx2v \
--local-dir ./models \
--include "models_t5_umt5-xxl-enc-fp8.pth"
# 下载 CLIP FP8 量化模型
huggingface-cli download lightx2v/Encoders-Lightx2v \
--local-dir ./models \
--include "models_clip_open-clip-xlm-roberta-large-vit-huge-14-fp8.pth"
```
### 方式二：自行量化模型
详细量化工具使用方法请参考：[模型转换文档](https://github.com/ModelTC/lightx2v/tree/main/tools/convert/readme_zh.md)
---
## 🚀 量化模型使用
### DIT 模型量化
#### 支持的量化模式
DIT 量化模式（`dit_quant_scheme`）支持：`fp8-vllm`、`int8-vllm`、`fp8-sgl`、`int8-sgl`、`fp8-q8f`、`int8-q8f`、`int8-torchao`、`int4-g128-marlin`、`fp8-b128-deepgemm`
#### 配置示例
```json
{
"dit_quantized": true,
"dit_quant_scheme": "fp8-sgl",
"dit_quantized_ckpt": "/path/to/dit_quantized_model" // 可选
}
```
> 💡 **提示**：当运行脚本的 `model_path` 中只有一个 DIT 模型时，`dit_quantized_ckpt` 可以不用单独指定。
### T5 模型量化
#### 支持的量化模式
T5 量化模式（`t5_quant_scheme`）支持：`int8-vllm`、`fp8-sgl`、`int8-q8f`、`fp8-q8f`、`int8-torchao`
#### 配置示例
```json
{
"t5_quantized": true,
"t5_quant_scheme": "fp8-sgl",
"t5_quantized_ckpt": "/path/to/t5_quantized_model" // 可选
}
```
> 💡 **提示**：当运行脚本指定的 `model_path` 中存在 T5 量化模型（如 `models_t5_umt5-xxl-enc-fp8.pth` 或 `models_t5_umt5-xxl-enc-int8.pth`）时，`t5_quantized_ckpt` 可以不用单独指定。
### CLIP 模型量化
#### 支持的量化模式
CLIP 量化模式（`clip_quant_scheme`）支持：`int8-vllm`、`fp8-sgl`、`int8-q8f`、`fp8-q8f`、`int8-torchao`
#### 配置示例
```json
{
"clip_quantized": true,
"clip_quant_scheme": "fp8-sgl",
"clip_quantized_ckpt": "/path/to/clip_quantized_model" // 可选
}
```
> 💡 **提示**：当运行脚本指定的 `model_path` 中存在 CLIP 量化模型（如 `models_clip_open-clip-xlm-roberta-large-vit-huge-14-fp8.pth` 或 `models_clip_open-clip-xlm-roberta-large-vit-huge-14-int8.pth`）时，`clip_quantized_ckpt` 可以不用单独指定。
### 性能优化策略
如果显存不够，可以结合参数卸载来进一步减少显存占用，参考[参数卸载文档](../method_tutorials/offload.md)：
> - **Wan2.1 配置**：参考 [offload 配置文件](https://github.com/ModelTC/LightX2V/tree/main/configs/offload)
> - **Wan2.2 配置**：参考 [wan22 配置文件](https://github.com/ModelTC/LightX2V/tree/main/configs/wan22) 中以 `4090` 结尾的配置
---
## 📚 相关资源
### 配置文件示例
- [INT8 量化配置](https://github.com/ModelTC/LightX2V/blob/main/configs/quantization/wan_i2v.json)
- [Q8F 量化配置](https://github.com/ModelTC/LightX2V/blob/main/configs/quantization/wan_i2v_q8f.json)
- [TorchAO 量化配置](https://github.com/ModelTC/LightX2V/blob/main/configs/quantization/wan_i2v_torchao.json)
### 运行脚本
- [量化推理脚本](https://github.com/ModelTC/LightX2V/tree/main/scripts/quantization)
### 工具文档
- [量化工具文档](https://github.com/ModelTC/lightx2v/tree/main/tools/convert/readme_zh.md)
- [LightCompress 量化文档](https://github.com/ModelTC/llmc/blob/main/docs/zh_cn/source/backend/lightx2v.md)
### 模型仓库
- [Wan2.1-LightX2V 量化模型](https://huggingface.co/lightx2v/Wan2.1-Distill-Models)
- [Wan2.2-LightX2V 量化模型](https://huggingface.co/lightx2v/Wan2.2-Distill-Models)
- [Encoders 量化模型](https://huggingface.co/lightx2v/Encoders-Lightx2v)
---
通过本文档，您应该能够：
✅ 理解 LightX2V 支持的量化方案
✅ 根据硬件选择合适的量化策略
✅ 正确配置量化参数
✅ 获取和使用量化模型
✅ 优化推理性能和显存使用
如有其他问题，欢迎在 [GitHub Issues](https://github.com/ModelTC/LightX2V/issues) 中提问。
docs/ZH_CN/source/method_tutorials/step_distill.md 0 → 100644
View file @ a1ebc651
# 步数蒸馏
步数蒸馏是 LightX2V 中的一项重要优化技术，通过训练蒸馏模型将推理步数从原始的 40-50 步大幅减少到 **4 步**，在保持视频质量的同时显著提升推理速度。LightX2V 在实现步数蒸馏的同时也加入了 CFG 蒸馏，进一步提升推理速度。
## 🔍 技术原理
### DMD 蒸馏
步数蒸馏的核心技术是 [DMD 蒸馏](https://arxiv.org/abs/2311.18828)。DMD 蒸馏的框架如下图所示：
<div align="center">
<img alt="DMD 蒸馏框架" src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/figs/step_distill/fig_01.png" width="75%">
</div>
DMD蒸馏的核心思想是最小化蒸馏模型与原始模型输出分布的 KL 散度：
$$
\begin{aligned}
D_{KL}\left(p_{\text{fake}} \; \| \; p_{\text{real}} \right) &= \mathbb{E}{x\sim p\text{fake}}\left(\log\left(\frac{p_\text{fake}(x)}{p_\text{real}(x)}\right)\right)\\
&= \mathbb{E}{\substack{
z \sim \mathcal{N}(0; \mathbf{I}) \\
x = G_\theta(z)
}}-\big(\log~p_\text{real}(x) - \log~p_\text{fake}(x)\big).
\end{aligned}
$$
由于直接计算概率密度几乎是不可能的，因此 DMD 蒸馏改为计算这个 KL 散度的梯度：
$$
\begin{aligned}
\nabla_\theta D_{KL}
&= \mathbb{E}{\substack{
z \sim \mathcal{N}(0; \mathbf{I}) \\
x = G_\theta(z)
} } \Big[-
\big(
s_\text{real}(x) - s_\text{fake}(x)\big)
\hspace{.5mm} \frac{dG}{d\theta}
\Big],
\end{aligned}
$$
其中 $s_\text{real}(x) =\nabla_{x} \text{log}~p_\text{real}(x)$ 和 $s_\text{fake}(x) =\nabla_{x} \text{log}~p_\text{fake}(x)$ 为得分函数。得分函数可以由模型进行计算。因此，DMD 蒸馏一共维护三个模型：
- `real_score`，计算真实分布的得分；由于真实分布是固定的，因此 DMD 蒸馏使用固定权重的原始模型作为其得分函数；
- `fake_score`，计算伪分布的得分；由于伪分布是不断更新的，因此 DMD 蒸馏使用原始模型对其初始化，并对其进行微调以学习生成器的输出分布；
- `generator`，学生模型，通过计算 `real_score` 与 `fake_score` KL 散度的梯度指导其优化方向。
> 参考文献：
> 1. [DMD (One-step Diffusion with Distribution Matching Distillation)](https://arxiv.org/abs/2311.18828)
> 2. [DMD2 (Improved Distribution Matching Distillation for Fast Image Synthesis)](https://arxiv.org/abs/2405.14867)
### Self-Forcing
DMD 蒸馏技术是针对图像生成的。Lightx2v 中的步数蒸馏基于 [Self-Forcing](https://github.com/guandeh17/Self-Forcing) 技术实现。Self-Forcing 的整体实现与 DMD 类似，但是仿照 DMD2，去掉了它的回归损失，而是使用了 ODE 初始化。此外，Self-Forcing 针对视频生成任务加入了一个重要优化：
目前基于 DMD 蒸馏的方法难以一步生成视频。Self-Forcing 每次选择一个时间步进行优化，generator 仅仅在这一步计算梯度。这种方法使得 Self-Forcing 的训练速度显著提升，并且提升了中间时间步的去噪质量，其效果亦有所提升。
> 参考文献：
> 1. [Self-Forcing (Self Forcing: Bridging the Train-Test Gap in Autoregressive Video Diffusion)](https://arxiv.org/abs/2506.08009)
### Lightx2v
Self-Forcing 针对 1.3B 的自回归模型进行步数蒸馏、CFG蒸馏。LightX2V 在其基础上，进行了一系列扩展：
1. **更大的模型**：支持 14B 模型的步数蒸馏训练；
2. **更多的模型**：支持标准的双向模型，以及 I2V 模型的步数蒸馏训练；
3. **更好的效果**：Lightx2v 使用了约 50,000 条数据的高质量 prompt 进行训练；
具体实现可参考 [Self-Forcing-Plus](https://github.com/GoatWu/Self-Forcing-Plus)。
## 🎯 技术特性
- **推理加速**：推理步数从 40-50 步减少到 4 步且无需 CFG，速度提升约 **20-24x**
- **质量保持**：通过蒸馏技术保持原有的视频生成质量
- **兼容性强**：支持 T2V 和 I2V 任务
- **使用灵活**：支持加载完整步数蒸馏模型，或者在原生模型的基础上加载步数蒸馏LoRA；支持与 int8/fp8 模型量化相兼容
## 🛠️ 配置文件说明
### 基础配置文件
在 [configs/distill/](https://github.com/ModelTC/lightx2v/tree/main/configs/distill) 目录下提供了多种配置选项：
| 配置文件 | 用途 | 模型地址 |
|----------|------|------------|
| [wan_t2v_distill_4step_cfg.json](https://github.com/ModelTC/lightx2v/blob/main/configs/distill/wan_t2v_distill_4step_cfg.json) | 加载 T2V 4步蒸馏完整模型 | [hugging-face](https://huggingface.co/lightx2v/Wan2.1-T2V-14B-StepDistill-CfgDistill-Lightx2v/blob/main/distill_models/distill_model.safetensors) |
| [wan_i2v_distill_4step_cfg.json](https://github.com/ModelTC/lightx2v/blob/main/configs/distill/wan_i2v_distill_4step_cfg.json) | 加载 I2V 4步蒸馏完整模型 | [hugging-face](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v/blob/main/distill_models/distill_model.safetensors) |
| [wan_t2v_distill_4step_cfg_lora.json](https://github.com/ModelTC/lightx2v/blob/main/configs/distill/wan_t2v_distill_4step_cfg_lora.json) | 加载 Wan-T2V 模型和步数蒸馏 LoRA | [hugging-face](https://huggingface.co/lightx2v/Wan2.1-T2V-14B-StepDistill-CfgDistill-Lightx2v/blob/main/loras/Wan21_T2V_14B_lightx2v_cfg_step_distill_lora_rank64.safetensors) |
| [wan_i2v_distill_4step_cfg_lora.json](https://github.com/ModelTC/lightx2v/blob/main/configs/distill/wan_i2v_distill_4step_cfg_lora.json) | 加载 Wan-I2V 模型和步数蒸馏 LoRA | [hugging-face](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v/blob/main/loras/Wan21_I2V_14B_lightx2v_cfg_step_distill_lora_rank64.safetensors) |
### 关键配置参数
- 由于 DMD 蒸馏仅训练几个固定的时间步，因此我们推荐使用 `LCM Scheduler` 进行推理。[WanStepDistillScheduler](https://github.com/ModelTC/LightX2V/blob/main/lightx2v/models/schedulers/wan/step_distill/scheduler.py) 中，已经固定使用 `LCM Scheduler`，无需用户进行配置。
- `infer_steps`, `denoising_step_list` 和 `sample_shift` 设置为与训练时相匹配的参数，一般不建议用户修改。
- `enable_cfg` 一定设置为 `false`（等价于设置 `sample_guide_scale = 1`），否则可能出现视频完全模糊的现象。
- `lora_configs` 支持融合不同强度的多个 lora。当 `lora_configs` 不为空时，默认加载原始的 `Wan2.1` 模型。因此使用 `lora_config` 并且想要使用步数蒸馏时，请设置步数蒸馏lora的路径与强度。
```json
{
"infer_steps": 4, // 推理步数
"denoising_step_list": [1000, 750, 500, 250], // 去噪时间步列表
"sample_shift": 5, // 调度器 timestep shift
"enable_cfg": false, // 关闭CFG以提升速度
"lora_configs": [ // LoRA权重路径（可选）
{
"path": "path/to/distill_lora.safetensors",
"strength": 1.0
}
]
}
```
## 📜 使用方法
### 模型准备
**完整模型：**
将下载好的模型（`distill_model.pt` 或者 `distill_model.safetensors`）放到 Wan 模型根目录的 `distill_models/` 文件夹下即可
- 对于 T2V：`Wan2.1-T2V-14B/distill_models/`
- 对于 I2V-480P：`Wan2.1-I2V-14B-480P/distill_models/`
**LoRA：**
1. 将下载好的 LoRA 放到任意位置
2. 修改配置文件中的 `lora_path` 参数为 LoRA 存放路径即可
### 推理脚本
**T2V 完整模型：**
```bash
bash scripts/wan/run_wan_t2v_distill_4step_cfg.sh
```
**I2V 完整模型：**
```bash
bash scripts/wan/run_wan_i2v_distill_4step_cfg.sh
```
### 步数蒸馏 LoRA 推理脚本
**T2V LoRA：**
```bash
bash scripts/wan/run_wan_t2v_distill_4step_cfg_lora.sh
```
**I2V LoRA：**
```bash
bash scripts/wan/run_wan_i2v_distill_4step_cfg_lora.sh
```
## 🔧 服务化部署
### 启动蒸馏模型服务
对 [scripts/server/start_server.sh](https://github.com/ModelTC/lightx2v/blob/main/scripts/server/start_server.sh) 中的启动命令进行修改：
```bash
python -m lightx2v.api_server \
--model_cls wan2.1_distill \
--task t2v \
--model_path $model_path \
--config_json ${lightx2v_path}/configs/distill/wan_t2v_distill_4step_cfg.json \
--port 8000 \
--nproc_per_node 1
```
运行服务启动脚本：
```bash
scripts/server/start_server.sh
```
更多详细信息见[服务化部署](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/deploy_guides/deploy_service.html)。
### 在 Gradio 界面中使用
见 [Gradio 文档](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/deploy_guides/deploy_gradio.html)
docs/ZH_CN/source/method_tutorials/video_frame_interpolation.md 0 → 100644
View file @ a1ebc651
# 视频帧插值 (VFI)
> **重要说明**: 视频帧插值功能通过配置文件启用，而不是通过命令行参数。请在配置 JSON 文件中添加 `video_frame_interpolation` 配置块来启用此功能。
## 概述
视频帧插值（VFI）是一种在现有帧之间生成中间帧的技术，用于提高帧率并创建更流畅的视频播放效果。LightX2V 集成了 RIFE（Real-Time Intermediate Flow Estimation）模型，提供高质量的帧插值能力。
## 什么是 RIFE？
RIFE 是一种最先进的视频帧插值方法，使用光流估计来生成中间帧。它能够有效地：
- 提高视频帧率（例如，从 16 FPS 提升到 32 FPS）
- 创建平滑的运动过渡
- 保持高视觉质量，最少伪影
- 实时处理视频
## 安装和设置
### 下载 RIFE 模型
首先，使用提供的脚本下载 RIFE 模型权重：
```bash
python tools/download_rife.py <目标目录>
```
例如，下载到指定位置：
```bash
python tools/download_rife.py /path/to/rife/train_log
```
此脚本将：
- 从 HuggingFace 下载 RIFEv4.26 模型
- 提取并将模型文件放置在正确的目录中
- 清理临时文件
## 使用方法
### 配置文件设置
视频帧插值功能通过配置文件启用。在你的配置 JSON 文件中添加 `video_frame_interpolation` 配置块：
```json
{
"infer_steps": 50,
"target_video_length": 81,
"target_height": 480,
"target_width": 832,
"fps": 16,
"video_frame_interpolation": {
"algo": "rife",
"target_fps": 32,
"model_path": "/path/to/rife/train_log"
}
}
```
### 命令行使用
使用包含 VFI 配置的配置文件运行推理：
```bash
python lightx2v/infer.py \
--model_cls wan2.1 \
--task t2v \
--model_path /path/to/model \
--config_json ./configs/video_frame_interpolation/wan_t2v.json \
--prompt "美丽的海上日落" \
--save_result_path ./output.mp4
```
### 配置参数说明
在 `video_frame_interpolation` 配置块中：
- `algo`: 帧插值算法，目前支持 "rife"
- `target_fps`: 输出视频的目标帧率
- `model_path`: RIFE 模型路径，通常为 "train_log"
其他相关配置：
- `fps`: 源视频帧率（默认 16）
### 配置优先级
系统会自动处理视频帧率配置，优先级如下：
1. `video_frame_interpolation.target_fps` - 如果启用视频帧插值，使用此帧率作为输出帧率
2. `fps`（默认 16）- 如果未启用视频帧插值，使用此帧率；同时总是用作源帧率
## 工作原理
### 帧插值过程
1. **源视频生成**: 基础模型以源 FPS 生成视频帧
2. **帧分析**: RIFE 分析相邻帧以估计光流
3. **中间帧生成**: 在现有帧之间生成新帧
4. **时序平滑**: 插值帧创建平滑的运动过渡
### 技术细节
- **输入格式**: ComfyUI 图像张量 [N, H, W, C]，范围 [0, 1]
- **输出格式**: 插值后的 ComfyUI 图像张量 [M, H, W, C]，范围 [0, 1]
- **处理**: 自动填充和分辨率处理
- **内存优化**: 高效的 GPU 内存管理
## 示例配置
### 基础帧率翻倍
创建配置文件 `wan_t2v_vfi_32fps.json`：
```json
{
"infer_steps": 50,
"target_video_length": 81,
"target_height": 480,
"target_width": 832,
"seed": 42,
"sample_guide_scale": 6,
"enable_cfg": true,
"fps": 16,
"video_frame_interpolation": {
"algo": "rife",
"target_fps": 32,
"model_path": "/path/to/rife/train_log"
}
}
```
运行命令：
```bash
python lightx2v/infer.py \
--model_cls wan2.1 \
--task t2v \
--model_path ./models/wan2.1 \
--config_json ./wan_t2v_vfi_32fps.json \
--prompt "一只小猫在花园里玩耍" \
--save_result_path ./output_32fps.mp4
```
### 更高帧率增强
创建配置文件 `wan_i2v_vfi_60fps.json`：
```json
{
"infer_steps": 30,
"target_video_length": 81,
"target_height": 480,
"target_width": 832,
"seed": 42,
"sample_guide_scale": 6,
"enable_cfg": true,
"fps": 16,
"video_frame_interpolation": {
"algo": "rife",
"target_fps": 60,
"model_path": "/path/to/rife/train_log"
}
}
```
运行命令：
```bash
python lightx2v/infer.py \
--model_cls wan2.1 \
--task i2v \
--model_path ./models/wan2.1 \
--config_json ./wan_i2v_vfi_60fps.json \
--image_path ./input.jpg \
--prompt "平滑的相机运动" \
--save_result_path ./output_60fps.mp4
```
## 性能考虑
### 内存使用
- RIFE 处理需要额外的 GPU 内存
- 内存使用量与视频分辨率和长度成正比
- 对于较长的视频，考虑使用较低的分辨率
### 处理时间
- 帧插值会增加处理开销
- 更高的目标帧率需要更多计算
- 处理时间大致与插值帧数成正比
### 质量与速度权衡
- 更高的插值比率可能引入伪影
- 最佳范围：2x 到 4x 帧率增加
- 对于极端插值（>4x），考虑多次处理
## 最佳实践
### 最佳使用场景
- **运动密集视频**: 从帧插值中受益最多
- **相机运动**: 更平滑的平移和缩放
- **动作序列**: 减少运动模糊感知
- **慢动作效果**: 创建流畅的慢动作视频
### 推荐设置
- **源 FPS**: 16-24 FPS（基础模型生成）
- **目标 FPS**: 32-60 FPS（2x 到 4x 增加）
- **分辨率**: 最高 720p 以获得最佳性能
### 故障排除
#### 常见问题
1. **内存不足**: 减少视频分辨率或目标 FPS
2. **输出中有伪影**: 降低插值比率
3. **处理缓慢**: 检查 GPU 内存并考虑使用 CPU 卸载
#### 解决方案
通过修改配置文件来解决问题：
```json
{
// 内存问题解决：使用较低分辨率
"target_height": 480,
"target_width": 832,
// 质量问题解决：使用适中的插值
"video_frame_interpolation": {
"target_fps": 24 // 而不是 60
},
// 性能问题解决：启用卸载
"cpu_offload": true
}
```
## 技术实现
LightX2V 中的 RIFE 集成包括：
- **RIFEWrapper**: 与 ComfyUI 兼容的 RIFE 模型包装器
- **自动模型加载**: 与推理管道的无缝集成
- **内存优化**: 高效的张量管理和 GPU 内存使用
- **质量保持**: 在添加帧的同时保持原始视频质量
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment