PaddleFormers 中 realsr 图像/视频 4 倍超分辨率模型实战指南

原创2026-09-22 14:38:061,386 阅读
文章标签:人工智能深度学习微调迁移学习模型推理服务本地部署NLP计算机视觉CLI

PaddleFormers 中 realsr 图像/视频 4 倍超分辨率模型实战指南

realsr 是 PaddleFormers(PaddleHub)仓库中面向真实世界图像/视频的超分辨率(Super Resolution)预训练模块,基于 "Toward Real-World Single Image Super-Resolution: A New Benchmark and A New Model" 提出,可将输入图片或视频放大 4 倍并显著恢复细节。本文以 realsr 官方模块文档 为主体,结合仓库内 module.py、rrdb.py、utils.py 与 test.py 源码,完整讲解从环境安装、模型加载、图片/视频预测到 PaddleHub Serving 在线服务部署的实战流程,并深入剖析底层网络结构与推理链路,帮助你直接上手复现图像与视频超分能力。

一、模型基本信息

realsr 模块位于仓库 modules/image/Image_editing/super_resolution/realsr/ 目录下,官方文档给出的核心信息如下:

项目 说明
模块名称 realsr
类别 图像-图像编辑
网络 LP-KPN
数据集 RealSR dataset
是否支持 Fine-tuning 否
模型大小 64MB
PSNR 29.05
最新更新日期 2021-02-26

说明:文档信息表中的"网络"标注为 LP-KPN;从仓库源码看,本模块的实际推理实现采用的是 RRDB(Residual in Residual Dense Block) 主干网络,即 rrdb.py 中的 RRDBNet(3, 3, 64, 23)。撰写与引用时建议以源码实现为准。

realsr 属于"图像-图像编辑"类目下的超分辨率模型,针对真实世界退化图像(如模糊、噪声、压缩伪影)进行重建,输出为原始分辨率的 4 倍放大结果。由于模块不支持 Fine-tuning,使用方式集中在加载预训练权重进行预测与服务化部署两条路径。

二、环境准备与安装

1、环境依赖

使用 realsr 模块前需要满足以下运行环境:

  • paddlepaddle >= 2.0.0
  • paddlehub >= 2.0.0

注意: 视频超分依赖 ffmpeg 完成视频拆帧与合帧,使用视频预测功能前必须自行安装 ffmpeg。若你使用 conda 环境,官方推荐使用如下命令安装指定版本:

$ conda install x264=='1!152.20180717' ffmpeg=4.0.2 -c conda-forge

2、安装模块

安装 realsr 模块的命令非常简单:

$ hub install realsr

如需安装指定历史版本(如 1.1.0),可执行:

$ hub install realsr == 1.1.0

若安装过程中遇到环境问题,可参考仓库内的零基础安装文档:

三、源码结构:一次完整的推理链路

realsr 模块目录包含 5 个文件,各自职责清晰:

文件 职责
module.py 模块主体,定义 RealSRPredictor 类,封装模型加载、图像/视频超分、Serving 方法
rrdb.py RRDB 生成器网络定义(ResidualDenseBlock_5C、RRDB、RRDBNet)
utils.py 工具函数:视频拆帧/合帧、图片判断、base64 编解码
test.py unittest 测试用例,验证 run_image 与 predict 行为
README.md 模块使用文档(本文主体)

1、模块注册与权重加载

module.py 通过 @moduleinfo 装饰器声明模块元信息(name="realsr"、type="CV/image_editing"、version="1.1.0"),使该类可被 hub.Module(name='realsr') 加载(对应机制见 paddlehub/module/module.py 中的 moduleinfo 与 init_with_name 实现)。

构造函数中,self.model = RRDBNet(3, 3, 64, 23) 创建网络(3 输入通道、3 输出通道、64 基础特征通道、23 个 RRDB 块)。权重加载逻辑为:

  • 若传入 load_checkpoint 参数,则从指定路径加载自定义权重(paddle.load + load_dict);
  • 否则自动查找模块目录下的 DF2K_JPEG.pdparams 预训练权重,不存在时通过 wget 从 paddlegan.bj.bcebos.com 下载后加载。

