ComfyUI-SeedVR2_VideoUpscaler

SeedVR2 的官方 ComfyUI 版本，支持高质量视频和图像 upscale。

也可作为 多 GPU 独立 CLI 运行，详见 🖥️ 独立运行 部分。

📋 快速访问

• 🆙 未来工作
• 🚀 发布说明
• 🎯 功能特性
• 🔧 系统要求
• 📦 安装指南
• 📖 使用说明
• 🖥️ 独立运行
• ⚠️ 局限性
• 🤝 贡献指南
• 🙏 致谢
• 📜 许可证

🆙 未来工作

我们正在积极开发改进和新功能。如需了解最新动态：

• 📌 跟踪开发进度：访问 Issues 查看活跃开发内容、报告错误并请求新功能
• 💬 加入社区：在 Discussions 中向他人学习、分享工作流程并获取帮助
• 🔮 下一代模型调查：我们正在征求社区对下一个开源超强通用修复模型的意见。请在 Issue #164 中分享您的建议

🚀 发布说明

2025.12.24 - 版本 2.5.24

• 🍎 修复：MPS 内存泄漏回归 - 恢复了在 VAE 编码/解码操作后清除 MPS 缓存的功能，该功能在 v2.5.23 的代码清理过程中被意外移除

2025.12.24 - 版本 2.5.23

• 🔒 安全：防止模型加载中的代码执行 - 通过限制反序列化仅处理张量，增加了对恶意 .pth 文件的防护
• 🎥 修复：FFmpeg 视频写入器可靠性 - 通过重定向 stderr 并添加缓冲区刷新解决了 ffmpeg 进程挂起问题，并改进了调试错误消息 (感谢 @thehhmdb)
• ⚡ 修复：GGUF VAE 模型支持 - 为卷积操作启用自动权重反量化，使 GGUF 量化的 VAE 模型完全可用 (感谢 @naxci1)
• 🛡️ 修复：VAE 切片边缘情况 - 当使用小分割尺寸和高时间下采样时，防止除零崩溃 (感谢 @naxci1)
• 🎨 修复：LAB 颜色传递精度 - 通过在矩阵运算前确保一致的浮点类型，解决了视频 upscale 过程中的数据类型不匹配错误
• 🔧 修复：PyTorch 2.9+ 兼容性 - 将 Conv3d 内存解决方法扩展到所有 PyTorch 2.9+ 版本，修复了在较新 PyTorch 版本上 3 倍 VRAM 使用问题
• 📦 修复：Bitsandbytes 兼容性 - 为非 Gaudi 系统上的 Intel Gaudi 版本检测失败添加了 ValueError 异常处理
• 🍎 MPS：内存优化 - 减少了 Apple Silicon 上编码/解码操作期间的内存使用 (感谢 @s-cerevisiae)

2025.12.13 - 版本 2.5.22

• 🎬 CLI：带 10 位支持的 FFmpeg 视频后端 - 新的 --video_backend ffmpeg 和 --10bit 标志支持 x265 编码与 10 位色深，与 8 位 OpenCV 输出相比减少了渐变中的色带伪影 (基于 @thehhmdb 的 PR - 谢谢！)
• 🍎 修复：MPS 双三次 upscale 兼容性 - 为 PyTorch 2.8.0 之前版本的双三次+抗锯齿插值添加 CPU 回退，解决了 Apple Silicon 上 RGBA alpha upscale 错误
• ⚡ 修复：跨平台直方图匹配 - 将 scatter_ 操作替换为 argsort+index_select，提高了在 CUDA、ROCm 和 MPS 后端的可靠性
• 🧹 MPS：移除同步开销 - 恢复了 v2.5.21 中引入的不必要的 torch.mps.synchronize() 调用，以实现与 CUDA 流水线的一致行为

2025.12.12 - 版本 2.5.21

• 🛠️ 修复：MPS 上的 GGUF 反量化错误 - 通过在精度转换中跳过 GGUF 量化缓冲区，解决了 2.5.20 中引入的形状不匹配错误 - 这些缓冲区必须保持打包格式以便推理期间动态反量化
• 🍎 MPS：消除 CPU 同步开销 - 在 Apple Silicon 统一内存架构上跳过不必要的 CPU 张量卸载，防止导致减速的同步停滞。输入图像和输出视频现在在整个流水线中保留在 MPS 设备上
• ⚡ MPS：预加载文本嵌入 - 在第一阶段编码前加载文本嵌入，避免第二阶段开始时的同步停滞，提高时序精度和吞吐量
• 🧹 MPS：优化模型清理 - 在统一内存上删除模型前跳过冗余的 CPU 移动

2025.12.12 - 版本 2.5.20

• ⚡ 扩展注意力后端 - 全面支持 Flash Attention 2 (Ampere+)、Flash Attention 3 (Hopper+)、SageAttention 2 和 SageAttention 3 (Blackwell/RTX 50xx)，当不可用时自动回退到 PyTorch SDPA (基于 @naxci1 的 PR - 谢谢！)
• 🍎 macOS/Apple Silicon 兼容性 - 在整个 VAE 和 DiT 流水线中用显式数据类型转换替换 MPS autocast，解决 M 系列 Mac 上的挂起和崩溃问题。BlockSwap 现在会自动禁用并发出警告（统一内存使其失去意义）
• 🛡️ Flash Attention 优雅回退 - 为损坏或部分安装的 flash_attn/xformers DLL 添加兼容性垫片，防止启动崩溃
• 🛡️ AMD ROCm：bitsandbytes 冲突修复 - 防止当 diffusers 尝试重新导入损坏的 bitsandbytes 安装时出现的内核注册错误
• 📦 ComfyUI Manager：macOS 分类器修复 - 移除导致 macOS 上出现"GPU 不支持"错误警告的 NVIDIA CUDA 分类器
• 📚 文档更新 - 更新 README，包含注意力后端详情、BlockSwap macOS 说明和清晰的模型缓存描述

2025.12.10 - 版本 2.5.19

• 🎨 新的标题徽标设计 - 更新的 ASCII 艺术横幅 (感谢 @naxci1)
• 🧹 移除无效的 flash attention 包装器 - 从 FP8CompatibleDiT 中移除遗留代码；FlashAttentionVarlen 已通过其 attention_mode 属性处理后端切换
• 🛡️ 修复从 flash-attn 的优雅回退 - 为损坏的 flash_attn/xformers DLL 添加兼容性垫片，防止 CUDA 扩展损坏时的启动崩溃
• 📊 改进的 VRAM 跟踪 - 分离已分配内存和保留内存跟踪，Windows 专用溢出检测（WDDM 分页行为）
• ♻️ 集中后端检测 - 统一代码库中的 is_mps_available()、is_cuda_available()、get_gpu_backend() 辅助函数
• 🔄 恢复 2.5.14 VRAM 限制强制 - 移除 set_per_process_memory_fraction 调用；溢出检测和警告仍然保留。

2025.12.09 - 版本 2.5.18

