TBC/api_docs/dataset_api.md

69 KiB
Raw Permalink Blame History

视觉感知工作台 · 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):

  1. 默认列表/详情(无 version_id):stats/status 取自 最高封存版(highest_version 对应 core);baseline_version_id 低于最高版时(已 switch-baseline)改取 可编辑 draft(editable_version_id)。
  2. GET ?version_id=<formal>:stats 取自该 formal 行;非当前主线且映射为 tobepublished 时对外改为 published(历史只读)。
  3. 若 stats 版本 clone_status=switching(switch-baseline fork 新 draft)→ switching;clone_status=running 且 save 封存进行中 → publishing。
  4. 否则将 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,与代码一致):

  1. 若字符串首字符为 /,去掉一个前导 /;
  2. 再 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 分支):

  1. IC / 深度单任务 且传了 is_labeled → BFF 本地按 SampleItem.is_labeled 扫页;忽略 annotation_task_types。
  2. 纯视觉任务集 + is_labeled 已传 + annotation_task_types 非空 → BFF 本地按 task_annotation_statuses AND 扫页(已标=指定分支全部已标;未标=指定分支全部未标)。
  3. is_labeled 省略 + annotation_task_types 非空 → core 全量列表;BFF 仅裁剪 list[] 中任务字段。
  4. 其他 → 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。