TBC/api_docs/dataset_annotation_finetune_api.md

46 KiB
Raw Permalink Blame History

视觉感知工作台 · CV 数据集标注与微调 BFF API

与代码对齐: internal/platform/cv/handler/dataset_handler.go、internal/platform/cv/dto/dataset.go、internal/platform/cv/service/dataset/annotation.go、internal/platform/cv/service/dataset/finetune.go、internal/platform/cv/client/dataset/types.go
更新日期: 2026-06-09

1. 范围

项 说明
路径前缀 {SERVER_CONTEXT_PATH}/cv/v1/dataset,默认 /roboticsBffApi/cv/v1/dataset
接口数量 11 (标注 6 + 微调 5)
下游 dataset-core v1/v2; 标注模型列表额外调用 d-cloud SKU 资源
响应格式 status / message / data (pkg/response/v1.go,v1 envelope)
ID 映射 BFF 对外使用 collection_id + version_id; 调用 dataset-core 前解析为 dataset_id

与 docs/dataset_api.md 中 12 个集合/版本/样本/导出接口互补; 该文档标注与微调为 Out of Scope, 以本文为准.


2. 公共约定

2.1 Headers

Header 必填 说明
Authorization 是 Bearer <d-cloud token>
x-request-id 是 缺失时中间件返回 40000
Content-Type POST 建议 application/json

鉴权后 BFF 从 d-cloud 注入用户上下文, 调用 dataset-core 时附带 d-user-id、org-symbol、sourceapp.

2.2 成功 Envelope

{
  "status": 0,
  "message": "success",
  "data": {}
}

2.3 错误 Envelope

{
  "status": 40000,
  "message": "invalid request body"
}
status HTTP 含义
0 200 成功
40000 400 请求参数非法、业务校验失败
40100 401 未授权
40400 404 资源不存在
40900 409 冲突
50200 502 下游 dataset-core 不可用或异常
50000 500 BFF 内部错误

3. 接口总览

分类 方法 路径
标注 POST /annotation/manual-annotation
标注 GET /annotation/get-annotation
标注 POST /annotation/auto-annotation
标注 POST /annotation/create-ground-truth
标注 GET /annotation/get-annotation-model-list
标注 POST /annotation/label-split
微调 POST /finetune/list
微调 POST /finetune/create
微调 POST /finetune/task/test
微调 GET /finetune/:task_id
微调 DELETE /finetune/:task_id

完整 URL 示例: POST /roboticsBffApi/cv/v1/dataset/annotation/manual-annotation


4. 标注接口

4.1 POST /annotation/manual-annotation

手动保存样本标注. 下游: dataset-core v2.

请求体 ManualAnnotationRequest

字段 类型 必填 说明
collection_id string 是 BFF 数据集集合 ID
version_id string 是 BFF 版本 ID
sample_id uint64 是 样本 ID
annotations object 是 标注 JSON, 结构由任务类型决定, passthrough 至 core

请求示例

{
  "collection_id": "dc_abc123",
  "version_id": "dv_xyz789",
  "sample_id": 1001,
  "annotations": {
    "objectdetection": [
      {
        "label": "cat",
        "boxes": [{ "x": 1, "y": 2, "width": 3, "height": 4 }]
      }
    ],
    "semanticsegmentation": [
      {
        "label": "cat",
        "boxes": [
          { "x": 0, "y": 0 },
          { "x": 10, "y": 0 },
          { "x": 10, "y": 10 }
        ]
      }
    ],
    "keypoints": [
      {
        "label": "person",
        "bbox": { "x": 120.5, "y": 80.0, "width": 200, "height": 350 },
        "keypoints": [
          { "x": 180.0, "y": 110.5, "visible": 2, "name": "nose" },
          { "x": 175.0, "y": 130.0, "visible": 1, "name": "" }
        ]
      }
    ]
  }
}

响应 data

字段 类型 说明
sample_id uint64 已标注样本 ID

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "sample_id": 1001
  }
}

4.2 GET /annotation/get-annotation

获取单个样本的标注详情. 下游: dataset-core v2.

Query

参数 必填 说明
collection_id 是 BFF 数据集集合 ID
version_id 是 BFF 版本 ID
sample_id 是 样本 ID (正整数)

请求示例

GET /roboticsBffApi/cv/v1/dataset/annotation/get-annotation?collection_id=dc_abc123&version_id=dv_xyz789&sample_id=1001

响应 data

字段 类型 说明
id uint64 样本 ID
name string 文件名
type string 样本类型
path string 存储路径
is_labeled bool 行级是否已标注
status string 样本状态
labels string[] 标签列表
annotations object / array 标注内容 JSON, 结构随数据集 task_type 变化, 见下表

annotations 结构说明

annotations 为 passthrough 字段, 实际内容取决于数据集任务类型. 单任务数据集通常只包含对应键; 多任务视觉集可同时包含多个键.

目标检测 / 语义分割 / 关键点 (objectdetection、semanticsegmentation、keypoints)

多任务视觉集示例 (同一 annotations 对象内可并存多个任务键):

