文档

• 1: 概述
• 2: 快速开始
• 2.1: 安装部署指南
• 2.2: 系统架构
• 2.3: 开发环境搭建
• 3: 用户指南
• 3.1: 数据归集
• 3.2: 数据管理
• 3.3: 数据清洗
• 3.4: 数据标注
• 3.5: 数据合成
• 3.6: 数据评估
• 3.7: 知识库管理
• 3.8: 算子市场
• 3.9: 流水线编排
• 3.10: Agent 对话
• 4: API 参考
• 4.1: 数据管理 API
• 5: 开发者指南
• 5.1: 后端架构
• 5.2: 前端架构
• 6: 附录
• 6.1: 配置参数
• 6.2: 故障排查
• 7: 贡献指南

1 - 概述

产品定位

DataMate 致力于解决大模型落地过程中的数据痛点，提供一站式数据治理解决方案：

• 全流程覆盖：从数据采集到数据评估，覆盖数据处理全生命周期
• 企业级能力：支持千万级数据并发处理，提供私有化部署方案
• 灵活扩展：内置丰富的数据处理算子，支持自定义算子开发
• 可视化编排：拖拽式流水线设计，无需编码即可完成复杂的数据处理流程

核心功能

数据采集

• 基于 DataX 的异构数据源采集能力
• 支持关系型数据库、NoSQL、文件系统等多种数据源
• 灵活的任务配置和监控机制

数据管理

• 统一的数据集管理，支持图像、文本、音频、视频、多模态等多种数据类型
• 提供文件上传、下载、预览等完整的数据操作能力
• 支持标签和元数据管理，便于数据组织和检索

数据清洗

• 内置丰富的数据清洗算子
• 可视化清洗模板配置
• 支持批处理和流式处理模式

数据标注

• 集成 Label Studio 提供专业标注能力
• 支持图像分类、目标检测、文本分类等多种标注类型
• 提供标注审核和质量控制机制

数据合成

• 基于大模型的数据增强和合成能力
• 支持指令模板管理和自定义
• 提供比例合成任务，满足多样化数据需求

数据评估

• 多维度数据质量评估指标
• 支持自动评估和手动评估
• 生成详细的评估报告

知识库管理（RAG）

• 支持多种文档格式的知识库构建
• 自动化文本切分和向量化
• 集成向量检索能力，支持 RAG 应用

算子市场

• 丰富的内置数据处理算子
• 支持算子发布和共享
• 提供自定义算子开发能力

流水线编排

• 可视化拖拽式流程设计
• 支持多种节点类型和配置
• 提供流程执行监控和调试能力

Agent 对话

• 集成大模型对话能力
• 支持知识库问答
• 提供对话历史管理

技术架构

整体架构

DataMate 采用微服务架构，核心组件包括：

• 前端：React 18 + TypeScript + Ant Design + Tailwind CSS
• 后端：Java 21 + Spring Boot 3.5.6 + Spring Cloud + MyBatis Plus
• 运行时：Python FastAPI + LangChain + Ray
• 数据库：PostgreSQL + Redis + Milvus + MinIO

微服务组件

• API Gateway (8080)：统一入口，负责路由和认证
• Main Application：核心业务逻辑
• Data Management Service (8092)：数据集管理
• Data Collection Service：数据采集任务管理
• Data Cleaning Service：数据清洗任务管理
• Data Annotation Service：数据标注任务管理
• Data Synthesis Service：数据合成任务管理
• Data Evaluation Service：数据评估任务管理
• Operator Market Service：算子市场管理
• RAG Indexer Service：知识库索引服务
• Runtime Service (8081)：算子执行引擎
• Backend Python Service (18000)：Python 后端服务

应用场景

模型微调

• 训练数据清洗和质量提升
• 数据增强和合成
• 训练数据评估

RAG 应用

• 企业知识库构建
• 文档向量化索引
• 语义检索和问答

数据治理

• 多源数据统一管理
• 数据血缘追踪
• 数据质量监控

部署方式

DataMate 支持多种部署方式：

• Docker Compose：快速体验和开发测试
• Kubernetes/Helm：生产环境部署
• 离线部署：支持内网环境部署

与其他产品的对比

下一步

• 快速开始 - 5 分钟快速部署 DataMate
• 用户指南 - 详细的功能使用说明
• API 参考 - 完整的 API 文档
• 开发者指南 - 架构设计和开发指南

2 - 快速开始

DataMate 支持两种主要的部署方式：

• Docker Compose：适合快速体验、开发测试环境
• Kubernetes/Helm：适合生产环境部署

前置条件

Docker Compose 部署

• Docker 20.10+
• Docker Compose 2.0+
• 至少 4GB 内存
• 至少 10GB 磁盘空间

Kubernetes 部署

• Kubernetes 1.20+
• Helm 3.0+
• kubectl 配置好集群连接
• 至少 8GB 内存
• 至少 20GB 磁盘空间

5 分钟快速部署（Docker Compose）

1. 拉取代码

git clone https://github.com/ModelEngine-Group/DataMate.git
cd DataMate

2. 启动服务

使用提供的 Makefile 进行一键部署：

make install

执行命令后，系统会提示选择部署方式：

Choose a deployment method:
1. Docker/Docker-Compose
2. Kubernetes/Helm
Enter choice:

输入 1 选择 Docker Compose 部署。

3. 验证部署

服务启动后，可以通过以下方式访问：

• 前端界面：http://localhost:30000
• API 网关：http://localhost:8080
• 数据库：localhost:5432

4. 查看服务状态

docker ps

您应该能看到以下容器在运行：

• datamate-frontend (前端服务)
• datamate-backend (后端服务)
• datamate-backend-python (Python 后端服务)
• datamate-gateway (API 网关)
• datamate-database (PostgreSQL 数据库)
• datamate-runtime (算子运行时)

可选组件安装

安装 Milvus 向量数据库

Milvus 用于知识库的向量存储和检索：

make install-milvus

选择 Docker Compose 部署方式。

安装 Label Studio 标注工具

Label Studio 用于数据标注功能：

make install-label-studio

访问地址：http://localhost:30001

默认账号：

• 用户名：admin@demo.com
• 密码：demoadmin

安装 MinerU PDF 处理服务

MinerU 用于增强 PDF 文档处理能力：

make build-mineru
make install-mineru

安装 DeerFlow 服务

DeerFlow 用于工作流编排增强功能：

make install-deer-flow

使用本地镜像开发

如果您修改了本地代码，可以使用本地镜像进行部署：

make build
make install dev=true

离线环境部署

对于离线环境，可以预先下载所有镜像：

make download SAVE=true

镜像将保存在 dist/ 目录下。在目标机器上加载镜像：

make load-images

卸载

卸载 DataMate

make uninstall

系统会提示是否删除数据卷：

• 选择 1：删除所有数据（包括数据集、配置等）
• 选择 2：保留数据卷

仅卸载特定组件

# 卸载 Label Studio
make uninstall-label-studio

# 卸载 Milvus
make uninstall-milvus

# 卸载 DeerFlow
make uninstall-deer-flow

下一步

• 安装部署指南 - 详细的安装和配置说明
• 系统架构 - 了解 DataMate 的技术架构
• 开发环境搭建 - 本地开发环境配置

常见问题

Q: 服务启动失败怎么办？

A: 首先检查端口是否被占用：

# 检查端口占用
lsof -i :30000
lsof -i :8080

如果端口被占用，可以修改 deployment/docker/datamate/docker-compose.yml 中的端口映射。

Q: 如何查看服务日志？

# 查看所有服务日志
docker compose -f deployment/docker/datamate/docker-compose.yml logs

# 查看特定服务日志
docker compose -f deployment/docker/datamate/docker-compose.yml logs -f datamate-backend

Q: 数据存储在哪里？

数据通过 Docker 卷进行持久化存储：

• datamate-dataset-volume：数据集文件
• datamate-postgresql-volume：数据库数据
• datamate-log-volume：日志文件

可以使用以下命令查看所有卷：

docker volume ls | grep datamate

2.1 - 安装部署指南

系统要求

最低配置

软件依赖

Docker Compose 部署

• Docker 20.10+
• Docker Compose 2.0+
• Git (可选，用于克隆代码)
• Make (可选，用于使用 Makefile)

Kubernetes 部署

• Kubernetes 1.20+
• Helm 3.0+
• kubectl (与集群版本匹配)
• Git (可选，用于克隆代码)
• Make (可选，使用 Makefile)

部署方式对比

Docker Compose 部署

基础部署

1. 准备工作

# 克隆代码仓库
git clone https://github.com/ModelEngine-Group/DataMate.git
cd DataMate

# 检查 Docker 和 Docker Compose 版本
docker --version
docker compose version

2. 使用 Makefile 部署

# 一键部署（包括 Milvus）
make install

在提示中选择 1. Docker/Docker-Compose。

3. 直接使用 Docker Compose

如果没有安装 Make，可以直接使用 Docker Compose：

# 设置镜像仓库（可选）
export REGISTRY=ghcr.io/modelengine-group/

# 启动基础服务
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d

4. 验证部署

# 检查容器状态
docker ps

# 查看服务日志
docker compose -f deployment/docker/datamate/docker-compose.yml logs -f

# 访问前端界面
open http://localhost:30000

可选组件部署

Milvus 向量数据库

Milvus 用于知识库的向量存储和检索。

# 使用 Makefile
make install-milvus

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d

组件包括：

• milvus-standalone (19530, 9091)
• milvus-minio (9000, 9001)
• milvus-etcd

Label Studio 标注工具

# 使用 Makefile
make install-label-studio

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile label-studio up -d

访问地址：http://localhost:30001

默认账号：

• 用户名：admin@demo.com
• 密码：demoadmin

MinerU PDF 处理服务

MinerU 提供增强的 PDF 文档解析能力，支持 NPU 加速。

# 构建 MinerU 镜像
make build-mineru

# 部署 MinerU
make install-mineru

支持的平台：

• mineru (默认，910B)
• mineru-910C
• mineru-310P

DeerFlow 工作流服务

# 使用 Makefile
make install-deer-flow

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile deer-flow up -d

Redis 缓存

# 使用 Makefile
make install-redis

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile redis up -d

环境变量配置

可以在 deployment/docker/datamate/docker-compose.yml 中配置以下环境变量：

数据卷管理

DataMate 使用以下 Docker 卷进行数据持久化：

# 查看所有卷
docker volume ls | grep datamate

# 查看卷详情
docker volume inspect datamate-dataset-volume

# 备份卷数据
docker run --rm -v datamate-dataset-volume:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/dataset-backup.tar.gz /data

