model_structure.md 16.5 KB
Newer Older
gushiqiao's avatar
gushiqiao committed
1
2
3
4
# 模型结构介绍

## 📖 概述

gushiqiao's avatar
gushiqiao committed
5
本文档全面介绍 LightX2V 项目的模型目录结构,旨在帮助用户高效组织模型文件,实现便捷的使用体验。通过科学的目录组织方式,用户可以享受"一键启动"的便利,无需手动配置复杂的路径参数。同时,系统也支持灵活的手动路径配置,满足不同用户群体的多样化需求。
gushiqiao's avatar
gushiqiao committed
6
7
8

## 🗂️ 模型目录结构

gushiqiao's avatar
gushiqiao committed
9
### LightX2V 官方模型列表
gushiqiao's avatar
gushiqiao committed
10

gushiqiao's avatar
gushiqiao committed
11
查看所有可用模型:[LightX2V 官方模型仓库](https://huggingface.co/lightx2v)
gushiqiao's avatar
gushiqiao committed
12
13
14

### 标准目录结构

gushiqiao's avatar
gushiqiao committed
15
`Wan2.1-I2V-14B-480P-LightX2V` 为例,标准文件结构如下:
gushiqiao's avatar
gushiqiao committed
16
17

```
gushiqiao's avatar
gushiqiao committed
18
Wan2.1-I2V-14B-480P-LightX2V/
gushiqiao's avatar
gushiqiao committed
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
├── fp8/                                          # FP8 量化版本 (DIT/T5/CLIP)
│   ├── block_xx.safetensors                      # DIT 模型 FP8 量化版本
│   ├── models_t5_umt5-xxl-enc-fp8.pth            # T5 编码器 FP8 量化版本
│   ├── clip-fp8.pth                              # CLIP 编码器 FP8 量化版本
│   ├── Wan2.1_VAE.pth                            # VAE 变分自编码器
│   ├── taew2_1.pth                               # 轻量级 VAE (可选)
│   └── config.json                               # 模型配置文件
├── int8/                                         # INT8 量化版本 (DIT/T5/CLIP)
│   ├── block_xx.safetensors                      # DIT 模型 INT8 量化版本
│   ├── models_t5_umt5-xxl-enc-int8.pth           # T5 编码器 INT8 量化版本
│   ├── clip-int8.pth                             # CLIP 编码器 INT8 量化版本
│   ├── Wan2.1_VAE.pth                            # VAE 变分自编码器
│   ├── taew2_1.pth                               # 轻量级 VAE (可选)
│   └── config.json                               # 模型配置文件
├── original/                                     # 原始精度版本 (DIT/T5/CLIP)
gushiqiao's avatar
gushiqiao committed
34
35
36
37
38
39
40
41
42
43
44
45
46
│   ├── xx.safetensors                            # DIT 模型原始精度版本
│   ├── 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 变分自编码器
│   ├── taew2_1.pth                               # 轻量级 VAE (可选)
│   └── config.json                               # 模型配置文件
```

`Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V` 为例,标准文件结构如下:


```
Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V/
GoatWu's avatar
GoatWu committed
47
├── distill_fp8/                                  # FP8 量化版本 (DIT/T5/CLIP)
gushiqiao's avatar
gushiqiao committed
48
49
50
51
52
53
│   ├── block_xx.safetensors                      # DIT 模型 FP8 量化版本
│   ├── models_t5_umt5-xxl-enc-fp8.pth            # T5 编码器 FP8 量化版本
│   ├── clip-fp8.pth                              # CLIP 编码器 FP8 量化版本
│   ├── Wan2.1_VAE.pth                            # VAE 变分自编码器
│   ├── taew2_1.pth                               # 轻量级 VAE (可选)
│   └── config.json                               # 模型配置文件
GoatWu's avatar
GoatWu committed
54
├── distill_int8/                                 # INT8 量化版本 (DIT/T5/CLIP)
gushiqiao's avatar
gushiqiao committed
55
56
57
58
59
60
│   ├── block_xx.safetensors                      # DIT 模型 INT8 量化版本
│   ├── models_t5_umt5-xxl-enc-int8.pth           # T5 编码器 INT8 量化版本
│   ├── clip-int8.pth                             # CLIP 编码器 INT8 量化版本
│   ├── Wan2.1_VAE.pth                            # VAE 变分自编码器
│   ├── taew2_1.pth                               # 轻量级 VAE (可选)
│   └── config.json                               # 模型配置文件
GoatWu's avatar
GoatWu committed
61
├── distill_models/                               # 原始精度版本 (DIT/T5/CLIP)
gushiqiao's avatar
gushiqiao committed
62
63
64
65
66
67
│   ├── distill_model.safetensors                 # DIT 模型原始精度版本
│   ├── 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 变分自编码器
│   ├── taew2_1.pth                               # 轻量级 VAE (可选)
│   └── config.json                               # 模型配置文件
GoatWu's avatar
GoatWu committed
68
69
├── loras/
│   ├── Wan21_I2V_14B_lightx2v_cfg_step_distill_lora_rank64.safetensors  # 蒸馏模型lora
gushiqiao's avatar
gushiqiao committed
70
71
72
73
```

### 💾 存储建议

gushiqiao's avatar
gushiqiao committed
74
**强烈建议将模型文件存储在 SSD 固态硬盘上**,此举可显著提升模型加载速度和推理性能。
gushiqiao's avatar
gushiqiao committed
75
76
77

**推荐存储路径**
```bash
gushiqiao's avatar
gushiqiao committed
78
79
/mnt/ssd/models/          # 独立 SSD 挂载点
/data/ssd/models/         # 数据 SSD 目录
gushiqiao's avatar
gushiqiao committed
80
81
82
/opt/models/              # 系统优化目录
```

gushiqiao's avatar
gushiqiao committed
83
84
85
86
87
88
89
90
91
92
### 量化版本说明

每个模型均包含多个量化版本,适配不同硬件配置需求:
- **FP8 版本**:适用于支持 FP8 的 GPU(如 H100、A100、RTX 40系列),提供最佳性能表现
- **INT8 版本**:适用于大多数 GPU,在性能和兼容性间取得平衡,内存占用减少约50%
- **原始精度版本**:适用于对精度要求极高的应用场景,提供最高质量输出

## 🚀 使用方法

### 环境准备
gushiqiao's avatar
gushiqiao committed
93

gushiqiao's avatar
gushiqiao committed
94
#### 安装 Hugging Face CLI
gushiqiao's avatar
gushiqiao committed
95

gushiqiao's avatar
gushiqiao committed
96
在开始下载模型之前,请确保已正确安装 Hugging Face CLI:
gushiqiao's avatar
gushiqiao committed
97

gushiqiao's avatar
gushiqiao committed
98
99
100
101
102
103
```bash
# 安装 huggingface_hub
pip install huggingface_hub

# 或者安装 huggingface-cli
pip install huggingface-cli
gushiqiao's avatar
gushiqiao committed
104

gushiqiao's avatar
gushiqiao committed
105
106
# 登录 Hugging Face(可选,但强烈推荐)
huggingface-cli login
gushiqiao's avatar
gushiqiao committed
107
```
gushiqiao's avatar
gushiqiao committed
108
109
110
111
112
113
114
115
116
117
118

### 方式一:完整模型下载(推荐)

**优势**:下载完整模型后,系统将自动识别所有组件路径,无需手动配置,使用体验更加便捷

#### 1. 下载完整模型

```bash
# 使用 Hugging Face CLI 下载完整模型
huggingface-cli download lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
    --local-dir ./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V
gushiqiao's avatar
gushiqiao committed
119
120
```

gushiqiao's avatar
gushiqiao committed
121
#### 2. 启动推理
gushiqiao's avatar
gushiqiao committed
122

gushiqiao's avatar
gushiqiao committed
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
##### Bash 脚本启动

###### 场景一:使用全精度模型

修改[运行脚本](https://github.com/ModelTC/LightX2V/tree/main/scripts/wan/run_wan_i2v_distill_4step_cfg.sh)中的配置:
- `model_path`:设置为下载的模型路径 `./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V`
- `lightx2v_path`:设置为 `LightX2V` 项目根目录路径

###### 场景二:使用量化模型

当使用完整模型时,如需启用量化功能,请在[配置文件](https://github.com/ModelTC/LightX2V/tree/main/configs/distill/wan_i2v_distill_4step_cfg.json)中添加以下配置:

```json
{
    "mm_config": {
        "mm_type": "W-fp8-channel-sym-A-fp8-channel-sym-dynamic-Vllm"
    },                              // DIT 模型量化方案
    "t5_quantized": true,           // 启用 T5 量化
    "t5_quant_scheme": "fp8",       // T5 量化模式
    "clip_quantized": true,         // 启用 CLIP 量化
    "clip_quant_scheme": "fp8"      // CLIP 量化模式
}
```
gushiqiao's avatar
gushiqiao committed
146

gushiqiao's avatar
gushiqiao committed
147
> **重要提示**:各模型的量化配置可以灵活组合。量化路径无需手动指定,系统将自动定位各模型的量化版本。
gushiqiao's avatar
gushiqiao committed
148

gushiqiao's avatar
gushiqiao committed
149
150
151
有关量化技术的详细说明,请参考[量化文档](../method_tutorials/quantization.md)

使用提供的 bash 脚本快速启动:
gushiqiao's avatar
gushiqiao committed
152
153

```bash
gushiqiao's avatar
gushiqiao committed
154
155
156
157
158
159
160
161
162
163
cd LightX2V/scripts
bash wan/run_wan_t2v_distill_4step_cfg.sh
```

##### Gradio 界面启动

通过 Gradio 界面进行推理时,只需在启动时指定模型根目录路径,轻量级 VAE 等可通过前端界面按钮灵活选择:

```bash
# 图像到视频推理 (I2V)
gushiqiao's avatar
gushiqiao committed
164
python gradio_demo_zh.py \
gushiqiao's avatar
gushiqiao committed
165
    --model_path ./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
gushiqiao's avatar
gushiqiao committed
166
    --model_size 14b \
gushiqiao's avatar
gushiqiao committed
167
168
169
170
171
172
173
    --task i2v \
    --model_cls wan2.1_distill
```

### 方式二:选择性下载

**优势**:仅下载所需的版本(量化或非量化),有效节省存储空间和下载时间
gushiqiao's avatar
gushiqiao committed
174

gushiqiao's avatar
gushiqiao committed
175
176
177
178
179
180
#### 1. 选择性下载

```bash
# 使用 Hugging Face CLI 选择性下载非量化版本
huggingface-cli download lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
    --local-dir ./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
gushiqiao's avatar
gushiqiao committed
181
    --include "distill_models/*"
gushiqiao's avatar
gushiqiao committed
182
183
184
185
186
187
```

```bash
# 使用 Hugging Face CLI 选择性下载 FP8 量化版本
huggingface-cli download lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
    --local-dir ./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
gushiqiao's avatar
gushiqiao committed
188
    --include "distill_fp8/*"
gushiqiao's avatar
gushiqiao committed
189
190
191
192
193
194
```

```bash
# 使用 Hugging Face CLI 选择性下载 INT8 量化版本
huggingface-cli download lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
    --local-dir ./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V \
gushiqiao's avatar
gushiqiao committed
195
    --include "distill_int8/*"
gushiqiao's avatar
gushiqiao committed
196
197
```

gushiqiao's avatar
gushiqiao committed
198
> **重要提示**:当启动推理脚本或Gradio时,`model_path` 参数仍需要指定为不包含 `--include` 的完整路径。例如:`model_path=./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V`,而不是 `./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V/distill_int8`。
gushiqiao's avatar
gushiqiao committed
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252

#### 2. 启动推理

**以只下载了FP8版本的模型为例:**

##### Bash 脚本启动

###### 场景一:使用 FP8 DIT + FP8 T5 + FP8 CLIP

[运行脚本](https://github.com/ModelTC/LightX2V/tree/main/scripts/wan/run_wan_i2v_distill_4step_cfg.sh)中的 `model_path` 指定为您下载好的模型路径 `./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V/``lightx2v_path` 指定为您的 `LightX2V` 项目路径。

仅需修改配置文件中的量化模型配置如下:
```json
{
    "mm_config": {
        "mm_type": "W-fp8-channel-sym-A-fp8-channel-sym-dynamic-Vllm"
    },                              // DIT 的量化方案
    "t5_quantized": true,           // 是否使用 T5 量化版本
    "t5_quant_scheme": "fp8",       // T5 的量化模式
    "clip_quantized": true,         // 是否使用 CLIP 量化版本
    "clip_quant_scheme": "fp8",     // CLIP 的量化模式
}
```

> **重要提示**:此时各模型只能指定为量化版本。量化路径无需手动指定,系统将自动定位各模型的量化版本。

###### 场景二:使用 FP8 DIT + 原始精度 T5 + 原始精度 CLIP

[运行脚本](https://github.com/ModelTC/LightX2V/tree/main/scripts/wan/run_wan_i2v_distill_4step_cfg.sh)中的 `model_path` 指定为您下载好的模型路径 `./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V``lightx2v_path` 指定为您的 `LightX2V` 项目路径。

由于仅下载了量化权重,需要手动下载 T5 和 CLIP 的原始精度版本,并在配置文件的 `t5_original_ckpt``clip_original_ckpt` 中配置如下:
```json
{
    "mm_config": {
        "mm_type": "W-fp8-channel-sym-A-fp8-channel-sym-dynamic-Vllm"
    },                              // DIT 的量化方案
    "t5_original_ckpt": "/path/to/models_t5_umt5-xxl-enc-bf16.pth",
    "clip_original_ckpt": "/path/to/models_clip_open-clip-xlm-roberta-large-vit-huge-14.pth"
}
```

使用提供的 bash 脚本快速启动:

```bash
cd LightX2V/scripts
bash wan/run_wan_t2v_distill_4step_cfg.sh
```

##### Gradio 界面启动

通过 Gradio 界面进行推理时,启动时指定模型根目录路径:

```bash
# 图像到视频推理 (I2V)
gushiqiao's avatar
gushiqiao committed
253
python gradio_demo_zh.py \
gushiqiao's avatar
gushiqiao committed
254
    --model_path ./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V/ \
gushiqiao's avatar
gushiqiao committed
255
    --model_size 14b \
gushiqiao's avatar
gushiqiao committed
256
257
    --task i2v \
    --model_cls wan2.1_distill
gushiqiao's avatar
gushiqiao committed
258
259
```

gushiqiao's avatar
gushiqiao committed
260
> **重要提示**:由于模型根目录下仅包含各模型的量化版本,前端使用时,对于 DIT/T5/CLIP 模型的量化精度只能选择 fp8。如需使用非量化版本的T5/CLIP,请手动下载非量化权重并放置到gradio_demo的model_path目录(`./Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-LightX2V/`)下,此时T5/CLIP的量化精度可以选择bf16/fp16。
gushiqiao's avatar
gushiqiao committed
261

gushiqiao's avatar
gushiqiao committed
262
### 方式三:手动配置
gushiqiao's avatar
gushiqiao committed
263

gushiqiao's avatar
gushiqiao committed
264
用户可根据实际需求灵活配置各个组件的量化选项和路径,实现量化与非量化组件的混合使用。请确保所需的模型权重已正确下载并放置在指定路径。
gushiqiao's avatar
gushiqiao committed
265

gushiqiao's avatar
gushiqiao committed
266
#### DIT 模型配置
gushiqiao's avatar
gushiqiao committed
267

gushiqiao's avatar
gushiqiao committed
268
269
270
271
272
273
274
275
276
```json
{
    "dit_quantized_ckpt": "/path/to/dit_quantized_ckpt",    // DIT 量化权重路径
    "dit_original_ckpt": "/path/to/dit_original_ckpt",      // DIT 原始精度权重路径
    "mm_config": {
        "mm_type": "W-fp8-channel-sym-A-fp8-channel-sym-dynamic-Vllm"  // DIT 矩阵乘算子类型,非量化时指定为 "Default"
    }
}
```
gushiqiao's avatar
gushiqiao committed
277

gushiqiao's avatar
gushiqiao committed
278
#### T5 模型配置
gushiqiao's avatar
gushiqiao committed
279

gushiqiao's avatar
gushiqiao committed
280
281
282
283
284
285
286
287
```json
{
    "t5_quantized_ckpt": "/path/to/t5_quantized_ckpt",      // T5 量化权重路径
    "t5_original_ckpt": "/path/to/t5_original_ckpt",        // T5 原始精度权重路径
    "t5_quantized": true,                                   // 是否启用 T5 量化
    "t5_quant_scheme": "fp8"                                // T5 量化模式,仅在 t5_quantized  true 时生效
}
```
gushiqiao's avatar
gushiqiao committed
288

gushiqiao's avatar
gushiqiao committed
289
#### CLIP 模型配置
gushiqiao's avatar
gushiqiao committed
290

gushiqiao's avatar
gushiqiao committed
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
```json
{
    "clip_quantized_ckpt": "/path/to/clip_quantized_ckpt",  // CLIP 量化权重路径
    "clip_original_ckpt": "/path/to/clip_original_ckpt",    // CLIP 原始精度权重路径
    "clip_quantized": true,                                 // 是否启用 CLIP 量化
    "clip_quant_scheme": "fp8"                              // CLIP 量化模式,仅在 clip_quantized  true 时生效
}
```

#### VAE 模型配置

```json
{
    "vae_pth": "/path/to/Wan2.1_VAE.pth",                   // 原始 VAE 模型路径
    "use_tiny_vae": true,                                   // 是否使用轻量级 VAE
    "tiny_vae_path": "/path/to/taew2_1.pth"                 // 轻量级 VAE 模型路径
}
```
gushiqiao's avatar
gushiqiao committed
309

gushiqiao's avatar
gushiqiao committed
310
311
312
313
> **配置说明**:
> - 量化权重和原始精度权重可以灵活混合使用,系统将根据配置自动选择对应的模型
> - 量化模式的选择取决于您的硬件支持情况,建议在 H100/A100 等高端 GPU 上使用 FP8
> - 轻量级 VAE 可以显著提升推理速度,但可能略微影响生成质量
gushiqiao's avatar
gushiqiao committed
314
315
316

## 💡 最佳实践

gushiqiao's avatar
gushiqiao committed
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
### 推荐配置

**完整模型用户**
- 下载完整模型,享受自动路径查找的便利
- 仅需配置量化方案和组件开关
- 推荐使用 bash 脚本快速启动

**存储空间受限用户**
- 选择性下载所需的量化版本
- 灵活混合使用量化和原始精度组件
- 使用 bash 脚本简化启动流程

**高级用户**
- 完全手动配置路径,实现最大灵活性
- 支持模型文件分散存储
- 可自定义 bash 脚本参数

### 性能优化建议

- **使用 SSD 存储**:显著提升模型加载速度和推理性能
- **选择合适的量化方案**
  - FP8:适用于 H100/A100 等高端 GPU,精度高
  - INT8:适用于通用 GPU,内存占用小
- **启用轻量级 VAE**`use_tiny_vae: true` 可提升推理速度
- **合理配置 CPU 卸载**`t5_cpu_offload: true` 可节省 GPU 内存

### 下载优化建议

- **使用 Hugging Face CLI**:比 git clone 更稳定,支持断点续传
- **选择性下载**:仅下载所需的量化版本,节省时间和存储空间
- **网络优化**:使用稳定的网络连接,必要时使用代理
- **断点续传**:使用 `--resume-download` 参数支持中断后继续下载
gushiqiao's avatar
gushiqiao committed
349
350
351

## 🚨 常见问题

gushiqiao's avatar
gushiqiao committed
352
353
### Q: 模型文件过大,下载速度缓慢怎么办?
A: 建议使用选择性下载方式,仅下载所需的量化版本,或使用国内镜像源
gushiqiao's avatar
gushiqiao committed
354
355

### Q: 启动时提示模型路径不存在?
gushiqiao's avatar
gushiqiao committed
356
A: 请检查模型是否已正确下载,验证路径配置是否正确,确认自动查找机制是否正常工作
gushiqiao's avatar
gushiqiao committed
357

gushiqiao's avatar
gushiqiao committed
358
359
### Q: 如何切换不同的量化方案?
A: 修改配置文件中的 `mm_type`, `t5_quant_scheme`,`clip_quant_scheme`等参数,请参考[量化文档](../method_tutorials/quantization.md)
gushiqiao's avatar
gushiqiao committed
360

gushiqiao's avatar
gushiqiao committed
361
362
### Q: 如何混合使用量化和原始精度组件?
A: 通过 `t5_quantized``clip_quantized` 参数控制,并手动指定原始精度路径
gushiqiao's avatar
gushiqiao committed
363
364

### Q: 配置文件中的路径如何设置?
gushiqiao's avatar
gushiqiao committed
365
366
367
368
369
370
371
A: 推荐使用自动路径查找,如需手动配置请参考"手动配置"部分

### Q: 如何验证自动路径查找是否正常工作?
A: 查看启动日志,代码将输出实际使用的模型路径

### Q: bash 脚本启动失败怎么办?
A: 检查脚本中的路径配置是否正确,确保 `lightx2v_path``model_path` 变量已正确设置
gushiqiao's avatar
gushiqiao committed
372
373
374

## 📚 相关链接

gushiqiao's avatar
gushiqiao committed
375
376
377
- [LightX2V 官方模型仓库](https://huggingface.co/lightx2v)
- [Gradio 部署指南](./deploy_gradio.md)
- [配置文件示例](https://github.com/ModelTC/LightX2V/tree/main/configs)
gushiqiao's avatar
gushiqiao committed
378
379
380

---

gushiqiao's avatar
gushiqiao committed
381
通过科学的模型文件组织和灵活的配置选项,LightX2V 支持多种使用场景。完整模型下载提供最大的便利性,选择性下载节省存储空间,手动配置提供最大的灵活性。自动路径查找机制确保用户无需记忆复杂的路径配置,同时保持系统的可扩展性。