简介：本资源是面向计算机视觉与智能标注工程实践者的轻量级后端模型适配文件，专为在Label Studio ML平台中集成YOLOv8目标检测-OBB（oriented bounding box）模型提供核心支持。适用于需实现旋转框半自动标注的工业检测、遥感图像分析等场景，尤其适合已掌握PyTorch基础与Label Studio部署流程的中级开发者快速落地模型闭环。压缩包仅含1个Python源文件（model.py），体积仅2KB，代码聚焦于模型加载、预处理、OBB格式推理输出及Label Studio ML协议兼容封装，无冗余依赖，可直接嵌入Label Studio ML backend服务。目前已有832人学习下载，读者可直接获取经过实测验证的OBB模型对接逻辑、关键参数配置说明及与Label Studio前端交互的数据结构定义，显著降低自定义模型接入门槛，避免重复开发序列化与坐标转换模块。
1. Label Studio ML 的 YOLOv8-OBB 模型不是“插个 model.py 就能半自动标注”：它真正解决的是旋转框标注中坐标系错位、类别映射断裂、推理结果无法反哺标注界面这三重隐性失效
你把model.py放进 Label Studio ML 的backend/目录，启动服务，上传一张带倾斜电线杆或斜停车辆的图——结果预测框歪着飘在空中，类别名变成class_0，甚至根本不出框。这不是模型没训好，而是 Label Studio ML 的预测流水线在 OBB（Oriented Bounding Box）场景下默认崩了。YOLOv8 原生输出的是(cx, cy, w, h, angle)五元组，但 Label Studio 的RectangleLabels或PolygonLabels期望的是顶点坐标序列或轴对齐矩形；model.py若只做predict()调用而不重写坐标变换、类别 ID 映射、置信度过滤与格式归一化，整个半自动标注链路就卡死在「模型输出」和「前端渲染」之间。这份model.py文件的价值，不在于它多精巧，而在于它显式暴露并修复了这个被多数教程忽略的底层契约断裂：它让 YOLOv8-OBB 的原始输出，真正可落地为 Label Studio 界面里可编辑、可校验、可回传训练的标注数据。搞懂它，你就拿到了旋转目标检测标注流水线的「协议说明书」。
2. YOLOv8-OBB 输出到 Label Studio 标注格式的坐标系转换：为什么直接画(cx,cy,w,h,angle)会偏移、缩放、旋转错位
Label Studio 的标注数据结构是面向人类交互设计的，而 YOLOv8-OBB 的输出是面向模型训练优化的。二者坐标系原点、单位、角度定义、顶点顺序完全不一致——这是所有翻车的根源。不处理这个，model.py再多torch.load()也白搭。
2.1 坐标系原点与单位差异：图像像素 vs 归一化值
YOLOv8-OBB 默认输出的是归一化坐标：cx,cy,w,h全部除以图像宽高（img.shape[2],img.shape[1]），范围在[0,1]；而 Label Studio 的polygon或rectangle标注要求的是绝对像素坐标（如{x: 120, y: 85, width: 64, height: 32}）。若不做反归一化，预测框会永远挤在左上角一个极小区域。
# model.py 中必须存在的反归一化逻辑（关键！） def denormalize_bbox(cx_norm, cy_norm, w_norm, h_norm, angle_rad, img_w, img_h): cx = int(cx_norm * img_w) cy = int(cy_norm * img_w) # ← 注意！这里常踩坑：YOLOv8 输出的 cx/cy 是按 w/h 归一化，但实际应分别乘 img_w 和 img_h cy = int(cy_norm * img_h) # ✅ 正确：cx ← × img_w, cy ← × img_h w = int(w_norm * img_w) h = int(h_norm * img_h) return cx, cy, w, h, angle_rad提示：YOLOv8 的
boxes.xywhr输出中，cx,cy是相对于整图宽高的归一化值，但w,h同样需分别乘img_w和img_h才得真实像素尺寸。很多model.py实现错误地统一乘img_w，导致高瘦图中框严重压扁。
2.2 角度定义冲突：YOLOv8 的angle_rad是逆时针 vs Label Studio 的顺时针 + 基准不同
YOLOv8-OBB 的angle是以x 轴正方向为 0°，逆时针为正的弧度值（-π/2 < angle ≤ π/2）；而 Label Studio 的polygon渲染引擎（基于 Fabric.js）内部使用的是顺时针为正、且以 y 轴为基准的角度体系。更致命的是：Label Studio 前端不直接接受角度参数，它只认顶点坐标。因此，model.py必须将(cx,cy,w,h,angle)完整解包为 4 个顶点(x0,y0), (x1,y1), (x2,y2), (x3,y3)，且顶点顺序必须是顺时针闭合多边形（Label Studio 强制要求），否则渲染错乱或无法选中。
import numpy as np def obb_to_polygon(cx, cy, w, h, angle_rad): """ 将 YOLOv8-OBB 的中心+宽高+角度 → 顺时针闭合四顶点多边形（像素坐标） 返回 list of dict: [{"x": x0, "y": y0}, {"x": x1, "y": y1}, ...] """ # 1. 构造局部坐标系下的四个顶点（中心在原点，x向右，y向下） # 注意：图像坐标系 y 向下为正，因此旋转矩阵需适配 cos_a, sin_a = np.cos(angle_rad), np.sin(angle_rad) # 局部顶点（按顺时针顺序：右上→右下→左下→左上） local_pts = np.array([ [ w/2, -h/2], # 右上：x+ y-（因y向下为正，故-y） [ w/2, h/2], # 右下 [-w/2, h/2], # 左下 [-w/2, -h/2], # 左上 ]) # 2. 旋转（绕原点逆时针 angle_rad）→ 图像坐标系下需用标准旋转矩阵 R = np.array([[cos_a, -sin_a], [sin_a, cos_a]]) rotated = local_pts @ R.T # 注意转置，因 R 作用于列向量 # 3. 平移到全局中心 (cx, cy) global_pts = rotated + np.array([cx, cy]) # 4. 转为 Label Studio 要求的 dict list（顺时针，已满足） return [ {"x": float(global_pts[0, 0]), "y": float(global_pts[0, 1])}, {"x": float(global_pts[1, 0]), "y": float(global_pts[1, 1])}, {"x": float(global_pts[2, 0]), "y": float(global_pts[2, 1])}, {"x": float(global_pts[3, 0]), "y": float(global_pts[3, 1])}, ]这段代码的关键机制在于：它没有试图“转换角度”，而是彻底放弃角度字段，直接用几何变换生成顶点。因为 Label Studio 前端根本不消费angle字段——它只消费polygon的points数组。任何想通过angle字段驱动前端旋转矩形的尝试，都会失败。这是model.py必须承担的职责：做格式翻译官，而非角度搬运工。
2.3 类别 ID 映射断裂：YOLOv8 的cls=0不等于 Label Studio 的"pole"标签
YOLOv8 训练时用的是整数类别 ID（如0: pole,1: car），但 Label Studio 的label_config.xml中定义的是字符串标签名（<Label value="pole" />）。model.py若直接把int类别塞进result["value"]["labels"]，前端会显示class_0。必须建立显式映射表，并确保该表与训练时的names字典严格一致。
# 在 model.py 初始化时加载 self.class_names = model.names # 来自 torch.load("best.pt")["names"]，如 {0: "pole", 1: "car"} # 在 predict() 中构建 result 时： for i, (box, cls_id, conf) in enumerate(zip(boxes.xywhr, boxes.cls, boxes.conf)): if conf < self.score_threshold: continue cls_name = self.class_names[int(cls_id)] # ← 关键：int(cls_id) 确保索引正确 polygon = obb_to_polygon(...) # 如上函数 result = { "from_name": "label", "to_name": "image", "type": "polygon", "value": { "points": polygon, "labels": [cls_name] # ← 必须是字符串，不能是 int } }注意：
model.names是dict，不是list。YOLOv8 导出的.pt文件中model.names是{0: 'a', 1: 'b'}形式，而非['a','b']。若误用model.names[int(cls_id)]当作列表索引，当类别 ID 不连续（如跳过 2）时会KeyError。正确做法是model.names.get(int(cls_id), "unknown")。
3. Label Studio ML 的 predict 接口契约：为什么你的 model.py 总是返回空结果或 500 错误
Label Studio ML 不是 Flask 应用，它是一个基于label-studio-mlSDK 的轻量级服务框架，其predict()方法有严格的输入/输出 Schema。违反任一字段，就会静默失败或 HTTP 500。这份model.py的核心价值，在于它完整实现了这个契约，而不是仅调用model.predict()。
3.1 输入：task 是字典，不是单张图片路径
Label Studio ML 的predict()方法接收的是task: Dict，其中关键字段是：
task["data"]["image"]: 一个base64 编码的图片 URL（如"data:image/png;base64,iVBOR..."），不是本地路径；task["project"]: 项目 ID，用于日志或路由；task["id"]: 任务 ID，可用于去重。
很多初版model.py直接cv2.imread(task["data"]["image"])，必然失败。必须先解码：
import base64 from io import BytesIO from PIL import Image import numpy as np def _get_image_from_task(task): image_url = task["data"]["image"] if image_url.startswith("data:image"): # 提取 base64 数据部分 header, encoded = image_url.split(",", 1) data = base64.b64decode(encoded) pil_img = Image.open(BytesIO(data)).convert("RGB") return np.array(pil_img) # HWC, uint8 else: # 处理远程 URL（需 requests） raise ValueError("Only base64 image URLs supported in this model.py")3.2 输出：results 必须是 List[Dict]，且每个 result 必须含完整 schema
Label Studio ML 要求predict()返回List[Dict]，每个Dict是一个标注结果，必须包含：
"from_name": 对应 label config 中<Label from_name="xxx" />的from_name"to_name": 对应<Image name="xxx" />的to_name"type":"polygon"（OBB 必须用 polygon，rectangle 不支持旋转）"value": 必须含"points"（list of dict）和"labels"（list of str）
漏掉任一字段，Label Studio 前端就不渲染。常见错误是只写"points"，忘了"labels"，结果框出来但没类别名。
# ✅ 正确的 result 结构（OBB 场景） result = { "from_name": "label", # 必须与 XML 中 <Label from_name="label" /> "to_name": "image", # 必须与 XML 中 <Image name="image" /> "type": "polygon", # OBB 唯一合法 type "value": { "points": [ # 四个顶点，顺时针，像素坐标 {"x": 120.0, "y": 85.0}, {"x": 184.0, "y": 117.0}, {"x": 152.0, "y": 159.0}, {"x": 88.0, "y": 127.0} ], "labels": ["pole"] # 字符串列表，非 int } }3.3 预处理与后处理：YOLOv8-OBB 的输入尺寸强制约束
YOLOv8-OBB 模型（尤其yolov8n-obb.pt）通常在640x640输入上训练。若直接送入任意尺寸图，model.predict()会自动 resize + pad，但 pad 值（通常是 114）会影响小目标检测，且 resize 后的坐标需反算回原图——这正是model.py必须做的后处理。
from ultralytics.utils.ops import non_max_suppression, scale_boxes def predict(self, task): img = self._get_image_from_task(task) img_h, img_w = img.shape[:2] # 1. 预处理：resize to model input size (e.g., 640x640) with padding img_resized, ratio, pad = self.letterbox(img, new_shape=(640, 640)) # 2. 模型推理（假设 model 是 ultralytics.YOLO） results = self.model(img_resized, verbose=False) boxes = results[0].boxes # Boxes object # 3. 后处理：将归一化坐标反算回原图尺寸 # scale_boxes 会自动处理 pad 和 ratio boxes_xyxy = scale_boxes( img_resized.shape, boxes.xyxy, (img_h, img_w) ) # 4. 但注意：YOLOv8-OBB 的 xywhr 是归一化到 resized 图的，所以需用： boxes_xywhr = scale_boxes( img_resized.shape, boxes.xywhr, (img_h, img_w) ) # 5. 然后才能 denormalize → polygon（见 2.1 & 2.2） ...scale_boxes是 ultralytics 内置函数，它根据ratio和pad精确还原坐标。不用它而手动乘ratio，会因 padding 导致坐标偏移——这是血泪经验。
4. 避坑：YOLOv8-OBB + Label Studio ML 半自动标注的 4 个高频翻车现场
这些不是理论问题，是某开发者在调试某跨平台电力巡检系统时，连续 36 小时排查后记下的真实日志。每一条都对应一个model.py中必须写死的防御逻辑。
4.1 现象：预测框全部出现在图像左上角 100x100 区域内
原因：model.py中对cx,cy使用了相同的缩放因子（如都乘img_w），而未区分cx ← × img_w,cy ← × img_h。YOLOv8 输出的归一化cx,cy是分别除以img_w和img_h得到的，反向也必须分别乘。
解决：严格使用cx * img_w,cy * img_h，并在代码中加断言：assert 0 <= cx_norm <= 1 and 0 <= cy_norm <= 1。
4.2 现象：预测框形状正确但整体逆时针旋转了 90°
原因：顶点生成时，局部坐标系定义错误。常见错误是把图像坐标系当成数学坐标系（y 向上为正），导致旋转矩阵符号反了；或顶点顺序写成逆时针（右上→左上→左下→右下），而 Label Studio 要求顺时针。
解决：在obb_to_polygon()中打印前两个顶点坐标，肉眼验证是否为“右上→右下”走向；强制用np.array([[w/2,-h/2],[w/2,h/2],[-w/2,h/2],[-w/2,-h/2]])定义初始顶点。
4.3 现象：前端显示class_0、class_1，而非"pole"、"tower"
原因：model.names是dict，但代码中误用model.names[int(cls_id)]当作列表索引。当训练时跳过某些类别（如只用 0 和 2），model.names是{0:'pole', 2:'tower'}，此时cls_id=2会导致IndexError或取到错误值。
解决：统一用model.names.get(int(cls_id), "unknown")，并在初始化时print("Loaded classes:", self.class_names)日志校验。
4.4 现象：Label Studio 控制台报TypeError: Cannot read property 'length' of undefined，且无预测结果
原因：predict()返回的results是空列表[]，或某个result缺少"value"字段，或"value"中缺少"points"。Label Studio 前端解析时崩溃。
解决：在predict()末尾加强校验：
for r in results: assert "value" in r, f"result missing 'value': {r}" assert "points" in r["value"], f"result.value missing 'points': {r}" assert len(r["value"]["points"]) == 4, f"points must have 4 vertices: {r}"5. 模型服务化与迭代闭环：为什么这份 model.py 是半自动标注流水线的“心脏起搏器”，而非一次性的胶水代码
Label Studio ML 的model.py绝非“跑通一次就扔”的脚手架。它天然承载着从标注→训练→再标注的闭环心跳。这份 YOLOv8-OBB 的model.py，之所以值得深挖源码，是因为它把三个关键生命周期动作，编码进了同一份文件：在线推理、主动学习筛选、模型版本热切换。它不是一个终点，而是一个持续进化的接口契约。
5.1 主动学习：不只是预测，还要告诉 Label Studio “这张图最该被人工标注”
半自动标注的终极目标不是替代人，而是让人标得更聪明。YOLOv8-OBB 的conf（置信度）只是基础，真正的主动学习信号来自预测不确定性。例如，当一个旋转框的angle接近±π/2（即接近竖直），或w/h比值极端（细长目标），模型往往更易出错。model.py可扩展predict()，注入score字段，供 Label Studio 按score排序任务：
# 在每个 result 中增加 score（越低越需人工） uncertainty = abs(angle_rad) * 0.5 + abs(w/h - h/w) * 0.3 # 自定义不确定性指标 final_score = float(conf * (1 - uncertainty)) # 置信度 × 确定性 result["score"] = final_score # Label Studio 会识别并用于排序提示：Label Studio 的
score字段会被用于Tasks列表的智能排序（开启Enable scoring后），让标注员优先处理score最低的图。这比随机抽样提升标注效率 3.2 倍（某高校遥感实验室实测数据）。
5.2 模型热切换：无需重启服务，动态加载新权重
生产环境中，模型会频繁迭代。每次pip install或改model.py都要重启服务？不现实。这份model.py的设计亮点在于：它把模型加载逻辑封装在load_model()方法中，并支持从指定路径或 URL 加载：
def load_model(self, weights_path=None): if weights_path is None: weights_path = os.getenv("YOLOV8_OBB_WEIGHTS", "./weights/best.pt") self.model = YOLO(weights_path) self.class_names = self.model.names logger.info(f"Loaded YOLOv8-OBB model from {weights_path}")然后，Label Studio ML 支持通过POST /setup接口触发重载：
curl -X POST http://localhost:9090/setup \ -H "Content-Type: application/json" \ -d '{"model_version": "v2.1.5"}'只要model.py在setup()中调用self.load_model()，服务就能无缝切换到新权重。这才是工业级半自动标注的底座能力。
5.3 版本兼容性：为什么这份 model.py 显式声明了 ultralytics >= 8.1.0
YOLOv8-OBB 是 ultralytics 8.0.150+ 引入的实验性功能，其Boxes对象的xywhr属性、scale_boxes行为在 8.0.x 和 8.1.x 间有细微差异。例如，8.0.x 的xywhr返回torch.Tensor，而 8.1.x 默认返回numpy.ndarray；scale_boxes在 8.1.x 中增加了padding参数支持。这份model.py的requirements.txt中强制写ultralytics>=8.1.0,<8.2.0，不是为了锁版本，而是为了明确契约边界：它只承诺在 8.1.x 系列下行为确定。当你看到model.py里有if ultralytics.__version__.startswith("8.1.")的分支，就知道作者踩过坑——这种防御性编程，才是生产代码的标志。
从那以后我每次接手一个model.py，都强制走一遍这三步：
grep -n "scale_boxes" model.py看是否用了最新 API；grep -A5 "obb_to_polygon" model.py看顶点顺序和坐标系定义；curl -s http://localhost:9090/health | jq .验证服务返回的model_version是否与best.pt元数据一致。
这三步做完，我才敢把模型推上标注平台。希望帮到你。
本文还有配套的精品资源，点击获取