• 🚀 CLI：长视频流模式 - 新的 --chunk_size 标志使视频处理按内存限制分块进行，支持任意长视频而无 RAM 限制。与模型缓存 (--cache_dit/--cache_vae) 配合使用，实现块间重用 (受 disk02 PR 贡献启发)
• ⚡ CLI：多 GPU 流处理 - 每个 GPU 现在通过独立模型缓存内部流处理其段，提高内存效率并支持在 GPU 边界处进行 --temporal_overlap 混合
• 🔧 CLI：修复大型视频 MemoryError - 共享内存传输替代 numpy 序列化，防止高分辨率/长视频输出时的崩溃 (受 FurkanGozukara PR 贡献启发)

2025.12.05 - 版本 2.5.17

• 🔧 修复：旧 GPU 兼容性（GTX 970 等） - 运行时 bf16 CUBLAS 探测替代计算能力启发式方法，正确检测不支持的 GPU，同时不影响 RTX 20XX

2025.12.05 - 版本 2.5.16

• 🔧 修复：旧 GPU 兼容性（GTX 970 等） - 为不支持 bfloat16 的 GPU 提供自动回退
• 🐛 修复：质量回归 - 恢复导致伪影问题的 bfloat16 检测
• 📋 调试：环境信息显示 - 在调试模式下显示系统信息，帮助问题报告
• 📚 文档：简化贡献工作流 - 简化为仅主分支

2025.12.03 - 版本 2.5.15

• 🍎 修复：MPS 兼容性 - 为 MPS 张量禁用抗锯齿并修复 bfloat16 arange 问题
• ⚡ 修复：Autocast 设备类型 - 使用正确的设备类型属性防止 autocast 错误
• 📊 内存：精确 VRAM 跟踪 - 使用 max_memory_reserved 实现更精确的峰值报告
• 🔧 修复：Triton 兼容性 - 为 bitsandbytes 0.45+ / triton 3.0+ 添加垫片（修复 PyTorch 2.7 安装错误）

2025.12.01 - 版本 2.5.14

• 🍎 修复：MPS 设备比较 - 规范化设备字符串以防止不必要的张量移动
• 📊 内存：VRAM 交换检测 - 峰值统计现在在发生溢出时显示 GPU+交换内存分解，并在检测到交换时发出警告
• 🛡️ 内存：强制物理 VRAM 限制 - PyTorch 现在会 OOM 而不是静默交换到共享内存（防止 Windows 上的极端减速）

2025.11.30 - 版本 2.5.13

• 🔧 修复：PyTorch 2.7+ triton 导入错误 - 解决了在较新 triton 版本上由 triton.ops 导入链导致的安装崩溃
• 💾 修复：长视频 float32 转换 OOM - 当 float32 转换内存不足时优雅回退到原生数据类型
• 🍎 修复：macOS CLI 水印错误 - 解决了 Apple Silicon 上与 MPS 相关的水印处理崩溃

2025.11.28 - 版本 2.5.12

• 🐛 修复：颜色伪影回归 - 恢复视频变换流水线中的原地张量操作，这些操作导致某些图像上出现颜色伪影

2025.11.28 - 版本 2.5.11

• ⚡ 功能：CUDNN 注意力后端 - 添加对 PyTorch 2.3+ CUDNN_ATTENTION 后端的支持，对旧版本自动回退（感谢 @eadwu）
• 💾 修复：长视频内存峰值 - VAE 解码现在直接流式传输到预分配张量，消除长视频处理期间的 OOM 错误
• 🎨 修复：LAB 颜色校正伪影 - 使用小波重建预处理解决 tile 边界伪影
• 🎨 修复：颜色参考对齐问题 - 修复带时间重叠的颜色校正帧对齐
• 🍎 修复：MPS 检测可靠性 - 切换到标准 torch.backends.mps.is_available() API 以实现一致的 Apple Silicon 检测
• 🖥️ 修复：Mac 子进程错误 - CLI 现在在 Mac 上使用直接处理，避免子进程中的 MPS 分配器失败
• 🖥️ 修复：多 GPU 设备分配 - 在生成前设置 CUDA_VISIBLE_DEVICES，以便工作进程正确继承
• 📊 修复：BlockSwap 日志 - 现在显示有效/总块数（例如 32/32）而不是原始请求值
• 🔧 功能：自动 bfloat16 检测 - 自动检测 bfloat16 支持，防止旧 GPU 上的 CUBLAS 错误
• 📊 功能：峰值 RAM 跟踪 - 在调试摘要中添加 RAM 使用情况与 VRAM 一起显示
• ⚡ 性能：原地张量操作 - 通过整个流水线中的原地操作减少内存分配开销
• 📖 文档：多 GPU 说明 - 澄清多 GPU 设置的帧级并行行为预期

2025.11.13 - 版本 2.5.10

• 🎯 修复：确定性生成 - 相同种子的相同图像现在在不同会话和批次位置产生相同结果
• 🔧 修复：BlockSwap 模型缓存 - 解决缓存的 DiT 模型在 VAE 缓存状态更改时无法正确重新加载的问题
• 💾 修复：Runner 缓存优化 - 无论缓存顺序如何，当 DiT 和 VAE 都被缓存时，Runner 模板现在正确缓存
• 📁 修复：不区分大小写的模型路径 - YAML 配置中的额外模型路径现在不区分大小写（seedvr2、SEEDVR2、SeedVR2 等）
• 🐛 修复：高分辨率 tile 调试崩溃 - 修复使用最大分辨率和 VAE tiling 时的"NoneType 没有 log 属性"错误
• 📊 修复：时间重叠日志 - 当时间重叠自动调整时更正帧计数报告
• 🔍 功能：增强的模型路径调试 - 添加详细日志以帮助排查模型加载问题（在调试模式下可见）

2025.11.12 - 版本 2.5.9

• 🐛 修复：Tile 调试可视化崩溃 - 修复在某些系统上使用 VAE tile 调试模式时的 OpenCV 错误。
• 🍎 修复：macOS MPS 加载错误 - 为某些 PyTorch/macOS 版本上的 MPS 分配器问题添加自动 CPU 回退。
• 🖥️ 修复：Windows 日志缓冲 - 为打印语句添加刷新，以便在 Windows 上的 ComfyUI 中实时查看日志
• 📦 修复：ComfyUI Registry 徽标 - 更新图标 URL 以在 ComfyUI 节点注册表中正确显示
• ℹ️ 功能：版本显示 - 在节点名称和 CLI/ComfyUI 标题中添加版本号，便于跟踪
• 💝 功能：GitHub 赞助 - 添加赞助按钮以支持项目开发。感谢大家的支持！
• 📜 许可证：Apache 2.0 - 将许可证从 MIT 恢复为 Apache 2.0，以匹配 ByteDance Seed 项目

2025.11.10 - 版本 2.5.8

• 🐛 修复 (CLI)：Windows 批处理重复文件 - 修复了 CLI 批处理模式在 Windows 上因文件系统不区分大小写而处理每个文件两次的问题。将目录扫描性能提高了 2-3 倍
• 📁 修复(CLI)：输出文件夹位置 - 输出文件现在创建在合理位置：批处理模式创建 {folder_name}_upscaled/ 同级文件夹并保留原始文件名；单文件模式在同一目录添加 _upscaled 后缀。所有日志现在显示绝对路径以确保清晰
• 🎨 修复(CLI)：RGBA alpha 通道支持 - 现在正确检测并保留带有透明度的 PNG 图像通过 upscale 流水线，与 ComfyUI 行为匹配

