figmar/deepdata

Fork 0

Table of Contents

使用说明

一、登录与首页
二、数据归集
三、数据管理
四、数据清洗

参数面板说明
常用算子速查
文档解析算子配置

五、数据标注

5.1 创建标注任务
5.2 Label Studio 同步特点
5.3 完整标注作业流程

六、标注作业 SOP（Label Studio 对接）

6.1 代码实况：平台硬编码为 Label Studio
6.2 四阶段可执行性判定
6.3 可执行流程（Label Studio）

阶段一：任务发起（DeepData）
阶段二：团队与分工（Label Studio 侧）
阶段三：标注与审核（Label Studio 侧）
阶段四：结果回收（DeepData）

6.4 数据落库机制（核实细节）
6.5 若未来要接入 CVAT
6.6 原始 SOP 参考材料（逐字照抄）

第一阶段：任务发起 (DeepData)
第二阶段：团队组建与任务分发 (CVAT)
第三阶段：标注与审核执行 (CVAT)
第四阶段：结果回收 (DeepData)
流程总结图解
针对 1000 张图的建议
SOP 原文与代码实况对照

七、数据评估
八、数据合成

合成任务
配比任务

九、知识生成（RAG）
十、算子市场

上传规范
常见上传失败

十一、可视化编排与 Agent

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

使用说明

界面操作指南 + 完整标注作业 SOP。

一、登录与首页

访问 http://<host>:30000，使用平台账号登录。首页提供各模块入口与统计概览。

修改密码：右上角头像 → 修改密码，需提供旧密码，新密码最少 6 位（后端 ChangePasswordRequest 约束：旧密码非空、新密码非空且长度 ≥ 6）。

二、数据归集

数据归集 → 新建归集模板 → 配置数据源 → 创建归集任务。

支持 NFS / S3 / GlusterFS / HTTP API / 数据库（DataX 全插件）/ 文件数据库。选择源时需填写连接参数与目标路径。

任务执行状态存于 t_dc_collection_tasks，明细在 t_dc_task_executions。

三、数据管理

数据管理 → 创建数据集 → 上传/导入文件。

上传方式：直接上传 / 归集导入 / 分片上传（大文件走 t_chunk_upload_request）。

标签体系：在数据集上配置标签（t_dm_tags），支持 t_dm_dataset_tags 关联。

血缘追溯：t_lineage_node + t_lineage_edge 记录加工链路，可查"这个文件怎么来的"。

四、数据清洗

数据清洗 → 创建清洗模板 → 拖拽算子到画布 → 连线编排 → 配置参数 → 提交。

参数面板说明

算子的参数面板由metadata.yml 的 settings 字段驱动，零代码生成：

settings:
  fileDuplicateThreshold:
    type: slider
    label: 相似度阈值
    defaultVal: 0.5
    min: 0
    max: 1
    step: 0.1

支持的控件类型：slider / switch / select / radio / range / checkbox / input / textarea / inputNumber / multiSelect。

常用算子速查

需求	算子
去除相似文档	`remove_duplicate_file`（MinHash + Jaccard）
过滤敏感词	`remove_file_with_many_sensitive_words`
文本清洗	`content_cleaner`、`extra_space_cleaner`、`garble_characters_cleaner`
全半角统一	`full_width_characters_cleaner`
简繁转换	`traditional_chinese`
PII 清洗	`email_cleaner`、`phone_number_cleaner`、`id_number_cleaner`、`ip_address_cleaner`、`url_cleaner`、`credit_card_number_cleaner`
图像增强	`img_enhanced_brightness` / `contrast` / `saturation` / `sharpness`
图像纠偏	`img_direction_correct`、`img_perspective_transformation`
模糊图剔除	`img_blurred_images_cleaner`
广告图剔除	`img_advertisement_images_cleaner`
文档解析	`mineru_formatter`、`MarkItDownParser`（自建）、`MinerUPdfParser`（自建）
质量评分	`text_quality_evaluation`、`TextQualityEvaluator`（自建）

