Label Studio Bucket 标签详解配合 Ranker 实现 List 分组排序与精选【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio导读Bucket是 Label Studio 标注配置中嵌套在Ranker标签内的分组容器用于将List中的列表项按类别归类、排序或精选。本文以 bucket.md 为核心骨架结合 Label Studio 前端编辑器源码Ranker.jsx与官方示例ranker_buckets完整讲解 Bucket 的参数定义、三种分组模式排序 / 精选 / 默认分组、导出结果结构与源码级运行原理帮助你在搜索相关性标注、RAG 检索反馈、内容精选等场景中快速落地可用的标注配置。一、Bucket 是什么Bucket是Ranker标签的子标签在源码中被定义为subtag见 Ranker.jsx 第 212-226 行本身不独立渲染界面元素而是作为Ranker内部的列column来组织List中的条目。标注人员可以把列表项拖拽进不同的 Bucket从而完成分组、排序或相关度精选。它的核心能力来自Ranker的三种工作模式见 Ranker.jsx 第 91-105 行 中的defaultBucket与rankOnly视图模式触发条件行为排序模式rank mode仅使用Ranker不嵌套任何 Bucket列表变为可拖拽排序结果是一个以Ranker名称为 key 的 ID 数组精选模式pick mode使用 Bucket 但未标记默认 Bucket列表项可被拖入各 Bucket未归入任何 Bucket 的项保留在原始列表列内部 key 为_分组模式group mode使用 Bucket 且其中一个标记defaulttrue原始列表列被隐藏所有未归类的项自动落入默认 Bucket导出结果始终包含全部列表项在源码中这三种模式与defaultBucket计算逻辑直接对应rank mode返回Ranker自身的 namepick mode返回undefinedgroup mode返回标记了defaulttrue的 Bucket 的 nameRanker.jsx 第 100-102 行。二、Bucket 标签参数详解这是 bucket.md 定义的完整参数表结合 Ranker.jsx 第 220-226 行 的BucketModel状态树定义参数类型默认值说明namestring必填无默认值列的名称作为导出结果中的 key 使用源码中name: types.string为必填字段titlestringnull列标题即界面中该 Bucket 列显示的标题源码中为types.maybeNull(types.string)允许省略defaultbooleanfalse是否将该 Bucket 设为默认分组。置为true后List中的全部条目默认归入此 Bucket源码中为types.optional(types.boolean, false)省略即视为falseBucketModel还包含一个自动生成的内部字段idtypes.optional(types.identifier, guidGenerator)用于在前端状态树中唯一标识每个 Bucket 实例标注配置中无需手动指定。三、核心用法一ListRanker排序模式标注配置View Style .htx-ranker-column { background: cornflowerblue; } .htx-ranker-item { background: lightgoldenrodyellow; } /Style List nameresults value$items titleSearch Results / Ranker namerank toNameresults / /View说明List的value$items指向任务数据中的数组数组元素需包含id、title、body等字段见 list.mdRanker的name与toName分别声明结果字段名和关联的List标签.htx-ranker-column与.htx-ranker-item是Style标签中预定义的两个样式类分别作用于列Bucket与列表项可自定义视觉样式。输入数据{ items: [ { id: blog, title: 10 tips to write a better function, body: There is nothing worse than being left in the lurch when it comes to writing a function! }, { id: mdn, title: Arrow function expressions, body: An arrow function expression is a compact alternative to a traditional function }, { id: wiki, title: Arrow (computer science), body: In computer science, arrows or bolts are a type class... } ] }导出结果标注人员将mdn拖到顶部、blog拖到底部后结果为以Ranker名称rank为 key、按新顺序排列的 ID 数组[ { value: { ranker: { rank: [mdn, wiki, blog] } }, id: PpwBv_NMxd, from_name: rank, to_name: results, type: ranker, origin: manual } ]源码原理在rankOnly模式下columns视图只生成一列其 id 为Ranker的 name、title 取自List的 titleRanker.jsx 第 107-110 行beforeSend在提交时若结果尚未创建会以所有列表项 ID 填充该唯一列Ranker.jsx 第 176-190 行从而保证每条任务都能导出一致的结构。四、核心用法二ListRankerBucket精选模式标注配置View List nameresults value$items titleSearch Results / Ranker namerank toNameresults Bucket namebest titleBest results / Bucket nameads titlePaid results / /Ranker /View这正好对应仓库内置示例 ranker_buckets/config.xml 中的配置该示例还额外示范了.htx-ranker-column与.htx-ranker-item的样式写法。导出结果未指定默认 Bucket 时结果是一个以 Bucket 名为 key 的字典每个 key 对应一个 ID 数组未被拖入任何 Bucket 的项会出现在 key 为_的数组中[ { value: { ranker: { _: [wiki], best: [mdn], ads: [blog] } }, id: sjYK7Bcl7g, from_name: rank, to_name: results, type: ranker, origin: manual } ]仓库内置示例的预置标注数据ranker_buckets/annotations/1.json与之同构——best: [mdn]、ads: [blog]wiki留在原始列表可以直接在 Label Studio 编辑器中加载该示例观察界面与数据对应关系。源码原理columns视图在存在 Bucket 且无默认 Bucket 时会在所有 Bucket 列之前unshift一个 id 为常量ORIGINAL_ITEMS_KEY即_、title 取自List的原始列表列Ranker.jsx 第 13-14 行、第 111-115 行。dataSource视图则负责把未进入任何已知列或来自未知列的项补回_列保证界面展示与导出数据一致Ranker.jsx 第 136-152 行。源码注释也明确指出_属于内部实现细节后续版本可能调整。五、核心用法三默认 Bucketdefaulttrue标注配置View List nameresults value$items titleSearch Results / Ranker namerank toNameresults Bucket namebest titleBest results defaulttrue / Bucket nameads titlePaid results / /Ranker /View标记默认 Bucket 后会发生两件事隐藏原始列表列界面不再显示Search Results这一列源码层面即不再unshift_列未分类项落入默认 Bucket所有未拖入任何 Bucket 的项自动归入best。导出结果[ { value: { ranker: { best: [mdn, wiki], ads: [blog] } }, id: 8QaNxe4hN3, from_name: rank, to_name: results, type: ranker, origin: manual } ]源码原理defaultBucket视图在存在 Bucket 时会找出default true的那个 Bucket 的 nameRanker.jsx 第 100-102 行。dataSource在尚未产生标注结果时会直接把全部列表项 ID 填进默认 Bucket 列Ranker.jsx 第 132 行beforeSend也以self.defaultBucket作为兜底填充列Ranker.jsx 第 187 行。这意味着使用默认 Bucket 时导出结果永远包含List中的全部条目不会因标注未完成而丢失未分类数据——这是设计精选 兜底类标注任务时的关键行为。六、典型应用场景结合 ranker.md 末尾列出的相关模板Bucket常见于以下任务搜索 / 检索结果相关度精选用best/ads或relevant/irrelevant等 Bucket 对候选结果分级配合默认 Bucket 保证每条结果都有归属RAG 检索反馈对 LLM 检索返回的文档片段做相关性分组作为强化学习或提示词调优的训练数据排序任务不使用 Bucket直接拖拽确定条目的先后顺序。Ranker组件在源码中被注册为独立的可标注对象类型Registry.addObjectType(RankerModel)见 Ranker.jsx 第 236 行因此 Bucket 产生的分组结果会作为普通标注结果一并导出到项目导出文件中可被下游训练管线直接消费。七、使用注意事项name必填且作为结果 key导出字典中的 key 直接取自 Bucket 的name命名应保持稳定、避免与其他字段冲突title可省略省略时 Bucket 列标题为空字符串Ranker.jsx 第 111 行建议始终填写以提升标注界面可读性default默认为false不写即表示不设默认分组原始列表会以_列形式出现在导出结果中Bucket仅能嵌套在Ranker内RankerModel的子节点类型被约束为types.unionArray([bucket])Ranker.jsx 第 83 行源码注释表明未来可能支持在 Bucket 内放置View但当前版本不支持Ranker的collapsible参数默认值为trueRanker.jsx 第 80 行即分组面板默认可折叠。八、快速验证与进一步探索在 Label Studio 中新建项目后可在标注配置编辑器中粘贴上文任一配置进行可视化验证仓库内置示例 ranker_buckets 及其任务数据 tasks.json、预置标注 annotations/1.json 提供了可直接加载的完整样例深入理解List标签的value数据结构见 list.md完整了解Ranker三种模式的切换逻辑见 ranker.md查看Bucket与Ranker的前端状态树与序列化实现见 Ranker.jsx相关模板可参考 generative-llm-ranker.md了解 Bucket 分组在实际 LLM 检索反馈任务中的端到端用法。【免费下载链接】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），仅供参考