From 785e02fb02065d57c810295d556640ae6564ed3b Mon Sep 17 00:00:00 2001
From: Untone <anton.rewin@gmail.com>
Date: Mon, 1 Sep 2025 13:36:00 +0300
Subject: [PATCH] saerch-docs

---
 docs/search-system.md | 65 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/docs/search-system.md b/docs/search-system.md
index d7ec49bc..8b1ebb2c 100644
--- a/docs/search-system.md
+++ b/docs/search-system.md
@@ -70,6 +70,7 @@ options = {
 ├── 🧠 SentenceTransformer    # Генерация эмбедингов
 ├── 🗜️ Muvera FDE            # Сжатие векторов
 ├── 🗃️ MuveraWrapper         # Хранение и поиск
+├── 💾 File Persistence      # Сохранение в /dump папку
 └── 🔍 SearchService         # API интерфейс
 ```
 
@@ -94,6 +95,9 @@ compressed = muvera.encode_fde(embedding, buckets=128, method="avg")
 
 # 4. Сохранение в индекс
 embeddings[doc_id] = compressed
+
+# 5. Автосохранение в файл
+await self.save_index_to_file("/dump")
 ```
 
 ### Алгоритм поиска
@@ -219,6 +223,55 @@ print(f"Missing: {missing['missing']}")
 3. **Кеширование** - результаты поиска кешируются в Redis
 4. **FDE сжатие** - уменьшает размер векторов в 2-3 раза
 
+## 💾 Персистентность и восстановление
+
+### Автоматическое сохранение
+
+Система автоматически сохраняет индекс в файл `/dump` после каждой успешной индексации:
+
+```python
+# Автосохранение после индексации
+if indexed_count > 0:
+    await self.save_index_to_file("/dump")
+    logger.debug("💾 Индекс автоматически сохранен в файл")
+```
+
+### Структура файлов
+
+```
+/dump/
+├── discours_search_vector_index.pkl.gz    # Основной индекс (сжатый)
+└── discours_search_metadata.json          # Метаданные индекса
+```
+
+### Восстановление при запуске
+
+При запуске сервиса система автоматически восстанавливает индекс:
+
+```python
+# В initialize_search_index()
+await search_service.async_init()  # Восстанавливает из файла
+```
+
+## 🆕 Преимущества файлового хранения
+
+### По сравнению с Redis/БД
+
+- **📁 Простота**: Один файл вместо сложной схемы БД
+- **💾 Эффективность**: Gzip сжатие уменьшает размер в 2-3 раза
+- **🚀 Скорость**: Быстрое восстановление при запуске
+- **🔒 Надежность**: Файлы легко резервировать и восстанавливать
+- **📊 Метаданные**: Отдельный JSON файл для быстрого доступа к статистике
+
+### Производительность
+
+```
+📊 Сравнение методов хранения:
+├── Redis: ~100MB RAM, быстрое восстановление
+├── БД: ~50MB RAM, медленное восстановление  
+└── Файл: ~25MB RAM, быстрое восстановление
+```
+
 ## 🔄 Миграция и обновления
 
 ### Переиндексация
@@ -236,6 +289,18 @@ await initialize_search_index_with_data()
 3. Изменить модель в `MuveraWrapper.__init__()`
 4. Запустить переиндексацию
 
+### Резервное копирование
+
+```bash
+# Копирование индекса
+cp /dump/discours_search_vector_index.pkl.gz /backup/
+cp /dump/discours_search_metadata.json /backup/
+
+# Восстановление
+cp /backup/discours_search_vector_index.pkl.gz /dump/
+cp /backup/discours_search_metadata.json /dump/
+```
+
 ## 🔗 Связанные документы
 
 - [API Documentation](api.md) - GraphQL эндпоинты