PaddleHub 中 SwinIR-M 实现 4 倍现实图像超分辨率:swinir_m_real_sr_x4 模块安装、预测与 Serving 部署全指南
PaddleHub 中 SwinIR-M 实现 4 倍现实图像超分辨率:swinir_m_real_sr_x4 模块安装、预测与 Serving 部署全指南
本文以 PaddleHub 仓库中的 swinir_m_real_sr_x4 模块文档为核心,系统讲解如何基于 Swin Transformer 的图像恢复模型 SwinIR,在 PaddlePaddle 环境下完成 4 倍现实图像超分辨率(Real-World Super Resolution)的安装、命令行与 Python API 预测,以及基于 PaddleHub Serving 的在线服务化部署。读完本文,你将掌握该模块的完整调用方式、
real_srAPI 的参数细节与返回格式,并能结合仓库源码理解其预处理/后处理流程与 SwinIR 网络结构,可直接用于实际图片的放大增强。
一、模型基本信息
| 模型名称 | swinir_m_real_sr_x4 |
|---|---|
| 类别 | 图像-图像编辑 |
| 网络 | SwinIR |
| 数据集 | DIV2K / Flickr2K |
| 是否支持 Fine-tuning | 否 |
| 模型大小 | 66.8MB |
| 指标 | - |
| 最新更新日期 | 2022-10-10 |
模型介绍
SwinIR 是一个基于 Swin Transformer 的图像恢复(Image Restoration)模型,其核心思路是将 Swin Transformer 的窗口自注意力机制引入底层视觉任务,在图像超分辨率、去噪、JPEG 压缩伪影去除等任务上均取得了很好的效果。
swinir_m_real_sr_x4 是基于 SwinIR-M(Medium 规格)的 4 倍现实图像超分辨率模型,与面向"干净/合成退化"图像的经典超分辨率(Classical SR)不同,它针对真实世界拍摄图片中存在的模糊、噪声、压缩等复杂复合退化进行建模,在放大 4 倍的同时尽可能抑制伪影(artifacts)。
从仓库源码 module.py 可以看到,该模块在构造 SwinIR 网络时使用的具体配置为:
upscale=4:放大倍数为 4;in_chans=3:输入为 3 通道彩色图像;img_size=64、window_size=8:输入 patch 尺寸 64,窗口大小 8;depths=[6, 6, 6, 6, 6, 6]:6 个阶段的 Swin Transformer 层深度均为 6;embed_dim=180:嵌入维度 180;num_heads=[6, 6, 6, 6, 6, 6]:各阶段注意力头数均为 6;mlp_ratio=2:MLP 隐藏层与嵌入维度的比率为 2;upsampler='nearest+conv':使用"最近邻插值 + 卷积"的上采样方式,该分支正是为真实世界超分辨率设计、以减少伪影;resi_connection='1conv':残差连接前的卷积块采用单层卷积。
模型加载的预训练权重为 003_realSR_BSRGAN_DFO_s64w8_SwinIR-M_x4_GAN.pdparams,即基于 BSRGAN/DFO 训练策略、以 GAN 方式训练得到的 SwinIR-M ×4 现实超分权重。权重加载后模型被置为 eval() 推理模式,且该模块不支持 Fine-tuning。
二、安装与环境依赖
1、环境依赖
- paddlepaddle >= 2.0.0
- paddlehub >= 2.0.0
2、安装
在满足上述依赖后,通过 PaddleHub 命令即可一键安装该模块:
$ hub install swinir_m_real_sr_x4
如需安装指定版本(当前仓库中模块版本为 1.0.0),可执行:
$ hub install swinir_m_real_sr_x4==1.0.0
如您在安装时遇到问题,可参考仓库内的零基础安装文档:零基础 Windows 安装 | 零基础 Linux 安装 | 零基础 MacOS 安装。
3、模块目录与源码构成
在仓库中,该模块的完整源码位于 modules/image/Image_editing/super_resolution/swinir_m_real_sr_x4/ 目录下:
- module.py:模块入口,定义
SwinIRMRealSR类,包含模型加载、预处理/后处理、real_sr预测 API、命令行入口与 Serving 方法; - swinir.py:SwinIR 网络的完整 Paddle 实现(
SwinIR、RSTB、SwinTransformerBlock、WindowAttention、PatchEmbed/PatchUnEmbed、Upsample等); - test.py:模块单元测试。
三、模型 API 预测
1、命令行预测
安装完成后,可直接通过 hub run 命令行对单张图片进行 4 倍超分辨率:
$ hub run swinir_m_real_sr_x4 \
--input_path "/PATH/TO/IMAGE" \
--output_dir "swinir_m_real_sr_x4_output"
--input_path:待处理的图片路径;--output_dir:结果保存目录,默认值为swinir_m_real_sr_x4_output。
从 module.py 中的 run_cmd 实现 可以看出,命令行入口的本质是解析 --input_path 与 --output_dir 两个参数后调用 self.real_sr(image=args.input_path, visualization=True, output_dir=args.output_dir),并将结果目录信息打印返回。
2、预测代码示例
在 Python 中通过 PaddleHub 加载模块并调用预测接口:
import paddlehub as hub
import cv2
module = hub.Module(name="swinir_m_real_sr_x4")
result = module.real_sr(
image=cv2.imread('/PATH/TO/IMAGE'),
visualization=True,
output_dir='swinir_m_real_sr_x4_output'
)
其中 cv2.imread 读入的图像为 BGR 格式的 numpy.ndarray,shape 为 [H, W, C]。real_sr 也支持直接传入图片文件路径字符串。
3、API 说明
def real_sr(
image: Union[str, numpy.ndarray],
visualization: bool = True,
output_dir: str = "swinir_m_real_sr_x4_output"
) -> numpy.ndarray
超分辨率 API
-
参数
image(Union[str, numpy.ndarray]):图片数据,ndarray.shape 为[H, W, C],BGR 格式;若传入字符串则视为图片文件路径;visualization(bool):是否将识别结果保存为图片文件;output_dir(str):保存处理结果的文件目录。
-
返回
res(numpy.ndarray):图像超分辨率结果(BGR 格式),shape 为[4H, 4W, 3]。
4、API 底层实现细节(源码级解读)
结合 module.py 中 real_sr 的实现,我们可以梳理出一次完整预测的内部流程:
(1)输入分发与保存文件名生成
- 若
image为字符串路径,则用os.path.split与os.path.splitext取出文件名主干,拼接当前时间戳生成形如{原名}_{时间戳}.jpg的保存文件名,并通过cv2.imdecode(np.fromfile(...))读取图片(np.fromfile方式可兼容中文路径); - 若
image为 ndarray,则以{时间戳}.jpg命名; - 其他类型直接抛出
Exception("image should be a str / np.ndarray"),与 test.py 中test_real_sr4的异常断言一致。
(2)预处理(preprocess)
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # BGR -> RGB
img = img.transpose((2, 0, 1)) # HWC -> CHW
img = img / 255.0 # 归一化到 [0, 1]
return img.astype(np.float32)
即完成 BGR→RGB 通道转换、HWC→CHW 维度重排与除以 255 的归一化,最终以 float32 输入网络。在推理阶段通过 paddle.no_grad() 关闭梯度,并将预处理后的数据经 paddle.to_tensor(img_input[None, ...], dtype=paddle.float32) 增加 batch 维后送入 self.swinir 前向计算。
(3)后处理(postprocess)
img = img.clip(0, 1) # 截断到 [0, 1]
img = img * 255.0 # 还原像素范围
img = img.transpose((1, 2, 0)) # CHW -> HWC
img = cv2.cvtColor(img, cv2.COLOR_RGB2BGR) # RGB -> BGR
return img.astype(np.uint8)
(4)可视化保存
当 visualization=True 时,若 output_dir 不存在则自动 os.makedirs 创建目录,随后将结果写入 output_dir 下的保存文件。
5、SwinIR 网络结构要点
swinir.py 中实现的 SwinIR 网络整体可分为三个部分:
- 浅层特征提取:
conv_first为一个3×3卷积,将输入从 3 通道映射到embed_dim=180维特征; - 深层特征提取:由 6 个 RSTB(Residual Swin Transformer Block) 堆叠而成。每个 RSTB 内部是若干
SwinTransformerBlock(W-MSA/SW-MSA 交替,即偶数层不 shift、奇数层 shift 半个窗口,配合calculate_mask生成注意力掩码),残差路径上使用resi_connection='1conv'的卷积块,并在整体上保留全局残差连接(conv_after_body(...) + x); - 高质量图像重建:本模型采用
upsampler='nearest+conv'分支,即对特征做scale_factor=2的最近邻插值后接卷积(×4 时执行两次),中间穿插LeakyReLU(negative_slope=0.2)激活,最终经conv_last输出 3 通道结果。
此外还有两个值得注意的实现细节:
- 均值减除:当
in_chans==3时,网络会减去 ImageNet 统计均值(0.4488, 0.4371, 0.4040)并乘以img_range=1.,前向结束后再除以img_range并加回均值(见 swinir.py forward); - 尺寸自适应:
check_image_size使用 reflect 填充将输入补齐为window_size=8的整数倍,前向输出后裁剪回H*upscale × W*upscale,因此实际使用时对输入图片的宽高没有严格限制。
6、单元测试验证
仓库提供了完整的单元测试 test.py,覆盖以下场景:
test_real_sr1:传入图片路径字符串且visualization=False,断言返回np.ndarray;test_real_sr2/test_real_sr3:传入cv2.imread读入的 ndarray 且开启可视化保存,断言返回np.ndarray;test_real_sr4:传入非法类型(list),断言抛出Exception;test_real_sr5:传入不存在的文件路径,断言抛出FileNotFoundError。
该测试同时印证了 API 对"路径字符串 / ndarray"两种输入形式的支持以及异常处理行为。
四、服务部署(PaddleHub Serving)
PaddleHub Serving 可以部署一个图像超分辨率的在线服务,将 swinir_m_real_sr_x4 封装为可通过 HTTP 调用的服务化 API。
第一步:启动 PaddleHub Serving
运行启动命令:
$ hub serving start -m swinir_m_real_sr_x4
这样就完成了一个图像超分辨率服务化 API 的部署,默认端口号为 8866。
从仓库源码 paddlehub/commands/serving.py 可以看到,--port/-p 参数默认值即为 8866,Serving 内部会对端口占用进行检查,并通过 --use_gpu、--workers 等参数控制运行模式(GPU 下走 ZMQ 多进程推理,CPU 下走 gunicorn/flask)。如需停止服务,可使用 hub serving stop --port 8866。
第二步:发送预测请求
配置好服务端后,以下代码即可实现发送预测请求并获取预测结果:
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/swinir_m_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)
Serving 请求链路说明
从模块源码角度看,Serving 的请求处理由 module.py 中的 serving_method 承担:服务端将收到的 base64 字符串通过 base64_to_cv2 还原为图像,调用 real_sr 完成超分,再经 cv2_to_base64 将结果编码为 base64 字符串返回给客户端,客户端再解码回 cv2 图像并保存。这一"base64 编码/解码"的对称设计,使得图片可以通过 JSON 在 HTTP 层安全传输。
五、参考资料
- 论文:SwinIR: Image Restoration Using Swin Transformer(SwinIR 原始论文,提出基于 Swin Transformer 的图像恢复框架);
- 官方实现:JingyunLiang/SwinIR(SwinIR 的 PyTorch 参考实现,本仓库的 swinir.py 即基于其结构使用 PaddlePaddle 完成移植,包括
RSTB、WindowAttention、nearest+conv上采样等核心组件)。
六、更新历史
-
1.0.0
初始发布,支持安装指定版本:
$ hub install swinir_m_real_sr_x4==1.0.0
七、使用建议与注意事项
- 输入输出格式:
real_sr的输入输出均为 BGR 格式 ndarray,输出尺寸为输入的 4 倍(宽高各放大 4 倍);如果输入宽高不是window_size=8的整数倍,网络内部会自动 reflect 填充后处理,无需手动裁剪。 - 推理资源:模型大小约 66.8MB,属于 SwinIR-M 中等规格,CPU 上即可完成推理;如需批量处理或追求更高吞吐,可参考 Serving 部署章节使用 GPU 模式。
- 适用场景:该模型面向真实世界图像(存在模糊、噪声等退化)的 4 倍放大,适合老照片增强、监控/抓拍图放大等场景;仓库中另有 swinir_l_real_sr_x4(SwinIR-L,142.2MB,精度更高)与 swinir_m_real_sr_x2(2 倍版本)可供按需选择,其 API 用法与本文完全一致。