mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-09 05:12:12 +02:00
364 lines
No EOL
14 KiB
Markdown
364 lines
No EOL
14 KiB
Markdown
# GraphRAG 性能优化技术规范
|
||
|
||
## 概述
|
||
|
||
本规范描述了 TrustGraph 中 GraphRAG（基于图的检索增强生成）算法的全面性能优化。当前的实现存在严重的性能瓶颈，限制了可扩展性和响应时间。本规范解决了四个主要优化领域：
|
||
|
||
1. **图遍历优化**: 消除低效的递归数据库查询，并实现批处理图探索。
|
||
2. **标签解析优化**: 替换顺序标签获取方式，采用并行/批处理操作。
|
||
3. **缓存策略增强**: 实现智能缓存，采用 LRU 淘汰策略和预取。
|
||
4. **查询优化**: 添加结果备忘和嵌入缓存，以提高响应时间。
|
||
|
||
## 目标
|
||
|
||
- **减少数据库查询量**: 通过批处理和缓存，实现总数据库查询量的 50-80% 减少。
|
||
- **提高响应时间**: 目标是子图构建速度提升 3-5 倍，标签解析速度提升 2-3 倍。
|
||
- **增强可扩展性**: 支持更大的知识图谱，并改进内存管理。
|
||
- **保持准确性**: 保持现有的 GraphRAG 功能和结果质量。
|
||
- **启用并发性**: 提高并行处理能力，支持多个并发请求。
|
||
- **减少内存占用**: 实施高效的数据结构和内存管理。
|
||
- **增加可观察性**: 包含性能指标和监控功能。
|
||
- **确保可靠性**: 添加适当的错误处理和超时机制。
|
||
|
||
## 背景
|
||
|
||
`trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` 中当前的 GraphRAG 实现存在以下关键性能问题，严重影响系统可扩展性：
|
||
|
||
### 当前性能问题
|
||
|
||
**1. 低效的图遍历 (`follow_edges` 函数，第 79-127 行)**
|
||
- 对每个实体、每个深度级别执行 3 次独立的数据库查询。
|
||
- 查询模式：针对每个实体的基于主体、基于谓词和基于对象的查询。
|
||
- 没有批处理：每次查询只处理一个实体。
|
||
- 没有循环检测：可能多次访问相同的节点。
|
||
- 没有备忘功能的递归实现会导致指数级复杂度。
|
||
- 时间复杂度：O(entities × max_path_length × triple_limit³)
|
||
|
||
**2. 顺序标签解析 (`get_labelgraph` 函数，第 144-171 行)**
|
||
- 顺序处理每个三元组组件（主体、谓词、对象）。
|
||
- 每次 `maybe_label` 调用可能触发数据库查询。
|
||
- 没有并行执行或批处理标签查询。
|
||
- 导致最多 subgraph_size × 3 次独立的数据库调用。
|
||
|
||
**3. 原始缓存策略 (`maybe_label` 函数，第 62-77 行)**
|
||
- 简单的字典缓存，没有大小限制或 TTL（生存时间）。
|
||
- 没有缓存淘汰策略导致内存无限增长。
|
||
- 缓存未命中会触发单独的数据库查询。
|
||
- 没有预取或智能缓存预热。
|
||
|
||
**4. 不佳的查询模式**
|
||
- 实体向量相似度查询未在相似请求之间缓存。
|
||
- 没有重复查询模式的结果备忘。
|
||
- 缺少常见访问模式的查询优化。
|
||
|
||
**5. 关键的对象生命周期问题 (`rag.py:96-102`)**
|
||
- **`GraphRag` 对象每个请求都重新创建**: 每次查询都会创建新的实例，失去所有缓存优势。
|
||
- **`Query` 对象生存时间极短**: 创建并销毁于单个查询执行中 (第 201-207 行)。
|
||
- **标签缓存每个请求都重置**: 缓存预热和积累的知识在请求之间丢失。
|
||
- **客户端重新创建开销**: 数据库客户端可能为每个请求重新建立连接。
|
||
- **没有跨请求优化**: 无法从查询模式或结果共享中受益。
|
||
|
||
### 性能影响分析
|
||
|
||
当前典型的查询最坏情况：
|
||
- **实体检索**: 1 次向量相似度查询。
|
||
- **图遍历**: entities × max_path_length × 3 × triple_limit 次查询。
|
||
- **标签解析**: subgraph_size × 3 次独立的标签查询。
|
||
|
||
对于默认参数（50 个实体，路径长度 2，30 个三元组限制，150 个子图大小）：
|
||
- **最小查询次数**: 1 + (50 × 2 × 3 × 30) + (150 × 3) = **9,451 次数据库查询**
|
||
- **响应时间**: 中等大小图的响应时间为 15-30 秒。
|
||
- **内存使用**: 缓存无限增长。
|
||
- **缓存有效性**: 0% - 每次请求都重置缓存。
|
||
- **对象创建开销**: 为每个请求创建/销毁 `GraphRag` + `Query` 对象。
|
||
|
||
本规范通过实施批处理查询、智能缓存和并行处理来解决这些问题。 通过优化查询模式和数据访问，TrustGraph 可以：
|
||
- 支持数百万个实体的企业级知识图谱。
|
||
- 为典型的查询提供亚秒级的响应时间。
|
||
- 处理数百个并发的 GraphRAG 请求。
|
||
- 通过图的大小和复杂性实现高效扩展。
|
||
|
||
## 技术设计
|
||
|
||
### 架构
|
||
|
||
GraphRAG 性能优化需要以下技术组件：
|
||
|
||
#### 1. **对象生命周期架构重构**
|
||
- **使 `GraphRag` 长期存在**: 将 `GraphRag` 实例移动到 Processor 级别，以在请求之间保持持久性。
|
||
- **保留缓存**: 保持标签缓存、嵌入缓存和查询结果缓存在请求之间。
|
||
- **优化 `Query` 对象**: 将 `Query` 重构为轻量级执行上下文，而不是数据容器。
|
||
- **连接持久化**: 在请求之间保持数据库客户端连接。
|
||
|
||
模块: `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` (已修改)
|
||
|
||
#### 2. **优化的图遍历引擎**
|
||
- 将递归的 `follow_edges` 替换为迭代的广度优先搜索。
|
||
- 在每个遍历级别实施批处理实体处理。
|
||
- 添加循环检测，使用已访问节点跟踪。
|
||
- 包含当达到限制时提前终止。
|
||
|
||
模块: `trustgraph-flow/trustgraph/retrieval/graph_rag/optimized_traversal.py`
|
||
|
||
#### 3. **并行标签解析系统**
|
||
- 批量处理多个实体同时的标签查询。
|
||
- 实施 async/await 模式以进行并发数据库访问。
|
||
- 添加常见的标签模式的智能预取。
|
||
- 包含标签缓存预热策略。
|
||
|
||
模块: `trustgraph-flow/trustgraph/retrieval/graph_rag/label_resolver.py`
|
||
|
||
#### 4. **保守的标签缓存层**
|
||
- LRU 缓存，带短 TTL（5 分钟）用于仅限标签，以平衡性能与一致性。
|
||
- 缓存指标和命中率监控。
|
||
- **不缓存嵌入**: 已针对每个查询进行缓存，没有跨查询的优势。
|
||
- **不缓存查询结果**: 由于图的mutation一致性问题。
|
||
|
||
模块: `trustgraph-flow/trustgraph/retrieval/graph_rag/cache_manager.py`
|
||
|
||
#### 5. **查询优化框架**
|
||
- 查询模式分析和优化建议。
|
||
- 数据库访问的批处理查询协调器。
|
||
- 连接池和查询超时管理。
|
||
- 性能监控和指标收集。
|
||
|
||
模块: `trustgraph-flow/trustgraph/retrieval/graph_rag/query_optimizer.py`
|
||
|
||
### 数据模型
|
||
|
||
#### 优化的图遍历状态
|
||
|
||
遍历引擎维护状态以避免重复操作：
|
||
|
||
```python
|
||
@dataclass
|
||
class TraversalState:
|
||
visited_entities: Set[str]
|
||
current_level_entities: Set[str]
|
||
next_level_entities: Set[str]
|
||
subgraph: Set[Tuple[str, str, str]]
|
||
depth: int
|
||
query_batch: List[TripleQuery]
|
||
```
|
||
|
||
这种方法允许：
|
||
- 通过跟踪已访问实体实现高效的循环检测。
|
||
- 在每个遍历级别批处理查询准备。
|
||
- 通过内存效率的状态管理。
|
||
- 当达到大小限制时提前终止。
|
||
|
||
#### 增强的缓存结构
|
||
|
||
```python
|
||
@dataclass
|
||
class CacheEntry:
|
||
value: Any
|
||
timestamp: float
|
||
access_count: int
|
||
ttl: Optional[float]
|
||
|
||
class CacheManager:
|
||
label_cache: LRUCache[str, CacheEntry]
|
||
embedding_cache: LRUCache[str, CacheEntry]
|
||
query_result_cache: LRUCache[str, CacheEntry]
|
||
cache_stats: CacheStatistics
|
||
```
|
||
|
||
#### 批处理查询结构
|
||
|
||
```python
|
||
@dataclass
|
||
class BatchTripleQuery:
|
||
entities: List[str]
|
||
query_type: QueryType # SUBJECT, PREDICATE, OBJECT
|
||
limit_per_entity: int
|
||
|
||
@dataclass
|
||
class BatchLabelQuery:
|
||
entities: List[str]
|
||
predicate: str = LABEL
|
||
```
|
||
|
||
### API
|
||
|
||
#### 新 API：
|
||
|
||
**图遍历 API**
|
||
```python
|
||
async def optimized_follow_edges_batch(
|
||
entities: List[str],
|
||
max_depth: int,
|
||
triple_limit: int,
|
||
max_subgraph_size: int
|
||
) -> Set[Tuple[str, str, str]]
|
||
```
|
||
|
||
**批量标签解析 API**
|
||
```python
|
||
async def resolve_labels_batch(
|
||
entities: List[str],
|
||
cache_manager: CacheManager
|
||
) -> Dict[str, str]
|
||
```
|
||
|
||
**缓存管理 API**
|
||
```python
|
||
class CacheManager:
|
||
async def get_or_fetch_label(self, entity: str) -> str
|
||
async def get_or_fetch_embeddings(self, query: str) -> List[float]
|
||
async def cache_query_result(self, query: str, result: Any, timeout: int = 3600)
|
||
def total_cache_size(self) -> int
|
||
```
|
||
|
||
#### 接口变更
|
||
|
||
**查询类**: 将 `follow_edges` 方法替换为批处理迭代遍历
|
||
**GraphRag 类**: 添加标签缓存层
|
||
**Processor 类**: 修改以使用持久的 `GraphRag` 实例
|
||
**总**: 大约 140 行的代码更改，主要集中在现有的类中。
|
||
|
||
## 缓存一致性注意事项
|
||
|
||
**数据时效性权衡：**
|
||
- **标签缓存 (5 分钟 TTL)**: 存在提供已删除/重命名的实体标签的风险。
|
||
- **不缓存嵌入**: 不需要 - 嵌入已经针对每个查询进行缓存。
|
||
- **不缓存查询结果**: 防止从已删除实体/关系中获取过时子图结果。
|
||
|
||
**缓解策略：**
|
||
- **保守的 TTL 值**: 平衡性能收益（10-20%）与数据新鲜度。
|
||
- **缓存失效钩子**: 可选地集成图 mutation 事件。
|
||
- **监控仪表板**: 跟踪缓存命中率与时效性事件。
|
||
- **可配置的缓存策略**: 允许根据 mutation 频率进行每个部署的调整。
|
||
|
||
**推荐的缓存配置（根据图的 mutation 速率）：**
|
||
- **高 mutation（每小时 > 100 次更改）**: TTL=60 秒，较小的缓存大小。
|
||
- **中等 mutation（每小时 10-100 次更改）**: TTL=300 秒（默认值）。
|
||
- **低 mutation（每小时 < 10 次更改）**: TTL=600 秒，较大的缓存大小。
|
||
|
||
## 安全注意事项
|
||
|
||
**防止查询注入：**
|
||
- 验证所有实体标识符和查询参数。
|
||
- 对所有数据库交互使用参数化查询。
|
||
- 实施查询复杂度限制，以防止拒绝服务攻击。
|
||
|
||
**资源保护：**
|
||
- 强制执行最大子图大小限制。
|
||
- 实施查询超时，以防止资源耗尽。
|
||
- 添加内存使用监控和限制。
|
||
|
||
**访问控制：**
|
||
- 维护现有的用户和集合隔离。
|
||
- 添加对性能影响操作的审计日志。
|
||
- 实施速率限制，以防止昂贵操作。
|
||
|
||
## 性能注意事项
|
||
|
||
### 预期性能提升
|
||
|
||
**查询减少：**
|
||
- 当前：典型的请求大约为 9,000+ 次查询。
|
||
- 优化后：大约 50-100 次批处理查询（减少 98%）。
|
||
|
||
**响应时间改进：**
|
||
- 图遍历：15-20 秒 → 3-5 秒（快 4-5 倍）。
|
||
- 标签解析：8-12 秒 → 2-4 秒（快 3 倍）。
|
||
- 总体查询：25-35 秒 → 6-10 秒（提高 3-4 倍）。
|
||
|
||
**内存效率：**
|
||
- 边界缓存大小可防止内存泄漏。
|
||
- 高效的数据结构可将内存占用减少 40%。
|
||
- 通过适当的资源清理实现更好的垃圾回收。
|
||
|
||
**可扩展性改进：**
|
||
- 支持更大的知识图谱（受缓存一致性需求的限制）。
|
||
- 更高的并发请求容量。
|
||
- 通过连接重用实现更好的资源利用率。
|
||
|
||
### 性能监控
|
||
|
||
**实时指标：**
|
||
- 查询执行时间（按操作类型）。
|
||
- 缓存命中率和有效性。
|
||
- 数据库连接池利用率。
|
||
- 内存使用情况和垃圾回收影响。
|
||
|
||
**性能基准测试：**
|
||
- 针对当前实现的自动化性能回归测试。
|
||
- 使用真实数据量的负载测试。
|
||
- 针对内存和连接限制进行压力测试。
|
||
- 针对性能改进进行回归测试。
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试
|
||
- 对遍历、缓存和标签解析等各个组件进行测试。
|
||
- 模拟数据库交互以进行性能测试。
|
||
- 缓存淘汰和 TTL 到期测试。
|
||
- 错误处理和超时场景。
|
||
|
||
### 集成测试
|
||
- 使用优化后的 GraphRAG 查询进行端到端测试。
|
||
- 使用真实数据进行数据库交互测试。
|
||
- 并发请求处理和资源管理。
|
||
- 内存泄漏检测和资源清理验证。
|
||
|
||
### 性能测试
|
||
- 针对当前实现进行基准测试。
|
||
- 使用不同大小和复杂度的知识图谱进行负载测试。
|
||
- 针对内存和连接限制进行压力测试。
|
||
- 针对性能改进进行回归测试。
|
||
|
||
### 兼容性测试
|
||
- 验证现有的 GraphRAG API 兼容性。
|
||
- 测试与各种图数据库后端兼容性。
|
||
- 验证与当前实现相比的结果准确性。
|
||
|
||
## 实施计划
|
||
|
||
### 直接实施方法
|
||
由于允许更改 API，因此直接实施优化，而无需迁移的复杂性：
|
||
|
||
1. **替换 `follow_edges` 方法**: 使用迭代的批处理遍历进行重写。
|
||
2. **优化 `get_labelgraph`**: 实施并行标签解析。
|
||
3. **添加长期存在的 `GraphRag` 实例**: 修改 `Processor` 以使用持久的实例。
|
||
4. **实施标签缓存**: 在 `GraphRag` 类中添加 LRU 缓存。
|
||
|
||
### 更改范围
|
||
- **`Query` 类**: 替换 `follow_edges` 方法，添加约 30 行批处理处理代码。
|
||
- **`GraphRag` 类**: 添加标签缓存层。
|
||
- **`Processor` 类**: 修改以使用持久的 `GraphRag` 实例，约 20 行代码。
|
||
- **总计**: 大约 140 行的集中代码更改，主要集中在现有的类中。
|
||
|
||
## 时间表
|
||
|
||
**第一周：核心实施**
|
||
- 替换 `follow_edges` 方法为批处理迭代遍历。
|
||
- 在 `get_labelgraph` 中实现并行标签解析。
|
||
- 将 `GraphRag` 实例添加到 `Processor`，使其长期存在。
|
||
- 在 `GraphRag` 类中实现标签缓存层。
|
||
|
||
**第二周：测试和集成**
|
||
- 对新的遍历和缓存逻辑进行单元测试。
|
||
- 针对当前实现进行性能基准测试。
|
||
- 使用真实图数据进行集成测试。
|
||
- 代码审查和优化。
|
||
|
||
**第三周：部署**
|
||
- 部署优化的实现。
|
||
- 监控性能改进。
|
||
- 根据实际使用情况微调缓存 TTL 和批处理大小。
|
||
|
||
## 开放问题
|
||
|
||
- **数据库连接池**: 是否应实施自定义连接池，或依赖于现有的数据库客户端池？
|
||
- **缓存持久性**: 是否应跨服务重启持久化标签和嵌入缓存？
|
||
- **分布式缓存**: 对于多实例部署，是否应实现分布式缓存（例如，使用 Redis/Memcached）？
|
||
- **查询结果格式**: 是否应优化内部三元组表示以实现更好的内存效率？
|
||
- **监控集成**: 哪些指标应暴露给现有的监控系统（例如，Prometheus）？
|
||
|
||
## 参考资料
|
||
|
||
- [GraphRAG 原始实现](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
|
||
- [TrustGraph 架构原则](architecture-principles.md)
|
||
- [集合管理规范](collection-management.md) |