Skip to content

About

Эвектио DXA — ИИ-сервис контроля качества денситометрических исследований (DXA) в формате DICOM

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Эвектио — ИИ-контроль качества DXA-исследований

Решение команды Эвектио для задачи «Сервис искусственного интеллекта по оценке качества исследований плотности костей человека» (Центр диагностики и телемедицины, «Лидеры цифровой трансформации 2026»).

Эвектио — локальный ИИ-сервис для автоматизированной оценки качества рентгеновских денситометрических исследований (DXA) в формате DICOM. Для каждого изображения сервис определяет анатомическую область и проекцию, решает, пригодно ли исследование для клинической интерпретации, называет тип нарушения, строит разметку областей измерения и формирует структурированный отчёт. Медицинские изображения не покидают машину, на которой запущен сервис.

Исследовательский прототип поддержки принятия решений. Не является медицинским изделием и не заменяет проверку врачом.

Содержание

  1. Быстрый старт для проверяющего
  2. Назначение и возможности
  3. Структура проекта
  4. Системные требования и зависимости
  5. Сборка и запуск контейнера
  6. API
  7. Входные данные
  8. Выходные данные
  9. Модель, предобработка и постобработка
  10. Качество модели
  11. Известные ошибки, ограничения и их обработка
  12. Запуск без Docker, тесты и переобучение
  13. Документация

1. Быстрый старт для проверяющего

Нужно: Linux или macOS, Docker (Docker Engine 20.10+ или запущенный Docker Desktop), 2 ГБ свободной памяти. Интернет нужен только при сборке образа — для загрузки базового образа Python и пакетов.

git clone https://github.com/archebaldo777/medhackathon.git
cd medhackathon

# 1. Собрать образ evectio:1.5.0
./scripts/build.sh

# 2. Проверить на тестовом фрагменте организатора, который лежит в репозитории
./scripts/analyze.sh "dataset/for tests" outputs/demo
cat outputs/demo/results.csv

# 3. Обработать свой набор: папку с DICOM или ZIP-архив (контейнер работает без сети)
./scripts/analyze.sh /path/to/test_dataset.zip outputs/result

После обработки скрипт печатает сводку и путь к результатам:

{"files": 3, "success": 3, "failure": 0, "with_violations": 2, "output": "/output"}
Результаты: /home/user/medhackathon/outputs/demo (results.csv, results.xlsx, result.zip)

Формат таблицы описан в разделе 8.

Веб-интерфейс и REST API:

./scripts/run.sh             # сервис на http://localhost:8000; остановка — Ctrl+C
DXA_PORT=8080 ./scripts/run.sh   # если порт 8000 занят
  1. Откройте http://localhost:8000 и перейдите к блоку загрузки («Загрузить исследование»).
  2. Перетащите DICOM-файлы или ZIP либо выберите их кнопкой и нажмите «Анализировать».
  3. Результаты откроются на странице; архив со всеми отчётами скачивается кнопкой «Все ZIP».

Проверка API из другого терминала:

curl -f http://localhost:8000/health
curl -f -X POST http://localhost:8000/v1/analyze \
  -F 'files=@test_dataset.zip;type=application/zip' \
  --output results.zip

Интерактивная OpenAPI-документация — http://localhost:8000/docs. Если что-то не запускается, см. раздел «Типичные проблемы» в docs/DEPLOYMENT.md.

2. Назначение и возможности

Сервис автоматизирует первичный контроль качества DXA, который обычно выполняется специалистом вручную (ТЗ, раздел 2).

