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