46 KiB
视觉感知工作台 · 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. 注意事项
- 响应 envelope 差异: 本文 11 个接口使用 v1 envelope (
status/message/data);docs/dataset_api.md中 12 个集合/样本接口使用 CV envelope (code/msg/data). 前端需按模块区分解析. - 动态 JSON 字段:
annotations、evaluate_result等为下游 passthrough, 本文示例仅供结构参考, 实际字段以 dataset-core 返回为准. - 配置依赖: 需配置
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 返回项. 前端若保留「选已完成微调任务作为检测模型」交互:
- 从新版微调列表拿
id(core ID) - 在模型列表中匹配
private_id - 自动标注请求里传该
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 状态码