Функция ТЗ Как реализовано
Анатомическая область (2.1, 2.2) Поясничный отдел позвоночника, правый и левый проксимальный отдел бедра — по содержимому изображения, имена файлов не используются
Проекция исследования (2.2) Прямая (AP) или боковая (LAT) — по тегам DICOM ViewPosition → PatientOrientation → описания серии/протокола
Класс качества (2.2) 0 — качественное, 1 — есть нарушение
Типы нарушений (2.3) Мультилейбл, одно или несколько нарушений из закрытого списка организатора
Корректность укладки и разметки (2.2, 2.3) Измерения в миллиметрах: наклон оси ≤ 5°, гребни подвздошных костей и половина Th12, поля 3 см сверху/снизу и 2 см сбоку от области интереса бедра
Отчёт (2.5) results.csv и results.xlsx, одна строка на изображение
Визуализация нарушения (2.6) Тепловая карта, ось позвоночника и разметка: PNG и DICOM Secondary Capture
Текстовое описание в DICOM SR (2.6) Basic Text SR на каждое изображение, UNVERIFIED → VERIFIED после решения специалиста
Автокоррекция разметки с подтверждением (2.6) Автоматическая разметка L1–L4 / шейка, квадрат Варда, редактируется в веб-интерфейсе и сохраняется как DICOM Presentation State
Веб-интерфейс (2.6) Загрузка, очередь просмотра (нарушения → сомнения → норма), подтверждение специалистом, выгрузка ZIP
Пакетная обработка (2.7) Папка, ZIP или список файлов; общая таблица и ZIP с дополнительными сериями
Локальная работа (3.2) Внешние сервисы не используются, контейнер работает и без сети

Закрытый список нарушений:

Область Нарушения (violation_type)
Поясничный отдел позвоночника Некорректная укладка, Не выравнена ось позвоночника, Присутствуют посторонние предметы
Проксимальный отдел бедра Некорректная укладка (включая ротацию по малому вертелу), Некорректная область интереса

Ограничения кратко: модель обучена на 100 исследованиях с одного аппарата (GE Lunar Prodigy Advance), разметка экспертов дана на уровне исследования, а не отдельного снимка, внешней валидации нет. Подробно — в разделе 11.

3. Структура проекта

.
├── src/                    исходный код сервиса (Python-пакет)
│   ├── api.py              REST API и веб-сервер (FastAPI)
│   ├── cli.py              командная строка: analyze, serve
│   ├── batch.py            пакетная обработка папок и ZIP, сборка результатов
│   ├── analyzer.py         анализ одного изображения / серии, итоговая запись
│   ├── dicom_io.py         чтение DICOM, калибровка пикселя, определение области
│   ├── projection.py       определение проекции и стороны бедра
│   ├── features.py         признаки по критериям ТЗ (угол оси, поля в мм, артефакты)
│   ├── model.py            загрузка модели, пороги голов, итоговый класс
│   ├── markup.py           автоматическая разметка областей измерения и проверки ТЗ
│   ├── visualization.py    тепловая карта и наложения (PNG)
│   ├── dicom_sr.py         DICOM Structured Report
│   ├── dicom_gsps.py       разметка как DICOM Presentation State
│   ├── dicom_viz.py        визуализация как DICOM Secondary Capture
│   ├── review.py           подтверждение/коррекция специалистом
│   ├── reporting.py        CSV, XLSX, manifest.json
│   ├── constants.py        области, нарушения, калибровка, колонки отчёта
│   └── static/             веб-интерфейс (одна HTML-страница и ресурсы)
├── models/                 обученная модель dxa_quality_v4.joblib
├── scripts/
│   ├── build.sh            сборка Docker-образа
│   ├── run.sh              запуск API и веб-интерфейса в контейнере
│   ├── analyze.sh          пакетная обработка папки/ZIP в контейнере
│   ├── demo.sh             демонстрационный прогон без Docker
│   ├── train.py            обучение и групповая кросс-валидация
│   ├── benchmark.py        замер скорости, памяти и детерминизма
│   ├── error_analysis.py   анализ ошибок по клиническим подгруппам
│   ├── preview.py          просмотр вёрстки веб-страницы без backend
│   └── build_spine_model.py  генерация 3D-модели позвоночника для заставки веб-страницы
├── reports/                метрики валидации, бенчмарк, анализ ошибок (JSON)
├── tests/                  автотесты (pytest)
├── dataset/for tests/      тестовый фрагмент организатора: 3 обезличенных DICOM
├── docs/                   руководства: пользователя, API, развёртывание, модель, обучение
├── Dockerfile              образ сервиса
├── Makefile                короткие команды для локальной разработки
├── start_local.sh          локальный запуск веб-интерфейса без Docker
├── pyproject.toml          описание пакета
├── requirements.txt        зафиксированные зависимости сервиса
└── requirements-dev.txt    + зависимости для тестов

