69 KiB
视觉感知工作台 · CV 数据集 BFF API
代码对齐:
internal/platform/cv/handler/cvdataset_handler.go(15 业务路由 + 2 废弃路由)、internal/platform/cv/dto/cvdataset/request.go、internal/platform/cv/dto/cvdataset/response.go、internal/platform/cv/service/dataset/、pkg/response/v1.go
伴生 OpenAPI:docs/cvdataset/dataset_swagger.json
前端接入指南:docs/cvdataset/dataset_frontend_integration_guide.md
变更 diff(自 merge dev #32 起):docs/cvdataset/dataset_changelog_since_merge_dev_32.md
联调参考:testui/dataset/app.js
更新日期:2026-06-29
受众:前端工程师 / 联调 / AI 自动封装
文档边界:本文只描述 BFF 对外 HTTP 契约(路径、请求、响应、错误、状态机)。不展开 BFF 内部下游实现;运维配置见 AGENTS.md。
Out of Scope(同 Base URL 下另有路由,不在本文 15 业务接口内):/annotation/*、/finetune/*;旧版 LeRobot /v1/datasets(batch/episode/preview/RRD)。
1. 快速开始
1.1 服务地址
| 项 | 值 |
|---|---|
| 默认 Host | http://localhost:8080(SERVER_PORT) |
| 业务前缀 | {SERVER_CONTEXT_PATH},默认 /roboticsBffApi |
| CV 数据集前缀 | {SERVER_CONTEXT_PATH}/cv/v1/dataset |
| 完整示例 | http://localhost:8080/roboticsBffApi/cv/v1/dataset |
BFF 未启用 CV 数据集模块时,上述路径返回 404(通常因运行环境未配置下游数据集服务)。
1.2 鉴权 Headers
| Header | 必填 | 说明 |
|---|---|---|
Authorization |
是 | Bearer <d-cloud token> |
x-request-id |
是 | 每次请求唯一 ID;缺失时中间件返回 code: 40000 |
Content-Type |
POST 建议 | application/json |
组织上下文:collections 读写经 requireCollectionAccess;鉴权成功后 context 须含 organizationId 与 orgSymbol(auth 中间件注入)。缺失时返回 40100 + missing organization context。
1.3 典型调用顺序
1. 获取 d-cloud Bearer token
2. 每次请求生成唯一 x-request-id
3. POST /collections/list → 列表卡片(无 versions[])
4. GET /collections/get → 详情 / 轮询状态(含 versions[])
5. GET /collections/version-tree → 版本管理抽屉分支树
6. POST /samples/list → 样本宫格
7. 写操作见各接口前置条件(§3 状态机)
异步任务(create / import / export / save):响应含 job_id 与 status: running;BFF 无 job 轮询接口,请轮询 GET /collections/get,观察 CollectionCard.status 与 status_text(§3)。
1.4 最小 curl
export BASE='http://localhost:8080/roboticsBffApi/cv/v1/dataset'
export TOKEN='<d-cloud-bearer-token>'
export RID='quickstart-001'
curl -sS -X POST "$BASE/collections/list" \
-H "Content-Type: application/json" \
-H "x-request-id: $RID" \
-H "Authorization: Bearer $TOKEN" \
-d '{"dataset_kind":"training","page":1,"page_size":20}'
1.5 术语
| 术语 | 含义 |
|---|---|
| collection | BFF 逻辑数据集卡片(collection_id 形如 dc_*),含训练/测试 Tab 与多版本 |
| formal version | 已封存正式版(version_type=formal 且 saved_at 非空),对用户展示为 V1/V2/… |
| draft / editable | 内部工作副本(version_type=draft,version_index=0),不对用户展示 V 号;所有写操作指向 editable_version |
| baseline | 当前编辑基准(baseline_version / baseline_version_id);切换基准会从该封存版 fork 新 draft |
| highest version | 已封存 formal 中 version_index 最大者(highest_version) |
| current_version | 兼容字段,与 baseline_version 相同(不再表示「查看版本」) |
| view version | 详情只读视角:GET /collections/get?version_id=,不落库 |
| sample | 样本行,BFF 映射为 SampleItem |
| job_id | 创建/导入/导出/封存/switch-baseline 时 BFF 返回的异步 clone 任务 ID |
1.6 版本模型(2026-06-23)
三条指针:
| 指针 | 字段 | 说明 |
|---|---|---|
| 最高正式版 | highest_version |
只读展示;已封存 formal 中 version_index 最大者 |
| 当前基准 | baseline_version / baseline_version_id |
编辑语义来源;保存快照后推进为新封存 formal(与 highest_version 一致) |
| 工作副本 | editable_version(version_type=draft) |
draft;所有写操作 body version_id;无 CollectionCard 顶层 editable_version_id 字段 |
封存:POST /versions/save 将当前 draft 克隆为新的 formal Vn;based_on_version_id 由 resolveSaveParentVersionID 记录血缘(优先 draft.based_on_version_id,否则保存前最高封存 formal,再否则 baseline);保存后 baseline_version_id = 新 formal id;再 fork 新 draft(based_on_version_id = 新 formal id),可继续基于未保存工作副本编辑。
版本树:GET /collections/version-tree 返回已封存 formal 的父子树(based_on_version_id);版本管理抽屉数据源;列表 POST /collections/list 不返回 versions[]。
切换基准:POST /versions/switch-baseline 仅能在版本管理操作;会丢弃当前 draft 未保存修改并从目标 formal fork 新 draft;响应含 version_creator_id。
废弃:POST /versions/switch(原切换查看)、POST /versions/promote-snapshot 均返回 40000 deprecated。
验收步骤见 docs/cvdataset/dataset_version_verification.md。
1.7 产品需求 ↔ 接口/字段(前端实现清单)
| # | 产品语义 | BFF 事实 | 前端必须 |
|---|---|---|---|
| 1 | 用户只见 V1/V2/… | get 的 versions[] 仅已封存 formal;draft 无对外 V 号 |
训练选版 / 详情历史用 get 的 versions[];版本管理抽屉用 version-tree;勿把 editable_version 当 V 号展示 |
| 2 | 卡片:最高 Vn + 基准 Vx | highest_version、baseline_version |
列表卡片版本条;▾ 按钮文案用 highest_version.version_name;list 无 versions[] |
| 3 | 保存快照仅在卡片 | POST /versions/save |
仅卡片「最高版本 ▾ → 保存快照」;无底栏独立按钮;version_id=editable_version_id;不要求有未保存修改 |
| 4 | 版本管理右侧抽屉 | GET /collections/version-tree + POST /versions/switch-baseline |
递归渲染 children;展示 version、created_at、version_creator_id、current_flag、is_latest;「切换到此版本」调 switch-baseline |
| 5 | 编辑基于基准的 draft | 写操作 version_id = editable_version_id |
补数/删样本/编辑元数据均传 draft id;新 formal 的 based_on_version_id 记录血缘;保存后 baseline_version_id = 新 formal id |
| 6 | 详情历史只读 | GET /collections/get?version_id= 不落库 |
详情历史下拉 + samples/list 只读;禁止 switch-baseline |
| 7 | 训练/微调仅 formal | ensureTrainableVersion;draft 返回 400 |
选版列表用 versions[];POST /finetune/create 等勿传 draft id |
1.8 训练 / 微调选版(/finetune/*,同 Base URL 子路由)
不在本文 15 个 collection 接口内,但 R7 与版本模型一致:
- 创建微调任务时
version_id(或等价字段)须为versions[]中已封存 formal。 - 传 draft
editable_version_id→40000+only sealed formal versions are trainable。 - UI 下拉数据源:仅
GET /collections/get返回的versions[](list 不返回versions[]),勿包含editable_version。
2. 公共约定
2.1 成功响应 Envelope
15 个 CV 数据集业务接口统一 status / message / data:
{ "status": 0, "message": "success", "data": {} }
分页接口 data 内嵌 list、total、page、page_size。
分页默认值(dto.NormalizePage):page 缺省或 <1 → 1;page_size 缺省或 <1 → 20;上限 100。
2.2 错误响应
业务层(15 个 CV 业务接口 + 2 废弃)
HTTP 状态码与业务 status 对齐。错误响应通常省略 data:
{ "status": 40000, "message": "invalid request body" }
中间件层(鉴权 / 缺 x-request-id)
字段为 code / message(无 status):
{ "code": 40100, "message": "unauthorized" }
判定:HTTP 2xx 且业务 status === 0;中间件错误看 code。
2.3 业务错误码
| status | HTTP | 典型场景 |
|---|---|---|
0 |
200 | 成功 |
40000 |
400 | 参数/业务校验失败 |
40100 |
401 | 无 token、d-cloud 拒绝、缺用户上下文、缺组织上下文(missing organization context) |
40400 |
404 | collection / version 不存在 |
40900 |
409 | 重名、task_types 冲突、版本绑定、fork 冲突 |
50000 |
500 | BFF DB/内部错误 |
50200 |
502 | 下游数据集服务不可达或异常 |
常见 message(与代码一致,便于前端分支):
| message | 触发接口 |
|---|---|
missing organization context |
collections 读写(requireCollectionAccess) |
no sealed versions found |
GET /collections/version-tree |
invalid dataset_kind |
collections/list、create |
name is required |
create |
collection name already exists |
create |
task_types is required / invalid task_type |
create / update / parser |
image_classification cannot combine with other types / stereo_depth cannot combine with other types |
create / update |
cannot remove existing task_type / cannot change task_types for … |
update |
sources is required |
create / import / parser |
path is required / invalid source_type |
sources 校验 |
collection_id is required / collection not found |
多数接口 |
collection_id and version_id are required |
update / samples / export / save / switch |
version not found / dataset version not found |
版本相关 |
version_id must match editable draft version |
collections/update、samples/import、samples/delete、versions/save;原因:body version_id ≠ 库内 editable_version_id;处理:用 list/get 最新 editable_version.version_id,勿用 baseline/highest;保存成功后须 refresh(见 §5.7.1) |
only draft working copy can be modified |
对 formal id 执行写操作 |
only sealed formal versions can be baseline |
versions/switch-baseline 目标为 draft |
only sealed formal versions are trainable |
finetune/create 等传 draft version_id |
dataset is not ready |
import / delete / export(core importing/appending/exporting/creating) |
dataset is not ready for clone |
versions/save / promote-snapshot |
sample_ids is required |
samples/delete |
target_path, export_name and export_format are required |
export |
invalid export_format |
export(多任务检测类集,须 coco 或 yolo) |
uap storage config is required |
create / import / export |
cannot delete the only version / cannot delete editable head version |
versions/delete |
version has task binding |
versions/delete |
version is not snapshot |
versions/promote-snapshot |
snapshot_version_id 缺失时 collection_id and snapshot_version_id are required |
promote-snapshot |
3. 数据集状态(核心)
3.1 前端应读哪些字段
BFF 不在响应中返回 creating、has_unsaved_changes 等内部布尔字段。卡片对外状态由 CollectionCard.status + CollectionCard.status_text 表达:
| 字段 | 类型 | 说明 |
|---|---|---|
status |
string | 业务状态枚举;与旧版 dataset 服务 dataset_version.status 尽量同名对齐,并新增 exporting / published(见 §3.2) |
status_text |
string | 中文展示文案;UI 优先展示此字段(collectionStatusLabel() 优先读 status_text,缺失时回退枚举映射) |
状态如何计算(buildCollectionCard → resolveCollectionStatsVersion + resolveCollectionCardStatus + applyViewingVersionStatus):
- 默认列表/详情(无
version_id):stats/status 取自 最高封存版(highest_version对应 core);baseline_version_id低于最高版时(已 switch-baseline)改取 可编辑 draft(editable_version_id)。 GET ?version_id=<formal>:stats 取自该 formal 行;非当前主线且映射为tobepublished时对外改为published(历史只读)。- 若 stats 版本
clone_status=switching(switch-baselinefork 新 draft)→switching;clone_status=running且 save 封存进行中 →publishing。 - 否则将 core 快照映射为 legacy 状态(
succeeded→tobepublished等);未切基准时最高封存版就绪态仍展示tobepublished(便于补数/编辑入口)。
内部 dirty 标记:update / import / delete 成功后 BFF 置 has_unsaved_changes=true,不映射到 status_text。保存快照不校验 dirty。
3.2 CollectionCard.status 全集
| status | status_text | 含义 | 是否处理中 |
|---|---|---|---|
creating |
创建中 | 元数据已创建,core 尚未就绪 | 是 |
running |
处理中 | core importing 等导入任务进行中 |
是 |
exporting |
导出中 | core exporting,导出任务进行中 |
是 |
tobepublished |
待发布 | draft 就绪且 core 空闲(卡片列表默认) | 否(可写) |
published |
已保存 | GET ?version_id= 查看历史 formal 时 |
否(只读) |
switching |
切换中 | switch-baseline fork 新 draft 后 clone 未完成 |
是 |
switchfailed |
切换失败 | switch-baseline 后台 clone 失败 |
否(终态,可重试切换) |
publishing |
发布中 | versions/save 封存后 clone 未完成 |
是 |
appending |
追加中 | core appending,补数进行中 |
是 |
labeling |
标注中 | core in_annotation |
是 |
gtgenerating |
真值生成中 | core training |
是 |
labelfailed |
标注失败 | core annotation_failed |
否(终态,可重试) |
appendfailed |
追加失败 | core appending_failed |
否(终态,可重试补数) |
gtgeneratingfailed |
真值生成失败 | core 训练失败类快照 | 否(终态) |
publishfailed |
发布失败 | versions/save clone 失败(非导出) |
否(终态) |
exportfailed |
导出失败 | core export_failed |
否(终态,可重试导出) |
failed |
失败 | core failed |
否(终态) |
removed |
已删除 | 已删除(列表接口通常查不到) | 否(终态) |
3.2.1 与旧版 dataset 状态快览(/Users/d-robotics/Project/dataset)
旧版事实源:
dataset_version.status(见旧仓库docs/architecture_design.md状态机、pkg/dataset/service/dataset_service.go)。
新版 BFF 不读旧库,但CollectionCard.status字符串尽量与旧版dataset_version.status同名,便于 trainer 迁移。
A. 完全一致(枚举相同,含义基本一致)
以下状态在旧版与新版的字符串与业务语义均对齐,前端可沿用原有分支逻辑:
BFF status |
旧版 dataset_version.status |
说明 |
|---|---|---|
creating |
creating |
数据集/版本创建初期 |
running |
running |
导入等工作流进行中 |
publishing |
publishing |
save 封存后 clone 进行中 |
switching |
switching |
switch-baseline fork 新 draft 后 clone 进行中 |
switchfailed |
switchfailed |
switch-baseline clone 失败 |
appending |
appending |
补数进行中 |
labeling |
labeling |
标注任务进行中 |
gtgenerating |
gtgenerating |
真值生成进行中 |
labelfailed |
labelfailed |
标注失败 |
appendfailed |
appendfailed |
补数失败 |
gtgeneratingfailed |
gtgeneratingfailed |
真值生成失败 |
publishfailed |
publishfailed |
仅 save/发布 clone 失败 |
failed |
failed |
通用失败 |
B. 语义有变化(枚举相同或相关,判定方式不同)
BFF status |
旧版对应 | 变化点 |
|---|---|---|
tobepublished |
tobepublished |
旧版:当前工作版本就绪。新版:仅当「当前查看版本 = 可编辑头」且 core 空闲;status_text=待发布 |
published |
published |
旧版:发布成功后写入 DB。新版:切换查看历史封存版时展示;status_text=已保存;亦可看 versions[].saved_at |
C. BFF 新增(旧版 dataset_version.status 状态机中无此枚举)
BFF status |
来源 | 说明 |
|---|---|---|
exporting |
dataset-core exporting |
旧版导出不在版本表持久化该状态;新版卡片展示 status_text=导出中 |
exportfailed |
dataset-core export_failed |
旧版无独立枚举;新版与 publishfailed(发布失败)分开,status_text=导出失败 |
D. switch-baseline 切换基准(与旧版 switching / switchfailed 对齐)
BFF status |
旧版 dataset_version.status |
说明 |
|---|---|---|
switching |
switching |
POST /versions/switch-baseline fork 新 draft 后;status_text=切换中;HTTP 立即返回,clone 后台执行 |
switchfailed |
switchfailed |
后台 clone 失败;status_text=切换失败;可再次 switch-baseline 重试 |
与
publishing区分:publishing/publishfailed仅用于POST /versions/save;切换基准不使用publishing。
| 操作 | BFF 行为 | 前端应怎么做 |
|---|---|---|
| 切换基准 | POST /versions/switch-baseline 立即返回;卡片 status=switching |
轮询 get/list 直至 tobepublished 或 switchfailed |
| 历史查看 | GET /collections/get?version_id= 只读 |
详情下拉;禁止调 switch-baseline |
旧 versions/switch |
返回 400 deprecated |
移除调用 |
迁移建议:旧代码若用 current_version 表示查看版本,新版查看走 query version_id;编辑/补数统一用 editable_version_id。旧 fork 补数逻辑已移除。
前端辅助函数(与 testui/dataset/app.js 一致):
function baselineVersionId(c) {
return c?.baseline_version?.version_id || c?.current_version?.version_id || '';
}
function editableVersionId(c) {
return c?.editable_version?.version_id || '';
}
function canMutateCurrentVersion(c) {
return Boolean(editableVersionId(c));
}
function canSaveCollection(c) {
if (isCollectionBusy(collectionStatusOf(c))) return false;
const st = collectionStatusOf(c);
if (st === 'creating' || st === 'failed') return false;
return Boolean(editableVersionId(c)); // 不要求 has_unsaved_changes
}
function canSupplementCollection(c) {
return Boolean(editableVersionId(c))
&& (collectionStatusOf(c) === 'tobepublished' || collectionStatusOf(c) === 'appendfailed');
}
按钮可用性(testui 参考实现):
| 操作 | 条件 |
|---|---|
| 编辑 | canMutateCurrentVersion(card) 且 status === 'tobepublished';version_id = editable_version_id |
| 补数 | canSupplementCollection(card) 且 !isCollectionBusy(status);version_id = editable_version_id |
| 保存快照 | 仅卡片「最高版本 ▾ → 保存快照」;canSaveCollection(card);body 见 §5.7.1:collection_id + editable_version.version_id |
| 切换基准 | 版本管理抽屉;POST /versions/switch-baseline;目标为 version-tree 节点或 get versions[] 中已封存 formal |
| 导出 | status === 'tobepublished' 或详情只读 published;version_id 为当前查看版(列表默认 draft,历史查看为 formal) |
| 删除样本 | status === 'tobepublished' 且非详情历史只读;version_id = editable_version_id |
轮询:create / import / export / save 等异步任务提交后,每 3–5s GET /collections/get?collection_id=...,直至 isCollectionTerminal(status)。samples/delete 为同步操作,成功后刷新 get + list 即可,无需 job 轮询。
3.3 与旧版 dataset 服务状态对照
旧版视觉数据集走 datasetApi/api/v1/datasets/*(仓库 /Users/d-robotics/Project/dataset)。卡片状态对应旧版 dataset_version.status(版本级);下文不对旧版 dataset.status(数据集表级)展开。
3.3.1 dataset-core 快照 → BFF CollectionCard.status
BFF 不直接读旧库,而是读 dataset-core 的 status 再映射(mapCoreSnapshotStatus):
dataset-core status |
BFF status |
BFF status_text |
|---|---|---|
succeeded |
tobepublished(卡片列表默认可编辑 draft)或 published(GET ?version_id= 查看历史 formal 时) |
待发布 / 已保存 |
creating |
creating |
创建中 |
importing |
running |
处理中 |
exporting |
exporting |
导出中 |
appending |
appending |
追加中 |
in_annotation |
labeling |
标注中 |
annotation_failed |
labelfailed |
标注失败 |
appending_failed |
appendfailed |
追加失败 |
export_failed |
exportfailed |
导出失败 |
training |
gtgenerating |
真值生成中 |
failed |
failed |
失败 |
removed |
removed |
已删除 |
3.3.2 旧版 dataset_version.status → BFF
旧版 dataset_version.status |
BFF 等价 | 备注 |
|---|---|---|
creating |
creating 或 running |
创建后首次导入多为 running |
running |
running |
导入任务进行中 |
tobepublished |
tobepublished |
可编辑头就绪;status_text=待发布 |
publishing |
publishing |
save 后 clone 进行中 |
published |
published |
切换查看历史封存版时;或看 versions[].saved_at 非空 |
exporting |
exporting |
旧版导出中 → 新版同名 |
exportfailed |
— | 旧版无独立枚举 |
failed |
failed |
|
publishfailed |
publishfailed |
save / clone 失败(不含导出失败) |
labeling |
labeling |
|
labelfailed |
labelfailed |
|
gtgenerating |
gtgenerating |
|
gtgeneratingfailed |
gtgeneratingfailed |
|
appending |
appending |
|
appendfailed |
appendfailed |
|
switching |
switching |
switch-baseline clone 进行中 |
switchfailed |
switchfailed |
switch-baseline clone 失败 |
3.3.3 旧版「发布」vs 新版「保存版本」
| 维度 | 旧版 datasets/{id}/publish |
新版 POST /versions/save |
|---|---|---|
| 触发 | 对当前版本发布 | version_id 须等于 editable_version_id;core 须 succeeded |
| 进行中 | publishing |
publishing |
| 完成后 | 旧版 published 字符串 |
新可编辑头 tobepublished;旧版进 versions[] 且 saved_at 有值 |
3.3.4 异步任务提交响应 status
create / import / export 首次响应(不含 samples/delete,删除为同步):
| 字段 | 值 | 说明 |
|---|---|---|
status |
running |
任务已提交 |
status_text |
运行中 |
|
job_id |
string | 任务 ID(save 亦返回 job_id) |
3.4 样本行级状态
SampleItem.is_labeled:bool,行是否已标注。
SampleItem.status / status_text:可选;无 status 时 BFF 由 is_labeled 映射为 已标注/未标注。
4. 枚举与字段字典
4.1 dataset_kind
| 值 | 含义 |
|---|---|
training |
训练集 Tab |
testing |
测试集 Tab |
4.2 task_type(BFF 请求/响应均用 snake_case)
| 值 | 中文 | 组合规则 |
|---|---|---|
object_detection |
目标检测 | 可与 SS/KP 组合 |
semantic_segmentation |
语义分割 | 可与 OD/KP 组合 |
keypoint |
关键点检测 | 可与 OD/SS 组合 |
image_classification |
图像分类 | 仅允许单任务 |
stereo_depth |
双目深度 | 仅允许单任务 |
更新时仅允许增量添加 task_type,不可删除已有类型。
4.3 source_type 与 SourceItem
SourceItem(request.go):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
source_type |
string | 是 | dataspace | datageneration |
path |
string | 条件必填 | source_type 为上述二者时必填;经 NormalizeSourcePath 后提交 dataset-core |
source_type 值 |
含义 |
|---|---|
dataspace |
数据空间目录 |
datageneration |
数据生成产出目录 |
路径规范化(NormalizeSourcePath,与代码一致):
- 若字符串首字符为
/,去掉一个前导/; - 再
TrimSpace首尾空白。
示例:/dataSpace/a/train → dataSpace/a/train; /foo → /foo(首字符为空格时不删 /)。
多个 sources 路径合并为一次导入/解析请求(common_file_path 数组)。
4.4 export_format(请求体)
BFF 校验后映射为 dataset-core 实际格式(MapExportFormat):
数据集 task_types |
请求体 export_format |
提交 core 的值 |
|---|---|---|
| 含 OD/SS/KP(非单任务 IC/深度) | 必填,须为 coco 或 yolo |
原样 |
仅 image_classification |
任意非空字符串 | 固定 image_classification(忽略前端具体值) |
仅 stereo_depth |
任意非空字符串 | 固定 depth_estimation(忽略前端具体值;前端可传 tiff 作语义占位) |
非法检测类格式返回 invalid export_format。
4.5 version_type
| 值 | 含义 |
|---|---|
formal |
已封存正式版(对用户展示 V1/V2/…) |
draft |
内部工作副本(无对外 V 号) |
snapshot |
已废弃;历史存量;promote-snapshot 已禁用 |
4.6 annotations(SampleItem.annotations)
类型:map[string]json.RawMessage。key 为 BFF task_type(snake_case);value 为按任务类型的标注 JSON。未标注时 key 缺失或 value 为 [] / {}。
4.6.1 object_detection
value 类型:ObjectDetectionAnnotation[]
| 字段 | 类型 | 说明 |
|---|---|---|
label |
string | 类别名,与 collection labels / 预解析标签一致 |
boxes |
BoundingBox[] |
检测框列表 |
BoundingBox
| 字段 | 类型 | 说明 |
|---|---|---|
x |
number | 左上角 x(像素) |
y |
number | 左上角 y(像素) |
width |
number | 框宽(像素) |
height |
number | 框高(像素) |
"object_detection": [
{ "label": "person", "boxes": [{ "x": 10, "y": 20, "width": 100, "height": 200 }] }
]
4.6.2 semantic_segmentation
value 类型:SemanticSegmentationAnnotation[]
| 字段 | 类型 | 说明 |
|---|---|---|
label |
string | 分割类别名 |
boxes |
Point[] |
多边形顶点序列(至少 3 点) |
Point
| 字段 | 类型 | 说明 |
|---|---|---|
x |
number | 顶点 x |
y |
number | 顶点 y |
"semantic_segmentation": [
{ "label": "road", "boxes": [{ "x": 10, "y": 20 }, { "x": 50, "y": 22 }, { "x": 48, "y": 60 }] }
]
4.6.3 keypoint
value 类型:KeypointAnnotation[]
| 字段 | 类型 | 说明 |
|---|---|---|
label |
string | 实例类别名,与 keypoints_configs[].name 对应 |
bbox |
BoundingBox |
可选,实例外接框 |
keypoints |
Keypoint[] |
关键点列表 |
Keypoint
| 字段 | 类型 | 说明 |
|---|---|---|
x |
number | 关键点 x |
y |
number | 关键点 y |
visible |
integer | 可见性:0=未标注 / 不可见,1=遮挡,2=可见(COCO 语义) |
name |
string | 关键点名称,与 keypoints_configs[].keypoints 元素对应 |
"keypoint": [
{
"label": "person",
"bbox": { "x": 0, "y": 0, "width": 200, "height": 400 },
"keypoints": [
{ "x": 95, "y": 40, "visible": 2, "name": "nose" },
{ "x": 80, "y": 38, "visible": 2, "name": "l_eye" }
]
}
]
4.6.4 image_classification
value 类型:string[],每个元素为一个分类标签名。
"image_classification": ["cat"]
4.6.5 stereo_depth
value 类型:StereoDepthAnnotation(object)
| 字段 | 类型 | 说明 |
|---|---|---|
right |
string | 右目图对象存储路径 |
disparity |
string | 视差图对象存储路径 |
左目图路径在样本行 storage_path。
"stereo_depth": {
"right": "/dataSpace/project/000001_right.png",
"disparity": "/dataSpace/project/000001_disparity.png"
}
4.7 列表筛选约定
以下与 collection.go(数据集列表)、sample.go + sample_list_filter.go + sample_stats_resolve.go(样本列表)行为一致。
4.7.1 POST /collections/list
| 参数 | 传递方式 | 筛选效果 | 对 total / list 的影响 |
|---|---|---|---|
dataset_kind |
必填 training | testing |
仅返回该 Tab 下、当前组织(organization_id + org_symbol)可见的 collection |
DB 条件;计入 total |
name |
可选 string | 对 BFF 本地展示名 name 模糊匹配(SQL LIKE %name%) |
DB 条件;计入 total |
creator |
可选 string | 对 created_by_name 模糊匹配(SQL LIKE %creator%) |
DB 条件;计入 total |
task_types |
可选 string[] | collection 的 task_types 须同时包含请求中列出的每一个类型(AND / 超集匹配,非精确相等) |
DB 分页之后在内存过滤;list 可能少于 page_size;total 仍为 DB 计数,不随本筛选减少 |
page / page_size |
可选 | 先对 DB 结果分页,再对当前页做 task_types 内存过滤 |
默认 1 / 20,上限 100 |
前端注意
- 任务类型 chips 筛选后,分页器
total可能大于实际可见卡片数;若需精确 total,只能客户端二次统计或接受近似分页。 name与task_types可组合:name在 DB 层生效,task_types在当前页结果上生效。
示例
{ "dataset_kind": "training", "name": "od", "task_types": ["object_detection", "keypoint"], "page": 1, "page_size": 20 }
含义:训练 Tab 下名称含 od 的数据集(DB),且任务类型同时含 OD 与 KP(当前页内存过滤)。
4.7.2 POST /samples/list
公共参数:
| 参数 | 筛选效果 |
|---|---|
collection_id + version_id |
必填;定位 core dataset |
name |
可选;文件名 模糊搜索,传入 dataset-core |
labels |
可选 string[];样本 labels 列 任意命中(OR),传入 dataset-core;可与 is_labeled / name 组合 |
page / page_size |
分页;默认 1 / 20,上限 100 |
is_labeled 与 annotation_task_types 组合
is_labeled |
annotation_task_types |
数据集类型 | BFF 列表策略 | 筛选语义 |
|---|---|---|---|---|
| 省略 | 省略 | 任意 | core 全量列表 | 不过滤标注状态 |
| 省略 | 非空(相对 collection task_types 的真子集) |
非 IC/深度单任务 | core 全量列表 | 列表不过滤;BFF 仅裁剪 list[].annotations / list[].task_annotation_statuses(不转发 core) |
true |
省略 | 多任务纯视觉 | core is_labeled=true |
与 Tab status_stats.labeled(≥1 分支已标)对齐 |
false |
省略 | 多任务纯视觉 | core is_labeled=false |
与 Tab status_stats.unlabeled(全部分支均未标)对齐 |
true / false |
任意 | 仅 image_classification 或 仅 stereo_depth |
BFF 本地扫页 | 按行级 SampleItem.is_labeled 匹配;始终忽略 annotation_task_types |
true |
非空 | OD / SS / KP 纯视觉任务集 | BFF 本地扫页 AND | 指定分支 全部 已标 |
false |
非空 | OD / SS / KP 纯视觉任务集 | BFF 本地扫页 AND | 指定分支 全部 未标(其他分支可已标) |
true / false |
非空 | 含 IC/深度等非纯视觉组合 | core + annotation_task_match=and |
指定分支 AND 匹配(以 core 行为为准;纯视觉子集优先走上一行本地扫页) |
纯视觉任务集(IsVisualBranchTaskDataset):collection 的 task_types 每一个都属于 object_detection / semantic_segmentation / keypoint。
本地扫页说明:BFF 以 200 条/页向 core 拉取并在内存按 task_annotation_statuses 匹配,再组装目标页;大数据集下比 core 直筛慢,但保证 IC/深度行级筛选与「未标 + 任务子集」分支语义正确。
testui 参考(testui/dataset/app.js)
- Tab「全部」:不传
is_labeled;任务真子集时仍传annotation_task_types(仅响应裁剪)。 - Tab「已标注 / 未标注」:传
is_labeled: true | false。 - 任务 chips:相对 collection 全量
task_types为真子集时传annotation_task_types;全选时不传。
4.7.3 响应统计字段与 total 对齐
status_stats(Tab 角标,与列表筛选语义对齐,resolveSampleStatusStats)
| 数据集类型 | labeled |
unlabeled |
|---|---|---|
| IC / 深度单任务 | core 行级 labeled_count |
core 行级 unlabeled_count |
| 多任务纯视觉(OD/SS/KP 组合) | multi_task_labeled_count(至少一分支已标) |
all_tasks_unlabeled_count(全部分支均未标) |
| 单任务纯视觉 | 该任务 task_status_stats[task_type].labeled |
同 bucket 的 unlabeled |
| 其他 / stats 降级 | core 全局 labeled_count |
core 全局 unlabeled_count |
task_status_stats:key 为 BFF task_type;IC/深度单任务时该唯一 key 的计数与 status_stats 一致。
total(分页总数,resolveListTotal)
| 筛选条件 | total 来源 |
|---|---|
未传 is_labeled |
core 列表 total(含 name 搜索) |
IC/深度 + is_labeled |
status_stats.labeled 或 status_stats.unlabeled(与 Tab 一致) |
is_labeled=true + annotation_task_types(纯视觉) |
BFF 本地 AND 扫页后的 total |
is_labeled=true(无任务子集) |
status_stats.labeled |
is_labeled=false + annotation_task_types(纯视觉) |
BFF 本地 AND 扫页后的 total(应与对应 task_status_stats[task].unlabeled 一致,单选任务时) |
is_labeled=false(无任务子集) |
status_stats.unlabeled |
传了 labels |
core / 本地扫页列表 total(stats 不按 label 过滤) |
4.8 其他枚举
task_annotation_statuses(SampleItem.task_annotation_statuses)
| 值 | 说明 |
|---|---|
labeled |
该 task_type 分支已有标注内容 |
unlabeled |
该分支尚无标注 |
key 为 BFF task_type。多任务集上各 key 可独立取值;image_classification / stereo_depth 单任务时 BFF 按行级 is_labeled 覆盖对应单键。
SampleItem.type(样本 split 类型)
| 值 | 说明 |
|---|---|
train |
训练集 split |
val |
验证集 split |
test |
测试集 split |
error |
导入异常样本 |
SampleItem.status(SampleRowStatus,可选透传)
dataset-core 行级状态;缺失时 status_text 由 is_labeled 映射为 已标注 / 未标注。
| 值 | 说明 |
|---|---|
in_annotation |
标注中 |
no_train |
未参与训练 |
training |
训练中 |
train_succeeded |
训练成功 |
异步任务响应 status(JobStatus)
create / import / export / save 提交后 data.status 固定为 running,data.status_text 为 运行中(与 CollectionCard.status 不同)。
5. 接口说明
路径均相对于 {SERVER_CONTEXT_PATH}/cv/v1/dataset。
5.1 POST /collections/list
用途:分页列出当前组织指定 Tab 下的数据集卡片(requireCollectionAccess + repoScope())。
请求:ListCollectionsRequest(§6.1)。
| 字段 | 必填 | 默认 | 说明 |
|---|---|---|---|
dataset_kind |
是 | — | training / testing |
name |
否 | — | 名称模糊搜索 |
creator |
否 | — | 创建人展示名(created_by_name)模糊搜索 |
task_types |
否 | — | 集合须包含所列全部类型 |
page |
否 | 1 |
|
page_size |
否 | 20 |
上限 100 |
筛选参数效果 — 详见 §4.7.1。
| 参数 | 筛选效果摘要 |
|---|---|
dataset_kind |
训练 / 测试 Tab 隔离 |
name |
展示名模糊搜索(DB 层,影响 total) |
creator |
创建人 created_by_name 模糊搜索(DB 层,影响 total) |
task_types |
任务类型超集 AND 匹配(内存过滤,不影响 total) |
list[] 元素:BuildCollectionListCard + enrichCardTaskStatusStats 组装,省略 versions[];版本摘要字段(highest_version、baseline_version、editable_version、version_count)仍返回。
list[].task_status_stats:map[string]TaskStats,key 为 BFF task_type;每项 labeled / unlabeled / total。由 loadSampleStatsForList + buildTaskStatusStats 填充(sample/stats 无任务维度时回退 batch-get 嵌套 stats)。统计版本与 stats 一致(默认 editable_version,无 draft 时 baseline_version)。
写操作 version_id 取自 list:list[].editable_version.version_id(draft)。CollectionCard 无顶层 editable_version_id 字段;baseline_version / current_version / highest_version 均为 formal,不可用于 save / import / delete / update。完整映射见 §5.7.1。
task_types 注意:筛选在 DB 分页后内存执行,当前页 list 可能变短,但 total 仍为 DB 分页总数。
响应 data:ListCollectionsResponse(§6.2),list[] 元素为 CollectionCard(§6.3)。
示例片段
{
"status": 0,
"message": "success",
"data": {
"list": [{
"collection_id": "dc_abc123_20260608120000",
"name": "my-od-dataset",
"dataset_kind": "training",
"task_types": ["object_detection"],
"status": "tobepublished",
"status_text": "待发布",
"version_count": 1,
"highest_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
"baseline_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
"current_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
"editable_version": { "version_id": "dv_draft", "version_name": "", "version_type": "draft" },
"stats": { "total_count": 100, "labeled_count": 80, "unlabeled_count": 20 }
}],
"total": 1,
"page": 1,
"page_size": 20
}
}
5.2 POST /collections/create
用途:创建 collection + 封存 V1 formal,提交首次导入。V1-only 阶段 editable_version 指向 V1 formal;draft 工作副本仅由 POST /versions/save 或 POST /versions/switch-baseline 显式 fork,list/get 的 reconcileVersionModel 不调用 dataset-core clone。
请求:CreateCollectionRequest(§6.1)。sources[] 元素为 SourceItem(§4.3 / §6.1)。
| 字段 | 必填 | 说明 |
|---|---|---|
dataset_kind |
是 | |
name |
是 | 同组织(organization_id + org_symbol)同 kind 不可重名 |
description |
否 | 数据集描述;写入 BFF 本地并透传 core dataset_description |
task_types |
是 | §4.2 |
labels |
否 | 类别标签名;双目深度创建通常省略 |
keypoints_configs |
否 | 非空数组时写入关键点骨架配置;仅含 keypoint 任务时有效,结构 §6.6。skeleton 前端传 0-based,BFF 写下游时转为 COCO 1-based |
sources |
是 | ≥1 |
响应 data:CreateCollectionResponse(§6.2)。
成功后:refreshList + 轮询 get 直至 status=tobepublished 或失败终态。
5.3 GET /collections/get
用途:单张卡片详情;所有异步任务轮询入口。
Query:GetCollectionQuery(§6.1)。
响应 data:CollectionCard(§6.3,含 versions[]、stats、task_status_stats、camera_intrinsics、keypoints_configs)。由 BuildCollectionCard 组装,includeVersionSummaries=true。
统计版本:默认取 editable_version 的 core 数据集(无 draft 时回退 baseline_version);传 version_id 时取该查看版。stats 与 task_status_stats 均基于同一版本(resolveCollectionStatsVersion)。
task_status_stats:map[string]TaskStats,key 为 BFF task_type;由 enrichCardTaskStatusStats → loadSampleStatsForList + buildTaskStatusStats 填充(sample/stats 无任务维度时回退 batch-get 嵌套 stats)。list / get 均返回;list 不支持 ?version_id= 指定历史版统计。
5.3.1 GET /collections/version-tree
用途:版本管理抽屉的分支树;仅含已封存 formal,按 based_on_version_id 建树。
Query:GetVersionTreeQuery(§6.1)
| 字段 | 必填 | 说明 |
|---|---|---|
collection_id |
是 |
响应 data:单个 VersionTreeNode 根节点(§6.4.1),非数组。无封存版时 40400 + no sealed versions found。
节点字段摘要:version(如 V1)、related_version(父版本名)、current_flag(是否基准)、is_latest、version_creator_id、created_at(优先 saved_at)、children[](递归)。
5.4 POST /collections/update
用途:更新可编辑头元数据(name/description/labels/task_types 增量、关键点骨架配置)。
请求:UpdateCollectionRequest(§6.1)。
前置:version_id 必须等于 editable_version_id(draft);status=tobepublished(或 core 非 busy)。
| 字段 | 说明 |
|---|---|
name |
非空时仅更新 BFF 展示名 |
description |
非空时同步下游 |
task_types |
非空时仅增量 |
labels |
非空数组时全量替换 |
keypoints_configs |
非空数组时全量替换关键点骨架配置;仅含 keypoint 任务时有效,结构见 §6.6。前端统一传 0-based skeleton;BFF 写入下游时按 COCO 格式转换(index_base=1,skeleton 各下标 +1) |
响应 data:UpdateCollectionResponse(§6.2)。
5.5 DELETE /collections/delete
Query:collection_id。响应 data:{}。
5.6 POST /versions/switch-baseline
用途:切换编辑基准(版本管理抽屉);从目标已封存 formal fork 新 draft;丢弃当前 draft 未保存修改。
Body:SwitchBaselineRequest(§6.1)
| 字段 | 说明 |
|---|---|
collection_id |
必填 |
version_id |
必填;须为已封存 formal(saved_at 非空),不能为 draft |
响应 data:SwitchBaselineResponse — baseline_version_id、editable_version_id、version_creator_id、job_id(clone 任务)
成功后卡片 status 可能为 switching,轮询 get 直至新 draft 就绪(tobepublished)或 switchfailed。
5.6.1 POST /versions/switch(已废弃)
返回 40000:versions/switch is deprecated; use versions/switch-baseline or GET collections/get?version_id= for view-only。
5.7 POST /versions/save
用途:封存当前 draft 为新的 formal Vn,再 fork 新 draft;更新 baseline_version_id 为新封存 formal id。
Body:SaveVersionRequest(§6.1)
前置:
version_id须等于库内editable_version_id(即 list/get 的editable_version.version_id)- 对应 core 数据集
status === succeeded
响应 data:SaveVersionResponse — saved_version、based_on_version(封存血缘父版本)、baseline_version(与 saved_version 相同)、新 editable_version、job_id
血缘:新 formal 的 based_on_version_id = resolveSaveParentVersionID 结果;保存后 col.BaselineVersionID = 新 formal id。
5.7.1 list → save 参数映射(前端必读)
SaveVersionRequest 字段 |
取自 POST /collections/list 的 list[] |
说明 |
|---|---|---|
collection_id |
card.collection_id |
必填 |
version_id |
card.editable_version.version_id |
须等于 BFF 当前 editable_version_id;JSON 可省略(omitempty),省略时 BFF 默认用库内 editable |
勿用:baseline_version.version_id、current_version.version_id、highest_version.version_id(均为 formal,会触发 version_id must match editable draft version)。
list 卡片示例:
{
"collection_id": "dc_abc123_20260608120000",
"highest_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
"baseline_version": { "version_id": "dv_v1", "version_name": "V1", "version_type": "formal" },
"editable_version": { "version_id": "dv_draft", "version_name": "", "version_type": "draft" }
}
对应 save 请求:
{
"collection_id": "dc_abc123_20260608120000",
"version_id": "dv_draft"
}
保存成功后:editable_version 变为新 fork 的 draft id;前端须 refreshList() 或用 SaveVersionResponse.editable_version 更新本地,禁止复用保存前的 version_id。
实现差异:list/get 在返回前执行 reconcileVersionModel(对齐 baseline 指针、legacy 行归一化,不 fork draft);SaveVersion 直接 GetCollection 并按库内 editable_version_id 校验(version_writable.go → resolveWritableVersion)。故 save 必须以最新 list/get 的 editable_version 为准。
testui 参考:testui/dataset/app.js — editableVersionId()、canSaveCollection()、卡片 data-save 处理器。
5.8 POST /versions/promote-snapshot(已废弃)
返回 40000 deprecated。快照模型已移除。
5.9 DELETE /versions/delete
Query:collection_id、version_id。
不可删可编辑头、不可删唯一版本、has_task_binding=true 时 40900。
5.10 POST /samples/list
用途:分页样本列表 + Tab 统计。
必填:ListSamplesRequest 中 collection_id、version_id(§6.1)。
筛选参数 — 完整组合语义、列表策略、status_stats / total 对齐见 §4.7.2–§4.7.3。
| 参数 | 说明 |
|---|---|
name |
文件名模糊搜索 |
labels |
样本级标签任意命中(OR) |
is_labeled |
省略=全部样本;true/false=已标/未标 Tab |
annotation_task_types |
任务真子集时传;与 is_labeled 组合见 §4.7.2(纯视觉:已标/未标 Tab 均为 AND;「全部」Tab 仅裁剪响应) |
page / page_size |
默认 1 / 20,上限 100 |
列表策略摘要(sample.go 分支):
- IC / 深度单任务 且传了
is_labeled→ BFF 本地按SampleItem.is_labeled扫页;忽略annotation_task_types。 - 纯视觉任务集 +
is_labeled已传 +annotation_task_types非空 → BFF 本地按task_annotation_statusesAND 扫页(已标=指定分支全部已标;未标=指定分支全部未标)。 is_labeled省略 +annotation_task_types非空 → core 全量列表;BFF 仅裁剪list[]中任务字段。- 其他 → dataset-core 列表(仅
is_labeled或全量);非纯视觉且带任务子集时 core 使用annotation_task_match=and。
响应 data:ListSamplesResponse(§6.2);list[] 为 SampleItem(§6.8);标注 JSON §4.6。
SampleItem.id 即 samples/delete 的 sample_ids 元素。thumbnail_url 当前恒为空字符串。
5.11 POST /samples/import
用途:补数 / 追加导入。
请求:ImportSamplesRequest(§6.1)。version_id 必须等于 editable_version_id(draft)。
历史 formal id 将返回 40000(不再 fork)。
前置:非处理中(!isBusy(status))。
响应 data:ImportSamplesResponse(§6.2);无 forked 字段。
5.12 POST /samples/delete
用途:批量删除样本(同步完成,无 job_id)。
请求:DeleteSamplesRequest(§6.1)。version_id 必须等于 editable_version_id(draft)。
前置:core 非 busy;详情历史只读视角下前端应禁用删除。
响应 data:DeleteSamplesResponse — deleted_count(同步;无 forked)
示例
{
"status": 0,
"message": "success",
"data": {
"deleted_count": 3
}
}
成功后:refreshSamples() + GET /collections/get(version_id 仍为当前 draft)。
5.13 POST /export
用途:对任意存在版本提交导出任务(不要求可编辑头)。
请求:ExportDatasetRequest(§6.1)。export_format 规则见 §4.4。
前置:status 非处理中;须配置 UAP(否则 uap storage config is required)。
响应 data:ExportDatasetResponse(§6.2)。
轮询 get 观察 status 直至 tobepublished 或 exportfailed/publishfailed/failed。
5.14 POST /labels/parser
用途:从数据空间/数据生成目录同步预解析标签名与关键点骨架配置(无 job_id)。仅含 keypoint 任务时,响应可能含 keypoints_configs(§6.6)。
请求:ParseLabelsRequest(§6.1)。
响应 data:ParseLabelsResponse(§6.2)。
创建弹窗典型流:parser → 填入 labels 与(关键点任务)keypoints_configs → create(见 testui runParseLabels())。
6. 数据模型参考(与 dto/cvdataset 对齐)
以下结构与 internal/platform/cv/dto/cvdataset/request.go、response.go 字段名、JSON tag 完全一致。接口章节的「请求 / 响应」均引用本节类型名。
6.1 请求体 / Query
ListCollectionsRequest — POST /collections/list
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
dataset_kind |
string | 是 | — | training | testing |
name |
string | 否 | — | 名称模糊搜索 |
creator |
string | 否 | — | created_by_name 模糊搜索 |
task_types |
string[] | 否 | — | 集合须包含所列全部类型 |
page |
int | 否 | 1 |
≥1 |
page_size |
int | 否 | 20 |
1–100 |
CreateCollectionRequest — POST /collections/create
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
dataset_kind |
string | 是 | training | testing |
name |
string | 是 | 同组织(organization_id + org_symbol)同 kind 不可重名 |
description |
string | 否 | 写入 BFF 本地并透传 core dataset_description |
task_types |
string[] | 是 | §4.2 |
labels |
string[] | 否 | 类别标签名;双目深度创建通常省略 |
keypoints_configs |
KeypointCategoryConfig[] |
否 | 非空数组时写入关键点骨架配置;仅 keypoint 任务;结构 §6.6。skeleton 前端传 0-based,BFF 写下游时转为 COCO 1-based |
sources |
SourceItem[] |
是 | ≥1,§4.3 |
GetCollectionQuery — GET /collections/get
| 字段 | 位置 | 必填 | 说明 |
|---|---|---|---|
collection_id |
Query | 是 | |
version_id |
Query | 否 | 指定时用该版本展示 stats / status / camera / keypoints |
GetVersionTreeQuery — GET /collections/version-tree
| 字段 | 位置 | 必填 | 说明 |
|---|---|---|---|
collection_id |
Query | 是 |
UpdateCollectionRequest — POST /collections/update
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_id |
string | 是 | |
version_id |
string | 是 | 须等于 editable_version_id(draft 工作副本) |
name |
string | 否 | 非空时仅更新 BFF 展示名 |
description |
string | 否 | 非空时同步下游 |
task_types |
string[] | 否 | 非空时仅增量添加 |
labels |
string[] | 否 | 非空数组时全量替换;传 [] 或不传则不更新 labels |
keypoints_configs |
KeypointCategoryConfig[] |
否 | 非空数组时全量替换;仅 keypoint 任务;结构 §6.6。skeleton 前端传 0-based,BFF 写下游时转为 COCO 1-based |
SwitchBaselineRequest — POST /versions/switch-baseline
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_id |
string | 是 | |
version_id |
string | 是 | 须为已封存 formal(versions[] 内项) |
SwitchVersionRequest — POST /versions/switch(已废弃)
| 字段 | 类型 | 必填 |
|---|---|---|
collection_id |
string | 是 |
version_id |
string | 是 |
SaveVersionRequest — POST /versions/save
| 字段 | 类型 | 必填 |
|---|---|---|
collection_id |
string | 是 |
version_id |
string | 是 |
PromoteSnapshotRequest — POST /versions/promote-snapshot
| 字段 | 类型 | 必填 |
|---|---|---|
collection_id |
string | 是 |
snapshot_version_id |
string | 是 |
ListSamplesRequest — POST /samples/list
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_id |
string | 是 | |
version_id |
string | 是 | 通常等于当前查看版 |
name |
string | 否 | 文件名模糊搜索 |
labels |
string[] | 否 | 样本 labels 列任意命中(OR) |
is_labeled |
bool | 否 | 省略=全部;指针字段,仅 JSON true/false 生效 |
annotation_task_types |
string[] | 否 | 任务真子集筛选/裁剪;与 is_labeled 组合语义 §4.7.2;「全部」Tab 可单独传(仅裁剪响应) |
page |
int | 否 | 默认 1 |
page_size |
int | 否 | 默认 20,上限 100 |
ImportSamplesRequest — POST /samples/import
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_id |
string | 是 | |
version_id |
string | 是 | 须等于 editable_version_id(draft) |
sources |
SourceItem[] |
是 | ≥1 |
labels |
string[] | 否 | 补数时可追加标签 |
DeleteSamplesRequest — POST /samples/delete
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_id |
string | 是 | |
version_id |
string | 是 | 须等于 editable_version_id(draft) |
sample_ids |
uint64[] | 是 | 非空;来自 SampleItem.id |
ExportDatasetRequest — POST /export
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
collection_id |
string | 是 | |
version_id |
string | 是 | 任意存在版本均可 |
target_path |
string | 是 | 导出目标目录 |
export_name |
string | 是 | 导出任务名 |
export_format |
string | 是 | §4.4 |
ParseLabelsRequest — POST /labels/parser
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_types |
string[] | 是 | ≥1 |
sources |
SourceItem[] |
是 | ≥1 |
collection_id |
string | 否 | 与 version_id 成对非空时合并 DB 已有 labels;关键点任务时同时合并已有 keypoints_configs |
version_id |
string | 否 | 同上;只传其一时忽略 |
SourceItem
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
source_type |
string | 是 | dataspace | datageneration |
path |
string | 条件 | §4.3 |
6.2 响应体 data
ListCollectionsResponse
| 字段 | 类型 | 说明 |
|---|---|---|
list |
CollectionCard[] |
|
total |
int64 | DB 分页总数;不随 task_types 内存筛选减少 |
page |
int | |
page_size |
int |
CreateCollectionResponse
| 字段 | 类型 | 说明 |
|---|---|---|
collection_id |
string | dc_* |
version_id |
string | 首个封存 formal dv_*(创建响应;draft 由 save/switch 显式 fork) |
job_id |
string | 首次导入任务 ID |
status |
string | running |
status_text |
string | 运行中 |
UpdateCollectionResponse
| 字段 | 类型 | 说明 |
|---|---|---|
collection_id |
string | 成功确认;不返回 dirty 标记 |
SwitchBaselineResponse
| 字段 | 类型 | 说明 |
|---|---|---|
baseline_version_id |
string | 切换后的基准 formal id |
editable_version_id |
string | 新 fork 的 draft id |
version_name |
string | 目标 formal 名(如 V2) |
version_type |
string | formal |
version_creator_id |
string | 新 draft 操作人展示名(omitempty) |
job_id |
string | clone 任务 ID(omitempty) |
SwitchVersionResponse(已废弃)
接口返回 40000;下列字段仅作历史参考。
| 字段 | 类型 | 说明 |
|---|---|---|
current_version_id |
string | |
version_name |
string | |
version_type |
string |
SaveVersionResponse
| 字段 | 类型 | 说明 |
|---|---|---|
saved_version |
VersionBrief |
新封存的 formal Vn |
based_on_version |
VersionBrief |
封存血缘父版本(omitempty) |
baseline_version |
VersionBrief |
保存后基准,与 saved_version 相同(omitempty) |
editable_version |
VersionBrief |
新 fork 的 draft |
sealed_version |
VersionBrief |
兼容别名 = saved_version |
job_id |
string | clone 任务 ID |
PromoteSnapshotResponse
| 字段 | 类型 | 说明 |
|---|---|---|
version_id |
string | 新 formal 版本 ID |
version_name |
string | |
version_type |
string | 固定 formal |
source_snapshot_id |
string | 源 snapshot 版本 ID |
job_id |
string | clone 任务 ID(可选 omitempty) |
ListSamplesResponse
| 字段 | 类型 | 说明 |
|---|---|---|
list |
SampleItem[] |
|
total |
int64 | 与当前 Tab/筛选一致 |
page |
int | |
page_size |
int | |
status_stats |
SampleStatusStats |
Tab 计数 |
task_status_stats |
map[string]TaskStats |
key 为 BFF task_type |
ImportSamplesResponse
| 字段 | 类型 | 说明 |
|---|---|---|
job_id |
string | 导入任务 ID |
status |
string | running |
status_text |
string | 运行中 |
imported_count |
int | 当前固定 0 |
响应结构体虽保留
forked等 omitempty 字段,当前实现不再 fork;补数须传editable_version_id。
DeleteSamplesResponse
| 字段 | 类型 | 说明 |
|---|---|---|
deleted_count |
int64 | 实际删除条数 |
version_id |
string | 实际操作的 draft id(omitempty) |
无
forked/clone_job_id业务语义。
ExportDatasetResponse
| 字段 | 类型 | 说明 |
|---|---|---|
job_id |
string | 导出任务 ID |
status |
string | running |
status_text |
string | 运行中 |
ParseLabelsResponse
| 字段 | 类型 | 说明 |
|---|---|---|
labels |
string[] | 预解析标签名;可为空数组 |
keypoints_configs |
KeypointCategoryConfig[] |
仅含 keypoint 任务且解析/合并结果非空时出现;结构 §6.6;skeleton 为 0-based;含 used |
{
"labels": ["person"],
"keypoints_configs": [
{
"name": "person",
"used": true,
"keypoints": ["nose", "l_eye", "r_eye"],
"skeleton": [[0, 1], [1, 2]]
}
]
}
DELETE /collections/delete、DELETE /versions/delete 成功时 data 为 {}。
6.3 CollectionCard
列表 / 详情共用结构;list 省略 versions[](BuildCollectionListCard),get 含 versions[](BuildCollectionCard)。stats 与 task_status_stats list / get 均有。
| 字段 | 类型 | 说明 |
|---|---|---|
collection_id |
string | BFF 逻辑 ID,dc_* |
name |
string | 展示名 |
description |
string | 描述(omitempty) |
dataset_kind |
string | training | testing |
task_types |
string[] | BFF snake_case 任务类型 |
labels |
string[] | 数据集级类别标签(omitempty) |
creator |
string | 当前查看版本对应 core 数据集创建者(omitempty) |
create_time |
string | BFF 本地创建时间,RFC3339(omitempty) |
status |
string | §3.2 CollectionCard.status 全集 |
status_text |
string | 中文展示文案 |
camera_intrinsics |
CameraIntrinsics |
仅 stereo_depth 任务;见 §6.5 |
keypoints_configs |
KeypointCategoryConfig[] |
仅含 keypoint 任务;见 §6.6;读响应含 used |
current_version |
VersionBrief |
兼容:等同 baseline_version |
highest_version |
VersionBrief |
最高已封存 formal(omitempty) |
baseline_version |
VersionBrief |
当前编辑基准(omitempty) |
editable_version |
VersionBrief |
draft 工作副本;version_type=draft 时 version_name 常为空 |
version_count |
int | 已封存 formal 数量 |
versions |
VersionSummary[] |
仅 get 返回;已封存 formal;详情历史下拉 / 训练选版数据源(omitempty) |
stats |
CollectionStats |
当前查看版本样本统计(omitempty);list / get 均有 |
task_status_stats |
map[string]TaskStats |
list / get 均返回;按任务类型 labeled / unlabeled / total(omitempty);见 §6.9 |
6.4 VersionBrief / VersionSummary
VersionBrief(highest_version / baseline_version / current_version / editable_version / save 响应内嵌)
| 字段 | 类型 | 说明 |
|---|---|---|
version_id |
string | dv_* |
version_name |
string | formal 如 V1;draft 通常为空 |
version_type |
string | formal | draft(snapshot 已废弃,不再新建) |
version_creator_id |
string | d-cloud userName;draft 操作人或封存作者(omitempty) |
VersionSummary(get 的 versions[])
| 字段 | 类型 | 说明 |
|---|---|---|
version_id |
string | |
version_name |
string | |
version_type |
string | formal(snapshot 仅历史存量) |
saved_at |
string | 封存时间 RFC3339;非空表示已 save(omitempty) |
saved_by |
string | 封存操作者 user ID(omitempty) |
version_creator_id |
string | 操作人展示名;存量行 fallback saved_by(omitempty) |
description |
string | 版本描述(omitempty) |
is_latest |
bool | 是否为最新封存的 formal |
is_baseline |
bool | 是否为当前基准 |
based_on_version_id |
string | 封存时记录的基准版本 id(omitempty) |
based_on_version_name |
string | 血缘展示,如「基于 V1」(omitempty) |
has_task_binding |
bool | 是否被训练/评测任务绑定;true 时不可 delete |
6.4.1 VersionTreeNode — GET /collections/version-tree 响应
| 字段 | 类型 | 说明 |
|---|---|---|
version_id |
string | BFF 版本 id(omitempty) |
dataset_id |
string | 兼容字段,值为 collection_id |
collection_id |
string | |
version |
string | 版本名,如 V1 |
status |
string | 固定 published |
description |
string | omitempty |
related_version |
string | 父版本名;根节点为空字符串 |
current_flag |
bool | 是否为当前基准(baseline_version_id) |
is_latest |
bool | 是否为最高封存 formal(omitempty) |
version_creator_id |
string | 操作人展示名(omitempty) |
created_at |
string | RFC3339;优先 saved_at |
updated_at |
string | RFC3339 |
children |
VersionTreeNode[] |
子节点,递归同结构 |
6.5 CameraIntrinsics
深度任务相机内参,来自 dataset-core extra_info,只读展示。
| 字段 | 类型 | 说明 |
|---|---|---|
fx |
float64 | 焦距 x |
fy |
float64 | 焦距 y |
cx |
float64 | 主点 x |
cy |
float64 | 主点 y |
baseline |
float64 | 双目基线(与深度单位一致) |
"camera_intrinsics": {
"fx": 718.856,
"fy": 718.856,
"cx": 607.1928,
"cy": 185.2157,
"baseline": 0.5327
}
6.6 KeypointCategoryConfig
关键点骨架配置;读(get/list/labels/parser)时 BFF 将 core skeleton 下标归一化为 0-based(减去 core index_base,该字段不对外暴露);写(create/update)时前端同样按 0-based 传 skeleton,BFF 固定按 COCO 格式写入下游(index_base=1,skeleton 各下标 +1)。keypoints 各元素 name 非空时即按此约定处理。
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 类别名,与标注 label、collection labels 一致 |
used |
bool | 该类别配置是否已被样本标注使用;仅读响应(get/list/labels/parser)由下游透传;create/update 写入时 BFF 不发送该字段 |
keypoints |
string[] | 关键点名称列表;数组下标即 skeleton 引用索引(0 起) |
virtual_initial_points |
float[][] | 虚拟初始点 [x, y] 列表, 坐标为归一化值 (相对图像宽高, 通常 0~1), 数组长度与 keypoints 对齐 (omitempty) |
skeleton |
int[][] | 骨架连线 [i, j] 对;i/j 为 keypoints 数组下标,0 起(omitempty) |
读响应示例(CollectionCard / ParseLabelsResponse 中的 keypoints_configs):
"keypoints_configs": [
{
"name": "person",
"used": true,
"keypoints": ["nose", "l_eye", "r_eye", "l_shoulder", "r_shoulder"],
"virtual_initial_points": [[0.5, 0.375], [0.47, 0.34], [0.53, 0.34], [0.44, 0.56], [0.56, 0.56]],
"skeleton": [[0, 1], [0, 2], [3, 4]]
}
]
create / update 请求示例(BFF 会将 skeleton 转为 [[1,2],[1,3],[4,5]] 写入下游, virtual_initial_points 原样透传;无需传 used):
{
"dataset_kind": "training",
"name": "pose-v1",
"task_types": ["keypoint"],
"labels": ["person"],
"sources": [{ "source_type": "dataspace", "path": "/data/pose" }],
"keypoints_configs": [
{
"name": "person",
"keypoints": ["nose", "l_eye", "r_eye", "l_shoulder", "r_shoulder"],
"virtual_initial_points": [[0.5, 0.375], [0.47, 0.34], [0.53, 0.34], [0.44, 0.56], [0.56, 0.56]],
"skeleton": [[0, 1], [0, 2], [3, 4]]
}
]
}
{
"collection_id": "dc_xxx",
"version_id": "dv_xxx",
"keypoints_configs": [
{
"name": "person",
"keypoints": ["nose", "l_eye", "r_eye", "l_shoulder", "r_shoulder"],
"virtual_initial_points": [[0.5, 0.375], [0.47, 0.34], [0.53, 0.34], [0.44, 0.56], [0.56, 0.56]],
"skeleton": [[0, 1], [0, 2], [3, 4]]
}
]
}
6.7 CollectionStats
| 字段 | 类型 | 说明 |
|---|---|---|
total_count |
int64 | 样本总数 |
labeled_count |
int64 | 已标注数 |
unlabeled_count |
int64 | 未标注数 |
6.8 SampleItem
| 字段 | 类型 | 说明 |
|---|---|---|
id |
uint64 | 样本 ID;samples/delete 的 sample_ids 元素 |
type |
string | train / val / test / error,§4.8 |
name |
string | 展示名(basename) |
storage_path |
string | 对象存储路径(omitempty) |
width |
int | 图片宽度(像素) |
height |
int | 图片高度(像素) |
annotations |
object | 按 task_type 分 key;各 value 结构 §4.6 |
task_annotation_statuses |
object | key=task_type,value=labeled|unlabeled |
labels |
string[] | 样本级标签(omitempty) |
is_labeled |
bool | 行级是否已标注 |
status |
string | core 行级状态透传(omitempty),§4.8 |
status_text |
string | 展示文案(omitempty) |
last_update_time |
int64 | 更新时间 Unix 秒(omitempty) |
thumbnail_url |
string | BFF 预留;当前恒为空字符串 |
6.9 SampleStatusStats / TaskStats
SampleStatusStats(ListSamplesResponse.status_stats)
| 字段 | 类型 | 说明 |
|---|---|---|
labeled |
int64 | 已标注 Tab 计数 |
unlabeled |
int64 | 未标注 Tab 计数 |
TaskStats(CollectionCard.task_status_stats[task_type](list / get)/ ListSamplesResponse.task_status_stats(samples/list))
| 字段 | 类型 | 说明 |
|---|---|---|
labeled |
int64 | 该任务已标注数 |
unlabeled |
int64 | 该任务未标注数 |
total |
int64 | 该任务样本总数 |
6.10 前端辅助:canMutate / 版本条显示
function editableVersionId(c: CollectionCard) {
return c.editable_version?.version_id || '';
}
function baselineVersionId(c: CollectionCard) {
return c.baseline_version?.version_id || c.current_version?.version_id || '';
}
const canMutate = Boolean(editableVersionId(card));
// 版本条:有 highest/baseline/versions 或非 creating 且有 draft 即展示(见 testui showCollectionVersionBar)
7. 接口索引
| # | Method | Path |
|---|---|---|
| 1 | POST | /collections/list |
| 2 | POST | /collections/create |
| 3 | GET | /collections/get |
| 4 | GET | /collections/version-tree |
| 5 | POST | /collections/update |
| 6 | DELETE | /collections/delete |
| 7 | POST | /versions/switch-baseline |
| 7.1 | POST | /versions/switch(deprecated) |
| 8 | POST | /versions/save |
| 9 | POST | /versions/promote-snapshot(deprecated) |
| 10 | DELETE | /versions/delete |
| 11 | POST | /samples/list |
| 12 | POST | /samples/import |
| 13 | POST | /samples/delete |
| 14 | POST | /export |
| 15 | POST | /labels/parser |
修改 DTO / 状态映射时请同步更新本文、dataset_swagger.json、dataset_frontend_integration_guide.md 与 dataset_changelog_since_merge_dev_32.md。