Label Studio如何导入JSON格式标注数据？

Question

在使用Label Studio进行数据标注时，如何正确导入JSON格式的标注数据是一个常见问题。许多用户在尝试将预标注或历史标注数据通过JSON文件导入时，发现数据未正确显示或标签丢失。这通常源于JSON结构不符合Label Studio预期的格式：需包含"tasks"字段，每个任务应有"data"和可选的"predictions"/"annotations"字段，且嵌套结构需与配置的标签模板一致。此外，字段名称映射错误、缺少唯一ID或使用了不兼容的数据类型也会导致导入失败。如何确保JSON数据结构与Label Studio项目配置完全匹配，是成功导入的关键所在。

Answer 1

如何正确导入JSON格式的标注数据到Label Studio

1. 基础概念：理解Label Studio的数据结构模型

Label Studio采用特定的JSON结构来表示标注任务，其核心是tasks数组，每个元素代表一个待标注或已标注的任务项。最基础的结构如下：

[
  {
    "id": 1,
    "data": {
      "text": "这是一个示例文本"
    },
    "annotations": [
      {
        "result": [
          {
            "value": { "labels": ["正面"] },
            "from_name": "label",
            "to_name": "text",
            "type": "labels"
          }
        ]
      }
    ]
  }
]

其中，data字段必须与项目中配置的from_name和to_name相对应；否则标签无法映射。

2. 深入解析：JSON结构的关键字段说明

字段名	是否必需	说明
id	推荐	唯一标识符，便于追踪和去重
data	必需	包含原始输入数据（如文本、图像URL等）
predictions	可选	用于预标注结果，通常来自模型预测
annotations	可选	人工标注结果，支持多轮标注

3. 映射一致性：确保JSON与Labeling Template匹配

Label Studio使用XML定义界面模板，例如：

<View>
  <Text name="text" value="$text"/>
  <Choices name="label" toName="text">
    <Choice value="正面"/>
    <Choice value="负面"/>
  </Choices>
</View>

对应的JSON中，from_name必须为"label"，to_name必须为"text"，否则即使结构完整也无法显示标签。

4. 常见错误类型及诊断方法

• 字段名拼写错误，如"data"写成"Data"
• 缺少tasks根节点，直接上传数组而非对象
• result中value结构不合规，如遗漏labels数组
• ID重复或缺失，导致系统无法识别任务
• 使用了非字符串类型的值（如布尔型、数字）作为标签内容
• 嵌套层级错误，如将annotations置于data内部
• 时间戳格式不符合ISO标准（影响版本控制）
• 未设置ground_truth标记高质量标注
• 预标注未使用predictions而误用annotations
• 字符编码问题（如含BOM的UTF-8文件）

5. 解决方案流程图

graph TD
            A[准备原始JSON数据] --> B{是否包含tasks?}
            B -- 否 --> C[封装为{ tasks: [...] }]
            B -- 是 --> D[检查每个task的id唯一性]
            D --> E[验证data字段与模板变量一致]
            E --> F[确认from_name/to_name映射正确]
            F --> G{存在标注数据?}
            G -- 是 --> H[放入annotations或predictions]
            G -- 否 --> I[仅保留data]
            H --> J[校验result结构合规性]
            J --> K[导出为UTF-8无BOM格式]
            K --> L[通过UI或API导入Label Studio]

6. 实战建议：构建自动化校验脚本

以下Python代码可用于验证JSON结构：

import json

def validate_ls_json(file_path, template_mapping):
    with open(file_path, 'r', encoding='utf-8') as f:
        data = json.load(f)
    
    assert isinstance(data, list), "顶层必须是tasks数组"
    seen_ids = set()
    
    for task in data:
        assert 'id' in task, "每个task需有id"
        assert task['id'] not in seen_ids, f"ID重复: {task['id']}"
        seen_ids.add(task['id'])
        
        assert 'data' in task, "缺少data字段"
        for key in task['data']:
            assert key in template_mapping['inputs'], f"未知输入字段: {key}"

        if 'annotations' in task:
            for ann in task['annotations']:
                for res in ann['result']:
                    assert res['from_name'] in template_mapping['outputs'], "from_name不匹配"
    print("✅ 所有校验通过")

7. 高级技巧：利用API进行批量导入与调试

使用Label Studio REST API可实现程序化导入：

curl -H "Authorization: Token abc123" \
     -X POST http://localhost:8080/api/projects/1/import \
     -F "file=@tasks.json"

结合日志输出，可快速定位解析失败的具体任务索引。

8. 数据迁移策略：从其他平台转换至Label Studio

当从CVAT、Prodigy或其他工具迁移时，应建立字段映射表：

源系统	目标 (Label Studio)	转换逻辑
Prodi.g's 'spans'	result[].value.start/end	提取偏移量并转为绝对位置
CVAT box coordinates	result[].value.x/y/width/height	归一化至百分比坐标
Spacy Doc.cats	predictions.result.value.labels	包装为choices类型结果