使用 PaddleHub 部署 SwinIR-L 现实图像 4 倍超分辨率模型:安装、API 预测与服务化部署全指南
使用 PaddleHub 部署 SwinIR-L 现实图像 4 倍超分辨率模型:安装、API 预测与服务化部署全指南
导读
本文围绕 PaddleFormers 仓库中 swinir_l_real_sr_x4 模块,系统讲解如何在 PaddleHub 生态中安装、调用与部署一个基于 SwinIR-L 架构的 4 倍现实图像超分辨率模型。你将掌握命令行预测、Python API 调用、Serving 在线服务化部署的完整流程,并深入理解 SwinIR 网络结构、模块预处理/后处理逻辑以及 PaddleHub 的 runnable/serving 装饰器机制,从而能够将该模型快速集成到自己的图像处理业务中。
一、模型基本信息
模型概览
swinir_l_real_sr_x4 是一个基于 SwinIR(Image Restoration Using Swin Transformer) 架构的现实图像超分辨率(Real-World Image Super-Resolution)模型,对应下表所列的基本属性:
| 项目 | 说明 |
|---|---|
| 模型名称 | swinir_l_real_sr_x4 |
| 类别 | 图像-图像编辑 |
| 网络 | SwinIR |
| 数据集 | DIV2K / Flickr2K |
| 是否支持 Fine-tuning | 否 |
| 模型大小 | 142.2MB |
| 指标 | - |
| 最新更新日期 | 2022-10-10 |
从源码角度进一步确认:模块实体定义在 module.py 中,其 moduleinfo 元信息标明 type="CV/image_editing"、version='1.0.0',模型权重文件为 003_realSR_BSRGAN_DFOWMFC_s64w8_SwinIR-L_x4_GAN.pdparams,网络结构定义在 swinir.py。
网络结构
SwinIR 是清华大学 2021 年提出的基于 Swin Transformer 的图像恢复模型,论文为《SwinIR: Image Restoration Using Swin Transformer》(arXiv:2108.10257)。它抛弃了传统 CNN 超分网络(如 SRCNN、EDSR、RCAN)的纯卷积堆叠范式,改用 Transformer 中的自注意力机制来建模图像内部的全局与局部依赖关系。
从 swinir.py 的 SwinIR 主干实现可以看到,模型整体分为三个子模块:
- 浅层特征提取(Shallow Feature Extraction):一个
Conv2D卷积(conv_first)将输入的 3 通道图像映射到embed_dim维特征空间; - 深层特征提取(Deep Feature Extraction):由多个 RSTB(Residual Swin Transformer Block) 堆叠而成,每个 RSTB 内部包含若干 Swin Transformer Block,Swin Transformer Block 的核心是 WindowAttention(基于窗口的 W-MSA / SW-MSA 多头自注意力,带相对位置偏置),并通过
PatchMerging完成下采样; - 高质量图像重建(High Quality Image Reconstruction):本模块使用
upsampler='nearest+conv'策略,即“最近邻插值 + 卷积”的渐进上采样,官方原版实现中该策略专为现实世界超分设计,相比像素重组(PixelShuffle)能产生更少的伪影(artifact)。
swinir_l_real_sr_x4 对应的 SwinIR-L 大模型配置,在 module.py 中体现为:
upscale=4:4 倍放大;in_chans=3、img_size=64、window_size=8:输入 3 通道图像,窗口尺寸为 8;depths=[6, 6, 6, 6, 6, 6, 6, 6, 6]:9 个阶段(Stage),每阶段 6 个 Swin Transformer Block;embed_dim=240:特征嵌入维度 240;num_heads=[8, 8, 8, 8, 8, 8, 8, 8, 8]:每个阶段 8 个注意力头;mlp_ratio=2:MLP 隐藏层维度为嵌入维度的 2 倍;resi_connection='3conv':残差连接前的卷积块采用 3 层卷积结构(Conv3x3 -> LeakyReLU -> Conv1x1 -> LeakyReLU -> Conv3x3,中间通道压缩为 1/4 以节省参数与显存)。
作为对比,同目录下的 swinir_m_real_sr_x4 是 SwinIR-M 中型配置(depths 为 6 个阶段、embed_dim=180、num_heads 为 6、resi_connection='1conv'),模型更小、推理更快;而本文的 L 版本在特征表达上更强。
适用场景
该模型针对 现实拍摄图像(含噪声、模糊、压缩伪影等退化)的超分辨率重建,而非理想化的合成退化图像。典型的落地场景包括:老照片/旧影像清晰化、监控与安防图像的细节增强、移动端拍摄照片的放大提质、以及作为图像编辑流水线的前置增强环节。
二、安装
1、环境依赖
运行该模块需要满足以下基础环境:
- paddlepaddle >= 2.0.0
- paddlehub >= 2.0.0
同时模块运行时依赖 opencv-python(用于图像读取、色彩空间转换与保存)、numpy 等常用库;由于图像编解码与 Serving 请求处理还会用到 requests、base64。建议在 Python 3.6+ 环境中安装,若需 GPU 加速,请安装对应 CUDA 版本的 paddlepaddle-gpu。
2、安装模块
通过 PaddleHub 一条命令即可完成模块安装(安装过程会自动下载约 142.2MB 的预训练权重):
$ hub install swinir_l_real_sr_x4
如需指定版本安装,可追加版本号(当前仓库中该模块版本为 1.0.0):
$ hub install swinir_l_real_sr_x4==1.0.0
安装完成后可使用 hub show swinir_l_real_sr_x4 查看模块信息。如安装时遇到环境问题,可参考 PaddleHub 的零基础安装文档:零基础 Windows 安装 | 零基础 Linux 安装 | 零基础 MacOS 安装。
三、模型 API 预测
1、命令行预测
安装完成后,可直接通过 hub run 命令对单张图片做 4 倍超分辨率:
$ hub run swinir_l_real_sr_x4 \
--input_path "/PATH/TO/IMAGE" \
--output_dir "swinir_l_real_sr_x4_output"
其中:
--input_path:待处理图片路径(必填);--output_dir:结果保存目录,默认值为swinir_l_real_sr_x4_output。
命令行入口的底层实现位于 module.py 的 run_cmd 方法,该方法通过 argparse 解析上述两个参数后调用 real_sr() 完成推理,并在命令行末尾打印 Results are saved in %s 提示结果保存位置。PaddleHub 的 hub run 命令由 paddlehub/commands/run.py 统一调度:它会先通过 Module(name=...) 加载模块,检查 is_runnable,然后调用被 @runnable 装饰的 run_cmd 方法。
2、预测代码示例
在 Python 中以代码方式调用同样非常简洁:
import paddlehub as hub
import cv2
module = hub.Module(name="swinir_l_real_sr_x4")
result = module.real_sr(
image=cv2.imread('/PATH/TO/IMAGE'),
visualization=True,
output_dir='swinir_l_real_sr_x4_output'
)
返回的 result 是一个 numpy.ndarray,即为放大 4 倍后的超分辨率结果图像(BGR 格式),可直接用 cv2.imwrite() 保存或交给下游图像处理逻辑继续使用。
3、API 说明
模块对外暴露的超分辨率 API 签名如下:
def real_sr(
image: Union[str, numpy.ndarray],
visualization: bool = True,
output_dir: str = "swinir_l_real_sr_x4_output"
) -> numpy.ndarray
参数
image(Union[str, numpy.ndarray]):输入图片。可以是图片文件路径字符串,也可以是numpy.ndarray,其 shape 为[H, W, C],BGR 格式;visualization(bool):是否将识别结果保存为图片文件,默认True;output_dir(str):保存处理结果的文件目录,默认swinir_l_real_sr_x4_output。
返回
res(numpy.ndarray):图像超分辨率结果(BGR),shape 为放大后的[4H, 4W, 3]。
实现细节解读(对应 module.py):
- 输入分支:当
image为字符串时,模块通过os.path.split提取文件名生成带时间戳的输出文件名(原文件名_时间戳.jpg),并用cv2.imdecode读取;当image为numpy.ndarray时直接使用;其他类型则抛出Exception("image should be a str / np.ndarray")。 - 预处理(preprocess):将 BGR 图像转换为 RGB(
cv2.cvtColor),调整维度顺序为(C, H, W),并归一化到[0, 1]区间(img / 255.0),最终转为float32。 - 推理:在
paddle.no_grad()上下文中将输入张量送入 SwinIR 网络,得到输出后转回 numpy 数组。 - 后处理(postprocess):将输出裁剪到
[0, 1]后乘回255.0,转置回(H, W, C),再转回 BGR 格式并转为uint8。 - 可视化保存:当
visualization=True时自动创建output_dir目录并写入结果图片。
测试用例佐证:仓库中的 test.py 对 API 的多种调用形态做了完整验证,包括字符串路径输入(test_real_sr1)、ndarray 输入且开启可视化(test_real_sr2/test_real_sr3)、非法类型输入抛异常(test_real_sr4,传入 list 触发 Exception)以及不存在的文件路径抛出 FileNotFoundError(test_real_sr5)。这为你在业务中正确传参提供了参考边界。
四、服务部署
除了单机预测,PaddleHub Serving 可以部署一个图像超分辨率的在线 HTTP 服务,便于接入 Web 应用、移动端或微服务架构。
第一步:启动 PaddleHub Serving
运行启动命令:
$ hub serving start -m swinir_l_real_sr_x4
这样就完成了一个图像超分辨率服务化 API 的部署,默认端口号为 8866。启动成功后,服务端会监听 0.0.0.0:8866,可通过浏览器访问 http://127.0.0.1:8866/ 查看服务状态。
底层机制说明:hub serving start 由 paddlehub/commands/serving.py 实现。命令解析阶段(parse_args)会为每个模块构造 modules_info,并支持 --port/-p 指定端口、--use_multiprocess 开启多进程(Windows 上自动回退单进程)、--use_gpu 使用 GPU、--config/-c 使用 JSON 配置文件等参数;随后 preinstall_modules() 会加载模块并取出被 @serving 装饰的方法(m.serving_func_name),最终由 Flask/Gunicorn 框架托管 HTTP 服务。模块的 serving 端点在 module.py 中实现:收到 base64 编码的图片字符串后解码为图像,调用 real_sr() 推理,再将结果编码回 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/swinir_l_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)
请求路径规则为 http://127.0.0.1:8866/predict/{module_name},请求体为 JSON 格式,image 字段存放 JPEG 编码后的 base64 字符串;响应中的 results 字段同样是 base64 编码的超分结果,解码后即可得到放大 4 倍的 BGR 图像。
停止服务:如需关闭该 Serving 服务,可使用 hub serving stop -p 8866(-p 指定端口)。该操作会读取 serving.py 中记录的 PID 信息并安全终止进程。
五、参考资料
- 论文:SwinIR: Image Restoration Using Swin Transformer
- 官方实现:JingyunLiang/SwinIR
- 仓库内同系列模块:swinir_m_real_sr_x2、swinir_m_real_sr_x4、swin2sr_real_sr_x4,以及 PaddleHub Serving 服务端实现 paddlehub/serving。
六、更新历史
- 1.0.0(初始发布):提供基于 SwinIR-L 的 4 倍现实图像超分辨率能力,支持命令行、Python API 与 Serving 三种调用方式。