企业官网建设流程全解析

• 人工智能
• 大模型
• 微调
• 模型推理服务

本文以 PaddleFormers 仓库中modules/image/classification/resnet_v2_101_imagenet模块文档为核心，系统讲解基于 ImageNet-2012 训练的 ResNet V2 101 图像分类模型在 PaddleHub 中的完整使用流程：从环境依赖与安装、命令行与 Python 接口预测，到分类 API 的参数与返回格式，并结合仓库中同族模块源码深入剖析模型的输入预处理与底层实现。读完本文，你将能够在自己的图片上直接运行该模型完成 Top-K 图像分类预测，并理解其数据流与调用原理。

一、模型基本信息

resnet_v2_101_imagenet是 PaddleHub 提供的一个预训练图像分类模块，其基本信息如下表所示（数据来源于 模块文档）：

该模块面向"开箱即用"的推理场景：模型基于 ImageNet-2012 数据集训练完成，接受输入图片大小为 224 x 224 x 3，支持直接通过命令行或者 Python 接口进行预测。从仓库结构看，该模块属于 PaddleHub 早期（1.x 版本时代）发布的模块，目录内仅保留 README.md 与 README_en.md，模块本体通过hub install从 PaddleHub 服务端拉取；而仓库中同族的resnet34_v2_imagenet、resnet101_vd_imagenet等模块则保留了完整的 module.py 源码，可用于印证本模块的实现细节。

二、ResNet 与残差单元：模型背景与源码印证

ResNet（Residual Network）系列是图像分类领域的重要模型之一。模型中提出的**残差单元（residual unit）**有效解决了深度网络训练困难的问题——通过跨层短路连接（shortcut）让梯度能够直达浅层，从而可以稳定地增加网络深度，并借此提升模型的准确率。

本模块的网络结构为 ResNet-101，即 101 层的残差网络。仓库中同族模块的源码可以印证 ResNet-101 的经典四阶段堆叠结构：在 resnet101_vd_imagenet/module.py 中，ResNet-101 的网络层数配置为：

depth = [3, 4, 23, 3] # 四个 stage 中 bottleneck block 的个数 num_channels = [64, 256, 512, 1024] num_filters = [64, 128, 256, 512]

可以看到，ResNet-101 的核心特点在于第三个 stage 堆叠了 23 个 Bottleneck 模块（3 + 4 + 23 + 3 = 33 个 block，加上首层卷积与全连接层构成 101 层网络）。在 resnet34_v2_imagenet/resnet.py 中还可以看到不同深度的残差网络配置表：

self.depth_cfg = { 34: ([3, 4, 6, 3], self.basicblock), 50: ([3, 4, 6, 3], self.bottleneck), }

而 ResNet-101 将[3, 4, 6, 3]中第三 stage 的 block 数扩展为 23，从而在不过度增加计算量的前提下显著加深网络，这是 ResNet 系列"以深度换精度"的代表性设计。需要说明的是，本文模块的输入输出约定为 224 x 224 x 3，对应 ImageNet 分类任务的通用输入尺寸。

三、环境依赖与模块安装

1. 环境依赖

运行resnet_v2_101_imagenet模块需要满足以下环境要求：

• paddlepaddle >= 1.4.0：PaddlePaddle 深度学习框架，负责模型的底层计算；
• paddlehub >= 1.0.0：PaddleHub 模型管理工具，负责模块的下载、安装与调用。

PaddleHub 的安装方式可参考 docs/docs_ch/get_start/installation.rst（英文版见 docs/docs_en/get_start/installation.rst）。

2. 安装模块

执行以下命令即可从 PaddleHub 服务端安装该模块：

$ hub install resnet_v2_101_imagenet

安装完成后，模块即被注册到本地 PaddleHub 环境，后续可通过命令行或 Python 接口直接调用。

安装遇到问题怎么办？可以分别参考零基础安装指南：

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

如果需要安装指定历史版本（例如 1.0.1），可以显式指定版本号：

$ hub install resnet_v2_101_imagenet==1.0.1

四、命令行预测

安装完成后，最简单的方式是通过 PaddleHub 命令行直接对单张图片进行分类预测：

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

其中/PATH/TO/IMAGE替换为本地待预测图片的绝对路径。命令执行后，模型会输出该图片的分类结果（label）及其对应的概率。

从仓库中同族模块的源码（如 resnet34_v2_imagenet/module.py）可以推断，命令行模式还支持以下常用参数，可用于更灵活的批处理场景：

• --input_path：指定单张输入图片路径；
• --input_file：指定一个文本文件，文件中逐行列出多张图片路径，实现批量预测（解析逻辑可参考paddlehub.io.parser.txt_parser）；
• --use_gpu：是否使用 GPU 进行预测，布尔值，默认为False；
• --batch_size：预测时的批大小，默认为 1。

PaddleHub 命令行的完整用法（如hub run的通用参数与行为）可参考 docs/docs_ch/tutorial/cmd_usage.rst。

五、Python 接口预测

1. 预测代码示例

在 Python 脚本中，通过hub.Module加载模块并调用classification接口完成预测：

import paddlehub as hub import cv2 classifier = hub.Module(name="resnet_v2_101_imagenet") test_img_path = "/PATH/TO/IMAGE" input_dict = {"image": [test_img_path]} result = classifier.classification(data=input_dict)

代码要点：

1. hub.Module(name="resnet_v2_101_imagenet")：按名称加载本地已安装模块，返回模块实例；
2. input_dict = {"image": [test_img_path]}：构造输入字典，key 为"image"，value 为图片路径构成的 list；
3. classifier.classification(data=input_dict)：执行分类推理，返回结果列表。

