企业官网建设流程全解析

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• 模型推理服务

导读

旋转目标检测（Rotated Object Detection）是通用目标检测在遥感等场景下的重要衍生任务，其核心是输出带角度信息的旋转矩形框（Rotated Bounding Box），比水平框包含更少的背景信息。本文以 PaddleX 仓库中的 rotated_object_detection.en.md 为主线，完整讲解 PaddleX 旋转目标检测模块的模型选型、Python 快速集成、结果解析，以及从数据准备、数据校验、模型训练、评估到推理集成的二次开发全流程，并结合仓库源码剖析其底层实现原理，帮助你快速在遥感影像等场景落地旋转框检测能力。

一、模块概述：旋转目标检测要解决什么问题

旋转目标检测是 PaddleX 目标检测模块的一个衍生子模块，专门用于检测带有旋转角度的目标。与水平边界框（Horizontal Bounding Box）不同，旋转边界框（Rotated Bounding Box）的宽高不再平行于图像坐标轴，而是带有角度信息，因此能更紧凑地贴合目标的真实轮廓。

相比水平框，旋转框通常包含更少的背景信息，这对于目标密集、方向任意且长宽比悬殊的场景尤为关键。旋转框检测最典型的应用场景是遥感影像（Remote Sensing），例如 DOTA 数据集所覆盖的飞机、车辆、环岛等目标——这些目标在航拍视角下往往以任意角度出现，使用水平框会混入大量相邻目标与背景，严重影响检测精度与下游分析质量。

从仓库源码可以印证这一模块的定位：在 paddlex/inference/pipelines/rotated_object_detection/pipeline.py 中，旋转目标检测拥有独立的 Pipeline 类（RotatedObjectDetectionPipeline），其entities标识为rotated_object_detection，并复用了目标检测模块的DetResult结果类型与后处理逻辑。在 paddlex/inference/models/object_detection/processors.py 中，DetPostProcess.apply会依据输出框的列数区分普通检测（6 列）与旋转检测（10 列，即[cls_id, score, x1, y1, x2, y2, x3, y3, x4, y4]），再分别调用restructured_boxes或restructured_rotated_boxes完成结果整理——这正是旋转框 8 个坐标点输出的源码级来源。

二、支持模型与性能基准

当前 PaddleX 旋转目标检测模块支持的模型如下表所示：

注：上表中的推理耗时仅包含模型推理时间，不包含前后处理时间。

2.1 测试环境说明

• 测试数据集：DOTA 验证集。
• 硬件配置：GPU 为 NVIDIA Tesla T4；CPU 为 Intel Xeon Gold 6271C @ 2.60GHz。
• 软件环境：Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6；paddlepaddle 3.0.0 / paddlex 3.0.3。

2.2 推理模式说明

模型与配置文件的对应关系可在 PaddleX 模型列表（CPU/GPU） 中查询，其中 PP-YOLOE-R-L 对应的配置文件为 paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml。

三、快速集成：几行代码完成旋转框推理

⚠️ 在快速集成之前，请先安装 PaddleX wheel 包，具体请参考 PaddleX 本地安装教程。

完成 wheel 包安装后，仅需几行代码即可完成旋转目标检测模块的推理。你可以随时切换该模块下的模型，也可以将旋转目标检测的模型推理集成到自己的项目中。运行以下代码前，请先将示例图片下载到本地。

from paddlex import create_model model = create_model("PP-YOLOE-R-L") output = model.predict("rotated_object_detection_001.png", batch_size=1) for res in output: res.print() res.save_to_img("./output/") res.save_to_json("./output/res.json")

运行后得到的结果示例：

{'res': "{'input_path': 'rotated_object_detection_001.png', 'boxes': [{'cls_id': 4, 'label': 'small-vehicle', 'score': 0.7513620853424072, 'coordinate': [92.72234, 763.36676, 84.7699, 749.9725, 116.207375, 731.8547, 124.15982, 745.2489]}, {'cls_id': 4, 'label': 'small-vehicle', 'score': 0.7284387350082397, 'coordinate': [348.60703, 177.85127, 332.80432, 149.83975, 345.37347, 142.95677, 361.17618, 170.96828]}, {'cls_id': 11, 'label': 'roundabout', 'score': 0.7909174561500549, 'coordinate': [535.02216, 697.095, 201.49803, 608.4738, 292.2446, 276.9634, 625.76874, 365.5845]}]}"}

