Label Studio DataManager API 深度解析

概述

Label Studio 是一个开源的标注工具，而 DataManager 是其核心组件之一，负责管理标注任务的数据流和界面展示。本文将深入解析 DataManager 的 API 接口，帮助开发者更好地理解和使用这套接口系统。

API 基础特性

DataManager API 具有以下核心特点：

1. JSON 数据格式：所有请求参数和响应数据均采用 JSON 格式
2. RESTful 风格：遵循标准的 REST 设计原则
3. 分层结构：API 按照项目(project)、标签页(tab)、任务(task)等层级组织

核心接口详解

1. 项目管理接口

/project

• GET：获取当前项目的基本信息
• 这是获取项目元数据的入口点，通常用于初始化数据管理界面

/project/columns

• GET：获取数据集列定义
• 返回数据结构包含列ID、类型、标题等元信息
• 支持嵌套列结构，通过parent和children字段表示

2. 标签页管理接口

/project/tabs

• GET：获取所有标签页信息
• 每个标签页代表数据集的一个特定视图

/project/tabs/:tabID

• POST：创建或更新标签页
• DELETE：删除指定标签页
• 标签页可以保存特定的过滤条件、排序规则等视图状态

3. 任务数据接口

/project/tabs/:tabID/tasks

• GET：获取分页任务数据
• 支持分页参数(page, page_size)
• 可按标签页定义的过滤条件和排序规则返回数据
• 响应中包含任务列表及各种统计信息

/tasks/:taskID

• GET：获取单个任务的详细信息
• 包含任务数据、标注统计等完整信息

/project/next

• GET：根据采样设置获取下一个待标注任务
• 常用于标注工作流的任务分配

4. 标注管理接口

/tasks/:taskID/annotations

• GET：获取任务的标注列表
• POST：创建新标注(支持标记为跳过)
• 标注数据遵循Label Studio的标准格式

/tasks/:taskID/annotations/:id

• GET/POST/DELETE：标注的CRUD操作
• 支持将已有标注标记为"跳过"状态

5. 选择项管理接口

/project/tabs/:tabID/selected-items

• POST/PATCH/DELETE：管理选中项集合
• 支持三种选择模式：
  • 明确指定选中项(included)
  • 全选后排除特定项(all + excluded)
  • 完全全选(all)

6. 操作管理接口

/project/actions

• GET：获取可用操作列表
• 每个操作包含ID、标题、顺序等信息
• 可配置确认对话框

/project/tabs/:tabID/actions

• POST：执行指定操作
• 操作可以应用于单个任务、选中任务或整个标签页

数据类型详解

1. 标签页(Tab)结构

{
  "id": 1,
  "type": "list",
  "title": "待标注任务",
  "target": "tasks",
  "filters": {...},
  "ordering": [...],
  "selectedItems": {...},
  "columnsDisplayType": {...},
  "columnsWidth": {...},
  "hiddenColumns": {...}
}

2. 过滤器(Filter)结构

{
  "conjunction": "and",
  "items": [
    {
      "filter": "filter:tasks:data.image",
      "type": "String",
      "operator": "contains",
      "value": "cat"
    }
  ]
}

3. 列定义(Column)结构

{
  "id": "image",
  "parent": "data",
  "target": "tasks",
  "title": "图片URL",
  "type": "Image",
  "children": null,
  "visibility_defaults": {
    "explore": true,
    "labeling": false
  }
}

4. 任务(Task)结构

{
  "id": 123,
  "cancelled_annotations": 0,
  "completed_at": "2023-01-01T00:00:00Z",
  "total_annotations": 1,
  "total_predictions": 0,
  "data": {
    "image": "https://example.com/cat.jpg"
  },
  "extra": {
    "source": "upload"
  }
}

最佳实践

1. 高效获取数据：

   • 使用/project/tabs/:tabID/tasks接口的分页参数避免一次性加载过多数据
   • 合理设置page_size平衡性能与用户体验

2. 复杂筛选：

   • 利用Filter的conjunction和嵌套条件构建复杂查询
   • 注意不同列类型的可用运算符差异

3. 批量操作：

   • 使用SelectedItems的"全选+排除"模式处理大规模选择
   • 结合Actions接口实现批量操作

4. 性能优化：

   • 对于大型项目，考虑将常用视图保存为标签页
   • 合理设置columnsWidth和hiddenColumns优化渲染性能

总结

DataManager API 提供了Label Studio数据管理的完整能力，从基础数据获取到复杂筛选操作，支持各种标注场景的需求。理解这些API的结构和使用方式，可以帮助开发者更好地定制和扩展Label Studio的功能。