vector/scripts

Скрипт парсинга спецдонесений МЧС

Описание

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. Создание таблиц в БД

cd /root/sar-mchs/scripts

# Подключитесь к PostgreSQL и выполните:
psql -U postgres -d sar_mchs -f create_tables.sql

Или через Docker:

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. Настройка переменных окружения

export ANTHROPIC_API_KEY="your_api_key_here"
export DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/sar_mchs"

Использование

Базовое использование

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. Тестовый запуск:

python3 parse_reports.py --dir ./test_reports --dry-run

2. Обработка с записью в БД:

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 контейнера:

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)

[
  {
    "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 не установлен"

export ANTHROPIC_API_KEY="your_key_here"

Ошибка подключения к БД

# Проверьте DATABASE_URL
echo $DATABASE_URL

# Проверьте доступность PostgreSQL
docker exec sar-mchs-postgres pg_isready

Файлы не найдены

# Проверьте путь и наличие .docx файлов
ls -la /path/to/docx/files/*.docx

TODO

• Добавить поддержку .pdf файлов
• Batch обработка для снижения стоимости API
• Retry логика при ошибках API
• Прогресс-бар для больших объемов
• Экспорт в CSV/Excel
• Web-интерфейс для мониторинга