# 恢复卷数据
docker run --rm -v datamate-dataset-volume:/data -v $(pwd):/backup \
  ubuntu tar xzf /backup/dataset-backup.tar.gz -C /

Kubernetes/Helm 部署

前置准备

# 检查集群连接
kubectl cluster-info
kubectl get nodes

# 检查 Helm 版本
helm version

# 创建命名空间（可选）
kubectl create namespace datamate

使用 Makefile 部署

# 部署 DataMate
make install INSTALLER=k8s

# 或直接部署到指定命名空间
make install NAMESPACE=datamate INSTALLER=k8s

使用 Helm 部署

1. 部署基础服务

# 添加 Helm 仓库（如果需要）
# helm repo add datamate https://charts.datamate.io

# 部署 DataMate
helm upgrade datamate deployment/helm/datamate/ \
  --install \
  --namespace datamate \
  --create-namespace \
  --set global.image.repository=ghcr.io/modelengine-group/

# 查看部署状态
kubectl get pods -n datamate

2. 配置 Ingress（可选）

# 编辑 values.yaml
cat >> deployment/helm/datamate/values.yaml << EOF
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: datamate.example.com
      paths:
        - path: /
          pathType: Prefix
EOF

# 重新部署
helm upgrade datamate deployment/helm/datamate/ \
  --namespace datamate \
  -f deployment/helm/datamate/values.yaml

3. 部署可选组件

# 部署 Milvus
helm upgrade milvus deployment/helm/milvus \
  --install \
  --namespace datamate

# 部署 Label Studio
helm upgrade label-studio deployment/helm/label-studio/ \
  --install \
  --namespace datamate

# 部署 DeerFlow
helm upgrade deer-flow deployment/helm/deer-flow \
  --install \
  --namespace datamate \
  --set global.image.repository=ghcr.io/modelengine-group/

Helm 配置选项

主要配置项（deployment/helm/datamate/values.yaml）：

# 镜像配置
global:
  image:
    repository: ghcr.io/modelengine-group/
    pullPolicy: IfNotPresent
    tag: latest

# 服务配置
services:
  frontend:
    port: 30000
  gateway:
    port: 8080
  backend:
    port: 8092

# 资源配置
resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "2000m"

# 存储配置
persistence:
  enabled: true
  storageClass: standard
  size: 50Gi

查看日志和调试

# 查看 Pod 状态
kubectl get pods -n datamate

# 查看服务日志
kubectl logs -f deployment/datamate-backend -n datamate

# 查看所有资源
kubectl get all -n datamate

# 端口转发进行本地调试
kubectl port-forward svc/datamate-gateway 8080:8080 -n datamate

离线环境部署

准备离线镜像包

1. 下载镜像

# 下载所有镜像到本地
make download SAVE=true

# 下载指定版本
make download VERSION=v1.0.0 SAVE=true

# 指定平台下载
make download PLATFORM=linux/amd64 SAVE=true

镜像将保存在 dist/ 目录。

2. 打包传输

# 打包
tar czf datamate-images.tar.gz dist/

# 传输到目标服务器
scp datamate-images.tar.gz user@target-server:/tmp/

离线安装

1. 加载镜像

# 在目标服务器上解压
tar xzf datamate-images.tar.gz

# 加载所有镜像
make load-images

