Skip to content

INDEXING_GUIDE.md

Latest commit

 

History

History
275 lines (197 loc) · 8.76 KB

INDEXING_GUIDE.md

File metadata and controls

275 lines (197 loc) · 8.76 KB

📚 Руководство по индексации базы знаний Biotact

🎯 Обзор

Система индексации автоматически обрабатывает документы из директории data/documents/ и создает векторные представления для RAG системы.

📁 Структура директорий

biotact-production/
├── data/
│   ├── documents/              # 👈 ОСНОВНАЯ ДИРЕКТОРИЯ ДЛЯ ЗАГРУЗКИ
│   │   ├── *.md               # Markdown файлы
│   │   └── *.txt              # Текстовые файлы
│   └── .index_state.json      # Состояние индексации (автоматически)
├── scripts/
│   └── incremental_index.py   # 🚀 ГЛАВНЫЙ СКРИПТ ИНДЕКСАЦИИ
└── docs/
    └── INDEXING_GUIDE.md      # Этот файл

🚀 Основной скрипт: incremental_index.py

Что делает:

✅ Инкрементальная индексация - индексирует только новые и измененные файлы ✅ Автоматическое отслеживание - запоминает hash каждого файла ✅ Экономия ресурсов - не тратит деньги на переиндексацию существующих файлов ✅ Удаление устаревших - автоматически удаляет векторы для удаленных файлов ✅ Обновление измененных - перезаписывает векторы для отредактированных файлов

Как использовать:

# Перейти в директорию проекта
cd /home/temrjan/project/biotact-production

# Запустить индексацию
venv/bin/python scripts/incremental_index.py

Пример вывода:

🚀 Инкрементальная индексация Biotact Knowledge Base
============================================================

📋 Шаг 1: Инициализация...
✅ Коллекция 'biotact_knowledge_v3' уже существует

📋 Шаг 2: Анализ изменений...

📊 Статистика изменений:
  ✅ Без изменений: 3
  🆕 Новые файлы: 1
  📝 Изменены: 0
  🗑️  Удалены: 0

🔄 Индексация 1 файлов...

🆕 НОВЫЙ: new_document.md
  📄 Индексирую 'new_document.md'...

✅ Добавлено 5 новых векторов

💾 Сохранение состояния...

============================================================
✅ ИНДЕКСАЦИЯ ЗАВЕРШЕНА
============================================================

📊 Итоговая статистика коллекции:
  - Всего файлов: 4
  - Всего векторов: 36
  - Статус коллекции: green
  - Размер векторов: 3072

📖 Сценарии использования

1️⃣ Добавление нового документа

# 1. Загрузи файл в директорию
scp новый_файл.md user@server:/home/temrjan/project/biotact-production/data/documents/

# 2. Запусти индексацию
cd /home/temrjan/project/biotact-production
venv/bin/python scripts/incremental_index.py

Результат: Будет проиндексирован только новый файл ✅

2️⃣ Обновление существующего документа

# 1. Отредактируй файл
nano /home/temrjan/project/biotact-production/data/documents/existing_file.md

# 2. Запусти индексацию
venv/bin/python scripts/incremental_index.py

Результат:

  • Старые векторы удалятся 🗑️
  • Новые векторы создадутся ✅

3️⃣ Удаление документа

# 1. Удали файл
rm /home/temrjan/project/biotact-production/data/documents/old_file.md

# 2. Запусти индексацию
venv/bin/python scripts/incremental_index.py

Результат: Векторы для этого файла удалятся из Qdrant 🗑️

4️⃣ Массовое добавление файлов

# 1. Загрузи несколько файлов
scp *.md user@server:/home/temrjan/project/biotact-production/data/documents/

# 2. Запусти индексацию ОДИН РАЗ
venv/bin/python scripts/incremental_index.py

Результат: Все новые файлы проиндексируются за один проход ✅

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

Поддерживаемые форматы:

  • .md - Markdown
  • .txt - Plain text

Параметры индексации:

Chunk size:     1024 токенов
Chunk overlap:  200 токенов
Embedding:      text-embedding-3-large (OpenAI)
Dimensions:     3072
Distance:       Cosine
Collection:     biotact_knowledge_v3

Хранение состояния:

Файл data/.index_state.json содержит:

{
  "filename.md": {
    "hash": "abc123...",
    "path": "/full/path/to/file",
    "size": 12345,
    "modified": 1234567890.123,
    "indexed_at": "2024-11-20T04:30:00"
  }
}

⚠️ Важные замечания

✅ НУЖНО делать:

  • Загружать файлы в data/documents/
  • Запускать incremental_index.py после изменений
  • Использовать .md или .txt форматы

❌ НЕ НУЖНО делать:

  • Не редактируй .index_state.json вручную
  • Не удаляй файлы напрямую из Qdrant
  • Не запускай несколько индексаций параллельно

🆘 Решение проблем

Проблема: "No files found"

Решение: Проверь что файлы находятся в data/documents/ и имеют расширение .md или .txt

Проблема: "Collection doesn't exist"

Решение: Скрипт автоматически создаст коллекцию при первом запуске

Проблема: Индексация зависает

Решение:

  1. Проверь доступность Qdrant: curl http://localhost:6333/collections
  2. Проверь API ключ OpenAI в .env
  3. Проверь лог ошибок

Проблема: "OpenAI API error"

Решение:

  1. Проверь баланс на счету OpenAI
  2. Проверь правильность API ключа в .env
  3. Проверь интернет соединение

💰 Стоимость индексации

Модель: text-embedding-3-large

  • Цена: $0.13 за 1 млн токенов
  • Средний документ: ~1000 токенов
  • 1000 документов: ~$0.13

Экономия с инкрементальной индексацией:

Без инкрементальной:  $0.13 × количество запусков
С инкрементальной:    $0.13 × 1 раз (только новые файлы)

Экономия: 90-99% при частых обновлениях! 💰

📊 Мониторинг

Проверка состояния Qdrant:

curl http://localhost:6333/collections/biotact_knowledge_v3 | python3 -m json.tool

Проверка количества векторов:

curl -s http://localhost:6333/collections/biotact_knowledge_v3 | \
  python3 -c "import json, sys; print(f\"Векторов: {json.load(sys.stdin)['result']['points_count']}\")"

Просмотр состояния индексации:

cat /home/temrjan/project/biotact-production/data/.index_state.json | python3 -m json.tool

🔄 Автоматизация (опционально)

Cron job для автоматической индексации:

# Редактировать crontab
crontab -e

# Добавить задачу (каждый час)
0 * * * * cd /home/temrjan/project/biotact-production && venv/bin/python scripts/incremental_index.py >> logs/indexing.log 2>&1

📞 Поддержка

При возникновении проблем:

  1. Проверь логи в терминале
  2. Проверь статус всех сервисов (Qdrant, PostgreSQL, FastAPI)
  3. Проверь конфигурацию в .env

Последнее обновление: 2024-11-20 Версия: 1.0 Автор: Biotact Team