second round of translation fixes

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

docs/tech-specs/graphrag-performance-optimization.zh-cn.md

@@ -0,0 +1,364 @@
+# 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)