PaddleHub Swin2SR 图像超分辨率模型实战指南:从安装部署到 4 倍现实图像复原
PaddleHub Swin2SR 图像超分辨率模型实战指南:从安装部署到 4 倍现实图像复原
导读:本文以 PaddleHub 中的 swin2sr_real_sr_x4 模块为核心,系统讲解基于 Swin Transformer V2 的 4 倍现实图像超分辨率(Real-World Super-Resolution)模型的完整使用链路——从环境安装、命令行预测、Python API 调用,到 PaddleHub Serving 在线服务化部署。读完本文,你将能够独立完成一张低分辨率、带压缩失真的图像到 4 倍高清图像的复原,并掌握其底层网络结构与推理流程的实现细节。
一、模型基本信息
swin2sr_real_sr_x4 是 PaddleHub 提供的一个图像超分辨率(Super-Resolution,SR)模块,其核心参数如下表所示:
| 模型名称 | swin2sr_real_sr_x4 |
|---|---|
| 类别 | 图像-图像编辑 |
| 网络 | Swin2SR |
| 数据集 | DIV2K / Flickr2K |
| 是否支持 Fine-tuning | 否 |
| 模型大小 | 68.4MB |
| 指标 | - |
| 最新更新日期 | 2022-10-25 |
1. 模型介绍
Swin2SR 是一个基于 Swin Transformer V2 的图像超分辨率模型,其思想来自论文 Swin2SR: SwinV2 Transformer for Compressed Image Super-Resolution and Restoration(arXiv:2209.11345)。与经典超分辨率任务只关注理想低分辨率(LR)到高分辨率(HR)的映射不同,**现实图像超分辨率(Real-World SR)**需要同时处理真实场景中普遍存在的模糊、噪声与 JPEG 压缩伪影。swin2sr_real_sr_x4 正是基于 Swin2SR 架构、面向现实退化图像的 4 倍(x4)超分辨率模型,输入任意尺寸的 BGR 图像,输出长宽各放大 4 倍的高清结果。
注意:该模块在仓库中标记为“不支持 Fine-tuning”,即它仅用于推理预测,不提供训练/微调入口。从 module.py 的初始化代码可以看出,模块加载的是预训练权重
Swin2SR_RealworldSR_X4_64_BSRGAN_PSNR.pdparams,并直接进入eval()推理模式。
二、安装
1. 环境依赖
使用该模块前,请确保环境中已安装以下依赖:
paddlepaddle >= 2.0.0paddlehub >= 2.0.0
2. 安装模块
在命令行中执行以下命令即可完成模块安装:
$ hub install swin2sr_real_sr_x4
如需指定版本安装(当前模块版本为 1.0.0):
$ hub install swin2sr_real_sr_x4==1.0.0
安装过程中会同时下载约 68.4MB 的预训练权重文件。如安装时遇到环境问题,可参考 PaddleHub 的零基础安装文档:
三、模型 API 预测
1. 命令行预测
安装完成后,可直接通过 hub run 命令完成单张图片的超分辨率推理:
$ hub run swin2sr_real_sr_x4 \
--input_path "/PATH/TO/IMAGE" \
--output_dir "swin2sr_real_sr_x4_output"
参数说明:
--input_path:待处理图片路径(必填);--output_dir:结果保存目录(可选,默认为swin2sr_real_sr_x4_output)。
从源码看,命令行入口对应 module.py 中的 run_cmd 方法,它被 @runnable 装饰器标记——在 PaddleHub 框架中,runnable 装饰器负责将模块方法注册为 hub run 命令的调用入口。命令执行后会将结果保存到指定目录,并返回提示信息 Results are saved in ...。
2. 预测代码示例
在 Python 脚本中调用则更加灵活:
import paddlehub as hub
import cv2
module = hub.Module(name="swin2sr_real_sr_x4")
result = module.real_sr(
image=cv2.imread('/PATH/TO/IMAGE'),
visualization=True,
output_dir='swin2sr_real_sr_x4_output'
)
其中 result 为超分辨率后的图像数组(numpy.ndarray,BGR 格式),可直接用 cv2.imwrite 保存或继续做后续处理。
3. API 详解
模块对外暴露的核心 API 签名如下:
def real_sr(
image: Union[str, numpy.ndarray],
visualization: bool = True,
output_dir: str = "swin2sr_real_sr_x4_output"
) -> numpy.ndarray
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
image |
Union[str, numpy.ndarray] |
必填 | 图片数据;可传图片文件路径(str),或 ndarray 格式的图像数据,ndarray.shape 为 [H, W, C],BGR 格式 |
visualization |
bool |
True |
是否将处理结果保存为图片文件 |
output_dir |
str |
"swin2sr_real_sr_x4_output" |
保存处理结果的文件目录 |
返回值
res(numpy.ndarray):图像超分辨率结果,BGR 格式。
输入校验与预处理细节(来自源码)
阅读 module.py 的 real_sr 实现可以发现如下行为:
- 当
image为str时,使用cv2.imdecode(np.fromfile(...))读取图片,输出文件名取原文件主名并追加时间戳(如cat_1663734773.jpg);当image为numpy.ndarray时直接使用,输出文件名仅含时间戳; - 若传入类型不是
str或ndarray,会抛出Exception("image should be a str / np.ndarray"); - 推理在
paddle.no_grad()上下文内执行; - 预处理
preprocess:BGR → RGB 通道转换、(H, W, C)→(C, H, W)转置、像素值归一化到[0, 1]并转为float32; - 后处理
postprocess:结果裁剪到[0, 1]区间、乘回 255、转回(H, W, C)布局并 RGB → BGR; visualization=True时会自动创建output_dir目录并写出结果图片。
单测验证:test.py 提供了 5 个用例,分别覆盖了字符串路径输入、ndarray 输入(含可视化保存)、非法类型输入(断言抛出 Exception)以及不存在的文件路径(断言抛出 FileNotFoundError)等场景,可作为调用方式的参考。
四、服务部署:PaddleHub Serving 在线化
PaddleHub Serving 可以将该模块部署为一个图像超分辨率在线服务,通过 HTTP 接口对外提供预测能力。
第一步:启动 PaddleHub Serving
$ hub serving start -m swin2sr_real_sr_x4
执行后即完成图像超分辨率服务化 API 的部署,默认端口号为 8866。服务端会在启动时预加载模块并注册 serving_method(由 module.py 中的 @serving 装饰器标记),该装饰器在 PaddleHub 框架中负责把方法注册为 Serving 的调用入口。从 serving 命令实现可以看到,除 -m 外还支持 --port/-p 自定义端口、--config/-c 加载配置文件、--use_gpu 指定 GPU 推理等参数;停止服务使用 hub serving stop -p 8866。
第二步:发送预测请求
服务端就绪后,以下代码即可实现发送预测请求并获取结果(请求与响应均以 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.tobytes()).decode('utf8')
def base64_to_cv2(b64str):
data = base64.b64decode(b64str.encode('utf8'))
data = np.frombuffer(data, np.uint8)
data = cv2.imdecode(data, cv2.IMREAD_COLOR)
return data
# 发送HTTP请求
org_im = cv2.imread('/PATH/TO/IMAGE')
data = {
'image': cv2_to_base64(org_im)
}
headers = {"Content-type": "application/json"}
url = "http://127.0.0.1:8866/predict/swin2sr_real_sr_x4"
r = requests.post(url=url, headers=headers, data=json.dumps(data))
# 结果转换
results = r.json()['results']
results = base64_to_cv2(results)
# 保存结果
cv2.imwrite('output.jpg', results)
上述 cv2_to_base64 / base64_to_cv2 工具函数与 module.py 中 Serving 侧的实现一一对应:服务端收到 base64 图像后解码为 ndarray,经 real_sr 推理后再编码回 base64 返回,客户端解码即可得到 4 倍超分结果。
五、底层实现:Swin2SR 网络结构剖析
为了帮助理解推理行为与参数意义,这里结合仓库中的 swin2sr.py 对网络结构作源码级说明。
1. 模块实例化的网络配置
在 module.py 中,Swin2SR 网络以如下配置实例化:
Swin2SR(upscale=4,
in_chans=3,
img_size=64,
window_size=8,
img_range=1.,
depths=[6, 6, 6, 6, 6, 6],
embed_dim=180,
num_heads=[6, 6, 6, 6, 6, 6],
mlp_ratio=2,
upsampler='nearest+conv',
resi_connection='1conv')
upscale=4:4 倍放大因子;in_chans=3:RGB 三通道输入;depths=[6,6,6,6,6,6]:6 个残差 Swin Transformer 块(RSTB),每个包含 6 层 Swin Transformer Block;embed_dim=180:嵌入维度;window_size=8:自注意力局部窗口大小;upsampler='nearest+conv':采用“最近邻插值 + 卷积”的重建方式——这是专门为现实超分设计的分支,源码注释指出该方式能产生更少的伪影(less artifacts),且当前仅支持 x4 放大(assert self.upscale == 4);resi_connection='1conv':残差连接前使用单个 3×3 卷积。
2. 网络三大组成部分
对照 swin2sr.py 的 __init__,整个网络可分为三部分:
- 浅层特征提取:
conv_first用 3×3 卷积将输入从 3 通道映射到embed_dim维; - 深层特征提取:主干由多层
RSTB(残差 Swin Transformer 块)堆叠而成,每个 RSTB 内部是若干 Swin Transformer Block + 残差卷积连接(resi_connection),最后经过norm层与conv_after_body; - 高质量图像重建:依据
upsampler选择不同分支。本模块的nearest+conv分支依次执行conv_before_upsample→ 两次“最近邻 ×2 上采样 + 3×3 卷积 + LeakyReLU”(conv_up1/conv_up2)→conv_hr→conv_last,从而把embed_dim特征逐步放大 4 倍并映射回 3 通道。
3. Swin Transformer V2 关键特性
模型内部还体现了 Swin V2 的多个技术点(见 WindowAttention 实现):
- 窗口自注意力(W-MSA / SW-MSA):通过
window_partition/window_reverse在局部窗口内计算多头自注意力,并通过交替的 shifted window 实现跨窗口信息交互; - 连续相对位置偏置(CPB):用一个 MLP(
cpb_mlp)从相对坐标表生成位置偏置,并对偏置做16 * sigmoid(...)缩放,这是 Swin V2 的关键改进; - 缩放余弦注意力(cosine attention):注意力得分先对 q、k 做 L2 归一化再点积,并乘以可学习的
logit_scale(上限裁剪为log(1/0.01)),提升训练稳定性; - 反射填充对齐窗口:
check_image_size使用 reflect 模式 pad 输入,使任意尺寸图像都能按window_size整除切窗,推理后裁剪回目标尺寸H*upscale × W*upscale。
六、参考资料
- 论文:Swin2SR: SwinV2 Transformer for Compressed Image Super-Resolution and Restoration(arXiv:2209.11345)
- 官方实现:mv-lab/swin2sr
七、更新历史
- 1.0.0:初始发布。
$ hub install swin2sr_real_sr_x4==1.0.0
结语
swin2sr_real_sr_x4 提供了一个开箱即用的现实图像 4 倍超分辨率方案:一行 hub install 完成安装,hub run 或 real_sr API 即可推理,hub serving 可将能力快速服务化。配合 module.py、swin2sr.py 与 test.py 的源码,开发者可以在此基础上进一步改造输入输出流程,或将同一 Swin2SR 骨架复用于去噪、JPEG 压缩伪影去除等其他复原任务。