DataMate/docs/knowledge-graph/architecture.md

DataMate 知识图谱架构设计

🏗️ 整体架构

分层架构

┌─────────────────────────────────────────────────────────────┐
│                        前端层 (Frontend)                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  React + AntV G6                                     │   │
│  │  - 图谱可视化（分层加载、子图裁剪）                  │   │
│  │  - 图谱编辑（Human-in-the-loop）                     │   │
│  │  - 查询界面（Cypher 查询构建器）                     │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓ HTTP/REST
┌─────────────────────────────────────────────────────────────┐
│                        服务层 (Service)                      │
│  ┌──────────────────────┐  ┌──────────────────────────┐    │
│  │ kg-service           │  │ rag-query-service        │    │
│  │ (Spring Boot)        │  │ (FastAPI)                │    │
│  │                      │  │                          │    │
│  │ - 图查询 API         │  │ - 混合检索               │    │
│  │ - 权限过滤           │  │ - GraphRAG               │    │
│  │ - 缓存层 (Redis)     │  │ - 向量检索 + 图检索      │    │
│  └──────────────────────┘  └──────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                        摄入层 (Ingestion)                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  kg-ingestion (FastAPI)                              │   │
│  │  - LangChain LLMGraphTransformer                     │   │
│  │  - 实体对齐（向量相似度 + LLM）                      │   │
│  │  - 关系生成（规则 + LLM）                            │   │
│  │  - 置信度评分                                        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                        存储层 (Storage)                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │  MySQL   │  │  Neo4j   │  │  Milvus  │                 │
│  │ (元数据) │  │ (图结构) │  │ (向量)   │                 │
│  └──────────┘  └──────────┘  └──────────┘                 │
└─────────────────────────────────────────────────────────────┘

🔧 技术选型

图数据库：Neo4j

选择理由：

• ✅ 成熟稳定，社区活跃
• ✅ Cypher 查询语言简洁强大
• ✅ Spring Data Neo4j 集成良好
• ✅ 支持 ACID 事务
• ✅ 丰富的图算法库

版本：Neo4j 社区版（生产环境可升级企业版）

配置：

• 端口：7474 (HTTP), 7687 (Bolt)
• 内存：heap 512MB, page cache 512MB（可根据数据量调整）
• 持久化：Docker volume

后端框架

knowledge-graph-service (Spring Boot)

职责：

• 图谱查询 API
• 权限控制和租户隔离
• 缓存管理
• 与其他服务集成

技术栈：

• Spring Boot 3.x
• Spring Data Neo4j
• Spring Security（权限控制）
• Redis（缓存）

DDD 分层：

com.datamate.knowledgegraph/
├── application/          # 应用服务层
│   └── GraphEntityService.java
├── domain/               # 领域层
│   ├── model/
│   │   ├── GraphEntity.java
│   │   └── GraphRelation.java
│   └── repository/
│       └── GraphEntityRepository.java
├── infrastructure/       # 基础设施层
│   ├── neo4j/
│   │   └── KnowledgeGraphProperties.java
│   └── exception/
│       └── KnowledgeGraphErrorCode.java
└── interfaces/           # 接口层
    ├── rest/
    │   └── GraphEntityController.java
    └── dto/
        ├── CreateEntityRequest.java
        ├── UpdateEntityRequest.java
        └── CreateRelationRequest.java

kg-ingestion (FastAPI)

职责：

• 知识抽取（文本 → 实体 + 关系）
• 实体对齐和消歧
• 关系生成和验证
• 置信度评分

技术栈：

• FastAPI
• LangChain
• LangChain LLMGraphTransformer
• Pydantic（数据验证）

模块结构：

kg_extraction/
├── __init__.py
├── models.py             # 数据模型
├── extractor.py          # 抽取器
└── aligner.py            # 实体对齐（待实现）

前端框架

技术栈：

• React 18
• AntV G6（图可视化）
• TypeScript
• Ant Design（UI 组件）

核心功能：

• 图谱可视化（支持 10000+ 节点）
• 交互式查询构建器
• 实时编辑和反馈
• 导出和分享

🔐 安全设计

多租户隔离

策略：

• 所有实体和关系都包含 graph_id 属性
• 查询时自动添加 graph_id 过滤条件
• Neo4j 索引包含 graph_id

实现：

// 创建索引
CREATE INDEX entity_graph_id IF NOT EXISTS FOR (n:Entity) ON (n.graph_id);

// 查询时自动过滤
MATCH (n:Entity {graph_id: $graphId})
WHERE n.id = $entityId
RETURN n;

权限控制

graphId 双重防御：

1. Controller 层：@Pattern(regexp = UUID_REGEX) 格式校验
2. Service 层：validateGraphId() 业务校验

实现：

// Controller 层
@GetMapping("/{graphId}/entities/{entityId}")
public GraphEntity getEntity(
    @PathVariable @Pattern(regexp = UUID_REGEX) String graphId,
    @PathVariable @Pattern(regexp = UUID_REGEX) String entityId
) {
    return entityService.getEntity(graphId, entityId);
}