Из данных организатора в репозиторий входит только фрагмент для проверки формата dataset/for tests/ (3 обезличенных DICOM) — на нём работают make demo и scripts/demo.sh. Обучающий набор в репозиторий не входит; для переобучения его кладут в dataset/for education/.

4. Системные требования и зависимости

Минимум Рекомендуется
CPU 2 ядра x86_64 или arm64 4 ядра
RAM 2 ГБ 4 ГБ
Диск 1 ГБ свободного места + место под результаты от 5 ГБ на SSD + место под результаты (≈ 0,9 МБ на снимок)
GPU не требуется не требуется

Конфигурация финального тестирования (H200, 44 CPU, 256 ГБ RAM) заведомо превышает требования. GPU сервис не использует: модель — компактный ансамбль scikit-learn.

Внутренний замер на пакете из 510 изображений обучающего набора (2 vCPU), полный цикл с PNG и тремя DICOM-объектами на снимок. Исходные данные организатора не публикуются, поэтому отчёт этого замера в репозиторий не включён; в reports/inference_benchmark.json — воспроизводимый замер на трёх тестовых DICOM (работа модели: медиана 0,05 с, p95 0,11 с на снимок). Повторить замер на своём наборе: .venv/bin/python scripts/benchmark.py --input <папка с DICOM> --output reports/inference_benchmark_full.json. Результаты внутреннего замера: медиана 0,59 с на изображение, p95 — 0,67 с, весь пакет — 268 с. Исследование из 1–3 снимков обрабатывается за 1–2 с при лимите ТЗ 3 минуты. Пиковая память — около 200 МБ плюс около 0,5 МБ на каждое изображение пакета (≈ 460 МБ на 510 снимков). Объём результатов — около 0,9 МБ на изображение. Подробнее — docs/DOCUMENTATION.md.

Программные зависимости (все версии зафиксированы):

  • базовый образ python:3.12.10-slim-bookworm, закреплённый дайджестом sha256:fd95fa221297… (полный — в первой строке Dockerfile);
  • Python-пакеты из requirements.txt: fastapi 0.116.1, uvicorn 0.35.0, pydicom 3.0.1, numpy 2.2.6, scipy 1.18.1, scikit-learn 1.7.2, joblib 1.6.0, Pillow 11.3.0, openpyxl 3.1.5, python-multipart 0.0.20 и их транзитивные зависимости;
  • для запуска без Docker — Python 3.12 или 3.13. На 3.11 не устанавливается scipy 1.18, для 3.14 нет готовых сборок numpy 2.2.6.

5. Сборка и запуск контейнера

Скрипты рассчитаны на Linux и Unix-подобные системы (bash/sh). Образ собирается из Dockerfile; внутрь попадают только код, модель и зависимости — данные и тесты в образ не входят.

./scripts/build.sh                          # docker build -t evectio:1.5.0 .
./scripts/run.sh                            # сервис на http://localhost:8000
DXA_PORT=8080 ./scripts/run.sh              # другой порт
./scripts/analyze.sh INPUT [OUTPUT]         # пакетная обработка без сети

analyze.sh принимает папку с DICOM (любая вложенность) или ZIP. Скрипт монтирует вход только на чтение, запускает контейнер с --network none от имени текущего пользователя (чтобы результаты в OUTPUT принадлежали ему) и пишет туда results.csv, results.xlsx, manifest.json, дополнительные серии и result.zip.

То же вручную:

docker run --rm --network none --user "$(id -u):$(id -g)" \
  -v "$PWD/input:/input:ro" -v "$PWD/output:/output" \
  evectio:1.5.0 python -m src analyze /input --output /output --zip

Контейнер работает от непривилегированного пользователя. HEALTHCHECK опрашивает GET /health; тяжёлая обработка идёт в отдельном потоке, поэтому сервис отвечает на проверки и во время большого пакета. Перенос в изолированный контур (docker save / docker load) описан в docs/DEPLOYMENT.md.

6. API

Все методы работают по HTTP на порту 8000. Полное описание с примерами ответов — в docs/API.md, интерактивная схема — GET /docs.

