DataMate/docs/knowledge-graph/implementation.md

DataMate 知识图谱实施计划

📅 总体时间线

第 0 阶段：基础设施（1周）        ✅ 已完成
第 1 阶段：MVP（2-3周）           ⏳ 进行中
第 2 阶段：GraphRAG 融合（3-4周）  ⏳ 待开始
第 3 阶段：可视化与优化（4-6周）   ⏳ 待开始

总计：10-14 周

---

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

目标

搭建知识图谱的基础设施，包括 Neo4j、Java 服务、Python 模块。

已完成任务

1. Neo4j Docker Compose 配置

• ✅ 创建 deployment/docker/neo4j/docker-compose.yml
• ✅ 配置 Neo4j 社区版
• ✅ 端口：7474 (HTTP), 7687 (Bolt)
• ✅ 数据持久化：Docker volume
• ✅ 环境变量化密码

2. Makefile 更新

• ✅ 添加 neo4j-up：启动 Neo4j
• ✅ 添加 neo4j-down：停止 Neo4j
• ✅ 添加 neo4j-logs：查看日志
• ✅ 添加 neo4j-shell：进入 Cypher Shell

3. knowledge-graph-service（Spring Boot）

• ✅ 创建完整的 DDD 分层架构
• ✅ 实现 GraphEntity 的 CRUD
• ✅ 实现 graphId 双重防御
• ✅ 实现查询限流
• ✅ 统一异常处理体系

文件清单（11 个 Java 文件）：

• KnowledgeGraphServiceConfiguration.java
• GraphEntityService.java
• GraphEntity.java, GraphRelation.java
• GraphEntityRepository.java
• KnowledgeGraphErrorCode.java
• KnowledgeGraphProperties.java
• GraphEntityController.java
• CreateEntityRequest.java, UpdateEntityRequest.java, CreateRelationRequest.java
• application-knowledgegraph.yml

4. kg_extraction 模块（Python）

• ✅ 创建 KnowledgeGraphExtractor 类
• ✅ 集成 LangChain LLMGraphTransformer
• ✅ 支持异步/同步/批量抽取
• ✅ 支持 schema-guided 模式
• ✅ 兼容 OpenAI 及自部署模型

文件清单（3 个 Python 文件）：

• __init__.py
• models.py：Pydantic 数据模型
• extractor.py：抽取器实现

5. 代码审查和修复

• ✅ 3 轮 Codex 审查
• ✅ 2 轮 Claude 修复
• ✅ 所有 P0 和 P1 问题已解决
• ✅ 编译通过，无阻塞性问题

成果

• Commit: 5a553dd
• 文件变更：22 个文件，1007 行新增
• 分支：lsf

---

⏳ 第 1 阶段：MVP（2-3周）

目标

实现基础的图谱构建和查询功能，支持 2-3 个高价值场景。

任务列表

任务 1.1：实现 Python 抽取器的 FastAPI 接口（3天）

子任务：

1. 创建 kg_extraction/interface.py

   • 定义 FastAPI 路由
   • 实现 /api/kg/extract 端点
   • 支持文本输入，输出节点和边

2. 集成到 FastAPI 主路由

   • 在 app/module/__init__.py 中注册路由
   • 添加 API 文档

3. 实现配置管理

   • 从环境变量读取 API Key
   • 使用 SecretStr 保护敏感信息

4. 编写单元测试

   • 测试抽取功能
   • 测试错误处理

验收标准：

• ✅ 能够通过 API 调用抽取功能
• ✅ 返回结构化的节点和边
• ✅ 有完整的 API 文档
• ✅ 单元测试覆盖率 > 80%

任务 1.2：实现 Java 服务的关系（Relation）功能（3天）

子任务：

1. 补充 GraphRelationRepository

   • 实现 findByGraphId
   • 实现 findBySourceAndTarget
   • 实现 findByType

2. 实现 GraphRelationService

   • 创建关系
   • 查询关系
   • 更新关系
   • 删除关系

3. 实现 GraphRelationController

   • POST /{graphId}/relations：创建关系
   • GET /{graphId}/relations：列表查询
   • GET /{graphId}/relations/{relationId}：单个查询
   • PUT /{graphId}/relations/{relationId}：更新关系
   • DELETE /{graphId}/relations/{relationId}：删除关系

4. 编写单元测试和集成测试

验收标准：

• ✅ 关系的 CRUD 功能完整
• ✅ 支持按类型、源节点、目标节点查询
• ✅ 有完整的权限控制
• ✅ 测试覆盖率 > 80%

任务 1.3：定义核心实体和关系模型（2天）

子任务：

1. 确定 5-8 类核心实体

   • 分析 DataMate 现有数据模型
   • 选择高价值实体
   • 定义实体属性

2. 定义实体之间的关系

   • 分析业务流程
   • 定义关系类型
   • 定义关系属性

3. 设计 Schema 版本管理

   • 定义 Schema 版本号
   • 实现 Schema 迁移机制
   • 记录 Schema 变更历史

4. 创建文档

   • 实体和关系清单
   • 属性说明
   • 示例数据

验收标准：

• ✅ 有清晰的实体和关系定义
• ✅ 有完整的文档
• ✅ 有示例数据

建议的核心实体（5-8 类）：

