# DataMate 知识图谱实现方案

## 📋 项目概述

DataMate 知识图谱旨在构建企业级数据处理平台的知识网络，通过图结构揭示数据资产之间的关系，支持智能推荐、影响分析、血缘追踪等高级功能。

## 🎯 核心目标

1. **数据血缘追踪**：追踪数据从源到目标的完整流转路径
2. **影响分析**：评估数据变更对下游任务的影响范围
3. **智能推荐**：基于历史使用模式推荐相关数据集和工作流
4. **知识发现**：挖掘隐藏的数据关系和模式

## 🏗️ 技术架构

### 技术栈

```
存储层：MySQL (元数据) + Neo4j (图结构) + Milvus (向量)
后端：Spring Boot (kg-service) + FastAPI (kg-ingestion)
前端：React + AntV G6
抽取：LangChain LLMGraphTransformer
```

### 架构设计

```
┌─────────────────────────────────────────────────┐
│                   前端层                         │
│  React + AntV G6 (图谱可视化 + 编辑)            │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│                  服务层                          │
│  kg-service (Spring Boot)                       │
│  - 图查询 API                                    │
│  - 权限过滤                                      │
│  - 缓存层 (Redis)                                │
│                                                  │
│  rag-query-service (增强)                       │
│  - 混合检索 (Milvus + Neo4j)                    │
│  - GraphRAG                                      │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│                 摄入层                           │
│  kg-ingestion (FastAPI)                         │
│  - LangChain LLMGraphTransformer                │
│  - 实体对齐                                      │
│  - 关系生成                                      │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│                 存储层                           │
│  MySQL + Neo4j + Milvus                         │
└─────────────────────────────────────────────────┘
```

## 📊 数据模型

> 详细定义参见 [实体文档](./schema/entities.md) 和 [关系文档](./schema/relationships.md)

### 核心实体（8 类）

- **Dataset**：数据集
- **Field**：字段
- **LabelTask**：标注任务
- **Workflow**：工作流
- **Job**：作业
- **User**：用户
- **Org**：组织
- **KnowledgeSet**：知识集

### 核心关系（10 类）

- **HAS_FIELD**：Dataset → Field，数据集包含字段
- **DERIVED_FROM**：Dataset → Dataset，数据集血缘派生
- **USES_DATASET**：Job/LabelTask/Workflow → Dataset，使用数据集
- **PRODUCES**：Job → Dataset，作业产出数据集
- **ASSIGNED_TO**：LabelTask/Job → User，任务分配给用户
- **BELONGS_TO**：User/Dataset → Org，组织归属
- **TRIGGERS**：Workflow → Job，工作流触发作业
- **DEPENDS_ON**：Job → Job，作业执行依赖
- **IMPACTS**：Field → Field，字段级影响
- **SOURCED_FROM**：KnowledgeSet → Dataset，知识溯源

### 节点公共属性

```json
{
  "id": "UUID，全局唯一标识符",
  "name": "实体名称",
  "type": "实体类型（Dataset / Field / LabelTask 等）",
  "description": "实体描述",
  "graph_id": "所属图谱 ID（多租户隔离）",
  "source_id": "来源记录 ID",
  "source_type": "来源类型：SYNC / EXTRACTION / MANUAL",
  "confidence": "置信度 0.0-1.0",
  "created_at": "创建时间"
}
```

### 边公共属性

```json
{
  "id": "UUID，关系唯一标识符",
  "relation_type": "语义关系类型",
  "graph_id": "所属图谱 ID",
  "weight": "关系权重 0.0-1.0",
  "confidence": "置信度 0.0-1.0",
  "source_id": "来源记录 ID",
  "properties_json": "扩展属性 JSON",
  "created_at": "创建时间"
}
```

## 🚀 实施路线图

### 第 0 阶段：基础设施（1周）✅ 已完成