文档解析算子配置

MarkItDownParser（my_ops/markitdown_parser）：支持 doc_formats 多选（docx/doc/xlsx/pptx/txt/csv/xml/html/htm 等）、download_remote_images（远程图片下载）、embed_images_base64（Base64 内联）、max_image_width、upload_images。

MinerUPdfParser（my_ops/mineru_pdf_parser）：需配置 mineruApi（远端服务地址）、server_url、backend（pipeline / vlm-http-client / hybrid-http-client）、lang_list（默认 ch）、parse_method（auto/ocr/txt）、formula_enable、table_enable、return_images、timeout（60~3600秒，默认 900）。需确保 MinerU 服务已启动（compose profile mineru，需 Ascend NPU）。

⚠️ 两个算子的 API 地址与图床地址默认值指向内网地址，部署到新环境时必须修改。

五、数据标注

5.1 创建标注任务

数据标注 → 创建标注任务：

填写任务名称（必填，≥3 字符 —— 此限制来自 Label Studio）
选择标注模板（必填，如目标检测）
通过数据集文件组件逐个勾选文件
描述（选填）
确定

⚠️ 没有"平台选择" —— 标注平台在代码中硬编码为 Label Studio，创建弹窗无平台下拉。详见 6.1。

创建后在任务列表可见，操作菜单含"标注"、"同步到数据库"、"导出标注结果"。

5.2 Label Studio 同步特点

Label Studio 走内置双向同步服务：

ls_annotation_sync.py 更新 tags / tags_updated_at / annotation
sync.py 实现双向覆盖，按 tags_updated_at 比较决定谁覆盖谁
interface/task.py 支持部分标签合并（只改提交的标签，其余保持）

自动标注：开启 AUTO_ANNOTATION_ENABLED + 配置 ANNOTATION_MODEL_ENDPOINT 后，可先由模型生成预标注。

⚠️ 注意：创建标注任务弹窗中的「自动标注」Tab 当前已被整段注释屏蔽（CreateAnnotationTaskDialog.tsx:333-380, 542-638），该路径暂时不可用。

5.3 完整标注作业流程

见下一节。

六、标注作业 SOP（Label Studio 对接）

⚠️ 重要更正：本章原标题为「DeepData/CVAT 标注作业流程SOP」，源自飞书文档。经代码核实，当前 DeepData 并未集成 CVAT，唯一支持的标注平台是 Label Studio。

原始参考材料（逐字照抄）见 /Users/figmarlite/deepdata-sources/01-feishu-sop/

逐条核实结论见 03-code-verification/sop-vs-code-核实报告.md

本章先给出代码实况（可执行），再附原始 SOP 原文（设计意图，含未实现部分）。

6.1 代码实况：平台硬编码为 Label Studio

全库 2752 个跟踪文件搜索 cvat（含变体 cvat2d/cvat.org/tagging.cvat/opentarget）零命中。硬编码三处：

#	位置	证据
1	客户端目录只有 `client/labelstudio/`	无平台抽象层/工厂类
2	直接实例化 LS 客户端	`interface/project.py:728-731` `LabelStudioClient(...)`
3	表字段注释写死	`scripts/db/data-annotation-init.sql:69` `labeling_project_id IS 'Label Studio项目ID'`，类型 `VARCHAR(8)`（LS 数字型 project ID 宽度，装不下 UUID 形式的 CVAT task ID）

前端亦无 platform 概念：创建标注任务弹窗的真实表单只有 4 个字段 —— 任务名称、标注模板、数据集文件、描述（CreateAnnotationTaskDialog.tsx:311-317）。

6.2 四阶段可执行性判定