2025.11.10 - 版本 2.5.7

• 🔧 修复：Conv3d 解决方法兼容性 - 增强平台检测并添加优雅回退，防止 PyTorch 开发构建和 AMD ROCm 系统上的错误

2025.11.09 - 版本 2.5.6

• 🎨 修复：恢复 7b 模型的自然外观 - 修正了 torch.compile 优化，该优化导致使用 7b 模型 upscale 的视频出现过度塑料感/高反光外观。

• 💾 内存：修复长视频 RAM 泄漏 - 使用轻量级批处理索引进行按需重建，而不是存储完整变换视频，修复 release_tensor_memory 以一致处理 CPU/CUDA/MPS，并重构批处理辅助函数

2025.11.08 - 版本 2.5.4

• 🎨 修复：AdaIN 颜色校正 - 用 .reshape() 替换 .view() 以处理空间填充后的非连续张量，解决"视图大小与输入张量的大小和步幅不兼容"错误
• 🔴 修复：AMD ROCm 兼容性 - 在 Conv3d 解决方法中添加 cuDNN 可用性检查，防止 ROCm 系统（Windows/Linux 上的 AMD GPU）上出现"ATen 未使用 cuDNN 支持编译"错误

2025.11.08 - 版本 2.5.3

• 🍎 修复：Apple Silicon MPS 设备处理 - 更正 MPS 设备枚举以使用 "mps" 而非 "mps:0"，解决 M 系列 Mac 上的无效设备错误
• 🪟 修复：Windows 上的 torch.mps AttributeError - 添加 torch.mps.is_available() 的防御性检查，以处理非 Mac 平台上不存在该方法的 PyTorch 版本

2025.11.07 - 版本 2.5.0 🎉

⚠️ 重大变更：这是需要重新创建工作流的重大更新。所有节点和 CLI 参数都经过重新设计，以提高可用性和一致性。观看 AInVFX 的最新视频了解详细内容，并查看 使用说明 部分。

📦 正式发布：现在在主分支上可用，支持 ComfyUI Manager，便于安装和自动版本跟踪。更新的依赖项和本地导入可防止与其他 ComfyUI 自定义节点冲突。

🎨 ComfyUI 改进

• 四节点模块化架构：拆分为 DiT 模型、VAE 模型、torch.compile 设置和主超分器专用节点，实现精细化控制
• 全局模型缓存：模型现在可在多个超分器实例间共享，并自动更新配置——不再需要重复加载
• ComfyUI V3 迁移：完全兼容 ComfyUI V3 无状态节点设计
• RGBA 支持：原生 alpha 通道处理，结合边缘引导超分技术，确保透明区域清晰干净
• 改进的内存管理：流式架构可防止 VRAM 峰值，无论视频长度如何
• 灵活的分辨率支持：采用无损填充方式（替代限制性裁剪），可将分辨率超分到任何能被 2 整除的尺寸
• 增强的参数：新增 uniform_batch_size、temporal_overlap、prepend_frames 和 max_resolution，实现更好的控制

🖥️ CLI 增强功能

• 批处理目录处理：处理整个文件夹的视频/图像，并通过模型缓存提高效率
• 单图像支持：直接进行图像超分，无需视频转换
• 智能输出检测：根据输入类型自动检测输出格式（MP4/PNG）
• 增强的多 GPU 支持：通过时间重叠混合改进工作负载分配
• 统一参数：CLI 和 ComfyUI 现在使用相同的参数名称，确保一致性
• 更好的用户体验：自动显示帮助信息、改进验证机制、进度跟踪和更清晰的输出

⚡ 性能与优化

• torch.compile 支持：通过完整图编译，DiT 速度提升 20-40%，VAE 速度提升 15-25%
• 优化的 BlockSwap：自适应内存清理（5% 阈值）、独立 I/O 组件处理、降低开销
• 增强的 VAE 分块处理：支持累积缓冲区的张量卸载，独立的编码/解码配置
• 原生数据类型流水线：消除不必要的转换，全程保持 bfloat16 精度，兼顾速度与质量
• 优化的张量操作：用原生 PyTorch 操作替代 einops rearrange，实现 2-5 倍更快的转换

🎯 质量改进

• LAB 色彩校正：全新感知色彩迁移方法，色彩准确度更高（现已设为默认）
• 额外色彩处理方式：HSV 饱和度匹配、小波自适应及混合处理方案
• 确定性生成：基于种子的可复现性，采用特定阶段的种子策略
• 更佳时间一致性：使用 Hann 窗口混合技术实现批次间的平滑过渡

💾 内存管理

• 智能卸载：为 DiT、VAE 和张量提供独立设备配置（CPU/GPU/无）
• 四阶段流水线：在进入下一阶段前完成所有批次的各阶段（编码→ upscale→解码→后处理），最大限度减少模型切换
• 优化清理机制：特定阶段的资源管理，确保张量内存得到妥善释放
• 峰值显存跟踪：按阶段进行内存监控并显示汇总信息

🔧 技术改进

• GGUF 量化支持：新增完整 GGUF 支持，可在低显存系统上进行 4 位/8 位推理
• 改进 GGUF 处理：修复显存泄漏问题，实现 torch.compile 兼容性，支持非持久化缓冲区
• Apple Silicon 支持：全面支持 Apple Silicon Mac 的 MPS（Metal 性能着色器）
• AMD ROCm 兼容性：为 PyTorch ROCm 7+ 支持添加条件性 FSDP 导入
• Conv3d 内存问题解决：修复 PyTorch 2.9+ cuDNN 内存 bug（内存使用量减少 3 倍）
• Flash Attention 可选：当 flash-attn 不可用时，可平稳回退至 SDPA

📚 代码质量

• 模块化架构：将大型文件拆分为专注于特定功能的模块（generation_phases、model_configuration 等）
• 全面文档：所有模块均配有详细的文档字符串和类型提示
• 优化错误处理：提前验证、清晰的错误消息及安装说明
• 统一日志记录：统一缩进格式，优化分类方式，日志消息简洁明了

2025.08.07

• 🎯 统一调试系统：全新结构化日志，包含分类、计时器和内存跟踪功能。主节点现已支持 enable_debug
• ⚡ 智能 FP8 优化：FP8 模型现在保持原生 FP8 存储，仅在进行算术运算时转换为 BFloat16 - 比 FP16 更快且内存效率更高
• 📦 模型注册表：多仓库支持（numz/ 和 AInVFX/），自动发现用户模型，添加混合 FP8 变体以修复 7B 模型的伪影问题
• 💾 模型缓存：cache_model 已移至主节点，通过妥善的 RoPE/包装器清理修复了内存泄漏
• 🧹 代码清理：全新模块化结构（constants.py、model_registry.py、debug.py），移除了遗留代码
• 🚀 性能提升：使用 torch.cuda.ipc_collect() 优化内存管理，改进 RoPE 处理

2025.07.17

• 🛠️ 添加 7B 锐化模型：新增 2 个具有锐化输出效果的 7B 模型

2025.07.11

