203 lines
6.3 KiB
Markdown
203 lines
6.3 KiB
Markdown
[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/comfyanonymous/ComfyUI) [](https://huggingface.co/lightx2v) [](https://deepwiki.com/GacLove/ComfyUI-Lightx2vWrapper)
|
||
|
||
# ComfyUI-Lightx2vWrapper
|
||
|
||
[English](./README.md) | 中文版
|
||
|
||
LightX2V 的 ComfyUI 自定义节点封装，通过模块化配置实现视频生成和高级优化功能。
|
||
|
||
## 功能特性
|
||
|
||
- **模块化配置系统**：为视频生成的各个方面提供独立的配置节点
|
||
- **文本生成视频（T2V）和图像生成视频（I2V）**：支持两种生成模式
|
||
- **高级优化功能**：
|
||
- TeaCache 加速（最高可达 3 倍速度提升）
|
||
- 量化支持（int8、fp8）
|
||
- 内存优化与 CPU 卸载
|
||
- 轻量级 VAE 选项
|
||
- **LoRA 支持**：可串联多个 LoRA 模型进行自定义
|
||
- **多模型支持**：wan2.1、hunyuan 架构
|
||
|
||
## 安装说明
|
||
|
||
1. 将此仓库克隆到 ComfyUI 的 `custom_nodes` 目录，包含子模块：
|
||
|
||
```bash
|
||
cd ComfyUI/custom_nodes
|
||
git clone --recursive https://github.com/gaclove/ComfyUI-Lightx2vWrapper.git
|
||
```
|
||
|
||
如果已经克隆但未包含子模块，请初始化子模块：
|
||
|
||
```bash
|
||
cd ComfyUI-Lightx2vWrapper
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
2. 安装依赖：
|
||
|
||
```bash
|
||
cd ComfyUI-Lightx2vWrapper
|
||
# 安装 lightx2v 子模块依赖
|
||
pip install -r lightx2v/requirements.txt
|
||
# 安装 ComfyUI 封装器依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
3. 下载模型并放置在 `ComfyUI/models/lightx2v/` 目录
|
||
|
||
## 节点概览
|
||
|
||
### 配置节点
|
||
|
||
#### 1. LightX2V Inference Config（推理配置）
|
||
|
||
视频生成的基础推理配置。
|
||
|
||
- **输入**：model（模型）、task_type（任务类型）、inference_steps（推理步数）、seed（种子）、cfg_scale（CFG 缩放）、width（宽度）、height（高度）、video_length（视频长度）、fps（帧率）
|
||
- **输出**：基础配置对象
|
||
|
||
#### 2. LightX2V TeaCache（TeaCache 配置）
|
||
|
||
特征缓存加速配置。
|
||
|
||
- **输入**：enable（启用）、threshold（阈值 0.0-1.0）、use_ret_steps（使用返回步数）
|
||
- **输出**：TeaCache 配置
|
||
- **注意**：阈值越低 = 速度提升越大（0.1 约 2 倍，0.2 约 3 倍）
|
||
|
||
#### 3. LightX2V Quantization（量化配置）
|
||
|
||
模型量化设置，提升内存效率。
|
||
|
||
- **输入**：dit_precision（DIT 精度）、t5_precision（T5 精度）、clip_precision（CLIP 精度）、backend（后端）、sensitive_layers_precision（敏感层精度）
|
||
- **输出**：量化配置
|
||
- **后端**：自动检测（vllm、sgl、q8f）
|
||
|
||
#### 4. LightX2V Memory Optimization（内存优化）
|
||
|
||
内存管理策略。
|
||
|
||
- **输入**：optimization_level（优化级别）、attention_type（注意力类型）、enable_rotary_chunking（启用旋转分块）、cpu_offload（CPU 卸载）、unload_after_generate（生成后卸载）
|
||
- **输出**：内存优化配置
|
||
|
||
#### 5. LightX2V Lightweight VAE（轻量级 VAE）
|
||
|
||
VAE 优化选项。
|
||
|
||
- **输入**：use_tiny_vae（使用微型 VAE）、use_tiling_vae（使用平铺 VAE）
|
||
- **输出**：VAE 配置
|
||
|
||
#### 6. LightX2V LoRA Loader（LoRA 加载器）
|
||
|
||
加载并串联 LoRA 模型。
|
||
|
||
- **输入**：lora_name（LoRA 名称）、strength（强度 0.0-2.0）、lora_chain（LoRA 链，可选）
|
||
- **输出**：LoRA 链配置
|
||
|
||
### 组合节点
|
||
|
||
#### 7. LightX2V Config Combiner（配置组合器）
|
||
|
||
将所有配置模块组合成单一配置。
|
||
|
||
- **输入**：所有配置类型（可选）
|
||
- **输出**：组合后的配置对象
|
||
|
||
### 推理节点
|
||
|
||
#### 8. LightX2V Modular Inference（模块化推理）
|
||
|
||
视频生成的主推理节点。
|
||
|
||
- **输入**：combined_config（组合配置）、prompt（提示词）、negative_prompt（负面提示词）、image（图像，可选）、audio（音频，可选）
|
||
- **输出**：生成的视频帧
|
||
|
||
## 使用示例
|
||
|
||
### 基础 T2V 工作流
|
||
|
||
1. 创建 LightX2V Inference Config（task_type: "t2v"）
|
||
2. 使用 LightX2V Config Combiner
|
||
3. 连接到 LightX2V Modular Inference，输入文本提示词
|
||
4. 保存视频输出
|
||
|
||
### 带优化的 I2V
|
||
|
||
1. 加载输入图像
|
||
2. 创建 LightX2V Inference Config（task_type: "i2v"）
|
||
3. 添加 LightX2V TeaCache（threshold: 0.26）
|
||
4. 添加 LightX2V Memory Optimization
|
||
5. 使用 LightX2V Config Combiner 组合配置
|
||
6. 运行 LightX2V Modular Inference
|
||
|
||
### 使用 LoRA
|
||
|
||
1. 创建基础配置
|
||
2. 使用 LightX2V LoRA Loader 加载 LoRA
|
||
3. 如需要可串联多个 LoRA
|
||
4. 组合所有配置
|
||
5. 运行推理
|
||
|
||
## 模型目录结构
|
||
|
||
从以下地址下载模型：<https://huggingface.co/lightx2v>
|
||
|
||
模型应放置在：
|
||
|
||
```txt
|
||
ComfyUI/models/lightx2v/
|
||
├── Wan2.1-I2V-14B-720P-xxx/ # 主模型检查点
|
||
├── Wan2.1-I2V-14B-480P-xxx/ # 主模型检查点
|
||
├── loras/ # LoRA 模型
|
||
```
|
||
|
||
## 使用技巧
|
||
|
||
- 从默认设置开始，根据硬件情况调整
|
||
- 使用 TeaCache，阈值设为 0.1-0.2 可显著提速
|
||
- 在显存有限时启用内存优化
|
||
- 量化可减少内存使用但可能影响质量
|
||
- 串联多个 LoRA 实现复杂风格组合
|
||
|
||
## 故障排除
|
||
|
||
- **内存不足**：启用内存优化或使用量化
|
||
- **生成速度慢**：启用 TeaCache 或减少推理步数
|
||
- **找不到模型**：检查 `ComfyUI/models/lightx2v/` 中的模型路径
|
||
|
||
## 示例工作流
|
||
|
||
`examples/` 目录中提供了示例工作流 JSON 文件：
|
||
|
||
- `wan_i2v.json` - 基础图像生成视频
|
||
- `wan_i2v_with_distill_lora.json` - 带蒸馏 LoRA 的 I2V
|
||
- `wan_t2v_with_distill_lora.json` - 带蒸馏 LoRA 的 T2V
|
||
|
||
## 贡献指南
|
||
|
||
我们欢迎社区贡献！在提交代码之前，请确保遵循以下步骤：
|
||
|
||
### 安装开发依赖
|
||
|
||
```bash
|
||
pip install ruff pre-commit
|
||
```
|
||
|
||
### 代码质量检查
|
||
|
||
在提交代码之前，请运行以下命令：
|
||
|
||
```bash
|
||
pre-commit run --all-files
|
||
```
|
||
|
||
这将自动检查代码格式、语法错误和其他代码质量问题。
|
||
|
||
### 贡献流程
|
||
|
||
1. Fork 本仓库
|
||
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
|
||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||
5. 创建 Pull Request
|