diff --git a/Home.md b/Home.md index e6c791f..661f750 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,120 @@ -欢迎来到百科。 \ No newline at end of file +# DeepData 一站式数据工作平台 + +> 面向模型微调与 RAG 检索的企业级数据处理平台。覆盖数据归集、数据管理、算子市场、数据清洗、数据合成、数据标注、数据评估、知识生成八大核心模块。 + +本百科随代码演进，内容以 `deepdata-20260928` 分支（commit `ff22ed3`）为基准。所有技术细节均标注来源文件路径，可溯源核查。 + +--- + +## 一句话定位 + +DeepData 把「原始数据」变成「可训练、可检索的语料」——中间的清洗、标注、增强、评估全部在平台内编排完成。 + +对比自建流水线：不需要自己拼 DataX + Spark清洗脚本 + Label Studio + 向量库 + 调度器，DeepData 提供的是**可视化编排 + 算子生态 + 一体化存储**。 + +--- + +## 八大核心模块 + +| 模块 | 作用 | 主要入口 | +|---|---|---| +| 数据归集 | 从 NFS/S3/API/数据库拉数据入库 | `/data/collection` | +| 数据管理 | 数据集、文件、标签、血缘管理 | `/data/management` | +| 算子市场 | 算子注册、打包、上传、复用 | `/data/operator-market` | +| 数据清洗 | 可视化编排清洗流水线 | `/data/cleansing` | +| 数据合成 | 指令数据合成、配比任务 | `/data/synthesis/task`、`/data/synthesis/ratio-task` | +| 数据标注 | 标注项目、自动标注、对接 Label Studio/CVAT | `/data/annotation` | +| 数据评估 | 质量与效果评估 | `/data/evaluation` | +| 知识生成 | RAG 知识库构建、索引 | `/data/knowledge-base` | + +另有可视化编排（`/orchestration`）与 Agent 对话入口（`/chat`）。 + +--- + +## 系统架构一览 + +``` + ┌─────────────────────────┐ + 浏览器 ─────────▶ │ 前端 React18 + Vite7│ :30000 + └───────────┬─────────────┘ + │ /api + ┌───────────▼─────────────┐ + │ 网关 Spring Cloud GW │ :8080 + │ JWT 认证 / SSO / 限流 │ + └───────────┬─────────────┘ + ┌──────────────────┴──────────────────┐ +┌────────────▼─────────────┐ ┌───────────────▼──────────────┐ +│ 主应用 Spring Boot 3.5│ │ Python 后端 FastAPI │ +│ 集成所有业务服务 │ │ :18000 │ +│ data-management │◀──────▶│ 归集/清洗/标注/算子调度 │ +│ rag-indexer │ │ MCP endpoint /mcp │ +└──────┬──────────┬───────┘ └────────┬──────────────┬───────┘ + │ │ │ │ + ┌────▼────┐ ┌───▼────────┐ ┌──────▼─────┐ ┌────▼─────┐ + │PostgreSQL│ │ Milvus │ │ Redis │ │Ray 集群 │ + │ :5432 │ │ :19530 │ │ :6379 │ │ 算子执行 │ + │ 主元数据 │ │ 向量索引 │ │ │ │(可选) │ + └─────────┘ └────────────┘ └────────────┘ └──────────┘ + ▲ + ┌─────┴──────┐ + │ MinIO │ S3 兼容对象存储 + └────────────┘ +``` + +**关键特征**：主应用与 Python 后端是**双后端**架构 —— Java 侧做数据管理与 RAG 索引，Python 侧做算子编排与调度，两者通过 HTTP 互调。 + +--- + +## 核心概念 + +| 概念 | 定义 | 说明 | +|---|---|---| +| 数据集 Dataset | 一批文件的集合 | UUID 主键，存于 `t_dm_datasets` | +| 算子 Operator | 单一处理能力的最小单元 | 有 metadata.yml 描述，支持打包上传 | +| 算子实例 Operator Instance | 算子在具体任务中的一次配置 | 存于 `t_operator_instance` | +| 任务 Task | 一次数据处理执行 | 清洗/标注/合成/评估各自有任务表 | +| Job | CVAT 侧的标注工作切片 | 大任务必须切分才能并行 | +| 血缘 Lineage | 数据加工的上下游关系 | `t_lineage_node` + `t_lineage_edge` | + +--- + +## 百科目录 + +| 章节 | 内容 | +|---|---| +| [需求与定位](需求与定位) | 谁在用、解决什么问题、典型场景与选型判断 | +| [产品功能](产品功能) | 八大模块的功能边界与设计意图 | +| [技术架构](技术架构) | 技术栈、服务拆分、算子执行引擎、数据模型 | +| [部署指南](部署指南) | Docker Compose 与 Helm K8s 两种形态 | +| [运维手册](运维手册) | 日志、健康检查、备份、排障、已知坑 | +| [使用说明](使用说明) | 界面操作指南、CVAT 标注 SOP | + +--- + +## 快速上手 + +```bash +# 1. 准备环境变量 +cp deployment/docker/deepdata/.env.example deployment/docker/deepdata/.env +# 编辑 .env，至少填写 DB_PASSWORD / JWT_SECRET / MINIO_* / LABEL_STUDIO_* + +# 2. 启动核心服务 +docker compose -f deployment/docker/deepdata/docker-compose.yml up -d + +# 3. 访问 +# 前端http://:30000 +# 网关 http://:8080 +``` + +**首次部署注意**：PostgreSQL 初始化脚本只在**数据卷为空时**执行一次（`docker-entrypoint-initdb.d` 机制）。修改 `scripts/db/*.sql` 后不会自动生效，需手工执行或重建数据卷。 + +--- + +## 版本与分支 + +| 分支 | 说明 | commit | +|---|---|---| +| `main` | 早期基线（含 Casdoor SSO 认证与 GitHub Actions CI） | `cbb1048` | +| `deepdata-20260928` | 当前开发基线，本次代码与功能变更所在分支 | `ff22ed3` | + +`main` 上的 `.github/workflows/` CI 与 Casdoor SSO 模块在 `deepdata-20260928` 中不存在 —— 后者基于国内交付版本（走自建镜像仓库）。详见 [运维手册](运维手册#分支差异)。 \ No newline at end of file diff --git a/产品功能.md b/产品功能.md new file mode 100644 index 0000000..ab8abff --- /dev/null +++ b/产品功能.md @@ -0,0 +1,221 @@ +# 产品功能 + +> 本文说明八大模块的**功能边界**与**设计意图**。具体操作步骤见[使用说明](使用说明)，技术实现见[技术架构](技术架构)。 + +--- + +## 模块总览 + +``` +数据归集 → 数据管理 → 数据清洗 → 数据评估 → 数据合成 → 知识生成 + ↓ ↓ + 数据标注 算子市场（支撑清洗/合成/评估） +``` + +算子市场是**横向支撑**模块 —— 清洗、合成、评估都依赖算子；归集与管理是**纵向主线**。 + +--- + +## 1. 数据归集（Collection） + +### 能力 +把外部数据源搬进平台，统一管理来源与归集状态。 + +### 支持的数据源 + +| 类型 | 实现 | 说明 | +|---|---|---| +| NFS | `runtime/datax/nfswriter` | 支持 MountUtil挂载 | +| S3/对象存储 | `runtime/datax/s3reader`、`s3writer` | 含 `HttpEndpointSecurity` | +| GlusterFS | `runtime/datax/glusterfsreader` / `writer` | 分布式文件系统 | +| HTTP API | `runtime/datax/apireader` | 含端点安全校验 | +| 数据库 | `DataX/` 完整插件集 | mysql/postgresql/milvus/hdfs 等近百个 | +| 文件数据库 | `txtfilewriter` | 单独分支处理 | + +### 归集方式 +- **归集模板**：可复用的归集配置（`t_dc_collection_templates`） +- **归集任务**：基于模板发起执行（`t_dc_collection_tasks`） +- **执行明细**：每次执行的日志与结果（`t_dc_task_executions`） + +### 设计意图 +归集是链路的**入口**，设计上强调"来源可追溯"。每条数据都能回溯到是从哪个源、按什么配置采来的。 + +--- + +## 2. 数据管理（Management） + +### 能力 +平台的数据资产中心，管理数据集、文件、标签、血缘。 + +### 核心概念 +- **数据集（Dataset）**：UUID 主键，文件集合的容器（`t_dm_datasets`） +- **数据集文件**：每行一个文件记录，含路径、类型、大小、校验和（`t_dm_dataset_files`） +- **标签体系**：可复用的标签定义（`t_dm_tags`）与数据集标签关联（`t_dm_dataset_tags`） +- **统计信息**：文件数、总量等汇总（`t_dm_dataset_statistics`） + +### 关键字段：`tags` + +`t_dm_dataset_files.tags` 是**JSONB 字段**，承载标注结果（类别、坐标等结构化数据）。配套的 `tags_updated_at` 时间戳用于**双向同步的冲突消解** —— 同步时比较两边时间戳，谁新谁覆盖谁。 + +详见[技术架构 · 数据模型](技术架构#数据模型) 与 [标注 SOP 第四阶段](使用说明#阶段-4结果回收deepdata)。 + +### 血缘 +`t_lineage_node`（实体对象）+ `t_lineage_edge`（处理流程）记录数据加工链路，支持追溯"这个文件是怎么来的"。 + +--- + +## 3. 算子市场（Operator Market） + +### 能力 +算子的注册、打包、上传、分发与版本管理。 + +### 算子分类 + +| 类别 | 数量 | 作用 | 示例 | +|---|---|---|---| +| `filter` | 10 | 过滤/剔除 | `remove_duplicate_file`（MinHash+Jaccard 相似文档去除）、`remove_file_with_many_sensitive_words`、`img_blurred_images_cleaner` | +| `mapper` | 33 | 1:1 转换 | `content_cleaner`、`email_cleaner`/`phone_cleaner`/`id_number_cleaner`（PII 清洗）、`traditional_chinese`、`img_enhanced_brightness`（图像增强） | +| `slicer` | 3 | 1:N 切片 | `slide_annotation_slicer`、`slide_simple_slicer` | +| `formatter` | 2 | 格式转换 | `mineru_formatter`、`slide_formatter` | +| `llms` | 2 | LLM 驱动 | `qa_condition_evaluator`、`text_quality_evaluation` | +| `annotation` | 0 | 预留 | 目录存在但暂无实现 | +| `user` | 0 | 自定义算子落地点 | 算子市场上传的算子落在这里 | +| `examples` | 1 | 示例模板 | `test_operator` | + +### 算子元数据（`metadata.yml`） + +关键字段： + +| 字段 | 作用 | 注意 | +|---|---|---| +| `raw_id` | 算子唯一标识 | **必须与 `process.py` 里的类名完全一致** | +| `types` | 适用场景 | cleanse/cleaning/annotation/collect/consolidate | +| `modal` / `inputs` / `outputs` | 数据模态 | text/image/audio/video | +| `runtime` | 资源声明 | memory/cpu/gpu/npu/storage | +| `settings` | UI 渲染定义 | slider/switch/select/inputNumber/multiSelect 等 | + +`settings` 直接决定前端参数面板怎么渲染 —— 这是算子"零代码可配"的关键。 + +### 内置算子来源 + +内置算子的 `vendor` 为 `huawei`（`runtime/ops/` 下），而 `my_ops/` 下的自建算子 `vendor` 为 `DeepData` / `DeepData User`，两者分离。详见[自定义算子开发](技术架构#自定义算子开发)。 + +--- + +## 4. 数据清洗（Cleansing） + +### 能力 +可视化编排的数据清洗流水线，支持 DataJuicer 引擎。 + +### 核心流程 +1. 从数据集选择待清洗数据 +2. 拖拽算子到画布，连线成流水线 +3. 配置每个算子的参数（来自 `settings`） +4. 提交任务，由Ray 集群（或本地 runtime）执行 +5. 清洗结果写入新数据集或原地更新 + +### 关键表 +`t_clean_template`（模板）、`t_clean_task`（任务）、`t_clean_result`（结果） + +### 执行引擎 +- 主路径：Ray 分布式执行（`runtime/python-executor`，Ray 2.7.0） +- 可选：DataJuicer 容器（compose profile `data-juicer`，镜像 `datajuicer/data-juicer:v1.4.4`） + +### 设计意图 +清洗是**最需要反复调参**的环节，所以做成可视化编排 —— 改参数不需要改代码，流水线拓扑一眼可见。 + +--- + +## 5. 数据合成（Synthesis） + +### 能力 +基于 LLM 生成指令数据，并支持多数据集按配比混合。 + +### 两种任务 +| 任务 | 表 | 说明 | +|---|---|---| +| 合成任务 | `t_data_synth_instances`、`t_data_synthesis_file_instances`、`t_data_synthesis_chunk_instances`、`t_data_synthesis_data` | 单个合成任务，按 chunk 分块执行 | +| 配比任务 | `t_st_ratio_instances`、`t_st_ratio_relations` | 多数据集按比例混合 | + +### 设计意图 +微调数据往往需要"通用指令 + 领域指令 + 安全指令"按特定比例混合。配比任务让这个比例**可配置、可复用**，而不是靠人工拼文件。 + +--- + +## 6. 数据标注（Annotation） + +### 能力 +标注项目管理，支持对接外部标注平台。 + +### 支持的标注平台 + +| 平台 | 对接方式 | 特点 | +|---|---|---| +| **Label Studio** | 内置双向同步服务 | 原生集成，支持自动标注、标签双向合并 | +| **CVAT** | 任务创建时指定平台 | 适合大批量图像标注，支持 Job 切分分工 | + +### 核心表 +`t_dm_annotation_templates`（标注模板）、`t_dm_labeling_projects`（标注项目）、`t_dm_auto_annotation_tasks`（自动标注任务） + +### 标注结果同步 +Label Studio 侧通过 `ls_annotation_sync.py` / `sync.py` 双向同步，写入 `t_dm_dataset_files.tags`，用 `tags_updated_at` 做冲突消解。 + +CVAT 侧由用户在界面上点击"同步到数据库"触发拉取，详见 [CVAT 标注 SOP](使用说明#六deepdatacvat-标注作业流程sop)。 + +### 自动标注 +`AUTO_ANNOTATION_ENABLED` 开关 + `ANNOTATION_MODEL_ENDPOINT` 配置模型端点，可先用模型跑一遍生成预标注（Pre-annotations），人工只需修正 —— **提效显著**（见 SOP 避坑建议）。 + +--- + +## 7. 数据评估（Evaluation） + +### 能力 +对数据集或合成结果做质量/效果评估。 + +### 核心表 +`t_de_eval_task`（评估任务）、`t_de_eval_file`（文件级）、`t_de_eval_item`（条目级） + +### 评估方式 +- 规则类算子：如`text_quality_evaluation`（LLM 多维度打分） +- QC 流程：`QC_ENABLED` / `QC_THRESHOLD` 配置阈值后可触发拦截 + +--- + +## 8. 知识生成（Knowledge Base / RAG） + +### 能力 +把处理好的语料转成可检索的向量知识。 + +### 技术路径 +``` +文档 → 解析(MinerU / unstructured) → 切片(slicer) → 向量化(langchain) +→ Milvus 索引 → rag-indexer-service 提供检索 +``` + +### 关键组件 +| 组件 | 作用 | +|---|---| +| `rag-indexer-service` | Java 侧 RAG 索引服务，用 langchain4j | +| `Milvus` | 向量库（`milvusdb/milvus:v2.6.5`，端口 19530） | +| `MinIO` | Milvus 的对象存储层 | +| `LightRAG` | GraphRAG增强（`lightrag-hku==1.4.10`） | +| `GraphRagClient` | Java → Python 的 GraphRAG 调用桥 | + +### 核心表 +`t_rag_knowledge_base`（知识库）、`t_rag_file`（知识库文件） + +### 解析器依赖 +`unstructured 0.18.21`、langchain4j 的 pdfbox/tika/poi/markdown 解析器 + +--- + +## 跨模块：Agent 与编排 + +| 能力 | 入口 | 说明 | +|---|---|---| +| Agent 对话 | `/chat` | 前端 Agent 页，配合 MCP 协议 | +| 可视化编排 | `/orchestration` | 基于 `@xyflow/react` 的工作流画布，用于多步骤任务编排 | + +--- + +**上一页**：[需求与定位](需求与定位) ｜ **下一页**：[技术架构](技术架构) \ No newline at end of file diff --git a/使用说明.md b/使用说明.md new file mode 100644 index 0000000..7b68b05 --- /dev/null +++ b/使用说明.md @@ -0,0 +1,321 @@ +# 使用说明 + +> 界面操作指南 + 完整标注作业 SOP。 + +--- + +## 一、登录与首页 + +访问 `http://: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` 字段驱动，零代码生成： + +```yaml +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 创建标注任务 + +`数据标注` → 创建标注任务： + +1. 选择数据集 +2. **平台选择**：Label Studio 或 CVAT +3. 选择标注模板（如目标检测） +4. 确定 + +创建后在任务列表可见，Label Studio 侧显示"前往 CVAT/LS"，且外部平台后台已生成对应任务。 + +### 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` 后，可先由模型生成预标注。 + +### 5.3 CVAT 作业流程 + +见[下一节](#六deepdatacvat-标注作业流程sop)。 + +--- + +## 六、DeepData/CVAT 标注作业流程SOP + +> 本节完整收录《DeepData/CVAT的标注作业流程SOP》，核心原则：**DeepData 负责"管数据（发起与回收）"，CVAT 负责"管人与流程（分配、标注、审核）"**。 +> +> 以下为针对**图片**标注任务的完整实操流程（示例：1000 张图）。 + +### 阶段 1：任务发起（DeepData） + +**操作人**：数据管理员 + +1. **创建标注任务：** + - 登录 DeepData → 进入"数据标注" → 点击"创建标注任务"。 + - 选择包含 1000 张图的数据集。 + - 关键设置：平台选择 **CVAT**，选择合适的标注模板（如"目标检测"）。 + - 点击确定。 + +2. **确认状态：** + - 在任务列表中看到新任务，显示"前往 CVAT"。 + - 此时 CVAT 后台已生成了一个包含 1000 张图的任务（Task）。 + +### 阶段 2：团队组建与任务分发（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。 + +### 阶段 3：标注与审核执行（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`。 + +### 阶段 4：结果回收（DeepData） + +**操作人**：数据管理员 + +1. **确认完工：** + - 在 CVAT 任务列表中，确认该 Task 进度为 **100%**，所有 Job 状态为 `completed`。 + +2. **同步回 DeepData：** + - 回到 DeepData 平台 → "标注任务列表"。 + - 找到对应任务，点击 **"同步到数据库"** 按钮。 + - **系统行为**：DeepData 会连接 CVAT，拉取所有图片对应的最终 JSON 标注数据，并写入 `t_dm_dataset_files` 表的 `tags` 字段。 + +3. **验证数据：** + - 进入"数据管理" → 找到原始数据集。 + - 查看文件列表的"标签/标注"列，应显示具体的类别名称（如 Person, Car）。 + - 点击文件预览，右侧信息栏应显示结构化的标注详情。 + +4. **归档/导出（可选）：** + - 点击任务右侧的"导出标注结果"，将最终成果打包下载或存入数据集归档。 + +### 流程总结图解 + +| 步骤 | 平台 | 动作 | 状态变化 | +|---|---|---|---| +| 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 倍以上**。 + +### 角色速查 + +| 角色 | 平台 | 能做什么 | +|---|---|---| +| 数据管理员 | DeepData | 创建任务、同步结果、导出归档 | +| Supervisor/Admin | CVAT | 建组、邀请、切分 Job、分配人员 | +| Worker | CVAT | 标注、提交 | +| Reviewer/Supervisor | CVAT | 审核、Accept/Reject | + +### 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`） | + +--- + +**上一页**：[运维手册](运维手册) ｜ **返回**：[首页](Home) \ No newline at end of file diff --git a/技术架构.md b/技术架构.md new file mode 100644 index 0000000..8e6190c --- /dev/null +++ b/技术架构.md @@ -0,0 +1,440 @@ +# 技术架构 + +> 本文所有事实均标注来源文件路径，可溯源核查。基于 `deepdata-20260928` 分支（commit `ff22ed3`）。 + +--- + +## 总体架构 + +DeepData 是**双后端**架构：Java 侧负责数据管理与 RAG 索引，Python 侧负责算子编排与任务调度，两者通过 HTTP 互调。 + +``` +浏览器 + │ + ▼ +前端 React18 + Vite7 (:30000) + │ /api + ▼ +网关 Spring Cloud Gateway (:8080) + │ JWT / SSO 认证 + ├──▶ 主应用 Spring Boot 3.5.6 (context-path /api) + │ ├── data-management-service + │ ├── rag-indexer-service + │ ├── domain-common / security-common + │ └── actuator (health/info/metrics/prometheus) + │ + └──▶ Python 后端 FastAPI (:18000) + ├── 归集 / 清洗 / 标注 / 采集/ 算子 / 评估 / 合成 / RAG + └── MCP endpoint /mcp + +存储层：PostgreSQL 15 · Milvus 2.6.5 · Redis 8.2.3 · MinIO +算子执行：Ray 2.7.0（可选） · DataJuicer v1.4.4（可选） +``` + +--- + +## 技术栈 + +### 后端（Java） + +| 项 | 版本/实现 | 来源 | +|---|---|---| +| Java | **21** | `backend/pom.xml` `maven.compiler.source/target` | +| Spring Boot | **3.5.6** | `backend/pom.xml` `spring-boot.version` | +| Spring Cloud | **2025.0.0** | `backend/pom.xml` `spring-cloud.version` | +| Spring AI | 1.0.0-RC1（MCP starter 用 1.1.2） | `backend/pom.xml`、`backend/services/pom.xml` | +| MyBatis-Plus | 3.5.14 | `backend/pom.xml` | +| MapStruct | 1.6.3 | `backend/pom.xml` | +| Milvus SDK | `milvus-sdk-java` 2.6.6 | `backend/pom.xml` | +| PostgreSQL 驱动 | 42.7.7 | `backend/pom.xml` `postgresql.version` | +| JJWT（网关） | 0.11.5 | `backend/api-gateway/pom.xml` | +| Log4j2 | 2.21.1 | `backend/pom.xml` | +| SpringDoc OpenAPI | 2.2.0 | `backend/pom.xml` | + +> ⚠️ **文档不一致**：`backend/README.md` 写「Database: PostgreSQL 8.0.33」，但 `8.0.33` 实为 POM 里的 `mysql.version` 属性值，PostgreSQL 驱动是 42.7.7。该README 行不可直接引用。 + +### 后端（Python） + +| 项 | 版本 | 来源 | +|---|---|---| +| Python | `>=3.12,<4.0.0` | `runtime/deepdata-python/pyproject.toml` | +| FastAPI | `>=0.124.0,<0.125.0` | 同上 | +| fastapi-mcp | `>=0.4.0,<0.5.0` | 同上（MCP 暴露） | +| SQLAlchemy | `>=2.0.45`（asyncpg 驱动） | 同上 | +| Pydantic | `>=2.12.5` | 同上 | +| Uvicorn | `>=0.38.0` | 同上 | +| APScheduler | `>=3.11.2`（任务调度） | 同上 | +| pymilvus | `>=2.6.0` | 同上 | +| LightRAG | `lightrag-hku==1.4.10` | 同上 | +| unstructured | 0.18.21（文档解析） | 同上 | +| langchain4j | bom 1.8.0 | `backend/services/rag-indexer-service/pom.xml` | + +> **版本差异**：Python 服务声明 `>=3.12`，但 runtime 镜像基于 **Python 3.11**（`ghcr.io/astral-sh/uv:python3.11-bookworm`）。开发环境需注意。 + +### 前端 + +| 项 | 版本 | 来源 | +|---|---|---| +| React | 18.1.1 | `frontend/package.json` | +| React Router | 7.8.0（`createBrowserRouter`） | 同上 | +| Redux Toolkit | 2.11.2 / react-redux 9.2.0 | 同上 | +| Ant Design | 5.27.0 | 同上 | +| Tailwind CSS | 4.1.12（`@tailwindcss/vite`） | 同上 | +| Vite | 7.1.2 | 同上 | +| TypeScript | ~5.8.3 | 同上 | +| xyflow（工作流画布） | `@xyflow/react` 12.8.3 | 同上 | +| recharts（图表） | 2.15.0 | 同上 | +| 3D 可视化 | `react-force-graph-2d/3d`、`three-spritetext` | 同上 | +| 文档预览 | `react-pdf`、`mammoth`、`jszip`、`react-markdown` | 同上 | +| 国际化 | i18next 25.8.0 / react-i18next 16.5.4 | 同上 | + +--- + +## 服务拆分 + +### Java 侧模块 + +| 模块 | 职责 | 来源 | +|---|---|---| +| `shared/domain-common` | DDD 构建块、异常处理 | `backend/pom.xml` | +| `shared/security-common` | JWT 工具 | 同上 | +| `services/data-management-service` | 数据管理服务 | `backend/services/data-management-service/pom.xml` | +| `services/rag-indexer-service` | RAG 文档索引（langchain4j + Milvus） | `backend/services/rag-indexer-service/pom.xml` | +| `services/main-application` | 主启动应用，集成所有服务 | `backend/services/main-application/pom.xml` | +| `api-gateway` | API 网关 | `backend/api-gateway/pom.xml` | + +**主应用端口**：`SERVER_PORT:8080`，context-path `/api`（`main-application/src/main/resources/application.yml`） + +### Python 侧业务模块 + +`runtime/deepdata-python/app/module/` 下的模块（来源 `app/module/__init__.py` 的 `include_router`）： + +| 模块 | 注册到 API | 说明 | +|---|---|---| +| `system` | ✅ | 系统设置（`t_sys_param`） | +| `annotation` | ✅ | 标注 | +| `cleaning` | ✅ | 清洗 | +| `collection` | ✅ | 归集 | +| `evaluation` | ✅ | 评估 | +| `generation` | ✅ | 合成/生成 | +| `ratio` | ✅ | 配比 | +| `operator` | ✅ | 算子（含 operator_router + category_router） | +| `rag` | ✅ | 知识库 | +| `dataset` | ❌ | 目录存在但未注册路由 | +| `shared` | ❌ | 内部公共库 | + +### Python 代码约定 + +来源 `runtime/README.md`： +- 路由放 `interface/*.py` +- 依赖注入用 `Depends(get_db)` +- 业务异常用 `raise BusinessError(ErrorCodes.XXX)` + +### Python 启动期行为 + +`app/main.py` 的 lifespan 中依次： +1. 数据库连通性校验（`SELECT 1`，URL 密码打码） +2. 打印 Label Studio 地址 +3. 启动collection 调度器 +4. 初始化任务执行器（`max_workers=10, max_concurrent_tasks=5`） +5. 恢复清洗任务调度器 +6. 注册日志 PVC 监控定时任务 + +--- + +## 网关与认证 + +### Spring Security 配置（重要） + +`backend/api-gateway/src/main/java/com/deepdata/gateway/common/config/SecurityConfig.java`： + +```java +@EnableWebFluxSecurity +http.csrf(ServerHttpSecurity.CsrfSpec::disable) + .authorizeExchange(exchange -> exchange.pathMatchers("**").permitAll()); +``` + +类注释写明「安全配置 - 暂时禁用所有认证」，**网关层全部放行**。真正的鉴权由自定义 `GlobalFilter` 承担。 + +### JWT 认证链路 + +**`AuthFilter.java`**（`implements GlobalFilter, Ordered`，`getOrder()=2`）流程： + +1. 公开路径放行：`/api/user/login`、`/api/user/signup`、`/api/user/me` +2. **SSO 优先**：请求头有 `X-User-Name` → 直接注入下游 `User` 头并放行 +3. `deepdata.jwt.enable=false`（默认）→ 直接放行 +4. Token 两种取法：`Authorization: Bearer ` 或 `?token=`（注释说明用于 ``/预览场景避免 401） +5. 校验失败返回 401 +6. 成功则注入 `User` header 给下游 + +**`JwtConfig.java`**：`@ConfigurationProperties(prefix="deepdata.jwt")`，字段 `secret`；`@PostConstruct` 校验 secret 非空，长度 < 32 打warn。过期 `expiration-seconds: 604800`（7 天）。 + +**`UserService.java`**： +- 签名算法 HS256，密钥 `Keys.hmacShaKeyFor(secret.getBytes(UTF_8))` +- Claims：`sub`=username，附加 `uid`、`role`，含 `iat`/`exp` +- 密码 `BCryptPasswordEncoder(10)` +- 实现 `register`、`changePassword` + +> 🔐 **安全提示**：JWT 认证在配置中**默认关闭**（`deepdata.jwt.enable=false`）。生产环境务必显式开启并设置足够强的 `JWT_SECRET`。 + +### OMS 认证 + +`OmsAuthFilter.java`（`getOrder()=1`，优先级最高）：开关 `oms.auth.enabled`（默认 false）；从 Cookie `__Host-X-Auth-Token` / `__Host-X-Csrf-Token` 取令牌；真实 IP 依次从 `X-Real-IP` → `X-Forwarded-For` → `Proxy-Client-IP` → `WL-Proxy-Client-IP` → remoteAddress 解析；认证成功注入 `X-User-Name`。 + +### 服务发现 + +`spring.cloud.nacos.discovery`，`server-addr: ${NACOS_ADDR:https://consulservice:18302}`，`cluster-name: DEFAULT`（`api-gateway/src/main/resources/application.yml`） + +> ⚠️ **未找到实际的 `spring.cloud.gateway.routes` 路由规则配置** —— README 中的路由示例仅为文档示例，yml 里没有。 + +--- + +## 算子执行引擎 + +### 双引擎设计 + +| 引擎 | 位置 | 说明 | +|---|---|---| +| Ray 分布式执行 | `runtime/python-executor/` | 主路径，Ray 2.7.0 | +| DataJuicer | compose profile `data-juicer` | 容器 `datajuicer/data-juicer:v1.4.4` | + +### `runtime/python-executor/` 结构 + +| 目录 | 职责 | +|---|---| +| `deepdata/core/` | `base_op.py`（算子基类）、`dataset.py`、`constant.py` | +| `deepdata/scheduler/` | `scheduler.py`、`func_task_scheduler.py`、`cmd_task_scheduler.py` | +| `deepdata/wrappers/` | `executor.py`、`deepdata_wrapper.py`、`data_juicer_wrapper.py` | +| `deepdata/sql_manager/` | SQL 管理 | +| `deepdata/operator_runtime.py` | 运行时入口 | + +### 算子基类 + +`runtime/python-executor/deepdata/core/base_op.py`： + +| 基类 | 行号 | 语义 | +|---|---|---| +| `OPERATORS = Registry("Operators")` | 24 | 算子注册表 | +| `BaseOp` | 51 | 基类 | +| `Mapper` | 218 | 1:1 转换 | +| `Slicer` | 268 | 1:N 切片 | +| `Filter` | 370 | 返回布尔（true 保留/ false 剔除） | +| `LLM(Mapper)` | 410 | LLM 驱动，需实现 `build_llm_prompt` | +| `FileExporter` | 499 | 文件导出 | + +### 算子包规范 + +一个算子包 = 目录（来源 `runtime/ops/README.md`）： + +``` +<算子名>/ +├── __init__.py # 注册入口（必要） +├── metadata.yml # 元数据 + UI 参数定义（必要） +├── process.py # 逻辑实现（必要） +├── requirements.txt # 依赖（可选） +├── README.md # 说明（可选） +└── sql/ # 可选：算子自带 SQL 配置 +``` + +**注册方式**（`runtime/ops/filter/remove_duplicate_file/__init__.py`）： + +```python +from deepdata.core.base_op import OPERATORS +OPERATORS.register_module(module_name='DuplicateFilesFilter', + module_path="ops.filter.remove_duplicate_file.process") +``` + +**打包上传规范**：压缩包名（不含后缀）必须与 `__init__.py` 中 `module_path` 的**包目录名一致**，否则 `ModuleNotFoundError`。 + +### 算子执行时的 sample 字段约定 + +`process.py` 的 `execute(sample: Dict) -> Dict` 中 sample 结构： + +| 字段 | 含义 | +|---|---| +| `text` | 文本内容 | +| `data` | 二进制/媒体数据 | +| `fileName` / `fileType` | 文件名/ 类型 | +| `fileId` / `filePath` / `fileSize` | 文件标识与存储信息 | +| `export_path` | 导出路径 | +| `ext_params` | 扩展参数 | +| `target_type` | 目标类型 | + +### runtime 镜像 + +`scripts/images/runtime/Dockerfile`：基于 `ghcr.io/astral-sh/uv:python3.11-bookworm`，安装系统依赖 `libgl1`、`libmagic1`、`libreoffice`、`tesseract-ocr`、`poppler-utils`，下载 PP-LCNet 文档方向检测模型到 `/home/models`。 + +算子目录拷入镜像：`COPY runtime/ops /opt/runtime/deepdata/ops`，`ENV PYTHONPATH=/opt/runtime/deepdata/`。 + +--- + +## 自定义算子开发 + +### `my_ops/` 目录 + +仓库根级目录（与 `runtime/ops/` **平级**），平台方自建算子： + +| 算子 | raw_id | vendor | types | 功能 | +|---|---|---|---|---| +| `markitdown_parser` | `MarkItDownParser` | DeepData | collect | 基于 MarkItDown 将docx/pptx/xlsx/pdf/html 等格式统一转 Markdown；支持图片上传/远程下载/Base64 内联 | +| `mineru_pdf_parser` | `MinerUPdfParser` | DeepData | collect | 调远端 MinerU FastAPI 解析 PDF 提取 Markdown + 图片；支持 Base64/本地保存/外传 | +| `text_quality_evaluator` | `TextQualityEvaluator` | DeepData User | consolidate | LLM 多维度文本质量评分；支持自定义模型、分块策略、并发处理 | + +> `my_ops/` 与 `runtime/ops/` 分离：前者是自建算子（`vendor: DeepData`），后者是内置算子库（`vendor: huawei`）。 + +### 打包产物 + +`my_ops/dist/` 下有已构建的 `deepdata_mineru_pdf_parser-1.0.0-py3-none-any.{whl,zip}`，命名带 `deepdata_` 前缀，符合"压缩包名 = module_path 包目录名"规范。 + +--- + +## 数据模型 + +### 数据库 + +| 类型 | 版本/镜像 | 用途 | +|---|---|---| +| PostgreSQL | `postgres:15-trixie` | 主元数据库 | +| Milvus | `milvusdb/milvus:v2.6.5` | 向量库（:19530，管理 :9091） | +| Redis | `redis:8.2.3` | 缓存/队列（:6379） | +| MinIO | `minio/minio:RELEASE.2024-12-18T13-15-44Z` | S3 兼容对象存储（Milvus 依赖） | + +初始化脚本创建两个库（`scripts/db/00-database-init.sql`）：`deepdata`、`labelstudio`（后者供 Label Studio 用）。 + +> MySQL 仅作为 `aiomysql`/`pymysql` 依赖与配置项存在，**部署 compose 中没有 MySQL 服务**；默认 `database_url` 走 `postgresql+asyncpg`（`app/core/config.py` 的 `build_database_url`）。 + +### 表清单 + +| 模块 | 表 | +|---|---| +| 公共 | `users`、`t_chunk_upload_request`（切片上传）、`t_lineage_node`、`t_lineage_edge`、`t_models`、`t_sys_param` | +| 数据管理 | `t_dm_datasets`、`t_dm_dataset_files`、`t_dm_dataset_statistics`、`t_dm_tags`、`t_dm_dataset_tags` | +| 数据标注 | `t_dm_annotation_templates`、`t_dm_labeling_projects`、`t_dm_auto_annotation_tasks` | +| 数据清洗 | `t_clean_template`、`t_clean_task`、`t_clean_result` | +| 数据归集 | `t_dc_collection_templates`、`t_dc_collection_tasks`、`t_dc_task_executions` | +| 算子 | `t_operator`、`t_operator_category`、`t_operator_category_relation`、`t_operator_instance`、`t_operator_release` | +| 数据评估 | `t_de_eval_task`、`t_de_eval_file`、`t_de_eval_item` | +| 数据合成 | `t_data_synth_instances`、`t_data_synthesis_file_instances`、`t_data_synthesis_chunk_instances`、`t_data_synthesis_data` | +| 配比 | `t_st_ratio_instances`、`t_st_ratio_relations` | +| 知识库 | `t_rag_knowledge_base`、`t_rag_file` | + +### 核心表：`t_dm_dataset_files` + +来源 `scripts/db/data-management-init.sql`： + +```sql +CREATE TABLE IF NOT EXISTS t_dm_dataset_files ( + id VARCHAR(36) PRIMARY KEY, + dataset_id VARCHAR(36) NOT NULL, + file_name VARCHAR(255) NOT NULL, + file_path VARCHAR(1000) NOT NULL, + file_type VARCHAR(50), + file_size BIGINT DEFAULT 0, + check_sum VARCHAR(64), + tags JSONB, -- 标注结果写入处 + tags_updated_at TIMESTAMP, -- 冲突消解用时间戳 + annotation JSONB, + metadata JSONB, + status VARCHAR(50) DEFAULT 'ACTIVE', + upload_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + last_access_time TIMESTAMP, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +ORM：`runtime/deepdata-python/app/db/models/dataset_management.py:63` + +**`tags` 写入路径**（标签同步主体）： + +| 文件 | 行为 | +|---|---| +| `app/module/annotation/service/ls_annotation_sync.py:127,142` | 直接更新 `tags` / `tags_updated_at` / `annotation` | +| `app/module/annotation/service/sync.py:606,629,800-809` | 双向覆盖策略 `_should_overwrite_dm` / `_should_overwrite_ls` 比较时间戳决定谁覆盖 | +| `app/module/dataset/service/service.py:197,460,538` | 读写 `tags_updated_at` | +| `app/module/ratio/service/ratio_task.py:183,307,387` | 写入并按时间区间筛选文件 | +| `app/module/annotation/interface/task.py:252` | 支持部分标签合并（只改提交的标签，其余保持） | + +### 数据库初始化机制 + +- **无 Flyway/Liquibase**（未找到依赖与配置） +- 依赖 `scripts/db/` 下 14 个幂等 DDL 脚本（`CREATE TABLE IF NOT EXISTS`） +- 由 `scripts/images/database/Dockerfile` 的 `COPY scripts/db/ /docker-entrypoint-initdb.d/` 在**容器首次初始化时**执行 +- `scripts/db/zz-final-task.sh` 读取 `HOME_PAGE_URL` 环境变量，用 `psql -v ON_ERROR_STOP=1` 更新 `t_sys_param.param_value where id='sys.home.page.url'` + +> ⚠️ **重要**：`docker-entrypoint-initdb.d` 只在数据卷为空时执行一次。修改 SQL 后不会自动生效，需手工执行或重建卷。 +> 另注：调研发现 `backend/api-gateway/migration/` 目录在当前分支**不存在**（在 `main` 分支存在）。 + +--- + +## DataX 集成 + +`runtime/datax/` 是精简版 DataX（`groupId=com.alibaba.datax`, `artifactId=datax-all`），完整源码在根目录 `DataX/`。 + +### 构建方式 + +`scripts/images/backend-python/Dockerfile` 第一阶段 `datax-builder`： + +1. `COPY DataX/ /DataX/` +2. `COPY runtime/datax/ DataX/`（精简版覆盖部分路径） +3. `mvn -U clean package assembly:assembly` +4. sed 修复 MySQL 驱动名（`com.mysql.jdbc.Driver` → `com.mysql.cj.jdbc.Driver`） +5. 第二阶段把 `/DataX/target/datax/datax` 拷到运行镜像 `/opt/datax` + +### 调用方 + +`runtime/deepdata-python/app/module/collection/client/datax_client.py`： +- `self.datax_main = "/opt/datax/bin/datax.py"` +- `subprocess.Popen` 执行，支持超时、日志 tail/header 写入 +- 目标类型白名单：`{"nfswriter", "s3writer", "glusterfswriter"}`；`txtfilewriter` 走单独分支 + +> DataX 位于**数据归集**链路，不是通用算子执行链路。 + +--- + +## deep-flow 子项目 + +**DeepFlow**（Deep Exploration and Efficient Research Flow）是内嵌的独立子项目，源自开源深度研究框架（README badge 指向 `bytedance/deer-flow`）。**不是 git submodule**（未找到 `.gitmodules`）。 + +关键文件：`main.py`、`server.py`、`conf.yaml`、`langgraph.json`、`uv.lock`、`web/`（前端）、`src/`、`examples/`、`tests/` + +在平台中作为**可选服务**（compose profile `deep-flow`，服务 `deep-flow-backend` / `deep-flow-frontend`）。 + +Java → Python 调用桥：`backend/services/rag-indexer-service/.../GraphRagClient.java` 用 `@FeignClient(name="rag-service", url="${collection.service.url:http://deepdata-backend-python:18000}")`。 + +--- + +## MCP 协议支持 + +| 侧 | 实现 | Endpoint | +|---|---|---| +| Python | `fastapi-mcp` | `/mcp` | +| Java | `spring-ai-starter-mcp-server-webmvc` 1.1.2 | `/mcp`，name `deepdata-mcp-server`，protocol `STATELESS`，tool capability 开启 | + +--- + +## 前端路由表 + +来源 `frontend/src/routes/routes.ts`： + +| 路径 | 页面 | +|---|---| +| `/` | Home | +| `/chat` | Agent | +| `/orchestration` | SmartOrchestration | +| `/orchestration/create-workflow` | WorkflowEditor | +| `/data/collection` | 数据归集 | +| `/data/management` | 数据管理 | +| `/data/cleansing` | 数据清洗 | +| `/data/annotation` | 数据标注 | +| `/data/synthesis/task` | 数据合成任务 | +| `/data/synthesis/ratio-task` | 配比任务 | +| `/data/evaluation` | 数据评估 | +| `/data/knowledge-base` | 知识库 | +| `/data/operator-market` | 算子市场 | + +所有组件经 `withErrorBoundary` 包装。 + +--- + +**上一页**：[产品功能](产品功能) ｜ **下一页**：[部署指南](部署指南) \ No newline at end of file diff --git a/运维手册.md b/运维手册.md new file mode 100644 index 0000000..c135283 --- /dev/null +++ b/运维手册.md @@ -0,0 +1,278 @@ +# 运维手册 + +> 基于 `deepdata-20260928` 分支（commit `ff22ed3`）。本文记录**日常运维操作**与**已核实的已知问题**。 + +--- + +## 一、健康检查 + +### Actuator（Java 主应用） + +`backend/services/main-application/src/main/resources/application.yml`： + +```yaml +management: + endpoints: + web: + exposure: + include: health,info,metrics,prometheus + endpoint: + health: + show-details: when-authorized + health: + elasticsearch: + enabled: false # 显式禁用 ES 健康检查 +``` + +访问路径（主应用 context-path 为 `/api`）： + +``` +http://:8080/api/actuator/health +http://:8080/api/actuator/info +http://:8080/api/actuator/metrics +http://:8080/api/actuator/prometheus +``` + +### Compose healthcheck + +**只有 Milvus profile 的三个服务配了 healthcheck**（`deployment/docker/deepdata/docker-compose.yml`）： + +| 服务 | 检查命令 | 参数 | +|---|---|---| +| `etcd` | `etcdctl endpoint health` | interval 30s / timeout 20s / retries 3 | +| `minio` | `curl -f http://localhost:9000/minio/health/live` | 30s / 20s / 3 | +| `milvus` | `curl -f http://localhost:9091/healthz` | 30s / 20s / 3，**start_period 90s** | + +> ⚠️ **注意**：核心业务服务（backend / backend-python / gateway / frontend / runtime）**都没有 healthcheck**，Dockerfile 里也没有 `HEALTHCHECK` 指令。容器"running"不代表服务可用 —— 需靠外部探针或人工确认。 + +### Python 启动期检查 + +`app/main.py` lifespan 中会做数据库连通性校验（`SELECT 1`，URL 密码打码），失败则启动失败。这属于**启动期一次性检查**，非常驻健康端点。 + +--- + +## 二、日志 + +### Java侧（Log4j2） + +`backend/services/main-application/src/main/resources/log4j2.xml`： + +| 项 | 值 | +|---|---| +| `LOG_PATH` | `/var/log/deepdata/backend` | +| 日志文件 | `${LOG_PATH}/app.log` | +| 轮转文件名 | `app-%d{yyyy-MM-dd}-%i.log` | +| `MAX_FILE_SIZE` | `${LOG_ROTATION_MAX_SIZE:-100MB}` | +| `MAX_HISTORY` | `${LOG_ROTATION_BACKUP_COUNT:-30}` | +| 格式 | `%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{50} - %msg%n` | +| `LOG_LEVEL` | INFO | +| `SQL_LOG_LEVEL` | WARN | + +通过 `logging.config: classpath:log4j2.xml` 启用。网关有独立 log4j2 配置（`backend/api-gateway/src/main/resources/log4j2.xml`）。 + +### Python 侧（标准库 logging） + +`runtime/deepdata-python/app/core/logging.py` 的 `setup_logging()`： + +- 双handler：`StreamHandler(sys.stdout)` + `RotatingFileHandler(log_dir/"python-backend.log")` +- 默认 `log_file_dir = /var/log/deepdata/backend-python`（`app/core/config.py` 第 29 行；`.env.example` 覆盖为 `./logs`） +- 自定义 `CenteredLevelNameFormatter` 与 `_rotated_log_namer` +- 显式调低 `httpx`/`httpcore` 与 `sqlalchemy.engine` 为 ERROR；接管 uvicorn 三类日志 + +### 日志卷挂载 + +| 卷 | 路径 | 使用方 | +|---|---|---| +| `deepdata-log-volume` | `/var/log/deepdata` | backend / backend-python / gateway / runtime | +| `deepdata-frontend-log-volume` | `/var/log/deepdata/frontend` | frontend | +| `deepdata-database-log-volume` | `/var/log/deepdata/database` | database | +| `deep-flow-log-volume` | `/var/log/deep-flow` | deep-flow | +| `deepdata-ray-log-volume` | `/tmp/ray` | ray | + +### 日志 PVC 监控（自动清理） + +Python 侧实现了 PVC 磁盘水位监控（`app/module/system/service/log_pvc_monitor.py`）： + +| 配置 | 默认 | 作用 | +|---|---|---| +| `LOG_PVC_MONITOR_ENABLED` | true | 开关 | +| `LOG_PVC_MONITOR_PATH` | `./logs` | 监控路径 | +| `LOG_PVC_MONITOR_THRESHOLD` | 0.9 | 水位阈值（90% 触发清理） | +| `LOG_PVC_MONITOR_INTERVAL_SECONDS` | 300 | 检查间隔 | +| `LOG_PVC_MONITOR_DELETE_BATCH_SIZE` | 10 | 单次删除文件数 | +| `LOG_PVC_MONITOR_FILE_SUFFIXES` | `log,out,err` | 匹配后缀 | + +测试覆盖：`tests/test_log_pvc_monitor.py`、`tests/test_logging_rotation.py` + +### 轮转脚本 + +| 脚本 | 用途 | +|---|---| +| `scripts/images/common/log-rotate-copytruncate.sh` | 拷入 runtime 镜像 `/usr/local/bin/` | +| `scripts/images/database/prune-postgres-logs.sh` | PostgreSQL 日志清理 | + +--- + +## 三、数据库运维 + +### 初始化机制 + +**无 Flyway/Liquibase**。数据库变更依赖 `scripts/db/` 下 14 个幂等 DDL 脚本，由数据库镜像的 `/docker-entrypoint-initdb.d/` 执行。 + +```dockerfile +# scripts/images/database/Dockerfile +COPY scripts/db/ /docker-entrypoint-initdb.d/ +``` + +> ⚠️ **关键机制**：`docker-entrypoint-initdb.d` **只在数据卷为空时执行一次**。 +> - 改 `scripts/db/*.sql` 后**不会自动生效** +> - 需要手工执行：`docker exec -i deepdata-database psql -U postgres -d deepdata < scripts/db/xxx-init.sql` +> - 或重建数据卷（**会丢数据，慎用**） + +### 迁移脚本位置问题 + +`backend/api-gateway/migration/` 在 `deepdata-20260928` 分支**不存在**（存在于 `main` 分支的 09-01 基线中）。当前分支的DDL 统一在 `scripts/db/`。 + +### 主库与初始化 + +| 项 | 值 | +|---|---| +| 镜像 | `postgres:15-trixie` | +| 启动脚本 | `/usr/local/bin/deepdata-database-start.sh` | +| 配置 | `scripts/images/database/postgresql.cnf` | +| 初始化库 | `deepdata`、`labelstudio` | +| JDBC | `jdbc:postgresql://deepdata-database:5432/deepdata` | +| 连接池 | HikariCP（max 20 / min 5） | +| Redis 池| Lettuce（max-active 20） | + +### 首页 URL 联动 + +`scripts/db/zz-final-task.sh` 读取 `HOME_PAGE_URL` 环境变量： + +```bash +psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d deepdata +# UPDATE t_sys_param SET param_value = :url WHERE id = 'sys.home.page.url' +``` + +未设置则跳过。 + +### 备份建议 + +| 数据 | 位置 | 备份方式 | +|---|---|---| +| 元数据 | `deepdata-postgresql-volume` | `pg_dump` | +| 数据集文件 | `deepdata-dataset-volume` / MinIO | 卷快照或对象存储同步 | +| 算子包 | `deepdata-operator-packages-volume` | 卷快照 | +| 向量数据 | `milvus-milvus-volume` + `milvus-minio-volume` | Milvus 官方备份工具 | + +--- + +## 四、已知坑（已核实） + +### 🔴 P0 · JWT 认证默认关闭 + +`deepdata.jwt.enable` 默认值为 `false`（`backend/api-gateway/.../JwtConfig.java` 的 `@Value("${deepdata.jwt.enable:false}")`），`.env.example` 中也是 `DEEPDATA_JWT_ENABLE=false`。 + +同时网关的 `SecurityConfig` 是 `pathMatchers("**").permitAll()`（类注释：暂时禁用所有认证）。 + +**影响**：若不改配置，接口层无认证保护。 +**处置**：生产环境显式设 `DEEPDATA_JWT_ENABLE=true`，并设置足够强的 `JWT_SECRET`（`JwtConfig` 在长度 < 32 时仅打warn，不报错 —— 短密钥不会被拒绝）。 + +### 🟡 Makefile 目标与 README 不匹配 + +| README 写的 | 实际情况 | +|---|---| +| `make install` / `make uninstall` | ❌ 无无后缀目标 | +| `make build` | ❌ 无此目标 | +| `make install-mineru` | ❌ `mineru` 不在 `VALID_SERVICE_TARGETS` | +| `make install-deep-flow` | ❌ `deep-flow` 不在合法目标 | +| `make install-label-studio` | ✅ 可用 | + +**根因**：`Makefile` 的 `install-%` 规则指向目录 `deployment/compose`，而**该目录不存在**（实际为 `deployment/docker/deepdata`）。 + +### 🟡 数据库 SQL 修改不生效 + +见[前文](#三数据库运维)。改 `scripts/db/*.sql` 后必须手工执行。 + +### 🟡 core 服务无 healthcheck + +backend / backend-python / gateway / frontend / runtime 均无 healthcheck 与 Dockerfile `HEALTHCHECK`。编排系统无法据此判断服务真实状态。 + +### 🟡 两份 compose 端口不同 + +混用`docker/docker-compose.yml`（开发）与 `deployment/docker/deepdata/docker-compose.yml`（部署）会撞端口。差异见[部署指南](部署指南#开发版-compose-的端口差异)。 + +### 🟢 backend 无对外端口 + +`deepdata-backend` 在两份 compose 中都**没有对外端口映射**，只能通过 `deepdata` 内部网络访问。前端只暴露 30000（开发版 40000）。外部调用一律走网关。 + +### 🟢 前置 Nacos + +`NACOS_ADDR` 默认值是 `https://consulservice:18302`（端口 18302 是 Consul 的典型端口，与 Nacos 默认 8848 不符）。纯 Compose 部署不需要服务发现，此配置无实际作用；但若误配会导致网关启动异常。 + +--- + +## 五、分支差异 + +| 分支 | commit | 内容 | +|---|---|---| +| `main` | `cbb1048` | 早期基线，**含 Casdoor SSO 与 GitHub Actions CI** | +| `deepdata-20260928` | `ff22ed3` | 当前开发基线 | + +`deepdata-20260928` 相对 `main`： + +| 缺失项 | 文件数 | +|---|---| +| `deepflow/`（已改名 `deep-flow/`） | 396（重命名） | +| `.github/workflows/` CI | 14 | +| Casdoor SSO 认证模块（Java） | 11 | +| `.gitattributes` | 1 | + +**原因**：zip 交付包（09-28）不含这些文件。Casdoor SSO 与 GitHub Actions 属于早期国际版基线的内容。 + +**影响**：切回 `main` 可找回 CI 与 SSO。若两条线都需要，需人工合并。 + +--- + +## 六、常见排障 + +| 现象 | 排查方向 | +|---|---| +| 网关启动即失败 | `JWT_SECRET` 未配置（`JwtConfig` `@PostConstruct` 抛 `IllegalStateException`） | +| 接口全 401 | `deepdata.jwt.enable=false` 时不会 401；若出现说明认证已开但 Token 无效/过期（默认 7 天） | +| 前端能开但数据为空 | 检查 backend / backend-python 容器状态（无 healthcheck，只能看日志） | +| 算子报错 `ModuleNotFoundError` | 上传包名与 `__init__.py` 中 `module_path` 包目录名不一致 | +| 清洗任务卡在调度 | 查 `LOG_LEVEL=DEBUG` 下的 asyncio 日志；检查 `TASK_SCHEDULING_POOL_SIZE` | +| 向量检索为空 | 确认 Milvus profile 已启用、`MILVUS_URI` 指向正确容器名（非 localhost） | +| 磁盘写满 | 检查日志 PVC 水位；确认 `LOG_PVC_MONITOR_ENABLED=true` | +| 数据库无表 | 数据卷非首次启动，初始化脚本未执行（见"数据库 SQL 修改不生效"） | +| 标注结果不同步 | 检查 `t_dm_dataset_files.tags_updated_at`，同步按时间戳做冲突消解 | + +--- + +## 七、日常巡检清单 + +```bash +# 1. 容器状态 +docker compose ps + +# 2. 后端健康 +curl -s http://:8080/api/actuator/health | jq . + +# 3. 磁盘水位（数据卷+ 日志卷） +docker exec deepdata-database df -h /var/lib/postgresql/data +docker exec df -h /var/log/deepdata + +# 4. 数据库关键表增长 +psql -U postgres -d deepdata -c " + SELECT relname, n_live_tup FROM pg_stat_user_tables + WHERE relname LIKE 't_dm_%' OR relname LIKE 't_clean_%' + ORDER BY n_live_tup DESC LIMIT 10;" + +# 5. 清理陈旧算子包（operator-packages 卷） +docker exec du -sh /opt/runtime/deepdata/ops/user +``` + +--- + +**上一页**：[部署指南](部署指南) ｜ **下一页**：[使用说明](使用说明) \ No newline at end of file diff --git a/部署指南.md b/部署指南.md new file mode 100644 index 0000000..1813e0b --- /dev/null +++ b/部署指南.md @@ -0,0 +1,256 @@ +# 部署指南 + +> 基于 `deepdata-20260928` 分支。所有配置项名称来自实际配置文件，敏感值一律不列出。 + +--- + +## 前置条件 + +| 依赖 | 用途 | 必需性 | +|---|---|---| +| Git | 拉取源码 | 必需 | +| Make | 构建与安装 | 必需 | +| Docker | 构建镜像 | 必需 | +| Docker Compose | Compose 部署 | Compose 方式必需 | +| Kubernetes + Helm | K8s 部署 | K8s 方式必需 | +| Sealed Secrets Controller | 加密管理敏感配置 | 仅 K8s 部署 | + +--- + +## 部署形态对比 + +| 维度 | Docker Compose | Helm / K8s | +|---|---|---| +| 配置文件 | `deployment/docker/deepdata/docker-compose.yml` | `deployment/helm/deepdata/` | +| 适合场景 | 单机/小规模、快速验证 | 生产、多副本、弹性伸缩 | +| 敏感配置 | `.env` 文件 | Bitnami Sealed Secrets（密文入库） | +| Ray 集群 | 单容器内启动 | 独立 `kuberay-operator` + `ray-cluster` chart | +| 外部依赖 | 需手动起Redis/Milvus/Label Studio | 独立 chart管理 | + +--- + +## 一、Docker Compose 部署 + +### 步骤 1：准备环境变量 + +```bash +cp deployment/docker/deepdata/.env.example deployment/docker/deepdata/.env +``` + +**必填项**（`.env.example` 中均以 `${VAR:?...}` 形式引用，不含明文）： + +| 变量 | 说明 | +|---|---| +| `DB_PASSWORD` | PostgreSQL 密码 | +| `JWT_SECRET` | JWT 签名密钥 | +| `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` | MinIO 凭据（Milvus 依赖） | +| `LABEL_STUDIO_USERNAME` / `LABEL_STUDIO_PASSWORD` / `LABEL_STUDIO_USER_TOKEN` | Label Studio 凭据 | +| `DEEPDATA_JWT_ENABLE` | JWT 开关，示例默认 `false` | + +可选：`CERT_PASS`（加密私钥口令）、`DOMAIN`（HTTPS 域名）。 + +### 步骤 2：启动 + +```bash +docker compose -f deployment/docker/deepdata/docker-compose.yml up -d +``` + +### 核心服务与端口 + +| 服务 | 镜像 | 端口映射 | 说明 | +|---|---|---|---| +| `deepdata-frontend` | `deepdata-frontend` | **30000:3000** | 用户界面入口 | +| `deepdata-gateway` | `deepdata-gateway` | **8080:8080** | API 网关 | +| `deepdata-backend-python` | `deepdata-backend-python` | **18000:18000** | Python 后端 | +| `deepdata-database` | `deepdata-database` | **5432:5432** | PostgreSQL 15 | +| `deepdata-backend` | `deepdata-backend` | 无对外端口 | 仅内部网络访问 | +| `deepdata-runtime` | `deepdata-runtime` | 无（容器内 8081） | 算子执行 | + +### 可选服务（按 profile启用） + +| profile | 服务 | 端口 | +|---|---|---| +| `redis` | `deepdata-redis`（redis:8.2.3） | 6379:6379 | +| `milvus` | `etcd` + `minio` + `milvus` | minio 9000/9001，milvus 19530/9091 | +| `label-studio` | `label-studio-pgbouncer` + `label-studio` | 30001:8000 | +| `data-juicer` | `deepdata-data-juicer`（datajuicer/data-juicer:v1.4.4） | 无 | +| `deep-flow` | `deep-flow-backend` / `deep-flow-frontend` | 无 | +| `mineru` | `deepdata-mineru`（vLLM引擎，需 Ascend NPU） | 容器内 8000 | + +示例： + +```bash +#启用向量库 + 缓存 +docker compose -f deployment/docker/deepdata/docker-compose.yml --profile milvus --profile redis up -d + +# 启用标注（Label Studio） +docker compose -f deployment/docker/deepdata/docker-compose.yml --profile label-studio up -d +``` + +### 数据卷 + +`compose` 定义了 17 个卷，重要的有： + +| 卷 | 用途 | +|---|---| +| `deepdata-postgresql-volume` | PostgreSQL 数据（**删卷即丢全部元数据**） | +| `deepdata-dataset-volume` | 数据集文件 | +| `deepdata-operator-*-volume` | 算子包/运行时/上传（3 个） | +| `deepdata-log-volume` | 后端日志 | +| `deepdata-graph-data-volume` | 图数据 | +| `milvus-milvus-volume` / `milvus-minio-volume` / `milvus-etcd-volume` | 向量库 | + +### 开发版 compose 的端口差异 + +`docker/docker-compose.yml`（本地开发用）与主部署 compose 端口**不同**，注意区分： + +| 服务 | 开发版 | 部署版 | +|---|---|---| +| gateway | 8085:8080 | 8080:8080 | +| frontend | 40000:3000 | 30000:3000 | +| database | **5442**:5432 | 5432:5432 | +| redis | 6339:6379 | 6379:6379 | +| milvus 管理口 | 19091:9091 | 9091:9091 | +| label-studio | 38000:8000 | 30001:8000 | + +开发版独有 `deepdata-ray-head` / `deepdata-ray-worker`（profile `ray`，Ray Dashboard `:8265`、客户端 `:10001`，`shm_size` 6-8GB）。 + +--- + +## 二、Helm / K8s 部署 + +### Chart 结构 + +`deployment/helm/` 下 4 个 chart： + +| chart | 名称/版本 | 说明 | +|---|---|---| +| `deepdata` | `deepdata` 0.0.1 | 主chart，依赖 9 个子chart | +| `milvus` | `milvus` 5.0.7（appVersion 2.6.5） | Milvus 官方 chart | +| `label-studio` | `label-studio` 0.1.0 | 镜像 compose 行为 | +| `deep-flow` | `deep-flow` 0.0.1 | DeepFlow 服务 | + +主 chart 子依赖（`deployment/helm/deepdata/charts/`）： + +`backend`、`backend-python`、`database`、`frontend`、`gateway`、`kuberay-operator`（1.4.2，condition `ray-cluster.enabled`）、`ray-cluster`（1.4.2，同 condition）、`runtime`（condition `runtime.enabled`）、`public` + +### 安装 + +```bash +make k8s-install-deepdata +# 等价于：helm upgrade --install deepdata ./charts/deepdata -n deepdata +``` + +> ⚠️ **Makefile 路径问题**：`Makefile` 中 `k8s-install-deepdata` 引用 `./charts/deepdata`，需在 `deployment/helm/deepdata/` 目录下执行，或自行调整路径。 + +### 密钥管理 + +K8s 部署使用 **Bitnami Sealed Secrets**，密文存于 `deployment/kubernetes/sealed-secrets/`（README 自述）。安装 Controller： + +```bash +helm repo add sealed-secrets https://bitnami-labs.github.io/sealed-secrets +helm install sealed-secrets sealed-secrets/sealed-secrets -n kube-system +``` + +--- + +## 三、Makefile 目标 + +> ⚠️ **README 与 Makefile 不一致**（调研发现，详见下方"已知坑"） + +### 构建镜像 + +每个镜像的 Dockerfile 统一在 `scripts/images//Dockerfile`： + +``` +frontend-docker-build / backend-docker-build / database-docker-build +gateway-docker-build / runtime-docker-build / runtime-ray-docker-build +backend-python-docker-build +deep-flow-backend-docker-build / deep-flow-frontend-docker-build / deep-flow-docker-build +label-studio-docker-build +mineru-docker-build / mineru-910B-docker-build / mineru-910C-docker-build / mineru-310P-docker-build +``` + +全局变量：`REGISTRY=ghcr.io/modelengine-group/`、`VERSION=latest`、`BUILD_PLATFORM=linux/amd64`、`NAMESPACE=deepdata` + +### Compose 安装 + +模式规则 `install-%` / `uninstall-%`，合法服务目标（`VALID_SERVICE_TARGETS`）： + +``` +deepdata backend frontend runtime runtime-ray backend-python +database gateway redis milvus label-studio data-juicer +``` + +例：`make install-deepdata`、`make install-label-studio`、`make uninstall-redis` + +> ❌ **`make install-mineru` / `make install-deep-flow` 会失败** —— `mineru` 和 `deep-flow` 不在合法目标列表。 + +### 其他目标 + +| 目标 | 说明 | +|---|---| +| `help` | 默认目标，列出所有目标 | +| `download` | 交互选择 amd64/arm64，pull + save 镜像到 `dist/` | +| `load-images` | 加载离线镜像 | +| `create-namespace` | 创建 K8s namespace | +| `node-setup` / `node-cleanup` | Ray 节点管理 | + +--- + +## 四、关键环境变量 + +### Python 后端（`runtime/deepdata-python/.env.example`） + +| 类别 | 变量 | +|---|---| +| 服务 | `HOST`（0.0.0.0）、`PORT`（18000）、`DEBUG` | +| 数据库 | `PGSQL_HOST`、`PGSQL_PORT`、`PGSQL_USER`、`PGSQL_PASSWORD`、`PGSQL_DATABASE` | +| 标注 | `LABEL_STUDIO_BASE_URL`、`LABEL_STUDIO_USER_TOKEN` | +| 向量库 | `MILVUS_URI`（生产写法 `http://milvus:19530`）、`MILVUS_TOKEN` | +| 日志 | `LOG_LEVEL`、`LOG_FILE_DIR`、`LOG_ROTATION_MAX_SIZE`（100MB）、`LOG_ROTATION_BACKUP_COUNT`（30） | +| 日志PVC监控 | `LOG_PVC_MONITOR_ENABLED`、`LOG_PVC_MONITOR_THRESHOLD`（0.9）、`LOG_PVC_MONITOR_INTERVAL_SECONDS`（300）、`LOG_PVC_MONITOR_DELETE_BATCH_SIZE`（10） | +| 存储 | `RAG_STORAGE_DIR` | +| 认证 | `DEEPDATA_jwt_enable` | + +### Java 主应用（`main-application/application.yml`） + +| 类别 | 变量 | +|---|---| +| 数据库 | `DB_USERNAME`、`DB_PASSWORD`、`REDIS_PASSWORD` | +| 存储 | `STORAGE_TYPE`（local/minio/s3）、`STORAGE_LOCAL_PATH` | +| Ray | `RAY_ENABLED`（默认 false）、`RAY_ADDRESS`、`RAY_WORKING_DIR` | +| 算子 | `OPERATOR_REPO_PATH`、`OPERATOR_REGISTRY_URL`、`OPERATOR_MAX_UPLOAD_SIZE` | +| 限制 | `MAX_FILE_SIZE`、`TEMP_DIR`、`BATCH_SIZE` | +| 标注 | `AUTO_ANNOTATION_ENABLED`、`ANNOTATION_MODEL_ENDPOINT` | +| 质检 | `QC_ENABLED`、`QC_THRESHOLD` | +| 任务 | `TASK_EXECUTION_CORE_SIZE`、`TASK_EXECUTION_MAX_SIZE`、`TASK_EXECUTION_QUEUE_CAPACITY`、`TASK_SCHEDULING_POOL_SIZE` | +| 集成 | `NACOS_ADDR`、`OMS_AUTH_ENABLED`、`OMS_SERVICE_URL` | + +--- + +## 五、验证部署 + +```bash +# 1. 容器状态 +docker compose ps + +# 2. 后端健康检查 +curl http://:8080/api/actuator/health + +# 3. Actuator 暴露的端点 +# health / info / metrics / prometheus +# show-details: when-authorized + +# 4. 前端可访问 +curl -I http://:30000 + +# 5. Python 后端 +curl http://:18000/docs # FastAPI 自动文档 +``` + +> 注意：Actuator 挂在主应用的 `/api` context-path 下。 + +--- + +**上一页**：[技术架构](技术架构) ｜ **下一页**：[运维手册](运维手册) \ No newline at end of file diff --git a/需求与定位.md b/需求与定位.md new file mode 100644 index 0000000..16fb9ee --- /dev/null +++ b/需求与定位.md @@ -0,0 +1,127 @@ +# 需求与定位 + +## 一、DeepData 解决什么问题 + +### 典型的痛点场景 + +做模型微调或 RAG 的团队，都绕不开同一条流水线：**数据从哪来 → 怎么洗干净 → 缺标注怎么办 → 质量够不够 → 能不能进知识库**。 + +自建这套东西的典型代价： + +| 环节 | 自建方案 | 问题 | +|---|---|---| +| 数据归集 | 写 DataX 调度脚本 + 手工执行 | 失败了只能靠日志；无重试、无状态记录 | +| 数据清洗 | PySpark脚本串成一条链 | 参数一改要改代码；无法可视化调参 | +| 数据标注 |自建 Label Studio + CVAT | 两套系统数据对不上；标注结果回不去 | +| 算子管理 | 脚本堆成 utils.py | 谁写的、什么版本、怎么复用，没人说得清 | +| 质量评估 | 人工抽查 | 不系统，无法量化 | +| 知识构建 | 另写一套向量化脚本 | 与上游数据脱节，语料更新无法感知 | + +DeepData 的价值就是**把这条链路上的人力搬运全部收进一个平台**。 + +### 核心主张 + +> **数据处理的成本应该集中在算法本身，而不是在胶水脚本上。** + +平台提供：可视化拖拽编排 + 标准化算子 + 一体化元数据存储，让数据工程师只关注"用什么算子、参数怎么调"，而不是"怎么把这20 个脚本串起来跑"。 + +--- + +## 二、目标用户与角色 + +| 角色 | 用DeepData 做什么 | 常用模块 | +|---|---|---| +| 数据管理员 | 建数据集、发起标注任务、回收结果 | 数据管理、数据标注 | +| 数据工程师 | 编排清洗流水线、调算子参数 | 数据清洗、算子市场 | +| 算法工程师 | 合成指令数据、质量评估 | 数据合成、数据评估 | +| 知识库工程师 | 构建 RAG 知识库、管向量索引 | 知识生成 | +| 标注团队 | 在 CVAT 里标图、审核、验收 | 见[标注作业 SOP](使用说明#六deepdatacvat-标注作业流程sop) | + +**注意**：DeepData 与 CVAT/Label Studio 的职责是**分离**的 —— DeepData 管数据（发起与回收），CVAT/Label Studio 管人与流程（分配、标注、审核）。理解这个边界是理解整个系统的前提。 + +--- + +## 三、典型使用场景 + +### 场景 1：大模型训练语料准备 + +``` +原始PDF/图片 → 数据归集 → 解析算子(MarkItDown/MinerU) → 清洗(去重/去噪/PII) +→ 质量评估 → 合成指令数据(qwen2.5 蒸馏) → 入库 → 微调 +``` +对应模块：归集 → 管理 → 清洗 → 评估 → 合成 + +### 场景 2：RAG 知识库构建 + +``` +文档 → 解析(MinerU 提取图文) → 切片(slicer 算子) → 向量化(知识生成) +→ Milvus 索引 → 提供检索 API +``` +对应模块：知识生成 + RAG 索引服务 + +### 场景 3：图像目标检测标注 + +``` +数据集(1000 张图) → 创建标注任务(平台选 CVAT) → CVAT 侧切 Job 分工 +→ 标注审核 → 同步回 DeepData → 标签落入 t_dm_dataset_files.tags +``` +详见[标注作业 SOP](使用说明#六deepdatacvat-标注作业流程sop) + +### 场景 4：多源数据归集 + +``` +NFS/S3/HDFS/数据库/API → DataX 统一 reader → 归集模板 → 数据集 +``` +对应模块：数据归集 + `runtime/datax` + +--- + +## 四、选型判断：什么时候该用、什么时候不该用 + +### 适合用DeepData 的情况 + +- 需要**端到端**流水线，且团队里有人负责数据而非只做算法 +- 语料需要**反复迭代**（改一个参数重跑全链路是常态） +- 需要让**非工程角色**（标注团队、数据管理员）参与流程 +- 多模态数据（图片、PDF、音频）需要统一管理 +- 需要在 RAG 与微调之间**复用同一套数据底座** + +### 不建议用的情况 + +- 数据量小、流程固定、一次跑完就结束（杀鸡用牛刀） +- 强依赖 Hadoop 生态做超大规模批处理（DeepData 的调度是轻量的，不适合 PB 级离线批） +- 需要严格的实时/流式处理（平台以任务制为主，无流式调度） +- 团队只有算法工程师、无数据工程支持（学习成本高于收益） + +--- + +## 五、与相邻方案的关系 + +| 方案 | 定位差异 | +|---|---| +| CVAT / Label Studio | **只做标注**，不做数据底座。DeepData 负责与它们对接 | +| DataX | **只做数据传输**，无编排无元数据。DeepData 内置集成 | +| Data-Juicer | 侧重**数据清洗算法本身**。DeepData 通过容器集成（profile `data-juicer`） | +| MinerU | **只做 PDF 解析**。DeepData 通过远端 API 调用 | +| Milvus | **只做向量存储检索**。DeepData 负责喂数据进去 | +| DeepFlow | **只做深度研究 Agent**。作为可选组件挂在 `deep-flow` profile | + +DeepData 的定位是**把这些工具串起来的中枢**，而非替代它们。 + +--- + +## 六、需求到功能的映射 + +| 原始需求 | 平台能力 | 实现载体 | +|---|---|---| +| 数据要有地方放 | 数据集 + 对象存储 | `t_dm_datasets` + MinIO/S3 | +| 清洗要能调参重跑 | 可视化编排 + 算子参数化 | `runtime/ops` 算子 + settings 定义 | +| 标注要能协作分工 | 对接 CVAT/Label Studio | 标注模块 + 双向同步服务 | +| 算子要能复用共享 | 算子市场 | `t_operator` + 上传打包机制 | +| 质量要能量化评估 | 数据评估模块 | `t_de_eval_task` / `_file` / `_item` | +| 要能追溯数据怎么来的 | 血缘管理 | `t_lineage_node` / `t_lineage_edge` | +| 语料要能给 RAG 用 | 知识生成 + 向量索引 | Milvus + rag-indexer-service | + +--- + +**下一页**：[产品功能](产品功能) —— 八大模块的具体能力边界 \ No newline at end of file