Label Studio HyperText 标签完全指南HTML 超文本数据标注配置与结果格式解析【免费下载链接】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 的HyperText对象标签展开系统讲解如何在命名实体识别NER与自然语言处理NLP项目中配置 HTML 编码文本与网页的标注界面涵盖valueType、inline、encoding、granularity、resolveUrls等全部参数语义、与HyperTextLabels控制标签的组合用法以及基于 XPath 的区域标注结果 JSON 格式。读完本文你将能够独立编写可运行的 HyperText 标注配置理解其结果数据的底层序列化原理并掌握将云端存储 URI 直接解析为可标注页面的高级用法。一、HyperText 标签是什么HyperText是 Label Studio 前端编辑器web/libs/editor中的一个对象Object标签用于在标注界面中渲染 HTML 格式的超文本内容供标注人员对 HTML 编码的文本与网页进行区域级标注。官方文档对其定位如下TheHyperTexttag displays hypertext markup for labeling. Use for labeling HTML-encoded text and webpages for NER and NLP projects.它面向的数据类型为HTML。与之配合的通常是Labels或HyperTextLabels这类控制Control标签后者正是为了标注超文本这一场景设计的在 hypertextlabels.md 中HyperTextLabels被描述为creates labeled hyper text (HTML)用于配合 HyperText 对象标签完成 HTML 文本或元素的命名实体识别任务。从源码结构看HyperText与Text标签共享同一个底层模型RichTextModel。RichText/index.js 中的注册逻辑显示两者只是以isText标志区分的同一套富文本实现Registry.addTag(text, RichTextModel, HtxRichText({ isText: true })); Registry.addTag(hypertext, RichTextModel, HtxRichText({ isText: false }));在 RichText/model.js 中TagAttrs模型集中定义了这两个标签的全部属性valuetype、inline、savetextresult、selectionenabled、clickablelinks、highlightcolor、showlabels、encoding、granularity、resolveurlsHyperText的正式文档声明则维护在 HyperText.js 这个 stub 文件中保证代码注释与用户文档同步。这意味着凡是本文下述关于 HyperText 的参数在代码层面均可在RichTextModel中找到对应字段。二、基本配置示例2.1 结合 Labels 标签标注 HTML 内容官方文档给出的第一个示例是使用HyperText展示绑定到任务数据字段$text的 HTML 内容并用Labels提供三个标签View HyperText nametext-1 value$text / Labels nameparts toNametext-1 Label valueCaption / Label valueArticle / Label valueAuthor / /Labels /View要点说明value$text表示从任务数据中取名为text的字段该字段保存 HTML 字符串toNametext-1将Labels与HyperText建立关联标注时选择的标签会作用于该超文本区域这一配置即可用于标注标题Caption、正文Article、作者Author等网页结构成分。2.2 内嵌 HTML 内容第二个示例演示了不依赖任务数据、直接在配置中内嵌 HTML 的用法View HyperText namep1 pSome explanations emwith style/em/p /HyperText /View此时HyperText标签体内直接书写 HTML 片段p、em等编辑器会将其作为待标注内容渲染适用于快速演示或固定内容标注。2.3 配合 HyperTextLabels 的 NER 配置若需要更细粒度控制同一标签可被选择的次数单选/多选官方推荐使用 HyperTextLabels 标签其示例配置为View HyperTextLabels namelabels toNameht Label valueHeader / Label valueBody Text / /HyperTextLabels HyperText nameht value$html / /ViewHyperTextLabels额外支持choicesingle/multiple默认single、maxUsages单个标签每个任务的最大使用次数与showInline是否同行内联展示标签默认true等控制参数适合标题Header/正文Body Text这类语义角色标注。三、完整参数详解官方文档通过{% insertmd %}引入了 includes/tags/hypertext.md 中的参数表以下逐项展开说明并结合源码给出实际取值与默认行为ParamTypeDefaultDescriptionnamestring元素名称供toName引用valuestring元素的值绑定任务数据字段如$textvalueTypeurl|texttext文本是直接存放在上传数据中还是需要从 URL 加载inlinebooleanfalse是否将 HTML 直接嵌入 Label Studio 页面渲染否则使用 iframesaveTextResultyes|no是否把标注文本一并存入结果对valueTypeurl默认不存encodingnone|base64|base64unicode如何解码编码字符串中的值selectionEnabledbooleantrue启用或禁用文本选择clickableLinksbooleanfalse是否允许点击超文本中的链接打开资源highlightColorstring高亮颜色十六进制未设置时使用标签颜色showLabelsboolean是否在区域旁显示标签未设置默认— 使用编辑器设置true/false — 覆盖编辑器设置granularitysymbol|word|sentence|paragraph控制区域选择的粒度resolveUrlsbooleantruevalueTypeurl时是否解析内容中的云存储 URI如s3://、gs://3.1valueType数据来源与安全模式valueType决定value字段的内容是直接作为 HTML 字符串渲染text还是作为 URL 去加载页面/内容url。在 RichText/model.js 中其默认值并非固定为text而是与浏览器安全模式联动valuetype: types.optional( types.enumeration([text, url]), () (window.LS_SECURE_MODE ? url : text), ),即在 SECURE MODE 下默认强制为url此时不允许直接把文本写进任务数据WARNING_MESSAGES中专门有一条dataTypeMistmatch提示Do not put text directly in task data if you use valueTypeurl见 model.js。3.2inline直接渲染还是 iframeinlinefalse默认时HTML 内容被渲染在 iframe 中隔离页面自身的脚本与样式inlinetrue则把 HTML 直接嵌入 Label Studio 页面。源码中对此有一个隐含约束model.jsif (self.type text) self.inline true;——即Text标签强制内联而inline参数只对HyperText有意义对应注释 whether to embed html directly to LS or use iframe (only HyperText)。3.3saveTextResult结果中是否携带文本saveTextResult控制标注结果中是否记录被选中区域的文本内容。官方文档特别强调对于valueTypeurl默认不保存文本。这一行为在afterCreate钩子中自动推导model.jsif (self.savetextresult none) { if (self.valuetype url) self.savetextresult no; else if (self.valuetype text) self.savetextresult yes; }也就是说savetextresult未显式配置时valueTypetext→ 自动保存文本valueTypeurl→ 自动不保存文本用户显式设置yes/no可以覆盖此推导。3.4encoding解码编码字符串当任务数据中的值本身是编码字符串时可设置none不解码直接使用源码中的默认值base64用atob(val)解码model.jsbase64unicode用Utils.Checkers.atobUnicode(val)解码适用于包含 Unicode 字符的 base64 编码内容model.js。3.5granularity区域选择粒度granularity控制用户一次框选的最小语义单元可选symbol字符、word单词、sentence句子、paragraph段落。在模型层被建模为枚举model.js默认symbol即自由选择任意字符范围。设置为word/sentence/paragraph后选区会自动吸附到对应粒度的边界便于按语义单元标注实体。3.6resolveUrls云存储 URI 解析当valueTypeurl且加载的 HTML 内容中引用了云存储资源如s3://、gs://开头的图片、附件地址时resolveUrlstrue默认会把它们解析为可访问的实际 URL在无法直接解析的场景下会替换为/tasks/{id}/resolve/代理地址使资源通过 Label Studio 的鉴权与预签名presigning机制加载model.jsif (self.resolveurls self.type ! text) { content presignUrls(content, store.task?.id); }注意这里同样排除了text类型即resolveUrls是 HyperText 的专属行为与 Label Studio 各存储后端S3、GCS、Azure Blob 等的预签名能力联动。3.7 其他行为参数selectionEnabled默认true置false可禁用选区用于纯展示场景clickableLinks默认false置true后标注人员可直接点击超文本中的链接跳转注意与标注框选操作共存时的交互取舍highlightColor十六进制高亮色缺省时沿用所选标签的配色showLabels三态参数——不设置时跟随编辑器全局设置显式true/false强制显示/隐藏区域旁的标签名。四、标注结果格式基于 XPath 的区域序列化HyperText 标注产生的区域Region结果由HyperTextRegion定义其文档 stub 位于 HyperTextRegion.js官方给出的结果参数如下NameTypeDescriptionvalueObject区域值对象value.startstring区域起始容器的 XPathvalue.endstring区域结束容器的 XPathvalue.startOffsetnumber起始容器内的偏移量value.endOffsetnumber结束容器内的偏移量value.text可选string区域文本内容可省略官方示例 JSON{ value: { start: /div[1]/p[2]/text()[1], end: /div[1]/p[4]/text()[3], startOffset: 2, endOffset: 81, hypertextlabels: [Car] } }该格式与HyperTextLabels的结果参数完全一致见 includes/tags/hypertextlabels.md便于两类标签混用同一套后处理逻辑。4.1 结果如何生成全局偏移与相对偏移的换算从源码看HyperText 区域的序列化并不是简单的字符下标而是**XPath 容器 容器内偏移**的双层定位这一转换由 DOM 管理器完成RichText 模型对外暴露三个换算接口model.jsglobalOffsetsToRelativeOffsets({ start, end })把文档级全局码点偏移转换为{start, startOffset, end, endOffset}相对定位即序列化方向relativeOffsetsToGlobalOffsets(start, startOffset, end, endOffset)反方向还原用于回放标注rangeToGlobalOffset(range)把浏览器选区Range对象转换为全局偏移即用户框选的入口。区域重建时needsUpdate()会调用region.initRangeAndOffsets()、applyHighlight(true)与updateHighlightedText()重新定位并高亮已有区域model.js。这种 XPath 定位方式的优势在于即使 HTML 结构复杂、文本被em、span等标签切碎区域仍能稳定锚定到具体 DOM 文本节点不会因为样式标签的增删而失配。4.2 安全清理结果与渲染的一致性setRemoteValue在载入 HTML 内容时执行关键的安全步骤model.jsif (self.type text) { self._value String(val); } else { self._value sanitizeHtml(String(val)); }即 HyperText 加载的 HTML 会经过sanitizeHtml清理移除 script、iframe 等危险元素替换为占位节点以保持 DOM 节点数量一致而 Text 类型因已在视图层做 HTML 转义不再重复消毒。这保证标注区域所锚定的 DOM 结构与序列化结果是严格对应的。五、实战一个完整的网页成分标注配置综合上述内容给出一个可直接投入使用的完整配置用于对从 URL 加载的网页做标题/正文/作者/链接成分标注View HyperText namepage value$html valueTypeurl granularityword clickableLinkstrue resolveUrlstrue encodingnone / HyperTextLabels nameparts toNamepage choicemultiple maxUsages10 Label valueHeader background#ff0000 / Label valueBody Text background#00ff00 / Label valueAuthor background#0000ff / Label valueLink background#ffa500 / /HyperTextLabels /View配置要点回顾valueTypeurlresolveUrlstrue支持直接标注从远程 URL 加载、且内含s3://、gs://等云存储引用的页面granularityword选区按单词对齐适合实体抽取clickableLinkstrue允许标注人员点击页面中的真实链接核验目标地址HyperTextLabels的choicemultiple允许多标签叠加maxUsages10限制单标签每任务最多使用 10 次由于是valueTypeurl且未显式设置saveTextResult结果默认不包含value.text仅记录 XPath 定位信息——如需回显文本可显式加上saveTextResultyes。对应的标注结果节选示例如下{ value: { start: /html[1]/body[1]/div[1]/p[1]/text()[1], end: /html[1]/body[1]/div[1]/p[3]/text()[2], startOffset: 0, endOffset: 120, text: Some explanations with style..., hypertextlabels: [Body Text] } }六、常见问题与调试线索内容没有渲染检查value绑定的任务数据字段是否存在若使用valueTypeurl而任务数据里直接放了文本会触发源码中的dataTypeMistmatch警告model.js。URL 加载失败会触发loadingError警告并在标注区显示错误信息在 SECURE MODE 下valueType被强制为url请确认任务数据确实存放 URL。标注结果没有text字段这是valueTypeurl的默认行为saveTextResult自动为no按需显式设置saveTextResultyes。区域无法精确选择selectionEnabledfalse会完全禁用选择granularity粒度设置过高如paragraph时最小选区为整个段落按需调整。点击文本却跳转链接clickableLinks默认为false只有在显式开启后链接才可点击。区域位置漂移XPath 定位依赖 DOM 结构稳定性若页面内容包含动态插入的节点建议在标注前固定页面版本并依赖sanitizeHtml的节点替换策略保持结构一致。七、进一步阅读hypertextlabels.md 与 includes/tags/hypertextlabels.mdHyperTextLabels控制标签的完整参数与结果说明HyperText.jsHyperText 标签的源码文档 stub与本文参数表一一对应RichText/model.jsHyperText 与 Text 共用的底层数据模型与加载、解码、消毒、坐标换算实现RichText/index.js标签注册逻辑可见hypertext与text共用RichTextModelHyperTextRegion.js区域结果的类型定义与示例 JSONtext.md同族Text标签文档用于纯文本标注场景的对比参考。【免费下载链接】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），仅供参考