1. Dataset：数据集
2. Field：字段
3. LabelTask：标注任务
4. Workflow：工作流
5. Job：作业
6. User：用户
7. Model：模型（可选）
8. Rule：规则（可选）

建议的核心关系：

1. HAS_FIELD：数据集包含字段
2. TRIGGERS：触发关系（Workflow → Job）
3. USES_DATASET：使用数据集（Workflow → Dataset）
4. ASSIGNED_TO：分配给（LabelTask → User）
5. PRODUCED_BY：产生于（Dataset → Job）
6. DEPENDS_ON：依赖于（Job → Job）

任务 1.4：实现基础的图谱构建流程（5天）

子任务：

1. 实现 MySQL → Neo4j 同步

   • 创建 GraphSyncService
   • 实现全量同步
   • 实现增量同步
   • 实现对账机制

2. 实现手动触发构建

   • 创建 /api/kg/sync 端点
   • 支持按实体类型同步
   • 支持按时间范围同步

3. 实现同步监控

   • 记录同步日志
   • 统计同步数据量
   • 监控同步耗时

4. 编写集成测试

   • 测试全量同步
   • 测试增量同步
   • 测试对账机制

验收标准：

• ✅ 能够从 MySQL 同步元数据到 Neo4j
• ✅ 支持增量更新
• ✅ 有完整的监控和日志
• ✅ 集成测试通过

任务 1.5：实现基础查询功能（2天）

子任务：

1. 实现邻居查询

   • 支持 N 跳邻居查询
   • 支持按关系类型过滤
   • 支持分页

2. 实现路径查询

   • 最短路径
   • 所有路径（限制最大数量）

3. 实现子图查询

   • 按条件筛选子图
   • 支持导出

4. 编写单元测试

验收标准：

• ✅ 查询功能完整
• ✅ 性能满足要求（< 1s）
• ✅ 测试覆盖率 > 80%

里程碑

M1.1（第 1 周结束）：

• ✅ Python 抽取器 API 完成
• ✅ Java 关系功能完成

M1.2（第 2 周结束）：

• ✅ 核心实体和关系模型定义完成
• ✅ 图谱构建流程完成

M1.3（第 3 周结束）：

• ✅ 基础查询功能完成
• ✅ 集成测试通过
• ✅ MVP 演示

验收标准

1. 功能完整性：

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

2. 性能指标：

   • ✅ 抽取响应时间 < 5s
   • ✅ 查询响应时间 < 1s
   • ✅ 同步吞吐量 > 1000 实体/分钟

3. 质量指标：

   • ✅ 单元测试覆盖率 > 80%
   • ✅ 集成测试通过
   • ✅ 代码审查通过

---

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

目标

将知识图谱与现有 RAG 系统深度融合，提升检索和生成质量。

任务列表

任务 2.1：实现混合检索（2周）

子任务：

1. 在 rag-query-service 中增加图检索模块
2. 实现 Milvus + Neo4j 并行检索
3. 实现结果融合和排序
4. 实现三元组文本化

任务 2.2：实现 GraphRAG（1周）

子任务：

1. 设计 GraphRAG 流程
2. 实现 Context 构建
3. 实现 LLM 生成
4. 优化 Prompt

任务 2.3：评估和优化（1周）

子任务：

1. 设计评估指标
2. 收集测试数据
3. 进行 A/B 测试
4. 优化检索策略

验收标准

• ✅ 混合检索性能优于单一检索
• ✅ 支持可配置的检索策略
• ✅ 有完整的评估指标

---

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

目标

提供友好的图谱可视化和编辑功能，优化性能和运维。

任务列表

任务 3.1：前端图谱浏览器（2周）

子任务：

1. 搭建 React + AntV G6 项目
2. 实现图谱可视化
3. 实现交互功能（缩放、拖拽、搜索）
4. 实现查询构建器

任务 3.2：Human-in-the-loop 编辑（1周）

子任务：

1. 实现实体编辑
2. 实现关系编辑
3. 实现批量操作
4. 实现审核流程

任务 3.3：性能优化（1周）

子任务：

1. 优化索引策略
2. 实现缓存机制
3. 实现离线计算
4. 优化查询语句

任务 3.4：监控和运维（1周）

子任务：

1. 集成 Prometheus + Grafana
2. 实现备份和恢复
3. 编写运维文档
4. 进行压力测试

验收标准

• ✅ 支持大规模图谱可视化（10000+ 节点）
• ✅ 支持实时编辑和反馈
• ✅ 查询响应时间 < 1s
• ✅ 有完整的监控和告警

---

📊 资源需求

人力资源

• 后端开发：1-2 人
• 前端开发：1 人
• 算法工程师：1 人（兼职）
• 测试工程师：1 人（兼职）

基础设施

• Neo4j：4 核 8GB 内存（开发环境）
• MySQL：现有资源
• Milvus：现有资源
• Redis：现有资源

外部依赖

• LLM API：OpenAI 或自部署模型
• 对象存储：备份使用

---

🎯 关键里程碑

里程碑	时间	交付物
M0	第 1 周	基础设施搭建完成 ✅
M1	第 4 周	MVP 完成，支持基础图谱构建和查询
M2	第 8 周	GraphRAG 融合完成，检索质量提升
M3	第 12 周	可视化和优化完成，系统上线

---

🔗 相关文档

• 总体方案
• 架构设计
• AI 分析结果