mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-07-09 05:12:12 +02:00

Jenkins, Kenneth Alexander 1f1aaa24ae

Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>

2026-04-06 14:50:34 -04:00

14 KiB

Raw Blame History

GraphRAG 性能优化技术规范

概述

本规范描述了 TrustGraph 中 GraphRAG（基于图的检索增强生成）算法的全面性能优化。当前的实现存在严重的性能瓶颈，限制了可扩展性和响应时间。本规范解决了四个主要优化领域：

图遍历优化: 消除低效的递归数据库查询，并实现批处理图探索。
标签解析优化: 替换顺序标签获取方式，采用并行/批处理操作。
缓存策略增强: 实现智能缓存，采用 LRU 淘汰策略和预取。
查询优化: 添加结果备忘和嵌入缓存，以提高响应时间。

目标

减少数据库查询量: 通过批处理和缓存，实现总数据库查询量的 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

数据模型

优化的图遍历状态

遍历引擎维护状态以避免重复操作：

@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]

这种方法允许：

通过跟踪已访问实体实现高效的循环检测。
在每个遍历级别批处理查询准备。
通过内存效率的状态管理。
当达到大小限制时提前终止。

增强的缓存结构

@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

批处理查询结构

@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

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

async def resolve_labels_batch(
    entities: List[str],
    cache_manager: CacheManager
) -> Dict[str, str]

缓存管理 API

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，因此直接实施优化，而无需迁移的复杂性：

替换 follow_edges 方法: 使用迭代的批处理遍历进行重写。
优化 get_labelgraph: 实施并行标签解析。
添加长期存在的 GraphRag 实例: 修改 Processor 以使用持久的实例。
实施标签缓存: 在 GraphRag 类中添加 LRU 缓存。

更改范围

Query 类: 替换 follow_edges 方法，添加约 30 行批处理处理代码。
GraphRag 类: 添加标签缓存层。
Processor 类: 修改以使用持久的 GraphRag 实例，约 20 行代码。
总计: 大约 140 行的集中代码更改，主要集中在现有的类中。

时间表

第一周：核心实施

替换 follow_edges 方法为批处理迭代遍历。
在 get_labelgraph 中实现并行标签解析。
将 GraphRag 实例添加到 Processor，使其长期存在。
在 GraphRag 类中实现标签缓存层。

第二周：测试和集成

对新的遍历和缓存逻辑进行单元测试。
针对当前实现进行性能基准测试。
使用真实图数据进行集成测试。
代码审查和优化。

第三周：部署

部署优化的实现。
监控性能改进。
根据实际使用情况微调缓存 TTL 和批处理大小。

开放问题

数据库连接池: 是否应实施自定义连接池，或依赖于现有的数据库客户端池？
缓存持久性: 是否应跨服务重启持久化标签和嵌入缓存？
分布式缓存: 对于多实例部署，是否应实现分布式缓存（例如，使用 Redis/Memcached）？
查询结果格式: 是否应优化内部三元组表示以实现更好的内存效率？
监控集成: 哪些指标应暴露给现有的监控系统（例如，Prometheus）？

14 KiB Raw Blame History Unescape Escape