加载完成后调用 self.model.eval() 切换到推理模式,并在 run_image 中使用 paddle.no_grad() 关闭梯度计算。

2、RRDB 网络结构解析

rrdb.py 实现了经典的 RRDB 生成器,核心组件如下:

  • ResidualDenseBlock_5C(RDB):5 个卷积层组成的密集连接块。每一层以"之前所有层输出的拼接"作为输入,中间特征以 gc=32 的增长通道逐层扩展,最后一层输出回 nf 通道,并通过 x5 * 0.2 + x 的残差缩放(residual scaling,系数 0.2)稳定训练。
  • RRDB:将 3 个 RDB 串联,输出再做 out * 0.2 + x 的残差连接,即"Residual in Residual"。
  • RRDBNet:整体结构为 conv_first → RRDB_trunk(23 个 RRDB) → trunk_conv → 两次 2× 上采样 → HRconv → conv_last。两次 F.interpolate(scale_factor=2, mode='nearest') 配合 upconv1/upconv2 实现总计 4 倍空间分辨率放大,这正是"超分四倍"的实现来源。

从源码结构可以看出:输入的 BGR/RGB 图像经 norm 归一化(像素除以 255、通道维度转置为 [C, H, W])后送入网络,输出再经 denorm 还原为 [H, W, C] 的 uint8 图像。

3、视频处理的 ffmpeg 依赖

utils.py 中 video2frames 调用系统 ffmpeg 将视频按 %08d.png 格式拆帧,frames2video 再按原视频帧率(fps,由 cv2.VideoCapture 读取)将超分后的帧合成为 mp4。run_video 的完整流程为:

  1. 在 output/RealSR/<视频名>/ 下建立输出目录;
  2. 用 ffmpeg 将视频拆分为单帧 PNG;
  3. 逐帧调用 run_image 超分并保存到 frames_pred/;
  4. 用 ffmpeg 将超分帧合成为 <视频名>_realsr_out.mp4。

这就是文档强调"必须安装 ffmpeg"的根本原因;若 ffmpeg 缺失或执行失败,utils.py 会抛出 RuntimeError。

四、模型 API 预测

1、预测代码示例

安装完成后,只需三行代码即可完成一次图片(或视频)超分预测:

import paddlehub as hub

model = hub.Module(name='realsr')
model.predict('/PATH/TO/IMAGE')

# model.predict('/PATH/TO/VIDEO')

predict 内部会先通过 utils.is_image 判断输入是图片还是视频:图片走 run_image,视频走 run_video。

2、API 详解

def predict(self, input)

超分总入口 API,自动识别输入类型并得到超分后的图片或视频。

  • 参数
    • input (str):图片或者视频的路径。
  • 返回
    • 若输入是图片,返回二元组:
      • pred_img (np.ndarray):BGR 格式图片数据,shape 为 [H, W, C];
      • out_path (str):保存图片路径(默认为 output/RealSR/<图片名>.png)。
    • 若输入是视频,返回二元组:
      • frame_pattern_combined (str):视频超分后单帧数据保存路径模式(frames_pred/%08d.png);
      • vid_out_path (str):合成后的视频保存路径(<视频名>_realsr_out.mp4)。

从 module.py 源码可见,predict 的默认输出目录由 self.output = os.path.join(output, 'RealSR') 决定(output 默认为 'output'),即结果统一落在 output/RealSR/ 下。

def run_image(self, img)

图像超分 API,返回超分后的图片。

  • 参数
    • img (str|np.ndarray):图片路径,或 BGR 格式的 numpy 数组;源码同时兼容 PIL.Image.Image 输入。
  • 返回
    • pred_img (np.ndarray):BGR 格式超分结果,shape 为 [H, W, C]。

def run_video(self, video)

视频超分 API,返回超分后的视频。

  • 参数
    • video (str):待处理视频路径。
  • 返回
    • frame_pattern_combined (str):视频超分后单帧数据保存路径;
    • vid_out_path (str):视频保存路径。

3、测试用例佐证

