# ComfyUI-Lightx2vWrapper

## 介绍

ComfyUI-Lightx2vWrapper 是一个用于 ComfyUI 的 [Lightx2v](https://github.com/ModelTC/lightx2v) 推理包装器，支持文本生成视频(T2V)和图像生成视频(I2V)功能。该插件基于Wan模型架构，提供高质量的视频生成能力。

## 功能特性

- 🎬 **文本生成视频(T2V)**: 根据文本描述生成视频
- 🖼️ **图像生成视频(I2V)**: 基于输入图像生成动态视频  
- 🚀 **TeaCache加速**: 支持TeaCache功能缓存优化，提升推理速度
- 🔧 **LoRA支持**: 支持LoRA微调模型加载
- 💾 **内存优化**: 支持CPU卸载和显存管理
- ⚡ **多种注意力机制**: 支持flash_attn2/flash_attn3等高效注意力实现

## 安装

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/gaclove/ComfyUI-Lightx2vWrapper.git
cd ComfyUI-Lightx2vWrapper
git submodule update --init --recursive
cd lightx2v
pip install -r lightx2v/requirements.txt # Install dependencies for lightx2v
```

## 模型准备

### 模型目录结构

确保你的模型目录结构如下：

```text
your_model_dir/
├── config.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模型
├── google/
│   └── umt5-xxl/                                  # T5 tokenizer目录
└── [其他模型文件]
```

### 推荐模型

- **Wan2.1-I2V-14B-480P**: 图像生成视频模型(480p分辨率)
- **Wan2.1-I2V-14B-720P**: 图像生成视频模型(720p分辨率)
- **Wan2.1-T2V-14B**: 文本生成视频模型

## 使用方法

### 图像生成视频(I2V)工作流

1. **设置模型目录**
   - 使用 `Lightx2vWanVideoModelDir` 节点设置模型路径

2. **加载编码器**
   - `Lightx2vWanVideoT5EncoderLoader`: 加载T5文本编码器
   - `Lightx2vWanVideoClipVisionEncoderLoader`: 加载CLIP视觉编码器
   - `Lightx2vWanVideoVaeLoader`: 加载VAE编码器

3. **文本编码**
   - `Lightx2vWanVideoT5Encoder`: 编码正负提示词

4. **图像编码**
   - `Lightx2vWanVideoImageEncoder`: 编码输入图像

5. **模型加载**
   - `Lightx2vWanVideoModelLoader`: 加载主要的Wan模型

6. **视频生成**
   - `Lightx2vWanVideoSampler`: 执行采样生成

7. **解码输出**
   - `Lightx2vWanVideoVaeDecoder`: 将潜在表示解码为视频帧

### 文本生成视频(T2V)工作流

T2V工作流与I2V类似，但使用 `Lightx2vWanVideoEmptyEmbeds` 替代图像编码器。

## 节点说明

### 核心节点

#### Lightx2vWanVideoModelDir

- **功能**: 设置模型目录路径
- **输入**:
  - `model_dir`: 模型目录路径

#### Lightx2vWanVideoT5EncoderLoader  

- **功能**: 加载T5文本编码器
- **输入**:
  - `model_name`: T5模型文件名
  - `precision`: 精度(bf16/fp16/fp32)
  - `device`: 设备(cuda/cpu)

#### Lightx2vWanVideoT5Encoder

- **功能**: 编码文本提示词
- **输入**:
  - `t5_encoder`: T5编码器实例
  - `prompt`: 正面提示词
  - `negative_prompt`: 负面提示词

#### Lightx2vWanVideoVaeLoader

- **功能**: 加载VAE模型
- **输入**:
  - `model_name`: VAE模型文件名
  - `precision`: 精度设置
  - `device`: 设备选择
  - `parallel`: 是否并行处理

#### Lightx2vWanVideoImageEncoder

- **功能**: 编码输入图像用于I2V生成
- **输入**:
  - `vae`: VAE模型实例
  - `clip_vision_encoder`: CLIP视觉编码器
  - `image`: 输入图像
  - `width/height`: 目标分辨率
  - `num_frames`: 生成帧数

#### Lightx2vWanVideoModelLoader

- **功能**: 加载主要的Wan生成模型
- **输入**:
  - `model_type`: 模型类型(t2v/i2v)
  - `precision`: 精度设置
  - `attention_type`: 注意力机制类型
  - `cpu_offload`: 是否CPU卸载
  - `lora_path`: LoRA模型路径(可选)
  - `teacache_args`: TeaCache参数(可选)

#### Lightx2vWanVideoSampler

- **功能**: 执行视频生成采样
- **输入**:
  - `model`: Wan模型实例
  - `text_embeddings`: 文本嵌入
  - `image_embeddings`: 图像嵌入
  - `steps`: 采样步数
  - `cfg_scale`: CFG引导强度
  - `seed`: 随机种子

#### Lightx2vWanVideoVaeDecoder

- **功能**: 解码潜在表示为视频帧
- **输入**:
  - `wan_vae`: VAE模型实例
  - `latent`: 潜在表示

### 优化节点

#### Lightx2vTeaCache

- **功能**: TeaCache加速配置
- **输入**:
  - `rel_l1_thresh`: 缓存阈值
  - `start_percent/end_percent`: 缓存使用范围
  - `coefficients`: 预设系数
  - `cache_device`: 缓存设备

#### Lightx2vWanVideoEmptyEmbeds

- **功能**: 为T2V任务提供空图像嵌入
- **输入**:
  - `width/height`: 目标分辨率
  - `num_frames`: 生成帧数

## 参数说明

### 分辨率设置

- **480P**: width=832, height=480
- **720P**: width=1280, height=720
- 确保宽高为8的倍数

### 帧数设置

- 推荐帧数: 81帧 (约5秒 @ 16fps)
- 帧数应为4的倍数+1 (如: 81, 85, 89等)

### 精度选择

- **bf16**: 推荐用于主模型，平衡精度和性能
- **fp16**: 适用于VAE和CLIP，节省显存
- **fp32**: 最高精度，显存占用大

### CFG引导

- **CFG Scale**: 1.0-20.0，值越高越遵循提示词
- **推荐值**: 5.0-8.0

## 示例工作流

参考 `examples/i2v_workflow.json` 获取完整的I2V工作流配置。

## 性能优化建议

1. **启用TeaCache**: 使用 `Lightx2vTeaCache` 节点加速推理
2. **CPU卸载**: 显存不足时启用 `cpu_offload`
3. **合适精度**: 根据显存情况选择bf16或fp16
4. **批处理**: 多个视频生成时考虑批处理

## 故障排除

### 常见问题

1. **模型文件缺失**: 确保所有必需的模型文件都在正确位置
2. **显存不足**: 降低精度或启用CPU卸载
3. **分辨率错误**: 确保宽高为8的倍数
4. **帧数错误**: 使用4的倍数+1的帧数

### 调试技巧

- 检查模型目录结构是否正确
- 验证config.json文件格式
- 监控GPU显存使用情况
- 查看ComfyUI控制台错误信息

## 更新日志

- 支持Wan2.1模型架构
- 集成TeaCache加速功能  
- 添加LoRA微调支持
- 优化内存管理和性能

## 参考资料

- [Develop Custom Nodes](https://docs.comfy.org/custom-nodes/walkthrough)
- [一份ComfyUI 自定义节点指南](https://developer.volcengine.com/articles/7399549896778317833)
- [Lightx2v](https://github.com/ModelTC/lightx2v)