SOP 阶段	平台	可执行	说明
一、任务发起	DeepData	⚠️ 部分	创建弹窗存在，但无平台下拉；模板/数据集/文件选择可用
二、团队组建与任务分发	CVAT	❌ 不可执行	无 CVAT；DeepData 也无 Organization / Job 切分 / Assignee 概念
三、标注与审核执行	CVAT	❌ 不可执行	无 CVAT；无 annotation→validation→completed 状态机，无 Accept/Reject 审核流
四、结果回收	DeepData	⚠️ 形式存在，实质为 LS	按钮与接口真实存在、确实写 `tags` 字段，但拉取源是 Label Studio

6.3 可执行流程（Label Studio）

阶段一：任务发起（DeepData）

操作人：数据管理员

准备外部条件：先部署 Label Studio（compose profile label-studio），配置 .env 中的 LABEL_STUDIO_BASE_URL、LABEL_STUDIO_USERNAME、LABEL_STUDIO_USER_TOKEN、LABEL_STUDIO_PASSWORD。
创建标注模板（若尚无模板）：
- 数据标注 → 模板管理 → 新建。
- 选择 data_type（image / text / audio / video）与 labeling_type。
- 在配置区用 Label Studio 的 XML <Choices> 语法定义标签，如目标检测：
```
<Choices>
  <Choice value="Person"/>
  <Choice value="Car"/>
</Choices>
```
- 标签类型受 runtime/deepdata-python/app/module/annotation/config/label_studio_tags.yaml 白名单约束（Audio / Bitmask / PDF / ParagraphLabels / Vector 等）。
创建标注任务：
- 数据标注 → 创建标注任务。
- 填写任务名称（必填，≥3 字符 —— 此限制来自 Label Studio）、选择标注模板（必填）。
- 通过 DatasetFileTransfer 组件逐个勾选文件（不是选整个数据集）。
- 描述（选填）。
- 确定。
确认状态：任务列表出现新任务，操作菜单含"标注"、"同步到数据库"、"导出标注结果"。

注意：创建弹窗原本有「自动标注」Tab，当前已被整段注释屏蔽（CreateAnnotationTaskDialog.tsx:333-380, 542-638），因此"先自动标注生成预标注再送审"这条路目前走不通。

阶段二：团队与分工（Label Studio 侧）

Label Studio 没有 DeepData 侧的"团队/Job切分/指派"概念。分工在 Label Studio 内自行组织：标注员用独立账号登录，打开分配给自己的 task。

阶段三：标注与审核（Label Studio 侧）

标注员在 Label Studio 内标注并提交。若需审核流程，由 Label Studio 自身的组织与审核规则承担（DeepData 不介入）。

阶段四：结果回收（DeepData）

操作人：数据管理员

确认完工：在 Label Studio 中确认任务标注完成。
同步回 DeepData：
- 数据标注 → 找到对应任务 → 操作菜单 → "同步到数据库"。
- 确认对话框会明确提示"将「任务名」在 Label Studio 中的标注结果同步到数据库吗？"。
- 后端接口：POST /api/annotation/project/{mapping_id}/sync-db（interface/project.py:707-753）。
验证数据：
- 进入 数据管理 → 找到原始数据集。
- 查看文件列表的标签/标注列，应显示具体类别名（如 Person、Car）。
- 点击文件预览，右侧信息栏显示结构化标注详情。
导出（注意差异）：
- 自动标注任务：操作菜单"导出标注结果"是真正的打包下载（GET /api/annotation/auto/{taskId}/download，interface/auto.py:870）。
- 手动标注任务：同名按钮实际执行 sync-label-studio-back，把 Label Studio 结果导成文件写回数据集，并非打包下载。界面文案与实际行为不一致，属已知缺陷。

6.4 数据落库机制（核实细节）

标注结果写入 t_dm_dataset_files 的 tags（JSONB）与 tags_updated_at（冲突消解用），完整标注结果写入 annotation。

标签结构归一化为 {id, type, from_name, to_name, values}，values 以 type 为键（如 rectanglelabels），前端通过 tag.values[tag.type] 解析（ls_annotation_sync.py:164-229）。

