PaddleHub 图像分类模块 se_resnet18_vd_imagenet 实战指南:安装、预测 API 与 Serving 部署
PaddleHub 图像分类模块 se_resnet18_vd_imagenet 实战指南:安装、预测 API 与 Serving 部署
导读
本指南围绕 PaddleHub 官方图像分类模块 se_resnet18_vd_imagenet 展开,完整讲解该模块的安装方式、命令行与 Python API 两种预测用法、关键参数含义,以及基于 PaddleHub Serving 的在线服务部署流程。读完本文,你将掌握该模块从「本地安装 → 单张图片分类 → HTTP 服务化调用」的完整落地路径,并能结合仓库源码理解其预处理、推理与后处理的实现细节,便于迁移到其他 PaddleHub CV 模块。
模块基本信息
se_resnet18_vd_imagenet 是 PaddleHub 中面向图像分类任务的预训练模块,其关键信息如下表所示:
| 项目 | 内容 |
|---|---|
| 模块名称 | se_resnet18_vd_imagenet |
| 类别 | image classification(图像分类) |
| 网络结构 | SE-ResNet |
| 训练数据集 | ImageNet-2012 |
| 是否支持微调(Fine-tuning) | 否 |
| 模块大小 | 48MB |
| 最新更新日期 | - |
| 数据指标 | - |
该模块基于 SE-ResNet 结构,在 ImageNet-2012 数据集上完成训练,可对尺寸为 224×224×3 的输入图像进行 1000 类分类预测。从源码看,模块类 SEResNet18vdImageNet 的元信息定义于 module.py,其摘要为 "SE_ResNet18_vd is a image classfication model, this module is trained with imagenet datasets",模块类型为 CV/image_classification,版本为 1.1.0,由 paddlepaddle 团队发布。
需要注意的是,原 README 中"基于 Res2Net"的表述与模块实际采用的 SE-ResNet 结构存在出入,本文以源码中的 @moduleinfo 声明与模块名 se_resnet18_vd_imagenet 为准。SE-ResNet 是在 ResNet 基础上引入 Squeeze-and-Excitation(SE)注意力机制的网络变体,通过显式建模通道间的相互依赖关系来提升表示能力。
环境依赖与模块安装
1、环境依赖
使用该模块前需要确保满足以下依赖:
- paddlepaddle >= 1.6.2:底层深度学习框架(PaddleHub Serving 与 Inference 推理均依赖 PaddlePaddle 的 inference API,见下文源码分析);
- paddlehub >= 1.6.0:模块管理与推理框架,安装指引可参考 PaddleHub 安装文档。
需要说明的是,安装文档 中针对当前仓库配套的 PaddleHub 版本建议了更高要求:操作系统支持 Windows/Mac/Linux,Python >= 3.6.2,PaddlePaddle >= 2.0.0,并推荐使用 pip install paddlehub==2.1.0 安装。实际使用时建议以仓库 requirements.txt 与安装文档的最新要求为准,以兼容当前 PaddlePaddle 与 PaddleHub 版本。
2、模块安装
通过 PaddleHub 命令行安装模块:
$ hub install se_resnet18_vd_imagenet
安装过程遇到问题时可参考对应平台的快速上手文档:Windows_Quickstart | Linux_Quickstart | Mac_Quickstart。
从 PaddleHub 命令行工具文档 可知,hub install 默认将模块安装到 ${HUB_HOME}/.paddlehub/modules 目录(未设置 ${HUB_HOME} 时使用 $HOME),安装完成后即可通过其他命令或 Python API 调用该模块。
模块 API 预测
1、命令行预测
安装完成后,可直接通过 hub run 命令对单张图片进行分类预测:
$ hub run se_resnet18_vd_imagenet --input_path "/PATH/TO/IMAGE"
--input_path 用于指定待分类图片路径。命令行的完整使用说明参见 PaddleHub Command Line Instruction。
该命令的执行链路在源码中有清晰对应:模块类中的 @runnable 装饰方法 run_cmd 定义了命令行入口(module.py),它通过 argparse 注册了三个参数——--use_gpu(默认 False)、--batch_size(默认 1)、--top_k(默认 1),以及输入参数 --input_path,最终调用 self.classification(paths=[args.input_path], ...) 完成预测。这说明命令行方式实际等价于以 paths 方式调用 classification API,且命令行默认不使用 GPU。
2、预测代码示例
在 Python 中以 API 方式调用模块:
import paddlehub as hub
import cv2
classifier = hub.Module(name="se_resnet18_vd_imagenet")
result = classifier.classification(images=[cv2.imread('/PATH/TO/IMAGE')])
# or
# result = classifier.classification(paths=['/PATH/TO/IMAGE'])
两种传参方式的差别在于:images 接收的是 numpy 数组(BGR 颜色空间),而 paths 接收的是图片文件路径。在 data_feed.py 的 reader 生成器中可以看到,paths 分支会校验文件是否真实存在(不存在则触发 AssertionError),而 images 分支会将 ndarray 通过 Image.fromarray(im[:, :, ::-1]) 转回 PIL 图像——注意这里做了 BGR 到 RGB 的通道反转。
仓库自带的 test.py 给出了对应的单元测试:test_classification1 与 test_classification2 分别验证 paths 与 images 两种调用方式,并对一张狗图片断言预测结果中包含 Pembroke 且概率大于 0.5;test_classification4 验证传入不存在的路径会抛出 AssertionError;test_classification5 验证以字符串列表作为 images 会抛出 TypeError。这些用例可以直接作为该模块的验收参考。
3、classification API 详解
def classification(images=None,
paths=None,
batch_size=1,
use_gpu=False,
top_k=1):
参数说明:
- images(list[numpy.ndarray]):图像数据列表,每个 ndarray 的形状为 [H, W, C],颜色空间为 BGR;
- paths(list[str]):图像路径列表;
- batch_size(int):批大小,控制每次送入推理引擎的图片数量,默认 1;
- use_gpu(bool):是否使用 GPU 进行预测;若使用 GPU,必须先设置 CUDA_VISIBLE_DEVICES 环境变量;
- top_k(int):返回概率最高的前 k 个分类结果,默认 1。
返回值:
- res(list[dict]):分类结果列表,每个元素为一个 dict,key 为标签名称,value 为对应概率。
上述参数语义在 module.py 的 classification 实现中得到了完整验证:
- 当
use_gpu=True时,若环境变量CUDA_VISIBLE_DEVICES未正确设置,会抛出RuntimeError提示;GPU 推理通过Config.enable_use_gpu(memory_pool_init_size_mb=1000, device_id=0)配置 1000MB 显存池; batch_size通过np.ceil(total_num / batch_size)计算批次数,并对不足一批的尾数做了容错处理;- 预测器(predictor)在首次调用时通过
_set_config()惰性初始化,使用 PaddlePaddle Inference 的create_predictor加载.pdmodel与.pdiparams模型文件,并默认disable_gpu()构建 CPU 预测器,同时依据CUDA_VISIBLE_DEVICES判断是否额外构建 GPU 预测器。
底层推理流程(源码级):
完整调用链可分为三个阶段:
- 预处理(data_feed.py 的
process_image):先将图像短边缩放到 256(resize_short,使用 LANCZOS 插值),再从中心裁剪出 224×224 区域(crop_image,center=True);若图像非 RGB 则转换颜色空间;最后转为 float32、除以 255 归一化,并按 ImageNet 数据集的均值/标准差做标准化(mean = 0.485, 0.456, 0.406],std = [0.229, 0.224, 0.225])。模块类中的get_expected_image_width/get_expected_image_height也印证了输入尺寸固定为 224×224([module.py); - 推理:将预处理后的批数据通过
input_handle.copy_from_cpu送入 predictor 并执行predictor.run(); - 后处理(processor.py 的
postprocess):对网络输出逐样本执行 softmax 得到各类别概率,按概率降序取前top_k个,再通过 label_list.txt(共 1000 行,对应 ImageNet 1000 类标签,格式为 "标签名, 别名")将索引映射为标签名,最终组装为{label: probability}形式的 dict。
Server 部署(PaddleHub Serving)
PaddleHub Serving 可以将该图像分类模块一键部署为在线服务,方便以 HTTP 接口形式对外提供分类能力。
Step 1:启动 PaddleHub Serving
运行如下命令启动服务:
$ hub serving start -m se_resnet18_vd_imagenet
服务启动后默认监听 8866 端口,该默认值在 serving.py 与 serving.py 中均有定义(self.args_config.get('port', 8866) 与 --port 参数默认值),也支持通过 -p/--port 参数自定义端口。
NOTE: 若使用 GPU 进行预测,需在启动服务前设置 CUDA_VISIBLE_DEVICES 环境变量;否则无需设置。
Step 2:发送预测请求
服务启动后,可通过 HTTP POST 请求完成图片分类:
import requests
import json
import cv2
import base64
def cv2_to_base64(image):
data = cv2.imencode('.jpg', image)[1]
return base64.b64encode(data.tostring()).decode('utf8')
# Send an HTTP request
data = {'images':[cv2_to_base64(cv2.imread("/PATH/TO/IMAGE"))]}
headers = {"Content-type": "application/json"}
url = "http://127.0.0.1:8866/predict/se_resnet18_vd_imagenet"
r = requests.post(url=url, headers=headers, data=json.dumps(data))
# print prediction results
print(r.json()["results"])
请求流程说明:客户端先将图片以 base64 字符串编码放入 images 字段并序列化为 JSON,POST 到 /predict/se_resnet18_vd_imagenet 端点;服务端收到请求后,由模块中的 @serving 装饰方法 serving_method 处理(module.py),它调用 processor.py 中的 base64_to_cv2 将 base64 字符串解码还原为 cv2 图像(cv2.imdecode),再交由 classification 完成推理,最后返回分类结果。
版本发布说明
| 版本 | 说明 |
|---|---|
| 1.0.0 | 首次发布 |
| 1.1.0 | 移除 Fluid API |
若需要安装指定版本,可通过带版本号的安装命令完成:
$ hub install se_resnet18_vd_imagenet==1.1.0
当前仓库中模块的 @moduleinfo 声明的版本即为 1.1.0(module.py),与发布说明中的最新版本一致。在 PaddlePaddle 2.x 时代,PaddleHub 模块普遍采用基于 Inference 的 create_predictor 推理方式(本模块即如此),不再依赖已废弃的 Fluid API。
延伸阅读
- 若要深入了解该模块的推理细节与测试方法,可继续阅读仓库中的 module.py、processor.py、data_feed.py 与 test.py;
- PaddleHub 命令行工具的完整命令说明见 cmd_usage.rst;
- 如需在本地将模块导出为独立推理模型(
save_inference_model),可参考 test.py 中test_save_inference_model的用法:导出后生成model.pdmodel与model.pdiparams两个文件,可直接供 PaddlePaddle Inference 加载使用。