Import Vector lab project

2026-06-06 18:31:55 +00:00
commit fcc22063ed
105 changed files with 31639 additions and 0 deletions
@@ -0,0 +1,216 @@
+# Скрипт парсинга спецдонесений МЧС
+
+## Описание
+
+`parse_reports.py` - скрипт для автоматического извлечения структурированных данных из спецдонесений МЧС Беларуси в формате .docx с использованием Claude API.
+
+## Возможности
+
+- ✅ Чтение .docx файлов через python-docx
+- ✅ Извлечение 18 полей данных через Claude API
+- ✅ Оценка уверенности (confidence) для каждого поля
+- ✅ Автоматическая фильтрация по качеству данных
+- ✅ Сохранение в PostgreSQL (таблицы cases + raw_documents)
+- ✅ Режим dry-run для тестирования
+- ✅ Детальное логирование и отчеты
+
+## Извлекаемые поля
+
+1. `age_years` - возраст в годах
+2. `gender` - пол (мужской/женский)
+3. `has_diagnosis` - наличие диагноза/заболевания
+4. `diagnosis_type` - тип диагноза
+5. `has_transport` - наличие транспорта
+6. `season` - сезон (winter/spring/summer/autumn)
+7. `time_of_day` - время суток (morning/day/evening/night)
+8. `elapsed_before_report_h` - часов до сообщения
+9. `last_seen_direction` - направление последнего наблюдения
+10. `terrain_primary` - основной тип местности
+11. `water_nearby` - водоем рядом
+12. `road_nearby` - дорога рядом
+13. `found_alive` - найден живым
+14. `found_distance_km` - расстояние обнаружения (км)
+15. `found_direction` - направление обнаружения
+16. `found_location_type` - тип места обнаружения
+17. `search_duration_hours` - длительность поиска (часы)
+18. `who_found` - кто нашел
+
+Каждое поле имеет:
+- `value` - значение или null
+- `confidence` - уровень уверенности (high/medium/low)
+
+## Установка
+
+### 1. Создание таблиц в БД
+
+```bash
+cd /root/sar-mchs/scripts
+
+# Подключитесь к PostgreSQL и выполните:
+psql -U postgres -d sar_mchs -f create_tables.sql
+```
+
+Или через Docker:
+```bash
+docker exec -i sar-mchs-postgres psql -U postgres -d sar_mchs < create_tables.sql
+```
+
+### 2. Установка зависимостей
+
+Зависимости уже установлены в backend/requirements.txt:
+- python-docx
+- httpx
+- sqlalchemy[asyncio]
+- asyncpg
+
+### 3. Настройка переменных окружения
+
+```bash
+export ANTHROPIC_API_KEY="your_api_key_here"
+export DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/sar_mchs"
+```
+
+## Использование
+
+### Базовое использование
+
+```bash
+cd /root/sar-mchs/scripts
+
+# Dry-run (без записи в БД)
+python3 parse_reports.py --dir /path/to/docx/files --dry-run
+
+# Запись в БД
+python3 parse_reports.py \
+  --dir /path/to/docx/files \
+  --db "postgresql+asyncpg://postgres:postgres@localhost:5432/sar_mchs"
+```
+
+### Параметры
+
+- `--dir` (обязательный) - путь к папке с .docx файлами
+- `--db` (опциональный) - DATABASE_URL для PostgreSQL
+- `--dry-run` (флаг) - режим тестирования без записи в БД
+
+### Примеры
+
+**1. Тестовый запуск:**
+```bash
+python3 parse_reports.py --dir ./test_reports --dry-run
+```
+
+**2. Обработка с записью в БД:**
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+python3 parse_reports.py \
+  --dir /data/mchs_reports \
+  --db "postgresql+asyncpg://postgres:postgres@postgres:5432/sar_mchs"
+```
+
+**3. Обработка из Docker контейнера:**
+```bash
+docker exec -it sar-mchs-backend bash
+cd /app/scripts
+python3 parse_reports.py --dir /data/reports --db $DATABASE_URL
+```
+
+## Логика работы
+
+1. **Чтение файлов**: Сканирует директорию на наличие .docx файлов
+2. **Извлечение текста**: Использует python-docx для чтения содержимого
+3. **Анализ через Claude**: Отправляет текст в Claude API с промптом извлечения
+4. **Валидация**: Подсчитывает поля с high confidence
+5. **Фильтрация**: Пропускает файлы с < 6 полей high confidence
+6. **Сохранение**: Записывает в таблицы raw_documents и cases
+7. **Отчет**: Генерирует parse_report.json с детальной статистикой
+
+## Выходные данные
+
+### Консольный вывод
+
+```
+2026-05-01 10:15:23 - INFO - Найдено файлов: 15
+2026-05-01 10:15:23 - INFO - Режим: ЗАПИСЬ В БД
+2026-05-01 10:15:24 - INFO - Обработка: report_001.docx
+2026-05-01 10:15:28 - INFO -   Полей с high confidence: 12/18
+2026-05-01 10:15:29 - INFO - ✓ Сохранено в БД: report_001.docx (doc_id=1)
+...
+2026-05-01 10:20:15 - INFO - ============================================================
+2026-05-01 10:20:15 - INFO - ИТОГОВАЯ СТАТИСТИКА
+2026-05-01 10:20:15 - INFO - ============================================================
+2026-05-01 10:20:15 - INFO - Всего файлов: 15
+2026-05-01 10:20:15 - INFO - Успешно обработано: 12
+2026-05-01 10:20:15 - INFO - Пропущено (< 6 high conf): 2
+2026-05-01 10:20:15 - INFO - Ошибки: 1
+```
+
+### Файл отчета (parse_report.json)
+
+```json
+[
+  {
+    "file": "report_001.docx",
+    "status": "success",
+    "high_confidence_count": 12
+  },
+  {
+    "file": "report_002.docx",
+    "status": "skipped",
+    "reason": "Недостаточно полей с high confidence (4 < 6)",
+    "high_confidence_count": 4
+  }
+]
+```
+
+## Структура БД
+
+### Таблица raw_documents
+- `id` - первичный ключ
+- `filename` - имя файла
+- `raw_text` - исходный текст
+- `extracted_json` - JSON с извлеченными данными
+- `created_at`, `updated_at` - временные метки
+
+### Таблица cases
+- `id` - первичный ключ
+- `raw_document_id` - ссылка на raw_documents
+- 18 полей данных (см. выше)
+- `created_at`, `updated_at` - временные метки
+
+## Ограничения и рекомендации
+
+- **Rate limiting**: Скрипт делает паузу 1 секунду между запросами к Claude API
+- **Длина текста**: Ограничена 8000 символами для промпта
+- **Минимальный порог**: Файлы с < 6 полей high confidence пропускаются
+- **Стоимость**: Каждый файл = 1 запрос к Claude API (~$0.003-0.015 за файл)
+
+## Troubleshooting
+
+**Ошибка: "ANTHROPIC_API_KEY не установлен"**
+```bash
+export ANTHROPIC_API_KEY="your_key_here"
+```
+
+**Ошибка подключения к БД**
+```bash
+# Проверьте DATABASE_URL
+echo $DATABASE_URL
+
+# Проверьте доступность PostgreSQL
+docker exec sar-mchs-postgres pg_isready
+```
+
+**Файлы не найдены**
+```bash
+# Проверьте путь и наличие .docx файлов
+ls -la /path/to/docx/files/*.docx
+```
+
+## TODO
+
+- [ ] Добавить поддержку .pdf файлов
+- [ ] Batch обработка для снижения стоимости API
+- [ ] Retry логика при ошибках API
+- [ ] Прогресс-бар для больших объемов
+- [ ] Экспорт в CSV/Excel
+- [ ] Web-интерфейс для мониторинга