# 或手动加载
for img in dist/*.tar; do
  docker load -i $img
done

2. 修改配置

使用本地镜像时，设置 REGISTRY 为空：

# Docker Compose 部署
REGISTRY= docker compose -f deployment/docker/datamate/docker-compose.yml up -d

# 或使用 Makefile
make install dev=true

3. 离线依赖

某些组件可能需要额外的离线资源：

• Python 包：预装在运行时镜像中
• Node 包：预装在前端镜像中
• Java 包：预装在后端镜像中

升级指南

Docker Compose 升级

# 1. 备份数据
docker run --rm -v datamate-postgresql-volume:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/postgres-backup.tar.gz /data

# 2. 拉取新镜像
docker pull ghcr.io/modelengine-group/datamate-backend:latest
docker pull ghcr.io/modelengine-group/datamate-frontend:latest
# ... 其他镜像

# 3. 停止服务
docker compose -f deployment/docker/datamate/docker-compose.yml down

# 4. 启动新版本
docker compose -f deployment/docker/datamate/docker-compose.yml up -d

# 5. 验证升级
docker ps
docker logs -f datamate-backend

或使用 Makefile：

make datamate-docker-upgrade

Kubernetes 升级

# 1. 备份数据
kubectl exec -n datamate deployment/datamate-database -- \
  pg_dump -U postgres datamate > backup.sql

# 2. 更新 Helm Chart
helm upgrade datamate deployment/helm/datamate/ \
  --namespace datamate \
  --set global.image.tag=new-version

# 3. 监控升级状态
kubectl rollout status deployment/datamate-backend -n datamate

# 4. 查看新 Pod 状态
kubectl get pods -n datamate

卸载

Docker Compose 完全卸载

# 使用 Makefile
make uninstall

# 选择删除数据卷以完全清理

或手动卸载：

# 停止并删除容器
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus --profile label-studio down -v

# 删除所有卷
docker volume rm datamate-dataset-volume \
  datamate-postgresql-volume \
  datamate-log-volume \
  # ... 其他卷

# 删除网络
docker network rm datamate-network

Kubernetes 完全卸载

# 卸载所有组件
make uninstall INSTALLER=k8s

# 或使用 Helm
helm uninstall datamate -n datamate
helm uninstall milvus -n datamate
helm uninstall label-studio -n datamate
helm uninstall deer-flow -n datamate

# 删除命名空间
kubectl delete namespace datamate

# 删除 PV/PVC（根据存储类）
kubectl delete pvc -n datamate --all

故障排查

常见问题

1. 服务无法启动

# 检查端口占用
netstat -tlnp | grep -E '30000|8080|5432'

# 检查磁盘空间
df -h

# 检查内存使用
free -h

# 查看详细日志
docker logs datamate-backend --tail 100

2. 数据库连接失败

# 检查数据库容器
docker ps | grep database

# 测试数据库连接
docker exec -it datamate-database psql -U postgres -d datamate

# 检查数据库日志
docker logs datamate-database

3. 前端无法访问后端

# 检查网关配置
docker logs datamate-gateway

# 检查网络连接
docker network inspect datamate-network

# 测试 API 连接
curl http://localhost:8080/api/v1/health

4. Milvus 连接失败

# 检查 Milvus 状态
docker logs milvus-standalone

# 检查依赖服务
docker logs milvus-etcd
docker logs milvus-minio

# 测试 Milvus 连接
curl http://localhost:19530/healthz

日志位置

获取帮助

如果遇到问题：

1. 查看 故障排查文档
2. 搜索 GitHub Issues
3. 提交新的 Issue 并附上详细的错误日志

2.2 - 系统架构

整体架构

DataMate 采用微服务架构，将系统拆分为多个独立的服务，每个服务负责特定的业务功能。这种架构提供了良好的可扩展性、可维护性和容错性。

┌─────────────────────────────────────────────────────────────────┐
│                           前端层                                │
│                    (React + TypeScript)                         │
│                      Ant Design + Tailwind                      │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                        API 网关层                               │
│                    (Spring Cloud Gateway)                       │
│                      端口: 8080                                  │
└────────────────────────┬────────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Java 后端   │ │ Python 后端  │ │  运行时服务  │
│   服务组     │ │    服务      │ │   (Ray)      │
├──────────────┤ ├──────────────┤ ├──────────────┤
│· Main App    │ │· RAG Service │ │· Operator    │
│· Data Mgmt   │ │· LangChain   │ │  Execution  │
│· Collection  │ │· FastAPI     │ │              │
│· Cleaning    │ │              │ │              │
│· Annotation  │ │              │ │              │
│· Synthesis   │ │              │ │              │
│· Evaluation  │ │              │ │              │
│· Operator    │ │              │ │              │
│· Pipeline    │ │              │ │              │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                │
       └────────────────┼────────────────┘
                        ▼
         ┌──────────────┴──────────────┐
         │                              │
    ┌────▼────┐    ┌─────────┐   ┌─────▼────┐
    │PostgreSQL│    │  Redis  │   │  Milvus  │
    │  (5432)  │    │ (6379)  │   │ (19530)  │
    └──────────┘    └─────────┘   └──────────┘
                                              │
                                        ┌─────▼─────┐
                                        │   MinIO   │
                                        │  (9000)   │
                                        └───────────┘

技术栈

前端技术栈

后端技术栈（Java）

后端技术栈（Python）

数据存储

微服务架构

服务列表

服务通信

同步通信

• API Gateway → 后端服务：HTTP/REST
• 前端 → API Gateway：HTTP/REST
• 后端服务之间：HTTP/REST (Feign Client)

异步通信

• 任务执行：通过数据库任务队列
• 事件通知：Redis Pub/Sub

服务发现与注册

DataMate 使用简单的服务注册机制：

• 服务启动时向数据库注册
• API Gateway 从数据库获取服务列表
• 支持服务的动态扩缩容

数据架构

数据流转

┌─────────────┐
│  数据采集   │ 采集任务配置
│  Collection │ → DataX → 原始数据
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  数据管理   │ 数据集管理、文件上传
│ Management  │ → 结构化存储
└──────┬──────┘
       │
       ├──────────────┐
       ▼              ▼
┌─────────────┐  ┌─────────────┐
│  数据清洗   │  │  知识库     │
│  Cleaning   │  │  Knowledge  │
│             │  │  Base       │
└──────┬──────┘  └──────┬──────┘
       │                │
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│  数据标注   │  │  向量索引    │
│  Annotation │  │  Milvus      │
└──────┬──────┘  └──────┬──────┘
       │                │
       ▼                │
┌─────────────┐          │
│  数据合成   │          │
│  Synthesis  │          │
└──────┬──────┘          │
       │                │
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│  数据评估   │  │  RAG 检索   │
│  Evaluation │  │  Retrieval  │
└─────────────┘  └─────────────┘

数据存储模型

PostgreSQL

• 业务数据：用户、数据集、任务、配置
• 关系数据：服务间的关联关系
• 事务数据：需要强一致性的数据

Redis

• 缓存数据：热点数据缓存
• 会话数据：用户会话信息
• 任务队列：异步任务队列

Milvus

• 向量数据：文档向量 embeddings
• 向量索引：高效的相似度搜索

MinIO

• 文件存储：原始文件、处理结果
• 大数据文件：不适合数据库存储的文件

部署架构

Docker Compose 部署

┌────────────────────────────────────────────────┐
│              Docker Network                    │
│            datamate-network                    │
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │Frontend  │  │ Gateway  │  │ Backend  │   │
│  │ :30000   │  │  :8080   │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │Backend   │  │ Runtime  │  │Database  │   │
│  │  Python  │  │  :8081   │  │  :5432   │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Milvus  │  │  MinIO   │  │  etcd    │   │
│  │  :19530  │  │  :9000   │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────────────────────────────┘

Kubernetes 部署

┌────────────────────────────────────────────────┐
│           Kubernetes Cluster                   │
│                                                │
│  Namespace: datamate                           │
│                                                │
│  ┌────────────┐  ┌────────────┐              │
│  │ Deployment │  │ Deployment │              │
│  │  Frontend  │  │  Gateway   │              │
│  │   (3 Pods) │  │  (2 Pods)  │              │
│  └─────┬──────┘  └─────┬──────┘              │
│        │                │                     │
│  ┌─────▼────────────────▼──────┐              │
│  │       Service (LoadBalancer) │              │
│  └──────────────────────────────┘              │
│                                                │
│  ┌────────────┐  ┌────────────┐              │
│  │ StatefulSet│  │ Deployment │              │
│  │  Database  │  │  Backend   │              │
│  └────────────┘  └────────────┘              │
└────────────────────────────────────────────────┘

安全架构

认证与授权

JWT 认证（可选）

datamate:
  jwt:
    enable: true  # 启用 JWT 认证
    secret: your-secret-key
    expiration: 86400  # 24 小时

API Key 认证

datamate:
  api-key:
    enable: false

数据安全

传输加密

• API Gateway 支持 HTTPS/TLS
• 内部服务通信可配置加密

存储加密

• 数据库支持透明数据加密 (TDE)
• MinIO 支持服务端加密
• Milvus 支持加密存储

网络隔离

• Docker Network 隔离
• Kubernetes Network Policy
• VPC 隔离（云环境）

访问控制

基于角色的访问控制 (RBAC)

• 管理员：所有权限
• 数据管理员：数据管理权限
• 标注员：标注权限
• 查看者：只读权限

数据权限

• 数据集级权限控制
• 文件级权限控制
• 任务级权限控制

扩展性设计

水平扩展

无状态服务

• 前端：支持多副本
• Gateway：支持多副本
• Backend 服务：支持多副本

有状态服务

• 数据库：主从复制、分库分表
• Milvus：分布式部署
• MinIO：分布式纠删码

垂直扩展

资源配置

resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

缓存策略

多级缓存

1. 浏览器缓存：静态资源
2. CDN 缓存：公共资源
3. Redis 缓存：热点数据
4. 数据库缓存：查询缓存

监控与可观测性

日志管理

日志级别

• DEBUG：详细调试信息
• INFO：一般信息
• WARN：警告信息
• ERROR：错误信息

日志存储

/var/log/datamate/
├── frontend/
├── backend/
├── database/
└── runtime/

性能监控

指标收集

• JVM 指标
• HTTP 指标
• 数据库指标
• 自定义业务指标

监控工具（可选）

• Prometheus + Grafana
• ELK Stack (Elasticsearch + Logstash + Kibana)

高可用设计

服务高可用

健康检查

livenessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

自动重启

• Docker restart policy
• Kubernetes restart policy

数据高可用

数据库

• 主从复制
• 自动故障转移
• 定期备份

对象存储

• 纠删码
• 多区域复制

向量数据库

• 主从架构
• 灾备恢复

性能优化

前端优化

• 代码分割
• 懒加载
• CDN 加速
• 资源压缩

后端优化

• 连接池优化
• 查询优化
• 缓存策略
• 异步处理

数据库优化

• 索引优化
• 分区表
• 查询优化
• 连接池配置

下一步

• 开发环境搭建 - 本地开发环境配置
• 后端架构 - 详细的后端架构说明
• 前端架构 - 详细的前端架构说明

2.3 - 开发环境搭建

前置要求

必需软件

推荐软件

• IDE：IntelliJ IDEA (后端) + VS Code (前端/Python)
• 数据库客户端：DBeaver、pgAdmin
• API 测试工具：Postman、curl
• Git 客户端：GitKraken、SourceTree

代码结构

DataMate/
├── backend/                 # Java 后端
│   ├── services/           # 微服务模块
│   │   ├── main-application/
│   │   ├── data-management-service/
│   │   ├── data-cleaning-service/
│   │   ├── data-collection-service/
│   │   ├── data-annotation-service/
│   │   ├── data-synthesis-service/
│   │   ├── data-evaluation-service/
│   │   ├── operator-market-service/
│   │   └── rag-indexer-service/
│   ├── openapi/            # OpenAPI 规范
│   └── scripts/            # 构建脚本
├── frontend/               # React 前端
│   ├── src/
│   │   ├── components/    # 公共组件
│   │   ├── pages/         # 页面组件
│   │   ├── services/      # API 服务
│   │   ├── store/         # Redux store
│   │   └── routes/        # 路由配置
│   └── package.json
├── runtime/                # Python 运行时
│   ├── deer-flow/         # DeerFlow 集成
│   └── datamate/          # DataMate 运行时
└── deployment/             # 部署配置
    ├── docker/            # Docker 配置
    └── helm/              # Helm Charts

后端开发环境

1. 安装 Java 21

# macOS (使用 Homebrew)
brew install openjdk@21

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install openjdk-21-jdk

# 验证安装
java -version

2. 安装 Maven

# macOS
brew install maven

# Linux
sudo apt install maven

# 验证安装
mvn -version

3. 配置 IDE（IntelliJ IDEA）

安装插件

• Lombok Plugin
• MyBatis Plugin
• Rainbow Brackets
• GitToolBox

导入项目

1. 打开 IntelliJ IDEA
2. 选择 File → Open
3. 选择 backend 目录
4. 等待 Maven 依赖下载完成

配置运行配置

创建 Spring Boot 运行配置：

• 主类：对应服务的 Application 类
• 工作目录：服务模块目录
• VM 参数：-Dspring.profiles.active=dev

4. 配置数据库

启动本地数据库（Docker）

# 仅启动数据库
docker compose -f deployment/docker/datamate/docker-compose.yml up -d datamate-database

# 查看数据库连接信息
docker logs datamate-database

默认连接信息：

• 主机：localhost
• 端口：5432
• 数据库：datamate
• 用户名：postgres
• 密码：password

初始化数据库

# 使用 Flyway 迁移（如果配置）
mvn flyway:migrate

# 或执行 SQL 脚本
psql -h localhost -U postgres -d datamate -f schema.sql

5. 运行后端服务

使用 Maven 运行

cd backend/services/main-application
mvn spring-boot:run

使用 IDE 运行

1. 找到对应的 Application 类
2. 右键 → Run
3. 访问 http://localhost:8080

6. 开发配置

编辑 application-dev.yml：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/datamate
    username: postgres
    password: password
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

logging:
  level:
    com.datamate: DEBUG

前端开发环境

1. 安装 Node.js

# macOS (使用 Homebrew)
brew install node@18

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v

2. 安装 pnpm

npm install -g pnpm

# 验证安装
pnpm -v

3. 安装依赖

cd frontend

# 安装依赖
pnpm install

4. 配置开发环境

创建 .env.development：

# API 地址
VITE_API_BASE_URL=http://localhost:8080
VITE_API_TIMEOUT=30000

# 其他配置
VITE_APP_TITLE=DataMate Dev

5. 启动开发服务器

# 启动开发服务器
pnpm dev

# 或指定端口
pnpm dev --port 3000

访问 http://localhost:3000

6. 构建生产版本

# 构建
pnpm build

# 预览构建结果
pnpm preview

7. 前端开发技巧

热更新

• 修改 .tsx 或 .css 文件会自动热更新
• 修改配置文件需要重启

代理配置

在 vite.config.ts 中配置代理：

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
    }
  }
}

路径别名

import MyComponent from '@/components/MyComponent';
import { useStore } from '@/store/hooks';

Python 服务开发环境

1. 安装 Python 3.11

# macOS
brew install python@3.11

# Linux
sudo apt install python3.11 python3.11-venv

# 验证安装
python3.11 --version

2. 创建虚拟环境

# 进入项目目录
cd runtime/datamate

# 创建虚拟环境
python3.11 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

3. 安装依赖

# 安装依赖
pip install -r requirements.txt

# 或使用 uv（更快）
pip install uv
uv pip install -r requirements.txt

4. 配置环境变量

创建 .env 文件：

# 数据库配置
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=password
PG_DATABASE=datamate

# 日志级别
log_level=DEBUG

# JWT 配置
datamate_jwt_enable=false

5. 运行 Python 服务

# 运行运行时服务
python /opt/runtime/datamate/operator_runtime.py --port 8081

# 或使用 FastAPI
uvicorn main:app --reload --port 18000

6. Python 开发工具

推荐插件

• Python (VS Code)
• Pylance
• Python Test Explorer

代码格式化

# Black
pip install black
black .

# isort
pip install isort
isort .

# 自动格式化
pip install autopep8

本地调试

1. 启动所有服务

使用 Docker Compose

# 启动基础服务（数据库、Redis 等）
docker compose -f deployment/docker/datamate/docker-compose.yml up -d \
  datamate-database \
  datamate-redis

# 启动 Milvus（可选）
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d

启动后端服务

# 终端 1：启动 Main Application
cd backend/services/main-application
mvn spring-boot:run

# 终端 2：启动 Data Management Service
cd backend/services/data-management-service
mvn spring-boot:run

# ... 其他服务

启动前端

cd frontend
pnpm dev

启动 Python 服务

# 终端 N：启动运行时服务
cd runtime/datamate
python operator_runtime.py --port 8081

# 终端 N+1：启动后端 Python 服务
cd backend-python
uvicorn main:app --reload --port 18000

2. 调试技巧

后端调试

在 IntelliJ IDEA 中：

1. 在代码行号处点击设置断点
2. 右键 → Debug 运行配置
3. 发送请求触发断点

前端调试

在浏览器中：

1. 按 F12 打开开发者工具
2. 使用 console.log 或 debugger 语句
3. React DevTools 查看组件状态

Python 调试

在 VS Code 中：

1. 安装 Python 扩展
2. 创建 launch.json 配置
3. 设置断点并 F5 启动调试

3. 日志查看

# Docker 容器日志
docker logs -f datamate-backend

# 应用日志
tail -f /var/log/datamate/backend/app.log

# 只查看错误日志
tail -f /var/log/datamate/backend/app.log | grep ERROR

代码规范

Java 代码规范

命名规范

• 类名：大驼峰 UserService
• 方法名：小驼峰 getUserById
• 常量：全大写 MAX_SIZE
• 变量：小驼峰 userName

注释规范

/**
 * 用户服务
 *
 * @author Your Name
 * @since 1.0.0
 */
public class UserService {

