Решение команды Эвектио для задачи «Сервис искусственного интеллекта по оценке качества исследований плотности костей человека» (Центр диагностики и телемедицины, «Лидеры цифровой трансформации 2026»).
Эвектио — локальный ИИ-сервис для автоматизированной оценки качества рентгеновских денситометрических исследований (DXA) в формате DICOM. Для каждого изображения сервис определяет анатомическую область и проекцию, решает, пригодно ли исследование для клинической интерпретации, называет тип нарушения, строит разметку областей измерения и формирует структурированный отчёт. Медицинские изображения не покидают машину, на которой запущен сервис.
Исследовательский прототип поддержки принятия решений. Не является медицинским изделием и не заменяет проверку врачом.
- Быстрый старт для проверяющего
- Назначение и возможности
- Структура проекта
- Системные требования и зависимости
- Сборка и запуск контейнера
- API
- Входные данные
- Выходные данные
- Модель, предобработка и постобработка
- Качество модели
- Известные ошибки, ограничения и их обработка
- Запуск без Docker, тесты и переобучение
- Документация
Нужно: 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 занят- Откройте http://localhost:8000 и перейдите к блоку загрузки («Загрузить исследование»).
- Перетащите DICOM-файлы или ZIP либо выберите их кнопкой и нажмите «Анализировать».
- Результаты откроются на странице; архив со всеми отчётами скачивается кнопкой «Все 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.
Сервис автоматизирует первичный контроль качества 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.
.
├── 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/.
| Минимум | Рекомендуется | |
|---|---|---|
| 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.
Скрипты рассчитаны на 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.
Все методы работают по 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}- 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.
Одна строка — одно изображение. 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).
Предобработка
- DICOM декодируется
pydicom; применяютсяRescaleSlope/Interceptи инверсияMONOCHROME1. - Размер пикселя берётся из
PixelSpacing/ImagerPixelSpacing/NominalScannedPixelSpacing. В выгрузках организатора этих тегов нет, поэтому используется калибровка аппарата: 1,05 мм по Y и 0,6 мм по X. Все критерии ТЗ считаются в миллиметрах: 3 см по Y — 28,6 px, 2 см по X — 33,3 px. - Интенсивность нормализуется по 1-му и 99-му процентилям.
- Область определяется по геометрии поля сканирования и распределению костной массы: позвоночник или бедро, для бедра — сторона по положению диафиза. Если в DICOM заполнен тег
Laterality, сторона берётся из него. - Проекция определяется по тегам 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, гребни подвздошных костей, область интереса бедра, окно шейки, квадрат Варда) строится эвристически и проверяется по критериям ТЗ в миллиметрах. Она объясняет вывод и редактируется специалистом, но не является входом модели.
Обучение и оценка — на всех 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.
Как обрабатываются ошибки
| Ситуация | Поведение |
|---|---|
| Повреждённый или нечитаемый 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: файлы передаются на сервер стенда и удаляются автоматически не ранее чем через час, при очередном обращении к сервису. Обработка без передачи данных за пределы организации обеспечивается при локальном развёртывании.
- Медицинское решение принимает специалист.
Нужен 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.
| Документ | Для кого |
|---|---|
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 |
Презентация решения |