• 🎬 完整教程发布：来自 AInVFX 的 Adrien 制作了一份深入的 ComfyUI SeedVR2 指南，涵盖从基本设置到在消费级 GPU 上运行的高级 BlockSwap 技术的所有内容。非常适合理解内存优化以及带有 alpha 通道的图像序列 upscale！观看教程

2025.09.07

• 🛠️ Blockswap 集成：非常感谢来自 AInVFX 的 Adrien Toupet 实现了这一功能 😃, 对低显存用户非常有用（参见 使用方法 部分）

2025.07.03

• 🛠️ 可以 独立模式 和 多 GPU 运行，参见 🖥️ 作为独立程序运行

2025.06.30

• 🚀 加快处理速度并减少显存占用
• 🛠️ 修复了 3B 模型的内存泄漏问题
• ❌ 现在可以在需要时中断处理过程
• ✅ 重构代码以便更好地与社区共享，欢迎提交拉取请求
• 🛠️ 移除了 flash attention 依赖项（感谢 luke2642！！）

2025.06.24

• 🚀 将处理速度提升至原来的 4 倍

2025.06.22

• 💪 支持 FP8！
• 🚀 加快所有处理流程
• 🚀 减少显存消耗（RTX4090 最多仍建议 batch_size=1，我正在努力解决此问题）
• 🛠️ 更好的基准测试即将推出

2025.06.20

• 🛠️ 首次提交

🎯 功能特点

核心功能

• 高质量扩散型超分辨率：一步到位的扩散模型，用于视频和图像增强
• 时间一致性：通过可配置的批量处理，保持视频帧间的连贯性
• 多格式支持：处理视频和图像的RGB及RGBA（alpha通道）格式
• 任意视频长度：适用于任何长度的视频

模型支持

• 多种模型变体：30亿和70亿参数模型，提供不同精度选项
• FP16、FP8和GGUF量化：根据不同显存需求，可选择全精度（FP16）、混合精度（FP8）或高度量化的GGUF模型
• 模型自动下载：首次使用时从HuggingFace自动下载模型

内存优化

• BlockSwap技术：动态在GPU和CPU内存间交换Transformer块，使大模型能在有限显存中运行
• VAE分块处理：通过分块编码/解码处理大分辨率，降低显存占用
• 智能卸载：在处理阶段之间将模型和中间张量卸载到CPU或辅助GPU
• GGUF量化支持：使用4位或8位量化运行模型，实现极致显存节省

性能特点

• torch.compile集成：借助PyTorch 2.0+编译，可选择性提升DiT速度20-40%、VAE速度15-25%
• 多GPU命令行界面：跨多GPU分配工作负载，自动进行时间重叠融合
• 模型缓存：在生成过程中保持模型加载，适用于单GPU目录处理或多GPU流式处理
• 灵活的注意力后端：可选择PyTorch SDPA（稳定、随时可用）、Flash Attention 2/3或SageAttention 2/3，在支持的硬件上实现更快计算

质量控制

• 高级色彩校正：五种方法，包括LAB（推荐用于最高保真度）、小波、自适应小波、HSV和AdaIN
• 噪声注入控制：微调输入和潜在噪声比例，减少高分辨率下的伪影
• 可配置分辨率限制：设置目标分辨率和最大分辨率，自动保持宽高比

工作流特性

• ComfyUI 集成：四个专用节点，可完全控制 upscale 流程
• 独立 CLI：用于批量处理和自动化的命令行界面
• 调试日志：全面的调试模式，包含内存跟踪、时间信息和处理详情
• 进度报告：处理过程中的实时进度更新

🔧 要求

硬件

凭借当前的优化（分块处理、BlockSwap、GGUF 量化），SeedVR2 可在多种硬件上运行：

• 最低显存（8GB 或以下）：使用 GGUF Q4_K_M 模型，并启用 BlockSwap 和 VAE 分块处理
• 中等显存（12-16GB）：使用 FP8 模型，根据需要启用 BlockSwap 或 VAE 分块处理
• 高显存（24GB+）：使用 FP16 模型以获得最佳质量和速度，无需内存优化

软件

• ComfyUI：建议使用最新版本
• Python：3.12+（已测试并推荐 Python 3.12 和 3.13）
• PyTorch：2.0+ 以支持 torch.compile（可选但推荐）
• Triton：使用 inductor 后端进行 torch.compile 时必需（可选）
• Flash Attention / SageAttention：Flash Attention 2（Ampere+）、Flash Attention 3（Hopper+）、SageAttention 2 或 SageAttention 3（Blackwell）可在支持的硬件上提供更快的注意力计算（可选，默认回退到 PyTorch SDPA）

📦 安装

选项 1：ComfyUI Manager（推荐）

1. 在 ComfyUI 界面中打开 ComfyUI Manager
2. 点击“自定义节点管理器”
3. 搜索“ComfyUI-SeedVR2_VideoUpscaler”
4. 点击“安装”并重启 ComfyUI

注册表链接：ComfyUI Registry - SeedVR2 Video Upscaler

选项 2：手动安装

1. 克隆仓库到您的 ComfyUI 自定义节点目录：

cd ComfyUI
git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler.git custom_nodes/seedvr2_videoupscaler

2. 使用独立 Python 安装依赖项：

# Install requirements (from same ComfyUI directory)
# Windows:
.venv\Scripts\python.exe -m pip install -r custom_nodes\seedvr2_videoupscaler\requirements.txt
# Linux/macOS:
.venv/bin/python -m pip install -r custom_nodes/seedvr2_videoupscaler/requirements.txt

3. 重启 ComfyUI

模型安装

首次使用时，模型将自动下载并保存至 ComfyUI/models/SEEDVR2。

您也可以手动从以下地址下载模型：

• 主模型可在 numz/SeedVR2_comfyUI 和 AInVFX/SeedVR2_comfyUI 获取
• 额外的 GGUF 模型可在 cmeka/SeedVR2-GGUF 获取

📖 使用方法

🎬 视频教程

最新版本深度解析（推荐）

由 AInVFX 的 Adrien 制作的 2.5 版本完整教程，涵盖全新的 4 节点架构、GGUF 支持、内存优化及生产工作流：

本综合教程内容包括：

• 通过 ComfyUI Manager 安装 v2.5 及冲突故障排除
• 理解全新的 4 节点模块化架构及其重构原因
• 使用 GGUF 量化在 8GB VRAM 上运行 7B 模型
• 针对硬件配置 BlockSwap、VAE 分块处理和 torch.compile
• 支持 alpha 通道的图像与视频放大工作流
• 用于批量处理和多 GPU 渲染的 CLI
• 不同 VRAM 容量下的内存优化策略
• 实际生产技巧及关键的 batch_size 公式（4n+1）

旧版本教程

作为参考，以下是涵盖初始版本的原始教程：

注：本教程介绍的是之前的单节点架构。虽然 v2.5 的界面已发生重大变化，但关于 BlockSwap 和内存管理的核心概念仍然具有参考价值。

节点设置

SeedVR2 采用模块化节点架构，包含四个专用节点：

1. SeedVR2 (Down)Load DiT Model

配置用于视频放大的 DiT（扩散 transformer）模型。

