简介：面向使用 Label Studio 进行目标检测标注的开发者，这份资源提供了 YOLOv8 OBB 旋转框检测模型接入 Label Studio ML 后端所需的 Model.py 文件。借助该脚本，标注人员可在标注界面直接调用训练好的 YOLOv8 OBB 模型，完成半自动预标注，尤其适用于遥感影像、工业质检、文档版面分析等需要旋转矩形标注的场景。脚本封装了模型加载、图像预处理、推理预测、结果解析与标注回传等关键步骤，可直接替换或集成到现有 ML 后端中。资源为 zip 压缩包，仅含 1 个 Python 文件，大小约 2KB，结构精简，方便对照官方教程快速部署。目前已有 831 人学习下载，适合熟悉 YOLOv8 与 Label Studio 基础配置、希望搭建旋转框自动标注流程的中高级开发者。通过这份 Model.py，读者可免去从零编写模型推理、坐标转换与标注回传等集成代码，直接获得可运行的对接实现，大幅缩短半自动标注管线的搭建时间。
1. Label Studio 预标注链路里的 Model.py：给 OBB 旋转框检测搭一座桥
当标注任务里全是朝向各异的旋转目标时，人工拖着多边形的四个角点去贴目标边缘，一上午标不了几十张，标注员的手腕和情绪都崩得很快。Label Studio 的 ML 后端就是用来缓解这件事的：它在标注服务旁边额外跑一个推理服务，打开新任务时自动请求这个后端，把 YOLOV8 objectdetection-OBB 模型的检测结果先画出来，人工只需要确认和修正。整个链路里最关键的实现文件就是后端的Model.py，它决定了请求进来的图片如何被读取、如何推理、以及旋转框结果如何转回标注格式。这篇笔记从零讲清楚Model.py的完整写法、坐标转换细节和部署避坑点，适合已经在 Label Studio 里建好 OBB 标注项目、想要引入模型预标注来提速的团队。
2. 搭起 ML 后端骨架：环境、依赖与 YOLOV8 OBB 权重加载
2.1 先用脚手架生成最小后端：装依赖、跑命令、认目录
很多人在这一步会踩进同一个误区：上来就照着老教程直接改model.py，却不知道label-studio-ml的打包方式这几年已经重构过一次。2023 年之后的后端包名是label-studio-ml-backend，命令行工具仍是label-studio-ml，但目录结构、Model 基类接口都和旧版有了明显差异。先把环境装干净，后面省掉很多排查时间。
# Python 3.10 / 3.11 都可以，建议在虚拟环境内部操作 python -m venv venv source venv/bin/activate pip install -U label-studio-ml-backend ultralytics opencv-python-headless pillow我一般不会把torch写进这一行里，因为它必须跟本机 CUDA 版本对齐。如果机器上已经有可用的 PyTorch，直接复用；如果还没有，先按自己显卡的 CUDA 版本装好 torch，再执行上面这条安装命令。opencv-python-headless是为了在无显示环境下做图像解码，pillow则配合 label_studio_ml 自带的工具函数读图。
把后端项目和 yolov8 环境搭建步骤放在一起做会顺手很多。装完以后先确认命令行可用：
label-studio-ml --help能正常列出子命令，说明安装没出问题。接下来用脚手架生成一个最小后端：
label-studio-ml create ml_obb cd ml_obb生成的目录里，先认四个东西：
model.py：ML 后端核心文件，后面主要改它；_wsgi.py：WSGI 启动入口，一般不需要动；requirements.txt：部署时的依赖清单，按实际删除多余项；Dockerfile：容器部署模板，本地调试可以先不管。
先不做任何改动，直接启动一次默认后端，验证环境是否真的通：
label-studio-ml start . --port 9090另开一个终端输入：
curl http://localhost:9090/health如果返回{"status":"UP"}，说明脚手架本身没有问题，接下来可以安心把 Model.py 改造成 OBB 推理后端。注意这里必须是start .，命令接受的是包含model.py的目录路径，不是文件路径。
2.2 Model.py 的类骨架：setup 里加载权重，设备与类别映射一次定死
setup方法在服务启动时只执行一次，适合把权重、设备、类别表这类重资源准备好。不要在predict里反复执行YOLO(...)加载模型，那样每个请求都会出现肉眼可见的延迟。
# ml_obb/model.py import os import torch from ultralytics import YOLO from label_studio_ml.model import Model class OBBPredictor(Model): def setup(self): weights_path = os.environ.get('OBB_WEIGHTS', 'best_obb.pt') self.device = torch.device('cuda:0' if torch.cuda.is_available() else 'cpu') self.model = YOLO(weights_path) self.model.to(self.device) # 类别顺序必须和训练时的 data.yaml 完全一致 self.label_index = { 0: 'airplane', 1: 'vehicle', 2: 'ship', } self.min_conf = 0.35权重路径走环境变量，原因很简单：Model.py 一旦提交到 Git，不同机器的绝对路径会不一样。用环境变量把路径和代码隔离开，换机器部署时只改环境变量，不碰代码。
self.model.to(self.device)在部分 Ultralytics 版本里并不会真正把推理设备切过去，真正起作用的是后面predict方法里显式传入device参数，这里只是先做一个设备声明，后面写predict时还会再传一次。
类别映射是 OBB 后端最容易出错的地方。训练时data.yaml里的类别顺序决定了模型输出通道对应的类别编号，如果你换过数据集或者合并过多个数据集，编号很可能和业务标签对不上。更稳妥的做法是直接把训练用的data.yaml放在后端目录里，启动时读进来：
import yaml with open('data.yaml', 'r', encoding='utf-8') as f: data_cfg = yaml.safe_load(f) self.label_index = {int(k): v for k, v in data_cfg['names'].items()}这样后端和训练配置永远共用同一份类别来源，人工复查时只需要核对一个文件。如果你还没有训练好的 OBB 权重，可以先从 Ultralytics 官方发布页下载一个预训练 OBB 权重用来打通流程，等标注了几百张图再训练自己的权重。
2.3 标签配置决定预测结果长什么样：OBB 标注类型怎么选
写predict之前，得先把 Label Studio 那边的标签配置想清楚，因为预测结果的type、from_name必须跟标注配置对齐，否则标注页面根本拿不到预测框。OBB 旋转目标在 Label Studio 里常见有两种表示方式，我的建议是直接用PolygonLabels：
<View> <Image name="image" value="$image" zoom="true" rotate="true"/> <PolygonLabels name="label" toName="image" opacity="0.6" strokeWidth="1"> <Label value="airplane" background="#FF0000"/> <Label value="vehicle" background="#00FF00"/> <Label value="ship" background="#0000FF"/> </PolygonLabels> </View>用多边形的好处是：旋转框的语义完全落在四个控制点上，不依赖 Label Studio 不同版本对rectangle旋转字段的兼容性。YOLOv8 OBB 输出的是中心点、宽高、旋转角，把它转成四点多边形只需要几十行坐标变换代码，而且标注员在画面上拖顶点微调，体感比拖一个旋转矩形更直观。如果后续要把标注结果导出成训练集，多边形坐标也能通过最小外接矩形算法还原成xywhr。
也有团队用RectangleLabels加旋转角字段来标 OBB，预测类型对应写成rectangle，值里带x、y、width、height、rotation。这个方案在部分版本里能跑，但历史兼容性问题比较多，同一个旋转字段在旧版前端可能不生效。除非你的标注团队已经习惯这种交互，否则不建议拿它当主线。Model.py 里的逻辑应该以标签配置为准，配置定了，预测结果就跟着输出对应type，不要混着来。
3. 让 predict 真正干活的三个环节：读图、推理、把旋转框还给 Label Studio
3.1 predict 的输入输出契约：tasks 里到底有什么
predict方法的签名是predict(self, tasks, batch, **context)。tasks是一个列表，每个元素是一个标注任务的字典。实际调试时打印一下就看到结构了：
{ "id": 1023, "data": { "image": "/data/upload/2024/05/11/a1b2c3.jpg" }, "annotations": [] }data.image的值由标签配置里<Image value="$image"/>决定。在正常标注流程里，它通常是一个 Label Studio 内部的上传地址或者本地文件的绝对路径。context里会带上部署时配置的参数和其他运行时信息，大部分情况下用不到，但保留**context形参是必须的，免得脚手架升级后接口不兼容。
predict的返回值也不是随便一个字典都行。新版本的后端框架推荐用LabelStudioMLResponse包装预测结果，它会做一层字段校验，避免因为少写一个score导致前端渲染失败。下面几节先把结果一步一步拼出来，最后统一返回这个对象。
3.2 图像读取与推理参数：统一用 PIL，避免 BGR 通道翻车
读取图像是第一个容易翻车的环节。label_studio_ml.utils里提供了get_image_local_path和load_image，前者负责把 Label Studio 传过来的路径或 URL 整理成本地文件路径，后者负责真正把图片加载成 PIL Image。
from label_studio_ml.utils import get_image_local_path, load_image image_path = get_image_local_path(task['data']['image']) image = load_image(image_path) # PIL Image这里有一个关键选择：不要贪图 OpenCV 方便就额外用cv2.imread。OpenCV 默认读出来是 BGR 通道序，而 YOLOv8 训练时用的是 RGB，通道顺序反了会让模型在物体密集、纹理相似的数据上出现整片误检。直接用 PIL，通道序从头到尾保持一致，少一类玄学问题。
推理参数看起来是几个数字，实际上每一步都决定预标注质量：
results = self.model.predict( source=image, imgsz=1024, conf=self.min_conf, iou=0.7, device=self.device, verbose=False, )imgsz尽量和训练时一致。OBB 模型如果训练时用了 1024，推理时不要贪快改到 640，旋转小目标的检测率会明显掉。conf是置信度阈值。预标注场景建议比训练时调高一些，比如 0.35 到 0.5。阈值太低，页面上会堆满低置信度框，标注员的注意力被稀释。iou用于 NMS 去重。默认 0.7，如果目标互相遮挡严重，可以调到 0.75 到 0.8，减少相邻框被合并的概率。device必须显式传self.device，否则 Ultralytics 在部分环境中会自己挑一个设备，可能落到 CPU 上跑，速度慢好几倍。
results是一个列表，通常取results[0]就能拿到当前图像的预测结果。如果模型检测不到任何目标，results[0].obb会是 None，这个空判断不能省。
3.3 后处理是重头戏：xywhr 转 Label Studio 四点多边形
YOLOv8 OBB 的输出和普通目标检测不一样，不能用results[0].boxes，必须取.obb属性。每一个旋转框对象里包含四样东西：
| 字段 | 含义 | 说明 |
|---|---|---|
| cx, cy | 旋转框中心点 | 像素坐标，基于原始图像分辨率 |
| w, h | 旋转框宽高 | 宽高不受旋转影响，是原始意义上的长和宽 |
| r | 旋转角度 | 单位是弧度，不是角度 |
| cls / conf | 类别索引与置信度 | 类别索引对应训练时的 names 顺序 |
很多移植代码在这里栽跟头：把弧度当成角度直接算，结果旋转框全部歪 90 度，长边短边互换。下面这个函数把旋转框转成四个顶点，按统一顺序输出，保证 Label Studio 多边形不会自交：
import math def obb_to_polygon(cx, cy, w, h, angle_rad): cos_a = math.cos(angle_rad) sin_a = math.sin(angle_rad) half_w = w / 2.0 half_h = h / 2.0 # 局部坐标下的四个角点，按顺时针排列 local = [ (-half_w, -half_h), (half_w, -half_h), (half_w, half_h), (-half_w, half_h), ] points = [] for dx, dy in local: x = cx + dx * cos_a - dy * sin_a y = cy + dx * sin_a + dy * cos_a points.append([round(x, 2), round(y, 2)]) return points这个变换就是二维旋转矩阵的应用。局部角点先相对于中心点偏移，再按angle_rad旋转，最后平移到图像坐标。注意角度单位是弧度，如果你在调试时打印结果想肉眼验证，可以用angle_rad * 180 / math.pi转成角度输出。
把旋转框拼成 Label Studio 能识别的预测结果：
result_item = { "from_name": "label", "to_name": "image", "type": "polygon", "value": { "points": points, "polygon": points, }, "score": conf, }from_name和to_name必须和标签配置里的控件名字一致，配置里写的是name="label"和toName="image"，这里就照抄。type是polygon，和PolygonLabels对应。points里的坐标是绝对像素值，不是归一化小数，这个尤其注意，因为模型输出的坐标本来就是像素坐标，不需要额外缩放。
3.4 把多目标结果组装成一次完整预测返回
把上面的零件拼起来，写完整的predict方法。一次请求进来可能有多个任务，每个任务都要独立走一遍读图、推理、后处理的流程。
from label_studio_ml.response import LabelStudioMLResponse class OBBPredictor(Model): def predict(self, tasks, batch, **context): predictions = [] for task in tasks: image_path = get_image_local_path(task['data']['image']) image = load_image(image_path) results = self.model.predict( source=image, imgsz=1024, conf=self.min_conf, iou=0.7, device=self.device, verbose=False, ) obb = results[0].obb if obb is None: predictions.append({"result": [], "score": 0.0}) continue result_items = [] conf_list = [] for i in range(len(obb)): xywhr = obb.xywhr[i].cpu().numpy() cx, cy, w, h, angle_rad = xywhr class_idx = int(obb.cls[i].item()) conf = float(obb.conf[i].item()) label_name = self.label_index.get(class_idx, f"class_{class_idx}") points = obb_to_polygon(cx, cy, w, h, angle_rad) result_item = { "from_name": "label", "to_name": "image", "type": "polygon", "value": { "points": points, "polygon": points, }, "score": conf, "id": f"obb_{i}", } result_items.append(result_item) conf_list.append(conf) predictions.append({ "result": result_items, "score": max(conf_list) if conf_list else 0.0, }) return LabelStudioMLResponse( predictions=predictions, model_version="yolov8-obb-001", )代码逻辑是：先解析任务里的图片路径，加载图像，然后调用model.predict一次推理；检测结果为空就返回空 result；有结果则逐个把xywhr转成多边形，组装成result_item。最终整个任务的score取最大置信度，这个值会用于 Label Studio 端的预测排序。
注意id字段，最好保证每次预测的唯一性。如果你在predict返回值里复用了上一轮的id，Label Studio 前端在做预测合并时可能出现旧框残留的情况。用obb_加循环下标基本不会撞。
4. 本地把 ML 后端跑起来：自测、联动与旋转框验证
4.1 用 curl 直接打 predict 接口：绕开页面先看返回
写完后端代码，最怕直接在 Label Studio 页面里测，因为页面链路长，出错时很难判断是后端的问题、网络的问题还是前端渲染的问题。我更习惯先用 curl 把后端接口摸透再上标注页。
label-studio-ml start . --port 9090服务起来后，构造一个最简单的预测请求：
curl -X POST http://localhost:9090/predict \ -H "Content-Type: application/json" \ -d '{"tasks":[{"data":{"image":"/absolute/path/to/test.jpg"}}]}'返回的 JSON 里会有results和model_version字段。重点检查两块：一是results[0].result里是不是有预期的多边形点；二是坐标值有没有超出图像宽高范围。如果图像是 1920x1080，点坐标却出现 5000，说明坐标空间没有对齐，这通常是读取图像路径时用错了图片，或者模型推理的输入尺寸被内部缩放后没有映射回原图。
这个阶段不要去看怪异的可视化效果，直接用数值判断最可靠。你还可以在本地写一个三行脚本，把返回的四个点和图片画在一起：
import json import urllib.request body = json.dumps({"tasks": [{"data": {"image": "/absolute/path/to/test.jpg"}}]}).encode() req = urllib.request.Request("http://localhost:9090/predict", data=body, headers={"Content-Type": "application/json"}) resp = json.loads(urllib.request.urlopen(req).read()) for pred in resp["results"][0]["result"]: print(pred["value"]["points"], pred["score"])这样能看到每个预测框的坐标和置信度，对比原图里的目标位置，角度转没转对立刻能看出来。
4.2 在 Label Studio 页面挂接这个后端：三步走完联动
curl 通了以后，再去 Label Studio 页面绑定后端。路径是项目设置里的 Machine Learning 页面：
- 点击 Add Model，输入刚才启动的 URL：
http://localhost:9090。 - 如果有鉴权要求，填上 Label Studio 的 API Token；本地调试一般不需要。
- 保存后回到标注页面，打开任意一个任务，等一两秒，预测框会自动出现在图像上。
页面联动的常见问题集中在from_name和to_name的对应关系上。如果后端日志显示请求成功、返回了results，但页面上一片空白，十有八九是返回的from_name和标签配置里的name不一致。多检查一遍model.py里的字符串和label_config.xml，这种错误后端不会报错，因为框架层只负责转发数据，语义对不对它不管。
4.3 验证旋转框吻合度的三个小习惯
页面联动成功后，不要急着让标注团队开工，先用几张典型图验证旋转框质量：
第一，用有明显朝向的物体验证。拿一张飞机、汽车这类长宽比大且方向清晰的图，看预测的多边形长边是否贴合目标的长轴。如果所有框都变成水平直框，说明角度被当成 0 处理了，问题出在xywhr解析或弧度转换上。
第二，检查多边形是否自交。Label Studio 渲染多边形时按你给定的点顺序连线闭合，如果点顺序乱了，会出现交叉的多边形，视觉上一眼就能看到。上面代码里局部角点按顺时针排列，基本不会出问题，但如果你自己改了顺序，就要留意。
第三，把模型预测结果和人工标注结果对齐比较。取同一张图，先人工标一遍，再打开预标注，看同一目标的角度偏差是不是在可接受范围内。OBB 模型对角度特别敏感，差 2 到 3 度人工修正很快，差 20 度以上就要回看训练数据里是不是存在角度标注不一致的问题。
5. 避坑记录：Model.py 调试中最常翻车的几个位置
5.1 图片本地路径解析失败：后端拿不到图
现象：后端日志提示找不到文件，或者请求直接超时。检查task['data']['image']发现它是一串 HTTP URL，但后端服务所在机器访问不了这个地址。
原因：Label Studio 传给你的data.image往往是对应上传文件的内部访问地址。ML 后端和标注服务不在同一台机器，或者没有配置鉴权时，这个地址无法从后端侧下载。
解决：在后端启动的同一台机器上配置LABEL_STUDIO_HOST和LABEL_STUDIO_API_KEY环境变量，让get_image_local_path能通过 API 拉取图片；更省事的做法是把图片目录做成共享存储，让后端直接走本地路径。我一般倾向于共享存储，因为对大批量任务来说，逐个走 HTTP 下载图片的耗时不可忽略。
5.2 xywhr 的角度单位没统一，旋转框全部歪 90 度
现象：预测框的中心点和宽高基本正确，但整体旋转方向不对，长边短边互换，界面里看起来就是“框倒了”。
原因：xywhr里的r是弧度，不是角度。很多移植代码把它当角度直接传入三角函数，或者把它乘了 180 再除 pi 导致方向反转。
解决：在obb_to_polygon函数里严格统一使用弧度，不要在外面做任何角度转换。如果要从调试日志里肉眼判断，只在打印时转换成角度，最终参与坐标运算的一律用弧度。检查方法也简单：在模型推理后打印一行angle_rad * 180 / math.pi，和原图目标朝向对比一下心里就有数了。
5.3 from_name / to_name 与标签配置对不上，预测结果石沉大海
现象：后端日志里没有报错，predict 返回正常，但标注页面不显示任何预标注框，前端控制台也没有异常。
原因：返回结果里的from_name和to_name字符串与label_config.xml不一致。框架只负责转发数据，不校验字段语义，所以不会报错。
解决：打开项目设置的标签配置，确认PolygonLabels那个控件定义的name和toName，再把model.py里的from_name和to_name一字不差地照抄过来。注意大小写，to_name不要写成toname。
5.4 置信度阈值太低，预标注变成刷屏
现象：标注页面打开后，一张图上堆了几十个框，很多框明显对着背景纹理，标注员右键删框的时间比从头标注还长。
原因：直接用了模型训练时的conf=0.25，这个值对训练阶段合适，但对预标注场景太低。预标注的目的是给人省时间，不是展示模型能检测到多少目标。
解决：预标注场景把conf调到 0.45 到 0.6。如果数据集中目标密集且互相遮挡严重，可以适当降低一点，但不要低于 0.35。这个值建议做成环境变量或者类属性，不要写死在推理代码里，这样现场调整阈值的时候不用改代码重启服务。
5.5 模型一直跑 CPU，显卡利用率上不去
现象：服务能跑，但一张图推理耗时几百毫秒甚至几秒，GPU 利用率很低甚至为零。
原因：只调用了self.model.to(self.device)，没有在predict里显式传device参数。Ultralytics 在内部会根据参数重新选择设备，你的to()调用可能根本没生效。
解决：在model.predict里加上device=self.device，并用环境变量控制默认设备。确认设备是否生效可以直接在日志里打一行print(self.device)，或者用nvidia-smi看显存是否有占用。这个问题在多人共用 GPU 的服务器上尤其容易漏掉，因为它不报错，只是速度慢。
6. 把预标注质量再往上提一档的后处理习惯
6.1 角度归一化与类别级置信度：两个快速调优手段
YOLOv8 OBB 的角度定义在-pi/2到pi/2之间，意味着一个旋转目标在表示上存在两种等价形式：一个角度加半圈，等价于同一个框的角度不变但长宽互换。模型本身已经做了归一化，但你在转换出来的多边形的顶点顺序上还是会留下痕迹。我的习惯是每次转换后检查多边形四个点的排列方向，确保顺时针排列，并且第一条边的方向对应目标的长边。这个小细节能避免 Label Studio 渲染时出现交叉连线。
类别级置信度比全局阈值更实用。全局阈值调到 0.5，如果某个类别本来就难检，它的召回率会掉得太狠；调到 0.3，其他好检的类别就开始刷屏。更好的做法是在setup阶段为每个类别单独设一个阈值，比如self.class_conf = {"vehicle": 0.45, "ship": 0.55}，在组装 result 之前按类别查表，查不到就使用全局默认值。这个方法用几行代码换来的是标注团队手感的大幅提升。
6.2 为落地留一手：TensorRT 部署思路
Model.py 在本地跑通后，接着要考虑标注团队多人同时使用时的吞吐量。预标注和训练不一样，它不追求最高单图准确率，而是追求“稳定、可预期、别让标注员等”。如果单张图上要跑 1024 分辨率的 OBB 推理，纯 PyTorch 模型在高并发下很容易把显存占满。常见做法是先把权重导出成 TensorRT 的 engine 文件：
yolo export model=best_obb.pt format=engine imgsz=1024 device=0导出后把 Model.py 里的权重路径指向.engine文件，Ultralytics 在predict时走 TensorRT 推理，速度通常能提升两到三倍。注意换用 engine 后，imgsz只能沿用导出时的尺寸，不要临时改，否则要么报错要么自动插值导致精度下降。
如果连 GPU 都不宽裕，另一个保底方案是把imgsz从 1024 降到 768，同时把预处理里加入一个简单的图像增强，比如对超大图先缩放再裁剪，保证长边不超过 1024。代价是小目标召回率会掉一些，但换来了更稳定的并发响应时间。
我自己在 OBB 项目上踩过的那几个坑，最后基本都收敛在角度单位、字段对齐和置信度这三个问题上。把 Model.py 的前五分钟调试时间花在确认这三件事上，后面能省一整天的排查精力。希望帮到你。
本文还有配套的精品资源，点击获取
