PaddleFormers 动物识别模块 resnet50_vd_animals 实战指南：安装、预测 API 与服务化部署

PaddleFormers 动物识别模块 resnet50_vd_animals 实战指南：安装、预测 API 与服务化部署

【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers

本篇技术指南以 PaddleFormers 仓库中的modules/image/classification/resnet50_vd_animals动物分类模块为核心，系统讲解该基于 ResNet50_vd（ResNet-D）架构、由百度自建动物数据集训练、可识别 7978 种动物的预训练模型的安装流程、命令行与 Python 预测 API、多设备推理原理以及 PaddleHub Serving 在线服务化部署。读完本文，你将能够独立完成从模型安装、单张/批量图片分类预测到部署在线动物识别 HTTP 服务的完整实战链路，并理解其底层数据预处理与后处理实现细节。

一、模型基本信息

模型概览

模型介绍

ResNet-vd 即 ResNet-D，是 ResNet 原始结构的变种，常用于图像分类和特征提取任务。该 PaddleHub Module 采用百度自建动物数据集训练得到，支持7978 种动物的分类识别，类别标签清单见 label_list.txt。

值得注意的细节是，label_list.txt实际包含 7979 行：除 7978 个动物类别外，末尾还包含一个"非动物"类别，用于对非动物输入给出显式的兜底判断。模型详情可参考 ResNet-vd 相关论文（arXiv:1812.01187）。

从模块源码看，该模型被打包为一个标准的 PaddleHub Module：module.py 中通过@moduleinfo装饰器声明了模块元信息（名称resnet50_vd_animals、类型CV/image_classification、作者baidu-vis、版本1.0.1），并定义了classification、serving_method、run_cmd等核心方法，分别对应 Python API 预测、Serving 服务调用与命令行hub run调用三种使用方式。

二、安装与环境依赖

1、环境依赖

• paddlepaddle >= 2.0.0
• paddlehub >= 2.0.0

2、安装

使用 PaddleHub 命令行即可一键安装模块：

$ hub install resnet50_vd_animals

如需指定历史版本，可显式指定版本号：

$ hub install resnet50_vd_animals==1.1.0

安装或环境准备阶段遇到问题时，可参考仓库内各平台的零基础安装指南：

• 零基础 Windows 安装
• 零基础 Linux 安装
• 零基础 MacOS 安装

关于安装背后的机制：从 paddlehub/module/module.py 的Module基类实现可以确认，当本地不存在该模块时，hub.Module(name="resnet50_vd_animals")会自动请求 PaddleHub 服务器下载对应资源；hub install命令则完成模块的下载与本地注册。

三、模型 API 预测

1、命令行预测

安装完成后，通过hub run即可直接对单张图片做预测，--input_path指定待识别图片的路径：

$ hub run resnet50_vd_animals --input_path "/PATH/TO/IMAGE"

命令行入口对应 module.py 中由@runnable装饰的run_cmd方法。除--input_path外，命令行还支持以下可选参数（与add_module_config_arg中定义一致）：

更完整的 PaddleHub 命令行用法可参考 PaddleHub 命令行说明。

2、预测代码示例

在 Python 环境中加载模块并进行分类预测：

import paddlehub as hub import cv2 classifier = hub.Module(name="resnet50_vd_animals") result = classifier.classification(images=[cv2.imread('/PATH/TO/IMAGE')]) # or # result = classifier.classification(paths=['/PATH/TO/IMAGE'])

其中images方式传入的是numpy.ndarray格式的 BGR 图像数据，paths方式直接传入图片文件路径，二者均可使用。

3、API 详解

预处理相关查询接口

def get_expected_image_width()

返回预处理后图片的宽度，即224。

def get_expected_image_height()

返回预处理后图片的高度，即224。

def get_pretrained_images_mean()

返回预处理使用的图片均值，即[0.485, 0.456, 0.406]。

def get_pretrained_images_std()

返回预处理使用的图片标准差，即[0.229, 0.224, 0.225]。

上述四个接口对应 module.py 中同名方法的实现：图片统一缩放到 224×224，并使用 ImageNet 风格的均值/标准差做通道归一化。

分类预测接口

def classification(images=None, paths=None, batch_size=1, use_gpu=False, top_k=1):

参数说明

• images（list[numpy.ndarray]）：图片数据列表，每个元素 shape 为[H, W, C]，颜色空间为 BGR；
• paths（list[str]）：图片路径列表；
• batch_size（int）：batch 大小；
• use_gpu（bool）：是否使用 GPU 预测；若使用 GPU，需提前设置CUDA_VISIBLE_DEVICES环境变量；
• top_k（int）：返回预测结果中置信度最高的前 k 个。

返回值

• res（list[dict]）：分类结果列表，每个元素为字典，key 为识别出的动物类别名称，value 为对应置信度。

模型导出接口

def save_inference_model(dirname, model_filename=None, params_filename=None, combined=True)

将模型保存为 Paddle Inference 格式到指定路径，便于脱离 PaddleHub 独立部署推理。

参数说明