两条写入路径：

路径	位置	方式
单向回写	`ls_annotation_sync.py:141-144`	直接赋值，整体覆盖
双向同步	`sync.py:763-809`	走 ORM update，带时间戳冲突判断

双向同步冲突消解（sync.py:606-654，纯时间戳比较，无字段级合并）：

方向	方法	行为
LS → DM	`_should_overwrite_dm`（:606-627）	`overwrite=False` → 不覆盖；DM 无时间戳 → 允许覆盖；否则比时间戳
DM → LS	`_should_overwrite_ls`（:629-654）	`overwrite_ls=False` → 不覆盖；DM 无时间戳 → 不覆盖（不对称）；否则比时间戳

⚠️ 对称性差异：两者对"缺失时间戳"处理相反 —— DM 无戳时 LS 可覆盖 DM（:623-624），但 DM 无戳时 DM 不覆盖 LS（:646-647）。是否为有意设计待确认。

6.5 若未来要接入 CVAT

SOP 第四阶段"写入 t_dm_dataset_files.tags"这个设计对 CVAT 不成立，接CVAT 时需重新设计：

维度	Label Studio（当前假设）	CVAT
任务层级	task → annotations	task → job → frame
标注载体	task.annotations（JSON）	frame 级 annotation JSON
导出方式	API 直接取 JSON	`/api/tasks/{id}/annotations`（文件）
predictions	有（模型预标注）	无此概念
文件关联	`task.data.file_id`	需经 job/frame 索引反查

现有实现强依赖 LS 的两个特有字段：task.data.file_id（ls_annotation_sync.py:68）、task.predictions（ls_annotation_sync.py:91）；冲突消解方法参数也直接命名为 ls_updated_at（sync.py:606、:629）。

接入清单（从零开发，非打开开关）：

新增 client/cvat/ 平台客户端（REST API：创建 Task/Job、查询 frame 标注、导出 annotations）
引入平台抽象层（当前 client/ 下只有 labelstudio/，无工厂类）
t_dm_labeling_projects 加 platform 字段，labeling_project_id 类型需放宽（CVAT task ID 是 UUID，VARCHAR(8) 装不下）
重新设计 frame_id ↔ file_id 映射（经 job/frame 索引反查）
替换冲突消解的时间戳来源（CVAT 无 per-task updated_at 语义）
前端创建弹窗加平台下拉，i18n 补 CVAT 文案
mapping.py（483 行）的 DM↔LS 映射逻辑需抽象化

6.6 原始 SOP 参考材料（逐字照抄）

以下为飞书文档《DeepData/CVAT的标注作业流程SOP》原文，完整保留以记录设计意图。⚠️ 其中 CVAT 相关步骤在当前代码中不可执行（见 6.1 / 6.2）。

来源：https://my.feishu.cn/wiki/FxOJwtOUXi9gm2kFMzQc20epn4b 文档 ID LP8rdgNmsoKdYMxmo6Uc0G2Pnqf · 所属空间 supercrawler的云文档 · 最近修改 2026-10-02 本地存档：/Users/figmarlite/deepdata-sources/01-feishu-sop/feishu-cvat-sop-原文照抄.md 抓取方式：提取页面 SSR 内嵌 Slate JSON（161 blocks，has_more: false，全文完整）

核心原则：DeepData 负责**"管数据（发起与回收）"，CVAT 负责"管人与流程（分配、标注、审核）"**。

以下为针对图片标注任务的完整实操流程：

第一阶段：任务发起 (DeepData)

操作人：数据管理员

创建标注任务：
- 登录 DeepData → 进入"数据标注" → 点击"创建标注任务"。
- 选择包含 1000 张图的数据集。
- 关键设置：平台选择 CVAT，选择合适的标注模板（如"目标检测"）。
- 点击确定。
确认状态：
- 在任务列表中看到新任务，显示"前往 CVAT"。
- 此时 CVAT 后台已生成了一个包含 1000 张图的任务（Task）。

第二阶段：团队组建与任务分发 (CVAT)

操作人：项目经理 (Supervisor/Admin)

1. 组建团队 (Organization)

如果是第一次使用，需先建组；已建组可跳过。

登录 CVAT，点击右上角头像 → Settings → Organizations。
点击 Create Organization（如命名为 DeepData_Label_Team）。
点击 Invite，输入标注员和审核员的邮箱，邀请他们加入。
分配角色：
- 标注人员设置为 Worker（只能标注）。
- 审核人员设置为 Reviewer 或 Supervisor（能审核）。

2. 任务切分 (Segmentation) —— 关键步骤

1000 张图太大，必须拆分成小块 (Jobs) 才能分给多人同时做。

在 CVAT 左侧菜单点击 Tasks，找到 DeepData 创建的任务（通常以 DeepData 任务名命名，如 cvat8-检测）。
进入任务详情页，找到 Jobs 标签页。
点击右上角 Edit 或 Settings。
设置 Job Size（切分粒度）：
- 建议设置为 20-50 张图/Job。
- 例如：设为 50，系统会自动将 1000 张图切分为 20 个 Job。
- 保存设置（系统可能需要一点时间处理切片）。

3. 分配工作 (Assignment)

在 Jobs 列表中，你会看到 20 个 Job。
指派标注员 (Assignee)：
- 点击 Job 1 → Assignee 下拉框 → 选择标注员 A。
- 依次将 20 个 Job 分配给组内的 Worker。
指派审核员 (Reviewer)：
- 点击 Job 1 → Reviewer 下拉框 → 选择审核员 B。
- 建议一人审核多个 Job。

第三阶段：标注与审核执行 (CVAT)

操作人：标注员 & 审核员

1. 标注员工作 (Worker)

登录 CVAT，点击左侧 Jobs → Assigned to me。
打开分配的 Job，进入标注界面。
操作：
- 根据模板要求画框/选标签。
- 完成后点击工具栏的 Save 和 Submit 按钮。
- 状态流转：Job 状态从 annotation 变为 validation（待审核）。

2. 审核员工作 (Reviewer)

登录 CVAT，点击左侧 Jobs → Validation（待我审核）。
打开状态为 validation 的 Job。
检查：查看标注质量。
- ✅ 通过：点击 Accept。
  - 结果：Job 状态变为 completed。
- ❌ 驳回：点击 Reject 并在评论区写明原因（如"漏标"、"框不准"）。
  - 结果：Job 状态回退为 annotation，标注员收到通知需重新修改。
循环：标注员修改后再次提交，直到所有 Job 状态均为 completed。

第四阶段：结果回收 (DeepData)

操作人：数据管理员

确认完工：
- 在 CVAT 任务列表中，确认该 Task 进度为 100%，所有 Job 状态为 completed。
同步回 DeepData：
- 回到 DeepData 平台 → "标注任务列表"。
- 找到对应任务，点击 "同步到数据库" 按钮。
- 系统行为：DeepData 会连接 CVAT，拉取所有图片对应的最终 JSON 标注数据，并写入 t_dm_dataset_files 表的 tags 字段。
验证数据：
- 进入"数据管理" → 找到原始数据集。
- 查看文件列表的"标签/标注"列，应显示具体的类别名称（如 Person, Car）。
- 点击文件预览，右侧信息栏应显示结构化的标注详情。
归档/导出 (可选)：
- 点击任务右侧的"导出标注结果"，将最终成果打包下载或存入数据集归档。

流程总结图解

步骤	平台	动作	状态变化
1	DeepData	创建任务，选定数据集	数据进入 CVAT
2	CVAT	切分 Job (1000→20 个)	Task 拆分为 Job 列表
3	CVAT	分配人员 (Assignee/Reviewer)	Job 关联到具体用户
4	CVAT	工人标注 → 提交	annotation → validation
5	CVAT	审核员验收 → 通过	validation → completed
6	DeepData	点击"同步到数据库"	JSON 数据写入 DeepData

针对 1000 张图的建议

⚠️ 务必切分：千万不要让一个人标 1000 张图，必须切成 20-50 张一组。
💡 预标注（进阶）：如果想提效，可以在 DeepData 侧先用模型跑一遍"自动标注"，同步到 CVAT 作为初始数据（Pre-annotations），工人只需要修正错误，速度会快 3 倍以上。

SOP 原文与代码实况对照

SOP 步骤	代码实况
平台选择 CVAT	❌ 无平台下拉，硬编码 Label Studio
任务列表显示"前往 CVAT"	⚠️ 文案是"标注"，行为跳 Label Studio
CVAT 后台已生成 Task	❌ 只在 Label Studio 建项目
Job Size 切分 1000→20	❌ 无 Job 概念（LS 是每文件一个 task）
Assignee / Reviewer 分配	❌ 未找到实现
annotation→validation→completed	❌ 无状态机，无 Accept/Reject
"同步到数据库"按钮	⚠️ 存在，但对话框明确写 Label Studio
DeepData 连接 CVAT	❌ 实际连 `label_studio_base_url`
导出标注结果打包下载	⚠️ 仅自动标注任务有 download 端点
选择包含 1000 张图的数据集	⚠️ 实际需逐个勾选文件
自动标注作 Pre-annotations	❌ 自动标注 Tab 已被注释屏蔽

Job 状态机（设计意图，当前未实现）：

annotation ──Submit──▶ validation ──Accept──▶ completed
     ▲                        │
     └────────Reject──────────┘

七、数据评估

数据评估 → 创建评估任务 → 选择待评估文件 → 配置评估维度 → 执行。

常用评估方式：

LLM 多维度评分：text_quality_evaluation 算子 / TextQualityEvaluator 自建算子
QC 拦截：配置 QC_ENABLED + QC_THRESHOLD

评估结果分三级落库：任务（t_de_eval_task）→ 文件（t_de_eval_file）→ 条目（t_de_eval_item）。

八、数据合成

合成任务

数据合成 → 创建合成任务 → 配置数据源与提示词 → 执行。

任务按 chunk 分块执行，明细见 t_data_synthesis_file_instances、t_data_synthesis_chunk_instances。

配比任务

用于多数据集按比例混合（如通用指令 50% + 领域指令 30% + 安全指令 20%）。

配置见 t_st_ratio_instances / t_st_ratio_relations。

九、知识生成（RAG）

知识库 → 创建知识库 → 上传文档 → 解析切片 → 向量化 → 完成。

技术链路：

文档 → MinerU / unstructured 解析 → slicer 切片
     → 向量化(langchain) → Milvus 索引 → rag-indexer-service 提供检索

依赖服务：Milvus（:19530）、MinIO（Milvus 存储层）、GraphRAG（LightRAG 增强）

可用 LLM 评分相关配置：t_rag_knowledge_base、t_rag_file

十、算子市场

算子市场 → 上传自定义算子 → 配置参数 → 在清洗/合成流程中使用。

上传规范

压缩包名（不含后缀）必须与 __init__.py 中 module_path 的包目录名一致，否则 ModuleNotFoundError。

包内必需文件：__init__.py、metadata.yml、process.py。

常见上传失败

报错	原因
`ModuleNotFoundError`	压缩包名与 `module_path` 包目录名不一致
算子不出现在列表	`metadata.yml` 中 `raw_id` 与 `process.py` 类名不一致
参数面板空白	`settings` 字段缺失或格式错误

十一、可视化编排与 Agent

入口	用途
`/orchestration`	基于 xyflow 的工作流画布，多步骤任务编排
`/chat`	Agent 对话入口，配合 MCP 协议（Python 侧 `/mcp`、Java 侧 `/mcp`）

上一页：运维手册｜返回：首页