{
  "objectdetection": [
    {
      "label": "cat",
      "boxes": [{ "x": 1, "y": 2, "width": 3, "height": 4 }]
    }
  ],
  "semanticsegmentation": [
    {
      "label": "cat",
      "boxes": [
        { "x": 0, "y": 0 },
        { "x": 10, "y": 0 },
        { "x": 10, "y": 10 }
      ]
    }
  ],
  "keypoints": [
    {
      "label": "person",
      "bbox": { "x": 120.5, "y": 80.0, "width": 200, "height": 350 },
      "keypoints": [
        { "x": 180.0, "y": 110.5, "visible": 2, "name": "nose" },
        { "x": 175.0, "y": 130.0, "visible": 1, "name": "" }
      ]
    }
  ]
}
任务键 元素字段 说明
objectdetection label, boxes[] boxes 为矩形框, 含 x、y、width、height
semanticsegmentation label, boxes[] boxes 为多边形顶点, 每项含 x、y
keypoints label, bbox, keypoints[] bbox 为人体/目标外接矩形, 含 x、y、width、height; keypoints[] 每项含 x、y、visible、name

keypoints[] 内字段补充说明:

字段 类型 说明
visible int 可见性, 取值为 0、1、2 (COCO 约定): 0 未标注, 1 已标注但遮挡/不可见, 2 已标注且可见
name string 关键点名称, 可为空字符串

关键点 (keypoints) 单任务示例:

{
  "keypoints": [
    {
      "label": "person",
      "bbox": { "x": 120.5, "y": 80.0, "width": 200, "height": 350 },
      "keypoints": [
        { "x": 180.0, "y": 110.5, "visible": 2, "name": "nose" },
        { "x": 175.0, "y": 130.0, "visible": 1, "name": "" }
      ]
    }
  ]
}

深度估计 (depthestimation)

annotations 为对象, 存放右目图与视差图相对路径:

{
  "right": "org_symbol/datasets/ds_xxx/samples/right/img_001.jpg",
  "disparity": "org_symbol/datasets/ds_xxx/samples/disparity/img_001.png"
}

图像分类 (imageclassification)

annotations 为标签字符串数组:

["cat", "dog"]

响应示例 (目标检测单任务)

{
  "status": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "name": "img.jpg",
    "type": "image",
    "path": "/dataSpace/org/sample/img.jpg",
    "is_labeled": true,
    "status": "ready",
    "labels": ["cat", "dog"],
    "annotations": {
      "objectdetection": [
        {
          "label": "cat",
          "boxes": [{ "x": 1, "y": 2, "width": 3, "height": 4 }]
        }
      ]
    }
  }
}

4.3 POST /annotation/auto-annotation

提交自动标注任务. 下游: dataset-core v1.

请求体 AutoAnnotationRequest

字段 类型 必填 说明
collection_id string 是 BFF 数据集集合 ID
version_id string 是 BFF 版本 ID
task_types string[] 是 任务类型列表, 如 object_detection、image_classification
objectdetection_models LabelModel[] 否 目标检测模型列表
imageclassification_model LabelModel 否 图像分类模型
semanticsegmentation_model LabelModel 否 语义分割模型; 检测+分割且已选 DINO-X-1.0 时可省略 (见 §7.1)
depthestimation_model LabelModel 否 深度估计模型
label_all bool 否 true 标注数据集所有样本; false 仅标注未标注样本 (默认建议 false)

模型选择与 DINO-X-1.0 多任务复用规则见 §7.1.

LabelModel

字段 类型 说明
sku_id string SKU ID
sku_name string 模型名称
private_id uint 私有模型 ID (dataset-core 侧)
labels string[] 标签列表

请求示例

{
  "collection_id": "dc_abc123",
  "version_id": "dv_xyz789",
  "task_types": ["objectdetection", "imageclassification"],
  "objectdetection_models": [
    {
      "sku_id": "30bcf36e-a129-48f9-b9d8-9ba808702d6e",
      "sku_name": "yolo-v8",
      "private_id": 12,
      "labels": ["cat", "dog"]
    }
  ],
  "imageclassification_model": {
    "sku_id": "sku-uuid-001",
    "sku_name": "resnet50",
    "private_id": 0,
    "labels": ["cat", "dog"]
  },
  "label_all": false
}

响应 data

字段 类型 说明
task_id string 自动标注异步任务 ID

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "task_id": "task-auto-001"
  }
}

4.4 POST /annotation/create-ground-truth

为样本创建 Ground Truth. 下游: dataset-core v1.

请求体 CreateGroundTruthRequest

字段 类型 必填 说明
collection_id string 是 BFF 数据集集合 ID
version_id string 是 BFF 版本 ID
sample_id uint64 是 样本 ID

请求示例

{
  "collection_id": "dc_abc123",
  "version_id": "dv_xyz789",
  "sample_id": 1001
}

响应示例

{
  "status": 0,
  "message": "success",
  "data": {}
}

4.5 GET /annotation/get-annotation-model-list

获取可用于自动标注的模型列表. BFF 已聚合 d-cloud SKU 资源与 dataset-core 私有模型, 前端直接消费 data.models 即可, 无需再自行调用 resource 服务拼接 (详见 §7.1).

BFF 内部逻辑

  • 基础列表来自 d-cloud SKU 资源 (resource.SkuList, 按 task_type 映射后的 SKU 类型过滤).
  • 当 task_type=object_detection 时, 额外合并 dataset-core 返回的私有检测模型 (微调产物).

Query

参数 必填 说明
task_type 否 BFF 任务类型, 如 object_detection、image_classification、semantic_segmentation、stereo_depth; 关键点检测场景也传 object_detection (见 §7.1)

请求示例

GET /roboticsBffApi/cv/v1/dataset/annotation/get-annotation-model-list?task_type=object_detection

响应 data

