deploy_gradio.md 8.56 KB
Newer Older
gushiqiao's avatar
gushiqiao committed
1
# Gradio 部署指南
helloyongyang's avatar
helloyongyang committed
2

gushiqiao's avatar
gushiqiao committed
3
4
## 📖 概述

gushiqiao's avatar
gushiqiao committed
5
6
Lightx2v 是一个轻量级的视频推理和生成引擎,提供基于 Gradio 的 Web 界面,支持图像到视频(Image-to-Video)和文本到视频(Text-to-Video)两种生成模式。

gushiqiao's avatar
gushiqiao committed
7
8
对于Windows系统,我们提供了便捷的一键部署方式,支持自动环境配置和智能参数优化。详细操作请参考[一键启动Gradio](./deploy_local_windows.md/#一键启动gradio推荐)章节。

gushiqiao's avatar
Fix  
gushiqiao committed
9
![Gradio中文界面](../../../../assets/figs/portabl_windows/pic_gradio_zh.png)
gushiqiao's avatar
gushiqiao committed
10

gushiqiao's avatar
gushiqiao committed
11
12
13
14
15
16
17
18
## 📁 文件结构

```
LightX2V/app/
├── gradio_demo.py          # 英文界面演示
├── gradio_demo_zh.py       # 中文界面演示
├── run_gradio.sh          # 启动脚本
├── README.md              # 说明文档
gushiqiao's avatar
gushiqiao committed
19
├── outputs/               # 生成视频保存目录
gushiqiao's avatar
gushiqiao committed
20
21
└── inference_logs.log     # 推理日志
```
gushiqiao's avatar
gushiqiao committed
22
23
24
25
26
27
28
29
30

本项目包含两个主要演示文件:
- `gradio_demo.py` - 英文界面版本
- `gradio_demo_zh.py` - 中文界面版本

## 🚀 快速开始

### 环境要求

gushiqiao's avatar
gushiqiao committed
31
按照[快速开始文档](../getting_started/quickstart.md)安装环境
gushiqiao's avatar
gushiqiao committed
32
33
34
35
36
37
38

#### 推荐优化库配置

-[Flash attention](https://github.com/Dao-AILab/flash-attention)
-[Sage attention](https://github.com/thu-ml/SageAttention)
-[vllm-kernel](https://github.com/vllm-project/vllm)
-[sglang-kernel](https://github.com/sgl-project/sglang/tree/main/sgl-kernel)
gushiqiao's avatar
gushiqiao committed
39
40
-[q8-kernel](https://github.com/KONAKONA666/q8_kernels) (仅支持ADA架构的GPU)

Gu Shiqiao's avatar
Gu Shiqiao committed
41
可根据需要,按照各算子的项目主页教程进行安装。
gushiqiao's avatar
gushiqiao committed
42

Gu Shiqiao's avatar
Gu Shiqiao committed
43
### 📥 模型下载
gushiqiao's avatar
gushiqiao committed
44

Gu Shiqiao's avatar
Gu Shiqiao committed
45
可参考[模型结构文档](../getting_started/model_structure.md)下载完整模型(包含量化和非量化版本)或仅下载量化/非量化版本。
gushiqiao's avatar
gushiqiao committed
46

Gu Shiqiao's avatar
Gu Shiqiao committed
47
#### wan2.1 模型目录结构
gushiqiao's avatar
gushiqiao committed
48

Gu Shiqiao's avatar
Gu Shiqiao committed
49
50
51
52
53
54
55
56
57
58
59
60
```
models/
├── 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 量化
├── wan2.1_i2v_720p_int8_lightx2v_4step_split                    # INT8 量化分block存储目录
├── wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step_split         # FP8 量化分block存储目录
├── 其他权重(例如t2v)
├── t5/clip/xlm-roberta-large/google    # text和image encoder
├── vae/lightvae/lighttae               # vae
└── config.json                         # 模型配置文件
```
gushiqiao's avatar
gushiqiao committed
61

Gu Shiqiao's avatar
Gu Shiqiao committed
62
#### wan2.2 模型目录结构
gushiqiao's avatar
gushiqiao committed
63

Gu Shiqiao's avatar
Gu Shiqiao committed
64
65
66
67
68
69
70
71
72
73
74
75
76
77
```
models/
├── wan2.2_i2v_A14b_high_noise_lightx2v_4step_1030.safetensors        # high noise 原始精度
├── wan2.2_i2v_A14b_high_noise_fp8_e4m3_lightx2v_4step_1030.safetensors    # high noise FP8 量化
├── wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step_1030.safetensors   # high noise INT8 量化
├── wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step_1030_split         # high noise INT8 量化分block存储目录
├── wan2.2_i2v_A14b_low_noise_lightx2v_4step.safetensors         # low noise 原始精度
├── wan2.2_i2v_A14b_low_noise_fp8_e4m3_lightx2v_4step.safetensors     # low noise FP8 量化
├── wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors    # low noise INT8 量化
├── wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step_split          # low noise INT8 量化分block存储目录
├── t5/clip/xlm-roberta-large/google    # text和image encoder
├── vae/lightvae/lighttae               # vae
└── config.json                         # 模型配置文件
```
gushiqiao's avatar
gushiqiao committed
78

Gu Shiqiao's avatar
Gu Shiqiao committed
79
**📝 下载说明**
gushiqiao's avatar
gushiqiao committed
80

Gu Shiqiao's avatar
Gu Shiqiao committed
81
82
83
- 模型权重可从 HuggingFace 下载:
  - [Wan2.1-Distill-Models](https://huggingface.co/lightx2v/Wan2.1-Distill-Models)
  - [Wan2.2-Distill-Models](https://huggingface.co/lightx2v/Wan2.2-Distill-Models)
Gu Shiqiao's avatar
Gu Shiqiao committed
84
- Text 和 Image Encoder 可从 [Encoders](https://huggingface.co/lightx2v/Encoders) 下载
Gu Shiqiao's avatar
Gu Shiqiao committed
85
86
- VAE 可从 [Autoencoders](https://huggingface.co/lightx2v/Autoencoders) 下载
- 对于 `xxx_split` 目录(例如 `wan2.1_i2v_720p_scaled_fp8_e4m3_lightx2v_4step_split`),即按照 block 存储的多个 safetensors,适用于内存不足的设备。例如内存 16GB 以内,请根据自身情况下载
gushiqiao's avatar
gushiqiao committed
87
88


gushiqiao's avatar
gushiqiao committed
89
90
91
92
### 启动方式

#### 方式一:使用启动脚本(推荐)

gushiqiao's avatar
gushiqiao committed
93
**Linux 环境:**
gushiqiao's avatar
gushiqiao committed
94
95
96
97
98
99
100
```bash
# 1. 编辑启动脚本,配置相关路径
cd app/
vim run_gradio.sh

# 需要修改的配置项:
# - lightx2v_path: Lightx2v项目根目录路径
Gu Shiqiao's avatar
Gu Shiqiao committed
101
# - model_path: 模型根目录路径(包含所有模型文件)
gushiqiao's avatar
gushiqiao committed
102
103
104
105
106
107
108

# 💾 重要提示:建议将模型路径指向SSD存储位置
# 例如:/mnt/ssd/models/ 或 /data/ssd/models/

# 2. 运行启动脚本
bash run_gradio.sh

Gu Shiqiao's avatar
Gu Shiqiao committed
109
110
111
# 3. 或使用参数启动
bash run_gradio.sh --lang zh --port 8032
bash run_gradio.sh --lang en --port 7862
gushiqiao's avatar
gushiqiao committed
112
113
114
115
116
117
118
119
120
121
```

**Windows 环境:**
```cmd
# 1. 编辑启动脚本,配置相关路径
cd app\
notepad run_gradio_win.bat

# 需要修改的配置项:
# - lightx2v_path: Lightx2v项目根目录路径
Gu Shiqiao's avatar
Gu Shiqiao committed
122
# - model_path: 模型根目录路径(包含所有模型文件)
gushiqiao's avatar
gushiqiao committed
123
124
125
126
127
128
129

# 💾 重要提示:建议将模型路径指向SSD存储位置
# 例如:D:\models\ 或 E:\models\

# 2. 运行启动脚本
run_gradio_win.bat

Gu Shiqiao's avatar
Gu Shiqiao committed
130
131
132
# 3. 或使用参数启动
run_gradio_win.bat --lang zh --port 8032
run_gradio_win.bat --lang en --port 7862
gushiqiao's avatar
gushiqiao committed
133
134
135
136
```

#### 方式二:直接命令行启动

Gu Shiqiao's avatar
Gu Shiqiao committed
137
138
139
140
```bash
pip install -v git+https://github.com/ModelTC/LightX2V.git
```

gushiqiao's avatar
gushiqiao committed
141
142
**Linux 环境:**

Gu Shiqiao's avatar
Gu Shiqiao committed
143
**中文界面版本:**
gushiqiao's avatar
gushiqiao committed
144
145
```bash
python gradio_demo_zh.py \
Gu Shiqiao's avatar
Gu Shiqiao committed
146
    --model_path /path/to/models \
gushiqiao's avatar
gushiqiao committed
147
148
149
150
    --server_name 0.0.0.0 \
    --server_port 7862
```

gushiqiao's avatar
gushiqiao committed
151
**英文界面版本:**
gushiqiao's avatar
gushiqiao committed
152
```bash
gushiqiao's avatar
gushiqiao committed
153
python gradio_demo.py \
Gu Shiqiao's avatar
Gu Shiqiao committed
154
    --model_path /path/to/models \
gushiqiao's avatar
gushiqiao committed
155
156
157
158
    --server_name 0.0.0.0 \
    --server_port 7862
```

gushiqiao's avatar
gushiqiao committed
159
160
**Windows 环境:**

Gu Shiqiao's avatar
Gu Shiqiao committed
161
**中文界面版本:**
gushiqiao's avatar
gushiqiao committed
162
163
```cmd
python gradio_demo_zh.py ^
Gu Shiqiao's avatar
Gu Shiqiao committed
164
    --model_path D:\models ^
gushiqiao's avatar
gushiqiao committed
165
166
167
168
    --server_name 127.0.0.1 ^
    --server_port 7862
```

gushiqiao's avatar
gushiqiao committed
169
**英文界面版本:**
gushiqiao's avatar
gushiqiao committed
170
```cmd
Gu Shiqiao's avatar
Gu Shiqiao committed
171
172
python gradio_demo.py ^
    --model_path D:\models ^
gushiqiao's avatar
gushiqiao committed
173
    --server_name 127.0.0.1 ^
gushiqiao's avatar
gushiqiao committed
174
175
176
    --server_port 7862
```

Gu Shiqiao's avatar
Gu Shiqiao committed
177
178
**💡 提示**:模型类型(wan2.1/wan2.2)、任务类型(i2v/t2v)以及具体的模型文件选择均在 Web 界面中进行配置。

gushiqiao's avatar
gushiqiao committed
179
180
181
182
## 📋 命令行参数

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
Gu Shiqiao's avatar
Gu Shiqiao committed
183
| `--model_path` | str | ✅ | - | 模型根目录路径(包含所有模型文件的目录) |
gushiqiao's avatar
gushiqiao committed
184
185
| `--server_port` | int | ❌ | 7862 | 服务器端口 |
| `--server_name` | str | ❌ | 0.0.0.0 | 服务器IP地址 |
Gu Shiqiao's avatar
Gu Shiqiao committed
186
187
188
| `--output_dir` | str | ❌ | ./outputs | 输出视频保存目录 |

**💡 说明**:模型类型(wan2.1/wan2.2)、任务类型(i2v/t2v)以及具体的模型文件选择均在 Web 界面中进行配置。
gushiqiao's avatar
gushiqiao committed
189
190
191

## 🎯 功能特性

Gu Shiqiao's avatar
Gu Shiqiao committed
192
193
194
195
196
197
198
199
200
### 模型配置

- **模型类型**: 支持 wan2.1 和 wan2.2 两种模型架构
- **任务类型**: 支持图像到视频(i2v)和文本到视频(t2v)两种生成模式
- **模型选择**: 前端自动识别并筛选可用的模型文件,支持自动检测量化精度
- **编码器配置**: 支持选择 T5 文本编码器、CLIP 图像编码器和 VAE 解码器
- **算子选择**: 支持多种注意力算子和量化矩阵乘法算子,系统会根据安装状态自动排序

### 输入参数
gushiqiao's avatar
gushiqiao committed
201
202
203

- **提示词 (Prompt)**: 描述期望的视频内容
- **负向提示词 (Negative Prompt)**: 指定不希望出现的元素
Gu Shiqiao's avatar
Gu Shiqiao committed
204
- **输入图像**: i2v 模式下需要上传输入图像
gushiqiao's avatar
gushiqiao committed
205
206
- **分辨率**: 支持多种预设分辨率(480p/540p/720p)
- **随机种子**: 控制生成结果的随机性
Gu Shiqiao's avatar
Gu Shiqiao committed
207
208
209
- **推理步数**: 影响生成质量和速度的平衡(蒸馏模型默认为 4 步)

### 视频参数
gushiqiao's avatar
gushiqiao committed
210
211
212

- **FPS**: 每秒帧数
- **总帧数**: 视频长度
Gu Shiqiao's avatar
Gu Shiqiao committed
213
- **CFG缩放因子**: 控制提示词影响强度(1-10,蒸馏模型默认为 1)
gushiqiao's avatar
gushiqiao committed
214
215
- **分布偏移**: 控制生成风格偏离程度(0-10)

Gu Shiqiao's avatar
Gu Shiqiao committed
216
## 🔧 自动配置功能
gushiqiao's avatar
gushiqiao committed
217

Gu Shiqiao's avatar
Gu Shiqiao committed
218
系统会根据您的硬件配置(GPU 显存和 CPU 内存)自动配置最优推理选项,无需手动调整。启动时会自动应用最佳配置,包括:
gushiqiao's avatar
gushiqiao committed
219

Gu Shiqiao's avatar
Gu Shiqiao committed
220
221
222
223
- **GPU 内存优化**: 根据显存大小自动启用 CPU 卸载、VAE 分块推理等
- **CPU 内存优化**: 根据系统内存自动启用延迟加载、模块卸载等
- **算子选择**: 自动选择已安装的最优算子(按优先级排序)
- **量化配置**: 根据模型文件名自动检测并应用量化精度
gushiqiao's avatar
gushiqiao committed
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241


### 日志查看

```bash
# 查看推理日志
tail -f inference_logs.log

# 查看GPU使用情况
nvidia-smi

# 查看系统资源
htop
```

欢迎提交Issue和Pull Request来改进这个项目!

**注意**: 使用本工具生成的视频内容请遵守相关法律法规,不得用于非法用途。