PaddleHub falsr_a 轻量级图像超分辨率模块实战:安装、API 预测与 Serving/Gradio 部署全指南
PaddleHub falsr_a 轻量级图像超分辨率模块实战:安装、API 预测与 Serving/Gradio 部署全指南
本文以 PaddleFormers 仓库中 PaddleHub 官方发布的 falsr_a 超分辨率模块为核心,系统讲解其模型特性、安装方式、命令行与 Python API 预测、PaddleHub Serving 服务化部署及 Gradio APP 使用,并结合仓库内 module.py、data_feed.py、processor.py 等源码剖析其底层实现原理。读完本文,你将能够独立完成从安装、单张图片超分推理到将超分能力封装为 HTTP 在线服务的完整流程。
一、模块概览:一个 8.9MB 的 2 倍超分模型
falsr_a 是 PaddleHub 官方发布的一款轻量化图像超分辨率(Super Resolution)模块,归类于「图像-图像编辑」(Image editing)场景。其核心信息如下表:
| 项目 | 内容 |
|---|---|
| 模块名称 | falsr_a |
| 类别 | 图像-图像编辑(CV/image_editing) |
| 网络 | falsr_a |
| 数据集 | DIV2K |
| 是否支持 Fine-tuning | 否 |
| 模型大小 | 8.9MB |
| 数据指标 | PSNR 37.82 |
| 最新更新日期 | 2021-02-26 |
模型原理
falsr_a 基于论文 Fast, Accurate and Lightweight Super-Resolution with Neural Architecture Search(FALSR,由小米自动化机器学习团队提出)设计。其技术要点包括:
- 多目标优化:模型设计同时考虑超分精度(accuracy)与计算量(轻量化),通过多目标方法在两者之间取得平衡,从而在极小模型体积下获得较高 PSNR;
- 混合控制器弹性搜索:使用基于混合控制器的弹性搜索策略(elastic search strategy)自动搜索轻量且高性能的网络结构,显著提升模型性能;
- 2 倍超分:该模块提供 scale factor x2 的超分辨率输出,即输出图像的宽高均为输入图像的 2 倍。
从仓库源码可以印证其轻量化推理设计:module.py 中 Falsr_A 类在 __init__ 阶段直接加载预训练推理模型 falsr_a_model/model.pdmodel 与 model.pdiparams,并通过 paddle.inference 的 Config 与 create_predictor 构建 CPU/GPU 预测器,模块内不含可训练的网络层定义,这正是其「不支持 Fine-tuning」且体积仅 8.9MB 的原因。
二、环境依赖与模块安装
1. 环境依赖
使用 falsr_a 前需要满足以下依赖:
- paddlepaddle >= 2.0.0
- paddlehub >= 2.0.0
如需在 GPU 上进行预测,还需要正确配置 CUDA 环境,并在运行时通过环境变量 CUDA_VISIBLE_DEVICES 指定设备(详见下文 API 说明)。
2. 安装模块
在满足上述依赖后,通过 PaddleHub 命令行一键安装:
$ hub install falsr_a
安装完成后即可在任意 Python 脚本或命令行中调用该模块。若安装过程中遇到环境问题,可参考仓库内的平台快速入门文档:Windows 零基础安装 | Linux 零基础安装 | Mac 零基础安装。
如需指定版本安装(例如安装支持 Gradio APP 的 1.2.0 版本),可使用:
$ hub install falsr_a == 1.2.0
三、模块 API 预测:命令行与 Python 双通道
1. 命令行预测
PaddleHub 提供了统一的 hub run 命令行入口。对单张图片执行 2 倍超分:
$ hub run falsr_a --input_path "/PATH/TO/IMAGE"
命令执行后,超分结果会按默认配置保存到 falsr_a_output 目录。命令行还支持以下可选项(见 module.py 中 add_module_config_arg 的定义):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--input_path |
str | 必填 | 输入图片路径 |
--use_gpu |
bool | False | 是否使用 GPU 预测 |
--output_dir |
str | falsr_a_output |
输出图片保存目录 |
--save_dir |
str | falsr_a_save_model |
导出推理模型的保存目录 |
--visualization |
bool | True | 是否将结果保存为图片文件 |
其中 --save_dir 存在时,命令行还会额外调用 save_inference_model 将模型导出到指定目录,方便后续脱离 PaddleHub 单独部署。关于 hub run 的完整参数约定,可参考 PaddleHub 命令行使用说明。
2. Python 预测代码示例
在 Python 脚本中,通过 hub.Module 加载模型并调用 reconstruct 接口:
import cv2
import paddlehub as hub
sr_model = hub.Module(name='falsr_a')
im = cv2.imread('/PATH/TO/IMAGE').astype('float32')
res = sr_model.reconstruct(images=[im], visualization=True)
print(res[0]['data'])
需要注意两点:
- 输入图像需通过
cv2.imread读取并转换为float32,颜色空间为 BGR; visualization=True便于直接查看超分效果图,若仅需内存中的结果数组以提升运行速度,可将其设为False。
3. reconstruct 预测 API 详解
完整函数签名如下:
def reconstruct(images=None,
paths=None,
use_gpu=False,
visualization=False,
output_dir="falsr_a_output")
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
images |
list[numpy.ndarray] | 图片数据列表,每个 ndarray 的 shape 为 [H, W, C],颜色空间为 BGR |
paths |
list[str] | 图片路径列表,与 images 二选一或同时提供 |
use_gpu |
bool | 是否使用 GPU 预测。若使用 GPU,必须先设置 CUDA_VISIBLE_DEVICES 环境变量 |
visualization |
bool | 是否将识别结果保存为图片文件 |
output_dir |
str | 图片保存路径,默认 "falsr_a_output" |
返回值
res(list[dict]):模型结果列表,每个元素为一个 dict,包含以下字段:
save_path(str,可选):可视化图片的保存路径,仅在visualization=True时存在;data(numpy.ndarray):超分辨率处理后的图像数据。
4. 源码级原理:预处理、推理与后处理全链路
reconstruct 的完整调用链可以从仓库源码中还原出来,共分三个阶段:
阶段一:数据预处理(data_feed.py 的 reader)
data_feed.py 中的 reader 生成器负责对每张输入图片执行预处理,核心流程为:
- 将 BGR 图像转换为 YUV 颜色空间(
cv2.cvtColor(img, cv2.COLOR_BGR2YUV)); - 使用双三次插值(
cv2.INTER_CUBIC)将整图宽高各放大 2 倍; - 提取 Y 通道作为网络输入
img_y,并将放大后的 PbPr(即 UV)通道作为img_scale_pbpr输入; - 两者均转置为
[C, H, W]并归一化到[0, 1]。
这说明该模型采用经典的 YCbCr 通道分离超分策略:网络只负责重建 Y(亮度)通道的高频细节,而色度通道直接使用双三次插值放大,从而大幅降低计算量——这正是轻量化模型的关键设计之一。
阶段二:Paddle Inference 推理(module.py 的 reconstruct)
Falsr_A 在 _set_config 中分别构建了 CPU 与 GPU 两套预测器:
- CPU 配置通过
cpu_config.disable_gpu()创建; - GPU 配置通过
gpu_config.enable_use_gpu(memory_pool_init_size_mb=1000, device_id=0)创建,且仅在检测到CUDA_VISIBLE_DEVICES环境变量有效时才会初始化; - 推理时按
use_gpu参数选择对应 predictor,通过get_input_handle写入img_y与img_scale_pbpr两个输入,调用predictor.run()后从输出句柄取回超分结果。
阶段三:后处理(processor.py 的 postprocess)
processor.py 中的 postprocess 将网络输出:
- 压缩多余的维度(
np.squeeze); - 反归一化(乘 255)并裁剪到
[0, 255],转为uint8; - 将 RGB 结果转回 BGR(
cv2.cvtColor(sr, cv2.COLOR_RGB2BGR)); - 若
visualization=True,调用get_save_image_name生成保存文件名(基于原图文件名加.png后缀,若同名已存在则追加时间戳避免覆盖)并写入output_dir。
5. 模型导出:save_inference_model
如需将模型导出为独立的 Paddle Inference 模型文件,可调用:
def save_inference_model(dirname)
dirname:模型保存路径。
导出逻辑实现在 paddlehub/module/module.py 的 save_inference_model 方法中,对于 CV 图像类模块(type 以 cv/image 开头),会以 <a href="https://link.gitcode.com/i/d72dab0335d23dac10ff6a7debfdcca2" target="_blank">None, 3, None, None] 的 float32 InputSpec 通过 paddle.jit.save 导出,生成 model.pdmodel 与 model.pdiparams 文件(可参考 [test.py 中 test_save_inference_model 对导出产物的断言验证)。
四、服务化部署:PaddleHub Serving 在线超分服务
PaddleHub Serving 可以将 falsr_a 快速封装为 HTTP 在线服务,支持通过 RESTful 请求完成图像超分。
第一步:启动 PaddleHub Serving
在终端执行:
$ hub serving start -m falsr_a
启动成功后,服务化 API 即部署完成,默认端口号为 8866。
注意:如果使用 GPU 预测,需要在启动服务之前设置
CUDA_VISIBLE_DEVICES环境变量;使用 CPU 预测则无需设置。
第二步:发送预测请求
服务端就绪后,通过以下 Python 脚本发送预测请求并保存超分结果:
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.tostring()).decode('utf8')
def base64_to_cv2(b64str):
data = base64.b64decode(b64str.encode('utf8'))
data = np.fromstring(data, np.uint8)
data = cv2.imdecode(data, cv2.IMREAD_COLOR)
return data
# 发送 HTTP 请求
org_im = cv2.imread('/PATH/TO/IMAGE')
data = {'images': [cv2_to_base64(org_im)]}
headers = {"Content-type": "application/json"}
url = "http://127.0.0.1:8866/predict/falsr_a"
r = requests.post(url=url, headers=headers, data=json.dumps(data))
sr = base64_to_cv2(r.json()["results"][0]['data'])
cv2.imwrite('falsr_a_X2.png', sr)
print("save image as falsr_a_X2.png")
请求-响应的数据流转在服务端由 @serving 装饰的 serving_method 完成(见 module.py):服务端先将请求体中的 base64 字符串解码为 BGR 图像(base64_to_cv2),调用 reconstruct 完成超分,再将结果图像编码回 base64(cv2_to_base64)封装进 {"status": ..., "msg": ..., "results": [...]} 结构返回客户端。
第三步:Gradio APP 可视化体验
从 PaddleHub 2.3.1 开始,falsr_a 支持通过浏览器访问 Gradio APP。在 Serving 服务运行期间,直接访问:
http://127.0.0.1:8866/gradio/falsr_a
即可在浏览器中打开交互式界面,上传图片并勾选 use_gpu 选项实时预览超分效果。
其底层机制实现在 paddlehub/serving/app_compat.py:服务端路由 /gradio/<module_name> 会调用 create_gradio_app,通过 getattr(module_info["module"], 'create_gradio_app') 获取模块内定义的 Gradio 接口(Falsr_A.create_gradio_app 使用 gr.Interface 构建了「图片输入 + GPU 开关 + 图片输出」的交互界面),并在独立进程中启动 Gradio 服务,再由 Flask 反向代理将 /gradio/falsr_a/ 下的所有资源转发到 Gradio 服务端口。
五、正确性验证:内置单元测试
仓库为 falsr_a 提供了完整的单元测试用例 test.py,覆盖了主要使用路径,可作为自行验证模块可用性的参考:
- 路径输入:
reconstruct(paths=['tests/test.jpg'])返回numpy.ndarray结果; - 图像数组输入:
reconstruct(images=[cv2.imread('tests/test.jpg')]); - 可视化输出:
visualization=True时正确保存图片并返回结果; - GPU 预测:
use_gpu=True路径; - 异常处理:传入不存在的路径应抛出
AssertionError,传入非 ndarray 的列表元素应抛出AttributeError; - 模型导出:
save_inference_model('./inference/model')后应生成model.pdmodel与model.pdiparams两个文件。
这些用例同时印证了 reconstruct 的两种输入形态(paths 与 images)、GPU 开关以及可视化开关的行为语义,开发者可据此快速排查集成问题。
六、版本更新历史
| 版本 | 更新内容 |
|---|---|
| 1.0.0 | 初始发布 |
| 1.1.0 | 移除 Fluid API |
| 1.2.0 | 添加 Gradio APP 支持 |
如需回退到指定版本,执行 $ hub install falsr_a == 1.2.0 即可。
总结
falsr_a 是 PaddleHub 生态中一款典型的轻量化 CV 模块:8.9MB 的模型体积、2 倍超分能力、PSNR 37.82 的精度指标,配合「命令行预测 + Python API + Serving 服务化 + Gradio APP」四层调用形态,覆盖了从本地实验到在线服务的完整链路。其源码实现(YUV 通道分离、双三次插值色度放大、Paddle Inference 预测器复用)也为读者理解轻量级超分模型的工程化落地提供了清晰的范本。进一步探索时,可阅读 module.py、data_feed.py、processor.py 三份核心文件,以及 PaddleHub Serving 文档 了解更多服务化配置细节。