- ✅ 搭建 Neo4j（docker-compose）
- ✅ 更新 Makefile
- ✅ 创建 knowledge-graph-service（Spring Boot）
- ✅ 创建 kg_extraction 模块（Python）
- ✅ 代码审查和修复（3 轮审查，2 轮修复）

**成果**：
- Neo4j 配置：`deployment/docker/neo4j/docker-compose.yml`
- Java 服务：`backend/services/knowledge-graph-service/`（11 个文件）
- Python 模块：`runtime/datamate-python/app/module/kg_extraction/`（3 个文件）
- Makefile 命令：`neo4j-up`, `neo4j-down`, `neo4j-logs`, `neo4j-shell`

### 第 1 阶段：MVP（2-3周）⏳ 进行中

**目标**：实现基础的图谱构建和查询功能

**任务**：
1. 实现 Python 抽取器的 FastAPI 接口
   - 创建 `/api/kg/extract` 端点
   - 支持文本输入，输出节点和边
   - 集成到 FastAPI 路由

2. 实现 Java 服务的关系（Relation）功能
   - 补充 Relation 的 Repository/Service/Controller
   - 实现关系的 CRUD 操作
   - 支持关系查询和遍历

3. 定义核心实体和关系模型
   - 确定 5-8 类核心实体
   - 定义实体之间的关系
   - 设计 Schema 版本管理

4. 实现基础的图谱构建流程
   - 从 MySQL 同步元数据到 Neo4j
   - 实现增量更新机制
   - 支持手动触发构建

**验收标准**：
- ✅ 能够从文本抽取实体和关系
- ✅ 能够存储到 Neo4j
- ✅ 能够查询和遍历图谱
- ✅ 支持基础的权限控制

### 第 2 阶段：GraphRAG 融合（3-4周）

**目标**：将知识图谱与现有 RAG 系统深度融合

**任务**：
1. 在 rag-query-service 中增加"混合检索"模式
2. 查询时同时检索 Milvus（向量）+ Neo4j（图结构）
3. 将 2-hop 子图的三元组文本化后作为 Context 喂给 LLM
4. 实现 GraphRAG 的评估和优化

**验收标准**：
- ✅ 混合检索性能优于单一检索
- ✅ 支持可配置的检索策略
- ✅ 有完整的评估指标

### 第 3 阶段：可视化与优化（4-6周）

**目标**：提供友好的图谱可视化和编辑功能

**任务**：
1. 前端图谱浏览器（React + AntV G6）
2. Human-in-the-loop 编辑功能
3. 性能优化（索引、缓存、离线计算）
4. 监控和运维（Prometheus + Grafana）

**验收标准**：
- ✅ 支持大规模图谱可视化（10000+ 节点）
- ✅ 支持实时编辑和反馈
- ✅ 查询响应时间 < 1s

## 🔑 核心原则

1. **先做"窄而深"的场景**：不追求"大而全本体"，先聚焦 2-3 个高价值场景
2. **最终一致性**：MySQL 为主库，Neo4j 为专用存储，通过对账机制保证一致性
3. **双重防御**：Controller 格式校验 + Service 业务校验
4. **权限隔离**：所有操作都在正确的 graph_id 范围内
5. **性能优先**：限制遍历深度、使用缓存、离线计算

## 📚 相关文档

- [架构设计](./architecture.md)
- [数据模型 - 实体定义](./schema/entities.md)
- [数据模型 - 关系定义](./schema/relationships.md)
- [数据模型 - ER 图](./schema/er-diagram.md)
- [实施计划](./implementation.md)
- [Gemini 分析结果](./analysis/gemini.md)
- [Codex 分析结果](./analysis/codex.md)
- [Claude 分析结果](./analysis/claude.md)

## 🔗 快速链接

- Neo4j Browser: http://localhost:7474
- Bolt URI: bolt://localhost:7687
- 默认密码: datamate123（生产环境请修改）

## 📝 更新日志

- 2026-02-17：完成基础设施搭建（第 0 阶段）
- 2026-02-17：创建项目文档