PaddleHub Swin2SR 图像超分辨率模型实战指南:从安装部署到 4 倍现实图像复原

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

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.0
  • paddlehub >= 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__,整个网络可分为三部分:

  1. 浅层特征提取:conv_first 用 3×3 卷积将输入从 3 通道映射到 embed_dim 维;
  2. 深层特征提取:主干由多层 RSTB(残差 Swin Transformer 块)堆叠而成,每个 RSTB 内部是若干 Swin Transformer Block + 残差卷积连接(resi_connection),最后经过 norm 层与 conv_after_body;
  3. 高质量图像重建:依据 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 压缩伪影去除等其他复原任务。

登录后查看全文
PaddleFormers