字段 类型 说明
models LabelModel[] 模型列表

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "models": [
      {
        "sku_id": "sku-uuid-001",
        "sku_name": "yolo-v8",
        "private_id": 0,
        "labels": []
      },
      {
        "sku_id": "30bcf36e-a129-48f9-b9d8-9ba808702d6e",
        "sku_name": "custom-detector",
        "private_id": 12,
        "labels": ["cat", "dog", "person"]
      }
    ]
  }
}

4.6 POST /annotation/label-split

将文本拆分为标签列表 (如逗号分隔的自然语言). 下游: dataset-core v1.

请求体 LabelSplitRequest

字段 类型 必填 说明
text string 是 待拆分文本
model string 否 可选 LLM 模型名

请求示例

{
  "text": "cat, dog, person",
  "model": "gpt-4"
}

响应 data

字段 类型 说明
labels string[] 拆分后的标签

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "labels": ["cat", "dog", "person"]
  }
}

5. 微调接口

5.1 POST /finetune/list

分页查询微调任务列表. 下游: dataset-core v2.

请求体 ListFinetuneRequest

字段 类型 必填 说明
page int 否 页码
page_size int 否 页大小
name string 否 任务名称过滤

请求示例

{
  "page": 1,
  "page_size": 20,
  "name": "my-finetune"
}

响应 data

字段 类型 说明
list FinetuneTaskInfo[] 任务列表
total int64 总数
page int 当前页
size int 页大小

FinetuneTaskInfo

字段 类型 说明
id uint 任务 ID (dataset-core 主键, 用于详情/删除路径参数)
task_id string IDEA 训练平台任务 ID (外部 UUID, 推理测试等下游调用使用)
name string 任务名称
model_name string 基础模型名
status string 任务状态, 如 waiting、running、succeeded
labels string[] 标签
created int IDEA 任务创建时间 (Unix 秒级时间戳)
start_time int 训练开始时间 (Unix 秒级时间戳; 未开始时为 0)
finish_time int 训练结束时间 (Unix 秒级时间戳; 未完成时为 0)
train_images_num int 训练集图片数量
evaluate_images_num int 评估集图片数量
evaluate_result object 评估结果; 任务 status=succeeded 时有值, 结构见下
embedding_url string 嵌入/产物 URL (可选)
created_at string BFF 记录创建时间 (RFC3339)

evaluate_result 结构

下游 passthrough 字段. 任务评估完成后返回, 主要字段如下:

字段 类型 说明
categorys array 按类别评估结果列表
categorys[].name string 类别名称
categorys[].anno string 标注信息 (可为空)
categorys[].image string 关联图片 (可为空)
categorys[].ap0_5 number 该类别 AP@0.5
categorys[].ap0_95 number 该类别 AP@0.95
categorys[].precision_recall_score number[][] PR 曲线点位, 每项为 [precision, recall, score]
m_ap0_5 number 全类别 mAP@0.5
m_ap0_95 number 全类别 mAP@0.95
recall_09precision number recall@0.9 precision

evaluate_result 示例

{
  "categorys": [
    {
      "anno": "",
      "ap0_5": 0.19999999999999996,
      "ap0_95": 0.20000000000000004,
      "image": "",
      "name": "pomegranate",
      "precision_recall_score": [
        [
          0.2,
          0,
          0.1470237374305725
        ],
        [
          0.2,
          0.01,
          0.07550938427448273
        ],
        [
          0.2,
          0.02,
          0.07550938427448273
        ],
        [
          0.2,
          0.03,
          0.07550938427448273
        ],
        [
          0.2,
          0.04,
          0.07550938427448273
        ],
        [
          0.2,
          0.05,
          0.07550938427448273
        ],
        [
          0.2,
          0.06,
          0.07550938427448273
        ],
        [
          0.2,
          0.07,
          0.07550938427448273
        ],
        [
          0.2,
          0.08,
          0.07550938427448273
        ],
        [
          0.2,
          0.09,
          0.07550938427448273
        ],
        [
          0.2,
          0.1,
          0.07550938427448273
        ],
        [
          0.2,
          0.11,
          0.07550938427448273
        ],
        [
          0.2,
          0.12,
          0.07550938427448273
        ],
        [
          0.2,
          0.13,
          0.07550938427448273
        ],
        [
          0.2,
          0.14,
          0.07550938427448273
        ],
        [
          0.2,
          0.15,
          0.07550938427448273
        ],
        [
          0.2,
          0.16,
          0.07550938427448273
        ],
        [
          0.2,
          0.17,
          0.07550938427448273
        ],
        [
          0.2,
          0.18,
          0.07550938427448273
        ],
        [
          0.2,
          0.19,
          0.07550938427448273
        ],
        [
          0.2,
          0.2,
          0.07550938427448273
        ],
        [
          0.2,
          0.21,
          0.07550938427448273
        ],
        [
          0.2,
          0.22,
          0.07550938427448273
        ],
        [
          0.2,
          0.23,
          0.07550938427448273
        ],
        [
          0.2,
          0.24,
          0.07550938427448273
        ],
        [
          0.2,
          0.25,
          0.07550938427448273
        ],
        [
          0.2,
          0.26,
          0.07550938427448273
        ],
        [
          0.2,
          0.27,
          0.07550938427448273
        ],
        [
          0.2,
          0.28,
          0.07550938427448273
        ],
        [
          0.2,
          0.29,
          0.07550938427448273
        ],
        [
          0.2,
          0.3,
          0.07550938427448273
        ],
        [
          0.2,
          0.31,
          0.07550938427448273
        ],
        [
          0.2,
          0.32,
          0.07550938427448273
        ],
        [
          0.2,
          0.33,
          0.07550938427448273
        ],
        [
          0.2,
          0.34,
          0.07550938427448273
        ],
        [
          0.2,
          0.35,
          0.07550938427448273
        ],
        [
          0.2,
          0.36,
          0.07550938427448273
        ],
        [
          0.2,
          0.37,
          0.07550938427448273
        ],
        [
          0.2,
          0.38,
          0.07550938427448273
        ],
        [
          0.2,
          0.39,
          0.07550938427448273
        ],
        [
          0.2,
          0.4,
          0.07550938427448273
        ],
        [
          0.2,
          0.41,
          0.07550938427448273
        ],
        [
          0.2,
          0.42,
          0.07550938427448273
        ],
        [
          0.2,
          0.43,
          0.07550938427448273
        ],
        [
          0.2,
          0.44,
          0.07550938427448273
        ],
        [
          0.2,
          0.45,
          0.07550938427448273
        ],
        [
          0.2,
          0.46,
          0.07550938427448273
        ],
        [
          0.2,
          0.47,
          0.07550938427448273
        ],
        [
          0.2,
          0.48,
          0.07550938427448273
        ],
        [
          0.2,
          0.49,
          0.07550938427448273
        ],
        [
          0.2,
          0.5,
          0.07550938427448273
        ],
        [
          0.2,
          0.51,
          0.07550938427448273
        ],
        [
          0.2,
          0.52,
          0.07550938427448273
        ],
        [
          0.2,
          0.53,
          0.07550938427448273
        ],
        [
          0.2,
          0.54,
          0.07550938427448273
        ],
        [
          0.2,
          0.55,
          0.07550938427448273
        ],
        [
          0.2,
          0.56,
          0.07550938427448273
        ],
        [
          0.2,
          0.57,
          0.07550938427448273
        ],
        [
          0.2,
          0.58,
          0.07550938427448273
        ],
        [
          0.2,
          0.59,
          0.07550938427448273
        ],
        [
          0.2,
          0.6,
          0.07550938427448273
        ],
        [
          0.2,
          0.61,
          0.07550938427448273
        ],
        [
          0.2,
          0.62,
          0.07550938427448273
        ],
        [
          0.2,
          0.63,
          0.07550938427448273
        ],
        [
          0.2,
          0.64,
          0.07550938427448273
        ],
        [
          0.2,
          0.65,
          0.07550938427448273
        ],
        [
          0.2,
          0.66,
          0.07550938427448273
        ],
        [
          0.2,
          0.67,
          0.07550938427448273
        ],
        [
          0.2,
          0.68,
          0.07550938427448273
        ],
        [
          0.2,
          0.69,
          0.07550938427448273
        ],
        [
          0.2,
          0.7,
          0.07550938427448273
        ],
        [
          0.2,
          0.71,
          0.07550938427448273
        ],
        [
          0.2,
          0.72,
          0.07550938427448273
        ],
        [
          0.2,
          0.73,
          0.07550938427448273
        ],
        [
          0.2,
          0.74,
          0.07550938427448273
        ],
        [
          0.2,
          0.75,
          0.07550938427448273
        ],
        [
          0.2,
          0.76,
          0.07550938427448273
        ],
        [
          0.2,
          0.77,
          0.07550938427448273
        ],
        [
          0.2,
          0.78,
          0.07550938427448273
        ],
        [
          0.2,
          0.79,
          0.07550938427448273
        ],
        [
          0.2,
          0.8,
          0.07550938427448273
        ],
        [
          0.2,
          0.81,
          0.07550938427448273
        ],
        [
          0.2,
          0.82,
          0.07550938427448273
        ],
        [
          0.2,
          0.83,
          0.07550938427448273
        ],
        [
          0.2,
          0.84,
          0.07550938427448273
        ],
        [
          0.2,
          0.85,
          0.07550938427448273
        ],
        [
          0.2,
          0.86,
          0.07550938427448273
        ],
        [
          0.2,
          0.87,
          0.07550938427448273
        ],
        [
          0.2,
          0.88,
          0.07550938427448273
        ],
        [
          0.2,
          0.89,
          0.07550938427448273
        ],
        [
          0.2,
          0.9,
          0.07550938427448273
        ],
        [
          0.2,
          0.91,
          0.07550938427448273
        ],
        [
          0.2,
          0.92,
          0.07550938427448273
        ],
        [
          0.2,
          0.93,
          0.07550938427448273
        ],
        [
          0.2,
          0.94,
          0.07550938427448273
        ],
        [
          0.2,
          0.95,
          0.07550938427448273
        ],
        [
          0.2,
          0.96,
          0.07550938427448273
        ],
        [
          0.2,
          0.97,
          0.07550938427448273
        ],
        [
          0.2,
          0.98,
          0.07550938427448273
        ],
        [
          0.2,
          0.99,
          0.07550938427448273
        ],
        [
          0.2,
          1.0,
          0.07550938427448273
        ]
      ]
    }
  ],
  "m_ap0_5": 0.13155940594059404,
  "m_ap0_95": 0.12840346534653468,
  "recall_09precision": 0
}