    /**
     * 根据用户 ID 获取用户信息
     *
     * @param userId 用户 ID
     * @return 用户信息
     * @throws UserNotFoundException 用户不存在异常
     */
    public User getUserById(Long userId) {
        // ...
    }
}

TypeScript 代码规范

命名规范

• 组件：大驼峰 UserProfile
• 类型/接口：大驼峰 UserData
• 函数：小驼峰 getUserData
• 常量：全大写 API_BASE_URL

组件规范

interface UserProfileProps {
  userId: string;
  onUpdate?: () => void;
}

export const UserProfile: React.FC<UserProfileProps> = ({
  userId,
  onUpdate
}) => {
  // 组件逻辑
  return <div>...</div>;
};

export default UserProfile;

Python 代码规范

遵循 PEP 8

def get_user(user_id: int) -> dict:
    """
    获取用户信息

    Args:
        user_id: 用户 ID

    Returns:
        用户信息字典
    """
    # ...

测试

后端测试

# 单元测试
mvn test

# 集成测试
mvn verify

# 生成测试报告
mvn jacoco:report

前端测试

# 单元测试
pnpm test

# E2E 测试
pnpm test:e2e

# 测试覆盖率
pnpm test:coverage

常见问题

后端启动失败

1. 检查 Java 版本：java -version
2. 检查端口占用：lsof -i :8080
3. 查看详细日志
4. 清理并重新构建：mvn clean install

前端启动失败

1. 检查 Node 版本：node -v
2. 删除 node_modules 重新安装：rm -rf node_modules && pnpm install
3. 检查端口占用：lsof -i :3000
4. 清理缓存：pnpm store prune

数据库连接失败

1. 检查数据库是否启动：docker ps | grep postgres
2. 测试连接：psql -h localhost -U postgres -d datamate
3. 检查防火墙设置
4. 验证连接配置

下一步

• 后端架构 - 详细的后端架构说明
• 前端架构 - 详细的前端架构说明
• 贡献指南 - 如何贡献代码

3 - 用户指南

DataMate 提供完整的大模型数据处理解决方案，涵盖数据采集、管理、清洗、标注、合成、评估等全流程。

功能模块

• 数据采集 - 从多种数据源采集数据
• 数据管理 - 管理数据集和文件
• 数据清洗 - 清洗和预处理数据
• 数据标注 - 数据标注和质量控制
• 数据合成 - 基于大模型的数据增强
• 数据评估 - 数据质量评估
• 知识库管理 - RAG 知识库构建
• 算子市场 - 数据处理算子管理
• 流水线编排 - 可视化流程编排
• Agent 对话 - AI 智能助手

典型使用场景

模型微调场景

1. 数据采集 → 2. 数据管理 → 3. 数据清洗 → 4. 数据标注
↓
5. 数据评估 → 6. 导出训练数据

RAG 应用场景

1. 上传文档 → 2. 向量化索引 → 3. 知识库管理
↓
4. Agent 对话（知识库问答）

数据增强场景

1. 准备原始数据 → 2. 创建指令模板 → 3. 数据合成
↓
4. 质量评估 → 5. 导出增强数据

快速链接

• 快速开始 - 部署和安装
• API 参考 - API 文档
• 开发者指南 - 架构和开发

3.1 - 数据归集

功能概述

数据归集模块基于 DataX 实现，支持：

• 多种数据源：MySQL、PostgreSQL、Oracle、SQL Server 等关系型数据库
• 异构同步：不同数据源之间的数据同步
• 批量归集：大规模数据的批量归集和同步
• 定时任务：支持定时执行归集任务
• 任务监控：实时监控归集任务执行状态

支持的数据源

快速开始

1. 创建采集任务

步骤 1：进入数据归集页面

在左侧导航栏选择 数据归集。

步骤 2：点击创建任务

点击右上角 创建任务 按钮。

步骤 3：配置基本信息

填写以下基本信息：

• 名称：为任务取一个有意义的名称
• 超时时间：任务执行超时时间（秒）
• 描述：描述任务用途（可选）

步骤 4：选择同步方式

选择任务的同步方式：

• 立即同步：创建任务后立即执行一次
• 定时同步：按照定时规则周期性执行

选择 定时同步 时，需要配置执行策略：

• 执行周期：每小时 / 每天 / 每周 / 每月
• 执行时间：选择执行时间点

步骤 5：配置数据源

选择数据源类型：从下拉列表中选择数据源类型（如 MySQL、CSV 等）

配置数据源参数：根据选择的数据源模板，填写相应的连接参数（表单形式）

MySQL 示例：

• JDBC URL：jdbc:mysql://localhost:3306/mydb
• 用户名：root
• 密码：password
• 表名：users

步骤 6：配置字段提取

系统不支持配置字段映射，只能从配置的 SQL 中提取部分字段。

• 提取指定字段：在字段列表中填写需要提取的字段名称
• 提取所有字段：不填写字段名称，则提取 SQL 查询结果中的所有字段

步骤 7：创建并执行

点击 创建 按钮创建任务。

• 如果选择 立即同步，任务将自动开始运行
• 如果选择 定时同步，任务将按照定时规则周期性执行

2. 监控任务执行

查看任务列表

在数据采集页面，可以看到所有采集任务及其状态：

查看任务详情

点击任务名称或 查看详情 按钮，可以看到：

• 基本信息：任务配置信息
• 执行记录：历史执行记录
• 执行日志：详细的执行日志
• 数据统计：采集的数据量、成功/失败记录数

查看执行日志

在任务详情页面，点击 执行记录 标签，选择某次执行记录，查看详细日志：

2024-01-15 10:30:00 INFO  任务开始执行
2024-01-15 10:30:01 INFO  连接数据源成功
2024-01-15 10:30:02 INFO  开始读取数据
2024-01-15 10:30:10 INFO  读取数据完成，共 10000 条
2024-01-15 10:30:11 INFO  开始写入目标数据集
2024-01-15 10:30:15 INFO  写入数据完成
2024-01-15 10:30:15 INFO  任务执行成功

3. 任务管理

任务列表中每个任务的操作包括：

• 查看执行记录：查看任务的历次执行情况
• 删除：删除任务（注意：删除任务不会删除已归集的数据）

点击任务名称可以查看任务详情，包括：

• 基本信息配置
• 执行记录列表
• 数据统计信息

常见问题

Q: 任务执行失败怎么办？

A: 按以下步骤排查：

1. 检查数据源连接：确保数据源地址、端口、用户名、密码正确
2. 检查网络连接：确保 DataMate 能访问数据源
3. 查看执行日志：获取详细错误信息
4. 检查数据格式：确保数据格式与配置一致
5. 检查目标数据集：确保目标数据集存在且有写入权限

Q: 如何采集大表数据？

A: 对于大表数据采集：

1. 使用增量采集：配置时间字段进行增量同步
2. 分批采集：将大表拆分为多个小任务
3. 调整并发参数：适当增加 channel 数量
4. 使用过滤条件：只采集需要的数据

Q: 如何实现增量采集？

A: 配置增量采集条件：

在数据源配置中，可以设置查询条件（如 SQL WHERE 子句），例如：

WHERE update_time > '${lastTime}'

系统会在每次执行时记录最后一次执行时间，下次执行时自动使用该时间进行增量采集。

Q: 采集速度慢怎么办？

A: 优化采集速度：

1. 增加并发通道：将 channel 设置为 3-5
2. 调整流控参数：增加 byte 和 record 限制
3. 优化 SQL 查询：使用索引、减少查询字段
4. 使用批量写入：启用批量写入模式

Q: 如何处理数据类型不兼容？

A: 使用类型转换：

{
  "column": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "price",
      "type": "decimal",
      "format": "#.##"
    }
  ]
}

API 参考

详细的 API 文档请参考：

• 数据采集 API

相关文档

• 数据管理 - 采集后的数据管理
• 数据清洗 - 采集后的数据清洗
• 流水线编排 - 将采集任务集成到流水线

3.2 - 数据管理

功能概述

数据管理是 DataMate 的核心模块，提供：

• 多数据类型支持：图像、文本、音频、视频、多模态等
• 文件管理：上传、下载、预览、删除等操作
• 目录结构：支持层级目录组织
• 标签管理：使用标签分类和检索数据
• 统计信息：数据集大小、文件数量等统计

数据集类型

快速开始

1. 创建数据集

步骤 1：进入数据管理页面

在左侧导航栏选择 数据管理。

步骤 2：创建数据集

点击右上角 创建数据集 按钮。

步骤 3：填写基本信息

• 数据集名称：例如 user_images_dataset
• 数据集类型：选择数据类型（如图像）
• 描述：描述数据集的用途（可选）
• 标签：添加标签用于分类（可选）

步骤 4：创建数据集

点击 创建 按钮完成创建。

2. 上传文件

方式一：拖拽上传

1. 进入数据集详情页面
2. 将文件直接拖拽到上传区域
3. 等待上传完成

方式二：点击上传

1. 点击 上传文件 按钮
2. 选择本地文件
3. 等待上传完成

方式三：分片上传（大文件）

对于大文件（>100MB），系统自动使用分片上传：

1. 选择大文件上传
2. 系统自动切分文件
3. 逐片上传
4. 自动合并

方式四：批量上传

支持批量选择多个文件上传：

1. 点击 上传文件 按钮
2. 按住 Ctrl/Cmd 多选文件
3. 点击确定开始上传

3. 创建目录

步骤 1：进入数据集

在数据管理页面，点击数据集名称进入详情。

步骤 2：创建目录

1. 点击 创建目录 按钮
2. 输入目录名称
3. 选择父目录（可选）
4. 点击确定

目录结构示例：

user_images_dataset/
├── train/
│   ├── cat/
│   └── dog/
├── test/
│   ├── cat/
│   └── dog/
└── validation/
    ├── cat/
    └── dog/

4. 管理文件

查看文件

在数据集详情页面，可以看到所有文件列表：

预览文件

点击 预览 按钮，可以在浏览器中预览文件：

• 图像：显示缩略图和详细信息
• 文本：显示文本内容
• 音频：在线播放
• 视频：在线播放

下载文件

• 单个文件下载：点击 下载 按钮

目前不支持批量下载和打包下载。

删除文件

• 单个删除：点击文件的 删除 按钮

目前不支持批量删除。

5. 数据集操作

查看统计信息

在数据集详情页面，可以看到：

• 总文件数：数据集中的文件总数
• 总大小：所有文件的总大小

编辑数据集

点击数据集的 编辑 按钮，可以修改：

• 数据集名称
• 描述
• 标签
• 关联归集任务

删除数据集

点击数据集的 删除 按钮，可以删除整个数据集。

注意：删除数据集会同时删除其中的所有文件，此操作不可恢复。

高级功能

