framework-caching

--- name: framework-caching description: "Кеширование PDF Vector Framework (семантический/embedding/HTTP cache). ТОЛЬКО при: семантический кеш pdf-framework, embedding cache pdf-framework, cache stats pdf-framework, очистить кеш pdf-framework. НЕ для оптимизации поиска (→ search-pipeline-debug), НЕ для 1С, НЕ для Claude Code, НЕ для LangChain." --- # Framework Caching ## Когда использовать - "кеш", "кэш", "cache", "TTL" - "семантический кеш", "semantic cache" - "очистить кеш", "cache stats", "cache clear" - "медленный поиск", "ускорить", "повторный запрос" --- ## 3 уровня кеша | Уровень | Что кеширует | Ускорение | Настройка | |---------|-------------|-----------|-----------| | **Семантический** | Результаты поиска (cosine ≥ 0.95) | 5-30 с → < 1 мс | `CACHE__SEMANTIC_ENABLED=true` | | **Embedding** | Vectorы запросов (LRU) | 415-475 мс → < 1 мс | `CACHE__EMBEDDING_ENABLED=true` | | **LLM** | Ответы LLM (hash-based) | 3-30 с → < 1 мс | `CACHE__LLM_ENABLED=true` | --- ## Семантический кеш Сохраняет результаты поиска и возвращает для **похожих** запросов: ``` "конфигуратор в 1С Предприятие" → embedding → cosine similarity с кешем → "конфигуратор 1С" (similarity 0.97 > 0.95) → HIT → < 1 мс ``` ### Настройка ```env CACHE__SEMANTIC_ENABLED=true CACHE__SEMANTIC_THRESHOLD=0.95 # Cosine similarity порог CACHE__SEMANTIC_TTL=3600 # TTL в секундах (1 час) ``` ### Автоматическая инвалидация Кеш очищается при: - Переиндексации документа - Удалении документа - Ручной очистке через API/CLI/UI --- ## Embedding кеш LRU кеш embedding-векторов запросов: ``` Запрос → embedding model → 1024d vector (415-475 мс) Повторный запрос → LRU cache hit → 1024d vector (< 1 мс) ``` ```env CACHE__EMBEDDING_ENABLED=true ``` --- ## LLM кеш Кеш ответов LLM по хешу запроса + стратегии + контекста: ``` Ключ = hash(query + strategy + context_hash) → Есть в кеше? → мгновенный возврат → Нет? → LLM генерация → сохранение ``` ```env CACHE__LLM_ENABLED=true ``` --- ## Управление кешем ### CLI ```bash # Статистика pdf-framework cache stats # → Embedding: 156 entries, 23% hit rate # → LLM: 42 entries, 67% hit rate # Очистить LLM кеш pdf-framework cache clear --type llm # Очистить embedding кеш pdf-framework cache clear --type embedding # Очистить весь кеш pdf-framework cache clear --type all ``` ### API ```bash # Статистика curl http://localhost:8000/cache/stats # Очистка curl -X DELETE http://localhost:8000/cache/clear ``` ### Python API ```python from src.pdf_framework.search.semantic_cache import SemanticCache cache = SemanticCache(threshold=0.95, ttl=3600) # Проверить кеш cached = await cache.get(query="конфигуратор 1С", strategy="hybrid") if cached: return cached # < 1 мс # Сохранить в кеш await cache.put( query="конфигуратор 1С", strategy="hybrid", response=search_response, ) ``` --- ## Contextual Retrieval Cache (Phase 50) Кеш LLM-generated context summaries для Contextual Retrieval: ``` Chunk → hash(content) → SQLite cache → Есть? → мгновенный возврат context summary → Нет? → LLM генерация → сохранение ``` Экономит **~90% LLM вызовов** при повторной индексации (контекст не меняется для неизменённых чанков). Файл: `src/pdf_framework/processing/context_generator.py` --- ## Рекомендации | Сценарий | Рекомендация | |----------|-------------| | Development / отладка | Отключить все кеши, чтобы видеть реальные результаты | | Production | Включить все 3 уровня | | После переиндексации | Семантический кеш инвалидируется автоматически | | Изменили промпт / стратегию | `pdf-framework cache clear --type all` | | Низкий hit rate | Понизить `SEMANTIC_THRESHOLD` (0.90) | --- ## Связанные скиллы - `framework-config` — все .env параметры кеша - `framework-cli` — CLI команды cache - `framework-api` — REST endpoints кеша - `framework-troubleshooting` — проблемы производительности ## Файлы - Semantic Cache: `src/pdf_framework/search/semantic_cache.py` - Cache Config: `src/pdf_framework/config/cache.py`