参数：

• model：选择 DiT 模型

  • 3B 模型：速度更快，VRAM 需求更低
    • seedvr2_ema_3b_fp16.safetensors：FP16（最佳质量）
    • seedvr2_ema_3b_fp8_e4m3fn.safetensors：FP8 8 位（良好质量）
    • seedvr2_ema_3b-Q4_K_M.gguf：GGUF 4 位量化（可接受质量）
    • seedvr2_ema_3b-Q8_0.gguf：GGUF 8 位量化（良好质量）
  • 7B 模型：质量更高，VRAM 需求更高
    • seedvr2_ema_7b_fp16.safetensors：FP16（最佳质量）
    • seedvr2_ema_7b_fp8_e4m3fn_mixed_block35_fp16.safetensors：FP8 且最后一个块为 FP16 以减少伪影（良好质量）
    • seedvr2_ema_7b-Q4_K_M.gguf：GGUF 4 位量化（可接受质量）
    • seedvr2_ema_7b_sharp_*：增强细节的锐利变体

• device：用于 DiT 推理的 GPU 设备（例如 cuda:0）

• offload_device：非活动处理时卸载 DiT 模型的设备

  • none：保持模型在推理设备上（速度最快，VRAM 占用最高）
  • cpu：卸载到系统内存（减少 VRAM 占用）
  • cuda:X：卸载到另一块 GPU（如可用，平衡良好）

• cache_model：在工作流运行之间将 DiT 模型保持加载在 offload_device 上

  • 对批量处理有用，可避免重复加载
  • 需要设置 offload_device

• blocks_to_swap：BlockSwap 内存优化

  • 0：禁用（默认）
  • 1-32：3B 模型要交换的 transformer 块数量
  • 1-36：7B 模型要交换的 transformer 块数量
  • 值越高 = VRAM 节省越多但处理速度越慢
  • 需要设置 offload_device 且与 device 不同

• swap_io_components：卸载输入/输出嵌入和归一化层

  • 与 blocks_to_swap 结合使用可额外节省 VRAM
  • 需要设置 offload_device 且与 device 不同

• attention_mode：注意力计算后端

  • sdpa：PyTorch scaled_dot_product_attention（默认，始终可用）
  • flash_attn_2：Flash Attention 2（Ampere+，需要 flash-attn 包）
  • flash_attn_3：Flash Attention 3（Hopper+，需要支持 FA3 的 flash-attn）
  • sageattn_2：SageAttention 2（需要 sageattention 包）
  • sageattn_3：SageAttention 3（Blackwell/RTX 50xx，需要 sageattn3 包）

• torch_compile_args：连接到 SeedVR2 Torch Compile Settings 节点以获得 20-40% 的速度提升

BlockSwap 说明：

BlockSwap 通过在推理过程中动态在 GPU 和 CPU 内存之间交换 transformer 块，使大型模型能够在 VRAM 有限的 GPU 上运行。

注意： BlockSwap 在 macOS 上不可用。Apple Silicon Mac 采用统一内存架构，GPU 和 CPU 共享同一内存池，因此 BlockSwap 没有意义。如果在 macOS 上请求此选项，将自动禁用并发出警告。

工作原理如下：

• 功能：仅将当前需要的 transformer 块保留在 GPU 上，其余存储在 CPU 或其他设备上
• 使用场景：放大阶段出现 OOM（内存不足）错误时
• 配置方法：
  1. 将 offload_device 设置为 cpu 或另一块 GPU
  2. 从 blocks_to_swap=16 开始（一半的块）
  3. 如果仍出现 OOM，增加到 24 或 32（3B）/ 36（7B）
  4. 启用 swap_io_components 以获得最大 VRAM 节省
  5. 如果 VRAM 充足，减少或设为 0 以获得更快处理速度

低 VRAM（8GB）示例配置：

• model: seedvr2_ema_3b-Q8_0.gguf
• device: cuda:0
• offload_device: cpu
• blocks_to_swap: 32
• swap_io_components: True

2. SeedVR2 (Down)Load VAE Model

配置用于视频帧编码/解码的 VAE（变分自编码器）模型。

参数：

• model：VAE 模型选择

  • ema_vae_fp16.safetensors：默认且推荐

• device：用于 VAE 推理的 GPU 设备（例如 cuda:0）

• offload_device：非活动处理时卸载 VAE 模型的设备

  • none：保持模型在推理设备上（默认，速度最快）
  • cpu：卸载到系统内存（减少 VRAM 占用）
  • cuda:X：卸载到另一块 GPU（如可用，平衡良好）

• cache_model：在工作流运行之间将 VAE 模型保持加载在 offload_device 上

  • 需要设置 offload_device

• encode_tiled：启用分块编码以减少编码阶段的 VRAM 使用

  • 如果在调试日志中看到"Encoding"阶段出现 OOM 错误，启用此选项

• encode_tile_size：编码分块大小（像素）（默认：1024）

  • 同时应用于高度和宽度
  • 值越低 VRAM 占用越少，但可能增加处理时间

• encode_tile_overlap：编码分块重叠（像素）（默认：128）

  • 减少分块之间的可见接缝

• decode_tiled：启用分块解码以减少解码阶段的 VRAM 使用

  • 如果在调试日志中看到"Decoding"阶段出现 OOM 错误，启用此选项

• decode_tile_size：解码分块大小（像素）（默认：1024）

• decode_tile_overlap：解码分块重叠（像素）（默认：128）

• torch_compile_args：连接到 SeedVR2 Torch Compile Settings 节点以获得 15-25% 的速度提升

VAE 分块处理说明：

VAE 分块处理以较小的分块处理大分辨率，从而降低 VRAM 需求。使用方法如下：

1. 先不使用分块运行并监控调试日志（在主节点上启用 enable_debug）
2. 如果"Encoding"阶段出现 OOM：
   • 启用 encode_tiled
   • 如果仍 OOM，减小 encode_tile_size（尝试 768、512 等）
3. 如果"Decoding"阶段出现 OOM：
   • 启用 decode_tiled
   • 如果仍 OOM，减小 decode_tile_size
4. 调整重叠（默认 128）：如果输出中看到可见接缝（增加）或处理时间过长（减少）。

高分辨率（4K）示例配置：

• encode_tiled: True
• encode_tile_size: 1024
• encode_tile_overlap: 128
• decode_tiled: True
• decode_tile_size: 1024
• decode_tile_overlap: 128

3. SeedVR2 Torch Compile Settings（可选）

配置 torch.compile 优化以获得 20-40% 的 DiT 速度提升和 15-25% 的 VAE 速度提升。

要求：

• PyTorch 2.0+
• Triton（用于 inductor 后端）

参数：

• backend：编译后端

  • inductor：使用 Triton 内核生成和融合的完全优化（推荐）
  • cudagraphs：使用 CUDA 图的轻量级包装，无内核优化

• mode：优化级别（编译时间 vs 运行时性能）

  • default：快速编译且具有良好加速（推荐用于开发）
  • reduce-overhead：低开销，针对小型模型优化
  • max-autotune：编译最慢，运行时性能最佳（推荐用于生产）
  • max-autotune-no-cudagraphs：类似 max-autotune 但不使用 CUDA 图

