Label Studio 任务标注 JSON 格式完全指南annotations、predictions 与 result 字段详解【免费下载链接】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 官方任务格式文档为核心系统讲解标注任务在 JSON 中的存储结构——从顶层data、annotations、predictions三大块到result数组内from_name/to_name/type/value的语义与组合规则。你将学会如何阅读和校验导出数据、如何在导入时通过completed_by指定标注者、如何区分草稿与预测结果并结合本仓库源码label_studio/tasks/理解这些字段在服务端落地时的真实含义与校验逻辑为二次开发、数据迁移和 ML 预标注集成打下基础。1. 任务标注 JSON 的整体骨架当你用 Label Studio 完成数据标注后系统会把结果以 JSON 形式存储。一个已完成任务的原始 JSON 结构如下来源于本仓库文档 docs/source/includes/task_format.md{ id: 1, created_at: 2021-03-09T21:52:49.513742Z, updated_at: 2021-03-09T22:16:08.746926Z, project: 83, 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 } } ] } ] }可以看到这份 JSON 由三大部分构成任务元信息id、created_at、updated_at、project任务数据data即导入时从输入数据原样拷贝过来的内容标注与预测annotations人工标注结果数组与predictions机器学习预测结果数组。从源码结构看这三个部分在服务端分别对应 label_studio/tasks/models.py 中的Task、Annotation与Prediction三个 Django 模型Task.data使用 JSONField 存储用户导入的数据Annotation.result与Prediction.result同样使用 JSONField 存储标注/预测结果明细而Annotation.completed_by则是一个指向用户表的外键settings.AUTH_USER_MODEL用于记录标注者身份。2. 顶层 JSON 属性详解下表是文档中给出的完整顶层属性说明其中关键的存储语义已在括号中补充JSON 属性名描述id数据集中该标注任务的标识符。data从输入数据任务格式拷贝过来的数据。对应Task.dataJSONField字段的 key 必须与标注配置中 Object 标签的value参数匹配。projectLabel Studio 中某个特定项目的标识符。annotations包含该任务标注结果的数组。annotations.id已完成任务的标识符。annotations.lead_time标注该任务所花费的时间秒。对应Annotation.lead_timeFloatField。annotations.result包含标注结果的数组。annotations.updated_at标注创建或修改的时间戳。annotations.completed_at标注创建或提交的时间戳。annotations.completed_by创建该标注的用户 ID。与 Label Studio UI 的 People 页面中用户列表顺序一致。annotations.was_cancelled布尔值表示该标注是否被跳过或取消。对应Annotation.was_cancelled源码注释为 User skipped the task。result.id该任务某个具体标注结果的标识符。可用于将不同控制标签如Labels和Rectangle的区域组合在一起。result.parentID可选父级区域result.id的引用。它把区域组织成 Region 面板中的层级树。result.from_name用于标注该区域的标签名称控制标签。result.to_name提供待标注区域的 Object 标签名称。result.type用于标注任务的标签类型。result.value标签特有的值包含标注任务的详细结果。其结构取决于具体标签。drafts草稿标注数组格式与 annotations 数组类似。仅当通过 UI 快照导出或通过 Snapshot API 导出时才会包含。predictions机器学习预测数组格式与 annotations 数组相同仅多一个参数。predictions.score结果的总体得分基于概率输出、置信度或其他指标。task.updated_at任务或其任何标注/审核被创建、更新或删除的时间戳。完整属性清单可参阅本仓库的 API 文档 docs/source/guide/api.md以及任务导入/导出文档 docs/source/guide/tasks.md 中关于 “Raw JSON format of completed tasks” 的说明。值得注意的两个细节result_count与id的唯一性在Annotation.save()的实现中label_studio/tasks/models.py服务端会根据result中每个结果的id构造集合并将result_count重算为该集合长度——这从侧面印证了result.id在结果组合与去重中的核心地位。predictions与annotations的关系两者result结构一致但predictions额外携带score和model_version。在 label_studio/tasks/models.py 中Prediction模型也确实比Annotation多出scoreFloatField、model_versionTextField、cluster、neighbors、mislabeling等字段用于支撑主动学习与预标注。3. 深入理解 result 数组from_name / to_name / type / valueresult是标注 JSON 中最核心的部分。每个 result 对象由四个关键字段构成它们共同描述“哪个控件、对哪个对象、以什么类型、标注了什么值”。3.1 四个关键字段的含义字段含义对应源码/文档from_name控制标签Control tag的name即产生标注动作的标签如Labels、Choices、RectangleLabels。文档指向 control tags 说明源码中 label_studio/tasks/models.py 的prepare_prediction_result会按from_name匹配解析出的标签配置。to_nameObject 标签的name即被标注的数据对象如Image、Text。同上。type标签类型如rectanglelabels、choices、labels、textarea等。在Prediction.prepare_prediction_result中type取自解析配置里标签类型的type()结果。value标签特有的值对象结构随标签类型变化。文档建议逐个查看每个标签的说明。3.2 value 的结构取决于标签类型以文档中的矩形框标注为例value包含x、y、width、height、rotation五个数值与标签数组value: { height: 10.458911419423693, rectanglelabels: [Moonwalker], rotation: 0, width: 12.4, x: 50.8, y: 5.869797225186766 }而如果是文本分类choices类型value则是value: { choices: [Positive] }不同标签的value结构各有约定可参见本仓库 docs/source/tags/ 目录下每个标签的独立文档以及 docs/source/includes/result_format.md 对结果格式的补充说明。3.3 一个任务对应多条结果同一个标注中可以有多个 result 条目例如同时包含一个Choices分类和一个TextArea文本输入的结果。此时依靠result.id区分条目from_name相同而id不同表示同类型控件的多个标注区域。从源码层面看(id, from_name, type)三元组还被用作结果去重的键在 label_studio/tasks/result_utils.py 的dedupe_annotation_result_list中服务端会按(id, from_name, type)折叠重复条目保留首个出现的防止同 id 行重复落库这也印证了文档中 “使用result.id组合不同控制标签区域” 的设计意图。另外result数据在写入前还会经过 result_utils.py 的sanitize_null_bytes清洗剔除 NUL 字节——这是 PostgreSQL JSONB 列无法存储\u0000所带来的工程细节。3.4 parentID区域层级树当标签配置包含父子区域例如先画一个矩形再在其中标注子区域时子区域的result会通过parentID字段引用父区域的result.id。Region 面板据此把这些区域组织成层级树方便嵌套标注的管理与导出。4. annotations 与 predictions人工标注与机器预测的并存4.1 两者的格式差异文档明确指出predictions数组与annotations数组采用相同格式仅多一个score参数以及示例中可见的model_version、created_ago。这意味着任何用于人工标注的 result 结构都可以原样用于机器预测结果预测结果可以直接作为预标注pre-annotation展示给标注者人工在此基础上修正后保存为 annotation。这一设计在源码中得到印证Prediction.result与Annotation.result都是 JSONField而Annotation.prediction字段JSONField记录了标注时看到的预测内容parent_prediction外键则记录了该标注是由哪条预测转化而来见 label_studio/tasks/models.py。4.2 score 的用途predictions.score表示该条预测的整体得分基于概率输出或置信度等指标。在导入文档 docs/source/guide/tasks.md 的示例中score被注释为 “用于主动学习采样模式”——即任务队列可依据预测得分决定优先展示给标注者哪些任务。在Prediction模型中score对应 FloatField而 SDK 侧PredictionValue也承载相同的结构见 label_studio/tasks/models.py 的导入。4.3 预测结果的多版本并存从示例可见同一任务可挂载多个预测条目分别来自model 1、model 2等不同model_version。Prediction.model_version在模型中被设计为 TextField注释为 “产生该预测的模型版本字符串用于实时模型与离线预测上传两种场景”。在Task.get_predictions_for_prelabeling()label_studio/tasks/models.py中系统正是依据project.model_version筛选对应版本的预测用于预标注。5. drafts 草稿数组快照导出特有的格式drafts仅在两种场景下出现从 Label Studio UI 导出快照使用 Snapshot API 导出快照。其结构与annotations数组基本一致但语义不同草稿是标注者尚未提交的中间状态。在源码中草稿由AnnotationDraft模型承载label_studio/tasks/models.py包含resultJSONField、lead_time、user、was_postponed是否被标注者点击“稍后处理”等字段导出时这些信息被序列化为drafts数组。企业版中草稿还支持按user邮箱还原给对应标注者见 label_studio/tasks/serializers.py 的_insert_valid_user_drafts。6. 导入时指定标注者completed_by 的三种写法通过 UI、API 或 SDK 导入标注时可以使用 annotation 对象中的completed_by字段控制哪些用户被分配为标注者。文档给出三种写法// 方式 1不指定标注者使用导入者 { result: [...], completed_by: null } // 方式 2按邮箱指定 { result: [...], completed_by: { email: annotatorexample.com } } // 方式 3按 ID 指定 { result: [...], completed_by: 42 }系统会将邮箱或 ID 与组织内已有用户匹配若配置允许则回退到导入者。6.1 源码层面的匹配逻辑从 label_studio/tasks/serializers.py 的resolve_completed_by_id可以还原完整的解析顺序completed_by为null时使用默认用户导入者completed_by为整数时若该 ID 存在于组织成员集合中则直接采用completed_by为字典时先尝试取email字段匹配组织成员邮箱映射再尝试id若email缺失或无法匹配则回退到默认用户在开启fflag_fix_back_bros_1092_import_unknown_completed_by_short特性开关时否则抛出ValidationError提示 “Unknown annotators email” 或 “not a valid annotators email or ID”。在批量导入流程中label_studio/data_import/functions.pyImportApiSerializer会以completed_by_id的形式把解析结果写入 annotation 记录从而把completed_by指向正确的用户外键。这一机制同样作用于快照还原场景_insert_valid_completed_by会利用组织成员email - user.id映射恢复completed_by保证跨实例迁移时标注者身份不丢失。7. 数据校验与常见陷阱7.1 result 的唯一性与去重(id, from_name, type)三元组是结果条目的唯一性键。服务端在写入边界会调用dedupe_annotation_result_list折叠重复条目保留首个出现者见 label_studio/tasks/result_utils.py。因此构造导入数据时应保证每个 result 的id唯一且有区分度避免不同区域共用 id 导致数据丢失。7.2 data 字段的类型校验data中的 key 必须与标注配置里 Object 标签的value参数一一对应。在 label_studio/tasks/validation.py 中导入任务会按project.data_types校验每个数据字段的类型例如Image、Audio期望字符串URLTimeSeries在valueTypejson时则期望列表。若类型不匹配会得到形如data[image]... is of type int, but the object tag Image expects...的错误提示。7.3 时间戳与时区示例中的created_at、updated_at均为 UTC 时间带Z后缀的 ISO 8601 格式。Annotation模型的created_at/updated_at使用auto_now_add/auto_now自动维护lead_time为浮点数秒数FloatField。7.4 NUL 字节与 PDF/OCR 数据从 PDF 内嵌 OCR 文本层复制内容时result中可能混入\u0000字符。由于 PostgreSQL JSONB 无法存储 NUL 字节服务端会通过sanitize_null_bytes在写入前剔除见 label_studio/tasks/result_utils.py。构造导入数据时应主动避免携带 NUL 字符。8. 实战构造一份可导入的完整任务 JSON综合以上规则下面是一份面向文本分类项目的、可直接通过 UI/API/SDK 导入的完整任务示例也可见于 docs/source/guide/tasks.md 的 “Basic Label Studio JSON format”[ { data: { my_text: Opossums are great, ref_id: 456, meta_info: { timestamp: 2020-03-09 18:15:28.212882, location: North Pole } }, annotations: [ { completed_by: { email: annotatorexample.com }, result: [ { from_name: sentiment_class, to_name: message, type: choices, readonly: false, hidden: false, value: { choices: [Positive] } } ] } ], predictions: [ { model_version: model 1, score: 0.95, result: [ { from_name: sentiment_class, to_name: message, type: choices, value: { choices: [Neutral] } } ] } ] } ]关键点回顾data中的my_text对应标注配置Text namemessage value$my_text/的value变量annotations与predictions均可省略未标注任务无需携带导入多个任务时使用 JSON 数组也可以改用 CSV/TSV列名即data的 key或 TXT每行一个任务需仅含单一 Object 标签对于图片、音频、视频等多媒体类型data中的值必须是带 CORS 的合法 URL而非二进制内容。9. 更多延伸阅读任务导入的完整指南支持的格式、UI/API/CLI 导入方式、valueType与resolver参数docs/source/guide/tasks.md标注结果导出的原始 JSON 格式说明docs/source/guide/export.md预测预标注数据的导入与主动学习docs/source/guide/predictions.md各标签的value结构定义docs/source/tags/index.md服务端模型与校验实现label_studio/tasks/models.py、label_studio/tasks/serializers.py、label_studio/tasks/validation.py结果写入的清洗与去重工具label_studio/tasks/result_utils.py批量导入落库流程label_studio/data_import/functions.py【免费下载链接】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），仅供参考
Label Studio 任务标注 JSON 格式完全指南：annotations、predictions 与 result 字段详解
Label Studio 任务标注 JSON 格式完全指南annotations、predictions 与 result 字段详解【免费下载链接】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 官方任务格式文档为核心系统讲解标注任务在 JSON 中的存储结构——从顶层data、annotations、predictions三大块到result数组内from_name/to_name/type/value的语义与组合规则。你将学会如何阅读和校验导出数据、如何在导入时通过completed_by指定标注者、如何区分草稿与预测结果并结合本仓库源码label_studio/tasks/理解这些字段在服务端落地时的真实含义与校验逻辑为二次开发、数据迁移和 ML 预标注集成打下基础。1. 任务标注 JSON 的整体骨架当你用 Label Studio 完成数据标注后系统会把结果以 JSON 形式存储。一个已完成任务的原始 JSON 结构如下来源于本仓库文档 docs/source/includes/task_format.md{ id: 1, created_at: 2021-03-09T21:52:49.513742Z, updated_at: 2021-03-09T22:16:08.746926Z, project: 83, 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 } } ] } ] }可以看到这份 JSON 由三大部分构成任务元信息id、created_at、updated_at、project任务数据data即导入时从输入数据原样拷贝过来的内容标注与预测annotations人工标注结果数组与predictions机器学习预测结果数组。从源码结构看这三个部分在服务端分别对应 label_studio/tasks/models.py 中的Task、Annotation与Prediction三个 Django 模型Task.data使用 JSONField 存储用户导入的数据Annotation.result与Prediction.result同样使用 JSONField 存储标注/预测结果明细而Annotation.completed_by则是一个指向用户表的外键settings.AUTH_USER_MODEL用于记录标注者身份。2. 顶层 JSON 属性详解下表是文档中给出的完整顶层属性说明其中关键的存储语义已在括号中补充JSON 属性名描述id数据集中该标注任务的标识符。data从输入数据任务格式拷贝过来的数据。对应Task.dataJSONField字段的 key 必须与标注配置中 Object 标签的value参数匹配。projectLabel Studio 中某个特定项目的标识符。annotations包含该任务标注结果的数组。annotations.id已完成任务的标识符。annotations.lead_time标注该任务所花费的时间秒。对应Annotation.lead_timeFloatField。annotations.result包含标注结果的数组。annotations.updated_at标注创建或修改的时间戳。annotations.completed_at标注创建或提交的时间戳。annotations.completed_by创建该标注的用户 ID。与 Label Studio UI 的 People 页面中用户列表顺序一致。annotations.was_cancelled布尔值表示该标注是否被跳过或取消。对应Annotation.was_cancelled源码注释为 User skipped the task。result.id该任务某个具体标注结果的标识符。可用于将不同控制标签如Labels和Rectangle的区域组合在一起。result.parentID可选父级区域result.id的引用。它把区域组织成 Region 面板中的层级树。result.from_name用于标注该区域的标签名称控制标签。result.to_name提供待标注区域的 Object 标签名称。result.type用于标注任务的标签类型。result.value标签特有的值包含标注任务的详细结果。其结构取决于具体标签。drafts草稿标注数组格式与 annotations 数组类似。仅当通过 UI 快照导出或通过 Snapshot API 导出时才会包含。predictions机器学习预测数组格式与 annotations 数组相同仅多一个参数。predictions.score结果的总体得分基于概率输出、置信度或其他指标。task.updated_at任务或其任何标注/审核被创建、更新或删除的时间戳。完整属性清单可参阅本仓库的 API 文档 docs/source/guide/api.md以及任务导入/导出文档 docs/source/guide/tasks.md 中关于 “Raw JSON format of completed tasks” 的说明。值得注意的两个细节result_count与id的唯一性在Annotation.save()的实现中label_studio/tasks/models.py服务端会根据result中每个结果的id构造集合并将result_count重算为该集合长度——这从侧面印证了result.id在结果组合与去重中的核心地位。predictions与annotations的关系两者result结构一致但predictions额外携带score和model_version。在 label_studio/tasks/models.py 中Prediction模型也确实比Annotation多出scoreFloatField、model_versionTextField、cluster、neighbors、mislabeling等字段用于支撑主动学习与预标注。3. 深入理解 result 数组from_name / to_name / type / valueresult是标注 JSON 中最核心的部分。每个 result 对象由四个关键字段构成它们共同描述“哪个控件、对哪个对象、以什么类型、标注了什么值”。3.1 四个关键字段的含义字段含义对应源码/文档from_name控制标签Control tag的name即产生标注动作的标签如Labels、Choices、RectangleLabels。文档指向 control tags 说明源码中 label_studio/tasks/models.py 的prepare_prediction_result会按from_name匹配解析出的标签配置。to_nameObject 标签的name即被标注的数据对象如Image、Text。同上。type标签类型如rectanglelabels、choices、labels、textarea等。在Prediction.prepare_prediction_result中type取自解析配置里标签类型的type()结果。value标签特有的值对象结构随标签类型变化。文档建议逐个查看每个标签的说明。3.2 value 的结构取决于标签类型以文档中的矩形框标注为例value包含x、y、width、height、rotation五个数值与标签数组value: { height: 10.458911419423693, rectanglelabels: [Moonwalker], rotation: 0, width: 12.4, x: 50.8, y: 5.869797225186766 }而如果是文本分类choices类型value则是value: { choices: [Positive] }不同标签的value结构各有约定可参见本仓库 docs/source/tags/ 目录下每个标签的独立文档以及 docs/source/includes/result_format.md 对结果格式的补充说明。3.3 一个任务对应多条结果同一个标注中可以有多个 result 条目例如同时包含一个Choices分类和一个TextArea文本输入的结果。此时依靠result.id区分条目from_name相同而id不同表示同类型控件的多个标注区域。从源码层面看(id, from_name, type)三元组还被用作结果去重的键在 label_studio/tasks/result_utils.py 的dedupe_annotation_result_list中服务端会按(id, from_name, type)折叠重复条目保留首个出现的防止同 id 行重复落库这也印证了文档中 “使用result.id组合不同控制标签区域” 的设计意图。另外result数据在写入前还会经过 result_utils.py 的sanitize_null_bytes清洗剔除 NUL 字节——这是 PostgreSQL JSONB 列无法存储\u0000所带来的工程细节。3.4 parentID区域层级树当标签配置包含父子区域例如先画一个矩形再在其中标注子区域时子区域的result会通过parentID字段引用父区域的result.id。Region 面板据此把这些区域组织成层级树方便嵌套标注的管理与导出。4. annotations 与 predictions人工标注与机器预测的并存4.1 两者的格式差异文档明确指出predictions数组与annotations数组采用相同格式仅多一个score参数以及示例中可见的model_version、created_ago。这意味着任何用于人工标注的 result 结构都可以原样用于机器预测结果预测结果可以直接作为预标注pre-annotation展示给标注者人工在此基础上修正后保存为 annotation。这一设计在源码中得到印证Prediction.result与Annotation.result都是 JSONField而Annotation.prediction字段JSONField记录了标注时看到的预测内容parent_prediction外键则记录了该标注是由哪条预测转化而来见 label_studio/tasks/models.py。4.2 score 的用途predictions.score表示该条预测的整体得分基于概率输出或置信度等指标。在导入文档 docs/source/guide/tasks.md 的示例中score被注释为 “用于主动学习采样模式”——即任务队列可依据预测得分决定优先展示给标注者哪些任务。在Prediction模型中score对应 FloatField而 SDK 侧PredictionValue也承载相同的结构见 label_studio/tasks/models.py 的导入。4.3 预测结果的多版本并存从示例可见同一任务可挂载多个预测条目分别来自model 1、model 2等不同model_version。Prediction.model_version在模型中被设计为 TextField注释为 “产生该预测的模型版本字符串用于实时模型与离线预测上传两种场景”。在Task.get_predictions_for_prelabeling()label_studio/tasks/models.py中系统正是依据project.model_version筛选对应版本的预测用于预标注。5. drafts 草稿数组快照导出特有的格式drafts仅在两种场景下出现从 Label Studio UI 导出快照使用 Snapshot API 导出快照。其结构与annotations数组基本一致但语义不同草稿是标注者尚未提交的中间状态。在源码中草稿由AnnotationDraft模型承载label_studio/tasks/models.py包含resultJSONField、lead_time、user、was_postponed是否被标注者点击“稍后处理”等字段导出时这些信息被序列化为drafts数组。企业版中草稿还支持按user邮箱还原给对应标注者见 label_studio/tasks/serializers.py 的_insert_valid_user_drafts。6. 导入时指定标注者completed_by 的三种写法通过 UI、API 或 SDK 导入标注时可以使用 annotation 对象中的completed_by字段控制哪些用户被分配为标注者。文档给出三种写法// 方式 1不指定标注者使用导入者 { result: [...], completed_by: null } // 方式 2按邮箱指定 { result: [...], completed_by: { email: annotatorexample.com } } // 方式 3按 ID 指定 { result: [...], completed_by: 42 }系统会将邮箱或 ID 与组织内已有用户匹配若配置允许则回退到导入者。6.1 源码层面的匹配逻辑从 label_studio/tasks/serializers.py 的resolve_completed_by_id可以还原完整的解析顺序completed_by为null时使用默认用户导入者completed_by为整数时若该 ID 存在于组织成员集合中则直接采用completed_by为字典时先尝试取email字段匹配组织成员邮箱映射再尝试id若email缺失或无法匹配则回退到默认用户在开启fflag_fix_back_bros_1092_import_unknown_completed_by_short特性开关时否则抛出ValidationError提示 “Unknown annotators email” 或 “not a valid annotators email or ID”。在批量导入流程中label_studio/data_import/functions.pyImportApiSerializer会以completed_by_id的形式把解析结果写入 annotation 记录从而把completed_by指向正确的用户外键。这一机制同样作用于快照还原场景_insert_valid_completed_by会利用组织成员email - user.id映射恢复completed_by保证跨实例迁移时标注者身份不丢失。7. 数据校验与常见陷阱7.1 result 的唯一性与去重(id, from_name, type)三元组是结果条目的唯一性键。服务端在写入边界会调用dedupe_annotation_result_list折叠重复条目保留首个出现者见 label_studio/tasks/result_utils.py。因此构造导入数据时应保证每个 result 的id唯一且有区分度避免不同区域共用 id 导致数据丢失。7.2 data 字段的类型校验data中的 key 必须与标注配置里 Object 标签的value参数一一对应。在 label_studio/tasks/validation.py 中导入任务会按project.data_types校验每个数据字段的类型例如Image、Audio期望字符串URLTimeSeries在valueTypejson时则期望列表。若类型不匹配会得到形如data[image]... is of type int, but the object tag Image expects...的错误提示。7.3 时间戳与时区示例中的created_at、updated_at均为 UTC 时间带Z后缀的 ISO 8601 格式。Annotation模型的created_at/updated_at使用auto_now_add/auto_now自动维护lead_time为浮点数秒数FloatField。7.4 NUL 字节与 PDF/OCR 数据从 PDF 内嵌 OCR 文本层复制内容时result中可能混入\u0000字符。由于 PostgreSQL JSONB 无法存储 NUL 字节服务端会通过sanitize_null_bytes在写入前剔除见 label_studio/tasks/result_utils.py。构造导入数据时应主动避免携带 NUL 字符。8. 实战构造一份可导入的完整任务 JSON综合以上规则下面是一份面向文本分类项目的、可直接通过 UI/API/SDK 导入的完整任务示例也可见于 docs/source/guide/tasks.md 的 “Basic Label Studio JSON format”[ { data: { my_text: Opossums are great, ref_id: 456, meta_info: { timestamp: 2020-03-09 18:15:28.212882, location: North Pole } }, annotations: [ { completed_by: { email: annotatorexample.com }, result: [ { from_name: sentiment_class, to_name: message, type: choices, readonly: false, hidden: false, value: { choices: [Positive] } } ] } ], predictions: [ { model_version: model 1, score: 0.95, result: [ { from_name: sentiment_class, to_name: message, type: choices, value: { choices: [Neutral] } } ] } ] } ]关键点回顾data中的my_text对应标注配置Text namemessage value$my_text/的value变量annotations与predictions均可省略未标注任务无需携带导入多个任务时使用 JSON 数组也可以改用 CSV/TSV列名即data的 key或 TXT每行一个任务需仅含单一 Object 标签对于图片、音频、视频等多媒体类型data中的值必须是带 CORS 的合法 URL而非二进制内容。9. 更多延伸阅读任务导入的完整指南支持的格式、UI/API/CLI 导入方式、valueType与resolver参数docs/source/guide/tasks.md标注结果导出的原始 JSON 格式说明docs/source/guide/export.md预测预标注数据的导入与主动学习docs/source/guide/predictions.md各标签的value结构定义docs/source/tags/index.md服务端模型与校验实现label_studio/tasks/models.py、label_studio/tasks/serializers.py、label_studio/tasks/validation.py结果写入的清洗与去重工具label_studio/tasks/result_utils.py批量导入落库流程label_studio/data_import/functions.py【免费下载链接】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），仅供参考
