PaddleHub 中 SwinIR-M 实现 4 倍现实图像超分辨率:swinir_m_real_sr_x4 模块安装、预测与 Serving 部署全指南

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

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_sr API 的参数细节与返回格式,并能结合仓库源码理解其预处理/后处理流程与 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 网络整体可分为三个部分:

  1. 浅层特征提取:conv_first 为一个 3×3 卷积,将输入从 3 通道映射到 embed_dim=180 维特征;
  2. 深层特征提取:由 6 个 RSTB(Residual Swin Transformer Block) 堆叠而成。每个 RSTB 内部是若干 SwinTransformerBlock(W-MSA/SW-MSA 交替,即偶数层不 shift、奇数层 shift 半个窗口,配合 calculate_mask 生成注意力掩码),残差路径上使用 resi_connection='1conv' 的卷积块,并在整体上保留全局残差连接(conv_after_body(...) + x);
  3. 高质量图像重建:本模型采用 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
    

七、使用建议与注意事项

  1. 输入输出格式:real_sr 的输入输出均为 BGR 格式 ndarray,输出尺寸为输入的 4 倍(宽高各放大 4 倍);如果输入宽高不是 window_size=8 的整数倍,网络内部会自动 reflect 填充后处理,无需手动裁剪。
  2. 推理资源:模型大小约 66.8MB,属于 SwinIR-M 中等规格,CPU 上即可完成推理;如需批量处理或追求更高吞吐,可参考 Serving 部署章节使用 GPU 模式。
  3. 适用场景:该模型面向真实世界图像(存在模糊、噪声等退化)的 4 倍放大,适合老照片增强、监控/抓拍图放大等场景;仓库中另有 swinir_l_real_sr_x4(SwinIR-L,142.2MB,精度更高)与 swinir_m_real_sr_x2(2 倍版本)可供按需选择,其 API 用法与本文完全一致。
登录后查看全文
PaddleFormers