3.1 结果字段含义

• input_path：待预测输入图片的路径。
• boxes：每个预测目标的信息。
  • cls_id：类别 ID。
  • label：类别名称。
  • score：预测置信度分数。
  • coordinate：预测边界框的坐标，格式为[x1, y1, x2, y2, x3, y3, x4, y4]，即旋转矩形的 4 个顶点（8 个坐标值）。

上述坐标格式与源码中的处理逻辑完全对应：在 paddlex/inference/models/object_detection/processors.py 中，restructured_rotated_boxes要求旋转框输入形状为[N, 10]，逐点将 8 个坐标裁剪到图像范围内后，以[x1, y1, x2, y2, x3, y3, x4, y4]形式写入结果字典。

3.2 create_model 参数详解

create_model用于实例化旋转目标检测模型（此处以PP-YOLOE-R-L为例），参数说明如下：

使用规则说明：

• model_name必须指定。指定model_name后，默认使用 PaddleX 内置的模型参数；若同时指定model_dir，则使用用户自定义模型。
• threshold是过滤低分目标的阈值，默认为None，表示使用优先级更低的设置。参数设置优先级从高到低为：predict 参数输入 > create_model 初始化 > yaml 配置文件设置。当前支持两种设置方式：
  • float：所有类别使用同一阈值。
  • dict：key 为类别 ID，value 为对应类别的阈值，可为不同类别设置不同阈值。
• img_size是模型预测使用的分辨率，默认为None，表示使用优先级更低的设置。参数优先级从高到低为：create_model 初始化 > yaml 配置文件设置。需要说明的是，在 paddlex/inference/models/object_detection/predictor.py 中，img_size仅支持int或Tuple[int, int]两种形式，且对静态形状模型（STATIC_SHAPE_MODEL_LIST中的模型）不允许自定义输入尺寸。

3.3 predict 方法参数详解

调用旋转目标检测模型的predict()方法进行推理预测，其参数为input、batch_size和threshold：

input支持的数据类型：

• Python 变量：如numpy.ndarray表示的图像数据；
• 文件路径：如图像文件的本地路径/root/data/img.jpg；
• URL 链接：如图像文件的网络 URL；
• 本地目录：目录内应包含待预测的数据文件，如/root/data/；
• 列表：列表元素必须是上述类型的数据，如[numpy.ndarray, numpy.ndarray]、["/root/data/img1.jpg", "/root/data/img2.jpg"]、["/root/data1", "/root/data2"]。

threshold的可选值：

• None：表示使用优先级更低的设置，优先级从高到低为predict 参数输入 > create_model 初始化 > yaml 配置文件设置；
• float：如0.5，表示推理时所有类别统一使用0.5作为阈值；
• dict：如{0: 0.5, 1: 0.35}，表示推理时类别 0 使用阈值 0.5、类别 1 使用阈值 0.35。

从源码看，paddlex/inference/pipelines/rotated_object_detection/pipeline.py 中的predict方法直接将threshold透传给底层旋转检测模型；而 paddlex/inference/models/object_detection/processors.py 的DetPostProcess.apply中，float阈值通过boxes[:, 1] > threshold统一过滤，dict阈值则按类别逐个过滤（未在 dict 中指定的类别回退到 0.5）。

3.4 预测结果的后处理与输出

预测结果的处理中，每个样本的预测结果为dict类型，支持打印、保存为图片、保存为json文件等操作：

print()：将结果打印到终端

save_to_json()：将结果保存为 JSON 格式文件

save_to_img()：将结果保存为图片格式文件

此外，还支持通过属性直接获取带结果的可视化图像与预测结果：

关于可视化绘制，可以追溯到 paddlex/inference/models/object_detection/result.py 中的draw_box函数：当坐标长度为 4 时按普通检测框绘制，当坐标长度为 8 时按旋转框绘制——将(x1, y1), (x2, y2), (x3, y3), (x4, y4), (x1, y1)依次连线构成闭合旋转矩形，并在框旁绘制label + score文本；DetResult._to_img则将 BGR 图像还原后完成绘制，_to_json/_to_str则剔除input_img字段后输出结构化结果。

关于 PaddleX 单模型推理 API 的更多用法，请参考 PaddleX 单模型 Python 脚本使用说明。

四、二次开发：从数据到模型训练与部署

如果希望基于现有模型追求更高精度，可以利用 PaddleX 的二次开发能力训练出更好的旋转目标检测模型。使用 PaddleX 进行旋转目标检测模型开发前，请确保已安装 PaddleX 中与旋转目标检测相关的模型训练插件，安装过程可参考 PaddleX 本地安装教程。

4.1 数据准备

模型训练前，需要为对应任务模块准备数据集。PaddleX 为每个模块提供数据校验功能，只有通过校验的数据才能用于模型训练。此外，PaddleX 为每个模块提供了 Demo 数据集，可用于完成后续开发。如果希望使用私有数据集进行后续模型训练，可参考 PaddleX 目标检测任务模块数据标注教程。

4.1.1 Demo 数据下载

可通过以下命令将 Demo 数据集下载到指定文件夹：

wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/rdet_dota_examples.tar -P ./dataset tar -xf ./dataset/rdet_dota_examples.tar -C ./dataset/

解压后数据集目录结构如下：

- dataset/DOTA-sampled200_crop1024_data - annotations - instance_train.json - instance_val.json - images - img1.png - img2.png - img3.png ...

4.1.2 数据校验

一条命令即可完成数据校验：

python main.py -c paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/DOTA-sampled200_crop1024_data

执行上述命令后，PaddleX 会对数据集进行校验并统计数据集的基本信息。命令运行成功后，日志中会打印Check dataset passed !。校验结果文件保存在./output/check_dataset_result.json，相关产物保存在当前目录下的./output/check_dataset目录中，包括可视化样本图片和样本分布直方图。

{ "done_flag": true, "check_pass": true, "attributes": { "num_classes": 15, "train_samples": 1892, "train_sample_paths": [ "check_dataset/demo_img/P2610__1.0__0___0.png", ... ], "val_samples": 473, "val_sample_paths": [ "check_dataset/demo_img/P2342__1.0__890___0.png", ... ] }, "analysis": { "histogram": "check_dataset/histogram.png" }, "dataset_path": "rdet_dota_examples", "show_type": "image", "dataset_type": "COCODetDataset" }

4.1.3 数据集格式转换/数据集划分（可选）

完成数据校验后，可以通过修改配置文件或追加超参数实现数据集格式转换或重新划分训练集/验证集比例。

...... CheckDataset: ...... split: enable: True train_percent: 90 val_percent: 10 ......

python main.py -c paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/DOTA-sampled200_crop1024_data

python main.py -c paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/DOTA-sampled200_crop1024_data \ -o CheckDataset.split.enable=True \ -o CheckDataset.split.train_percent=90 \ -o CheckDataset.split.val_percent=10

4.2 模型训练

一条命令即可完成模型训练，以训练旋转目标检测模型PP-YOLOE-R-L为例：

python main.py -c paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml \ -o Global.mode=train \ -o Global.dataset_dir=./dataset/DOTA-sampled200_crop1024_data

需要按以下要点操作：

• 指定模型的.yaml配置文件路径（此处为PP-YOLOE-R-L.yaml。训练其他模型时，需指定对应的配置文件，模型与配置文件的对应关系可在 PaddleX 模型列表（CPU/GPU） 中查看）；
• 指定模式为模型训练：-o Global.mode=train；
• 指定训练数据集路径：-o Global.dataset_dir；
• 其他相关参数可以通过修改.yaml配置文件中Global和Train下的字段设置，也可以通过命令行追加参数。例如，指定前 2 张 GPU 卡训练：-o Global.device=gpu:0,1；设置训练轮数为 10：-o Train.epochs_iters=10。更多可修改参数及详细说明，请参考对应任务模块的配置文件说明 PaddleX 通用模型配置文件参数说明；
• 新特性：Paddle 3.0 支持在使用 GPU 设备时通过 CINN（Compiler Infrastructure for Neural Networks）加速训练，请指定-o Train.dy2st=True启用。

从配置文件中可以看到PP-YOLOE-R-L的默认训练超参数：paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml 默认设置num_classes: 15、epochs_iters: 10、batch_size: 1、learning_rate: 0.128、warmup_steps: 100、eval_interval: 5，预训练权重来自 CSPResNetb_l，这些参数均可按上述方式覆盖。

4.3 模型评估

完成模型训练后，可以在验证集上评估指定模型权重文件，以验证模型精度。使用 PaddleX 进行模型评估同样只需一条命令：

python main.py -c paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml \ -o Global.mode=evaluate \ -o Global.dataset_dir=./dataset/DOTA-sampled200_crop1024_data

与模型训练类似，需要按以下要点操作：

• 指定模型的.yaml配置文件路径（此处为PP-YOLOE-R-L.yaml）；
• 指定模式为模型评估：-o Global.mode=evaluate；
• 指定验证数据集路径：-o Global.dataset_dir。其他相关参数可以通过修改.yaml配置文件中Global和Evaluate下的字段设置，详情可参考 PaddleX 通用模型配置文件参数说明。

4.4 模型推理与集成

完成模型训练与评估后，可以使用训练好的模型权重进行推理预测或 Python 集成。

4.4.1 模型推理

• 通过命令行进行推理预测，命令如下。运行以下代码前，请先将示例图片下载到本地。

python main.py -c paddlex/configs/modules/rotated_object_detection/PP-YOLOE-R-L.yaml \ -o Global.mode=predict \ -o Predict.model_dir="./output/best_model/inference" \ -o Predict.input="rotated_object_detection_001.png"

与模型训练和评估类似，需要按以下要点操作：

• 指定模型的.yaml配置文件路径（此处为PP-YOLOE-R-L.yaml）；
• 指定模式为模型推理预测：-o Global.mode=predict；
• 指定模型权重路径：-o Predict.model_dir="./output/best_model/inference"；
• 指定输入数据路径：-o Predict.input="..."；
• 其他相关参数可以通过修改.yaml配置文件中Global和Predict下的字段设置，详情可参考 PaddleX 通用模型配置文件参数说明。

4.4.2 模型集成

训练产出的模型可以直接集成到 PaddleX 流水线中，也可以直接集成到自己的项目中。具体而言，训练得到的权重可以直接集成到旋转目标检测模块：参考上文"快速集成"章节的 Python 示例代码，将模型名替换为训练模型的路径即可。

此外，还可以使用 PaddleX 高性能推理插件优化模型的推理过程、进一步提升效率，详细流程请参考 PaddleX 高性能推理指南。

五、源码视角：旋转框检测的底层实现链路

为帮助开发者更深入地理解旋转目标检测在 PaddleX 中的落地方式，这里补充几条源码线索：

1. Pipeline 组织：旋转目标检测在 paddlex/inference/pipelines/rotated_object_detection/pipeline.py 中通过RotatedObjectDetectionPipeline对外提供服务，从配置的SubModules.RotatedObjectDetection节点读取模型配置与默认阈值，并支持AutoParallelImageSimpleInferencePipeline自动并行推理。

2. 流水线默认配置：paddlex/configs/pipelines/rotated_object_detection.yaml 展示了流水线级配置结构，默认使用PP-YOLOE-R-L模型、batch_size: 1、threshold: 0.5，model_dir为null时走内置模型参数。

3. 前后处理链路：在 paddlex/inference/models/object_detection/predictor.py 的DetRunnerPredictor.process中，预处理依次执行ReadImage → Resize/Normalize/PadStride 等 → ToBatch，推理后由DetPostProcess按 10 列格式的旋转框做阈值过滤与坐标裁剪，最终交给DetResult统一输出。

4. 结果可视化：paddlex/inference/models/object_detection/result.py 的draw_box对 8 点旋转框按顶点顺序绘制闭合多边形，标签文本的绘制位置依据旋转框的ymin自动调整，避免文字被框线遮挡。

5. 服务化部署：在 paddlex/inference/serving/basic_serving/_pipeline_apps/rotated_object_detection.py 中可以看到旋转目标检测的 FastAPI 服务化实现，infer端点接收图像与可选threshold，将boxes转换为bbox（旋转框 8 点坐标）、categoryId、categoryName、score的结构化响应，并可选择返回 base64 编码的可视化结果图。

结语

从旋转框的概念出发，本文完整覆盖了 PaddleX 旋转目标检测模块的模型选型、Python 快速集成、结果解析与输出，以及数据准备、数据校验、模型训练、评估、推理与集成的二次开发全流程，并结合源码剖析了旋转框 8 点坐标的输出链路、阈值过滤机制与可视化绘制原理。无论你是希望在遥感影像中快速接入旋转框检测能力，还是计划基于 PP-YOLOE-R 训练更高精度的自定义模型，上述内容都可以直接作为落地参考。

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• 模型推理服务