TurboDiffusion 环境部署与 WebUI 配置指南
1. 快速开始
1.1 环境准备与启动流程
TurboDiffusion 是由清华大学、生数科技和加州大学伯克利分校联合推出的视频生成加速框架，基于 Wan2.1 和 Wan2.2 模型进行二次开发，集成 SageAttention、SLA（稀疏线性注意力）和 rCM（时间步蒸馏）等核心技术，将视频生成速度提升 100~200 倍。在单张 RTX 5090 显卡上，原本耗时 184 秒的生成任务可缩短至仅 1.9 秒。
本镜像已预装完整环境，所有模型均已离线下载并配置完毕，实现开机即用，无需额外安装依赖或下载权重。
- 启动方式：
- 登录系统后，直接点击桌面快捷方式或控制面板中的【打开 WebUI】即可进入使用界面；
- 若出现卡顿，可点击【重启应用】释放资源，等待服务重新启动后再访问；
- 如需查看生成进度或调试信息，可通过【后台查看】功能实时监控日志输出。
提示：控制面板位于系统界面中，请确保正确登录账户后操作。
2. T2V 文本生成视频
2.1 基础使用流程
T2V（Text-to-Video）功能支持从自然语言描述生成高质量动态视频内容，适用于创意设计、广告制作、影视预演等场景。
步骤说明：
- 选择模型
Wan2.1-1.3B：轻量级模型，显存需求约 12GB，适合快速迭代与测试。Wan2.1-14B：大型模型，显存需求约 40GB，生成质量更高，适合最终输出。
- 输入提示词（Prompt） 提供具体、生动的描述有助于提升生成效果。推荐包含主体、动作、环境、光线和风格五个要素。
- 示例：一位时尚的女性走在东京街头，街道两旁是温暖发光的霓虹灯和动画城市标牌
- 设置关键参数
- 分辨率：支持 480p（854×480）和 720p（1280×720），建议 480p 用于快速验证。
- 宽高比：支持 16:9、9:16、1:1、4:3、3:4，适配不同平台需求。
- 采样步数：1~4 步，推荐使用 4 步以获得最佳质量。
- 随机种子（Seed）：设为 0 表示每次生成不同结果；固定数值可复现相同输出。
- 执行生成
- 点击'生成'按钮后，系统将在后台处理请求。
- 生成完成后，视频自动保存至
outputs/目录。
2.2 提示词优化技巧
高质量提示词是决定生成效果的核心因素之一。以下是构建有效提示词的方法论：
优质提示词特征：
- 具体明确：避免模糊词汇如'好看''美丽'，改用'金色阳光洒落''丝绸质感长裙'。
- 包含动态元素：使用动词如'旋转''飞舞''流动'增强画面动感。
- 描述光影氛围：如'黄昏暖光''冷色调月光''逆光剪影'提升视觉层次。
- 指定艺术风格：如'赛博朋克''水墨风''电影级画质'引导模型风格化输出。
示例对比：
✓ 好：一只橙色的猫在阳光明媚的花园里追逐蝴蝶，花朵随风摇曳
✗ 差：猫和蝴蝶
✓ 好：未来城市的空中交通，飞行汽车在摩天大楼间穿梭，霓虹灯闪烁
✗ 差：未来城市
✓ 好：海浪拍打着岩石海岸，日落时分，金色的光芒洒在水面上
✗ 差：海边日落
3. I2V 图像生成视频
3.1 功能概述
I2V（Image-to-Video）功能已完整实现，支持将静态图像转化为具有自然运动的动态视频。该功能采用双模型架构（高噪声 + 低噪声模型自动切换），结合 ODE/SDE 采样模式与自适应分辨率技术，显著提升生成质量与稳定性。
支持特性：
- ✅ 双模型协同推理
- ✅ 自适应分辨率匹配输入图像比例
- ✅ ODE（确定性）与 SDE（随机性）采样模式可选
- ✅ 完整参数调节接口
3.2 使用步骤详解
- 上传图像
- 支持格式：JPG、PNG
- 推荐分辨率：720p 或更高
- 支持任意宽高比，启用'自适应分辨率'后自动调整输出尺寸
- 编写运动描述 描述应聚焦于以下三类动态变化：
- 相机运动：推进、拉远、环绕、俯视
- 物体运动：人物抬头、树叶摇摆、水流涌动
- 环境变化：光影渐变、天气转变、风吹窗帘
- 示例：相机缓慢向前推进，树叶随风摇摆；她抬头看向天空，然后回头看向镜头；日落时分，天空颜色从蓝色渐变到橙红色
- 配置核心参数
- 分辨率：当前仅支持 720p 输出
- 宽高比：支持多种比例选择
- 采样步数：推荐 4 步
- 随机种子：0 为随机，固定值可复现
- 高级选项（可选）
- 模型切换边界（Boundary）：0.5~1.0，默认 0.9，控制何时从高噪声模型切换至低噪声模型
- ODE 采样：启用可提高锐度，推荐开启
- 自适应分辨率：推荐启用，防止图像变形
- 初始噪声强度（Sigma Max）：默认 200，影响生成多样性
- 开始生成
- 点击'生成'后等待约 1~2 分钟（取决于硬件）
- 视频保存路径：
output/
3.3 I2V 特有参数解析
| 参数 | 说明 | 推荐值 |
|---|---|---|
| Boundary | 模型切换的时间节点（占总步数比例） | 0.9 |
| ODE Sampling | 是否启用确定性采样 | 启用 |
| Adaptive Resolution | 是否根据输入图像比例自动调整输出 | 启用 |
| Sigma Max | 初始噪声强度，影响创造性 | 200 |
3.4 显存与性能要求
由于 I2V 需同时加载两个 14B 规模的模型（高噪声与低噪声），对显存要求较高：
| 显存级别 | 最小需求 | 推荐配置 | 适用 GPU |
|---|---|---|---|
| 最低运行 | ~24GB | 启用量化 (quant_linear=True) | RTX 4090 / 5090 |
| 高质量输出 | ~40GB | 关闭量化，全精度推理 | H100 / A100 |
3.5 性能优化策略
加速技巧：
- 启用
quant_linear=True - 使用
sagesla注意力机制（需安装 SpargeAttn） - 减少采样步数至 2 步（用于预览）
- 降低帧数（如设为 49 帧）
质量提升方法：
- 使用 4 步采样
- 提高
sla_topk至 0.15 - 启用 ODE 采样
- 开启自适应分辨率
4. 参数详解
4.1 核心参数说明
Model（模型）
| 模型名称 | 类型 | 显存需求 | 适用场景 |
|---|---|---|---|
| Wan2.1-1.3B | T2V | ~12GB | 快速测试、提示词验证 |
| Wan2.1-14B | T2V | ~40GB | 高质量输出 |
| Wan2.2-A14B（双模型） | I2V | ~24GB（量化）/ ~40GB（完整） | 图像转视频 |
Resolution（分辨率）
- 480p：854×480，速度快，适合快速迭代
- 720p：1280×720，细节更丰富，推荐用于成品输出
Aspect Ratio（宽高比）
- 16:9：横屏视频，适用于 YouTube、电影
- 9:16：竖屏短视频，适配抖音、快手
- 1:1：社交媒体正方形内容
- 4:3 / 3:4：传统比例，兼容老设备
Steps（采样步数）
- 1 步：最快，质量较低
- 2 步：速度与质量平衡
- 4 步：推荐，质量最优
Seed（随机种子）
- 0：每次生成不同结果
- 固定数字：相同输入下可复现完全一致的视频
4.2 高级参数配置
| 参数 | 可选值 | 说明 | 推荐设置 |
|---|---|---|---|
| Attention Type | sagesla, sla, original | 注意力机制类型 | sagesla（最快） |
| SLA TopK | 0.05~0.2 | 控制注意力计算范围 | 0.1（默认），0.15（高质量） |
| Quant Linear | True / False | 是否启用线性层量化 | RTX 5090/4090 必须开启 |
| Num Frames | 33~161 | 输出帧数（@16fps ≈ 2~10 秒） | 默认 81 帧（~5 秒） |
| Sigma Max | T2V:80, I2V:200 | 初始噪声强度 | 根据任务调整 |
5. 最佳实践指南
5.1 快速迭代工作流
第一轮：测试提示词
├─ Model: Wan2.1-1.3B
├─ Resolution: 480p
├─ Steps: 2
└─ 快速验证创意可行性
第二轮：精细调整
├─ Model: Wan2.1-1.3B
├─ Resolution: 480p
├─ Steps: 4
└─ 优化提示词细节
第三轮：最终输出
├─ Model: Wan2.1-14B（可选）
├─ Resolution: 720p
├─ Steps: 4
└─ 生成高质量成品
5.2 显存优化建议
低显存 GPU（12–16GB）：
- 使用 Wan2.1-1.3B 模型
- 分辨率限制为 480p
- 启用
quant_linear=True - 关闭其他占用 GPU 的程序
中等显存 GPU（24GB）：
- 可运行 Wan2.1-1.3B @ 720p
- 或 Wan2.1-14B @ 480p
- 建议启用量化以提升稳定性
高显存 GPU（40GB+）：
- 可运行 Wan2.1-14B @ 720p
- 可禁用量化以获取更优画质
- 支持完整 I2V 双模型运行
5.3 提示词结构化模板
推荐使用以下五段式结构撰写提示词：
[主体] + [动作] + [环境] + [光线/氛围] + [风格]
示例：一位宇航员 + 在月球表面漫步 + 地球在背景中升起 + 柔和的蓝色光芒 + 电影级画质
动态元素建议：
- 动词：走、跑、飞、旋转、摇摆、流动
- 相机运动：推进、拉远、环绕、俯视
- 环境变化：风吹、水流、光影渐变、雨滴落下
5.4 种子管理策略
建立个人'种子库'，记录表现优异的结果：
提示词：樱花树下的武士
种子：42
结果：优秀 ⭐⭐⭐⭐⭐
提示词：赛博朋克城市夜景
种子：1337
结果：优秀 ⭐⭐⭐⭐⭐
便于后续复现高质量输出。
6. 常见问题解答
6.1 Q1: 生成速度慢怎么办？
解决方案：
- 使用
sagesla注意力机制（需安装 SpargeAttn） - 降低分辨率为 480p
- 切换至 Wan2.1-1.3B 模型
- 将采样步数减少至 2 步
6.2 Q2: 出现显存不足（OOM）错误？
应对措施：
- 启用
quant_linear=True - 使用较小模型（1.3B）
- 降低分辨率或帧数
- 确保使用 PyTorch 2.8.0（更高版本可能存在内存泄漏）
6.3 Q3: 生成结果不理想？
优化方向：
- 增加采样步数至 4
- 编写更详细的提示词
- 更换随机种子尝试新结果
- 调整
sla_topk至 0.15 提升细节 - 使用 14B 大模型提升整体质量
6.4 Q4: 如何复现之前的生成结果？
关键条件：
- 记录并使用相同的随机种子
- 输入完全一致的提示词
- 使用相同模型与参数配置
- 注意：种子为 0 时每次结果均不同
6.5 Q5: 生成的视频保存在哪里？
默认路径：
/root/TurboDiffusion/outputs/
命名规则：
- T2V：
t2v_{seed}_{model}_{timestamp}.mp4 - I2V：
i2v_{seed}_Wan2_2_A14B_{timestamp}.mp4
示例：
t2v_0_Wan2_1_1_3B_20251224_153045.mp4
i2v_42_Wan2_2_A14B_20251224_162722.mp4
6.6 Q6: 可以生成多长时间的视频？
默认设置：
- 81 帧，约 5 秒（16fps）
可调范围：
- 33
161 帧（对应 210 秒） - 更长视频需更多显存支持
6.7 Q7: 是否支持中文提示词？
支持情况：
- ✅ 完全支持中文输入
- ✅ 支持英文及中英混合
- 模型基于 UMT5 文本编码器，具备良好多语言理解能力
6.8 Q9: I2V 与 T2V 的主要区别？
| 维度 | T2V | I2V |
|---|---|---|
| 输入类型 | 文本 | 图像 |
| 应用场景 | 创意生成 | 静态图动起来 |
| 模型架构 | 单模型 | 双模型（高 + 低噪声） |
| 显存需求 | 较低（~12–40GB） | 较高（~24–40GB） |
| 分辨率支持 | 480p / 720p | 当前仅 720p |
| 自适应分辨率 | 不支持 | 支持 |
6.9 Q10: 为什么 I2V 生成时间比 T2V 长？
原因分析：
- 需加载两个 14B 规模模型
- 存在模型切换开销
- 图像编码与预处理耗时
- 典型生成时间：约 110 秒（4 步采样）
6.10 Q11: ODE 与 SDE 采样如何选择？
| 模式 | 特点 | 推荐用途 |
|---|---|---|
| ODE | 确定性，结果锐利，可复现 | 主要推荐 |
| SDE | 随机性，结果柔和但鲁棒 | 多样性探索 |
建议优先使用 ODE，若效果不佳再尝试 SDE。
6.11 Q12: 什么是自适应分辨率？
定义：根据输入图像的宽高比，自动计算输出分辨率，保持目标像素面积不变（如 720p = 921600 像素），避免图像拉伸或压缩。
优势：
- 保持原始构图比例
- 防止内容变形
- 提升视觉一致性
建议：除非需要固定尺寸输出，否则强烈推荐启用。
7. 输出文件说明
7.1 视频文件规格
| 属性 | 值 |
|---|---|
| 格式 | MP4 |
| 编码 | H.264 |
| 帧率 | 16 fps |
| 默认时长 | ~5 秒（81 帧） |
7.2 文件命名规范
T2V: t2v_{seed}_{model}_{timestamp}.mp4
I2V: i2v_{seed}_Wan2_2_A14B_{timestamp}.mp4
字段含义：
t2v/i2v：生成类型{seed}：随机种子{model}：所用模型名称{timestamp}：生成时间戳（YYYYMMDD_HHMMSS）
8. 技术支持与维护
8.1 日志查看命令
# 查看 WebUI 启动日志
tail -f webui_startup_latest.log
# 查看详细错误信息
cat webui_test.log
8.2 性能监控指令
# 实时监控 GPU 状态（每秒刷新）
nvidia-smi -l 1
# 使用 watch 命令持续观察显存占用
watch -n 1 nvidia-smi
8.3 问题反馈渠道
请查阅以下文档获取针对性帮助：
[todo.md]：已知问题与待修复项[CLAUDE.md]：技术原理与架构说明[SAGESLA_INSTALL.md]：SageAttention 安装指南[I2V_IMPLEMENTATION.md]：I2V 实现细节解析
9. 更新日志
2025-12-24 版本更新内容
- ✓ 修复 SageSLA 安装兼容性问题
- ✓ 优化默认参数配置，提升首次使用体验
- ✓ 新增完整用户使用手册
- ✓ 全面上线 I2V 功能
- 支持双模型架构（高噪声 + 低噪声）
- 实现自适应分辨率功能
- 提供 ODE/SDE 采样模式切换
- 完善 WebUI 操作界面
- ✓ 增加启动脚本日志记录功能