Метод Назначение
POST /v1/analyze Пакетная обработка (ТЗ 3.2). multipart/form-data, поле files: один или несколько DICOM и/или ZIP. Ответ — ZIP с результатами; сводка — в заголовке X-DXA-Summary
POST /v1/jobs То же, но ответ — JSON для веб-интерфейса; результат хранится 1 час
GET /v1/jobs/{id}/download ZIP всей задачи
GET /v1/jobs/{id}/case/{i}/zip ZIP одного исследования
GET /v1/jobs/{id}/zip?indices=0,2 ZIP отмеченных исследований
POST /v1/jobs/{id}/review/{i} Решение специалиста: подтвердить/отклонить вывод, принять/исправить/отклонить разметку
GET /health Состояние сервиса и версия модели
GET /v1/model Версия модели, пороги голов, области, проекции, типы нарушений, калибровка

Коды ответов: 200 — результат сформирован (отдельные файлы внутри могут иметь processing_status=Failure); 400 — некорректный запрос: повреждённый ZIP, нет DICOM, небезопасный архив; 413 — файл больше 1 ГБ; 415 — неподдерживаемый формат; 500 — контролируемая внутренняя ошибка в JSON.

curl -f -X POST http://localhost:8000/v1/analyze \
  -F 'files=@study1.zip;type=application/zip' \
  -F 'files=@IM000001' \
  --output results.zip -D - | grep X-DXA-Summary
# X-DXA-Summary: {"files":4,"success":4,"failure":0,"with_violations":2,"manual_review":2}

7. Входные данные

  • DICOM-исследования без разметки (ТЗ 2.4): монохромные изображения (MONOCHROME1/2), 8–16 бит. Цветные снимки переводятся в оттенки серого, у многокадровых берётся первый кадр. Поддерживаются несжатый Little Endian (Explicit/Implicit VR), RLE, JPEG Baseline и JPEG 2000.
  • Способы подачи: отдельные файлы, папка с любой вложенностью, ZIP-архив или несколько архивов. Файлы распознаются по расширению .dcm/.dicom или по сигнатуре DICM, поэтому подходят и выгрузки без расширений (IM000001). DICOMDIR, скрытые файлы и служебные папки __MACOSX пропускаются. Кириллические имена в ZIP читаются корректно, включая архивы без UTF-8-флага (Windows, консольный zip).
  • Исследование может содержать до трёх изображений/серий. Кадры с одним StudyInstanceUID и одной областью/стороной анализируются вместе, как серия.
  • Персональные данные не используются. Из DICOM берутся только StudyInstanceUID, SOPInstanceUID, размер пикселя, геометрические теги проекции (ViewPosition, PatientOrientation, (Image)Laterality) и описания серии/протокола.
  • Ограничения API: до 1 ГБ на файл, до 10 000 объектов и 5 ГБ в распакованном архиве. Включена защита от Zip Slip.

8. Выходные данные

Таблица results.csv / results.xlsx (ТЗ 2.5)

Одна строка — одно изображение. CSV в UTF-8 с BOM (корректно открывается в Excel), разделитель — запятая. Первые восемь колонок совпадают с рекомендуемой структурой ТЗ, две последние добавлены.

Колонка Формат Содержание
path_to_study String Путь к файлу относительно входной папки или корня ZIP
study_uid String StudyInstanceUID из тегов; заполняется и при Failure, если заголовок файла читается
image_uid String SOPInstanceUID из тегов; заполняется и при Failure, если заголовок файла читается
anatomical_region String Поясничный отдел позвоночника, Проксимальный отдел бедра (правый) или Проксимальный отдел бедра (левый)
quality_class Integer 0 — качественное, 1 — есть нарушение; пусто при Failure
violation_type String Нарушения из закрытого списка через ;; пусто, если ни один тип не превысил порог (при quality_class = 1 это значит, что сработала только голова общего качества)
processing_status String Success / Failure
time_of_processing Float Время обработки изображения, с
quality_prob Float Оценка риска нарушения [0; 1]; quality_class = 1 ⇔ quality_prob ≥ 0,5
projection String Прямая (AP) или Боковая (LAT)
error String Причина Failure или сообщение о несозданном дополнительном файле (SR, разметка, визуализация); пусто, если ошибок нет