precision_recall_score 共 101 个点位 (recall 从 0 到 1, 步长 0.01). 列表/详情响应中 evaluate_result 结构与此一致.

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 7,
        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "my-finetune-1",
        "model_name": "DINO-X-1.0",
        "status": "succeeded",
        "labels": ["pomegranate"],
        "created": 1717819200,
        "start_time": 1717819300,
        "finish_time": 1717822800,
        "train_images_num": 80,
        "evaluate_images_num": 20,
        "evaluate_result": {
          "categorys": [
            {
              "anno": "",
              "ap0_5": 0.19999999999999996,
              "ap0_95": 0.20000000000000004,
              "image": "",
              "name": "pomegranate",
              "precision_recall_score": [
                [0.2, 0, 0.1470237374305725],
                [0.2, 0.01, 0.07550938427448273],
                [0.2, 1, 0.07550938427448273]
              ]
            }
          ],
          "m_ap0_5": 0.13155940594059404,
          "m_ap0_95": 0.12840346534653468,
          "recall_09precision": 0
        },
        "embedding_url": "",
        "created_at": "2026-06-08T10:00:00+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

5.2 POST /finetune/create

创建微调任务. 下游: dataset-core v2.

请求体 CreateFinetuneRequest

字段 类型 必填 说明
name string 是 任务名称
model string 是 基础模型, 固定为 DINO-X-1.0
labels string[] 是 标签列表
collections CreateFinetuneCollectionInput[] 是 训练数据来源, 至少 1 项
train int 是 训练集比例 (百分比), 取值范围 60–90
evaluate int 是 评估集比例 (百分比), 取值范围 10–40

CreateFinetuneCollectionInput

字段 类型 必填 说明
collection_id string 是 BFF 数据集集合 ID
version_id string 是 BFF 版本 ID
sample_ids uint64[] 是 参与微调的样本 ID 列表

请求示例

{
  "name": "my-finetune-1",
  "model": "DINO-X-1.0",
  "labels": ["cat", "dog"],
  "collections": [
    {
      "collection_id": "dc_abc123",
      "version_id": "dv_xyz789",
      "sample_ids": [1001, 1002, 1003]
    }
  ],
  "train": 80,
  "evaluate": 20
}

超出上述范围时, 下游 dataset-core 将返回参数校验错误.

响应示例

{
  "status": 0,
  "message": "success",
  "data": {}
}

5.3 POST /finetune/task/test

使用已训练微调模型对单张图片进行推理测试. 下游: dataset-core v2.

请求体 TaskTestRequest

字段 类型 必填 说明
task_id string 是 IDEA 训练平台任务 ID, 取列表/详情返回的 task_id
image_path string 是 待测图片路径

请求示例

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "image_path": "/dataSpace/org/test/sample.jpg"
}

响应 data

字段 类型 说明
annotations object 推理结果标注 JSON

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "annotations": {
      "objectdetection": {
        "boxes": [
          {
            "label": "cat",
            "confidence": 0.95,
            "x": 15,
            "y": 25,
            "width": 90,
            "height": 70
          }
        ]
      }
    }
  }
}

5.4 GET /finetune/:task_id

获取微调任务详情. 下游: dataset-core v2.

路径参数

参数 必填 说明
task_id 是 IDEA 训练平台任务 ID (外部 UUID, 取列表/详情返回的 task_id)

请求示例

GET /roboticsBffApi/cv/v1/dataset/finetune/a1b2c3d4-e5f6-7890-abcd-ef1234567890

响应 data: 结构同 FinetuneTaskInfo (见 §5.1, 含 evaluate_result 结构).

响应示例

{
  "status": 0,
  "message": "success",
  "data": {
    "id": 7,
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "my-finetune-1",
    "model_name": "DINO-X-1.0",
    "status": "succeeded",
    "labels": ["pomegranate"],
    "created": 1717819200,
    "start_time": 1717819300,
    "finish_time": 1717822800,
    "train_images_num": 80,
    "evaluate_images_num": 20,
    "evaluate_result": {
      "categorys": [
        {
          "anno": "",
          "ap0_5": 0.19999999999999996,
          "ap0_95": 0.20000000000000004,
          "image": "",
          "name": "pomegranate",
          "precision_recall_score": [
            [0.2, 0, 0.1470237374305725],
            [0.2, 0.01, 0.07550938427448273],
            [0.2, 1, 0.07550938427448273]
          ]
        }
      ],
      "m_ap0_5": 0.13155940594059404,
      "m_ap0_95": 0.12840346534653468,
      "recall_09precision": 0
    },
    "embedding_url": "https://example.com/embeddings/7",
    "created_at": "2026-06-08T10:00:00+08:00"
  }
}

5.5 DELETE /finetune/:task_id

删除微调任务. 下游: dataset-core v2.

路径参数

参数 必填 说明
task_id 是 IDEA 训练平台任务 ID (外部 UUID, 取列表/详情返回的 task_id)

请求示例

DELETE /roboticsBffApi/cv/v1/dataset/finetune/a1b2c3d4-e5f6-7890-abcd-ef1234567890

响应示例

{
  "status": 0,
  "message": "success",
  "data": {}
}

6. 与 dataset-core 映射

BFF 接口 下游方法 下游路径
manual-annotation POST /api/v2/annotation/manual-annotation
get-annotation GET /api/v2/annotation/get-annotation
auto-annotation POST /api/v1/annotation/auto-annotation
create-ground-truth POST /api/v1/annotation/create-ground-truth
get-annotation-model-list (部分) GET /api/v1/annotation/get-annotation-model-list
label-split POST /api/v1/annotation/label-split
finetune/list POST /api/v2/finetune/list
finetune/create POST /api/v2/finetune/create
finetune/task/test POST /api/v2/finetune/task/test
finetune/:task_id (GET) GET /api/v2/finetune/:task_id
finetune/:task_id (DELETE) DELETE /api/v2/finetune/:task_id

BFF 请求中的 collection_id + version_id 会在 service 层解析为 dataset-core 的 dataset_id 后再转发.


7. 注意事项

  1. 响应 envelope 差异: 本文 11 个接口使用 v1 envelope (status/message/data); docs/dataset_api.md 中 12 个集合/样本接口使用 CV envelope (code/msg/data). 前端需按模块区分解析.
  2. 动态 JSON 字段: annotations、evaluate_result 等为下游 passthrough, 本文示例仅供结构参考, 实际字段以 dataset-core 返回为准.
  3. 配置依赖: 需配置 DATASET_CORE_SERVICE_BASE_URL; 标注模型列表依赖 d-cloud 用户中心与 SKU 资源可用.

7.1 标注模型列表 (get-annotation-model-list) 前端对接

旧版 vs 新版调用方式

维度 旧版 (前端自行拼接) 新版 (BFF 聚合)
SKU 公有模型 前端调用 d-cloud resource 服务获取 SKU 列表 BFF 内部调用 resource.SkuList, 前端无需再调 resource
目标检测私有模型 前端再调标注模型列表接口, 与 SKU 列表手动拼接 BFF 在 task_type=object_detection 时自动合并 dataset-core 私有模型
前端消费 维护两套数据源与合并逻辑 仅调本接口一次, 直接使用 data.models
旧版: resource.SkuList ──┐
                          ├──> 前端合并 ──> 模型选择器
     get-annotation-model-list (仅检测私有模型) ──┘

新版: get-annotation-model-list ──> data.models (可直接渲染)

按任务类型的前端用法

自动标注场景 task_type 传参 模型选择 UI
目标检测 object_detection 展示 data.models 全部项 (SKU 公有 + 私有微调模型)
图像分类 image_classification 展示 data.models
语义分割 (单独) semantic_segmentation 展示 data.models; 未选 DINO-X-1.0 时仍需独立选分割模型
双目深度 / 真值生成 stereo_depth 展示 data.models
关键点检测 object_detection 固定选择 DINO-X-1.0, 不可选其他模型
目标检测 + 语义分割 (多任务) object_detection 选 DINO-X-1.0 后跳过分割模型步骤 (见下节)

DINO-X-1.0 多任务模型

DINO-X-1.0 为多任务标注模型, 同一模型可同时支撑:

  • 目标检测 (object_detection)
  • 语义分割 (semantic_segmentation)
  • 关键点检测 (keypoint)

拉取模型列表时, 上述任务统一使用 task_type=object_detection (当前无独立 keypoint / 多任务 SKU 入口).

场景 A: 仅关键点检测
  • 模型列表: task_type=object_detection, UI 写死 DINO-X-1.0, 不提供其他选项.
  • 提交 auto-annotation: task_types 含 keypoint, 模型写入 objectdetection_models.
GET .../get-annotation-model-list?task_type=object_detection

POST .../auto-annotation
{
  "task_types": ["keypoint"],
  "objectdetection_models": [{ "sku_name": "DINO-X-1.0", "sku_id": "...", "labels": ["person"] }]
}
场景 B: 目标检测 + 语义分割, 且检测模型为 DINO-X-1.0

用户同时勾选目标检测与语义分割, 并在检测模型步骤选择了 DINO-X-1.0 时:

  • 前端不再展示「选择分割模型」步骤.
  • 提交 auto-annotation 时不传 semanticsegmentation_model; 仅通过 objectdetection_models 传入 DINO-X-1.0, 由下游复用同一模型完成分割.
POST .../auto-annotation
{
  "task_types": ["object_detection", "semantic_segmentation"],
  "objectdetection_models": [{ "sku_name": "DINO-X-1.0", "sku_id": "...", "labels": ["cat", "dog"] }]
  // 无需 semanticsegmentation_model
}
场景 C: 目标检测 + 语义分割, 检测模型非 DINO-X-1.0

检测模型为 YOLO 等常规模型时, 行为与旧版一致:

  • 前端仍需第二步选择分割模型.
  • 提交时同时传 objectdetection_models 与 semanticsegmentation_model.
POST .../auto-annotation
{
  "task_types": ["object_detection", "semantic_segmentation"],
  "objectdetection_models": [{ "sku_name": "yolo-v8", ... }],
  "semanticsegmentation_model": { "sku_name": "seg-model-v1", ... }
}
前端模型选择流程 (决策)
用户勾选 task_types
    │
    ├─ 含 keypoint ──> 固定 DINO-X-1.0 (objectdetection_models), 结束
    │
    ├─ 含 object_detection + semantic_segmentation
    │       │
    │       ├─ 检测模型 = DINO-X-1.0 ──> 跳过选分割模型, 不传 semanticsegmentation_model
    │       └─ 检测模型 ≠ DINO-X-1.0 ──> 继续选 semanticsegmentation_model
    │
    └─ 其他单任务 ──> 按任务类型选对应模型字段

前端检查项

  • 移除对 d-cloud resource SKU 列表的独立调用与手动拼接逻辑
  • 模型选择器统一绑定 get-annotation-model-list 返回的 data.models
  • 关键点检测: task_type 传 object_detection, UI 固定 DINO-X-1.0, 禁用其他模型
  • 检测+分割且选 DINO-X-1.0: 跳过分割模型步骤, 不传 semanticsegmentation_model
  • 检测+分割且选非 DINO-X-1.0 检测模型: 仍展示分割模型步骤并传入 semanticsegmentation_model
  • 私有微调模型: 使用返回项中的 private_id (非旧版微调列表的本地 id)

8. 旧版迁移对照

旧版来源: dataset 服务 pkg/dataset/router/label.go、anno_train.go (路径前缀典型为 /datasetApi/api/v1).
新版即本文 11 个 BFF 接口. 供前端从旧 dataset 服务切换集成.

8.1 全局变更

维度 旧版 (dataset 服务) 新版 (robotics-bff)
Base URL {APP_SERVER_CONTEXT_PATH}/api/v1, 典型 /datasetApi/api/v1 {SERVER_CONTEXT_PATH}/cv/v1/dataset, 默认 /roboticsBffApi/cv/v1/dataset
鉴权 前端常需传 d-user-id + Authorization 仅 Authorization: Bearer <token>; BFF 从 d-cloud 注入用户上下文
Request ID 无强制要求 必须传 x-request-id, 缺失返回 40000
数据集标识 路径参数 dataset_id + version Body/Query 中 collection_id + version_id (BFF 内部解析为 core dataset_id)
响应 Envelope { status, message, data }, HTTP 几乎恒为 200 同为 { status, message, data }, HTTP 状态码与业务码对齐 (400/401/404/502 等)
错误码 500 / 50000 等混杂 统一 40000 / 40100 / 40400 / 50200 / 50000
下游架构 dataset 服务自建索引表 + 工作流 + IDEA 直连 BFF 代理 dataset-core v1/v2; 标注模型列表额外走 d-cloud SKU

ID 映射: 旧版 dataset_id/version 对应新版 CV 数据集模块的 collection_id/version_id (见 docs/dataset_api.md). 标注与微调应复用同一套 ID, 勿再使用旧 dataset 服务的 dataset_id.

8.2 接口对照总表

标注

# 能力 旧版 新版
1 手动保存标注 POST /datasets/:dataset_id/versions/:version/samples/label POST /annotation/manual-annotation
2 获取样本标注 GET /datasets/:dataset_id/versions/:version/samples/:sample_id GET /annotation/get-annotation
3 触发自动标注 (检测/分类/分割等) POST /datasets/:dataset_id/versions/:version/label POST /annotation/auto-annotation
4 批量深度真值生成 POST /datasets/:dataset_id/versions/:version/ground-truth-generate POST /annotation/auto-annotation (stereo_depth + depthestimation_model + label_all)
5 单样本 Ground Truth GET .../samples/:sample_id/ground-truth POST /annotation/create-ground-truth
6 标注模型列表 GET /datasets/label/models GET /annotation/get-annotation-model-list
7 标签文本拆分 POST /datasets/label/split POST /annotation/label-split

微调

# 能力 旧版 新版
1 任务列表 POST /datasets/anno-train-tasks/list POST /finetune/list
2 创建任务 POST /datasets/anno-train-tasks POST /finetune/create
3 任务详情 GET /datasets/anno-train-tasks/:task_id GET /finetune/:task_id
4 删除任务 DELETE /datasets/anno-train-tasks/:task_id DELETE /finetune/:task_id
5 推理测试 POST /datasets/anno-train-tasks/:task_id/test POST /finetune/task/test

8.3 逐接口关键差异

手动保存标注

项 旧版 新版
数据集定位 路径 dataset_id + version Body: collection_id + version_id
样本 ID 字段 id (int64) sample_id (uint64)
成功响应 data 为空 data: { "sample_id": 1001 }
- POST /datasetApi/api/v1/datasets/ds_001/versions/v1/samples/label
- { "id": 1001, "annotations": { ... } }
+ POST /roboticsBffApi/cv/v1/dataset/annotation/manual-annotation
+ { "collection_id": "dc_abc", "version_id": "dv_xyz", "sample_id": 1001, "annotations": { ... } }

获取样本标注

项 旧版 新版
方法/定位 GET 路径含三个 ID GET Query: collection_id, version_id, sample_id
响应字段 含 storage_path, width, height, vector, quality_score, last_label_user, last_label_time 等 精简为 id, name, type, path, is_labeled, status, labels, annotations

触发自动标注

项 旧版 新版
数据集定位 路径参数 Body: collection_id + version_id
任务类型 不传, 由数据集 task_type 推断 必填 task_types[], 使用 BFF 命名 (见 §8.4)
成功响应 data.taskId (camelCase) data.task_id (snake_case)
- POST /datasets/ds_001/versions/v1/label
- { "objectdetection_models": [...], "label_all": false }
+ POST /annotation/auto-annotation
+ { "collection_id": "dc_abc", "version_id": "dv_xyz",
+   "task_types": ["object_detection"],
+   "objectdetection_models": [...], "label_all": false }

批量深度真值生成 (原 ground-truth-generate)

旧版整版异步真值生成已并入 auto-annotation, 不再保留独立路由.

项 旧版 新版
路径 POST .../ground-truth-generate POST /annotation/auto-annotation
任务类型 隐含为双目深度 task_types: ["stereo_depth"]
模型 depthestimation_model (sku_id + sku_name 必填) 同名字段 depthestimation_model
批量范围 整版异步工作流 label_all: true 标注数据集所有样本; false 仅标注未标注样本
响应 data.taskId data.task_id
- POST /datasetApi/api/v1/datasets/ds_001/versions/v1/ground-truth-generate
- { "depthestimation_model": { "sku_id": "sku-uuid", "sku_name": "depth-model-v1" } }
+ POST /roboticsBffApi/cv/v1/dataset/annotation/auto-annotation
+ {
+   "collection_id": "dc_abc", "version_id": "dv_xyz",
+   "task_types": ["stereo_depth"],
+   "depthestimation_model": { "sku_id": "sku-uuid", "sku_name": "depth-model-v1" },
+   "label_all": true
+ }

