HuggingFace镜像/SparkVSR
模型介绍文件和版本分析
下载使用量0

SparkVSR:基于稀疏关键帧传播的交互式视频超分辨率

余炅泽1、高向博1、Pooja Verlani2、Akshay Gadde2、 王艺霖2、Balu Adsumilli2、涂 Zhengzhong†,1

1德克萨斯 A&M 大学    2YouTube, Google
†通讯作者

   

📰 新闻

  • 2026.03.17: 本代码库正式发布。🔥🔥🔥

摘要: 视频超分辨率(VSR)旨在从低分辨率(LR)估计中恢复高质量视频帧,然而大多数现有 VSR 方法在推理时表现得像黑盒:用户无法可靠地修正意外伪影,只能被动接受模型生成的结果。 本文提出了一种名为 SparkVSR 的新型交互式 VSR 框架,该框架将稀疏关键帧作为一种简单且富有表现力的控制信号。具体而言,用户可以首先使用任何现成的图像超分辨率(ISR)模型对一小部分关键帧进行超分辨率处理(或可选地进行编辑),然后 SparkVSR 将关键帧先验信息传播到整个视频序列,同时保持与原始 LR 视频运动的一致性。 具体来说,我们引入了一种关键帧条件的潜像素两阶段训练流水线,该流水线将 LR 视频潜变量与稀疏编码的 HR 关键帧潜变量相融合,以学习稳健的跨空间传播并优化感知细节。在推理时,SparkVSR 支持灵活的关键帧选择(手动指定、编解码器 I 帧提取或随机采样)以及一种无参考引导机制,该机制持续平衡对关键帧的遵循度和盲修复,确保即使在参考关键帧缺失或不完美的情况下也能实现稳健性能。在多个 VSR 基准测试上的实验表明,该方法提高了时间一致性并具有优异的修复质量,在 CLIP-IQA、DOVER 和 MUSIQ 指标上分别超过基线方法高达 24.6%、21.8% 和 5.6%,实现了可控的、关键帧驱动的视频超分辨率。 此外,我们证明 SparkVSR 是一个通用的交互式、关键帧条件视频处理框架,可直接应用于未见过的任务,如老电影修复和视频风格迁移。


推理流程


训练流程

🔖 待办事项

  • ✅ 发布推理代码。
  • ✅ 发布预训练模型。
  • ✅ 发布训练代码。
  • ✅ 发布项目页面。

⚙️ 依赖项

  • Python 3.10+
  • PyTorch >= 2.5.0
  • Diffusers
  • 其他依赖项(详见 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

📖 目录

  1. 数据集
  2. 模型
  3. 训练
  4. 推理
  5. 引用
  6. 致谢

📁 数据集

🗳️ 训练数据集

我们的模型与 DOVE 使用相同的数据集进行训练:HQ-VSR 和 DIV2K-HR。所有数据集应放置在 datasets/train/ 目录下。

数据集类型视频/图像数量下载链接
HQ-VSR视频2,055Google Drive
DIV2K-HR图像800官方链接

所有数据集应遵循以下结构:

datasets/
└── train/
    ├── HQ-VSR/
    └── DIV2K_train_HR/

🗳️ 测试数据集

我们使用多个真实世界和合成测试数据集进行评估。所有数据集均遵循一致的目录结构:

数据集类型视频数量平均帧数下载地址
UDM10合成数据1032Google Drive
SPMCS合成数据3032Google Drive
YouHQ40合成数据4032Google Drive
RealVSR真实世界数据5050Google Drive
MovieLQ老电影数据10192Google 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-500

🔨 推理

  • 运行推理前,请确保已下载相应的预训练模型和测试数据集。
  • 完整的推理命令在 shell 脚本 sparkvsr_inference.sh 中提供。

SparkVSR 通过三种主要推理模式(--ref_mode)支持灵活的关键帧传播。

🌟 全局自定义参数

无论选择哪种模式,都可以使用以下参数自定义时间传播行为:

  • --ref_indices:指定要用作参考的关键帧索引(从 0 开始)。
    • 示例:--ref_indices 0 16 32
    • ⚠️ 重要:任意两个参考帧索引之间的间隔必须严格大于 4。
  • --ref_guidance_scale:控制参考关键帧对输出视频的影响强度(默认值为 1.0)。增大此值会迫使模型更严格地遵循提供的关键帧。

1️⃣ 无参考模式(--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

2️⃣ API 模式(--ref_mode api)

使用商业 API 修复的关键帧作为条件信号。SparkVSR 默认使用性能出色的 fal-ai/nano-banana-pro/edit 端点。

⚠️ 设置要求:

  1. 打开 finetune/utils/ref_utils.py。
  2. 找到文件顶部的配置块。
  3. 将 'your_fal_key' 替换为您实际的 API 密钥。
  4. (可选)在同一文件中自定义 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

3️⃣ PiSA-SR 模式(--ref_mode pisasr)

使用开源 PiSA-SR 模型修复的关键帧。

⚠️ 设置要求:

  1. 克隆 PiSA-SR 仓库 并按照其说明在单独的 Conda 环境中安装依赖。
  2. 下载其预训练权重(stable-diffusion-2-1-base 和 pisa_sr.pkl)。
  3. 更新 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/ 目录中。

  1. 将 VQAssessment/DOVER 克隆到 metrics/DOVER。
  2. 将 VQAssessment/FAST-VQA-and-FasterVQA 克隆到 metrics/FastVQA。
  3. 下载其仓库中指定的预训练权重,并将其放入各自的嵌套算法文件夹中。

指标设置完成后,您只需运行统一评估脚本 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 奠定的坚实基础之上。我们衷心感谢这些项目的作者所做出的卓越开源贡献。