• fullgraph：将整个模型编译为单个无中断图

  • False：允许图中断以获得更好的兼容性（默认，推荐）
  • True：强制无中断以获得最大优化（动态形状可能失败）

• dynamic：处理变化的输入形状而无需重新编译

  • False：针对精确输入形状进行专门优化（默认）
  • True：创建适应形状变化的动态内核（处理不同分辨率或批量大小时启用）

• dynamo_cache_size_limit：每个函数的最大缓存编译版本数（默认：64）

  • 越高 = 内存占用越多，越低 = 重新编译越多

• dynamo_recompile_limit：回退到即时模式前的最大重新编译尝试次数（默认：128）

  • 防止编译循环的安全限制

使用方法：

1. 将此节点添加到工作流
2. 将其输出连接到 DiT 和/或 VAE 加载器节点的 torch_compile_args 输入
3. 首次运行会较慢（编译），后续运行会快很多

使用场景：

• 仅当处理多个批次、长视频或许多分块时，torch.compile 才有意义
• 对于单张图像或短视频，编译时间超过速度提升收益
• 最适合批量处理工作流或长视频

推荐设置：

• 开发/测试：mode=default，backend=inductor，fullgraph=False
• 生产：mode=max-autotune，backend=inductor，fullgraph=False

4. SeedVR2 Video Upscaler（主节点）

使用 DiT 和 VAE 模型处理视频帧的主放大节点。

必需输入：

• image：作为图像批次的输入视频帧（RGB 或 RGBA 格式）
• dit：来自 SeedVR2 (Down)Load DiT Model 节点的 DiT 模型配置
• vae：来自 SeedVR2 (Down)Load VAE Model 节点的 VAE 模型配置

参数：

• seed：用于可重现生成的随机种子（默认：42）

  • 相同种子和相同输入产生完全相同的输出

• resolution：最短边的目标分辨率（像素）（默认：1080）

  • 自动保持宽高比

• max_resolution：任意边的最大分辨率（默认：0 = 无限制）

  • 如超过将自动缩小以防止 OOM

• batch_size：每批处理的帧数（默认：5）

  • 关键要求：必须遵循4n+1 公式（1、5、9、13、17、21、25...）
  • 重要性：模型使用这些帧进行时间一致性计算
  • 时间一致性最低要求 5：仅单张图像或不需要时间一致性时使用 1
  • 理想匹配镜头长度：为获得最佳结果，将 batch_size 设置为匹配镜头长度（例如 20 帧镜头使用 batch_size=21）
  • VRAM 影响：batch_size 越高 = 质量和速度越好，但需要更多 VRAM
  • 如果 batch_size=5 仍 OOM：先尝试优化技术（模型卸载、BlockSwap、GGUF 模型...）再减少 batch_size 或输入分辨率，因为这些会直接影响质量

uniform_batch_size（默认：False）

• 将最后一批填充至 batch_size 以实现统一处理

  • 防止最后一批远小于其他批次时的时间伪影
  • 示例：45 帧与 batch_size=33 创建 [33, 33] 而非 [33, 12]
  • 当使用大 batch_size 且视频长度不是 batch_size 的倍数时推荐使用
  • 略微增加 VRAM 占用，但确保所有批次间一致的时间连贯性

• temporal_overlap：批次间的重叠帧数（默认：0）

  • 用于批次间混合以减少时间伪影
  • 范围：0-16 帧

• prepend_frames：要前置的帧数（默认：0）

  • 前置反转帧以减少视频开始处的伪影
  • 处理后自动移除
  • 范围：0-32 帧

• color_correction：色彩校正方法（默认："wavelet"）

  • lab：全感知色彩匹配并保留细节（推荐用于最高保真度）
  • wavelet：基于频率的自然色彩，良好保留细节
  • wavelet_adaptive：小波基础 + 目标饱和度校正
  • hsv：基于色调的饱和度匹配
  • adain：统计风格迁移
  • none：无色彩校正

• input_noise_scale：输入噪声注入比例 0.0-1.0（默认：0.0）

  • 向输入帧添加噪声以减少极高分辨率下的伪影
  • 如果高输出分辨率下看到伪影，尝试 0.1-0.3

• latent_noise_scale： latent 空间噪声比例 0.0-1.0（默认：0.0）

  • 扩散过程中添加噪声，可柔化过多细节
  • 如果 input_noise 无帮助，尝试 0.05-0.15

• offload_device：处理阶段之间存储中间张量的设备（默认："cpu"）

  • none：所有张量保持在推理设备上（最快但 VRAM 占用最高）
  • cpu：卸载到系统内存（长视频推荐，传输较慢）
  • cuda:X：卸载到另一块 GPU（如可用，平衡良好，比 CPU 快）

• enable_debug：启用详细调试日志（默认：False）

  • 显示内存使用、时间信息和处理详情
  • 排查 OOM 问题时强烈推荐

输出：

• 应用色彩校正后的放大视频帧
• 格式（RGB/RGBA）与输入匹配
• 范围 [0, 1] 归一化以兼容 ComfyUI

典型工作流设置

基础工作流（高显存 - 24GB+）：

Load Video Frames
    ↓
SeedVR2 Load DiT Model
  ├─ model: seedvr2_ema_3b_fp16.safetensors
  └─ device: cuda:0
    ↓
SeedVR2 Load VAE Model
  ├─ model: ema_vae_fp16.safetensors
  └─ device: cuda:0
    ↓
SeedVR2 Video Upscaler
  ├─ batch_size: 21
  └─ resolution: 1080
    ↓
Save Video/Frames

低显存工作流程（8-12GB）：

Load Video Frames
    ↓
SeedVR2 Load DiT Model
  ├─ model: seedvr2_ema_3b-Q8_0.gguf
  ├─ device: cuda:0
  ├─ offload_device: cpu
  ├─ blocks_to_swap: 32
  └─ swap_io_components: True
    ↓
SeedVR2 Load VAE Model
  ├─ model: ema_vae_fp16.safetensors
  ├─ device: cuda:0
  ├─ encode_tiled: True
  └─ decode_tiled: True
    ↓
SeedVR2 Video Upscaler
  ├─ batch_size: 5
  └─ resolution: 720
    ↓
Save Video/Frames

高性能工作流程（24GB+ 显存，支持 torch.compile）：

Load Video Frames
    ↓
SeedVR2 Torch Compile Settings
  ├─ mode: max-autotune
  └─ backend: inductor
    ↓
SeedVR2 Load DiT Model
  ├─ model: seedvr2_ema_7b_sharp_fp16.safetensors
  ├─ device: cuda:0
  └─ torch_compile_args: connected
    ↓
SeedVR2 Load VAE Model
  ├─ model: ema_vae_fp16.safetensors
  ├─ device: cuda:0
  └─ torch_compile_args: connected
    ↓
SeedVR2 Video Upscaler
  ├─ batch_size: 81
  └─ resolution: 1080
    ↓
Save Video/Frames

🖥️ 作为独立程序运行（CLI）

独立 CLI 提供强大的批量处理功能，支持多 GPU 以及复杂的优化选项。

前提条件

根据您的安装情况选择合适的设置：

选项 1：已安装带有 SeedVR2 的 ComfyUI

如果您已将 SeedVR2 作为 ComfyUI 的一部分安装（通过 ComfyUI 安装），您可以直接使用 CLI：

# Navigate to your ComfyUI directory
cd ComfyUI

# Run the CLI using standalone Python (display help message)
# Windows:
.venv\Scripts\python.exe custom_nodes\seedvr2_videoupscaler\inference_cli.py --help
# Linux/macOS:
.venv/bin/python custom_nodes/seedvr2_videoupscaler/inference_cli.py --help

跳至下方的命令行用法。

选项 2：独立安装（无需 ComfyUI）

如果您希望在不安装 ComfyUI 的情况下使用命令行界面，请按照以下步骤操作：

1. 安装 uv（现代 Python 包管理器）：

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. 克隆仓库：

git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler.git seedvr2_videoupscaler
cd seedvr2_videoupscaler

3. 创建虚拟环境并安装依赖项：

# Create virtual environment with Python 3.13
uv venv --python 3.13

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Install PyTorch with CUDA support
# Check command line based on your environment: https://pytorch.org/get-started/locally/
uv pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu130

# Install SeedVR2 requirements
uv pip install -r requirements.txt

# Run the CLI (display help message)
# Windows:
.venv\Scripts\python.exe inference_cli.py --help
# Linux/macOS:
.venv/bin/python inference_cli.py --help

命令行使用方法

命令行界面（CLI）为单GPU、多GPU和批量处理工作流提供了全面的选项。

基本使用示例：

# Basic image upscaling
python inference_cli.py image.jpg

# Basic video upscaling with temporal consistency
python inference_cli.py video.mp4 --resolution 720 --batch_size 33

# Streaming mode for long videos (memory-efficient) with 10-bit video output (requires FFMPEG)
# Processes video in chunks of 330 frames to avoid loading entire video into RAM
# Use --temporal_overlap to ensure smooth transitions between chunks
python inference_cli.py long_video.mp4 \
    --resolution 1080 \
    --batch_size 33 \
    --chunk_size 330 \
    --temporal_overlap 3 \
    --video_backend ffmpeg \
    --10bit

# Multi-GPU processing with temporal overlap
python inference_cli.py video.mp4 \
    --cuda_device 0,1 \
    --resolution 1080 \
    --batch_size 81 \
    --uniform_batch_size \
    --temporal_overlap 3 \
    --prepend_frames 4

# Memory-optimized for low VRAM (8GB)
python inference_cli.py image.png \
    --dit_model seedvr2_ema_3b-Q8_0.gguf \
    --resolution 1080 \
    --blocks_to_swap 32 \
    --swap_io_components \
    --dit_offload_device cpu \
    --vae_offload_device cpu

# High resolution with VAE tiling
python inference_cli.py video.mp4 \
    --resolution 1440 \
    --batch_size 31 \
    --uniform_batch_size \
    --temporal_overlap 3 \
    --vae_encode_tiled \
    --vae_decode_tiled

# Batch directory processing with model caching
python inference_cli.py media_folder/ \
    --output processed/ \
    --cuda_device 0 \
    --cache_dit \
    --cache_vae \
    --dit_offload_device cpu \
    --vae_offload_device cpu \
    --resolution 1080 \
    --max_resolution 1920

命令行参数

输入/输出：

• <input>：输入文件（.mp4、.avi、.png、.jpg 等）或目录
• --output：输出路径（默认：在 'output/' 目录中自动生成）
• --output_format：输出格式：'mp4'（视频）或 'png'（图像序列）。默认：根据输入类型自动检测
• --video_backend：视频编码器后端：'opencv'（默认）或 'ffmpeg'（需要 PATH 中包含 ffmpeg）
• --10bit：使用 x265 编解码器和 yuv420p10le 像素格式保存 10 位视频（减少渐变中的色带现象）。不使用此标志时，ffmpeg 会使用 x264（yuv420p）以获得最大兼容性。需要 --video_backend ffmpeg
• --model_dir：模型目录（默认：./models/SEEDVR2）

模型选择：

• --dit_model：要使用的 DiT 模型。选项：3B/7B 以及 fp16/fp8/GGUF 变体（默认：3B FP8）

处理参数：

• --resolution：目标短边分辨率（像素）（默认：1080）
• --max_resolution：任意边的最大分辨率。如果超过则缩小。0 = 无限制（默认：0）
• --batch_size：每批帧数（必须遵循 4n+1：1、5、9、13、17、21...）。理想情况下应与镜头长度匹配，以获得最佳时间一致性（默认：5）
• --seed：用于可重复性的随机种子（默认：42）
• --skip_first_frames：跳过前 N 帧（默认：0）
• --load_cap：从视频加载的最大总帧数。0 = 加载所有（默认：0）
• --chunk_size：流模式下每块的帧数。当 > 0 时，以内存限制的 N 帧块处理视频，在加载下一块之前写入每块。对于否则会超出 RAM 的长视频至关重要。与 --temporal_overlap 一起使用可实现无缝块过渡。0 = 一次性加载所有帧（默认：0）
• --prepend_frames： prepend N 个反转帧以减少起始伪影（会自动移除）（默认：0）
• --temporal_overlap：批次/GPU 之间重叠的帧数，用于平滑混合（默认：0）

质量控制：

• --color_correction：色彩校正方法：'lab'（感知型，推荐）、'wavelet'、'wavelet_adaptive'、'hsv'、'adain' 或 'none'（默认：lab）
• --input_noise_scale：输入噪声注入比例（0.0-1.0）。在高分辨率下减少伪影（默认：0.0）
• --latent_noise_scale：潜在空间噪声比例（0.0-1.0）。必要时柔化细节（默认：0.0）

内存管理：

• --dit_offload_device：用于卸载 DiT 模型的设备：'none'（保持在 GPU 上）、'cpu' 或 'cuda:X'（默认：none）
• --vae_offload_device：用于卸载 VAE 模型的设备：'none'、'cpu' 或 'cuda:X'（默认：none）
• --blocks_to_swap：要交换的 transformer 块数量（0=禁用，3B：0-32，7B：0-36）。需要 dit_offload_device（默认：0）。macOS 上不可用。
• --swap_io_components：卸载 I/O 组件以节省更多 VRAM。需要 dit_offload_device。macOS 上不可用。

VAE 分块：

• --vae_encode_tiled：启用 VAE 编码分块以减少编码期间的 VRAM
• --vae_encode_tile_size：VAE 编码分块大小（像素）（默认：1024）
• --vae_encode_tile_overlap：VAE 编码分块重叠（像素）（默认：128）
• --vae_decode_tiled：启用 VAE 解码分块以减少解码期间的 VRAM
• --vae_decode_tile_size：VAE 解码分块大小（像素）（默认：1024）
• --vae_decode_tile_overlap：VAE 解码分块重叠（像素）（默认：128）
• --tile_debug：可视化分块：'false'（默认）、'encode' 或 'decode'

性能优化：

• --allow_vram_overflow：允许 VRAM 溢出到系统 RAM。防止内存不足（OOM）但可能导致严重减速
• --attention_mode：注意力后端：'sdpa'（默认）、'flash_attn_2'（Ampere+）、'flash_attn_3'（Hopper+）、'sageattn_2' 或 'sageattn_3'（Blackwell）
• --compile_dit：为 DiT 模型启用 torch.compile（20-40% 加速，需要 PyTorch 2.0+ 和 Triton）
• --compile_vae：为 VAE 模型启用 torch.compile（15-25% 加速，需要 PyTorch 2.0+ 和 Triton）
• --compile_backend：编译后端：'inductor'（完全优化）或 'cudagraphs'（轻量级）（默认：inductor）
• --compile_mode：优化级别：'default'、'reduce-overhead'、'max-autotune'、'max-autotune-no-cudagraphs'（默认：default）
• --compile_fullgraph：将整个模型编译为单个图（更快但灵活性较低）（默认：False）
• --compile_dynamic：处理不同的输入形状而无需重新编译（默认：False）
• --compile_dynamo_cache_size_limit：每个函数的最大缓存已编译版本数（默认：64）
• --compile_dynamo_recompile_limit：回退前的最大重新编译尝试次数（默认：128）

模型缓存（批处理）：

• --cache_dit：在生成之间将 DiT 模型保留在内存中。适用于单 GPU 目录处理或多 GPU 流处理（--chunk_size）。需要 --dit_offload_device
• --cache_vae：在生成之间将 VAE 模型保留在内存中。适用于单 GPU 目录处理或多 GPU 流处理（--chunk_size）。需要 --vae_offload_device

多 GPU：

• --cuda_device：CUDA 设备 ID。单个 ID（例如 '0'）或逗号分隔的列表 '0,1' 用于多 GPU

调试：

• --debug：启用详细调试日志

多GPU处理说明

CLI的多GPU模式采用帧级并行处理：视频被分割成多个片段，每个GPU独立处理其负责的片段，完整执行全部4个阶段（编码→ upscale → 解码→后处理）。这种模式非常适合长视频，通过分摊工作负载来减少总体处理时间。

工作原理：

1. 视频帧在各GPU之间平均分配（例如，2个GPU处理100帧 → 每个GPU处理50帧）
2. 每个GPU加载各自的模型副本，并独立处理其负责的片段
3. 当设置--temporal_overlap时，片段会包含重叠帧以实现无缝融合
4. 处理结果被拼接（并在重叠区域进行融合）为最终视频

2个GPU处理100帧且temporal_overlap=4的示例：

GPU 0: Frames 0-53 (50 base + 4 overlap at end, processed as independent video)
GPU 1: Frames 50-99 (50 frames, 4 overlap at start, processed as independent video)
Result: Frames 0-99 with smooth blending at the transition point

重要注意事项：

• 每个 GPU 都会将其处理的视频片段作为独立视频进行处理，并采用各自的批次分割方式
• batch_size 控制每个 GPU 片段内的批处理大小，而非跨 GPU 的批处理
• 对于短视频（少于 100 帧），单 GPU 通常效率更高，因为模型加载会产生额外开销
• 多 GPU 会使显存占用翻倍（每个 GPU 都加载完整模型），但处理时间大致减半

何时使用多 GPU：

• 长视频（100 帧以上），此时分割处理能显著节省时间
• 拥有多个显存充足的 GPU 时

何时使用单 GPU：

• 短视频，此时模型加载开销超过并行处理带来的收益
• 希望所有帧一起处理以获得最大时间连贯性时

最佳实践：

• 将 --temporal_overlap 设置为 2-4 帧，以实现 GPU 片段间的平滑过渡
• 重叠帧数越高，过渡越平滑，但冗余处理也越多
• 使用 --prepend_frames 减少视频开头的伪影
• 对于短视频的最佳质量，使用单 GPU 并将 batch_size 设置为与镜头长度匹配

⚠️ 局限性

模型局限性

批次大小限制：由于时间一致性架构，模型要求 batch_size 遵循 4n+1 公式（1、5、9、13、17、21、25……）。批次中的所有帧会一起处理以确保时间连贯性，然后可以使用 temporal_overlap 对批次进行融合。理想情况下，将 batch_size 设置为与镜头长度匹配以获得最佳质量。

性能考虑因素

VAE 瓶颈：即使采用了优化的 DiT upscale 技术（BlockSwap、GGUF、torch.compile），VAE 编码/解码阶段仍可能成为瓶颈，尤其是在高分辨率下。VAE 处理速度较慢。使用较大的 batch_size 可以缓解此问题。

显存使用：尽管当前集成已支持低显存系统（8GB 或以下，配合适当优化），但显存使用情况取决于以下因素：

• 输入/输出分辨率（分辨率越高，显存占用越多）
• 批次大小（批次越大，显存占用越多，但时间连贯性和速度越好）
• 模型选择（显存占用：FP16 > FP8 > GGUF）
• 优化设置（BlockSwap、VAE 分块可显著降低显存占用）

速度：处理速度取决于：

• GPU 性能（计算性能、显存带宽和架构代次）
• 模型大小（3B 比 7B 更快）
• 批次大小（较大的批次大小由于 GPU 利用率更高，每帧处理速度更快）
• 优化设置（torch.compile 可显著提升速度）
• 分辨率（分辨率越高，处理速度越慢）

最佳实践

1. 启用调试模式开始，以了解显存的使用情况
2. 编码过程中出现内存溢出错误：启用 VAE 编码分块功能并减小分块大小
3. ** upscale 过程中出现内存溢出错误**：启用 BlockSwap 并增加 blocks_to_swap 的值
4. 解码过程中出现内存溢出错误：启用 VAE 解码分块功能并减小分块大小
   • 如果尝试上述所有方法后仍出现内存溢出：减小 batch_size 或分辨率
5. 追求最佳质量：使用与镜头长度匹配的较大 batch_size、FP16 模型以及 LAB 色彩校正
6. 追求速度：使用 FP8/GGUF 模型，启用 torch.compile，并在可用时使用 Flash Attention
7. 处理长视频前，先用短视频测试设置

🤝 贡献指南

欢迎贡献！我们重视社区的意见和改进建议。

详细的贡献指南，请参见 CONTRIBUTING.md。

快速开始：

1. Fork 本仓库
2. 创建你的功能分支（git checkout -b feature/AmazingFeature）
3. 提交你的更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 向 main 分支提交 Pull Request

获取帮助：

• YouTube：AInVFX Channel
• GitHub Issues：用于提交错误报告和功能请求
• GitHub Discussions：用于提问和社区支持
• Discord：adrientoupet & NumZ#7184

🙏 致谢

此 ComfyUI 实现是 NumZ 和 AInVFX（Adrien Toupet）的协作项目，基于 ByteDance Seed 团队的原始 SeedVR2。

特别感谢我们的社区贡献者，包括 naxci1、thehhmdb、s-cerevisiae、benjaminherb、cmeka、FurkanGozukara、JohnAlcatraz、lihaoyun6、Luchuanzhao、Luke2642、proxyid、q5sys 以及其他许多人，感谢他们的改进、错误修复和测试。

📜 许可证

本仓库中的代码根据 LICENSE 文件中所述的 Apache 2.0 许可证发布。