真值生成场景分工:

场景 旧版 新版
批量真值生成 ground-truth-generate auto-annotation + label_all: true
单样本真值生成 GET .../samples/:sample_id/ground-truth POST /annotation/create-ground-truth

标注模型列表

项 旧版 新版
调用方式 前端先调 resource 拿 SKU, 目标检测再调本接口拼接 仅调 BFF 本接口一次, BFF 内部聚合 resource + core 私有模型 (见 §7.1)
Query task_type 必填, 值: objectdetection / imageclassification / semanticsegmentation / depthestimation 可选, 值: object_detection 等 (BFF 命名, 见 §8.4); 关键点检测也传 object_detection
响应结构 data 直接为数组 [{ id, name, labels }] data.models[] 为 [{ sku_id, sku_name, private_id, labels }]
私有微调模型 id = 本地 anno_train_task 表主键 private_id = dataset-core 私有模型 ID
关键点 / 检测+分割 分割需单独选 semanticsegmentation_model DINO-X-1.0 多任务: 检测+分割同选时可省略 semanticsegmentation_model (见 §7.1)

微调任务列表

项 旧版 新版
分页参数 page, page_size 必填 均可选
列表字段 data.items[] + data.pageInfo (total, pageNo, pageSize, totalPage) data.list[] + data.total / data.page / data.size
任务标识 仅 task_id (IDEA UUID) id (uint, 列表展示) + task_id (IDEA UUID, 详情/删除/推理测试)
进度与时间 无统一字段 created / start_time / finish_time (Unix 秒)
样本统计 无 train_images_num / evaluate_images_num

创建微调任务

项 旧版 新版
训练数据 images[]: { dataset_id, dataset_version, image_id } collections[]: { collection_id, version_id, sample_ids[] }
标签 不传, 从标注 COCO 自动提取 必填 labels[]
模型 model 自由传入 model 固定 DINO-X-1.0
- { "images": [{ "dataset_id": "ds_001", "dataset_version": "v1", "image_id": 1001 }], ... }
+ { "labels": ["cat", "dog"],
+   "collections": [{ "collection_id": "dc_abc", "version_id": "dv_xyz", "sample_ids": [1001, 1002] }], ... }

微调详情 / 删除 / 测试

项 旧版 新版
路径参数 :task_id (string, IDEA 外部 UUID) 同左, 路径参数名与取值一致
详情字段 含 task_id, status, evaluate_result 等 同列表 FinetuneTaskInfo, 额外含 created / start_time / finish_time / train_images_num / evaluate_images_num
测试任务 ID 路径 :task_id Body task_id (IDEA 外部 UUID, 取详情/列表返回的 task_id)
测试响应 annotations 数组: [{ label, boxes[] }] 对象: { objectdetection: { boxes: [{ label, confidence, x, y, width, height }] } }

8.4 task_types 命名对照

新版 BFF 入参 旧版 dataset 内部值
object_detection objectdetection
image_classification imageclassification
semantic_segmentation semanticsegmentation
stereo_depth depthestimation
keypoint keypointdetection (旧版无自动标注入口)

8.5 跨模块关联 (自动标注 x 微调)

旧版自动标注选私有模型时, objectdetection_models[].private_id 传的是本地微调任务表 anno_train_task.id.

新版应传 dataset-core 私有模型 private_id, 来源为 get-annotation-model-list 返回项. 前端若保留「选已完成微调任务作为检测模型」交互:

  1. 从新版微调列表拿 id (core ID)
  2. 在模型列表中匹配 private_id
  3. 自动标注请求里传该 private_id

8.6 前端切换检查清单

  • Base URL 改为 /roboticsBffApi/cv/v1/dataset
  • 所有请求加 x-request-id
  • 去掉手动传 d-user-id (仅保留 Authorization)
  • 数据集 ID 统一为 collection_id + version_id
  • 手动标注: id → sample_id, 路径参数改 Body
  • 获取标注: 路径改 Query; 适配精简后的响应字段
  • 自动标注: 新增 task_types[]; taskId → task_id; 任务类型改 BFF 命名
  • 批量 GT 生成: ground-truth-generate → auto-annotation (task_types=["stereo_depth"], label_all=true)
  • 单样本 GT: GET .../ground-truth → POST /annotation/create-ground-truth
  • 模型列表: 移除 resource SKU 拼接; 仅调 get-annotation-model-list, 直接使用 data.models
  • 关键点检测: 拉列表 task_type=object_detection, UI 固定 DINO-X-1.0
  • 检测+分割且选 DINO-X-1.0: 跳过分割模型步骤, 不传 semanticsegmentation_model
  • 微调列表: items → list; pageInfo → total/page/size
  • 微调创建: images → collections + labels; model 固定 DINO-X-1.0
  • 微调详情/删除: 路径用 task_id (IDEA UUID, 来自列表/详情); 推理测试 Body 传 task_id
  • 微调测试: annotations 从数组改为按任务键分组的对象
  • 错误处理: 除解析 body.status 外, 同时处理非 200 HTTP 状态码