1688 lines
46 KiB
Markdown
1688 lines
46 KiB
Markdown
# 视觉感知工作台 · 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
|
||
|
||
```json
|
||
{
|
||
"status": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 2.3 错误 Envelope
|
||
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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 (正整数) |
|
||
|
||
**请求示例**
|
||
|
||
```http
|
||
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` 对象内可并存多个任务键):
|
||
|
||
```json
|
||
{
|
||
"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`) 单任务示例:
|
||
|
||
```json
|
||
{
|
||
"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` 为对象, 存放右目图与视差图相对路径:
|
||
|
||
```json
|
||
{
|
||
"right": "org_symbol/datasets/ds_xxx/samples/right/img_001.jpg",
|
||
"disparity": "org_symbol/datasets/ds_xxx/samples/disparity/img_001.png"
|
||
}
|
||
```
|
||
|
||
**图像分类** (`imageclassification`)
|
||
|
||
`annotations` 为标签字符串数组:
|
||
|
||
```json
|
||
["cat", "dog"]
|
||
```
|
||
|
||
**响应示例** (目标检测单任务)
|
||
|
||
```json
|
||
{
|
||
"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[] | 标签列表 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"collection_id": "dc_abc123",
|
||
"version_id": "dv_xyz789",
|
||
"sample_id": 1001
|
||
}
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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) |
|
||
|
||
**请求示例**
|
||
|
||
```http
|
||
GET /roboticsBffApi/cv/v1/dataset/annotation/get-annotation-model-list?task_type=object_detection
|
||
```
|
||
|
||
**响应 `data`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `models` | LabelModel[] | 模型列表 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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 模型名 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"text": "cat, dog, person",
|
||
"model": "gpt-4"
|
||
}
|
||
```
|
||
|
||
**响应 `data`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `labels` | string[] | 拆分后的标签 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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 | 否 | 任务名称过滤 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"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` 示例**
|
||
|
||
```json
|
||
{
|
||
"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` 结构与此一致.
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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 列表 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"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 将返回参数校验错误.
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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 | 是 | 待测图片路径 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
||
"image_path": "/dataSpace/org/test/sample.jpg"
|
||
}
|
||
```
|
||
|
||
**响应 `data`**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `annotations` | object | 推理结果标注 JSON |
|
||
|
||
**响应示例**
|
||
|
||
```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`) |
|
||
|
||
**请求示例**
|
||
|
||
```http
|
||
GET /roboticsBffApi/cv/v1/dataset/finetune/a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
||
```
|
||
|
||
**响应 `data`**: 结构同 `FinetuneTaskInfo` (见 §5.1, 含 `evaluate_result` 结构).
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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`) |
|
||
|
||
**请求示例**
|
||
|
||
```http
|
||
DELETE /roboticsBffApi/cv/v1/dataset/finetune/a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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` |
|
||
|
||
```text
|
||
旧版: 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`.
|
||
|
||
```http
|
||
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`, 由下游复用同一模型完成分割.
|
||
|
||
```http
|
||
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`.
|
||
|
||
```http
|
||
POST .../auto-annotation
|
||
{
|
||
"task_types": ["object_detection", "semantic_segmentation"],
|
||
"objectdetection_models": [{ "sku_name": "yolo-v8", ... }],
|
||
"semanticsegmentation_model": { "sku_name": "seg-model-v1", ... }
|
||
}
|
||
```
|
||
|
||
##### 前端模型选择流程 (决策)
|
||
|
||
```text
|
||
用户勾选 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 }` |
|
||
|
||
```diff
|
||
- 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) |
|
||
|
||
```diff
|
||
- 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` |
|
||
|
||
```diff
|
||
- 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`** |
|
||
|
||
```diff
|
||
- { "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 状态码
|