Label Studio Labels 标签完全指南为文本与音频区域配置标注标签集【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio导读Labels是 Label Studio 中用于「区域标注」region labeling的核心控制标签它为文本、音频等任务提供一组可被选中并赋予到已识别区域上的标签集合是构建命名实体识别NER、音频区域分类、文本分类等标注界面的基础构件。阅读本文后你将掌握Labels的完整配置参数、子标签Label的使用方式、基于任务数据动态加载标签的机制以及标签选择与使用次数限制等底层实现原理可直接上手搭建生产可用的区域标注配置。本文以 docs/source/tags/labels.md 与 docs/source/includes/tags/labels.md 为骨架结合前端编辑器源码web/libs/editor/src/tags/control/进行纵深解读。Labels 标签是什么在 Label Studio 中标注配置labeling config由 XML 形式的标签树组成。Labels标签的作用是提供一组标签label set用于给任务中被识别出的区域region打上标记并指定要赋给这些区域的标签值。它适用于机器学习和数据科学项目中的区域标注任务典型场景包括给一段文本中的实体打标如品牌、产品、给音频片段做分类标注等。从源码角度前端编辑器在 Labels/Labels.jsx 中注册了labels标签类型Registry.addTag(labels, LabelsModel, HtxLabels)见该文件第 155 行其模型由ControlBase、AnnotationMixin、DynamicChildrenMixin、LabelMixin与SelectedModelMixin组合而成子元素类型被约束为label / header / view / text / hypertext / richtext第 97 行默认子元素类型为labeldefaultChildType。与类型专属 Labels 标签的关系原文档明确说明Labels标签可用于音频audio和文本text数据类型其他数据类型拥有类型专属的 Labels 变体。这一点在 Label.jsx 的parentTypes定义中得到印证第 75–92 行——单个Label子标签可以挂载到以下所有父标签下父标签类型适用数据/区域类型Labels文本、音频RectangleLabels图像矩形框EllipseLabels图像椭圆PolygonLabels图像多边形KeyPointLabels图像关键点BrushLabels图像画笔/分割HyperTextLabels超文本TimelineLabels时间线TimeSeriesLabels时间序列ParagraphLabels段落BitmaskLabels位掩码VectorLabels向量VideoVectorLabels视频向量因此本指南的核心内容标签集、动态加载、参数语义对上述所有变体同样适用只是可视化区域类型不同。基础用法给一段文本打标签原文档给出了最基础的配置示例——对一段文本应用一组标签View Labels nametype toNametxt-1 Label aliasB valueBrand / Label aliasP valueProduct / /Labels Text nametxt-1 value$text / /View要点拆解Labels的name是该控制标签的唯一标识如typetoName指向要被标注的数据对象标签此处为txt-1即Text标签Label子标签声明具体标签value是标签的显示文本与导出值alias是显示在界面上的别名/缩写如用B代表 Brand该配置在仓库中的真实范例可参考 examples/named_entity/config.xml——一份包含 Person、Organization、Location 等 11 个标签的经典 NER 配置。在 Label Studio 中Labels通常与Text或Audio数据标签配合用户在文本/音频上框选或圈选出一个区域后再从标签集中点选一个标签赋给该区域。Labels 参数详解原文档 includes/tags/labels.md 提供了完整的参数表下文逐一结合源码展开说明。参数总表参数类型默认值说明namestring无元素名称必填同一配置内唯一toNamestring无要标注的目标元素名称必填choicesingle|multiplesingle一个区域允许选择单个还是多个标签maxUsagesnumber无每个标签在单任务中最多可被使用的次数showInlinebooleantrue是否在同一视觉行内展示标签opacityfloat0.6高亮矩形的透明度fillColorstring无矩形填充色的十六进制值strokeColorstring#f48a42描边颜色的十六进制值strokeWidthnumber1描边宽度valuestring无任务数据中存放动态加载标签列表的字段名关键参数与源码实现name/toNamename是控制元素的名字toName绑定被标注的数据对象。在 Labels.jsx 的TagAttrs模型中toname被定义为可空的字符串第 69 行。choice决定一个区域内可分配标签的数量。默认single单选可选multiple多选。源码中以枚举类型定义第 71 行choice: types.optional(types.enumeration([single, multiple]), single),在 Label.jsx 的toggleSelected动作中第 218–240 行Labels模型通过shouldBeUnselected即choice single分支处理单选/多选逻辑多选模式下每个标签独立切换选中状态单选模式下选中新标签前会先unselectAll()取消所有其他标签。multiple场景适用于一个区域同时归属多个类别如一段文本既是品牌又是产品。maxUsages限制每个标签在单个任务中的总使用次数上限。该参数同时存在于Labels与Label上Label.jsx 中实现了子级优先、父级兜底的取值逻辑第 101–103 行get maxUsages() { return Number(self.maxusages || self.parent?.maxusages); },即Label自身的maxUsages优先未设置时回退到父Labels的值。实际计数与校验由usedAlready()遍历当前标注的所有区域统计hasLabel(self.value)的命中次数与canBeUsed(count)判断used count maxUsages完成第 105–116 行当超出限制时界面会弹出提示You cant use ${self.value} more than ${self.maxUsages} time(s)第 161 行。showInline是否让标签在同一视觉行内平铺展示默认true。源码中HtxLabels组件根据item.showinline给容器添加inline样式类Labels.jsx 第 147–153 行。opacity/fillColor/strokeColor/strokeWidth控制区域高亮矩形的视觉样式。opacity是矩形高亮的不透明度fillColor是填充色strokeColor是描边色strokeWidth是描边宽度。在 Labels.jsx 第 78–82 行可以看到这些参数的底层定义opacity: types.optional(customTypes.range(), 0.2), fillcolor: types.optional(customTypes.color, #f48a42), strokewidth: types.optional(types.string, 1), strokecolor: types.optional(customTypes.color, #f48a42),需要注意文档表中opacity的默认值写为0.6而当前仓库源码中该字段默认定义为0.2、fillColor在源码中实际有#f48a42的默认色文档与源码存在版本差异实际行为请以你所使用的 Label Studio 版本为准。value动态加载标签的开关详见下文「动态标签」一节。子标签 Label单个标签的完整参数Labels内部的每个Label子标签本身也有丰富参数原文档未展开这里从 Label.jsx 第 51–67 行的TagAttrs模型补充完整参数表参数类型默认值说明valuestring无标签的值必填selectedbooleanfalse是否预选此标签maxUsagesnumber无该标签在单任务中的最大使用次数覆盖父级设置hintstring无悬停时显示的提示文本hotkeystring无标签快捷键未指定时自动生成aliasstring无标签别名showAliasbooleanfalse是否在标签文本内显示别名aliasStylestringopacity:0.6别名的 CSS 样式sizestringmedium标签内文字大小backgroundstring#36B37E激活标签的背景色十六进制selectedColorstring#ffffff激活标签的文字颜色十六进制granularitysymbol|word无文本标注的粒度按字符或按词仅 Text 有效htmlstring无用 HTML 代码替代value渲染标签按钮需正确转义categoryint无导出排序类别YOLO/COCO 等格式在 label-studio-converter 中用于标签排序几个值得注意的实现细节别名渲染当showAlias true且有alias时组件会在标签文本后追加带样式的别名Label.jsx 第 324–326 行别名默认样式为opacity: 0.6可通过aliasStyle覆盖。HTML 渲染html参数通过sanitizeHtml消毒后注入第 319–323 行用于展示富文本样式的标签按钮直接使用value时则纯文本展示。背景色自动生成若未显式指定backgroundafterCreate会用ColorScheme.make_color({ seed: value })根据标签值稳定生成颜色第 287–293 行保证同一标签跨任务颜色一致。热键交互开启热键后Label通过onHotKey()触发与点击相同的toggleSelected()交互第 274–285 行。动态标签从任务数据加载标签集Labels的一个强大特性是动态值所有类型的 Labels 都可以通过value参数从任务task数据中加载标签列表。任务数据中应包含一组选项options用于在渲染时创建底层的Label且选项中的所有参数都会原样传递给对应的Label标签。官方示例对比原文档给出了动态加载写法与其等价展开写法动态加载写法Labels nameproduct toNameshelf value$brands / !-- { data: { brands: [ { value: Big brand }, { value: Another brand, background: orange }, { value: Local brand }, { value: Green brand, alias: Eco, showalias: true } ] } } --等价展开写法Labels nameproduct toNameshelf Label valueBig brand / Label valueAnother brand backgroundorange / Label valueLocal brand / Label valueGreen brand aliasEco showAliastrue / /Labels两种写法渲染出的标签集合完全相同。动态方式的收益在于标签集不必写死在标注配置中而是随每条任务数据变化非常适合数据中包含候选实体、候选类别等动态集合的场景。底层实现原理动态子元素的创建由DynamicChildrenMixin完成见 DynamicChildrenMixin.jsupdateValue/updateDynamicChildren第 60–89 行通过parseValue(self.value, store.task?.dataObj)从任务数据对象中解析value字段指向的数组updateWithDynamicChildren第 50–58 行遍历数组为每个选项创建defaultChildType对Labels而言即label子元素并把选项的全部字段value、background、alias等合并进子元素节点第 23–38 行每个动态子元素会生成一个稳定 IDobj.id ?? guidGenerator()并递归处理obj.children支持嵌套结构第 37 行创建完成后还会刷新热键绑定setupHotKeys并触发界面更新第 84–87 行。这从源码层面验证了原文档的表述选项中的参数会被完整转移给对应子标签——因此动态数据里可以携带background、alias、showAlias等任意Label参数。实战示例完整可运行的标注配置示例一文本 NER命名实体识别参考仓库内 examples/named_entity/config.xmlView Labels namener toNametext Label valuePerson/Label Label valueOrganization/Label Label valueFact/Label Label valueMoney/Label Label valueDate/Label Label valueTime/Label Label valueOrdinal/Label Label valuePercent/Label Label valueProduct/Label Label valueLanguage/Label Label valueLocation/Label /Labels Text nametext value$text/Text /View在 Label Studio 中导入该配置并上传文本数据后标注员可选中文字片段并为其指定上述任意标签。示例二音频区域分类 动态标签View Labels nameaudio_class toNameaudio value$classes / Audio nameaudio value$audio / /View对应的任务数据中classes字段需为数组例如[{value: speech}, {value: music, background: #ff0000}]渲染效果等同于手写多个Label。该用法适合标注配置复用、标签集随数据动态变化的音频项目。示例三多选标签 使用次数限制View Labels nametags toNametext choicemultiple maxUsages5 Label valueA / Label valueB / Label valueC / /Labels Text nametext value$text / /View每个区域最多同时分配多个标签且任一标签在单个任务中的总使用次数不超过 5 次Label可单独覆盖该值。边界条件与注意事项Labels的适用数据类型文档明确仅限音频与文本图像、视频等类型请使用RectangleLabels、PolygonLabels、VideoRectangle等类型专属标签。value引用字段必须存在动态标签模式下若任务数据中value指向的字段缺失或为空源码中parseValue会返回空值并直接returnDynamicChildrenMixin.js 第 76–79 行不会报错但也不会生成标签请确保数据字段与配置一致。动态参数全量透传动态选项中的任意字段都会成为Label属性务必使用Label支持的合法参数名避免拼写错误导致属性被忽略。默认值以版本为准如前文所述opacity、fillColor的默认值在文档与当前仓库源码中存在差异生产环境应以实际安装版本的源码web/libs/editor/src/tags/control/Labels/Labels.jsx为准。maxUsages的覆盖关系Label级设置优先于Labels级设置未设置时继承父级。配置校验Labels必须正确设置name与toName仓库测试数据 data_for_test_label_config_matrix.yml 中覆盖了大量Labels配置变体含缺省toName、缺省子标签等边界情况可在开发自定义配置时参考其校验行为。总结Labels标签是 Label Studio 区域标注体系的基础控制组件通过Label子标签声明标签集、通过choice控制单选/多选、通过maxUsages限制使用次数、通过value实现任务数据驱动的动态标签加载。配合 Label.jsx 与 Labels/Labels.jsx 的源码实现可以精确预判每个参数在界面与数据层面的行为从而快速搭建文本 NER、音频分类等生产级标注界面。【免费下载链接】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），仅供参考