Label Studio 标注 ID 机制全解析region 与 result 的共享 ID、字符集约束与预测追踪原理【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio本指南围绕 Label Studio 的 annotation_ids 文档 展开系统讲解每次标注产生的 region 与 result 概念、二者 ID 的生成规则与共享机制以及从模型预测转写为人工标注时 ID 保持不变的设计用意。阅读本文后你将理解标注 JSON 中id字段的语义边界掌握利用共享 ID 关联多标签结果、跟踪 ML 模型预测区域的方法并能结合 result_format 文档 与 task_format 文档 读懂任意一条标注记录。Label Studio 的每一次标注行为最终都会沉淀为结构化的 JSON。无论你是在界面上框一个矩形、圈一段音频还是给整张图做一个分类前端编辑器都会把操作拆解为区域region和结果result两部分并用一套统一的 ID 规则把它们组织起来。本文基于仓库中的 annotation_ids.md 文档结合前端编辑器与后端校验源码从概念、ID 规则、共享机制到预测追踪完整拆解这套标注数据模型。核心概念Region 与 Result 的职责划分原文档开篇即给出一个关键区分每次标注都同时包含 region 与 result 两个层面的信息。Regions区域指被选中的数据范围可以是文本片段text span、图像区域image area、音频片段audio segment或其他实体。它是标注画在了哪里。Results结果指赋给该区域的标签。它是这个区域被标注成了什么。以图像目标检测为例你在图片上画一个矩形框这个矩形框的坐标范围就是 region你给这个框选的类别标签如 Moonwalker就是 result。二者通过相同的 ID绑定在一起。result_format 文档 对此做了更精确的阐述每个标注的 result 是一个列表list其中每一项就是一个 region统一存放在annotation.result字段下{result: [{id: 123, ...}, {id: 456, ...}], ...}region 可以代表任意标注动作——画出的边界框、创建的 Relation、赋的类别等。而value字段承载标注动作的具体产物其结构随标签配置变化例如矩形框的x/y/width/height坐标、标签的labels数组等。每条 annotation 中 region ID 的生成与字符集约束原文档明确了一个易于被忽略的细节region 的 ID 是针对每条 annotation而言的。即同一个任务task如果有多条 annotation不同 annotation 之间的 region ID 可以重复没有全局唯一性要求ID 的唯一性范围限定在单条 annotation 内部用于把该 annotation 下的各 region 区分开。每个 region ID 是字符串string由字符集A-Za-z0-9_-组成也就是大小写字母、数字、下划线和连字符。该字符集与 URL-safe 的 Base64 编码字符高度重合保证了 ID 可以安全出现在 JSON 字段、URL 参数等传输场景中。从实现层面看前端编辑器正是使用nanoid库生成这种短 ID。以 web/libs/editor/src/utils/unique.ts 为例// todo for nanoid3 there should be default import import { nanoid } from nanoid; /** * Unique hash generator * param {number} lgth */ export const guidGenerator (length 10) nanoid(length);nanoid的默认字符集包含A-Za-z0-9_-与文档描述的字符集完全一致默认生成长度为 10 的 ID如Dx_aB91ISN、t5sp3TyXPo。数据管理模块 web/libs/datamanager/src/utils/random.js 也有同构实现允许传入长度参数import { nanoid } from nanoid; /** * Unique hash generator * param {number} lgth */ export function guidGenerator(lgth) { let uniqueID nanoid(10); if (lgth) { uniqueID nanoid(lgth); } return uniqueID; }值得说明的是nanoid默认还包含~字符Label Studio 对 ID 字符集的描述A-Za-z0-9_-可理解为对外契约层面的约束只要符合该字符集的字符串Label Studio 都能正确解析与回显实际生成时则采用 nanoid 短 ID。共享 ID 机制result 与 region 的绑定原理原文档指出每个 result 的 ID 与其所作用的 region ID 相同。这意味着同一 region 上挂载的多个 result 共享同一个id这个 ID 就是它们与 region 之间的外键。为什么需要共享 IDresult_format 文档 给出了格式推导原则概括如下配置中至少要有 1 个 object tag如Image、Text它定义数据类型至少 1 个 control tag如RectangleLabels、Labels要挂在该 object tag 上才能在对应数据上创建 region每个 control tag 为 region 产生 1 条 result同一 region 的多条 result 共享同一个 id分类classification在技术上会创建一个特殊的空分类 region。以条件标注per-region配置为例同一 region 上可以同时挂一个必选的矩形框标注和一个可选的文本备注Image nameimage value$image/ RectangleLabels nameproduct toNameimage Label valueSome label / ... /RectangleLabels TextArea namename toNameimage perRegiontrue /对应生成的 result 列表里两条 result 的id均为X_12fGk[{ id: X_12fGk, from_name: product, to_name: image, type: rectanglelabels, // ... value: { labels: [Some label], // ... } }, { id: X_12fGk, from_name: name, to_name: image, type: textarea, // ... value: { text: [Roasted beans], // ... } }]这种共享 ID 设计带来的直接收益按 ID 聚合处理导出数据时按id分组即可把同一 region 的所有 result坐标、标签、备注、价格等拼装回一个完整对象无需额外维护关联关系支撑 RelationRelation控件通过from_id/to_id引用 region ID 来建立两个区域之间的关系详见下文支撑层次结构result.parentID引用父 region 的result.id在 Region 面板中组织出树形层级见 task_format 文档 的 JSON 属性表。后端在任务导入校验时也依赖这一结构。在 label_studio/tasks/validation.py 中TaskValidator.validate会校验每条 annotation 必须包含result字段且必须是 list保证导入数据的结构契约不被破坏。多 result 组合的实际形态per-region、可选标签与多标签原文档描述了同一 region 多个 result的模型result_format 文档进一步给出了三种典型组合理解它们有助于阅读任何导出的标注 JSON。可选标签optional labels绘制控件如Rectangle与标签控件如Labels搭配时矩形坐标 result 与标签 result 共享 IDImage nameimage value$image/ Rectangle nameproduct toNameimage / Labels namekind toNameimage Label valueTea / Label valueCoffee / /Labels[{ id: X_12fGk, from_name: product, to_name: image, type: rectangle, // ... value: { x: 100, y: 200 /* ... */ } }, { id: X_12fGk, from_name: kind, to_name: image, type: labels, // ... value: { labels: [Tea] /* ... */ } }]多标签multi-labels同一 region 可同时挂多个标签维度如类别、产地与一个必填数值result 数量随之扩展Image nameimage value$image/ Rectangle nameproduct toNameimage / Labels namekind toNameimage Label valueTea / Label valueCoffee / /Labels Labels namecountry toNameimage Label valueSri-Lanka / Label valueBrazil / /Labels Number nameprice toNameimage perRegiontrue requiredtrue /[{ id: X_12fGk, from_name: product, type: rectangle, /* 坐标 */ }, { id: X_12fGk, from_name: kind, type: labels, value: { labels: [Coffee] } }, { id: X_12fGk, from_name: country, type: labels, value: { labels: [Brazil] } }, { id: X_12fGk, from_name: price, type: labels, value: { number: 12.5 } }]perRegiontrue属性正是该控件为每个 region 单独产生一条 result的开关。项目配置侧同样识别这一属性label_studio/projects/serializers.py 会读取perRegion/perItem属性用于判断配置是否支持某些高级导出特性。区域关系relationsRelation 是共享 ID 机制的另一个重要应用两个区域之间的关系本身也是一条特殊 result通过from_id/to_id引用两个 region 的 ID 建立有向连接。以目标检测配置为例Image nameimage value$image/ RectangleLabels namekind toNameimage Label valueCar / Label valueAirplaine / /RectangleLabels[{ id: oid67, type: rectanglelabels // ... }, { id: RQbW3Sj_Zr, type: rectanglelabels // ... }, { type: relation, to_id: RQbW3Sj_Zr, from_id: oid66, direction: right }]注意这里 relation 这条 result 自身没有id而是通过from_id起点区域 ID与to_id终点区域 ID把两个 region 关联起来direction描述关系方向。这正是同一 ID 用于将不同实体关联在一起的典型用法——例如用Relation关联两个框或用perRegion属性做条件标注。预测转标注ID 保持不变实现区域级追踪原文档最后指出一个对 ML 工作流至关重要的特性当一条预测prediction被用于创建标注annotation时result 的 ID 在 annotation 字段中保持不变。这使得你可以追踪模型生成的区域预测结果中的每条 result 进入人工标注后仍保留原 ID可以明确区分这条区域来自模型预标注而非人工新画对比人工与模型将人类创建的标注与模型预测直接按 ID 对齐比较评估模型建议的采纳率、人工修正程度。从完整数据流看task_format 文档 的示例 JSON任务对象中的predictions数组与annotations数组使用完全相同的 result 格式predictions额外携带model_version与score字段{ id: 1, data: { image: https://example.com/opensource/label-studio/1.jpg }, annotations: [ { id: 1001, result: [ { from_name: tag, id: Dx_aB91ISN, source: $image, to_name: img, type: rectanglelabels, value: { height: 10.458911419423693, rectanglelabels: [Moonwalker], rotation: 0, width: 12.4, x: 50.8, y: 5.869797225186766 } } ], was_cancelled: false, ground_truth: false, created_at: 2021-03-09T22:16:08.728353Z, updated_at: 2021-03-09T22:16:08.728378Z, lead_time: 4.288, result_count: 0, task: 1, completed_by: 10 } ], predictions: [ { created_ago: 3 hours, model_version: model 1, result: [ { from_name: tag, id: t5sp3TyXPo, source: $image, to_name: img, type: rectanglelabels, value: { height: 11.612284069097889, rectanglelabels: [Moonwalker], rotation: 0, width: 39.6, x: 13.2, y: 34.702495201535505 } } ] } ] }前后端共用同一套 result 结构ID 即可在 prediction → annotation 的转换中保持不变无需重新生成从而保证追踪链条完整。结合 tasks 模块的校验逻辑 可以看到predictions数组同样被要求包含result字段且为 list与 annotation 的结构约束完全一致。ID 之外读懂一条完整标注记录为完整理解 ID 的上下文这里给出 task_format 文档 中与 ID 直接相关的核心 JSON 属性说明JSON 属性说明id标注任务的标识符annotations该任务的标注结果数组annotations.id完成标注记录的标识符result.id单条标注 result 的标识符用于将不同 control tag如Labels与Rectangle产生的 region 组合在一起result.parentID可选父 region 的result.id引用在 Region 面板中组织区域树形层级result.from_name用于标注该 region 的 control tag 名称result.to_name提供该 region 的 object tag 名称result.type标注所用 tag 的类型result.value标签特有的标注结果值结构取决于对应 tagpredictions机器学习预测数组格式与 annotations 相同额外含score等参数predictions.score预测结果的总体分数概率输出、置信度等其中result.id的组合不同 control tag 的 region这一作用正是本文共享 ID 机制在导出数据结构上的直接体现result.parentID则是在共享 ID 基础上建立的父子层级引用。此外导入标注时可通过completed_by字段控制标注人归属支持三种写法不指定默认使用导入用户、按邮箱指定{email: annotatorexample.com}、按用户 ID 指定数字系统会匹配组织中已有用户未匹配时按配置回退到导入用户。该能力适用于 UI、API 与 SDK 三种导入途径。小结与进阶阅读Label Studio 的标注数据模型可以浓缩为三句话每次标注 若干 region画在哪 若干 result标成什么二者通过共享 ID绑定region ID 限定在单条 annotation 内唯一字符集为A-Za-z0-9_-前端通过 nanoid 生成短 IDprediction → annotation 转换时result ID 保持不变是模型区域追踪与人工对比的基础。想进一步深入建议按以下路径阅读仓库内文档理解同一 region 多 result 的完整推导原则与更多组合示例见 result_format 文档掌握完整任务 JSON 结构annotations / predictions / drafts / reviews与导入时的completed_by写法见 task_format 文档查询各类 control tag / object tag 的value结构与属性如perRegion见 标签参考文档阅读任务导入校验源码 label_studio/tasks/validation.py 与配置解析逻辑 label_studio/projects/serializers.py验证 annotation / prediction 的结构契约。掌握这套 ID 规则后无论你是解析导出数据、对接 ML 预测结果还是二次开发数据流水线都能准确读写每一条标注记录。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
