Label Studio Pairwise 标签实战指南：配置对象对比与选择标注任务
【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio
Pairwise 是 Label Studio 中用于对象两两对比并让标注人员二选一的控制标签，适用于文本摘要质量对比、图像相似性比较、搜索结果排序等需要"AB 选择"的场景。本文以官方标签文档为主线，结合仓库中 Pairwise 控件源码、官方示例 与 Pairwise 分类模板，完整讲解其参数体系、标注配置写法、结果数据格式与底层交互逻辑，读完后你可以直接在 Label Studio 中搭建一个可运行的 Pairwise 对比标注项目。
什么是 Pairwise 标签
Pairwise标签用于让标注人员对比两个不同的对象，并从这两个对象中选出一个。它天然适用于偏好排序类任务：比如同时展示两段文本摘要，让标注员选出"更准确的一段"；或同时展示两张图片，让标注员选出"更符合条件的一张"。
在 Label Studio 的标签体系中，它属于控制（Control）类标签，与Choices、Rating等标签平级。官方文档特别指出一个易混淆点：如果目标是让标注人员判断两个对象是否相似（即"相似 / 不相似"这种二元判断），应当使用Choices标签，而不是Pairwise——Pairwise 只负责"二选一"式的对象选择。
从源码看，Pairwise 的控件模型在 web/libs/editor/src/tags/control/Pairwise.js 中定义，其核心状态是：
selected: types.maybeNull(types.enumeration(["left", "right", "none"]))即标注结果只有三种可能：选中左侧对象（left）、选中右侧对象（right）、未选择（none）。
支持的标签与数据类型
官方文档明确，Pairwise 可配合以下数据类型使用：
| 数据类型 | 说明 |
|---|---|
| audio | 音频（配合Audio标签） |
| image | 图片（配合Image标签） |
| HTML | 网页快照（配合HyperText标签） |
| paragraphs | 对话/段落（配合Paragraphs标签） |
| text | 文本（配合Text标签） |
| time series | 时间序列（配合TimeSeries标签） |
| video | 视频（配合Video标签） |
只要toName指向的对象类型属于上述范围，Pairwise 都能在其上叠加"点击选中"的交互。
基本用法：文本对比标注配置
官方文档给出的第一个示例是"比较两段文本，选出更准确的摘要"：
<View> <Header value="Select the more accurate summary"/> <Pairwise name="pairwise" leftClass="text1" rightClass="text2" toName="txt-1,txt-2"></Pairwise> <Text name="txt-1" value="Text 1" /> <Text name="txt-2" value="Text 2" /> </View>拆解这个配置：
<Header>：向标注人员展示任务指令（"选出更准确的摘要"），确保标注意图明确；<Pairwise name="pairwise" ... toName="txt-1,txt-2">：声明一个名为pairwise的对比控件，通过toName指明要对比的对象；- 两个
<Text>对象分别以txt-1、txt-2命名，其展示内容由value决定。若任务数据来自标注任务的 JSON，则可写成value="$text1"、value="$text2"这种数据引用形式（见下文模板一节）。
标注时，标注人员点击左侧或右侧对象即可选中，再次点击同一侧可取消选中。选中后，被选中的对象会呈现高亮边框样式。
关键约束：toName 必须恰好指向两个对象
Pairwise 的toName必须传入两个、且互不相同的对象名，用逗号分隔。源码在控件创建时做了强校验（Pairwise.js）：
if (self.names.length !== 2 || self.names[0] === self.names[1]) { InfoModal.error("Incorrect toName parameter on Pairwise, must be two names separated by a comma: name1,name2"); }若toName只写了一个对象、写多了，或两个名称相同，Label Studio 会在配置校验阶段直接弹出错误提示。此外，源码中names视图通过self.toname.split(",")解析名称（Pairwise.js），left取第一个对象引用、right取第二个对象引用（Pairwise.js），这也印证了顺序即左右位置的规则。
参数详解
Pairwise 的完整参数见 docs/source/includes/tags/pairwise.md，结合源码声明（Pairwise.js）整理如下：
| 参数 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
name | string | 是 | — | 控件元素名称，标注结果中from_name会使用该值 |
toName | string | 是 | — | 要对比的元素的名称，多个名称用英文逗号分隔，必须恰好两个且互不相同 |
selectionStyle | string | 否 | — | 选中状态的样式，以 CSS 样式字符串传入（如"border: 2px solid #00ff00"），传入后采用内联样式渲染 |
leftClass | string | 否 | left | 左侧对象的 CSS 类名 |
rightClass | string | 否 | right | 右侧对象的 CSS 类名 |
selectionStyle 与默认选中样式
selectionStyle是可选参数，但它的存在与否会改变渲染机制。源码 Pairwise.js 中的实现逻辑是：
- 传入
selectionStyle时：通过Tree.cssConverter将 CSS 字符串转换为内联样式对象，选中侧直接应用该样式（向后兼容模式）； - 未传入时：使用 Tailwind 语义类
bg-primary-background border border-primary-border-subtle rounded-sm作为选中态，通过 className 切换实现。
同时，无论采用哪种方式，两个对比对象都会被注入交互类cursor-pointer hover:bg-primary-emphasis-subtle transition-colors rounded-sm（Pairwise.js），使对象在悬停时呈现可点击反馈。
leftClass / rightClass
这两个参数用于给左右对象附加自定义 CSS 类名，便于与项目自身的样式体系（如覆盖到Text、Image等对象标签上）协同工作。官方示例中就为两个Text对象分别指定了leftClass="text1"和rightClass="text2"，在需要按左右位置差异化排版时非常实用。
高级用法：用 View 标签自定义布局
官方文档的第二个示例演示了如何通过View标签自定义 Pairwise 的呈现布局：
<View> <Pairwise name="pw" toName="txt-1,txt-2"></Pairwise> <View style="display: flex;"> <View style="margin-right: 1em;"><Text name="txt-1" value="$text1" /></View> <View><Text name="txt-2" value="$text2" /></View> </View> </View>这里的要点：
- 使用 flex 布局让左右两个对象并排展示，中间通过
margin-right留出间距； - 注意
Pairwise控件的声明与对象声明可以分离——控件通过toName="txt-1,txt-2"与对象建立关联，不要求控件紧贴对象书写； - 数据通过
$text1、$text2从任务 JSON 的data字段中取真实内容。
这种"控件在上、布局在下"的写法同样适用于Image、Audio等对象标签，是搭建并排对比界面的通用模式。
标注结果与数据导出格式
Pairwise 的标注结果以 JSON 形式存入任务 annotation 的result数组中。官方分类模板 pairwise-classification/config.xml 内置了标准结果样例：
{ "value": { "selected": "left" }, "id": "Prs1iTKZzp", "from_name": "pw", "to_name": "pw", "type": "pairwise" }字段含义：
| 字段 | 说明 |
|---|---|
value.selected | 选中结果，取值"left"、"right"或"none"（未选择） |
from_name | 对应配置中 Pairwise 的name（此处为pw） |
to_name | Pairwise 控件自身名称（源码创建结果时以控件自身为对象引用） |
type | 固定为"pairwise" |
从源码看，选中结果由updateResult动作写入（Pairwise.js）：当selected为"none"时移除已有结果；否则创建或更新结果，值即selected字段。该值类型在源码中定义为valueType: "selected"（Pairwise.js）。导出 CSV / JSON 时，value.selected即可直接作为"偏好/胜出方"特征用于后续排序模型的训练。
源码级原理：交互与状态机
深入 web/libs/editor/src/tags/control/Pairwise.js 可以看到整个交互闭环：
- 绑定点击：控件附加到标注页面后（
annotationAttached），分别把selectLeft、selectRight绑定到左右对象的onClick（Pairwise.js）； - 切换逻辑：
selectLeft/selectRight实现"再次点击取消"——若当前已选中同侧则重置为none，否则切换到该侧（Pairwise.js）； - 样式刷新：
setResult根据选择方向为左右对象更新 className 或内联样式（Pairwise.js）； - 结果持久化：
updateResult将选择写入 annotation result，needsUpdate则在加载既有标注时恢复选中态（Pairwise.js）。
值得注意的细节：源码注释中记录了一个已知约束——如果left/right任一对象引用缺失（例如toName拼写与对象名不一致），控制台会输出警告Pairwise: left or right object reference is missing（Pairwise.js）。因此排查"点击无响应"类问题时，应优先检查toName与对象name是否完全匹配。
实战模板：Pairwise 分类任务
仓库内置的社区模板 pairwise-classification/config.yml 提供了一个可直接在 Label Studio 中导入使用的完整配置：
<View> <Header>Select one of two items</Header> <Pairwise name="pw" toName="text1,text2" /> <Text name="text1" value="$pairText1" /> <Text name="text2" value="$pairText2" /> </View>对应任务数据格式为：
{ "data": { "pairText1": "Look at this! It's a brand new product", "pairText2": "Look at this! It's an awesome piece of sh*t" } }使用该模板时，只需在导入任务时提供pairText1、pairText2两个字段，即可批量开展对比标注。同样的结构可以替换为Image、Audio、Video等对象标签，扩展到图像美学对比、音频音质对比、视频片段偏好等场景。若需要"选择后打分"这类混合任务，也可以参考 pairwise-regression/config.yml 的写法，在 Pairwise 之外叠加Rating标签对两对象同时评分。
小结
Pairwise 标签以极简的配置完成了"对象对比 + 二选一"这一高频标注需求：toName声明对比对象、name定义结果字段、可选样式参数控制选中态外观，底层由 Pairwise.js 统一管理点击交互、状态切换与结果写入。理解其left / right / none三态模型与"再次点击取消"的交互规则，即可在文本、图片、音频、视频等任意受支持的数据类型上快速搭建专业的成对对比标注项目，为后续的偏好排序、生成质量评估等机器学习任务积累结构化数据。
【免费下载链接】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），仅供参考
