TBC/api_docs/dataset_annotation_finetune_api.md

1688 lines
46 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 视觉感知工作台 · 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 状态码