标签管理

创建标签

1. 在数据集列表页，点击 标签管理
2. 点击 创建标签
3. 输入标签名称

使用标签

1. 编辑数据集
2. 在标签栏选择已有标签
3. 保存数据集

标签筛选

在数据集列表页，点击标签可以筛选具有该标签的数据集。

最佳实践

1. 数据集组织

推荐的目录组织方式：

project_dataset/
├── raw/              # 原始数据
├── processed/        # 处理后的数据
├── train/            # 训练数据
├── validation/       # 验证数据
└── test/             # 测试数据

2. 命名规范

• 数据集名称：使用小写字母和下划线，如 user_images_2024
• 目录名称：使用有意义的英文名称，如 train, test, processed
• 文件名称：保持原始文件名或使用规范命名

3. 标签使用

建议使用以下标签分类：

• 项目标签：project-a, project-b
• 状态标签：raw, processed, validated
• 类型标签：image, text, audio
• 用途标签：training, testing, evaluation

4. 数据备份

目前系统不支持自动备份功能，如需备份数据，可以通过以下方式手动下载单个文件：

1. 进入数据集详情页面
2. 找到需要备份的文件
3. 点击文件的 下载 按钮

常见问题

Q: 上传大文件失败怎么办？

A: 大文件上传建议：

1. 使用分片上传：系统自动启用分片上传
2. 检查网络连接：确保网络稳定
3. 调整上传参数：增加超时时间
4. 使用 FTP/SFTP：对于超大文件，建议使用 FTP 上传

Q: 如何导入已有的数据？

A: 三种方式导入已有数据：

1. 上传文件：通过界面上传
2. 添加文件：如果文件已在服务器上，使用添加文件功能
3. 数据采集：使用数据采集模块从外部数据源采集

Q: 如何共享数据集？

A: 目前数据集共享方式：

1. 导出数据集：导出为文件分享
2. 设置权限：（即将推出）设置数据集访问权限
3. API 访问：通过 API 接口访问数据集

Q: 数据集有大小限制吗？

A: 数据集大小限制：

• 单个文件：最大 5GB（分片上传）
• 数据集总大小：受存储空间限制
• 文件数量：没有明确限制

建议定期清理不需要的文件以释放空间。

Q: 如何查看数据集的详细信息？

A: 在数据集详情页面可以查看：

• 基本信息：名称、描述、类型、标签
• 统计信息：文件数、总大小、完成率
• 文件列表：所有文件及其详情
• 操作日志：数据集的操作历史

API 参考

详细的 API 文档请参考：

• 数据管理 API

相关文档

• 数据采集 - 采集数据到数据集
• 数据清洗 - 清洗数据集中的数据
• 数据标注 - 标注数据集中的数据

3.3 - 数据清洗

功能概述

数据清洗模块提供：

• 内置清洗算子：丰富的前置清洗算子库
• 可视化配置：拖拽式配置清洗流程
• 模板管理：保存和复用清洗模板
• 批量处理：支持大规模数据批量清洗
• 实时预览：预览清洗结果

清洗算子类型

数据质量算子

文本清洗算子

图像清洗算子

数据转换算子

快速开始

1. 创建清洗任务

步骤 1：进入数据清洗页面

在左侧导航栏选择 数据处理。

步骤 2：创建任务

点击右上角 创建任务 按钮。

步骤 3：配置基本信息

• 任务名称：例如 user_data_cleansing
• 任务描述：描述清洗任务的目的（可选）
• 源数据集：选择要清洗的数据集
• 输出数据集：选择或创建输出数据集

步骤 4：配置清洗流程

在清洗流程配置页面：

1. 从左侧算子库拖拽算子到中间画布
2. 连接算子形成处理流程
3. 配置每个算子的参数
4. 预览清洗结果

示例流程：

输入数据 → 去重 → 空值处理 → 格式校验 → 输出数据

步骤 5：配置执行参数

• 执行模式：立即执行 / 定时执行
• 并发数：任务并发数（默认 1）
• 失败策略：跳过失败记录 / 终止任务

步骤 6：创建并执行

点击 创建 按钮创建任务。如果选择立即执行，任务将自动开始运行。

2. 使用清洗模板

创建模板

1. 配置好清洗流程
2. 点击 保存为模板
3. 输入模板名称和描述
4. 点击保存

使用模板

1. 创建清洗任务时，点击 使用模板
2. 从模板列表选择模板
3. 系统自动加载模板配置
4. 根据需要调整配置

3. 监控清洗任务

查看任务列表

在数据清洗页面，可以看到所有清洗任务：

查看任务详情

点击任务名称进入详情页面，可以看到：

• 任务配置：清洗流程和参数
• 执行记录：历史执行记录
• 清洗统计：
  • 输入记录数
  • 输出记录数
  • 清洗掉的记录数
  • 清洗率

查看清洗结果

在任务详情页面，点击 查看结果 可以：

• 查看清洗后的数据
• 对比清洗前后数据
• 导出清洗结果

清洗算子详解

去重算子

功能：删除重复的数据记录

参数：

• 去重字段：选择用于判断重复的字段
• 保留策略：保留第一条 / 保留最后一条

示例：

输入：
{"id": 1, "name": "Alice"}
{"id": 1, "name": "Alice"}
{"id": 2, "name": "Bob"}

输出（保留第一条）：
{"id": 1, "name": "Alice"}
{"id": 2, "name": "Bob"}

空值处理算子

功能：处理空值（NULL/空字符串）

参数：

• 处理策略：删除记录 / 填充默认值
• 填充值：当选择填充时，指定填充值

示例：

输入：
{"id": 1, "name": "Alice", "age": null}
{"id": 2, "name": null, "age": 25}

输出（填充默认值 "Unknown"）：
{"id": 1, "name": "Alice", "age": "Unknown"}
{"id": 2, "name": "Unknown", "age": 25}

文本清洗算子

功能：清洗文本数据

参数：

• 去除特殊字符：是否去除
• 转换大小写：不转换 / 全部小写 / 全部大写
• 去除停用词：是否去除
• 最小长度：过滤短于该长度的文本

示例：

输入："Hello!!! This is a Test..."

输出（去除特殊字符、转小写）：
"hello this is a test"

图像格式转换算子

功能：转换图像格式

参数：

• 目标格式：JPG / PNG / WebP
• 质量：输出图像质量（1-100）
• 尺寸：调整图像尺寸（可选）

数据归一化算子

功能：数值型数据归一化

参数：

• 归一化方法：Min-Max / Z-Score
• 目标范围：Min-Max 归一化的目标范围

示例：

输入（Min-Max 归一化到 [0, 1]）：
{"age": 20, "salary": 5000}
{"age": 40, "salary": 10000}

输出：
{"age": 0.0, "salary": 0.0}
{"age": 1.0, "salary": 1.0}

高级功能

自定义算子

除了内置算子，DataMate 还支持自定义算子开发。详见：

• 算子市场 - 算子开发指南

条件分支

在清洗流程中，可以添加条件分支：

输入数据 → [条件判断]
              ├── 满足条件 → 处理流程 A
              └── 不满足条件 → 处理流程 B

条件类型：

• 字段值比较
• 数据类型检查
• 自定义表达式

循环处理

对于需要重复处理的场景，可以使用循环算子：

• For 循环：固定次数循环
• While 循环：条件循环
• 迭代循环：遍历集合

数据验证

在清洗完成后，可以添加数据验证算子：

• 完整性验证：检查必填字段
• 一致性验证：检查字段间关系
• 业务规则验证：自定义验证规则

常见问题

Q: 清洗任务执行失败怎么办？

A: 按以下步骤排查：

1. 检查数据格式：确保数据格式与算子要求一致
2. 查看执行日志：获取详细错误信息
3. 检查参数配置：确保算子参数配置正确
4. 测试单个算子：单独测试问题算子
5. 减少数据量：先用小数据集测试

Q: 如何处理大量数据？

A: 大数据量清洗建议：

1. 分批处理：将大数据集拆分为多个小批次
2. 增加并发：适当增加并发数
3. 使用增量清洗：只清洗新增或变更的数据
4. 优化流程：简化清洗流程，移除不必要的算子

Q: 清洗速度慢怎么办？

A: 优化清洗速度：

1. 减少算子数量：只使用必要的算子
2. 优化算子顺序：先过滤数据再处理
3. 增加并发：提高任务并发数
4. 使用增量处理：避免重复处理

Q: 如何保证清洗质量？

A: 建议的清洗流程：

1. 数据探索：先了解数据质量状况
2. 制定规则：根据业务需求制定清洗规则
3. 小批量测试：先在小数据集上测试
4. 验证结果：清洗后验证数据质量
5. 定期审查：定期审查和更新清洗规则

API 参考

详细的 API 文档请参考：

• 数据清洗 API

相关文档

• 数据管理 - 管理清洗后的数据
• 算子市场 - 获取更多清洗算子
• 流水线编排 - 将清洗任务集成到流水线

3.4 - 数据标注

功能概述

数据标注模块提供：

• 多类型标注：支持图像、文本、音频等多种数据类型
• 标注模板：丰富的标注模板和配置
• 质量控制：标注审核和一致性检查
• 团队协作：多人协作标注
• 标注导出：导出标注结果

标注类型

图像标注

文本标注

音频标注

快速开始

1. 部署 Label Studio

使用 Docker Compose

make install-label-studio

访问 Label Studio

• 地址：http://localhost:30001
• 用户名：admin@demo.com
• 密码：demoadmin

2. 创建标注任务

步骤 1：进入数据标注页面

在左侧导航栏选择 数据标注。

步骤 2：创建任务

点击右上角 创建任务 按钮。

步骤 3：配置基本信息

• 任务名称：例如 image_classification_task
• 任务描述：描述标注任务（可选）
• 源数据集：选择要标注的数据集
• 标注类型：选择标注类型（如图像分类）

步骤 4：配置标注模板

选择或创建标注模板：

图像分类模板示例：

<View>
  <Image name="image" value="$image"/>
  <Choices name="choice" toName="image">
    <Choice value="cat"/>
    <Choice value="dog"/>
    <Choice value="bird"/>
  </Choices>
</View>

目标检测模板示例：

<View>
  <Image name="image" value="$image"/>
  <RectangleLabels name="label" toName="image">
    <Label value="cat" background="blue"/>
    <Label value="dog" background="red"/>
  </RectangleLabels>
</View>

步骤 5：配置标注规则

• 标注方式：单标签 / 多标签
• 最少标注数：每个样本最少标注次数（用于一致性）
• 审核机制：是否启用审核
• 标注人员：分配标注人员

步骤 6：创建任务

点击 创建 按钮完成创建。

3. 开始标注

步骤 1：进入标注界面