// Service 层
public GraphEntity getEntity(String graphId, String entityId) {
    validateGraphId(graphId);
    return entityRepository.findByIdAndGraphId(entityId, graphId)
        .orElseThrow(() -> BusinessException.of(
            KnowledgeGraphErrorCode.ENTITY_NOT_FOUND
        ));
}

Cypher 注入防护

策略：

• 使用参数化查询
• 禁止拼接 Cypher 字符串
• 输入验证和转义

示例：

// ✅ 正确：参数化查询
@Query("MATCH (n:Entity {id: $id, graph_id: $graphId}) RETURN n")
Optional<GraphEntity> findByIdAndGraphId(
    @Param("id") String id,
    @Param("graphId") String graphId
);

// ❌ 错误：字符串拼接
String cypher = "MATCH (n:Entity {id: '" + id + "'}) RETURN n";

📊 数据同步策略

MySQL → Neo4j 同步

策略：最终一致性 + 对账机制

同步方式：

1. 实时同步：通过 CDC（Change Data Capture）捕获 MySQL 变更
2. 批量同步：定时任务（每小时/每天）全量同步
3. 手动同步：提供 API 触发同步

对账机制：

• 每天凌晨对比 MySQL 和 Neo4j 的数据
• 发现不一致时记录日志并告警
• 提供修复工具

实现：

@Scheduled(cron = "0 0 * * * *") // 每小时
public void syncFromMySQL() {
    // 1. 查询 MySQL 中的变更
    List<Dataset> changedDatasets = datasetRepository
        .findByUpdatedAtAfter(lastSyncTime);
    
    // 2. 转换为图实体
    List<GraphEntity> entities = changedDatasets.stream()
        .map(this::toGraphEntity)
        .collect(Collectors.toList());
    
    // 3. 批量写入 Neo4j
    graphEntityRepository.saveAll(entities);
    
    // 4. 更新同步时间
    lastSyncTime = Instant.now();
}

⚡ 性能优化

查询优化

策略：

1. 限制遍历深度：最大 3 跳
2. 限制返回节点数：最大 1000 个
3. 使用索引：在高频查询字段上创建索引
4. 缓存热点数据：使用 Redis 缓存

实现：

public List<GraphEntity> getNeighbors(
    String graphId, 
    String entityId, 
    int depth, 
    int limit
) {
    // Clamp 参数
    int actualDepth = Math.min(depth, properties.getMaxDepth());
    int actualLimit = Math.min(limit, properties.getMaxNodesPerQuery());
    
    // 查询
    return entityRepository.findNeighbors(
        graphId, entityId, actualDepth, actualLimit
    );
}

索引策略

必需索引：

// 实体 ID 索引
CREATE INDEX entity_id IF NOT EXISTS FOR (n:Entity) ON (n.id);

// 图 ID 索引
CREATE INDEX entity_graph_id IF NOT EXISTS FOR (n:Entity) ON (n.graph_id);

// 复合索引
CREATE INDEX entity_id_graph_id IF NOT EXISTS
FOR (n:Entity) ON (n.id, n.graph_id);

缓存策略

缓存层次：

1. L1 缓存：Spring Cache（本地缓存）
2. L2 缓存：Redis（分布式缓存）
3. L3 缓存：Neo4j 内置缓存

缓存内容：

• 热点实体（访问频率 > 100/小时）
• 常用子图（2-hop 邻居）
• 查询结果（TTL 5 分钟）

🔄 GraphRAG 融合

混合检索架构

用户查询
    ↓
┌─────────────────────────────────────┐
│  查询理解和改写                      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  并行检索                            │
│  ┌───────────┐  ┌─────────────┐    │
│  │ Milvus    │  │ Neo4j       │    │
│  │ 向量检索  │  │ 图检索      │    │
│  │ Top-K     │  │ 2-hop 子图  │    │
│  └───────────┘  └─────────────┘    │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  结果融合和排序                      │
│  - 向量相似度 × 0.6                 │
│  - 图结构相关性 × 0.4               │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  Context 构建                        │
│  - 文档片段（Milvus）               │
│  - 三元组文本化（Neo4j）            │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│  LLM 生成                            │
└─────────────────────────────────────┘

三元组文本化

策略：将图结构转换为自然语言

示例：

# 图结构
(Dataset:用户行为数据)-[HAS_FIELD]->(Field:user_id)
(Dataset:用户行为数据)-[USED_BY]->(Workflow:用户画像构建)

# 文本化
"""
数据集"用户行为数据"包含字段"user_id"。
数据集"用户行为数据"被工作流"用户画像构建"使用。
"""

📈 监控和运维

监控指标

Neo4j 指标：

• 节点数量
• 关系数量
• 查询响应时间
• 内存使用率
• 磁盘使用率

服务指标：

• API 响应时间
• 错误率
• 吞吐量
• 缓存命中率

工具：

• Prometheus（指标采集）
• Grafana（可视化）
• Neo4j Metrics（Neo4j 专用指标）

备份策略

Neo4j 备份：

• 每天凌晨全量备份
• 保留最近 7 天的备份
• 备份到对象存储（S3/OSS）

恢复测试：

• 每月进行一次恢复演练
• 验证备份的完整性和可用性

🔗 相关文档

• 总体方案
• 实施计划
• AI 分析结果