Label Studio 导出指南注解与数据的格式、API 与实操详解【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 支持在标注项目的任意阶段导出注解annotations与数据导出结果可直接用于训练机器学习模型或数据科学项目。本指南以官方文档为基础结合仓库源码label_studio/data_export/、label_studio/tasks/functions.py等深入讲解 UI 导出、命令行导出、Easy Export API、快照Snapshot异步导出、受支持的全部导出格式、原始 JSON 结构以及图像注解单位换算帮助读者在社区版与企业版中选择最合适的导出路径并规避超时陷阱。一、导出机制概览注解存储在哪里Label Studio 将注解以原始 JSON 格式存储在后端数据库中包括 SQLite、PostgreSQL或你指定的云存储与数据库目标存储。云存储桶中每个已标注任务对应一个名为task_id.json的文件。关于目标存储同步的更多说明参见云存储配置。从源码看同步导出的核心调用链位于 data_export/api.py 的ExportAPI.get()先按条件筛选任务并序列化为 JSON 列表再由 data_export/models.py 的DataExport.generate_export_file()交给label_studio_sdk.converter.Converter完成格式转换。若转换结果只有一个文件则直接返回否则会打包成 ZIP 归档返回。快照异步导出的核心在 data_export/mixins.py 的export_to_file()与后台任务export_background()。有一点需要特别注意部分导出格式只导出注解而不导出任务数据本身具体见下文受支持的导出格式一节。图像注解以 JSON 导出时边框尺寸与位置使用相对整张图片尺寸的百分比而非像素换算方法见图像注解单位换算。二、注解结果在 JSON 中的保存方式每个标注生成的注解annotation都包含**区域Regions与结果Results**两部分Regions指被选中的数据区域可能是文本片段、图像区域、音频片段或其他实体Results指赋予该区域的标签。每个区域在每条注解内拥有唯一 ID由A-Za-z0-9_-字符组成的字符串每条 result 的 ID 与其对应的区域 ID 相同。当预测prediction被用来生成注解时结果 ID 会保持一致从而可以追踪模型生成的区域并与人工创建、审核过的注解直接对比。Label Studio JSON 格式的注解任务标注完成后每个任务的原始 JSON 结构如下完整字段说明见API 文档与任务格式{ 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 } } ] }, { created_ago: 4 hours, model_version: model 2, result: [ /* ... 结构同上 ... */ ] } ] }关键 JSON 字段说明JSON 属性名说明id数据集中的标注任务标识符。data从输入任务格式复制的原始数据参见任务格式。project该任务所属 Label Studio 项目的标识符。annotations包含该任务标注结果的数组。annotations.id已完成任务的标识符。annotations.lead_time标注该任务所花费的秒数。annotations.result包含标注结果的数组。annotations.updated_at注解创建或修改的时间戳。annotations.completed_at注解创建或提交的时间戳。annotations.completed_by创建注解的用户 ID与 UI 人员页面上的用户列表顺序一致。annotations.was_cancelled布尔值表示该注解是否被跳过或取消。result.id该任务下特定标注结果的标识符可用于将不同控制标签如Labels与Rectangle的区域关联起来。result.parentID可选父区域 result.id 的引用用于在 Regions 面板中组织区域的层级树。result.from_name标注该区域所用标签的名称参见控制标签。result.to_name提供待标注区域的对象标签名称参见对象标签。result.type用于标注该任务的标签类型。result.value标签相关的值包含标注结果的细节其结构取决于标签类型参见各标签文档。drafts草稿注解数组结构与 annotations 类似。仅当通过UI 快照导出或快照 API导出时包含。predictions机器学习预测数组结构与 annotations 相同但额外带一个参数。predictions.score基于概率输出、置信度或其他指标得到的结果总体得分。task.updated_at任务或其注解/审核被创建、更新或删除的时间戳。导入时指定标注者completed_by在导入注解时可以通过注解对象中的completed_by字段控制标注者分配// 方式 1不指定标注者使用导入者 { result: [...], completed_by: null } // 方式 2通过邮箱指定 { result: [...], completed_by: { email: annotatorexample.com } } // 方式 3通过 ID 指定 { result: [...], completed_by: 42 }系统会将该邮箱或 ID 匹配到组织内已有用户若配置允许则回退到导入者。该规则同时适用于通过 UI、API 或 SDK 导入的场景。企业版补充字段annotations.reviews注解审核详情数组、reviews.id审核 ID、reviews.created_by审核人的用户 ID、邮箱、姓名等字典信息、reviews.accepted布尔值表示审核人是否接受该注解。三、社区版通过 UI 与命令行导出通过 UI 导出在社区版Community Edition中按以下步骤导出数据与注解在项目中点击Export选择可用的导出格式点击Export导出数据。注意三点无论标签页上设置了什么过滤器导出结果始终包含已标注任务已取消cancelled的已标注任务也会包含在导出结果中若要对导出应用标签页过滤条件可改用 SDK 创建导出快照。社区版的导出超时问题社区版 UI 的导出是同步生成的作为请求的一部分执行。社区版为保持部署简单默认不运行后台导出 workerLabel Studio Enterprise 支持后台 worker 的异步快照导出更适合大规模项目。对于大型项目社区版导出耗时可能超过反向代理或 ingress 配置的超时时间通常约90 秒导致 502/504 错误或导出超时。遇到该限制时可选择以下替代方案使用 SDK 导出快照见 SDK 导出快照 API使用控制台命令在运行 Label Studio 的机器上直接使用下面的控制台命令导出项目在大规模场景下使用 UI 导出Label Studio Enterprise 在 UI 中提供后台快照导出见下文导出快照。从源码可以印证这一点同步导出 APIExportAPI.get()直接在同一请求内完成查询、序列化、转换与文件响应data_export/api.py而快照导出则通过ExportListAPI创建Export记录、由后台任务export_background()异步生成文件data_export/mixins.py。使用控制台命令导出label-studio export project-id export-format --export-pathoutput-path启用调试日志DEBUG1 LOG_LEVELDEBUG label-studio export project-id export-format --export-pathoutput-path该子命令由 core/argparser.py 注册支持project_id、export_format如 JSON、JSON_MIN、CSV 等与--export-path参数--export-serializer-context可用于传入序列化上下文默认值为{annotations__completed_by: {only_id: null}, interpolate_key_frames: true}。实际执行逻辑位于 tasks/functions.py 的export_project()先校验格式是否受支持再按每批 1000 个任务批量序列化最终调用DataExport.generate_export_file()生成文件并写入--export-path若为目录则追加生成的文件名。四、Easy Export API同步导出对于小型标注项目可直接调用导出端点同步导出注解。导出包含未标注任务在内的全部任务Label Studio 开源版默认只导出已标注任务。若想轻松导出包括未标注任务在内的全部任务可在调用 Easy Export API 时带上查询参数download_all_taskstrue。例如curl -X GET https://localhost:8080/api/projects/{id}/export?exportTypeJSONdownload_all_taskstrue对应的同步导出接口为 data_export/urls.py 中的project-exportExportAPI。从源码看ExportAPI.get()中only_finished not download_all_tasks当only_finished为真时会执行query.filter(annotations__isnullFalse).distinct()这正是默认只导出已标注任务的底层实现data_export/api.py。如果项目很大通常应改用快照导出以避免超时。快照默认包含所有任务包括未标注任务。五、使用快照 API 导出对于拥有数十万任务的的大型标注项目按以下三步操作向创建新导出文件/快照发起 POST 请求响应中会包含创建文件的id使用该id作为export_pk检查导出文件的状态仍以该id作为export_pk向下载导出文件发起 GET 请求完成下载。对应的 REST 路由在 data_export/urls.py 中定义POST /api/projects/{id}/exports/创建快照ExportListAPIGET /api/projects/{id}/exports/{export_pk}查看状态ExportDetailAPIGET /api/projects/{id}/exports/{export_pk}/download下载文件ExportDownloadAPI。快照模型Export维护了created / in_progress / failed / completed四种状态并通过FileField存储生成的文件、记录md5与counters元数据data_export/models.py。快照文件名默认由get_default_title()生成格式为PROJECT-NAME-at-YEAR-MM-DD-HH-MMUTC 时间。六、导出快照Snapshot异步导出企业版在 Label Studio Enterprise 中可以创建数据与注解的快照按需精确导出标注项目中想要的内容。这种延迟导出方式更适合从 UI 导出大型标注项目。在项目的 Label Studio UI 中点击Export点击Create New SnapshotApply filters from tab ...从下拉列表中选择Default可选Snapshot Name输入快照名称便于日后查找。默认快照命名为PROJECT-NAME-at-YEAR-MM-DD-HH-MM时间为 UTCInclude in the Snapshot…选择要包含的数据类型All tasks全部任务、Only annotated仅已标注或Only reviewed仅已审核Drafts选择导出完整草稿注解Complete drafts还是仅导出草稿注解的 IDOnly IDs仅标记存在草稿Predictions选择导出完整预测Complete predictions还是仅导出预测 IDOnly IDs仅标记任务存在预测Annotations启用要导出的注解类型可指定Annotations普通注解、Ground Truth与Skipped跳过的注解。默认只导出普通注解可选启用Remove user details移除用户详细信息点击Create a Snapshot开始导出在快照列表中可以看到可下载的快照以及其中包含的内容、创建时间与创建者信息点击Download并选择导出格式快照文件即下载到本地。从源码看快照导出支持丰富的过滤选项_get_filtered_tasks()支持按 tab 视图view、跳过skipped、完成finished与已标注annotated过滤任务data_export/mixins.py_get_filtered_annotations_queryset()支持按普通注解、Ground Truth、跳过的注解取并集过滤data_export/mixins.py序列化选项则控制草稿、预测、completed_by是否展开以及是否插值视频关键帧、是否下载资源data_export/mixins.py。七、受支持的导出格式Label Studio 支持多种通用与标准格式导出已完成的标注任务。如果缺少你需要的格式还可以为项目贡献一种。更多信息参见 Label Studio SDK 仓库中的 Converter 工具。格式支持的实际判定发生在 data_export/models.py 的DataExport.get_export_formats()它基于项目解析后的标签配置创建Converter将converter.supported_formats中不支持的格式标记为disabled在 UI 中置灰企业版启用自定义界面时还会额外加入DOCLANG格式。ASR_MANIFEST将自动语音识别的音频转写标签导出为 NVIDIA NeMo 模型期望的 JSON manifest 格式。适用于使用Audio标签配合TextArea标签的音频转写项目。{audio_filepath: /path/to/audio.wav, text: the transcription, offset: 301.75, duration: 0.82, utt: utterance_id, ctm_utt: en_4156, side: A}Brush labels to NumPy and PNG将画笔遮罩标签导出为 NumPy 二维数组与 PNG 图片。每个标签输出为一张图片。适用于使用BrushLabels标签的画笔标注图像项目。COCOCOCO 数据集常用的机器学习格式用于目标检测与图像分割任务。适用于使用BrushLabels、RectangleLabels、KeyPointLabels见下方说明或PolygonLabels标签的边界框与多边形图像标注项目。KeyPointLabels 导出支持如果使用KeyPointLabels需要在标注配置中添加以下内容至少一个RectangleLabels选项作为关键点的父边界框在KeyPointLabels内的每个Label上添加model_index该值定义输出数组中关键点坐标的顺序供 YOLO 使用。例如View Image nameimage value$image/ KeyPointLabels namekp toNameimage Label valuenose model_index0/ Label valueeye model_index1/ Label valuetail model_index2/ /KeyPointLabels RectangleLabels namebbox toNameimage Label valueanimal/ /RectangleLabels /View标注完成后必须在Regions面板中将每个关键点区域拖放到其对应的矩形区域下方从而通过parentID建立父子层级关系这是导出所必需的见上图与下方导出示例。导出示例Keypoints in JSON[ { id: 17n06ubOJs, type: keypointlabels, value: { x: 6.675567423230974, y: 20.597014925373134, width: 0.26702269692923897, keypointlabels: [nose] }, origin: manual, to_name: image, parentID: QHG4TBXuNC, from_name: kp, image_rotation: 0, original_width: 200, original_height: 179 }, { id: QHG4TBXuNC, type: rectanglelabels, value: { x: 3.871829105473965, y: 4.029850746268656, width: 94.39252336448598, height: 92.08955223880598, rotation: 0, rectanglelabels: [animal] }, origin: manual, to_name: image, from_name: bbox, image_rotation: 0, original_width: 200, original_height: 179 } ]Keypoints in COCO[ { id: 0, image_id: 0, category_id: 0, segmentation: [], bbox: [7.74365821094793, 7.213432835820895, 188.78504672897196, 164.84029850746268], ignore: 0, iscrowd: 0, area: 31119.38345654903 }, { id: 1, image_id: 0, category_id: 0, keypoints: [13, 37, 2, 33, 33, 2, 167, 24, 2], num_keypoints: 3, bbox: [13, 24, 154, 13], iscrowd: 0 } ]Keypoints in YOLO0 0.5106809078771696 0.5007462686567165 0.9439252336448598 0.9208955223880598 0.06675567423230974 0.20597014925373133 2 0.1628838451268358 0.18507462686567164 2 0.8371161548731643 0.13134328358208955 2CoNLL2003CoNLL-2003 命名实体识别挑战赛常用格式。适用于使用Text与Labels标签的文本标注项目。CSV结果以逗号分隔值存储列名由标注配置中from_name与to_name字段的值决定。支持所有项目类型。JSON以原始 JSON 格式存储在一个 JSON 文件中的条目列表。适合同时导出数据集的数据与注解。支持所有项目类型。JSON_MIN仅导出原始 JSON 格式中from_name、to_name值的条目列表。适合导出数据集的数据与注解且不包含 Label Studio 特有字段。支持所有项目类型。例如{ image: https://htx-pub.s3.us-east-1.amazonaws.com/examples/images/nick-owuor-astro-nic-visuals-wDifg5xc9Z4-unsplash.jpg, tag: [{ height: 10.458911419423693, rectanglelabels: [Moonwalker], rotation: 0, width: 12.4, x: 50.8, y: 5.869797225186766 }] }Pascal VOC XML用于目标检测与图像分割任务的流行 XML 格式。适用于使用RectangleLabels标签的边界框图像标注项目。spaCyLabel Studio 不支持直接导出为 spaCy 二进制格式但可以将导出的注解转换为与 spaCy 兼容的格式。进行此转换前必须安装 spacy Python 包。转换步骤先将注解导出为 CONLL2003 格式打开下载的文件在第一行添加O-DOCSTART- -X- O O在命令行运行spacy convert将 CoNLL 格式注解转换为 spaCy 二进制格式将/path/to/filename替换为注解文件的路径与文件名spaCy 2.xspacy convert /path/to/filename.conll -c nerspaCy 3.xspacy convert /path/to/filename.conll -c conll .更多信息参见 spaCy 文档中关于 Converting existing corpora and annotations 运行spacy convert的说明。TSV结果存储在制表符分隔的表格文件中列名由标注配置中的from_name与to_name值决定。支持所有项目类型。YOLO以 YOLOv3 与 YOLOv4 格式导出目标检测注解。适用于使用RectangleLabels与KeyPointLabels标签的目标检测项目。如果使用 KeyPointLabels请参见 COCO 小节下的说明。八、图像注解单位换算图像注解中x, y, width, height的单位是占整体图像尺寸的百分比。使用以下换算公式pixel_x x / 100.0 * original_width pixel_y y / 100.0 * original_height pixel_width width / 100.0 * original_width pixel_height height / 100.0 * original_height完整示例含双向换算task { annotations: [{ result: [ { ...: ..., original_width: 600, original_height: 403, image_rotation: 0, value: { x: 5.33, y: 23.57, width: 29.16, height: 31.26, rotation: 0, rectanglelabels: [Airplane] } } ] }] } # 从 LS 百分比单位转换为像素 def convert_from_ls(result): if original_width not in result or original_height not in result: return None value result[value] w, h result[original_width], result[original_height] if all([key in value for key in [x, y, width, height]]): return w * value[x] / 100.0, \ h * value[y] / 100.0, \ w * value[width] / 100.0, \ h * value[height] / 100.0 # 从像素转换为 LS 百分比单位 def convert_to_ls(x, y, width, height, original_width, original_height): return x / original_width * 100.0, y / original_height * 100.0, \ width / original_width * 100.0, height / original_height * 100 # 从 LS 转换 output convert_from_ls(task[annotations][0][result][0]) if output is None: raise Exception(Wrong convert) pixel_x, pixel_y, pixel_width, pixel_height output print(pixel_x, pixel_y, pixel_width, pixel_height) # 转换回 LS x, y, width, height convert_to_ls(pixel_x, pixel_y, pixel_width, pixel_height, 600, 403) print(x, y, width, height)注意只有当 result 中包含original_width与original_height时才能完成换算因此请确保这些字段存在于导出的 JSON 中。九、手动将 JSON 注解转换为其他格式可以通过命令行或 Python在已完成 JSON 注解的目录或文件上运行 Label Studio converter 工具将 Label Studio JSON 格式的注解转换为其他格式。如果使用早于 1.0.0 的 Label Studio 版本这是将 Label Studio JSON 注解转换为其他标注格式的唯一方式。在仓库中Converter 正是同步/快照导出链路里实际执行格式转换的组件DataExport.generate_export_file()通过Converter(configproject.get_parsed_config(), ...)加载项目标签配置在临时目录中调用converter.convert(input_json, tmp_dir, output_format, is_dirFalse)完成转换data_export/models.py。十、在 Label Studio 之外访问任务数据供 ML 后端使用机器学习后端需要使用任务中的数据生成预测因此需要在 ML 后端侧下载这些资源。Label Studio 提供了下载工具位于label-studio-toolsPython 包中。如果使用官方 Label Studio Machine Learning 后端label-studio-tools会随其他依赖自动安装。从 Label Studio 实例访问任务数据Label Studio 中存储任务资源图像、音频、文本等的方式有以下几种云存储Cloud storages外部网页链接External web links上传的文件Uploaded files本地文件目录Local files directoryLabel Studio 以上传文件时按项目级别组织目录结构每个项目拥有独立的文件文件夹。可以使用label_studio_tools.core.utils.io.get_local_path获取任务数据——它会将任务数据中的路径或 URL 转换为本地路径。对于本地路径会返回完整本地路径使用download_resources参数时会下载资源。访问外部资源时需要提供Hostname与access_token。在 Label Studio 实例之外访问任务数据同样可以使用label_studio_tools.core.utils.io.get_local_path方法从外部机器获取外部链接与云存储中的数据。重要不要忘记提供凭证credentials。如果在外部机器上挂载了相同的磁盘也可以直接使用get_local_path获取数据。另一种访问方式是利用任务中的链接与 ACCESS_TOKEN参见认证文档拼接 Label Studio 主机名与任务数据中的链接然后在请求中加入访问令牌curl -X GET http://localhost:8080/api/projects/ -H Authorization: Token {YOUR_TOKEN}十一、常见问题FAQ问题 1请求返回了以下 API 响应没有提供任何数据No data was provided返回了 404 或 403 错误码。解答首先检查发送 API 请求时与 Label Studio 实例之间的网络连通性。可以使用示例数据执行测试 curl 请求来验证。问题 2访问文件时收到FileNotFound错误解答确认已挂载与 Label Studio 实例相同的磁盘并先在 Label Studio 实例中确认文件存在检查 Label Studio 实例中的LOCAL_FILES_DOCUMENT_ROOT环境变量并在访问数据的脚本中添加该变量。问题 3如何修改 COCO 与 YOLO 导出中类别的顺序标签默认按字母顺序排序。如需修改请在Label中添加category属性来改变行为。例如Label valueabc category1 / Label valuedef category2 /十二、延伸阅读云存储配置目标存储同步与云存储桶中的task_id.json文件API 参考认证方式与导出相关端点的完整说明访问令牌ML 后端与外部脚本访问任务数据所需的认证任务格式输入任务的 JSON 格式标注界面与标签文档各控制标签与对象标签的from_name/to_name语义SDK 导出快照 API以编程方式创建、查询与下载快照【免费下载链接】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），仅供参考