在任务列表页，点击任务名称进入标注界面。

步骤 2：进行标注

1. 查看当前待标注样本
2. 根据标注类型进行标注
3. 点击 提交 完成标注
4. 自动加载下一个样本

步骤 3：查看标注进度

在标注界面可以看到：

• 总样本数：待标注的样本总数
• 已标注数：已完成标注的样本数
• 完成进度：标注完成百分比
• 我的标注数：当前用户标注的数量

4. 标注审核

查看待审核标注

1. 进入任务详情页
2. 点击 审核 标签
3. 查看待审核的标注结果

审核标注

1. 查看标注结果
2. 选择 通过 或 拒绝
3. 如果拒绝，可以修改标注
4. 提交审核结果

5. 导出标注结果

导出为 JSON

[
  {
    "id": 1,
    "image": "image1.jpg",
    "label": "cat",
    "annotator": "user1",
    "created_at": "2024-01-15T10:30:00"
  }
]

导出为 CSV

id,image,label,annotator,created_at
1,image1.jpg,cat,user1,2024-01-15 10:30:00
2,image2.jpg,dog,user1,2024-01-15 10:31:00

导出到数据集

将标注结果导出到新的数据集，用于后续处理。

高级功能

标注模板定制

自定义标签

在模板中定义标签及其属性：

<Choices name="choice" toName="image">
  <Choice value="cat" alias="feline"/>
  <Choice value="dog" alias="canine"/>
  <Choice value="other"/>
</Choices>

添加属性

为标签添加额外属性：

<RectangleLabels name="label" toName="image">
  <Label value="person" background="blue">
    <Attribute name="gender" type="radio">
      <Value value="male"/>
      <Value value="female"/>
    </Attribute>
    <Attribute name="age" type="number"/>
  </Label>
</RectangleLabels>

质量控制

标注一致性

检查不同标注员的一致性：

• Cohen’s Kappa：评估标注一致性
• 多数投票：使用多数标注结果
• 专家审核：专家审核争议标注

标注指南

创建详细的标注指南：

1. 明确标注标准
2. 提供标注示例
3. 说明边界情况
4. 定期更新指南

团队协作

角色分配

任务分配

• 手动分配：管理员手动分配样本
• 自动分配：系统自动分配待标注样本
• 认领模式：标注员主动认领样本

预标注

使用模型进行预标注：

1. 训练或使用现成模型
2. 对数据集进行预标注
3. 标注员修正预标注结果

优势：

• 提高标注效率
• 降低标注成本
• 保持标注一致性

最佳实践

1. 标注指南

制定清晰的标注指南：

• 明确标准：清晰定义标注标准
• 提供示例：给出正例和反例
• 边界情况：说明如何处理边界情况
• 培训标注员：确保标注员理解指南

2. 质量控制

建立质量控制流程：

1. 预标注：使用模型预标注
2. 标注：标注员进行标注
3. 审核：审核员抽检
4. 反馈：提供反馈并改进

3. 标注效率

提高标注效率：

• 使用快捷键：使用键盘快捷键
• 批量操作：支持批量标注
• 智能推荐：使用 AI 辅助标注
• 合理分工：根据难度分配任务

常见问题

Q: 标注质量不理想怎么办？

A: 改进建议：

1. 完善标注指南：更详细的标注说明
2. 加强培训：培训标注员
3. 增加审核：提高审核比例
4. 使用预标注：使用模型辅助
5. 提供反馈：及时反馈问题

Q: 标注速度慢怎么办？

A: 提高效率：

1. 使用预标注：减少从零开始标注
2. 优化界面：使用快捷键和批量操作
3. 合理分工：根据难度分配任务
4. 激励标注员：设置激励机制

Q: 如何处理标注不一致？

A: 处理方法：

1. 明确标准：制定明确的标注标准
2. 多数投票：使用多个标注员投票
3. 专家裁决：专家处理争议标注
4. 计算一致性：使用 Cohen’s Kappa 等指标

Q: 支持哪些标注格式？

A: 导出格式：

• JSON
• CSV
• COCO (用于目标检测)
• YOLO (用于目标检测)
• Pascal VOC (用于目标检测)
• 自定义格式

相关文档

• 数据管理 - 管理待标注数据
• 数据评估 - 评估标注质量

3.5 - 数据合成

功能概述

数据合成模块提供：

• 指令模板管理：创建和管理合成指令模板
• 单任务合成：创建单个合成任务
• 比例合成任务：按指定比例合成多类别数据
• 大模型集成：支持多种大模型 API
• 质量评估：自动评估合成数据质量

快速开始

1. 创建指令模板

步骤 1：进入数据合成页面

在左侧导航栏选择 数据合成 → 合成任务。

步骤 2：创建指令模板

1. 点击 指令模板 标签
2. 点击 创建模板 按钮

步骤 3：配置模板

基本信息：

• 模板名称：例如 qa_generation_template
• 模板描述：描述模板用途（可选）
• 模板类型：选择模板类型（问答、对话、摘要等）

提示词配置：

示例提示词：

你是一个专业的数据生成助手。请根据以下要求生成数据：

任务：生成问答对
主题：{topic}
数量：{count}
难度：{difficulty}

要求：
1. 问题要清晰明确
2. 答案要准确完整
3. 涵盖不同难度级别

输出格式：JSON
[
  {
    "question": "...",
    "answer": "..."
  }
]

参数配置：

• 模型：选择使用的大模型（GPT-4、Claude、本地模型等）
• 温度：控制生成随机性（0-1）
• 最大 tokens：限制生成长度
• 其他参数：根据模型配置

步骤 4：保存模板

点击 保存 按钮保存模板。

2. 创建合成任务

步骤 1：填写基本信息

1. 返回 数据合成 页面
2. 点击 创建任务 按钮
3. 填写基本信息：
   • 任务名称：例如 medical_qa_synthesis
   • 任务描述：描述任务目的（可选）

步骤 2：选择数据集和选择文件

从现有数据集中选择合成所需的数据：

• 选择数据集：从列表中选择需要使用的数据集
• 选择文件：
  • 可以选择整个数据集的所有文件
  • 也可以选择数据集中的部分特定文件
  • 支持多选多个文件

步骤 3：选择合成指令模板

选择已创建的指令模板，或创建新模板：

• 从模板库选择：从已创建的模板中选择
• 模板类型：问答生成、对话生成、摘要生成等
• 预览模板：可以查看模板的提示词内容

步骤 4：填写合成配置

合成配置包含以下四个部分：

1. 设置合成总数

设置整个任务生成的数据总量上限：

此设置可选，适用于大规模合成任务的总量控制。

2. 配置文本切片策略

对输入的文本文件进行切片处理，支持多种切片方式：

切片方式选项：

• 默认分块：使用系统默认的智能分块策略
• 按章节分块：根据章节结构进行分块
• 按段落分块：按照段落边界进行分块
• 固定长度分块：按照固定的字符长度进行分块
• 自定义分隔符分块：使用自定义分隔符进行分块

3. 配置问题合成参数

设置问题生成的相关参数：

参数说明：

• 问题生成数量：每个文本切片生成的问题个数，数值越高生成的问题越多
• 温度：值越高生成的问题越多样，值越低生成的问题越稳定

4. 配置答案合成参数

设置答案生成的相关参数：

参数说明：

• 温度：值越低答案越保守和准确，值越高答案越多样和创造性

合成类型： 系统支持两种合成类型：

• SFT 问答数据合成：生成监督微调用的问答对数据
• COT 链式推理合成：生成包含推理过程的数据

步骤 5：开始任务

点击 开始任务 按钮，任务将自动开始执行。

3. 创建比例合成任务

比例合成任务用于按指定比例合成多类别平衡数据。

步骤 1：创建比例任务

1. 在左侧导航栏选择 数据合成 → 配比任务
2. 点击 创建任务 按钮

步骤 2：填写基本信息

示例：

• 任务名称：balanced_dataset_synthesis
• 目标总数量：10000
• 任务描述：生成训练集和验证集的平衡数据

步骤 3：选择数据集

从现有数据集中选择需要参与配比的数据集：

数据集选择功能：

• 搜索数据集：通过关键词搜索数据集
• 多选支持：可以同时选择多个数据集
• 数据集信息：显示每个数据集的详细信息
  • 数据集名称和类型
  • 数据集描述
  • 文件数量
  • 数据集大小
  • 标签分布预览（最多显示 8 个标签）

选择数据集后，系统会自动加载每个数据集的标签分布信息。

步骤 4：填写配比配置

为每个选中的数据集配置具体的合成规则：

配比配置项：

功能说明：

• 自动分配：点击"自动分配"按钮，系统会自动将目标总数量均匀分配到各数据集
• 数量限制：每个配置项的数量不能超过该数据集的文件总数
• 百分比计算：系统自动计算每个配置项占总数量的百分比
• 删除配置：可以删除不需要的配置项
• 添加配置：每个数据集可以添加多个不同的标签配置

示例配置：

步骤 5：执行任务

点击 开始任务 按钮，系统将按照配比配置创建并执行任务。

4. 监控合成任务

查看任务列表

在数据合成页面，可以看到所有合成任务：

查看任务详情

点击任务名称进入详情页面，可以看到：

• 任务配置：模板和参数配置
• 执行记录：历史执行记录
• 生成结果：
  • 总生成数量
  • 成功数量
  • 失败数量
  • 成功率

查看生成数据

在任务详情页面，点击 查看数据 可以：

• 预览生成的数据
• 下载数据
• 导出到数据集

高级功能

模板变量

在提示词中使用变量，实现动态配置：

变量语法：{variable_name}

示例：

请生成关于 {topic} 的 {count} 个 {difficulty} 级别的 {type}。

内置变量：

• {current_date}：当前日期
• {current_time}：当前时间
• {random_id}：随机 ID

模型选择

DataMate 支持多种大模型：

数据质量控制

启用数据质量评估：

• 格式验证：验证输出格式
• 内容检查：检查敏感词、不当内容
• 重复检测：检测重复生成的内容
• 质量评分：对生成内容打分

批量生成

对于大规模数据生成：

1. 分批生成：将大批量任务拆分为多个小批次
2. 并发控制：控制并发请求数量
3. 失败重试：自动重试失败的生成请求
4. 断点续传：支持从中断处继续生成

最佳实践

1. 提示词设计

好的提示词应该：

• 明确任务：清晰描述生成任务
• 指定格式：明确输出格式要求
• 提供示例：给出期望的输出示例
• 控制质量：设置质量要求

示例提示词：

你是一个专业的教育内容创作助手。

任务：生成教育问答对
学科：{subject}
年级：{grade}
数量：{count}