仓库内的 test.py 用 unittest 验证了 API 行为,可作为使用方式的参考:

  • test_run_image1:传入图片字符串路径,断言返回结果为 np.ndarray;
  • test_run_image2:传入 cv2.imread 读出的 BGR ndarray,同样断言返回 ndarray;
  • test_run_image3:传入不存在的路径,断言抛出 FileNotFoundError;
  • test_predict1:predict 返回 (pred_img, out_path),分别断言为 ndarray 与 str;
  • test_predict2:对不存在的输入,断言抛出 RuntimeError。

五、服务部署:PaddleHub Serving 在线超分服务

PaddleHub Serving 可以将 realsr 部署为一个在线图像超分 HTTP 服务,便于以 API 形式对外提供能力。

第一步:启动 PaddleHub Serving

执行如下命令启动服务:

$ hub serving start -m realsr

执行完成后即完成图像超分在线服务 API 的部署,默认端口号为 8866。

注意: 如果使用 GPU 预测,需要在启动服务之前设置 CUDA_VISIBLE_DEVICES 环境变量,否则无需设置。

从服务端源码看,http_server.py 通过 Flask 暴露 POST /predict/<module_name> 接口(Windows 下直接运行 Flask,Linux 下基于 gunicorn),请求经 ZeroMQ 转发到 worker.py 中的推理 Worker,最终调用模块上以 @serving 装饰的 serving_method 完成预测并返回结果。realsr 的 serving_method(见 module.py)接收 base64 编码的图片,解码为 BGR ndarray 后调用 run_image 超分,再将结果编码回 base64 返回。

第二步:发送预测请求

配置好服务端后,以下代码即可发送预测请求并获取结果:

import requests
import json
import base64

import cv2
import numpy as np

def cv2_to_base64(image):
    data = cv2.imencode('.jpg', image)[1]
    return base64.b64encode(data.tostring()).decode('utf8')

def base64_to_cv2(b64str):
    data = base64.b64decode(b64str.encode('utf8'))
    data = np.fromstring(data, np.uint8)
    data = cv2.imdecode(data, cv2.IMREAD_COLOR)
    return data

# 发送HTTP请求
org_im = cv2.imread('/PATH/TO/IMAGE')
data = {'images': cv2_to_base64(org_im)}
headers = {"Content-type": "application/json"}
url = "http://127.0.0.1:8866/predict/realsr"
r = requests.post(url=url, headers=headers, data=json.dumps(data))
img = base64_to_cv2(r.json()["results"])
cv2.imwrite('/PATH/TO/SAVE/IMAGE', img)

请求体中 images 字段为 JPEG 编码后的 base64 字符串;响应中的 results 字段为超分结果图像的 base64 数据,解码后即可写回本地图片文件。

六、更新历史

版本 更新内容
1.0.0 初始发布
1.0.1 适配 paddlehub 2.0 版本
1.1.0 更新代码格式

如需安装指定版本,可执行:

$ hub install realsr == 1.1.0

七、小结与实践建议

realsr 模块提供了开箱即用的 4 倍超分能力,覆盖图片与视频两类输入,且支持通过 PaddleHub Serving 快速服务化。实践中需要注意以下几点:

  1. 图片预测:直接使用 model.predict(图片路径) 或 model.run_image(...),结果保存在 output/RealSR/ 下;
  2. 视频预测:务必预先安装 ffmpeg(推荐 conda install x264=='1!152.20180717' ffmpeg=4.0.2 -c conda-forge),否则拆帧/合帧会抛 RuntimeError;
  3. GPU 加速:Serving 部署前设置 CUDA_VISIBLE_DEVICES 环境变量即可切换 GPU 推理;
  4. 模型局限:realsr 不支持 Fine-tuning,若需针对特定场景微调,可参考仓库中 super_resolution 目录 下的其他超分模块(如 dcscn、falsr_a/b/c、swinir 系列)按需选择。

结合 README.md 与源码,你可以快速在本地复现 realsr 的图像/视频超分效果,并基于 PaddleHub Serving 将其集成到自己的业务服务中。

登录后查看全文
PaddleFormers