Skip to content

CACHE_MODULE_GUIDE.md

Latest commit

 

History

History
316 lines (241 loc) · 8.47 KB

CACHE_MODULE_GUIDE.md

File metadata and controls

316 lines (241 loc) · 8.47 KB
Raw

本地緩存模塊使用指南

概述

本地緩存模塊為增強版RAG系統提供了高效的緩存功能，可以顯著提升重複分析相同項目時的執行速度。緩存模塊會自動檢測項目變化，並在項目未發生變化時從緩存加載結果，避免重複分析。

主要功能

1. 智能緩存管理

  • 自動項目哈希計算: 基於項目結構和關鍵文件內容生成唯一哈希
  • 緩存有效性檢查: 自動檢測項目變化，確保緩存數據的時效性
  • TTL支持: 支持設置緩存生存時間，自動清理過期緩存
  • 統計信息: 提供詳細的緩存命中率、使用情況統計

2. 緩存類型支持

  • 分析結果緩存: RAG分析報告
  • 處理結果緩存: 數據處理結果
  • 學習結果緩存: 智能學習結果
  • 決策結果緩存: 判斷決策結果

3. 緩存管理功能

  • 緩存查詢: 根據項目路徑和緩存類型查詢緩存
  • 緩存設置: 將分析結果保存到緩存
  • 緩存清理: 支持按項目或類型清理緩存
  • 緩存統計: 查看緩存使用情況和命中率

安裝和使用

基本使用

from modules.cache_manager import CacheManager, CachedRAGAnalyzer

# 創建緩存管理器（默認緩存目錄：~/.cache/rag-system）
cache_manager = CacheManager()

# 使用帶緩存的RAG分析器
cached_analyzer = CachedRAGAnalyzer("/path/to/your/project", cache_manager)

# 生成分析報告（自動使用緩存）
report = cached_analyzer.generate_analysis_report()

命令行測試

# 測試緩存管理器
python3 test_cache_module.py

# 測試緩存模塊
python3 modules/cache_manager.py /path/to/test/project

API 參考

CacheManager 類

初始化

CacheManager(cache_dir=None, ttl_hours=24)
  • cache_dir: 緩存目錄路徑（默認：~/.cache/rag-system）
  • ttl_hours: 緩存生存時間（小時，默認24小時）

主要方法

獲取緩存數據

get(project_path: str, cache_type: str) -> Optional[Dict[str, Any]]
  • project_path: 項目路徑
  • cache_type: 緩存類型（analysis, processing, learning, decision）
  • 返回值：緩存數據或None（如果未命中）

設置緩存數據

set(project_path: str, cache_type: str, data: Dict[str, Any]) -> bool
  • project_path: 項目路徑
  • cache_type: 緩存類型
  • data: 要緩存的數據
  • 返回值：是否成功

刪除緩存

delete(project_path: str = None, cache_type: str = None) -> int
  • project_path: 項目路徑（None表示所有項目）
  • cache_type: 緩存類型（None表示所有類型）
  • 返回值：刪除的緩存數量

清空所有緩存

clear() -> int
  • 返回值：刪除的緩存文件數量

獲取統計信息

get_stats() -> Dict[str, Any]
  • 返回值：包含緩存統計信息的字典

列出緩存項目

list_cached_projects() -> List[Dict[str, Any]]
  • 返回值：緩存的項目列表

CachedRAGAnalyzer 類

初始化

CachedRAGAnalyzer(project_path: str, cache_manager: CacheManager = None)
  • project_path: 項目路徑
  • cache_manager: 緩存管理器實例（默認創建新的）

主要方法

生成分析報告（帶緩存）

generate_analysis_report(use_cache: bool = True) -> Dict[str, Any]
  • use_cache: 是否使用緩存（默認True）
  • 返回值：分析報告

保存報告（同時更新緩存）

save_report(report: Dict[str, Any], output_path: str = None) -> str
  • report: 分析報告
  • output_path: 輸出文件路徑
  • 返回值：保存的文件路徑

集成到現有系統

1. 修改現有模塊使用緩存

在現有模塊中添加緩存支持：

from modules.cache_manager import CacheManager

class YourModule:
    def __init__(self, project_path: str):
        self.project_path = project_path
        self.cache_manager = CacheManager()
    
    def your_method(self, use_cache=True):
        if use_cache:
            cached_data = self.cache_manager.get(self.project_path, "your_cache_type")
            if cached_data is not None:
                print("✅ 從緩存加載數據")
                return cached_data
        
        # 執行實際操作
        result = self._do_actual_work()
        
        # 保存到緩存
        if use_cache:
            self.cache_manager.set(self.project_path, "your_cache_type", result)
            print("💾 數據已緩存")
        
        return result