要求：
1. 问题要符合该年级的知识水平
2. 答案要准确、详细、易懂
3. 每个答案包含解析过程
4. 不得生成敏感或不当内容

输出格式（JSON）：
[
  {
    "id": 1,
    "question": "问题内容",
    "answer": "答案内容",
    "explanation": "解析内容",
    "difficulty": "easy/medium/hard",
    "knowledge_points": ["知识点1", "知识点2"]
  }
]

请开始生成：

2. 参数调优

根据需求调整模型参数：

3. 数据验证

生成后进行数据验证：

1. 格式检查：检查输出格式是否正确
2. 内容审核：人工抽查部分数据
3. 质量评估：使用评估工具打分
4. 去重：去除重复或高度相似的内容

常见问题

Q: 生成数据质量不理想怎么办？

A: 优化建议：

1. 改进提示词：更详细、更明确的指令
2. 调整参数：降低温度、增加最大 tokens
3. 提供示例：在提示词中给出示例
4. 更换模型：尝试其他大模型
5. 人工审核：人工审核和筛选

Q: 生成速度慢怎么办？

A: 加速建议：

1. 减少数量：分批生成，不要一次性生成过多
2. 调整并发：适当增加并发数
3. 使用更快的模型：如 GPT-3.5-Turbo
4. 缩短输出：减少最大 tokens
5. 使用本地模型：部署本地模型加速

Q: 如何保证生成数据的多样性？

A: 增加多样性：

1. 提高温度：设置温度为 0.7-1.0
2. 丰富提示词：在提示词中加入变化元素
3. 多次生成：多次生成后去重
4. 使用不同种子：改变随机种子
5. 混合模型：使用多个模型生成

Q: 生成的数据有重复怎么办？

A: 去重方法：

1. 启用去重：在任务配置中启用去重功能
2. 调整温度：提高温度增加随机性
3. 丰富提示词：在提示词中加入更多变化
4. 后处理去重：使用去重工具处理

Q: 如何控制生成成本？

A: 成本控制：

1. 选择合适模型：根据需求选择模型
2. 控制长度：限制最大 tokens
3. 批量处理：使用批量 API（如果支持）
4. 缓存复用：缓存相似请求的结果
5. 本地模型：对于大规模生成，考虑部署本地模型

API 参考

详细的 API 文档请参考：

• 数据合成 API

相关文档

• 数据评估 - 评估合成数据质量
• 数据管理 - 管理合成数据
• 流水线编排 - 将合成任务集成到流水线

3.6 - 数据评估

功能概述

数据评估模块提供：

• 质量指标：丰富的数据质量评估指标
• 自动评估：自动执行数据评估任务
• 手动评估：人工抽样评估
• 评估报告：生成详细的评估报告
• 质量追踪：追踪数据质量变化趋势

评估维度

数据完整性

数据准确性

数据唯一性

数据时效性

快速开始

1. 创建评估任务

步骤 1：进入数据评估页面

在左侧导航栏选择 数据评估。

步骤 2：创建任务

点击右上角 创建任务 按钮。

步骤 3：配置基本信息

• 任务名称：例如 data_quality_evaluation
• 任务描述：描述评估任务（可选）
• 评估数据集：选择要评估的数据集

步骤 4：配置评估维度

选择要评估的维度：

• ✅ 数据完整性
• ✅ 数据准确性
• ✅ 数据唯一性
• ✅ 数据时效性

步骤 5：配置评估规则

为每个维度配置具体规则：

完整性规则：

必填字段：name, email, phone
空值阈值：5%（超过5%则警告）

准确性规则：

email 格式：正则表达式验证
age 范围：0-120
phone 格式：手机号格式

唯一性规则：

唯一字段：id, email
重复阈值：3%（超过3%则警告）

步骤 6：创建任务

点击 创建 按钮完成创建。

2. 执行评估

自动评估

任务创建后自动执行，或点击 立即执行。

手动评估

1. 点击 手动评估 标签
2. 查看待评估样本
3. 人工评估样本质量
4. 提交评估结果

3. 查看评估报告

总体评分

评估报告提供总体质量评分：

总体质量评分：85 分 (优秀)

完整性：90 分 ⭐⭐⭐⭐⭐
准确性：82 分 ⭐⭐⭐⭐
唯一性：95 分 ⭐⭐⭐⭐⭐
时效性：75 分 ⭐⭐⭐⭐

详细指标

每个维度的详细指标：

完整性：

• 空值率：3.2% ✅
• 缺失字段率：1.5% ✅
• 记录完整率：96.8% ✅

准确性：

• email 格式正确率：98.5% ✅
• age 值域符合率：95.2% ✅
• phone 格式正确率：88.7% ⚠️

唯一性：

• 重复率：1.8% ✅
• 唯一率：98.2% ✅

时效性：

• 数据新鲜度：平均 7 天前
• 过期数据率：12.5% ⚠️

问题列表

列出发现的数据质量问题：

质量趋势

查看数据质量变化趋势：

质量评分趋势
90 │     ╭─╮
85 │ ╭─╮╭─╯ ╭─╮
80 │╭─╯╭─╯   ╭─╯
75 │╭─╯╭─╯   ╭─╯
70 │╭─╯╭─╯   ╭─╯
   └─────────────
   1月 2月 3月 4月

4. 导出评估报告

导出为 PDF

1. 点击 导出报告 按钮
2. 选择 PDF 格式
3. 下载报告文件

导出为 Excel

1. 点击 导出报告 按钮
2. 选择 Excel 格式
3. 下载报告文件

Excel 报告包含多个工作表：

• 总体评分
• 详细指标
• 问题列表
• 样本明细

高级功能

自定义评估规则

除了内置规则，还可以自定义评估规则：

正则表达式验证

字段：phone
规则：^1[3-9]\d{9}$
说明：中国大陆手机号

值域验证

字段：age
最小值：0
最大值：120
说明：年龄在合理范围内

自定义脚本

使用 Python 脚本自定义评估逻辑：

def evaluate(record):
    # 自定义评估逻辑
    if record.get('score', 0) < 0 or record.get('score', 0) > 100:
        return False, "分数必须在 0-100 之间"
    return True, "OK"

对比评估

对比不同数据集或不同版本的数据质量：

1. 选择要对比的数据集/版本
2. 执行对比评估
3. 查看对比报告

对比维度：

• 总体评分对比
• 各维度指标对比
• 问题类型分布对比

质量阈值告警

设置质量阈值，超过阈值自动告警：

告警规则:
  总体评分低于 80: 发送邮件
  空值率超过 10%: 发送短信
  重复率超过 5%: 发送邮件

最佳实践

1. 定期评估

建议定期执行数据质量评估：

• 每日评估：关键数据每日评估
• 每周评估：一般数据每周评估
• 每月评估：全部数据每月评估

2. 建立基线

为每个数据集建立质量基线：

• 初次评估作为基线
• 后续评估与基线对比
• 追踪质量变化趋势

3. 持续改进

根据评估结果持续改进：

• 清洗问题数据：根据评估结果清洗
• 优化采集流程：改进数据采集方式
• 更新验证规则：及时更新验证规则

常见问题

Q: 评估任务执行失败？

A: 排查步骤：

1. 检查数据集：确认数据集存在
2. 检查规则配置：确认评估规则正确
3. 查看执行日志：获取详细错误信息
4. 减少样本量：先用小样本测试

Q: 评估结果不准确？

A: 改进建议：

1. 调整评估规则：根据实际需求调整
2. 增加评估维度：添加更多评估维度
3. 人工审核：人工抽检验证结果
4. 更新基线：定期更新质量基线

Q: 如何提高数据质量？

A: 改进建议：

1. 数据清洗：使用数据清洗模块清洗
2. 源头控制：在数据采集阶段控制质量
3. 建立规范：制定数据标准和规范
4. 定期评估：定期评估并改进

API 参考

详细的 API 文档请参考：

• 数据评估 API

相关文档

• 数据清洗 - 清洗数据
• 数据管理 - 管理数据

3.7 - 知识库管理

功能概述

知识库管理模块提供：

• 文档上传：支持多种文档格式的上传
• 文本切分：智能文本分块策略
• 向量化：自动将文本转换为向量
• 向量检索：基于相似度的语义检索
• 知识库问答：集成 RAG 的智能问答

支持的文档格式

快速开始

1. 创建知识库

步骤 1：进入知识库页面

在左侧导航栏选择 知识生成。

步骤 2：创建知识库

点击右上角 创建知识库 按钮。

步骤 3：配置基本信息

• 知识库名称：例如 company_docs_kb
• 知识库描述：描述知识库用途（可选）
• 知识库类型：通用 / 专业领域

步骤 4：配置向量参数

• 嵌入模型：选择嵌入模型

  • OpenAI text-embedding-ada-002
  • BGE-M3
  • 自定义模型

• 向量维度：根据模型自动设置

• 索引类型：IVF_FLAT / HNSW / IVF_PQ

步骤 5：配置切分策略

• 切分方式：

  • 按字符数切分
  • 按段落切分
  • 按语义切分

• 块大小：每个文本块的大小（字符数）

• 重叠大小：相邻块的重叠大小

步骤 6：创建知识库

点击 创建 按钮完成创建。

2. 上传文档

步骤 1：进入知识库详情

点击知识库名称进入详情页面。

步骤 2：上传文档

1. 点击 上传文档 按钮
2. 选择本地文件
3. 等待上传完成

系统会自动：

1. 解析文档内容
2. 切分文本
3. 生成向量
4. 建立索引

步骤 3：查看处理状态

在文档列表中可以看到处理状态：

3. 向量检索

步骤 1：进入检索页面

在知识库详情页面，点击 向量检索 标签。

步骤 2：输入查询

在搜索框输入查询内容，例如：

如何使用 DataMate 进行数据清洗？

步骤 3：查看检索结果

系统返回最相关的文本块及其相似度分数：

高级检索

点击 高级检索，可以：

• 设置 Top-K：返回前 K 个结果（默认 5）
• 设置阈值：过滤低于相似度阈值的结果
• 过滤文档：限定检索范围
• 重排序：使用重排序模型优化结果

4. 知识库问答（RAG）

步骤 1：启用 RAG

在知识库详情页面，点击 RAG 问答 标签。

步骤 2：配置 RAG 参数

• 大语言模型：选择使用的 LLM
• 检索数量：检索的文本块数量
• 温度：控制生成随机性
• 提示词模板：自定义问答模板

步骤 3：进行问答

在对话框输入问题，例如：

用户：DataMate 支持哪些数据清洗算子？

助手：DataMate 支持丰富的数据清洗算子，包括：
1. 数据质量算子：去重、空值处理、异常值检测...
2. 文本清洗算子：去除特殊字符、大小写转换...
3. 图像清洗算子：格式转换、质量检测...
[来源：user_guide.pdf, tutorial.md]

