PaddleFormers 中 realsr 图像/视频 4 倍超分辨率模型实战指南
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.0paddlehub >= 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 的完整流程为:
- 在
output/RealSR/<视频名>/下建立输出目录; - 用 ffmpeg 将视频拆分为单帧 PNG;
- 逐帧调用
run_image超分并保存到frames_pred/; - 用 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 快速服务化。实践中需要注意以下几点:
- 图片预测:直接使用
model.predict(图片路径)或model.run_image(...),结果保存在output/RealSR/下; - 视频预测:务必预先安装 ffmpeg(推荐
conda install x264=='1!152.20180717' ffmpeg=4.0.2 -c conda-forge),否则拆帧/合帧会抛RuntimeError; - GPU 加速:Serving 部署前设置
CUDA_VISIBLE_DEVICES环境变量即可切换 GPU 推理; - 模型局限:realsr 不支持 Fine-tuning,若需针对特定场景微调,可参考仓库中 super_resolution 目录 下的其他超分模块(如 dcscn、falsr_a/b/c、swinir 系列)按需选择。
结合 README.md 与源码,你可以快速在本地复现 realsr 的图像/视频超分效果,并基于 PaddleHub Serving 将其集成到自己的业务服务中。