📚 Векторизация руководств 1Forma

Обзор

Система для семантического поиска по руководствам администратора и пользователя 1Forma.

Обрабатываемые документы:

• Admin.pdf — Руководство администратора (6331 стр, 396 МБ)
• User_Guide.pdf — Руководство пользователя (855 стр, 301 МБ)
• Maintenance.pdf — Руководство по техобслуживанию (553 стр, 62 МБ)

Технологии:

• PyMuPDF (fitz) — извлечение текста из PDF
• ChromaDB — векторная база данных (локально)
• OpenAI embeddings — text-embedding-3-small

---

🚀 Быстрый старт

1. Векторизация документов

# Активируем виртуальное окружение
source venv-vectorize/bin/activate

# Запускаем векторизацию (займёт 10-30 минут)
python3 vectorize_manuals.py

Скрипт обработает все три PDF постранично и создаст три коллекции:

• admin_manual — руководство администратора
• user_manual — руководство пользователя
• maintenance_manual — руководство по техобслуживанию

2. Поиск по документам

# Поиск в руководстве администратора
python3 query_docs.py "как настроить дополнительные поля"

# Поиск в руководстве пользователя
python3 query_docs.py "создание задачи" user_manual

# Поиск в руководстве по техобслуживанию
python3 query_docs.py "резервное копирование" maintenance_manual

# Получить больше результатов
python3 query_docs.py "виджеты портала" admin_manual 10

---

📁 Структура файлов

.
├── Admin.pdf                   # Исходное руководство администратора
├── User_Guide.pdf              # Исходное руководство пользователя
├── vectorize_manuals.py        # Скрипт векторизации
├── query_docs.py               # Скрипт поиска
├── venv-vectorize/             # Виртуальное окружение Python
├── chroma_db/                  # База векторов (создаётся автоматически)
│   ├── admin_manual/           # Коллекция руководства администратора
│   └── user_manual/            # Коллекция руководства пользователя
└── README_VECTORIZATION.md     # Этот файл

---

🔧 Технические детали

Обработка PDF

• Батчинг: по 100 страниц за раз
• Лимит текста: 8000 символов на страницу
• Пропуск: пустые страницы игнорируются
• Метаданные: источник, номер страницы, общее количество

Векторные эмбеддинги

• Модель: intfloat/multilingual-e5-large
• Причина: отличная поддержка русского языка
• Размерность: 1024
• Метрика: косинусная близость

База данных

• Тип: ChromaDB (SQLite + HNSW индекс)
• Расположение: ./chroma_db/
• Персистентность: данные сохраняются на диск

---

💡 Примеры использования

Python API

import chromadb
from chromadb.utils import embedding_functions

# Подключаемся к базе
ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="intfloat/multilingual-e5-large"
)
client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_collection(name="admin_manual", embedding_function=ef)

# Поиск
results = collection.query(
    query_texts=["настройка пользователей"],
    n_results=5
)

for doc, meta in zip(results['documents'][0], results['metadatas'][0]):
    print(f"Страница {meta['page']}: {doc[:200]}...")

CLI

# Список коллекций
python3 -c "import chromadb; print([c.name for c in chromadb.PersistentClient(path='./chroma_db').list_collections()])"

# Количество документов
python3 -c "import chromadb; c = chromadb.PersistentClient(path='./chroma_db').get_collection('admin_manual'); print(c.count())"

---

⚡ Производительность

Векторизация:

• Admin.pdf (6331 стр): ~20-25 минут
• User_Guide.pdf (855 стр): ~3-5 минут
• Maintenance.pdf (553 стр): ~2-3 минуты
• Общее время: ~27-33 минуты

Поиск:

• Латентность: 100-300 мс на запрос
• Throughput: ~5-10 запросов в секунду

Память:

• Векторизация: ~4-6 ГБ RAM
• Поиск: ~2-3 ГБ RAM

---

🛠 Обслуживание

Повторная векторизация

# Удалить старую базу
rm -rf chroma_db/

# Запустить заново
python3 vectorize_manuals.py

Обновление одной коллекции

import chromadb

client = chromadb.PersistentClient(path="./chroma_db")
client.delete_collection(name="admin_manual")  # Удалить только admin_manual

Бэкап базы

# Создать архив
tar -czf chroma_db_backup_$(date +%Y%m%d).tar.gz chroma_db/

# Восстановить
tar -xzf chroma_db_backup_20260214.tar.gz

---

🐛 Устранение неполадок

Ошибка: "Collection not found"

# Проверить доступные коллекции
python3 -c "import chromadb; print(chromadb.PersistentClient(path='./chroma_db').list_collections())"

Ошибка: "Out of memory"

Уменьшить batch_size в vectorize_manuals.py:

batch_size = 50  # было 100

Низкая релевантность результатов

• Увеличить n_results для получения большего количества результатов
• Попробовать переформулировать запрос
• Использовать ключевые слова из документации

---

📊 Статистика

После векторизации вы получите:

• admin_manual: ~6200 документов (непустые страницы)
• user_manual: ~850 документов
• maintenance_manual: ~550 документов
• Размер базы: ~3-4 ГБ на диске
• Время индексации: ~27-33 минуты

---

🔐 Безопасность

• Все данные хранятся локально
• Нет отправки данных на внешние серверы
• Модель эмбеддингов загружается один раз и кэшируется

---

📝 Лицензия

Скрипты: MIT
Документация 1Forma: собственность правообладателя