2. 創建帶緩存的增強版系統

參考 main_enhanced.py 創建帶緩存的版本：

class EnhancedRAGSystemWithCache:
    def __init__(self, project_path: str, enable_cache: bool = True):
        self.project_path = project_path
        self.enable_cache = enable_cache
        self.cache_manager = CacheManager() if enable_cache else None
    
    def run_analysis(self):
        # 每個階段都檢查緩存
        if self.enable_cache:
            cached_data = self.cache_manager.get(self.project_path, "analysis")
            if cached_data:
                return cached_data
        
        # 執行分析並緩存結果
        result = self._do_analysis()
        
        if self.enable_cache:
            self.cache_manager.set(self.project_path, "analysis", result)
        
        return result

緩存策略

1. 緩存鍵生成

緩存鍵由以下部分組成：

  • 緩存類型（analysis, processing, learning, decision）
  • 項目路徑哈希（前12個字符）
  • 項目內容哈希（基於關鍵文件和目錄結構）

2. 項目哈希計算

項目哈希基於：

  • 關鍵文件（package.json, README.md, tsconfig.json等）的修改時間和大小
  • 目錄結構（前兩層）
  • 文件列表（前20個文件）

3. 緩存失效策略

  • TTL過期: 緩存超過設定的生存時間後自動失效
  • 項目變化: 項目哈希變化時緩存自動失效
  • 手動清理: 可以手動清理特定項目或類型的緩存

性能優化建議

1. 調整TTL設置

根據項目更新頻率調整緩存生存時間：

# 頻繁更新的項目：較短的TTL
cache_manager = CacheManager(ttl_hours=6)

# 穩定的項目：較長的TTL
cache_manager = CacheManager(ttl_hours=72)

2. 緩存目錄優化

  • 使用SSD存儲提升緩存讀寫速度
  • 定期清理過期緩存釋放磁盤空間
  • 考慮使用內存緩存（如Redis）提升性能

3. 監控緩存使用

定期檢查緩存統計，優化緩存策略：

stats = cache_manager.get_stats()
print(f"命中率: {stats['hit_rate_percent']}%")
print(f"緩存大小: {stats['total_size_mb']:.2f} MB")

故障排除

常見問題

1. 緩存未命中率過高

  • 檢查項目是否頻繁變化
  • 確認緩存鍵生成邏輯是否正確
  • 檢查緩存目錄權限

2. 緩存數據過期

  • 調整TTL設置
  • 實現手動緩存刷新機制
  • 添加緩存版本控制

3. 緩存目錄空間不足

  • 定期清理過期緩存
  • 設置緩存大小限制
  • 使用外部存儲服務

調試方法

# 啟用詳細日誌
import logging
logging.basicConfig(level=logging.DEBUG)

# 檢查緩存狀態
cache_manager = CacheManager()
print("緩存目錄:", cache_manager.cache_dir)
print("索引文件:", cache_manager.index_file)

# 手動清理緩存
deleted = cache_manager.clear()
print(f"清理了 {deleted} 個緩存文件")

最佳實踐

  1. 漸進式集成: 先在非關鍵模塊測試緩存功能
  2. 監控緩存命中率: 確保緩存帶來性能提升
  3. 定期維護: 清理過期緩存，優化緩存策略
  4. 備份重要數據: 緩存不應替代持久化存儲
  5. 測試緩存失效: 確保項目變化時緩存正確失效

擴展開發

添加新的緩存類型

  1. 在 _generate_cache_key 方法中添加新的緩存類型
  2. 創建對應的緩存管理方法
  3. 在相關模塊中集成新緩存類型

支持分布式緩存

  1. 實現緩存接口抽象
  2. 添加Redis、Memcached等后端支持
  3. 實現緩存同步機制

添加緩存壓縮

  1. 實現數據壓縮/解壓方法
  2. 添加壓縮選項配置
  3. 優化大數據緩存性能

版本歷史

v1.0.0 (初始版本)

  • 基礎緩存管理器實現
  • 支持四種緩存類型
  • TTL過期機制
  • 詳細統計信息

v1.1.0 (計劃中)

  • 緩存壓縮支持
  • 分布式緩存后端
  • 緩存預熱功能
  • 性能監控儀表板

注意: 緩存模塊旨在提升重複分析性能，但不應替代持久化存儲。重要數據請確保有備份機制。