注：代码示例中的import cv2是早期模块的常规依赖引入；在当前预测流程中核心依赖为paddlehub与paddlepaddle。

2. classification API 详解

def classification(data)

• 功能：图像分类接口 API。
• 参数data：dict 类型。key 为image（str 类型），value 为待检测的图片路径列表（list 类型）。即支持一次传入多张图片进行批量预测。
• 返回值result：list 类型，长度与输入图片数量一致。每个元素为对应输入图片的预测结果，是 dict 类型：key 为该图片的分类结果 label，value 为该 label 对应的概率。

例如，单张图片的返回值形如：

[{"goldfish": 0.9234, "tench": 0.0312}] # 示意结构，实际 label 以模型输出为准

3. 从同族源码看 classification 的更多参数

仓库中resnet34_v2_imagenet模块保留了完整的classification实现（见 resnet34_v2_imagenet/module.py），其签名如下，可作为理解本模块内部行为的参考：

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

• paths：图片路径列表，list 类型，每个元素为一张图片的路径；
• images：直接传入的图片数据，numpy.ndarray，形状为[N, H, W, C]，与paths二选一；
• use_gpu：是否使用 GPU，bool 类型；
• batch_size：预测批大小，int 类型，默认 1；
• top_k：返回概率最高的前 k 个分类结果，int 类型，默认 2，内部被限制在[1, 1000]区间内。

从源码可以看出，classification内部会：

1. 懒加载推理程序（context(...)构建网络并将infer_prog克隆为测试模式）；
2. 通过数据读取器test_reader逐张读取并预处理图片；
3. 按batch_size分批次执行预测器（CPU/GPU 二选一）；
4. 对输出概率np.argsort(res)[::-1][:top_k]取 Top-K，将类别索引映射为label_file.txt中的类别名，组装成{label: prob}字典返回。

六、输入预处理流程：224 x 224 背后发生了什么

文档明确说明该模块接受224 x 224 x 3的输入图片。仓库中同族模块的 data_feed.py 完整实现了这一预处理管线，可作为本模块预处理流程的直接参考：

DATA_DIM = 224 img_mean = np.array([0.485, 0.456, 0.406]).reshape((3, 1, 1)) img_std = np.array([0.229, 0.224, 0.225]).reshape((3, 1, 1))

预处理步骤依次为：

1. resize_short(img, 256)：将图片短边缩放至 256，保持宽高比，使用Image.LANCZOS高质量重采样；
2. crop_image(img, 224, center=True)：从缩放后的图片中央裁剪 224 x 224 区域（预测阶段采用中心裁剪，保证结果可复现）；
3. RGB 转换：若图片非 RGB 模式则先转换为 RGB；
4. 归一化：像素值除以 255 缩放到[0, 1]，再按 ImageNet 统计的均值[0.485, 0.456, 0.406]与标准差[0.229, 0.224, 0.225]做标准化，即(x / 255 - mean) / std。

上述均值/标准差同样出现在 resnet34_v2_imagenet/module.py 的get_pretrained_images_mean/std方法中，是 ResNet 系列 ImageNet 预训练模型的通用预处理约定。也就是说，无论你传入的原始图片尺寸是多少，模型都会先等比缩放再中心裁剪到 224 x 224 后送入网络——因此输入图片并不需要预先裁好。

七、模型族与迁移学习扩展阅读

resnet_v2_101_imagenet属于 PaddleHub 图像分类模型大家族。仓库modules/image/classification/下还包含大量同族或同任务模块，便于横向对比与选型：

• ResNet V2 系列：resnet_v2_18_imagenet、resnet_v2_34_imagenet、resnet_v2_50_imagenet、resnet_v2_152_imagenet；
• ResNet 及变体：resnet101_imagenet、resnet101_vd_imagenet（VD 变体，含完整源码）、resnet50_vd_imagenet_ssld 等；
• 同任务模块：VGG、MobileNet、EfficientNet、DenseNet、HRNet 等，覆盖不同精度与速度档位。

值得注意的是，虽然本文模块文档标注"不支持 Fine-tuning"，但仓库中同族的resnet34_v2_imagenet模块在 module.py 中提供了context(...)接口，可通过trainable、pretrained、param_prefix、feature_maps等参数抽取骨干网络特征用于迁移学习。从源码结构可以推断，需要做下游任务微调时，可优先选用带完整源码且支持context接口的模块；此外 demo/image_classification/train.py 给出了基于hub.Module+paddlehub.finetune.trainer.Trainer的完整微调示例（以resnet50_vd_imagenet_ssld为例），可作为自定义数据集分类训练的参考模板。

八、更新历史

• 1.0.0：初始发布。
• 1.0.1：修复 Python 2 中的编码问题。如需使用该版本，安装命令为：

$ hub install resnet_v2_101_imagenet==1.0.1

总结

resnet_v2_101_imagenet是一个开箱即用的 ImageNet-2012 预训练图像分类模块：安装仅需一条hub install命令，预测支持hub run命令行与 Pythonclassification接口两种方式，返回 Top-K 的{类别: 概率}结果。其背后的 ResNet-101 残差网络结构、224 x 224 中心裁剪与 ImageNet 归一化预处理，均可通过仓库中同族模块的 module.py、resnet.py 与 data_feed.py 源码逐一印证。对于需要将 ImageNet 分类能力快速集成到自身图像处理流程的开发者，这是一个低成本、易上手的起点。

• 人工智能
• 大模型
• 微调
• 模型推理服务