助手会：

1. 检索相关文本块
2. 基于检索内容生成答案
3. 标注答案来源

高级功能

文本切分策略

字符切分

按固定字符数切分：

• 块大小：500 字符
• 重叠：50 字符

段落切分

按段落边界切分：

• 保持段落完整性
• 适合结构化文档

语义切分

基于语义相似度切分：

• 保持语义完整性
• 适合长文档
• 需要额外模型

自定义嵌入模型

使用本地模型

1. 部署本地嵌入模型服务
2. 在知识库配置中选择自定义模型
3. 填写模型服务地址

示例：

模型服务地址：http://localhost:8000/embeddings
请求格式：
{
  "texts": ["文本1", "文本2"],
  "model": "bge-m3"
}

使用 OpenAI

{
  "provider": "openai",
  "model": "text-embedding-ada-002",
  "api_key": "your-api-key"
}

知识库管理

更新知识库

当文档变更时，可以：

1. 重新索引：重新生成所有文档的向量
2. 增量更新：只更新变更的文档
3. 删除文档：从知识库中删除文档

导出知识库

支持导出：

• 文档列表：导出为 CSV
• 向量数据：导出为 NPY/CSV
• 元数据：导出为 JSON

知识库统计

查看知识库统计信息：

• 文档数量：总文档数
• 文本块数量：总文本块数
• 向量数量：总向量数
• 存储大小：向量存储大小
• 更新时间：最后更新时间

多知识库管理

创建多个知识库

可以根据不同主题创建多个知识库：

• product_kb：产品文档
• technical_kb：技术文档
• hr_kb：人力资源文档

联合检索

在多个知识库中同时检索：

1. 选择要检索的知识库
2. 执行检索
3. 结果汇总并排序

最佳实践

1. 文档准备

上传文档前的准备工作：

• 格式统一：转换为统一的格式（如 PDF、Markdown）
• 清理内容：删除无关内容（页眉页脚、广告等）
• 结构化：保持良好的文档结构
• 元数据：添加文档元数据（作者、日期、标签等）

2. 切分策略选择

根据文档类型选择：

3. 向量参数调优

根据需求调整：

4. RAG 提示词设计

设计有效的 RAG 提示词：

你是一个专业的客服助手。请基于以下知识库内容回答用户问题。

知识库内容：
{context}

用户问题：
{question}

回答要求：
1. 只基于知识库内容回答
2. 如果知识库中没有相关信息，明确告知
3. 回答要准确、详细
4. 标注信息来源

请回答：

常见问题

Q: 文档上传后一直处于"处理中"状态？

A: 检查以下项目：

1. 文档格式：确保文档格式被支持
2. 文档大小：单个文档不超过 100MB
3. 向量服务：检查向量服务是否正常运行
4. 查看日志：查看详细错误信息

Q: 检索结果不准确？

A: 优化建议：

1. 调整切分策略：尝试不同的切分方式
2. 增加块大小：增加上下文信息
3. 使用重排序：启用重排序模型
4. 优化查询：使用更明确的查询语句
5. 更换嵌入模型：尝试其他嵌入模型

Q: RAG 回答质量不佳？

A: 改进建议：

1. 增加检索数量：检索更多相关文本块
2. 优化提示词：改进问答提示词模板
3. 更换 LLM：尝试更强大的模型
4. 人工审核：人工审核和优化回答

Q: 如何处理大文档？

A: 大文档处理建议：

1. 拆分文档：将大文档拆分为多个小文档
2. 分批上传：分批上传和处理
3. 使用语义切分：保持语义完整性
4. 异步处理：选择异步处理模式

Q: 如何更新知识库？

A: 知识库更新方式：

1. 单个文档更新：删除旧文档，上传新文档
2. 批量更新：使用批量导入功能
3. 全量重建：清空知识库，重新上传
4. API 更新：通过 API 接口更新

API 参考

详细的 API 文档请参考：

• RAG 索引 API

相关文档

• Agent 对话 - 使用知识库进行问答
• 数据管理 - 管理知识库文档
• 流水线编排 - 将知识库集成到流水线

3.8 - 算子市场

功能概述

算子市场模块提供：

• 内置算子：丰富的内置数据处理算子
• 算子发布：发布和分享自定义算子
• 算子安装：安装第三方算子
• 自定义开发：开发自定义算子

内置算子

数据清洗算子

文本处理算子

图像处理算子

数据增强算子

快速开始

1. 浏览算子

步骤 1：进入算子市场

在左侧导航栏选择 算子市场。

步骤 2：浏览算子

在算子市场页面，可以看到所有可用算子：

步骤 3：查看算子详情

点击算子名称或 查看 按钮，可以看到：

• 算子简介：功能和用途
• 使用示例：如何使用算子
• 输入输出：输入输出格式
• 参数说明：可配置参数
• 用户评价：其他用户的评价

2. 安装算子

安装内置算子

内置算子默认已安装，可以直接使用。

安装第三方算子

1. 在算子详情页，点击 安装 按钮
2. 等待安装完成
3. 安装后可以在数据清洗等模块中使用

3. 使用算子

安装算子后，可以在以下场景使用：

数据清洗

1. 创建数据清洗任务
2. 在清洗流程中添加算子节点
3. 配置算子参数
4. 执行清洗任务

流水线编排

1. 创建流水线
2. 添加算子节点
3. 配置算子参数
4. 执行流水线

4. 开发自定义算子

创建算子

1. 在算子市场页，点击 创建算子 按钮
2. 填写算子信息：
   • 算子名称：例如 my_text_cleaner
   • 算子类别：选择类别
   • 功能描述：描述算子功能
   • 版本号：例如 1.0.0

编写算子代码

Python 算子示例：

from typing import Dict, Any

class MyTextCleaner:
    """自定义文本清洗算子"""

    def __init__(self, config: Dict[str, Any]):
        """
        初始化算子

        Args:
            config: 算子配置
                - remove_special_chars: 是否去除特殊字符
                - to_lowercase: 是否转为小写
        """
        self.remove_special_chars = config.get('remove_special_chars', True)
        self.to_lowercase = config.get('to_lowercase', True)

    def process(self, data: Any) -> Any:
        """
        处理数据

        Args:
            data: 输入数据

        Returns:
            处理后的数据
        """
        if isinstance(data, str):
            result = data
            if self.to_lowercase:
                result = result.lower()
            if self.remove_special_chars:
                # 去除特殊字符
                import re
                result = re.sub(r'[^\w\s]', '', result)
            return result
        return data

    def get_config_schema(self) -> Dict[str, Any]:
        """
        获取配置模式

        Returns:
            配置模式定义
        """
        return {
            "type": "object",
            "properties": {
                "remove_special_chars": {
                    "type": "boolean",
                    "title": "去除特殊字符",
                    "default": True
                },
                "to_lowercase": {
                    "type": "boolean",
                    "title": "转为小写",
                    "default": True
                }
            }
        }

打包算子

1. 创建算子目录结构：

my_text_cleaner/
├── __init__.py
├── operator.py       # 算子代码
├── config.json       # 配置文件
├── README.md         # 说明文档
└── requirements.txt  # 依赖列表

2. 打包为 ZIP 文件

发布算子

1. 在创建算子页，上传算子包
2. 填写算子信息
3. 点击 发布 按钮

发布选项

• 私有算子：仅自己可见
• 公开算子：所有人可见
• 团队共享：团队成员可见

高级功能

算子版本管理

创建新版本

1. 进入算子详情页
2. 点击 版本 标签
3. 点击 创建版本
4. 上传新版本代码
5. 填写版本说明

版本回退

如果新版本有问题，可以回退到旧版本。

算子测试

单元测试

为算子编写单元测试：

import unittest

class TestMyTextCleaner(unittest.TestCase):
    def setUp(self):
        config = {
            'remove_special_chars': True,
            'to_lowercase': True
        }
        self.cleaner = MyTextCleaner(config)

    def test_lowercase(self):
        input_text = "Hello World"
        output = self.cleaner.process(input_text)
        self.assertEqual(output, "hello world")

    def test_remove_special_chars(self):
        input_text = "Hello!!! World..."
        output = self.cleaner.process(input_text)
        self.assertEqual(output, "hello world")

在线测试

在算详情页，点击 测试 按钮：

1. 输入测试数据
2. 配置算子参数
3. 执行测试
4. 查看输出结果

算子权限管理

权限级别

权限设置

1. 进入算子详情页
2. 点击 设置 标签
3. 修改权限级别
4. 保存设置

最佳实践

1. 算子设计

好的算子设计：

• 单一职责：每个算子只做一件事
• 可配置：提供丰富的配置选项
• 错误处理：完善的错误处理机制
• 性能优化：考虑大数据量场景

2. 文档编写

完善的文档应该包含：

• 功能说明：清晰描述算子功能
• 使用示例：提供使用示例
• 参数说明：详细说明每个参数
• 注意事项：说明使用注意事项

3. 测试覆盖

充分的测试：

• 单元测试：测试核心功能
• 边界测试：测试边界情况
• 性能测试：测试大数据量场景

常见问题

Q: 算子执行失败怎么办？

A: 排查步骤：

1. 查看日志：查看详细错误信息
2. 检查配置：确认参数配置正确
3. 检查数据：确认输入数据格式正确
4. 本地测试：在本地环境测试算子

Q: 如何优化算子性能？

A: 优化建议：

1. 减少内存使用：使用生成器、迭代器
2. 并行处理：使用多进程/多线程
3. 批量处理：批量处理数据
4. 缓存结果：缓存重复计算

Q: 如何分享算子？

A: 分享方式：

1. 公开发布：发布为公开算子
2. 团队共享：团队内共享
3. 导出分享：导出算子包文件分享

相关文档

• 数据清洗 - 使用算子进行数据清洗
• 流水线编排 - 在流水线中使用算子

3.9 - 流水线编排

功能概述

流水线编排模块提供：

• 可视化设计器：拖拽式流程设计
• 丰富的节点类型：数据处理、条件判断、循环等
• 流程执行：自动执行和监控流程
• 模板管理：保存和复用流程模板
• 版本管理：流程版本控制

节点类型

数据节点

逻辑节点

算子节点

集成节点

快速开始

1. 创建流水线

步骤 1：进入流水线编排页面

在左侧导航栏选择 流水线编排。

步骤 2：创建流水线

点击右上角 创建流水线 按钮。

步骤 3：填写基本信息

• 流水线名称：例如 data_processing_pipeline
• 流水线描述：描述流水线用途（可选）
• 标签：添加标签（可选）

步骤 4：进入流程设计器

点击 创建 后，自动进入流程设计器。