使用 PaddleHub 部署 SwinIR-L 现实图像 4 倍超分辨率模型:安装、API 预测与服务化部署全指南

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

使用 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 主干实现可以看到,模型整体分为三个子模块:

  1. 浅层特征提取(Shallow Feature Extraction):一个 Conv2D 卷积(conv_first)将输入的 3 通道图像映射到 embed_dim 维特征空间;
  2. 深层特征提取(Deep Feature Extraction):由多个 RSTB(Residual Swin Transformer Block) 堆叠而成,每个 RSTB 内部包含若干 Swin Transformer Block,Swin Transformer Block 的核心是 WindowAttention(基于窗口的 W-MSA / SW-MSA 多头自注意力,带相对位置偏置),并通过 PatchMerging 完成下采样;
  3. 高质量图像重建(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 信息并安全终止进程。

五、参考资料

六、更新历史

  • 1.0.0(初始发布):提供基于 SwinIR-L 的 4 倍现实图像超分辨率能力,支持命令行、Python API 与 Serving 三种调用方式。
登录后查看全文
PaddleFormers