Merge branch 'main' into audio_r2v

e08c4f90 · sandy · GitHub · 12bfd120 · 6d07a72e · e08c4f90
Commit e08c4f90 authored Jul 17, 2025 by sandy Committed by GitHub Jul 17, 2025
20 changed files
--- a/docs/PAPERS_ZH_CN/source/papers/step_distill.md
+++ b/docs/PAPERS_ZH_CN/source/papers/step_distill.md
+# 步数蒸馏
+xxx
--- a/docs/ZH_CN/source/conf.py
+++ b/docs/ZH_CN/source/conf.py
@@ -25,7 +25,7 @@ sys.path.append(os.path.abspath("../.."))
 # -- Project information -----------------------------------------------------
 project = "Lightx2v"
-copyright = "2024, Lightx2v Team"
+copyright = "2025, Lightx2v Team"
 author = "the Lightx2v Team"
 # -- General configuration ---------------------------------------------------

--- a/docs/ZH_CN/source/deploy_guides/deploy_comfyui.md
+++ b/docs/ZH_CN/source/deploy_guides/deploy_comfyui.md
-# comfyui部署
+# ComfyUI 部署
-xxx
+## ComfyUI-Lightx2vWrapper
+LightX2V 的官方 ComfyUI 集成节点已经发布在独立仓库中，提供了完整的模块化配置系统和优化功能。
+### 项目地址
+- GitHub: [https://github.com/ModelTC/ComfyUI-Lightx2vWrapper](https://github.com/ModelTC/ComfyUI-Lightx2vWrapper)
+### 主要特性
+- 模块化配置系统：为视频生成的各个方面提供独立节点
+- 支持文生视频（T2V）和图生视频（I2V）两种生成模式
+- 高级优化功能：
+  - TeaCache 加速（最高 3 倍加速）
+  - 量化支持（int8、fp8）
+  - CPU 卸载内存优化
+  - 轻量级 VAE 选项
+- LoRA 支持：可链式组合多个 LoRA 模型
+- 多模型支持：wan2.1、hunyuan 等架构
+### 安装和使用
+请访问上述 GitHub 仓库查看详细的安装说明、使用教程和示例工作流。
--- a/docs/ZH_CN/source/deploy_guides/deploy_gradio.md
+++ b/docs/ZH_CN/source/deploy_guides/deploy_gradio.md
-# gradio部署
+# Gradio 部署
-xxx
+## 📖 概述
+Lightx2v 是一个轻量级的视频推理和生成引擎，提供了基于 Gradio 的 Web 界面，支持图像到视频（Image-to-Video）和文本到视频（Text-to-Video）两种生成模式。
+本项目包含两个主要演示文件：
+- `gradio_demo.py` - 英文界面版本
+- `gradio_demo_zh.py` - 中文界面版本
+## 🚀 快速开始
+### 环境要求
+- Python 3.10+ (推荐)
+- CUDA 12.4+ (推荐)
+- 至少 8GB GPU 显存
+- 至少 16GB 系统内存（最好最少有 32G）
+- 至少 128GB SSD固态硬盘 (**💾 强烈建议使用SSD固态硬盘存储模型文件！"延迟加载"启动时，显著提升模型加载速度和推理性能**)
+### 安装依赖☀
+```bash
+# 安装基础依赖
+pip install -r requirements.txt
+pip install gradio
+```
+#### 推荐优化库配置
+- ✅ [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)
+- ✅ [q8-kernel](https://github.com/KONAKONA666/q8_kernels) (只支持ADA架构的GPU)
+### 🤖 支持的模型
+#### 🎬 图像到视频模型 (Image-to-Video)
+| 模型名称 | 分辨率 | 参数量 | 特点 | 推荐场景 |
+|----------|--------|--------|------|----------|
+| ✅ [Wan2.1-I2V-14B-480P-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-Lightx2v) | 480p | 14B | 标准版本 | 平衡速度和质量 |
+| ✅ [Wan2.1-I2V-14B-720P-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-720P-Lightx2v) | 720p | 14B | 高清版本 | 追求高质量输出 |
+| ✅ [Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v) | 480p | 14B | 蒸馏优化版 | 更快的推理速度 |
+| ✅ [Wan2.1-I2V-14B-720P-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-720P-StepDistill-CfgDistill-Lightx2v) | 720p | 14B | 高清蒸馏版 | 高质量+快速推理 |
+#### 📝 文本到视频模型 (Text-to-Video)
+| 模型名称 | 参数量 | 特点 | 推荐场景 |
+|----------|--------|------|----------|
+| ✅ [Wan2.1-T2V-1.3B-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-T2V-1.3B-Lightx2v) | 1.3B | 轻量级 | 快速原型测试 |
+| ✅ [Wan2.1-T2V-14B-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-T2V-14B-Lightx2v) | 14B | 标准版本 | 平衡速度和质量 |
+| ✅ [Wan2.1-T2V-14B-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-T2V-14B-StepDistill-CfgDistill-Lightx2v) | 14B | 蒸馏优化版 | 高质量+快速推理 |
+**💡 模型选择建议**:
+- **首次使用**: 建议选择蒸馏版本
+- **追求质量**: 选择720p分辨率或14B参数模型
+- **追求速度**: 选择480p分辨率或1.3B参数模型
+- **资源受限**: 优先选择蒸馏版本和较低分辨率
+### 启动方式
+#### 方式一：使用启动脚本（推荐）
+```bash
+# 1. 编辑启动脚本，配置相关路径
+cd app/
+vim run_gradio.sh
+# 需要修改的配置项：
+# - lightx2v_path: Lightx2v项目根目录路径
+# - i2v_model_path: 图像到视频模型路径
+# - t2v_model_path: 文本到视频模型路径
+# 💾 重要提示：建议将模型路径指向SSD存储位置
+# 例如：/mnt/ssd/models/ 或 /data/ssd/models/
+# 2. 运行启动脚本
+bash run_gradio.sh
+# 3. 或使用参数启动（推荐）
+bash run_gradio.sh --task i2v --lang zh --model_size 14b --port 8032
+# bash run_gradio.sh --task i2v --lang zh --model_size 14b --port 8032
+# bash run_gradio.sh --task i2v --lang zh --model_size 1.3b --port 8032
+```
+#### 方式二：直接命令行启动
+**图像到视频模式：**
+```bash
+python gradio_demo_zh.py \
+    --model_path /path/to/Wan2.1-I2V-14B-720P-Lightx2v \
+    --model_size 14b \
+    --task i2v \
+    --server_name 0.0.0.0 \
+    --server_port 7862
+```
+**文本到视频模式：**
+```bash
+python gradio_demo_zh.py \
+    --model_path /path/to/Wan2.1-T2V-1.3B \
+    --model_size 1.3b \
+    --task t2v \
+    --server_name 0.0.0.0 \
+    --server_port 7862
+```
+**英文界面版本：**
+```bash
+python gradio_demo.py \
+    --model_path /path/to/model \
+    --model_size 14b \
+    --task i2v \
+    --server_name 0.0.0.0 \
+    --server_port 7862
+```
+## 📋 命令行参数
+| 参数 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--model_path` | str | ✅ | - | 模型文件夹路径 |
+| `--model_cls` | str | ❌ | wan2.1 | 模型类别（目前仅支持wan2.1） |
+| `--model_size` | str | ✅ | - | 模型大小：`14b（图像到视频或者文本到视频）` 或 `1.3b（文本到视频）` |
+| `--task` | str | ✅ | - | 任务类型：`i2v`（图像到视频）或 `t2v`（文本到视频） |
+| `--server_port` | int | ❌ | 7862 | 服务器端口 |
+| `--server_name` | str | ❌ | 0.0.0.0 | 服务器IP地址 |
+## 🎯 功能特性
+### 基本设置
+#### 输入参数
+- **提示词 (Prompt)**: 描述期望的视频内容
+- **负向提示词 (Negative Prompt)**: 指定不希望出现的元素
+- **分辨率**: 支持多种预设分辨率（480p/540p/720p）
+- **随机种子**: 控制生成结果的随机性
+- **推理步数**: 影响生成质量和速度的平衡
+#### 视频参数
+- **FPS**: 每秒帧数
+- **总帧数**: 视频长度
+- **CFG缩放因子**: 控制提示词影响强度（1-10）
+- **分布偏移**: 控制生成风格偏离程度（0-10）
+### 高级优化选项
+#### GPU内存优化
+- **分块旋转位置编码**: 节省GPU内存
+- **旋转编码块大小**: 控制分块粒度
+- **清理CUDA缓存**: 及时释放GPU内存
+#### 异步卸载
+- **CPU卸载**: 将部分计算转移到CPU
+- **延迟加载**: 按需加载模型组件，显著节省系统内存消耗
+- **卸载粒度控制**: 精细控制卸载策略
+#### 低精度量化
+- **注意力算子**: Flash Attention、Sage Attention等
+- **量化算子**: vLLM、SGL、Q8F等
+- **精度模式**: FP8、INT8、BF16等
+#### VAE优化
+- **轻量级VAE**: 加速解码过程
+- **VAE分块推理**: 减少内存占用
+#### 特征缓存
+- **Tea Cache**: 缓存中间特征加速生成
+- **缓存阈值**: 控制缓存触发条件
+- **关键步缓存**: 仅在关键步骤写入缓存
+## 🔧 自动配置功能
+启用"自动配置推理选项"后，系统会根据您的硬件配置自动优化参数：
+### GPU内存规则
+- **80GB+**: 默认配置，无需优化
+- **48GB**: 启用CPU卸载，卸载比例50%
+- **40GB**: 启用CPU卸载，卸载比例80%
+- **32GB**: 启用CPU卸载，卸载比例100%
+- **24GB**: 启用BF16精度、VAE分块
+- **16GB**: 启用分块卸载、旋转编码分块
+- **12GB**: 启用清理缓存、轻量级VAE
+- **8GB**: 启用量化、延迟加载
+### CPU内存规则
+- **128GB+**: 默认配置
+- **64GB**: 启用DIT量化
+- **32GB**: 启用延迟加载
+- **16GB**: 启用全模型量化
+## ⚠️ 重要注意事项
+### 🚀 低资源设备优化建议
+**💡 针对显存不足或性能受限的设备**:
+- **🎯 模型选择**: 优先使用蒸馏版本模型 (StepDistill-CfgDistill)
+- **⚡ 推理步数**: 建议设置为 4 步
+- **🔧 CFG设置**: 建议关闭CFG选项以提升生成速度
+- **🔄 自动配置**: 启用"自动配置推理选项"
+## 📁 文件结构
+```
+lightx2v/app/
+├── gradio_demo.py          # 英文界面演示
+├── gradio_demo_zh.py       # 中文界面演示
+├── run_gradio.sh          # 启动脚本
+├── README.md              # 说明文档
+├── saved_videos/          # 生成视频保存目录
+└── inference_logs.log     # 推理日志
+```
+## 🎨 界面说明
+### 基本设置标签页
+- **输入参数**: 提示词、分辨率等基本设置
+- **视频参数**: FPS、帧数、CFG等视频生成参数
+- **输出设置**: 视频保存路径配置
+### 高级选项标签页
+- **GPU内存优化**: 内存管理相关选项
+- **异步卸载**: CPU卸载和延迟加载
+- **低精度量化**: 各种量化优化选项
+- **VAE优化**: 变分自编码器优化
+- **特征缓存**: 缓存策略配置
+## 🔍 故障排除
+### 常见问题
+**💡 提示**: 一般情况下，启用"自动配置推理选项"后，系统会根据您的硬件配置自动优化参数设置，通常不会出现性能问题。如果遇到问题，请参考以下解决方案：
+1. **CUDA内存不足**
+   - 启用CPU卸载
+   - 降低分辨率
+   - 启用量化选项
+1. **系統内存不足**
+   - 启用CPU卸载
+   - 启用延迟加载选项
+   - 启用量化选项
+2. **生成速度慢**
+   - 减少推理步数
+   - 启用自动配置
+   - 使用轻量级模型
+   - 启用Tea Cache
+   - 使用量化算子
+   - 💾 **检查模型是否存放在SSD上**
+3. **模型加载缓慢**
+   - 💾 **将模型迁移到SSD存储**
+   - 启用延迟加载选项
+   - 检查磁盘I/O性能
+   - 考虑使用NVMe SSD
+4. **视频质量不佳**
+   - 增加推理步数
+   - 提高CFG缩放因子
+   - 使用14B模型
+   - 优化提示词
+### 日志查看
+```bash
+# 查看推理日志
+tail -f inference_logs.log
+# 查看GPU使用情况
+nvidia-smi
+# 查看系统资源
+htop
+```
+欢迎提交Issue和Pull Request来改进这个项目！
+**注意**: 使用本工具生成的视频内容请遵守相关法律法规，不得用于非法用途。
--- a/docs/ZH_CN/source/deploy_guides/deploy_local_windows.md
+++ b/docs/ZH_CN/source/deploy_guides/deploy_local_windows.md
-# 本地windows电脑部署
+# 本地Windows电脑部署指南
-xxx
+本文档将详细指导您在Windows环境下完成LightX2V的本地部署配置。
+## 系统要求
+在开始之前，请确保您的系统满足以下要求：
+- **操作系统**: Windows 10/11
+- **显卡**: NVIDIA GPU（支持CUDA）
+- **显存**: 至少8GB显存
+- **内存**: 至少16GB内存
+- **存储空间**: 20GB以上可用硬盘空间
+- **环境管理**: 已安装Anaconda或Miniconda
+- **网络工具**: Git（用于克隆代码仓库）
+## 部署步骤
+### 步骤1：检查CUDA版本
+首先确认您的GPU驱动和CUDA版本，在命令提示符中运行：
+```bash
+nvidia-smi
+```
+记录输出中显示的**CUDA Version**信息，后续安装时需要保持版本一致。
+### 步骤2：创建Python环境
+创建一个独立的conda环境，推荐使用Python 3.12：
+```bash
+# 创建新环境（以Python 3.12为例）
+conda create -n lightx2v python=3.12 -y
+# 激活环境
+conda activate lightx2v
+```
+> 💡 **提示**: 建议使用Python 3.10或更高版本以获得最佳兼容性。
+### 步骤3：安装PyTorch框架
+#### 方法一：下载官方wheel包安装（推荐）
+1. 访问 [PyTorch官方wheel包下载页面](https://download.pytorch.org/whl/torch/)
+2. 选择对应版本的wheel包，注意匹配：
+   - **Python版本**: 与您的环境一致（cp312表示Python 3.12）
+   - **CUDA版本**: 与您的GPU驱动匹配
+   - **平台**: 选择Windows版本（win_amd64）
+**以Python 3.12 + PyTorch 2.6 + CUDA 12.4为例：**
+```
+torch-2.6.0+cu124-cp312-cp312-win_amd64.whl
+```
+下载完成后进行安装：
+```bash
+# 安装PyTorch（请替换为实际的文件路径）
+pip install torch-2.6.0+cu124-cp312-cp312-win_amd64.whl
+# 安装配套的vision和audio包
+pip install torchvision==0.21.0 torchaudio==2.6.0
+```
+#### 方法二：使用pip直接安装
+如果您偏好直接安装，可以使用以下命令：
+```bash
+# 示例：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版本匹配（如cp312）
+- PyTorch版本匹配
+- CUDA版本匹配
+**推荐安装v0.9.1版本：**
+```bash
+pip install vllm-0.9.1+cu124-cp312-cp312-win_amd64.whl
+```
+> ⚠️ **注意**: 请根据您的具体环境选择对应的wheel包文件名。
+### 步骤5：安装注意力机制算子
+您可以选择安装Flash Attention 2或SageAttention 2，**强烈推荐SageAttention 2**。
+#### 选项A：Flash Attention 2
+```bash
+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)
+**版本选择要点：**
+- Python版本必须匹配
+- PyTorch版本必须匹配
+- **CUDA版本可以不严格对齐**（SageAttention暂未使用破坏性API）
+**推荐安装版本：**
+```bash
+pip install sageattention-2.1.1+cu126torch2.6.0-cp312-cp312-win_amd64.whl
+```
+**验证SageAttention安装：**
+> 📝 **测试**: 您也可以运行[测试脚本](https://github.com/woct0rdho/SageAttention/blob/main/tests/test_sageattn.py)进行更详细的功能验证。
+### 步骤6：获取LightX2V项目代码
+从GitHub克隆LightX2V项目并安装Windows专用依赖：
+```bash
+# 克隆项目代码
+git clone https://github.com/ModelTC/LightX2V.git
+# 进入项目目录
+cd LightX2V
+# 安装Windows专用依赖包
+pip install -r requirements_win.txt
+```
+> 🔍 **说明**: 这里使用`requirements_win.txt`而不是标准的`requirements.txt`，因为Windows环境可能需要特定的包版本或额外的依赖。
+## 故障排除
+### 1. CUDA版本不匹配
+**问题现象**: 出现CUDA相关错误
+**解决方案**:
+- 确认GPU驱动支持所需CUDA版本
+- 重新下载匹配的wheel包
+- 可以通过`nvidia-smi`查看支持的最高CUDA版本
+### 2. 依赖冲突
+**问题现象**: 包版本冲突或导入错误
+**解决方案**:
+- 删除现有环境: `conda env remove -n lightx2v`
+- 重新创建环境并严格按版本要求安装
+- 使用虚拟环境隔离不同项目的依赖
+### 3. wheel包下载问题
+**问题现象**: 下载速度慢或失败
+**解决方案**:
+- 使用下载工具或浏览器直接下载
+- 寻找国内镜像源
+- 检查网络连接和防火墙设置
+## 下一步操作
+环境配置完成后，您可以：
+- 📚 查看[快速开始指南](../getting_started/quickstart.md)（跳过环境安装步骤）
+- 🌐 使用[Gradio Web界面](./deploy_gradio.md)进行可视化操作（跳过环境安装步骤）
+## 版本兼容性参考
+| 组件 | 推荐版本 |
+|------|----------|
+| Python | 3.12 |
+| PyTorch | 2.6.0+cu124 |
+| vLLM | 0.9.1+cu124 |
+| SageAttention | 2.1.1+cu126torch2.6.0 |
+| CUDA | 12.4+ |
+---
+💡 **小贴士**: 如果遇到其他问题，建议先检查各组件版本是否匹配，大部分问题都源于版本不兼容。
--- a/docs/ZH_CN/source/deploy_guides/for_low_resource.md
+++ b/docs/ZH_CN/source/deploy_guides/for_low_resource.md
-# 低资源场景部署
+# Lightx2v 低资源部署指南
-xxx
+## 📋 概述
+本指南专门针对硬件资源受限的环境，特别是**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](https://github.com/madebyollin/taehv/blob/main/taew2_1.pth)
+```python
+# VAE优化配置
+use_tiny_vae = True            # 使用轻量级VAE
+```
+**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到项目仓库。
--- a/docs/ZH_CN/source/deploy_guides/lora_deploy.md
+++ b/docs/ZH_CN/source/deploy_guides/lora_deploy.md
-# Lora模型部署
+# LoRA 模型部署与相关工具
-xxx
+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
+```
--- a/docs/ZH_CN/source/deploy_guides/model_structure.md
+++ b/docs/ZH_CN/source/deploy_guides/model_structure.md
+# 模型结构介绍
+## 📖 概述
+本文档介绍 Lightx2v 项目的模型目录结构，帮助用户正确组织模型文件，实现便捷的使用体验。通过合理的目录组织，用户可以享受到"一键启动"的便利，无需手动配置复杂的路径参数。
+## 🗂️ 模型目录结构
+### Lightx2v官方模型列表
+查看所有可用模型：[Lightx2v官方模型仓库](https://huggingface.co/lightx2v)
+### 标准目录结构
+以 `Wan2.1-I2V-14B-480P-Lightx2v` 为例：
+```
+模型根目录/
+├── Wan2.1-I2V-14B-480P-Lightx2v/
+│   ├── config.json                                    # 模型配置文件
+│   ├── Wan2.1_VAE.pth                                # VAE变分自编码器
+│   ├── models_clip_open-clip-xlm-roberta-large-vit-huge-14.pth  # CLIP视觉编码器 (FP16)
+│   ├── models_t5_umt5-xxl-enc-bf16.pth               # T5文本编码器 (BF16)
+│   ├── taew2_1.pth                                   # 轻量级VAE (可选)
+│   ├── fp8/                                          # FP8量化版本 (DIT/T5/CLIP)
+│   ├── int8/                                         # INT8量化版本 (DIT/T5/CLIP)
+│   ├── original/                                     # 原始精度版本 (DIT)
+│   ├── xlm-roberta-large/
+│   └── google/
+```
+### 💾 存储建议
+**强烈建议将模型文件存储在SSD固态硬盘上**，可以显著提升模型加载速度和推理性能。
+**推荐存储路径**：
+```bash
+/mnt/ssd/models/          # 独立SSD挂载点
+/data/ssd/models/         # 数据SSD目录
+/opt/models/              # 系统优化目录
+```
+## 🔧 模型文件说明
+### 量化版本目录
+每个模型都包含多个量化版本，用于不同硬件配置：
+```
+模型目录/
+├── fp8/                         # FP8量化版本 (H100/A100等高端GPU)
+├── int8/                        # INT8量化版本 (通用GPU)
+└── original/                    # 原始精度版本 (DIT)
+```
+**💡 使用全精度模型**：如需使用全精度模型，只需将官方权重文件复制到 `original/` 目录即可。
+## 🚀 使用方法
+### Gradio界面启动
+使用Gradio界面时，只需指定模型根目录路径：
+```bash
+# 图像到视频 (I2V)
+python gradio_demo_zh.py \
+    --model_path /path/to/Wan2.1-I2V-14B-480P-Lightx2v \
+    --model_size 14b \
+    --task i2v
+# 文本到视频 (T2V)
+python gradio_demo_zh.py \
+    --model_path /path/to/models/Wan2.1-T2V-14B-Lightx2v \
+    --model_size 14b \
+    --task t2v
+```
+### 配置文件启动
+使用配置文件启动时, 如[配置文件](https://github.com/ModelTC/LightX2V/tree/main/configs/offload/disk/wan_i2v_phase_lazy_load_480p.json)中的以下路径配置可以省略：
+- `dit_quantized_ckpt` 无需指定，代码会自动在模型目录下查找
+- `tiny_vae_path`：无需指定，代码会自动在模型目录下查找
+- `clip_quantized_ckpt`：无需指定，代码会自动在模型目录下查找
+- `t5_quantized_ckpt`：无需指定，代码会自动在模型目录下查找
+**💡 简化配置**：按照推荐的目录结构组织模型文件后，大部分路径配置都可以省略，代码会自动处理。
+### 手动下载
+1. 访问 [Hugging Face模型页面](https://huggingface.co/lightx2v)
+2. 选择需要的模型版本
+3. 下载所有文件到对应目录
+**💡 下载建议**：建议使用SSD存储，并确保网络连接稳定。对于大文件，可使用 `git lfs` 或下载工具如 `aria2c`。
+## 💡 最佳实践
+- **使用SSD存储**：显著提升模型加载速度和推理性能
+- **统一目录结构**：便于管理和切换不同模型版本
+- **预留足够空间**：确保有足够的存储空间（建议至少200GB）
+- **定期清理**：删除不需要的模型版本以节省空间
+- **网络优化**：使用稳定的网络连接和下载工具
+## 🚨 常见问题
+### Q: 模型文件太大，下载很慢怎么办？
+A: 使用国内镜像源、下载工具如 `aria2c`，或考虑使用云存储服务
+### Q: 启动时提示模型路径不存在？
+A: 检查模型是否已正确下载，验证路径配置是否正确
+### Q: 如何切换不同的模型版本？
+A: 修改启动命令中的模型路径参数，支持同时运行多个模型实例
+### Q: 模型加载速度很慢？
+A: 确保模型存储在SSD上，启用延迟加载功能，使用量化版本模型
+### Q: 配置文件中的路径如何设置？
+A: 按照推荐目录结构组织后，大部分路径配置可省略，代码会自动处理
+## 📚 相关链接
+- [Lightx2v官方模型仓库](https://huggingface.co/lightx2v)
+- [Gradio部署指南](./deploy_gradio.md)
+---
+通过合理的模型文件组织，用户可以享受到"一键启动"的便捷体验，无需手动配置复杂的路径参数。建议按照本文档的推荐结构组织模型文件，并充分利用SSD存储的优势。
--- a/docs/ZH_CN/source/getting_started/benchmark.md
+++ b/docs/ZH_CN/source/getting_started/benchmark.md
+# 基准测试
+由于要展示一些视频的播放效果和详细的性能对比，您可以在这个[🔗 页面](https://github.com/ModelTC/LightX2V/blob/main/docs/ZH_CN/source/getting_started/benchmark_source.md)获得更好的展示效果以及相对应的文档内容。
--- a/docs/ZH_CN/source/getting_started/benchmark_source.md
+++ b/docs/ZH_CN/source/getting_started/benchmark_source.md
+# 基准测试
+---
+## 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) | 推理时间(s) | GPU显存占用(GB) | 加速比 | 视频效果 |
+|:-----|:---------------:|:----------:|:---------------:|:------:|:--------:|
+| **Wan2.1 Official** | 68.26 | 366.04 | 71 | 1.0x | <video src="https://github.com/user-attachments/assets/24fb112e-c868-4484-b7f0-d9542979c2c3" width="200px"></video> |
+| **Fast Video** | xx | xx | xx | **xx** | <video src="" width="200px"></video> |
+| **LightX2V_1** | 37.28 | 249.54 | 53 | **1.47x** | <video src="https://github.com/user-attachments/assets/7bffe48f-e433-430b-91dc-ac745908ba3a" width="200px"></video> |
+| **LightX2V_2** | 37.24 | 216.16 | 50 | **1.69x** | <video src="https://github.com/user-attachments/assets/0a24ca47-c466-433e-8a53-96f259d19841" width="200px"></video> |
+| **LightX2V_3** | 23.62 | 190.73 | 35 | **1.92x** | <video src="https://github.com/user-attachments/assets/970c73d3-1d60-444e-b64d-9bf8af9b19f1" width="200px"></video> |
+| **LightX2V_4** | 23.62 | 107.19 | 35 | **3.41x** | <video src="https://github.com/user-attachments/assets/49cd2760-4be2-432c-bf4e-01af9a1303dd" width="200px"></video> |
+| **LightX2V_4-Distill** | xxx| xxx | xx | **xx** | <video src="" 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=42, enable_cfg=True
+*即将更新...*
+---
+## RTX 4090 (~24GB显存)
+### 480P 5s视频
+*即将更新...*
+### 720P 5s视频
+*即将更新...*
+---
+## 表格说明
+- **Wan2.1 Official**: 基于[Wan2.1官方仓库](https://github.com/Wan-Video/Wan2.1)
+- **FastVideo**: 基于[FastVideo官方仓库](https://github.com/hao-ai-lab/FastVideo)
+- **LightX2V_1**: 使用SageAttention2替换原生注意力机制，采用DIT BF16+FP32(部分敏感层)混合精度计算，在保持精度的同时提升计算效率
+- **LightX2V_2**: 统一使用BF16精度计算，进一步减少显存占用和计算开销，同时保持生成质量
+- **LightX2V_3**: 引入FP8量化技术显著减少计算精度要求，结合Tiling VAE技术优化显存使用
+- **LightX2V_4**: 在LightX2V_3基础上加入TeaCache(teacache_thresh=0.2)缓存复用技术，通过智能跳过冗余计算实现加速
+- **LightX2V_4-Distill**: 在LightX2V_4基础上使用4步蒸馏模型([Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v](https://huggingface.co/lightx2v/Wan2.1-I2V-14B-480P-StepDistill-CfgDistill-Lightx2v))
--- a/docs/ZH_CN/source/getting_started/quickstart.md
+++ b/docs/ZH_CN/source/getting_started/quickstart.md
@@ -25,9 +25,8 @@ git clone https://github.com/ModelTC/lightx2v.git lightx2v && cd lightx2v
 conda create -n lightx2v python=3.11 && conda activate lightx2v
 pip install -r requirements.txt
-# 单独重新安装transformers，避免pip的冲突检查
 # 混元模型需要在4.45.2版本的transformers下运行，如果不需要跑混元模型，可以忽略
-pip install transformers==4.45.2
+# pip install transformers==4.45.2
 # 安装 flash-attention 2
 git clone https://github.com/Dao-AILab/flash-attention.git --recursive
@@ -41,7 +40,7 @@ cd flash-attention/hopper && python setup.py install
 ```shell
 # 修改脚本中的路径
-bash scripts/run_wan_t2v.sh
+bash scripts/wan/run_wan_t2v.sh
 ```
-除了脚本中已有的输入参数，`--config_json`指向的`${lightx2v_path}/configs/wan_t2v.json`中也会存在一些必要的参数，可以根据需要，自行修改。
+除了脚本中已有的输入参数，`--config_json`指向的`wan_t2v.json`中也会存在一些必要的参数，可以根据需要，自行修改。
--- a/docs/ZH_CN/source/index.rst
+++ b/docs/ZH_CN/source/index.rst
@@ -2,17 +2,33 @@
 ==================
 .. figure:: ../../../assets/img_lightx2v.png
-  :width: 100%
+  :width: 80%
  :align: center
  :alt: Lightx2v
  :class: no-scaled-link
 .. raw:: html
-   <p style="text-align:center">
+    <div align="center" style="font-family: charter;">
-   <strong>一个轻量级的视频生成推理框架
-   </strong>
+    <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
 文档列表
 -------------
@@ -22,6 +38,7 @@
   :caption: 快速入门
   快速入门 <getting_started/quickstart.md>
+   基准测试 <getting_started/benchmark.md>
 .. toctree::
   :maxdepth: 1
@@ -32,6 +49,7 @@
   注意力机制 <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>
@@ -39,17 +57,11 @@
   :maxdepth: 1
   :caption: 部署指南
+   模型结构 <deploy_guides/model_structure.md>
   低延迟场景部署 <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>
+   Gradio部署 <deploy_guides/deploy_gradio.md>
-   comfyui部署 <deploy_guides/deploy_comfyui.md>
+   ComfyUI部署 <deploy_guides/deploy_comfyui.md>
   本地windows电脑部署 <deploy_guides/deploy_local_windows.md>
-.. Indices and tables
-.. ==================
-.. * :ref:`genindex`
-.. * :ref:`modindex`
--- a/docs/ZH_CN/source/method_tutorials/attention.md
+++ b/docs/ZH_CN/source/method_tutorials/attention.md
-# 🎯 DiT 模型中的注意力类型配置说明
+# 注意力机制
-当前 DiT 模型在 `LightX2V` 中三个地方使用到了注意力，每个注意力可以分别配置底层注意力库类型。
+## LightX2V支持的注意力机制
---
-## 使用注意力的位置
-1. **图像的自注意力（Self-Attention）**
-   - 配置参数：`self_attn_1_type`
-2. **图像与提示词（Text）之间的交叉注意力（Cross-Attention）**
-   - 配置参数：`cross_attn_1_type`
-3. **I2V 模式下图像与参考图（Reference）之间的交叉注意力**
-   - 配置参数：`cross_attn_2_type`
---
-## 🚀 支持的注意力库（Backend）
 | 名称               | 类型名称         | GitHub 链接 |
 |--------------------|------------------|-------------|
@@ -29,9 +12,13 @@
 ---
-## 🛠️ 配置示例
+## 配置示例
-在 `wan_i2v.json` 配置文件中，可以通过如下方式指定使用的注意力类型：
+注意力机制的config文件在[这里](https://github.com/ModelTC/lightx2v/tree/main/configs/attentions)
+通过指定--config_json到具体的config文件，即可以测试不同的注意力机制
+比如对于radial_attn，配置如下：
 ```json
 {
@@ -45,22 +32,4 @@
 tips: radial_attn因为稀疏算法原理的限制只能用在self attention
---
-对于 Sparge Attention 配置参考 `wan_t2v_sparge.json` 文件:
-    Sparge Attention是需要后一个训练的权重
-```json
-{
-  "self_attn_1_type": "flash_attn3",
-  "cross_attn_1_type": "flash_attn3",
-  "cross_attn_2_type": "flash_attn3"
-  "sparge": true,
-  "sparge_ckpt": "/path/to/sparge_wan2.1_t2v_1.3B.pt"
-}
-```
---
 如需进一步定制注意力机制的行为，请参考各注意力库的官方文档或实现代码。
--- a/docs/ZH_CN/source/method_tutorials/autoregressive_distill.md
+++ b/docs/ZH_CN/source/method_tutorials/autoregressive_distill.md
 # 自回归蒸馏
-xxx
+自回归蒸馏是 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
+```
--- a/docs/ZH_CN/source/method_tutorials/cache.md
+++ b/docs/ZH_CN/source/method_tutorials/cache.md
 # 特征缓存
-## 缓存加速算法
+由于要展示一些视频的播放效果，你可以在这个[🔗 页面](https://github.com/ModelTC/LightX2V/blob/main/docs/ZH_CN/source/method_tutorials/cache_source.md)获得更好的展示效果以及相对应的文档内容。
- 在扩散模型的推理过程中，缓存复用是一种重要的加速算法。
- 其核心思想是在部分时间步跳过冗余计算，通过复用历史缓存结果提升推理效率。
- 算法的关键在于如何决策在哪些时间步进行缓存复用，通常基于模型状态变化或误差阈值动态判断。
- 在推理过程中，需要缓存如中间特征、残差、注意力输出等关键内容。当进入可复用时间步时，直接利用已缓存的内容，通过泰勒展开等近似方法重构当前输出，从而减少重复计算，实现高效推理。
-## TeaCache
-`TeaCache`的核心思想是通过对相邻时间步输入的**相对L1**距离进行累加，当累计距离达到设定阈值时，判定当前时间步可以进行缓存复用。
- 具体来说，算法在每一步推理时计算当前输入与上一步输入的相对L1距离，并将其累加。
- 当累计距离超过阈值，说明模型状态发生了足够的变化，则直接复用最近一次缓存的内容，跳过部分冗余计算。这样可以显著减少模型的前向计算次数，提高推理速度。
-实际效果上，TeaCache 在保证生成质量的前提下，实现了明显的加速。加速前后的视频对比如下：  
-| 加速前 | 加速后 |
-|:------:|:------:|
-| 单卡H200推理耗时：58s | 单卡H200推理耗时：17.9s |
-| ![加速前效果](../../../../assets/gifs/1.gif) | ![加速后效果](../../../../assets/gifs/2.gif) |
- 加速比为：**3.24**
- 参考论文：[https://arxiv.org/abs/2411.19108](https://arxiv.org/abs/2411.19108)
-## TaylorSeer Cache
-`TaylorSeer Cache`的核心在于利用泰勒公式对缓存内容进行再次计算，作为缓存复用时间步的残差补偿。具体做法是在缓存复用的时间步，不仅简单地复用历史缓存，还通过泰勒展开对当前输出进行近似重构。这样可以在减少计算量的同时，进一步提升输出的准确性。泰勒展开能够有效捕捉模型状态的微小变化，使得缓存复用带来的误差得到补偿，从而在加速的同时保证生成质量。`TaylorSeer Cache`适用于对输出精度要求较高的场景，能够在缓存复用的基础上进一步提升模型推理的表现。
-| 加速前 | 加速后 |
-|:------:|:------:|
-| 单卡H200推理耗时：57.7s | 单卡H200推理耗时：41.3s |
-| ![加速前效果](../../../../assets/gifs/3.gif) | ![加速后效果](../../../../assets/gifs/4.gif) |
- 加速比为：**1.39**
- 参考论文：[https://arxiv.org/abs/2503.06923](https://arxiv.org/abs/2503.06923)
-## AdaCache
-`AdaCache`的核心思想是根据指定block块中的部分缓存内容，动态调整缓存复用的步长。
- 算法会分析相邻两个时间步在特定 block 内的特征差异，根据差异大小自适应地决定下一个缓存复用的时间步间隔。
- 当模型状态变化较小时，步长自动加大，减少缓存更新频率；当状态变化较大时，步长缩小，保证输出质量。
-这样可以根据实际推理过程中的动态变化，灵活调整缓存策略，实现更高效的加速和更优的生成效果。AdaCache 适合对推理速度和生成质量都有较高要求的应用场景。
-| 加速前 | 加速后 |
-|:------:|:------:|
-| 单卡H200推理耗时：227s | 单卡H200推理耗时：83s |
-| ![加速前效果](../../../../assets/gifs/5.gif) | ![加速后效果](../../../../assets/gifs/6.gif) |
- 加速比为：**2.73**
- 参考论文：[https://arxiv.org/abs/2411.02397](https://arxiv.org/abs/2411.02397)
-## CustomCache
-`CustomCache`综合了`TeaCache`和`TaylorSeer Cache`的优势。
- 它结合了`TeaCache`在缓存决策上的实时性和合理性，通过动态阈值判断何时进行缓存复用.
- 同时利用`TaylorSeer`的泰勒展开方法对已缓存内容进行利用。
-这样不仅能够高效地决定缓存复用的时机，还能最大程度地利用缓存内容，提升输出的准确性和生成质量。实际测试表明，`CustomCache`在多个内容生成任务上，生成的视频质量优于单独使用`TeaCache、TaylorSeer Cache`或`AdaCache`的方案，是目前综合性能最优的缓存加速算法之一。
-| 加速前 | 加速后 |
-|:------:|:------:|
-| 单卡H200推理耗时：57.9s | 单卡H200推理耗时：16.6s |
-| ![加速前效果](../../../../assets/gifs/7.gif) | ![加速后效果](../../../../assets/gifs/8.gif) |
- 加速比为：**3.49**
--- a/docs/ZH_CN/source/method_tutorials/cache_source.md
+++ b/docs/ZH_CN/source/method_tutorials/cache_source.md
+# 特征缓存
+## 缓存加速算法
+- 在扩散模型的推理过程中，缓存复用是一种重要的加速算法。
+- 其核心思想是在部分时间步跳过冗余计算，通过复用历史缓存结果提升推理效率。
+- 算法的关键在于如何决策在哪些时间步进行缓存复用，通常基于模型状态变化或误差阈值动态判断。
+- 在推理过程中，需要缓存如中间特征、残差、注意力输出等关键内容。当进入可复用时间步时，直接利用已缓存的内容，通过泰勒展开等近似方法重构当前输出，从而减少重复计算，实现高效推理。
+### 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)有一些运行脚本供使用。
--- a/docs/ZH_CN/source/method_tutorials/changing_resolution.md
+++ b/docs/ZH_CN/source/method_tutorials/changing_resolution.md
+# 变分辨率推理
+## 概述
+变分辨率推理是一种优化去噪过程的技术策略，通过在不同的去噪阶段采用不同的分辨率来提升计算效率并保持生成质量。该方法的核心思想是：在去噪过程的前期使用较低分辨率进行粗略去噪，在后期切换到正常分辨率进行精细化处理。
+## 技术原理
+### 分阶段去噪策略
+变分辨率推理基于以下观察：
+- **前期去噪**：主要处理粗糙的噪声和整体结构，不需要过多的细节信息
+- **后期去噪**：专注于细节优化和高频信息恢复，需要完整的分辨率信息
+### 分辨率切换机制
+1. **低分辨率阶段**（前期）
+   - 将输入降采样到较低分辨率（如原尺寸的0.75）
+   - 执行初始的去噪步骤
+   - 快速移除大部分噪声，建立基本结构
+2. **正常分辨率阶段**（后期）
+   - 将第一步的去噪结果上采样回原始分辨率
+   - 继续执行剩余的去噪步骤
+   - 恢复细节信息，完成精细化处理
+## 使用方式
+变分辨率推理的config文件在[这里](https://github.com/ModelTC/LightX2V/tree/main/configs/changing_resolution)
+通过指定--config_json到具体的config文件，即可以测试变分辨率推理。
+可以参考[该脚本](https://github.com/ModelTC/LightX2V/blob/main/scripts/wan/run_wan_t2v_changing_resolution.sh)。
--- a/docs/ZH_CN/source/method_tutorials/offload.md
+++ b/docs/ZH_CN/source/method_tutorials/offload.md
 # 参数卸载
-xxx
+## 📖 概述
+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,        # 启用磁盘卸载
+    "offload_path": ".",            # 磁盘卸载路径
+}
+```
+**智能缓存关键参数：**
+- `max_memory`：控制CPU缓存大小，影响缓存命中率和内存使用
+- `num_disk_workers`：控制磁盘加载线程数，影响预取速度
+- `offload_granularity`：控制缓存粒度（block或phase），影响缓存效率
+  - `"block"`：以完整的Transformer层为单位进行缓存管理
+  - `"phase"`：以单个计算组件为单位进行缓存管理
+详细配置文件可参考[config](https://github.com/ModelTC/lightx2v/tree/main/configs/offload)
+## 🎯 使用建议
+- 🔄 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设计，充分利用了现代硬件的异步计算能力，能够显著降低大模型推理的硬件门槛。
--- a/docs/ZH_CN/source/method_tutorials/parallel.md
+++ b/docs/ZH_CN/source/method_tutorials/parallel.md
 # 并行推理
-xxx
+LightX2V 支持分布式并行推理，能够利用多个 GPU 进行推理。DiT部分支持两种并行注意力机制：**Ulysses** 和 **Ring**，同时还支持 **VAE 并行推理**。并行推理，显著降低推理耗时和减轻每个GPU的显存开销。
+## DiT 并行配置
+DiT 并行是通过 `parallel_attn_type` 参数控制的,支持两种并行注意力机制：
+### 1. Ulysses 并行
+**配置方式：**
+```json
+{
+    "parallel_attn_type": "ulysses"
+}
+```
+### 2. Ring 并行
+**配置方式：**
+```json
+{
+    "parallel_attn_type": "ring"
+}
+```
+## VAE 并行配置
+VAE 并行是通过 `parallel_vae` 参数控制：
+```json
+{
+    "parallel_vae": true
+}
+```
+**配置说明：**
+- `parallel_vae: true`：启用 VAE 并行推理（推荐设置）
+- `parallel_vae: false`：禁用 VAE 并行，使用单 GPU 处理
+**使用建议：**
+- 在多 GPU 环境下，建议始终启用 VAE 并行
+- VAE 并行可与任何注意力并行方式（Ulysses/Ring）组合使用
+- 对于内存受限的场景，VAE 并行可显著减少内存使用
+## 使用方式
+并行推理的config文件在[这里](https://github.com/ModelTC/lightx2v/tree/main/configs/dist_infer)
+通过指定--config_json到具体的config文件，即可以测试并行推理
+[这里](https://github.com/ModelTC/lightx2v/tree/main/scripts/dist_infer)有一些运行脚本供使用。
--- a/docs/ZH_CN/source/method_tutorials/quantization.md
+++ b/docs/ZH_CN/source/method_tutorials/quantization.md
 # 模型量化
-lightx2v支持对`Dit`中的线性层进行量化推理，支持`w8a8-int8`和`w8a8-fp8`的矩阵乘法。
+lightx2v支持对`Dit`中的线性层进行量化推理，支持`w8a8-int8`, `w8a8-fp8`, `w8a8-fp8block`, `w8a8-mxfp8` 和 `w4a4-nvfp4`的矩阵乘法。
 ## 生产量化模型
-### 自动量化
+使用LightX2V的convert工具，将模型转换成量化模型，参考[文档](https://github.com/ModelTC/lightx2v/tree/main/tools/convert/readme_zh.md)。
-lightx2v支持推理时自动对模型权重进行量化，具体可参考[配置文件](https://github.com/ModelTC/lightx2v/tree/main/configs/quantization/wan_i2v_quant_auto.json)。
+## 加载量化模型进行推理
-值得注意的是，需要将配置文件的**mm_config**进行设置：**"mm_config": {"mm_type": "W-int8-channel-sym-A-int8-channel-sym-dynamic-Vllm","weight_auto_quant": true }**， **mm_type**代表希望使用的量化算子，**weight_auto_quant：true**代表自动转量化模型。
+将转换后的量化权重的路径，写到[配置文件](https://github.com/ModelTC/lightx2v/blob/main/configs/quantization)中的`dit_quantized_ckpt`中。
-### 离线量化
+通过指定--config_json到具体的config文件，即可以加载量化模型进行推理
-lightx2v同时支持直接加载量化好的权重进行推理，对模型进行离线量化可参考[文档](https://github.com/ModelTC/lightx2v/tree/main/tools/convert/readme_zh.md)。
+[这里](https://github.com/ModelTC/lightx2v/tree/main/scripts/quantization)有一些运行脚本供使用。
-将转换的权重路径，写到[配置文件](https://github.com/ModelTC/lightx2v/tree/main/configs/quantization/wan_i2v_quant_offline.json)中的`dit_quantized_ckpt`中，同时`mm_type**中的**weight_auto_quant`置为`false`即可。
-## 量化推理
-### 自动量化
-```shell
-bash scripts/run_wan_i2v_quant_auto.sh
-```
-### 离线量化
-```shell
-bash scripts/run_wan_i2v_quant_offline.sh
-```
-## 启动量化服务
-建议离线转好量化权重之后，`--config_json`指向到离线量化的`json`文件
-比如，将`scripts/start_server.sh`脚本进行如下改动：
-```shell
-export RUNNING_FLAG=infer
-python -m lightx2v.api_server \
--model_cls wan2.1 \
--task t2v \
--model_path $model_path \
--config_json ${lightx2v_path}/configs/quantization/wan_i2v_quant_offline.json \
--port 8000
-```
 ## 高阶量化功能