• dirname：保存模型的目录名称；
• model_filename：模型文件名，默认为__model__；
• params_filename：参数文件名，默认为__params__（仅在combined=True时生效）；
• combined：是否将所有参数保存到统一的单个文件中。

该接口在 paddlehub/module/module.py 的RunModule.save_inference_model中实现：对于静态图推理模块，会通过paddle.static.load_inference_model加载原始模型并用paddle.static.save_inference_model导出；对于动态图paddle.nn.Layer模块，则会基于paddle.jit.to_static导出。模块目录下的 test.py 中test_save_inference_model用例验证了导出产物model.pdmodel与model.pdiparams的存在性。

四、源码级原理剖析

1、数据预处理流水线

data_feed.py 实现了完整的推理预处理流程，与get_expected_image_*/get_pretrained_images_*系列接口一一对应：

1. resize_short：将图片短边等比缩放到 256（使用Image.LANCZOS重采样）；
2. crop_image：从缩放后图片中心裁剪 224×224 区域（center=True）；
3. 将非 RGB 图像转换为 RGB；
4. 转为float32并调整通道顺序为[C, H, W]，除以 255 归一化到[0, 1]；
5. 减去均值[0.485, 0.456, 0.406]、除以标准差[0.229, 0.224, 0.225]。

reader生成器统一处理paths与images两种输入：路径方式直接Image.open读取，ndarray 方式则通过Image.fromarray(im[:, :, ::-1])将 BGR 转换回 RGB 后再走同一套流程。

2、后处理与结果排序

processor.py 中的postprocess对网络原始输出执行 softmax 归一化，然后通过np.argsort降序取前top_k个索引，映射到label_list得到类别名称与置信度字典。同一个文件中的base64_to_cv2函数则用于 Serving 场景下对 base64 编码图片的解码。

3、多设备推理支持

从 module.py 的_set_config与classification实现可以看出，模块基于paddle.inference的Config/create_predictor构建了多套 predictor，支持 CPU、GPU、XPU、NPU 四种设备：

• 默认创建 CPU predictor；
• 通过环境变量FLAGS_selected_npus检测 NPU 设备（enable_npu）；
• 通过环境变量CUDA_VISIBLE_DEVICES检测 GPU 设备（enable_use_gpu，初始显存池 1000MB）；
• 通过环境变量XPU_VISIBLE_DEVICES检测 XPU 设备（enable_xpu）。

classification中use_device参数会覆盖use_gpu标志选择具体设备，batch 数据通过input_tensor.copy_from_cpu送入 predictor 执行。

4、自动化测试验证

模块自带 test.py，基于unittest验证了核心行为：

• 分别以paths与images两种输入方式调用classification，并断言结果中包含"威尔士柯基"且置信度大于 0.5；
• 覆盖use_gpu=True的 GPU 推理路径；
• 验证非法路径触发AssertionError、非法输入类型触发TypeError等异常分支；
• 验证save_inference_model导出产物完整。

五、服务化部署

PaddleHub Serving 可以将该模块部署为一个在线动物识别服务，整体分为两步。

第一步：启动 PaddleHub Serving

运行启动命令：

$ hub serving start -m resnet50_vd_animals

执行完成后即完成在线动物识别服务化 API 的部署，默认监听端口为8866。

NOTE：如使用 GPU 预测，需要在启动服务前设置CUDA_VISIBLE_DEVICES环境变量；不使用 GPU 则无需设置。

Serving 的底层实现在 paddlehub/commands/serving.py：hub serving start会通过preinstall_modules加载模块并找到其@serving装饰的serving_method方法（本例中即 module.py 内的serving_method，负责 base64 解码后调用classification），随后启动 HTTP 服务并监听指定端口；端口被占用时会提示更换。

第二步：发送预测请求

服务端配置完成后，以下代码即可发送预测请求并获取结果：

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') # 发送HTTP请求 data = {'images':[cv2_to_base64(cv2.imread("/PATH/TO/IMAGE"))]} headers = {"Content-type": "application/json"} url = "http://127.0.0.1:8866/predict/resnet50_vd_animals" r = requests.post(url=url, headers=headers, data=json.dumps(data)) # 打印预测结果 print(r.json()["results"])

请求体中的images字段为图片经 base64 编码后的字符串列表，返回的results即分类结果（类别与置信度字典）。更多 Serving 配置细节可参考 PaddleHub Serving 文档。

六、更新历史

• 1.0.0：初始发布。
• 1.1.0：移除 Fluid API。

如需安装 1.1.0 版本，执行：

$ hub install resnet50_vd_animals==1.1.0

结语

resnet50_vd_animals是 PaddleHub 生态中一个开箱即用的细粒度动物分类模块：它以 ResNet50_vd 为骨干网络，在百度自建动物数据集上训练，支持 7978 种动物识别，并提供命令行、Python API 与 Serving 服务三种调用形态。通过本文对 module.py、data_feed.py、processor.py 与 test.py 的源码级拆解，读者既可以快速上手完成推理与部署，也能在需要时基于同样的 Module 开发模式，复用其多设备推理与预处理后处理流程构建自己的图像分类服务。

【免费下载链接】PaddleFormersPaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleFormers