Label-studio ml 后端接入 YOLOV8 OBB：Model.py 核心解析与避坑指南

简介：这份资源是面向使用 Label Studio 进行半自动标注的算法工程师与深度学习开发者，提供 YOLOv8 目标检测 OBB（旋转框）模型接入 Label Studio ML 后端所需的 Model.py 文件。它解决的是在 Label Studio 中集成 YOLOv8 OBB 模型、实现预标注与半自动标注流程时的后端适配问题，适合已具备一定 Python 与目标检测基础、希望提升标注效率的中高级用户。压缩包为 zip 格式，共 1 个文件，即一个 py 脚本，整体约 2KB，体积轻量，便于直接放入 ML 后端目录使用。该脚本承担模型加载、推理与 Label Studio 预测结果转换等核心逻辑，可作为搭建半自动标注流水线的关键组件。目前已有 831 人学习，配套博文提供了完整接入教程，读者可据此快速完成 YOLOv8 OBB 模型与 Label Studio 的对接，减少自行调试后端接口的时间成本。

1. Label-studio ml 后端接入 YOLOV8 OBB：Model.py 到底在管什么

如果你正在做旋转框标注，大概率绕不开 Label-studio 的 ml 后端。普通水平框检测接起来很顺，换成 YOLOV8 objectdetection-OBB 就卡在Model.py上——预测结果要么画不出来，要么角度全乱，要么后端直接报维度不匹配。这个文件就是 ml 后端和模型之间的翻译官：它负责把 Label-studio 发来的图片 URL 读成张量，调用 YOLOV8 OBB 推理，再把旋转框的四个角点转成 Label-studio 认识的百分比坐标。搞懂它，你就能把任意 OBB 权重挂进标注流水线，做预标注、主动学习、模型迭代闭环。适合已经跑通 YOLOV8 训练、但卡在后端对接这一步的工程师，也适合想用旋转框做遥感、航拍、文档版面分析的团队。

2. 从 Label-studio ml 后端到 OBB 推理：Model.py 的职责边界

2.1 ml 后端不是模型服务，是协议适配层

很多人第一次看 Label-studio ml 后端，会以为它是个通用推理服务器。其实它只做三件事：接收 Label-studio 发来的 JSON 任务、按约定格式返回预测、把预测转成标注。真正的模型加载和推理，全部由你写的Model.py承担。Label-studio 官方给的label-studio-ml-backend仓库里，model.py是一个抽象基类，你继承它并实现predict方法即可。对于 YOLOV8 objectdetection-OBB，关键差异在于输出不是[x, y, w, h, conf, cls]，而是[cx, cy, w, h, angle, conf, cls]，且角度定义在不同版本里有差异。ml 后端不关心这些，它只要求你返回的result列表里每个元素带from_name、to_name、type、value。所以Model.py的核心任务就是：把 OBB 的旋转框转成 Label-studio 的rectanglelabels或polygonlabels能消费的结构。

常见做法是继承LabelStudioMLBase，在__init__里加载 YOLO 模型，在predict里逐张推理。这里有个容易忽略的点：ml 后端默认会并发调用predict，而 Ultralytics 的 YOLO 对象不是线程安全的。我一般会在__init__里加一个threading.Lock()，推理时加锁，或者直接用model.predict的stream模式配合队列。另一个边界是图片读取：Label-studio 传过来的是本地文件路径或 URL，Model.py里要用requests或PIL读成 numpy 数组，不能直接丢给 YOLO 的predict传路径，否则在容器里路径映射会对不上。

2.2 YOLOV8 OBB 的输出结构与坐标转换

YOLOV8 OBB 的results[0].obb里有xywhr、conf、cls，其中xywhr是中心点、宽、高、弧度角。Label-studio 的旋转框标注格式是rectanglelabels带rotation字段，角度是角度制，且旋转中心是矩形中心。转换时要注意：Ultralytics 输出的角度范围通常是[-pi/2, pi/2)，而 Label-studio 的rotation接受-180到180。直接乘180/pi后，如果角度为负，需要根据宽高是否交换来修正。更稳妥的做法是转成polygonlabels，用四个角点的百分比坐标，这样不依赖角度定义，Label-studio 也能正常渲染。四个角点由cv2.boxPoints或手动计算：以中心为原点，宽高为边，旋转角度后加回中心，再除以图片宽高归一化。

下面是一个最小可用的Model.py片段，展示从 OBB 输出到 Label-studio 结果的转换逻辑：

import threading import numpy as np from PIL import Image from ultralytics import YOLO from label_studio_ml.model import LabelStudioMLBase class YOLOv8OBBModel(LabelStudioMLBase): def __init__(self, **kwargs): super().__init__(**kwargs) # 加载 OBB 权重，任务类型必须是 obb self.model = YOLO("yolov8n-obb.pt") self.lock = threading.Lock() # 从 label config 里解析标签名，保证顺序一致 self.labels = self.get_labels() def _obb_to_polygon(self, obb_xywhr, img_w, img_h): cx, cy, w, h, angle = obb_xywhr # 计算四个角点，再归一化成百分比 cos_a, sin_a = np.cos(angle), np.sin(angle) dx, dy = w / 2, h / 2 corners = np.array([ [-dx, -dy], [dx, -dy], [dx, dy], [-dx, dy] ]) rot = np.array([[cos_a, -sin_a], [sin_a, cos_a]]) corners = corners @ rot.T + np.array([cx, cy]) corners[:, 0] = np.clip(corners[:, 0] / img_w * 100, 0, 100) corners[:, 1] = np.clip(corners[:, 1] / img_h * 100, 0, 100) return corners.flatten().tolist() def predict(self, tasks, **kwargs): results = [] for task in tasks: img_path = task["data"]["image"] image = Image.open(img_path).convert("RGB") img_w, img_h = image.size with self.lock: preds = self.model.predict(image, conf=0.25, iou=0.5, verbose=False) obb = preds[0].obb items = [] if obb is not None: xywhr = obb.xywhr.cpu().numpy() confs = obb.conf.cpu().numpy() clss = obb.cls.cpu().numpy().astype(int) for i in range(len(xywhr)): points = self._obb_to_polygon(xywhr[i], img_w, img_h) items.append({ "from_name": "label", "to_name": "image", "type": "polygonlabels", "value": { "points": [points[j:j+2] for j in range(0, 8, 2)], "polygonlabels": [self.labels[clss[i]]] }, "score": float(confs[i]) }) results.append({"result": items}) return results

这段代码里，self.labels来自 Label-studio 的标注配置，必须和训练时的类别顺序一致，否则标签会错位。conf和iou是 OBB 推理的两个关键阈值，旋转框重叠多时iou要调低到 0.3 左右。polygonlabels的points是[[x1,y1],[x2,y2],...]的列表，每个点是百分比。如果你坚持用rectanglelabels，需要把value换成x, y, width, height, rotation，其中x, y是左上角百分比，width, height是百分比宽高，rotation是角度制。但旋转框的左上角在旋转后不好定义，所以 polygon 更稳。

2.3 把 Model.py 挂进 ml 后端并跑通本地推理

写完Model.py只是第一步，还要让 ml 后端能加载它。标准做法是在项目目录下建model.py和_wsgi.py，用label-studio-ml start启动。但 YOLOV8 依赖较重，我一般直接写一个Dockerfile，基于python:3.10-slim，装ultralytics、label-studio-ml、opencv-python-headless。启动命令用label-studio-ml start . --port 9090。本地验证时，不要直接开 Label-studio 界面，先用curl发一个假任务，看返回结构对不对：

curl -X POST http://localhost:9090/predict \ -H "Content-Type: application/json" \ -d '{"tasks":[{"data":{"image":"/data/test.jpg"}}]}'

如果返回的result里points数量不对，或者polygonlabels为空，先检查self.labels是否解析成功。get_labels()会从 Label-studio 的label_config里读Label标签的value，如果配置里用的是PolygonLabels，解析出来的就是多边形标签名。另一个常见问题是图片路径：ml 后端容器里的/data要和 Label-studio 的本地存储挂载一致，否则Image.open会报FileNotFoundError。我通常会在predict里加一层判断，如果是http开头就用requests读字节流，否则按本地路径读。

3. 避坑：OBB 接 ml 后端最容易翻车的 5 个点

3.1 角度定义不一致导致框旋转 90 度

现象：预测出来的旋转框和实际目标垂直，或者宽高互换。原因：Ultralytics 的 OBB 角度定义在不同版本里有变化，早期版本xywhr的r是弧度，且范围是[-pi/2, pi/2)，但有些导出模型（比如 ONNX）会输出[0, pi/2)。Label-studio 的rotation是角度制，且以顺时针为正。解决：统一转成 polygon 输出，彻底绕开角度定义。如果必须用rectanglelabels，在转换后加一个判断：当w < h时，交换w, h并把角度加 90 度，再归一化到[-90, 90]。

3.2 并发推理导致 CUDA OOM 或结果错乱

现象：Label-studio 一次发多张图，后端报CUDA out of memory，或者返回的框和图片对不上。原因：ml 后端默认多线程调用predict，而 YOLO 模型实例共享，显存被多线程同时占用。解决：在__init__里加self.lock = threading.Lock()，推理时with self.lock:。如果吞吐要求高，改成单线程队列，或者每个线程独立加载模型（显存够的话）。更稳的做法是设置model.predict的batch参数，一次推理多张，但 ml 后端的predict接口是按任务列表来的，需要自己攒批。

3.3 标签顺序错位导致类别全错

现象：预测框位置对，但标签名全是错的，比如把“飞机”标成“船”。原因：self.labels的顺序和训练时data.yaml里的names顺序不一致。Label-studio 的label_config里标签顺序是你手动写的，而 YOLO 训练时的类别顺序由数据集决定。解决：不要依赖get_labels()的返回顺序，直接在Model.py里硬编码一个class_names列表，和训练时完全一致。如果标签多，从data.yaml里读，但确保 ml 后端容器里能访问到该文件。

3.4 图片 EXIF 方向导致坐标偏移

现象：手机拍的图，标注框整体偏移或旋转。原因：PIL 读图时默认不应用 EXIF 旋转，而 Label-studio 前端显示时应用了。解决：用PIL.ImageOps.exif_transpose(image)先纠正方向，再推理。或者统一在predict里读图后做一次exif_transpose，保证和前端显示一致。

3.5 置信度阈值和 NMS 参数不匹配业务

现象：漏检严重，或者同一个目标出多个框。原因：OBB 的conf默认 0.25，iou默认 0.7，但旋转框的 NMS 和水平框不同，密集场景下 0.7 会保留大量重叠框。解决：遥感或文档场景，conf调到 0.4~0.5，iou调到 0.3~0.4。如果还是漏，检查agnostic_nms是否开启，多类别重叠时开启会合并不同类。这些参数在model.predict里传，不要写死在模型导出时。

4. 进阶：用 polygon 输出做主动学习与热力图验证

4.1 把 OBB 预测转成 Label-studio 预标注的完整配置

要让预标注在 Label-studio 里直接可编辑，label_config必须用PolygonLabels，并且Model.py返回的from_name要和配置里的name一致。一个可用的配置片段：

<View> <Image name="image" value="$image"/> <PolygonLabels name="label" toName="image"> <Label value="plane" background="#FFA39E"/> <Label value="ship" background="#D4380D"/> </PolygonLabels> </View>

对应Model.py里from_name="label"，to_name="image"。如果配置里用了RectangleLabels，返回的type要改成rectanglelabels，value里用x, y, width, height, rotation。我建议统一用 polygon，因为旋转框的四个角点信息更完整，后续导出 COCO 或 YOLO OBB 格式时不用再反算。

4.2 用预测结果反推模型短板：热力图与损失曲线

预标注跑起来后，别急着全量标注。先抽 50 张图，把Model.py返回的score存下来，按分数排序。低分样本就是模型的盲区。更直观的做法是，在predict里额外返回一个热力图叠加图，但 ml 后端不支持直接返回图片。我一般会在本地写一个脚本，用同样的Model.py逻辑跑一遍验证集，把 OBB 的xywhr画到原图上，同时用model.predict的save=True输出可视化结果。如果发现某类目标的角度预测总是偏，检查训练时的degrees增强参数，OBB 任务里degrees设 0 会导致角度过拟合，设 180 又太激进，通常 90 左右比较稳。损失曲线方面，YOLOV8 OBB 的loss包含box_loss、cls_loss、dfl_loss和angle_loss，如果angle_loss震荡不降，多半是学习率太大或 batch 太小，先把lr0降到 0.001 试试。

4.3 一个我踩过的坑：ml 后端超时与重试

Label-studio 默认等待 ml 后端 30 秒，超时后会重试。OBB 模型如果输入分辨率大（比如 1024），单张推理可能超过 30 秒。现象是前端一直转圈，后端日志里同一个任务被请求多次。解决：在Model.py里把输入尺寸降到 640，或者用model.export(format="onnx")导出后走 ONNX Runtime，推理速度能快 2~3 倍。另外，在 ml 后端的启动参数里加--timeout 120，给足时间。如果还是慢，检查是不是每次predict都重新加载了模型——模型必须在__init__里加载一次，不能放在predict里。

我现在的习惯是，任何 OBB 项目接 ml 后端，先跑通一张图的 polygon 输出，再用curl压 10 张图看显存和耗时，最后才开 Label-studio 界面。这样能把大部分坐标和并发问题挡在标注之前。希望帮到你。

本文还有配套的精品资源，点击获取