
余炅泽1、高向博1、Pooja Verlani2、Akshay Gadde2、 王艺霖2、Balu Adsumilli2、涂 Zhengzhong†,1
1德克萨斯 A&M 大学 2YouTube, Google
†通讯作者
摘要: 视频超分辨率(VSR)旨在从低分辨率(LR)估计中恢复高质量视频帧,然而大多数现有 VSR 方法在推理时表现得像黑盒:用户无法可靠地修正意外伪影,只能被动接受模型生成的结果。 本文提出了一种名为 SparkVSR 的新型交互式 VSR 框架,该框架将稀疏关键帧作为一种简单且富有表现力的控制信号。具体而言,用户可以首先使用任何现成的图像超分辨率(ISR)模型对一小部分关键帧进行超分辨率处理(或可选地进行编辑),然后 SparkVSR 将关键帧先验信息传播到整个视频序列,同时保持与原始 LR 视频运动的一致性。 具体来说,我们引入了一种关键帧条件的潜像素两阶段训练流水线,该流水线将 LR 视频潜变量与稀疏编码的 HR 关键帧潜变量相融合,以学习稳健的跨空间传播并优化感知细节。在推理时,SparkVSR 支持灵活的关键帧选择(手动指定、编解码器 I 帧提取或随机采样)以及一种无参考引导机制,该机制持续平衡对关键帧的遵循度和盲修复,确保即使在参考关键帧缺失或不完美的情况下也能实现稳健性能。在多个 VSR 基准测试上的实验表明,该方法提高了时间一致性并具有优异的修复质量,在 CLIP-IQA、DOVER 和 MUSIQ 指标上分别超过基线方法高达 24.6%、21.8% 和 5.6%,实现了可控的、关键帧驱动的视频超分辨率。 此外,我们证明 SparkVSR 是一个通用的交互式、关键帧条件视频处理框架,可直接应用于未见过的任务,如老电影修复和视频风格迁移。
requirements.txt)# Clone the github repo and go to the directory
git clone https://github.com/taco-group/SparkVSR
cd SparkVSR
# Create and activate conda environment
conda create -n sparkvsr python=3.10
conda activate sparkvsr
# Install all required dependencies
pip install -r requirements.txt我们的模型与 DOVE 使用相同的数据集进行训练:HQ-VSR 和 DIV2K-HR。所有数据集应放置在 datasets/train/ 目录下。
| 数据集 | 类型 | 视频/图像数量 | 下载链接 |
|---|---|---|---|
| HQ-VSR | 视频 | 2,055 | Google Drive |
| DIV2K-HR | 图像 | 800 | 官方链接 |
所有数据集应遵循以下结构:
datasets/
└── train/
├── HQ-VSR/
└── DIV2K_train_HR/我们使用多个真实世界和合成测试数据集进行评估。所有数据集均遵循一致的目录结构:
| 数据集 | 类型 | 视频数量 | 平均帧数 | 下载地址 |
|---|---|---|---|---|
| UDM10 | 合成数据 | 10 | 32 | Google Drive |
| SPMCS | 合成数据 | 30 | 32 | Google Drive |
| YouHQ40 | 合成数据 | 40 | 32 | Google Drive |
| RealVSR | 真实世界数据 | 50 | 50 | Google Drive |
| MovieLQ | 老电影数据 | 10 | 192 | Google Drive |
运行推理前,请确保路径(datasets/test/)正确无误。
目录结构如下:
datasets/
└── test/
└── [DatasetName]/
├── GT/ # Ground Truth: folder of high-quality frames (one per clip)
├── GT-Video/ # Ground Truth (video version): lossless MKV format
├── LQ/ # Low-quality Input: folder of degraded frames (one per clip)
└── LQ-Video/ # Low-Quality Input (video version): lossless MKV format在训练或测试前,您需要生成包含数据集目录中所有有效视频和图像文件相对路径的 .txt 文件。这些文本列表将作为训练和推理过程中数据加载器的索引。请运行以下命令:
# 🔹 Train dataset
python finetune/scripts/prepare_dataset.py --dir datasets/train/HQ-VSR
python finetune/scripts/prepare_dataset.py --dir datasets/train/DIV2K_train_HR
# 🔹 Testing dataset
python finetune/scripts/prepare_dataset.py --dir datasets/test/UDM10/GT-Video
python finetune/scripts/prepare_dataset.py --dir datasets/test/UDM10/LQ-Video
# (You may need to repeat the above for other test datasets as needed)我们的模型基于 CogVideoX1.5-5B-I2V 基础模型构建。我们提供了 SparkVSR 在不同训练阶段的预训练权重。
| 模型名称 | 描述 | HuggingFace |
|---|---|---|
| CogVideoX1.5-5B-I2V | 用于初始化的基础模型 | zai-org/CogVideoX1.5-5B-I2V |
| SparkVSR (Stage-1) | SparkVSR 第一阶段训练权重 | JiongzeYu/SparkVSR-S1 |
| SparkVSR (Stage-2) | SparkVSR 第二阶段最终权重 | JiongzeYu/SparkVSR |
💡 模型存放位置:
- 将基础模型(
CogVideoX1.5-5B-I2V)放入pretrained_weights/文件夹。- 将下载的 SparkVSR 权重(第一阶段和第二阶段)放入
checkpoints/文件夹。
注意: 训练需要 4×A100 GPU。
🔹 第一阶段( latent 空间):关键帧条件适配。 进入 finetune/ 目录并开始训练:
cd finetune/
bash sparkvsr_train_s1_ref.sh此阶段通过学习将低分辨率视频 latent 与稀疏高分辨率关键帧 latent 融合,实现鲁棒的跨空间传播,从而使基础模型适应视频超分辨率任务。
🔹 第二阶段(像素空间):细节优化。 首先,将第一阶段的检查点转换为可加载的 SFT 权重格式:
python scripts/prepare_sft_ckpt.py --checkpoint_dir ../checkpoint/SparkVSR-s1/checkpoint-10000(根据实际训练输出调整路径和步数)。
您可以通过下载我们的 SparkVSR 第一阶段权重 作为第二阶段的起点,从而跳过第一阶段。
然后,运行第二阶段微调:
bash sparkvsr_train_s2_ref.sh此阶段在像素空间优化感知细节,确保在遵循提供的关键帧的同时,当关键帧缺失或不完善时,仍能保持强大的无参考盲超分辨率能力。
最后,将第二阶段检查点转换为推理格式:
python scripts/prepare_sft_ckpt.py --checkpoint_dir ../checkpoint/SparkVSR-s2/checkpoint-500sparkvsr_inference.sh 中提供。SparkVSR 通过三种主要推理模式(--ref_mode)支持灵活的关键帧传播。
无论选择哪种模式,都可以使用以下参数自定义时间传播行为:
--ref_indices:指定要用作参考的关键帧索引(从 0 开始)。
--ref_indices 0 16 32--ref_guidance_scale:控制参考关键帧对输出视频的影响强度(默认值为 1.0)。增大此值会迫使模型更严格地遵循提供的关键帧。--ref_mode no_ref)在没有任何参考关键帧的情况下执行盲视频超分辨率。
MODEL_PATH="checkpoints/sparkvsr-s2/ckpt-500-sft"
CUDA_VISIBLE_DEVICES=0 python sparkvsr_inference_script.py \
--input_dir datasets/test/UDM10/LQ-Video \
--model_path $MODEL_PATH \
--output_path results/UDM10/no_ref \
--gt_dir datasets/test/UDM10/GT-Video \
--is_vae_st \
--ref_mode no_ref \
--ref_prompt_mode fixed \
--ref_guidance_scale 1.0 \
--eval_metrics psnr,ssim,lpips,dists,clipiqa \
--upscale 4--ref_mode api)使用商业 API 修复的关键帧作为条件信号。SparkVSR 默认使用性能出色的 fal-ai/nano-banana-pro/edit 端点。
⚠️ 设置要求:
- 打开
finetune/utils/ref_utils.py。- 找到文件顶部的配置块。
- 将
'your_fal_key'替换为您实际的 API 密钥。- (可选)在同一文件中自定义
TASK_PROMPT,以更好地指导修复过程。
MODEL_PATH="checkpoints/sparkvsr-s2/ckpt-500-sft"
CUDA_VISIBLE_DEVICES=0 python sparkvsr_inference_script.py \
--input_dir datasets/test/UDM10/LQ-Video \
--model_path $MODEL_PATH \
--output_path results/UDM10/api_ref \
--gt_dir datasets/test/UDM10/GT-Video \
--is_vae_st \
--ref_mode api \
--ref_prompt_mode fixed \
--ref_guidance_scale 1.0 \
--eval_metrics psnr,ssim,lpips,dists,clipiqa \
--upscale 4 \
--ref_indices 0--ref_mode pisasr)使用开源 PiSA-SR 模型修复的关键帧。
⚠️ 设置要求:
- 克隆 PiSA-SR 仓库 并按照其说明在单独的 Conda 环境中安装依赖。
- 下载其预训练权重(
stable-diffusion-2-1-base和pisa_sr.pkl)。- 更新
sparkvsr_inference.sh中的--pisa_*标志,以指向实际克隆的 PiSA-SR 目录、环境和所需的 GPU。
MODEL_PATH="checkpoints/sparkvsr-s2/ckpt-500-sft"
CUDA_VISIBLE_DEVICES=0 python sparkvsr_inference_script.py \
--input_dir datasets/test/UDM10/LQ-Video \
--model_path $MODEL_PATH \
--output_path results/UDM10/pisa_ref \
--gt_dir datasets/test/UDM10/GT-Video \
--is_vae_st \
--ref_mode pisasr \
--ref_prompt_mode fixed \
--ref_guidance_scale 1.0 \
--eval_metrics psnr,ssim,lpips,dists,clipiqa \
--upscale 4 \
--ref_indices 0 \
--pisa_python_executable "path/to/your/pisasr/conda/env/bin/python" \
--pisa_script_path "path/to/your/PiSA-SR/test_pisasr.py" \
--pisa_sd_model_path "path/to/your/PiSA-SR/preset/models/stable-diffusion-2-1-base" \
--pisa_chkpt_path "path/to/your/PiSA-SR/preset/models/pisa_sr.pkl" \
--pisa_gpu "0"💡 注意: 上述所有三种推理模式及其完整执行命令均已整理完毕,并可在
sparkvsr_inference.sh脚本中直接运行!
为了对超分辨率视频进行定量评估,我们提供了一个统一的评估脚本:run_eval_all.sh。
⚠️ 评估环境设置要求: 若要计算 DOVER 和 FastVQA/FasterVQA 分数,您必须克隆它们各自的仓库并将其(连同权重)放置到
metrics/目录中。
- 将 VQAssessment/DOVER 克隆到
metrics/DOVER。- 将 VQAssessment/FAST-VQA-and-FasterVQA 克隆到
metrics/FastVQA。- 下载其仓库中指定的预训练权重,并将其放入各自的嵌套算法文件夹中。
指标设置完成后,您只需运行统一评估脚本 run_eval_all.sh 即可计算分数。评估结果将保存为 all_metrics_results.json 并存储在您指定的输出目录中。
如果您发现本代码对您的研究或工作有所帮助,请引用以下论文。
@misc{yu2026sparkvsrinteractivevideosuperresolution,
title={SparkVSR: Interactive Video Super-Resolution via Sparse Keyframe Propagation},
author={Jiongze Yu and Xiangbo Gao and Pooja Verlani and Akshay Gadde and Yilin Wang and Balu Adsumilli and Zhengzhong Tu},
year={2026},
eprint={2603.16864},
archivePrefix={arXiv},
primaryClass={cs.CV},
url={https://arxiv.org/abs/2603.16864},
}本研究的工作建立在 DOVE 和 CogVideoX 奠定的坚实基础之上。我们衷心感谢这些项目的作者所做出的卓越开源贡献。