Остальные результаты

Файл Содержание
manifest.json Всё из таблицы плюс источник проекции и стороны, измерения (угол оси, поля в мм), баллы и пороги каждой головы, автоматическая разметка и её проверки, рекомендации по укладке, приоритет ручной проверки, текст ошибки
visualizations/*.png Снимок с тепловой картой вклада, осью позвоночника и разметкой
dicom_viz/*.dcm Та же визуализация как DICOM Secondary Capture в исходном исследовании (серия 901)
dicom_sr/*.dcm Обезличенный DICOM Basic Text SR: область, проекция, статус, нарушения, измерения, рекомендации
dicom_markup/*.dcm Разметка областей измерения как DICOM Grayscale Softcopy Presentation State поверх исходного снимка (серия 902)
result.zip Архив всего перечисленного (флаг --zip / ответ API)

Код завершения CLI: 0 — все файлы обработаны, 2 — есть файлы с Failure, 1 — ошибка запуска или входа (например, не найдено ни одного DICOM).

9. Модель, предобработка и постобработка

Предобработка

  1. DICOM декодируется pydicom; применяются RescaleSlope/Intercept и инверсия MONOCHROME1.
  2. Размер пикселя берётся из PixelSpacing / ImagerPixelSpacing / NominalScannedPixelSpacing. В выгрузках организатора этих тегов нет, поэтому используется калибровка аппарата: 1,05 мм по Y и 0,6 мм по X. Все критерии ТЗ считаются в миллиметрах: 3 см по Y — 28,6 px, 2 см по X — 33,3 px.
  3. Интенсивность нормализуется по 1-му и 99-му процентилям.
  4. Область определяется по геометрии поля сканирования и распределению костной массы: позвоночник или бедро, для бедра — сторона по положению диафиза. Если в DICOM заполнен тег Laterality, сторона берётся из него.
  5. Проекция определяется по тегам DICOM: ViewPosition (AP/PA/LL/RL), затем PatientOrientation (фронтальная плоскость L/R + H/F — прямая, сагиттальная A/P + H/F — боковая), затем ключевые слова в описаниях серии и протокола. В данных организатора заполнен PatientOrientation = L\F, то есть прямая проекция. Если ни одного тега нет, записывается стандартная для DXA прямая проекция с источником protocol в manifest.json.

Модель

Семь специализированных голов — по одной на общий класс качества и на каждый тип нарушения в двух областях. Каждая голова получает свой физически интерпретируемый дескриптор, а не общий вектор внешнего вида:

  • наклон оси позвоночника в градусах с поправкой на анизотропию пикселя (ТЗ: допуск 5°);
  • поля кадра вокруг кости в миллиметрах и физический размер поля сканирования (ТЗ: 3 см / 2 см);
  • локальный контраст и яркость у краёв — признаки посторонних предметов;
  • медиальный контур бедра относительно собственного тренда — ротация по малому вертелу.

Классификаторы голов: ExtraTrees — общее качество позвоночника и бедра, укладка и ось позвоночника; L2-регуляризованная логистическая регрессия — посторонние предметы, укладка/ротация бедра, область интереса бедра. Признаки кадров одной серии агрегируются (mean/max), потому что экспертная разметка дана на уровне исследования. Параметры каждой головы — в reports/validation_metrics_v4.json.

Постобработка

  • У каждой головы свой порог: максимум out-of-fold F1 при специфичности не ниже 0,60. Пороги и их источник возвращает GET /v1/model.
  • Типы нарушений определяются независимо; любой сработавший тип даёт quality_class = 1.
  • quality_prob — максимум по головам после приведения порога каждой головы к 0,5, поэтому класс и вероятность не противоречат друг другу.
  • review_priority: high — нарушение или боковая проекция (модель обучена на прямых снимках), medium — вероятность близка к порогу, low — норма.
  • Автоматическая разметка (L1–L4, гребни подвздошных костей, область интереса бедра, окно шейки, квадрат Варда) строится эвристически и проверяется по критериям ТЗ в миллиметрах. Она объясняет вывод и редактируется специалистом, но не является входом модели.

10. Качество модели

Обучение и оценка — на всех 100 исследованиях / 499 изображениях организатора: 5-fold StratifiedGroupKFold по исследованию (кадры одного исследования не попадают одновременно в обучение и валидацию; идентификатор пациента в данных обезличен), seed 42, дисбаланс компенсируется весами классов. 95% доверительные интервалы — кластерный бутстреп по исследованиям. Полный отчёт с PR-AUC, сбалансированной точностью и матрицами ошибок: reports/validation_metrics_v4.json.

Голова Изображений / положительных Чувствительность Специфичность F1 [95% ДИ] ROC-AUC [95% ДИ]
Позвоночник — общее качество 172 / 61 0,69 0,73 0,63 [0,45–0,77] 0,74 [0,62–0,85]
Позвоночник — некорректная укладка 172 / 10 0,50 0,99 0,62 [0,15–1,00] 0,85 [0,70–1,00]
Позвоночник — ось не выравнена 172 / 17 0,41 0,90 0,35 [0,07–0,60] 0,65 [0,40–0,86]
Позвоночник — посторонние предметы 172 / 35 0,46 0,97 0,58 [0,13–0,82] 0,79 [0,61–0,91]
Бедро — общее качество 324 / 90 0,70 0,66 0,54 [0,38–0,69] 0,67 [0,52–0,80]
Бедро — некорректная укладка 324 / 71 0,52 0,84 0,50 [0,26–0,68] 0,64 [0,44–0,79]
Бедро — некорректная область интереса 324 / 19 0,42 1,00 0,57 [0,00–0,94] 0,93 [0,80–0,99]

Сбалансированная точность и PR-AUC (п. 8.4 ТЗ), 95% ДИ:

Голова Сбалансированная точность PR-AUC
Позвоночник — общее качество 0,71 [0,59–0,81] 0,58 [0,40–0,78]
Позвоночник — укладка 0,75 [0,55–1,00] 0,54 [0,22–1,00]
Позвоночник — ось 0,65 [0,49–0,83] 0,29 [0,07–0,64]
Позвоночник — посторонние предметы 0,71 [0,53–0,86] 0,57 [0,22–0,83]
Бедро — общее качество 0,68 [0,56–0,78] 0,43 [0,29–0,69]
Бедро — укладка/ротация 0,68 [0,54–0,80] 0,41 [0,19–0,69]
Бедро — область интереса 0,71 [0,50–1,00] 0,57 [0,09–0,93]

Macro-F1 пяти типов нарушений — 0,53, средний ROC-AUC типов — 0,77. Широкие интервалы отражают малое число положительных примеров: у редких типов их 10–19. Разбор ошибок по клиническим подгруппам (сколиоз, эндопротез, переходный позвонок, перелом) — в reports/error_analysis.json и docs/MODEL_CARD.md.

11. Известные ошибки, ограничения и их обработка

Как обрабатываются ошибки

Ситуация Поведение
Повреждённый или нечитаемый DICOM Строка с processing_status=Failure, причина — в manifest.json; остальные файлы обрабатываются
Нестандартное изображение (пустое, крошечное, не DXA) Обрабатывается без падения пакета; результат нужно проверить вручную
Ошибка анализа серии кадров одного исследования Строки этой серии получают Failure с причиной; другие исследования пакета не затрагиваются
Цветной или многокадровый снимок в серии Переводится в оттенки серого / берётся первый кадр, поэтому не искажает оценку остальных снимков серии
Не удалось построить SR, разметку или визуализацию Основной результат сохраняется, ошибка записывается в поле error
Повреждённый ZIP, архив без DICOM, небезопасные пути в архиве API: 400 с описанием; CLI: код 1 и JSON с ошибкой. Временные файлы удаляются
Неподдерживаемый формат файла API: 415
Любая непредвиденная ошибка API 500 с JSON {"status": "Failure", "error": ...}, без необработанного исключения
Повторный запуск на тех же данных Классы, типы нарушений и вероятности воспроизводятся без изменений: фиксированные seed и версии, детерминированный порядок файлов. Меняются только время обработки и UID/время создания производных DICOM

Ограничения

  • Обучающая выборка мала (100 исследований), получена на одном аппарате GE Lunar Prodigy Advance; нужна внешняя многоцентровая валидация. Для других аппаратов нужна перекалибровка размера пикселя и определения области или дообучение.
  • Экспертная разметка дана на уровне исследования и переносится на изображения соответствующей области — это слабая разметка.
  • Модель обучена только на прямых проекциях. Боковая проекция определяется, но её результат помечается для обязательной ручной проверки.
  • Если в DICOM нет ни одного тега проекции, проекция не измеряется, а принимается стандартной (прямой); источник protocol указан в manifest.json.
  • Автоматическая разметка эвристическая, эталона для неё в данных нет. На снимках со сколиозом, эндопротезом или переходным позвонком L6 её нужно проверять особенно внимательно. Дуга оси ≥ 6 мм помечается как «вероятен сколиоз».
  • Известные слабые места модели: голова оси ложно срабатывает примерно на трети снимков со сколиозом; крупный однородный металл эндопротеза не распознаётся как посторонний предмет.
  • JPEG-LS и другие редкие сжатые transfer syntax требуют дополнительных декодеров pydicom; такие файлы получают Failure с причиной.
  • Производные DICOM-объекты сохраняют исходный StudyInstanceUID дословно, даже если в нём есть компоненты с ведущим нулём (так в выгрузках организатора), — иначе PACS разнесёт их по разным исследованиям. Строгий PACS может выдать на такие UID предупреждение или отказ; совместимость нужно проверить на целевой системе.
  • Сервис формирует DICOM GSPS, SR и Secondary Capture для импорта в совместимый PACS; сетевая отправка (C-STORE, STOW-RS) и DICOM Conformance Statement не входят в прототип.
  • Публичный демо-стенд предназначен только для обезличенных тестовых DICOM: файлы передаются на сервер стенда и удаляются автоматически не ранее чем через час, при очередном обращении к сервису. Обработка без передачи данных за пределы организации обеспечивается при локальном развёртывании.
  • Медицинское решение принимает специалист.

12. Запуск без Docker, тесты и переобучение

Нужен Python 3.12 или 3.13. Проверьте версию командой python3 --version. На macOS системный python3 обычно старше — установите нужный через Homebrew (brew install python@3.12) и используйте python3.12 вместо python3.

python3.12 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt

.venv/bin/python -m src serve                         # API и веб-интерфейс на :8000
.venv/bin/python -m src analyze INPUT --output OUT --zip
.venv/bin/pytest                                      # автотесты, около 40 с

То же через make: make install PYTHON=python3.12, make serve, make test, make demo (прогон на dataset/for tests/), make benchmark. Для быстрого запуска веб-интерфейса после установки есть ./start_local.sh. Справка по параметрам — .venv/bin/python -m src analyze --help.

Путь к модели можно переопределить переменной DXA_MODEL_PATH.

Переобучение на данных организатора (около минуты на CPU):

.venv/bin/python scripts/train.py \
  --studies "dataset/for education/Исследования" \
  --labels "dataset/for education/разметка.xlsx" \
  --output models/dxa_quality_v4.joblib \
  --metrics reports/validation_metrics_v4.json

Файл модели хранит размер признакового вектора каждой головы. После изменений в src/features.py модель нужно переобучить, иначе сервис откажется запускаться с понятной ошибкой. Подробнее — docs/TRAINING.md.

13. Документация

Документ Для кого
docs/DOCUMENTATION.md Полная документация в одном файле: соответствие пунктам ТЗ, архитектура, алгоритм, форматы, метрики, производительность, тесты
docs/USER_GUIDE.md Руководство пользователя: веб-интерфейс, CLI, подтверждение специалистом
docs/DEPLOYMENT.md Руководство по развёртыванию: сборка, изолированный контур, ресурсы, мониторинг
docs/API.md Все методы REST API с примерами
docs/TRAINING.md Процедура обучения и дообучения
docs/MODEL_CARD.md Карточка модели: данные, метрики, ограничения
docs/PROJECT_DESCRIPTION.md Краткое описание решения для защиты
presentation.pdf Презентация решения

About

Эвектио DXA — ИИ-сервис контроля качества денситометрических исследований (DXA) в формате DICOM

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages