Feat: TrustGraph i18n & Documentation Translation Updates (#781)

Native CLI i18n: The TrustGraph CLI has built-in translation support
that dynamically loads language strings. You can test and use
different languages by simply passing the --lang flag (e.g., --lang
es for Spanish, --lang ru for Russian) or by configuring your
environment's LANG variable.

Automated Docs Translations: This PR introduces autonomously
translated Markdown documentation into several target languages,
including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew,
Arabic, Simplified Chinese, and Russian.

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

@@ -0,0 +1,774 @@
+---
+layout: default
+title: "GraphRAG 性能优化技术规范"
+parent: "Chinese (Beta)"
+---
+
+# GraphRAG 性能优化技术规范
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 概述
+
+本规范描述了 TrustGraph 中 GraphRAG (基于图的检索增强生成) 算法的全面性能优化。当前的实现存在严重的性能瓶颈，限制了可扩展性和响应时间。本规范解决了四个主要的优化领域：
+
+1. **图遍历优化**: 消除低效的递归数据库查询，并实现批量图探索
+2. **标签解析优化**: 使用并行/批量操作替换顺序标签获取
+3. **缓存策略增强**: 实现智能缓存，采用 LRU 淘汰策略和预取
+4. **查询优化**: 添加结果记忆化和嵌入式缓存，以提高响应时间
+
+## 目标
+
+**减少数据库查询量**: 通过批量和缓存，实现总数据库查询量减少 50-80%
+**提高响应时间**: 目标是子图构建速度提高 3-5 倍，标签解析速度提高 2-3 倍
+<<<<<<< HEAD
+**增强可扩展性**: 更好地管理内存，支持更大的知识图谱
+=======
+**增强可扩展性**: 通过更好的内存管理，支持更大的知识图谱
+>>>>>>> 82edf2d (New md files from RunPod)
+**保持准确性**: 保持现有的 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 对象每个请求重新创建**: 为每个查询创建一个新的实例，失去所有缓存的好处
+**查询对象寿命极短**: 在单个查询执行中创建和销毁 (第 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% - 每次请求都会重置缓存
+<<<<<<< HEAD
+**对象创建开销**: 每个请求都会创建/销毁GraphRag + Query对象
+
+本规范通过实现批量查询、智能缓存和并行处理来解决这些问题。通过优化查询模式和数据访问，TrustGraph可以：
+支持拥有数百万个实体的企业级知识图谱
+为典型的查询提供亚秒级的响应时间
+=======
+**对象创建开销**: 每个请求会创建/销毁GraphRag + Query对象
+
+本规范通过实现批量查询、智能缓存和并行处理来解决这些问题。通过优化查询模式和数据访问，TrustGraph可以：
+支持拥有数百万个实体的企业级知识图谱
+为典型查询提供亚秒级的响应时间
+>>>>>>> 82edf2d (New md files from RunPod)
+处理数百个并发的GraphRAG请求
+随着图的大小和复杂性而高效扩展
+
+## 技术设计
+
+### 架构
+
+GraphRAG性能优化需要以下技术组件：
+
+#### 1. **对象生命周期架构重构**
+   **使GraphRag具有长期生命周期**: 将GraphRag实例移动到处理器级别，以便在请求之间保持持久性
+   **保留缓存**: 在请求之间维护标签缓存、嵌入缓存和查询结果缓存
+   **优化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分钟，以平衡性能与一致性
+   监控缓存指标和命中率
+   **不缓存嵌入**: 已经针对每个查询进行缓存，没有跨查询的好处
+   **不缓存查询结果**: 由于图的突变一致性问题
+
+   模块: `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]
+```
+
+这种方法允许：
+<<<<<<< HEAD
+通过跟踪访问的实体实现高效的循环检测
+=======
+通过跟踪访问过的实体实现高效的循环检测
+>>>>>>> 82edf2d (New md files from RunPod)
+在每个遍历层级进行批量查询准备
+内存效率高的状态管理
+当达到大小限制时，可以提前终止
+
+#### 增强的缓存结构
+
+```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_hash: str, result: Any, ttl: int)
+    def get_cache_statistics(self) -> CacheStatistics
+```
+
+#### 修改后的 API：
+
+**GraphRag.query()** - 增强了性能优化：
+<<<<<<< HEAD
+添加了 cache_manager 参数以进行缓存控制
+包含 performance_metrics 返回值
+添加了 query_timeout 参数以提高可靠性
+
+**Query 类** - 进行了重构，用于批量处理：
+将单个实体处理替换为批量操作
+添加了异步上下文管理器以进行资源清理
+=======
+添加 `cache_manager` 参数以进行缓存控制
+包含 `performance_metrics` 返回值
+添加 `query_timeout` 参数以提高可靠性
+
+**Query 类** - 重新设计，用于批量处理：
+将单个实体处理替换为批量操作
+添加异步上下文管理器以进行资源清理
+>>>>>>> 82edf2d (New md files from RunPod)
+包含进度回调函数，用于长时间运行的操作
+
+### 实施细节
+
+#### 阶段 0：关键架构生命周期重构
+
+**当前存在问题的实现：**
+```python
+# INEFFICIENT: GraphRag recreated every request
+class Processor(FlowProcessor):
+    async def on_request(self, msg, consumer, flow):
+        # PROBLEM: New GraphRag instance per request!
+        self.rag = GraphRag(
+            embeddings_client = flow("embeddings-request"),
+            graph_embeddings_client = flow("graph-embeddings-request"),
+            triples_client = flow("triples-request"),
+            prompt_client = flow("prompt-request"),
+            verbose=True,
+        )
+        # Cache starts empty every time - no benefit from previous requests
+        response = await self.rag.query(...)
+
+# VERY SHORT-LIVED: Query object created/destroyed per request
+class GraphRag:
+    async def query(self, query, user="trustgraph", collection="default", ...):
+        q = Query(rag=self, user=user, collection=collection, ...)  # Created
+        kg = await q.get_labelgraph(query)  # Used briefly
+        # q automatically destroyed when function exits
+```
+
+<<<<<<< HEAD
+**优化后的长期运行架构：**
+=======
+**优化后的长寿命架构：**
+>>>>>>> 82edf2d (New md files from RunPod)
+```python
+class Processor(FlowProcessor):
+    def __init__(self, **params):
+        super().__init__(**params)
+        self.rag_instance = None  # Will be initialized once
+        self.client_connections = {}
+
+    async def initialize_rag(self, flow):
+        """Initialize GraphRag once, reuse for all requests"""
+        if self.rag_instance is None:
+            self.rag_instance = LongLivedGraphRag(
+                embeddings_client=flow("embeddings-request"),
+                graph_embeddings_client=flow("graph-embeddings-request"),
+                triples_client=flow("triples-request"),
+                prompt_client=flow("prompt-request"),
+                verbose=True,
+            )
+        return self.rag_instance
+
+    async def on_request(self, msg, consumer, flow):
+        # REUSE the same GraphRag instance - caches persist!
+        rag = await self.initialize_rag(flow)
+
+        # Query object becomes lightweight execution context
+        response = await rag.query_with_context(
+            query=v.query,
+            execution_context=QueryContext(
+                user=v.user,
+                collection=v.collection,
+                entity_limit=entity_limit,
+                # ... other params
+            )
+        )
+
+class LongLivedGraphRag:
+    def __init__(self, ...):
+        # CONSERVATIVE caches - balance performance vs consistency
+        self.label_cache = LRUCacheWithTTL(max_size=5000, ttl=300)  # 5min TTL for freshness
+        # Note: No embedding cache - already cached per-query, no cross-query benefit
+        # Note: No query result cache due to consistency concerns
+        self.performance_metrics = PerformanceTracker()
+
+    async def query_with_context(self, query: str, context: QueryContext):
+        # Use lightweight QueryExecutor instead of heavyweight Query object
+        executor = QueryExecutor(self, context)  # Minimal object
+        return await executor.execute(query)
+
+@dataclass
+class QueryContext:
+    """Lightweight execution context - no heavy operations"""
+    user: str
+    collection: str
+    entity_limit: int
+    triple_limit: int
+    max_subgraph_size: int
+    max_path_length: int
+
+class QueryExecutor:
+    """Lightweight execution context - replaces old Query class"""
+    def __init__(self, rag: LongLivedGraphRag, context: QueryContext):
+        self.rag = rag
+        self.context = context
+        # No heavy initialization - just references
+
+    async def execute(self, query: str):
+        # All heavy lifting uses persistent rag caches
+        return await self.rag.execute_optimized_query(query, self.context)
+```
+
+<<<<<<< HEAD
+这种架构上的改变提供了：
+**对于具有常见关系的图，数据库查询减少 10-20%**（相对于目前 0% 的减少）
+**消除了每个请求中的对象创建开销**
+=======
+这一架构变更提供了：
+**对于具有常见关系的图，数据库查询减少 10-20%**（相对于目前 0% 的减少）
+**消除了每个请求的对象的创建开销**
+>>>>>>> 82edf2d (New md files from RunPod)
+**持久连接池和客户端重用**
+**缓存 TTL 窗口内的跨请求优化**
+
+**重要的缓存一致性限制：**
+长期缓存会带来数据陈旧的风险，尤其是在底层图中删除或修改实体/标签时。 LRU 缓存和 TTL 在性能提升和数据新鲜度之间提供了一种平衡，但无法检测到实时图的变化。
+
+#### 第一阶段：图遍历优化
+
+**当前实现的缺点：**
+```python
+# INEFFICIENT: 3 queries per entity per level
+async def follow_edges(self, ent, subgraph, path_length):
+    # Query 1: s=ent, p=None, o=None
+    res = await self.rag.triples_client.query(s=ent, p=None, o=None, limit=self.triple_limit)
+    # Query 2: s=None, p=ent, o=None
+    res = await self.rag.triples_client.query(s=None, p=ent, o=None, limit=self.triple_limit)
+    # Query 3: s=None, p=None, o=ent
+    res = await self.rag.triples_client.query(s=None, p=None, o=ent, limit=self.triple_limit)
+```
+
+**优化实现：**
+```python
+async def optimized_traversal(self, entities: List[str], max_depth: int) -> Set[Triple]:
+    visited = set()
+    current_level = set(entities)
+    subgraph = set()
+
+    for depth in range(max_depth):
+        if not current_level or len(subgraph) >= self.max_subgraph_size:
+            break
+
+        # Batch all queries for current level
+        batch_queries = []
+        for entity in current_level:
+            if entity not in visited:
+                batch_queries.extend([
+                    TripleQuery(s=entity, p=None, o=None),
+                    TripleQuery(s=None, p=entity, o=None),
+                    TripleQuery(s=None, p=None, o=entity)
+                ])
+
+        # Execute all queries concurrently
+        results = await self.execute_batch_queries(batch_queries)
+
+        # Process results and prepare next level
+        next_level = set()
+        for result in results:
+            subgraph.update(result.triples)
+            next_level.update(result.new_entities)
+
+        visited.update(current_level)
+        current_level = next_level - visited
+
+    return subgraph
+```
+
+#### 第二阶段：并行标签解析
+
+**当前的顺序实现方式：**
+```python
+# INEFFICIENT: Sequential processing
+for edge in subgraph:
+    s = await self.maybe_label(edge[0])  # Individual query
+    p = await self.maybe_label(edge[1])  # Individual query
+    o = await self.maybe_label(edge[2])  # Individual query
+```
+
+<<<<<<< HEAD
+**优化后的并行实现：**
+=======
+**优化并行实现：**
+>>>>>>> 82edf2d (New md files from RunPod)
+```python
+async def resolve_labels_parallel(self, subgraph: List[Triple]) -> List[Triple]:
+    # Collect all unique entities needing labels
+    entities_to_resolve = set()
+    for s, p, o in subgraph:
+        entities_to_resolve.update([s, p, o])
+
+    # Remove already cached entities
+    uncached_entities = [e for e in entities_to_resolve if e not in self.label_cache]
+
+    # Batch query for all uncached labels
+    if uncached_entities:
+        label_results = await self.batch_label_query(uncached_entities)
+        self.label_cache.update(label_results)
+
+    # Apply labels to subgraph
+    return [
+        (self.label_cache.get(s, s), self.label_cache.get(p, p), self.label_cache.get(o, o))
+        for s, p, o in subgraph
+    ]
+```
+
+#### 第三阶段：高级缓存策略
+
+**LRU 缓存与 TTL：**
+```python
+class LRUCacheWithTTL:
+    def __init__(self, max_size: int, default_ttl: int = 3600):
+        self.cache = OrderedDict()
+        self.max_size = max_size
+        self.default_ttl = default_ttl
+        self.access_times = {}
+
+    async def get(self, key: str) -> Optional[Any]:
+        if key in self.cache:
+            # Check TTL expiration
+            if time.time() - self.access_times[key] > self.default_ttl:
+                del self.cache[key]
+                del self.access_times[key]
+                return None
+
+            # Move to end (most recently used)
+            self.cache.move_to_end(key)
+            return self.cache[key]
+        return None
+
+    async def put(self, key: str, value: Any):
+        if key in self.cache:
+            self.cache.move_to_end(key)
+        else:
+            if len(self.cache) >= self.max_size:
+                # Remove least recently used
+                oldest_key = next(iter(self.cache))
+                del self.cache[oldest_key]
+                del self.access_times[oldest_key]
+
+        self.cache[key] = value
+        self.access_times[key] = time.time()
+```
+
+#### 第四阶段：查询优化和监控
+
+**性能指标收集：**
+```python
+@dataclass
+class PerformanceMetrics:
+    total_queries: int
+    cache_hits: int
+    cache_misses: int
+    avg_response_time: float
+    subgraph_construction_time: float
+    label_resolution_time: float
+    total_entities_processed: int
+    memory_usage_mb: float
+```
+
+**查询超时和断路器：**
+```python
+async def execute_with_timeout(self, query_func, timeout: int = 30):
+    try:
+        return await asyncio.wait_for(query_func(), timeout=timeout)
+    except asyncio.TimeoutError:
+        logger.error(f"Query timeout after {timeout}s")
+        raise GraphRagTimeoutError(f"Query exceeded timeout of {timeout}s")
+```
+
+## 缓存一致性考虑
+
+**数据时效性权衡：**
+**标签缓存 (5 分钟 TTL)**：存在提供已删除/重命名的实体标签的风险。
+**不缓存嵌入 (embeddings)**：不需要 - 嵌入已按查询缓存。
+**不缓存结果**：防止从已删除的实体/关系中获取过时的子图结果。
+
+**缓解策略：**
+**保守的 TTL 值**：在性能提升 (10-20%) 和数据新鲜度之间取得平衡。
+**缓存失效钩子**：可选地与图的修改事件集成。
+<<<<<<< HEAD
+**监控仪表板**：跟踪缓存命中率与数据时效性事件。
+**可配置的缓存策略**：允许根据修改频率进行按部署的调整。
+
+**根据图修改速率推荐的缓存配置：**
+=======
+**监控仪表板**：跟踪缓存命中率与数据陈旧事件。
+**可配置的缓存策略**：允许根据修改频率进行按部署的调整。
+
+**基于图修改速率的推荐缓存配置：**
+>>>>>>> 82edf2d (New md files from RunPod)
+**高修改速率 (>100 次/小时)**：TTL=60 秒，较小的缓存大小。
+**中等修改速率 (10-100 次/小时)**：TTL=300 秒 (默认值)。
+**低修改速率 (<10 次/小时)**：TTL=600 秒，较大的缓存大小。
+
+## 安全性考虑
+
+**查询注入防护：**
+验证所有实体标识符和查询参数。
+对所有数据库交互使用参数化查询。
+实施查询复杂度限制以防止拒绝服务 (DoS) 攻击。
+
+**资源保护：**
+强制执行最大子图大小限制。
+实施查询超时以防止资源耗尽。
+添加内存使用情况监控和限制。
+
+**访问控制：**
+维护现有的用户和集合隔离。
+添加对影响性能的操作的审计日志。
+实施速率限制以防止对昂贵操作的滥用。
+
+## 性能考虑
+
+### 预期的性能提升
+
+**查询减少：**
+<<<<<<< HEAD
+当前：典型请求需要 ~9,000+ 次查询。
+优化后：~50-100 个批处理查询 (减少 98%)。
+=======
+当前：典型请求约 9,000+ 个查询。
+优化后：约 50-100 个批处理查询 (减少 98%)。
+>>>>>>> 82edf2d (New md files from RunPod)
+
+**响应时间改进：**
+图遍历：15-20 秒 → 3-5 秒 (快 4-5 倍)。
+标签解析：8-12 秒 → 2-4 秒 (快 3 倍)。
+总体查询：25-35 秒 → 6-10 秒 (提升 3-4 倍)。
+
+**内存效率：**
+限制的缓存大小可防止内存泄漏。
+<<<<<<< HEAD
+高效的数据结构可减少内存占用 ~40%。
+=======
+高效的数据结构可将内存占用减少约 40%。
+>>>>>>> 82edf2d (New md files from RunPod)
+通过适当的资源清理实现更好的垃圾回收。
+
+**现实的性能期望：**
+**标签缓存**：对于具有常见关系的图，查询减少 10-20%。
+**批处理优化**：查询减少 50-80% (主要优化)。
+**对象生命周期优化**：消除每个请求的创建开销。
+**总体改进**：主要通过批处理实现响应时间提升 3-4 倍。
+
+**可扩展性改进：**
+支持 3-5 倍更大的知识图 (受缓存一致性需求限制)。
+3-5 倍更高的并发请求容量。
+通过连接重用实现更好的资源利用率。
+
+### 性能监控
+
+**实时指标：**
+按操作类型划分的查询执行时间。
+缓存命中率和有效性。
+数据库连接池利用率。
+内存使用情况和垃圾回收影响。
+
+<<<<<<< HEAD
+**性能基准测试 (Xìngnéng Jīzhǔ Cèshì):**
+自动化性能回归测试 (Zìdònghuà xìngnéng huíguī cèshì)
+使用真实数据量的负载测试 (Shǐyòng zhēnshí shùjùliàng de fùzài cèshì)
+与当前实现相比的基准测试 (Yǔ xiàncái shíxiàn xiāngbǐ de jīzhǔ cèshì)
+=======
+**性能基准测试:**
+自动化性能回归测试
+使用真实数据量的负载测试
+与当前实现相比的基准测试
+>>>>>>> 82edf2d (New md files from RunPod)
+
+## 测试策略 (Cèshì Cèlüè)
+
+<<<<<<< HEAD
+### 单元测试 (Dānyuán Cèshì)
+对遍历、缓存和标签解析等各个组件进行单独测试 (Duì biànlì, cáichǔ hé biāoqiān jiěshì děng gège zǔjiàn jìnxíng dānduǒ cèshì)
+模拟数据库交互以进行性能测试 (Mónǐ shùjùkù jiāohù yǐ jìnxíng xìngnéng cèshì)
+缓存驱逐和 TTL 过期测试 (Cáichǔ qūzhí hé TTL guòqí cèshì)
+错误处理和超时场景测试 (Cuòwù chǔlǐ hé chāoshí chǎngjǐng cèshì)
+
+### 集成测试 (Jíchéng Cèshì)
+使用优化后的 GraphRAG 查询的端到端测试 (Shǐyòng yōuhuà hòu de GraphRAG shōuchá de duān dào duān cèshì)
+使用真实数据的数据库交互测试 (Shǐyòng zhēnshí shùjù de shùjùkù jiāohù cèshì)
+并发请求处理和资源管理测试 (Bìngfā qǐngqiú chǔlǐ hé zīyuán guǎnlǐ cèshì)
+内存泄漏检测和资源清理验证 (Nèicún liūlèi jiǎncè hé zīyuán qīnglǐ yànzhèng)
+
+### 性能测试 (Xìngnéng Cèshì)
+与当前实现相比的基准测试 (Yǔ xiàncái shíxiàn xiāngbǐ de jīzhǔ cèshì)
+使用不同大小和复杂度的图的负载测试 (Shǐyòng bùtóng dàxiǎo hé fùzá dù de tú de fùzài cèshì)
+压力测试以确定内存和连接限制 (Yālì cèshì yǐ quèdìng nèicún hé liánjiē xiànzhì)
+用于性能改进的回归测试 (Yòng yú xìngnéng gǎijìn de huíguī cèshì)
+
+### 兼容性测试 (Jiānróng Xìng Cèshì)
+验证现有 GraphRAG API 的兼容性 (Yànzhèng xiàn yǒu GraphRAG API de jiānróng xìng)
+使用各种图数据库后端进行测试 (Shǐyòng gè zhǒng tú shùjùkù hòudùàn jìnxíng cèshì)
+验证与当前实现相比的结果准确性 (Yànzhèng yǔ xiàncái shíxiàn xiāngbǐ de jiéguǒ zhǔnquè xìng)
+=======
+### 单元测试
+对遍历、缓存和标签解析的各个组件进行测试
+模拟数据库交互以进行性能测试
+缓存驱逐和 TTL 过期测试
+错误处理和超时场景
+
+### 集成测试
+使用优化后的 GraphRAG 查询进行端到端测试
+使用真实数据进行数据库交互测试
+并发请求处理和资源管理
+内存泄漏检测和资源清理验证
+
+### 性能测试
+与当前实现相比的基准测试
+使用不同大小和复杂度的图进行负载测试
+压力测试以检查内存和连接限制
+针对性能改进进行的回归测试
+
+### 兼容性测试
+验证现有 GraphRAG API 的兼容性
+使用各种图数据库后端进行测试
+验证与当前实现相比的结果准确性
+>>>>>>> 82edf2d (New md files from RunPod)
+
+## 实施计划 (Shíshī Jìhuà)
+
+<<<<<<< HEAD
+### 直接实施方法 (Zhíjiē Shíshī Fāngfǎ)
+由于允许 API 更改，因此在不引入迁移复杂性的情况下，直接实施优化：(Yóuyú yǔnxǔ API gēnggǎi, yīncǐ zài bù yǐnrù qiān yí fùzá xìng de qíngkuàng xià, zhíjiē shíshī yōuhuà:)
+
+1. **替换 `follow_edges` 方法**: 使用迭代批量遍历重写 (Tiānyuē `follow_edges` fāngfǎ: Shǐyòng diànxìng pīliàng biànlì chóngxīn xiě)
+2. **优化 `get_labelgraph`**: 实施并行标签解析 (Yōuhuà `get_labelgraph`: Shíshī bìngxíng biāoqiān jiěshì)
+3. **添加长期 GraphRag**: 修改处理器以维护持久实例 (Tiānjiā chángqí GraphRag: Gǎixiāng chǔlǐ qì yǐ wéihù chíjiǔ yǐnshì)
+4. **实施标签缓存**: 为 GraphRag 类添加 LRU 缓存和 TTL (Shíshī biāoqiān cáichǔ: Wèi GraphRag lèi tiānjiā LRU cáichǔ hé TTL)
+
+### 变更范围 (Biàngēng Fànwéi)
+**查询类 (Query Class)**: 替换 `follow_edges` 中的 ~50 行代码，添加 ~30 行批量处理代码 (Tiānyuē `follow_edges` zhōng de ~50 háng dàimǎ, tiānjiā ~30 háng pīliàng chǔlǐ dàimǎ)
+**GraphRag 类 (GraphRag Class)**: 添加缓存层 (~40 行代码) (Tiānjiā cáichǔ céng (~40 háng dàimǎ))
+**处理器类 (Processor Class)**: 修改为使用持久的 GraphRag 实例 (~20 行代码) (Gǎixiāng wéi shǐyòng chíjiǔ de GraphRag yǐnshì (~20 háng dàimǎ))
+**总计 (Zǒngjì)**: ~140 行专注于的变更，主要在现有类中 (~140 háng zhuānzhù yú de biàngēng, zhǔyào zài xiàn yǒu lèi zhōng)
+=======
+### 直接实施方法
+由于允许 API 更改，因此无需迁移复杂性，可以直接实现优化：
+
+1. **替换 `follow_edges` 方法**: 使用迭代批量遍历重写
+2. **优化 `get_labelgraph`**: 实现并行标签解析
+3. **添加长期 GraphRag**: 修改 Processor 以维护持久实例
+4. **实现标签缓存**: 为 GraphRag 类添加 LRU 缓存和 TTL
+
+### 变更范围
+**查询类**: 替换 `follow_edges` 中的约 50 行代码，添加约 30 行批量处理代码
+**GraphRag 类**: 添加缓存层（约 40 行代码）
+**Processor 类**: 修改为使用持久的 GraphRag 实例（约 20 行代码）
+**总计**: 约 140 行代码的集中性变更，主要在现有类中
+>>>>>>> 82edf2d (New md files from RunPod)
+
+## 时间线 (Shíjiān Xiàn)
+
+<<<<<<< HEAD
+**第一周: 核心实施 (Dì Yī Zhōu: Héxīn Shíshī)**
+使用批量迭代遍历替换 `follow_edges` (Shǐyòng pīliàng diànxìng biànlì tiānyuē `follow_edges`)
+在 `get_labelgraph` 中实施并行标签解析 (Zài `get_labelgraph` zhōng shíshī bìngxíng biāoqiān jiěshì)
+向处理器添加长期 GraphRag 实例 (Xiàng chǔlǐ qì tiānjiā chángqí GraphRag yǐnshì)
+实施标签缓存层 (Shíshī biāoqiān cáichǔ céng)
+
+**第二周: 测试和集成 (Dì Èr Zhōu: Cèshì hé Jíchéng)**
+对新的遍历和缓存逻辑进行单元测试 (Duì xīn de biànlì hé cáichǔ luójí jìnxíng dānyuán cèshì)
+与当前实现相比进行性能基准测试 (Yǔ xiàncái shíxiàn xiāngbǐ jìnxíng xìngnéng jīzhǔ cèshì)
+使用真实图数据进行集成测试 (Shǐyòng zhēnshí tú shùjù jìnxíng jíchéng cèshì)
+代码审查和优化 (Dàimǎ shěnchá hé yōuhuà)
+
+**第三周: 部署 (Dì Sān Zhōu: Bùshǔ)**
+部署优化后的实现 (Bùshǔ yōuhuà hòu de shíshī)
+监控性能改进 (Jiānkòng xìngnéng gǎijìn)
+根据实际使用情况微调缓存 TTL 和批量大小 (Gēnjù shíjì shǐyòng qíngkuàng wēitiáo cáichǔ TTL hé pīliàng dàxiǎo)
+=======
+**第一周：核心实施**
+使用批量迭代遍历替换 `follow_edges`
+在 `get_labelgraph` 中实现并行标签解析
+在 Processor 中添加长期 GraphRag 实例
+实现标签缓存层
+
+**第二周：测试和集成**
+对新的遍历和缓存逻辑进行单元测试
+与当前实现相比的性能基准测试
+使用真实图数据的集成测试
+代码审查和优化
+
+**第三周：部署**
+部署优化的实现
+监控性能改进
+根据实际使用情况微调缓存 TTL 和批次大小
+>>>>>>> 82edf2d (New md files from RunPod)
+
+## 开放性问题 (Kāifàng Xìng Wèntí)
+
+<<<<<<< HEAD
+**数据库连接池 (Shùjùkù Liánjiē Chí)**: 我们应该实施自定义连接池，还是依赖于现有的数据库客户端连接池？(Wǒmen yīnggāi shíshī zìdìngyì liánjiē chí, háishì yīlài yú xiàn yǒu de shùjùkù kèfāngliánjiē chí?)
+**缓存持久性 (Cáichǔ Chíjiǔ Xìng)**: 标签和嵌入式缓存是否应该在服务重启后持久存在？(Biāoqiān hé qiànrùshì cáichǔ shìfǒu yīnggāi zài fúwù chóngqí hòu chíjiǔ cúnzài?)
+**分布式缓存 (Fēn Bùshì Cáichǔ)**: 对于多实例部署，我们是否应该实施具有 Redis/Memcached 的分布式缓存？(Duìyú duō yǐnshì bùshǔ, wǒmen shìfǒu yīnggāi shíshī yǒuyú Redis/Memcached de fēn bùshì cáichǔ?)
+**查询结果格式 (Shōuchá Jiéguǒ Géshì)**: 我们是否应该优化内部三元组表示以获得更好的内存效率？(Wǒmen shìfǒu yīnggāi yōuhuà nèibù sān yuánzǔ biǎoshì yǐ huòdé gèng hǎo de nèicún xiàolǜ?)
+**监控集成 (Jiānkòng Jíchéng)**: 哪些指标应该暴露给现有的监控系统（Prometheus 等）？(Nǎxiē zhǐbiāo yīnggāi bàolù gěi xiàn yǒu de jiānkòng xìtǒng (Prometheus děng)?)
+
+## 参考文献 (Cānkǎo Z tàiliào)
+
+GraphRAG API 文档 (GraphRAG API 文档)
+示例代码 (Lìmiàn dàimǎ)
+相关论文 (Xiāngguān lùnwén)
+=======
+**数据库连接池**: 我们应该实现自定义连接池，还是依赖于现有的数据库客户端池？
+**缓存持久性**: 标签和嵌入式缓存是否应该在服务重启后持久存在？
+**分布式缓存**: 对于多实例部署，我们是否应该实现使用 Redis/Memcached 的分布式缓存？
+**查询结果格式**: 我们是否应该优化内部三元组表示以获得更好的内存效率？
+**监控集成**: 哪些指标应该暴露给现有的监控系统（Prometheus 等）？
+
+## 参考文献
+
+[GraphRAG 原始实现](trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py)
+[TrustGraph 架构原则](architecture-principles.md)
+[集合管理规范](collection-management.md)
+>>>>>>> 82edf2d (New md files from RunPod)