Автоматизированная оценка качества денситометрических исследований

Документ описывает фактическое состояние репозитория на дату, указанную на титуле: все параметры, пороги, метрики и имена полей приведены по коду и по выполненным измерениям, а не по проектным намерениям. Там, где значение измерено на конкретной машине, указано, на какой. Расхождения и ограничения перечислены явно — разделы 15 и 16.

1. Назначение и область применения

Сервис принимает денситометрическое исследование в формате DICOM и выполняет автоматизированный контроль его качества: определяет анатомическую область, решает бинарную задачу «изображение пригодно для клинической интерпретации / содержит нарушение качества», относит нарушение к категории и формирует структурированный отчёт (XLSX/CSV) с одной строкой на изображение.

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

Решение работает полностью офлайн: изображения не передаются во внешние сервисы, все зависимости и веса фиксированы, доступ в сеть при инференсе не требуется. Это прямое требование методики (п. 3.2 задания) и одновременно условие применимости в закрытом контуре медицинской организации.

2. Соответствие требованиям задания

Таблица связывает пункты задания с реализацией и со способом проверки. Формулировки требований приведены по тексту методических рекомендаций.

3. Архитектура решения

3.1. Слои

3.2. Поток обработки одного изображения

Ниже — фактический путь данных от файла до строки отчёта. Ключевое свойство: обучение и сервис используют один и тот же код предобработки и предсказания, поэтому расхождение между офлайн-оценкой и работой API невозможно по построению, а не по договорённости.

Порядок операций и точка принятия решения:

1. Чтение. Из файла берутся пиксельные данные и идентификаторы исследования и снимка (StudyInstanceUID, SOPInstanceUID). Персональные данные не используются: решение не зависит от их наличия.
2. Предобработка. Приводится к виду, ожидаемому предобученным backbone (описание — разд. 5). Параметры предобработки хранятся в чекпоинте и берутся из него, а не из кода по умолчанию.
3. Оценка качества. Один прямой проход сети даёт логит. Решение принимается по логиту: quality_class = 1, если логит выше порога. Порог подобран по F1 на валидации и сохранён в чекпоинте (текущее значение −0.4930, что соответствует вероятности 0.379).
4. Анатомическая область. Определяется независимо от модели, по геометрии кадра (разд. 7), с оценкой уверенности.
5. Измерения и тип нарушения. Для снимков с нарушением вычисляются числовые признаки снимка, по которым нарушение относится к категории словаря (разд. 8).
6. Отчёт. Строка собирается со статусом обработки и временем; ошибка на файле не прерывает пакет.

4. Состав данных и разметка

4.1. Набор

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

4.2. Единица разметки и правило получения метки

Экспертная таблица описывает исследование, а не отдельный снимок. Однако каждая анатомическая область встречается в исследовании ровно один раз (после склейки дублей), поэтому вердикт исследования по области переносится на снимок однозначно — не требуется решать, какой из нескольких снимков «плохой». Так получены метки и типы нарушений (labels/labels_images.csv); каждый источник свидетельства сохранён в отдельном столбце, поэтому правило можно переиграть без повторного разбора данных.

Возможны были два правила: учитывать только экспертную таблицу либо дополнительно учитывать пометки _good/_bad, проставленные вручную в именах файлов. Пометки расходились с экспертом в 15 случаях из 252, поэтому правило выбиралось измерением: одно зафиксированное разбиение, пять seed'ов обучения, один эталон (табл. в разд. 12.3). Выбрано правило «только экспертная таблица».

4.3. Разбиение выборки

Разбиение стратифицировано по эталону и фиксировано в файле: все сравниваемые варианты обучаются и оцениваются на одном и том же held-out наборе, что делает сравнения корректными. Снимки одного исследования не попадают одновременно в обе части — это исключает утечку, при которой метрики растут за счёт запоминания конкретных исследований. Наличие утечки и воспроизводимость разбиения проверяются тестами (tests/test_labels.py).

5. Предобработка изображений

Предобработка описана декларативно в src/dxa/preprocess.py (неизменяемая конфигурация PreprocessConfig) и используется и при обучении, и при работе API. Параметры хранятся в чекпоинте и восстанавливаются из него, поэтому вход модели не может разойтись между двумя режимами.

Порядок операций над одним файлом:

1. Чтение. pydicom.dcmread и pixel_array в float32; многокадровое изображение усредняется по кадрам, иная размерность — ошибка.
2. Коррекция интенсивностей. Учитываются RescaleSlope и RescaleIntercept; для MONOCHROME1 яркость инвертируется.
3. Нормировка. По перцентилям 0.5 / 99.5 с обрезкой в [0, 1] и защитой от вырожденного диапазона (hi ≤ lo).
4. Приведение к тензору. Умножение на 255 и uint8, дублирование одного канала в три, resize 224×224 билинейно, перевод в CHW, деление на 255, затем нормировка ImageNet.

Если в чекпоинте нет блока preprocess (старый файл), применяются значения по умолчанию — percentile с нормировкой ImageNet; устаревший профиль minmax без ImageNet доступен флагом --no-imagenet-norm.

6. Модель и процедура обучения

6.1. Архитектура

6.2. Гиперпараметры и процедура обучения

Почему линейный зонд. При ~250 уникальных снимках полный fine-tune ResNet18 за несколько эпох запоминает обучающую выборку: train F1 стремится к 1.0, а val AUC падает к 0.5. Поэтому по умолчанию backbone заморожен и обучается только голова на признаках ImageNet. При заморозке слои BatchNorm остаются в режиме eval: иначе бегущие статистики продолжали бы обновляться и признаки «уезжали» бы от тех, на которых рассчитывалась стандартизация.

Почему порог по логиту. Порог хранится и применяется в логитах (log-odds): после обучения линейный зонд разделяет обучающую выборку почти идеально, вероятности насыщаются в 0/1, и порог в единицах вероятности вырождается. Для человека порог переводится в вероятность через сигмоиду. ROC-AUC и PR-AUC считаются по вероятностям и от порога не зависят.

Как подбирается порог. На каждой эпохе по валидации: кандидаты — все наблюдаемые логиты плюс края диапазона, выбирается максимум F1; при равном F1 берётся меньший логит, чтобы не терять recall. Аргумент --min-recall позволяет вместо этого взять максимальный порог с recall не ниже заданного.

Рабочий чекпоинт. Лучшая эпоха — 39 из прогона в 64 эпохи (обучение остановлено по терпению), порог логита −0.4930 (вероятность 0.379). Метрики этой эпохи — в разделе 12, честная оценка варианта на пяти seed'ах — ROC-AUC 0.6764.

6.3. Чекпоинт и отчёты

Чекпоинт самодостаточен: кроме весов в нём лежат архитектура, параметры предобработки, порог и происхождение данных, поэтому инференс не может рассинхронизироваться с обучением.

Рядом с чекпоинтом обучение пишет train_report.md и train_report.json: гиперпараметры, метрики на валидации, метрики по областям и историю по эпохам. Артефакты кладутся в --output-dir (по умолчанию models).

7. Определение анатомической области

Область определяется по содержимому снимка, а не по имени файла: на закрытом наборе соглашение об именах может отсутствовать. Решение принимается по геометрии кадра (resolve_region в src/dxa/inference.py) независимо от модели качества; обученная вспомогательная голова области привлекается только как уточнение.

Признаки считает функция heuristic_signals по маске яркой (костной) ткани с порогом по 95-му перцентилю:

Порог ширины задан константой SPINE_MIN_WIDTH = 295. Порядок решений:

1. если ширина кадра ≥ 295 — spine, уверенность 0.8;
2. иначе (бедро) — сторона по перевесу светимости: left_right_ratio > 1.3 даёт hip_right, < 0.7 — hip_left, уверенность 0.6;
3. при промежуточном перевесе — предсказание головы области, если её уверенность ≥ 0.5;
4. если и оно неуверенно — общая область hip с уверенностью 0.4.

Если ширина кадра неизвестна, используется предсказание головы, а затем форма яркой области (bbox_aspect и symmetry).

Точность. Сопоставление с областью из рабочей разметки (252 снимка, раздел 4):

Различение позвоночника и бедра по ширине кадра работает безошибочно, а сторона бедра определяется менее надёжно: перевес светимости путает левое и правое в 17 случаях из 152. Сторона не проверялась по тегам DICOM — Laterality в наборе пуст, — поэтому это ограничение (раздел 17, п. 7), а не измеренная ошибка модели.

8. Таксономия нарушений качества

Коды типов нарушений собраны в одном модуле src/dxa/violations.py. Раньше словарь был свой в трёх местах (инференс, main.py и веб-интерфейс), и ни одна копия не знала кодов экспертной таблицы; теперь коды, русские подписи и пояснения заданы один раз, а сервер отдаёт их клиенту.

У каждого кода есть пояснение, чем нарушение мешает измерению (например, для rotation — что малый вертел виден слишком хорошо и шейка бедра кажется укороченной). Функция catalogue() отдаёт словарь через /api/v1/model, поэтому подписи в интерфейсе и в выгрузке не могут разойтись с кодами.

Для текстового отчёта DICOM SR у каждого кода заданы условный числовой код и английская формулировка. Полноценного справочника SNOMED/DICOM для контроля качества DXA в наборе нет, поэтому коды условные и всегда идут рядом с текстом: пригодный снимок кодируется 113001 (DXA image quality acceptable) с флагом FINAL, нарушение — с флагом WARNING. Устаревшие значения внешних источников (artifact_motion, roi_error, position_error, quality_violation_detected и другие) приводит к канону функция canon_type.

8.1. Тип нарушения в разметке

Экспертная таблица кодирует не все девять кодов, а пять: positioning, axis_deviation, artifact, rotation, roi_incorrect. Распределение в рабочей разметке (в четырёх из 77 нарушений указано по два критерия, поэтому сумма больше 77):

Коды motion, incomplete_anatomy и labeling_error в разметке не встречаются: таблица их не кодирует, хотя словарь их знает ради критериев condition_doctor.txt. Пять снимков имеют только unspecified, потому что источник не указывает критерий.

8.2. Тип нарушения при инференсе

Модель решает только бинарную задачу, поэтому тип для снимка с нарушением выбирает функция classify_violation_type по дешёвым признакам: размытие (laplacian_variance), доля плотных пикселей (bright_fraction) и вытянутость яркой области (bbox_aspect для бедра). При отсутствии выраженного признака возвращается unspecified.

9. Форматы входных и выходных данных

9.1. Вход

Один файл DICOM (для API — один HTTP-загрузкой, для CLI — файл или каталог с рекурсивным обходом). Исследование может содержать несколько снимков — каждый обрабатывается отдельно и даёт отдельную строку отчёта. Перед обработкой файл читается целиком; при ошибке чтения строка получает статус сбоя, а пакет продолжается.

9.2. Выходной файл

Состав столбцов проверен на реальных прогонах — и через CLI, и через /api/v1/export. Обязательные восемь столбцов задания совпадают в обоих путях по составу и порядку; дополнительно пишутся confidence и violation_reason, а CLI-инференс добавляет одиннадцатый столбец region_confidence. Таблица ниже отражает CLI-вывод; в ответе /api/v1/export последнего столбца нет.

10. API сервиса

Сервис на FastAPI. Маршруты и состав полей ответов ниже приведены по фактическим ответам на запросах к тестовым файлам, а не по схеме из документации кода.

10.1. Состав ответа /api/v1/analyze

Поля: filename, study_uid, image_uid, anatomical_region, region_confidence, quality_class, quality_label, overall_quality, severity, confidence, confidence_per_class, threshold_probability, violation_type, violation_type_label, violation_type_is_heuristic, violation_type_note, reason, metrics, samples, processing_status.

Два поля заслуживают пояснения при интеграции:

• violation_type_is_heuristic = true — тип нарушения определён по измеряемым признакам снимка, а не предсказан моделью; модель решает только бинарную задачу. Флаг отдаётся клиенту явно, чтобы это различие не терялось в интеграции.
• quality_label, violation_type_label, violation_type_note — готовые подписи для интерфейса. Они приходят с сервера: клиент не держит собственных копий словаря, поэтому подписи не могут разойтись с кодами.

10.2. Расширенный ответ /api/v1/analyze/detailed

Дополнительно к предыдущему набору: image (визуализация снимка), mask (маска зоны измерения, при запросе), reasons, metrics_note, view_quality, а также измерения по областям: spine_completeness, hip_completeness, hip_rotation.

11. Веб-интерфейс

Интерфейс предназначен для ручной проверки работы сервиса и для демонстрации: загрузка файлов, таблица результатов со статистикой, панель деталей по выбранной строке и панель «О модели» с источником загруженного чекпоинта.

Отдельный принцип — интерфейс не утверждает больше, чем известно решению:

• тип нарушения показан с пометкой «эвристика» и пояснением, что модель решает только бинарную задачу;
• метрика рабочего чекпоинта помечена как завышенная (чекпоинт выбирался лучшим из пяти seed'ов), а честная оценка варианта приведена рядом — в панели «О модели»;
• плитка средней уверенности не называется точностью: точность требует эталонных меток, которых для произвольного файла нет;
• числовые измерения панели деталей идут под дисклеймером о некалиброванности порогов.

12. Метрики качества

12.1. Основная оценка

Оценка получена на фиксированном разбиении по исследованиям (обучение 199 снимков / 81 исследование, валидация 53 снимка / 19 исследований, 16 нарушений), пять seed'ов обучения, эталон — вердикт эксперта из таблицы. Приоритетные по заданию метрики приведены с 95 % доверительными интервалами.

12.2. Оценка по областям и контрольные проверки

Разбивка по областям нужна потому, что нарушения распределены неравномерно: в позвоночнике 33 из 99 снимков, у бёдер 21–22 из 73–79, а сама область почти однозначно определяется по ширине кадра. Поэтому общий AUC частично отражает различение области, а не только распознавание дефекта. Чтобы отделить одно от другого, выполнена проверка: правило «позвоночник = нарушение» даёт внутри областей 0.50 (подсказки нет), модель — 0.85–0.93. Это означает, что модель использует содержимое снимка, а не только область.

12.3. Выбор правила разметки

Парная разница (только таблица минус с суффиксами): ROC-AUC +0.0564 [+0.0403, +0.0725], PR-AUC +0.0713 [+0.0398, +0.1028] — знаки +++++, то есть преимущество на всех пяти seed'ах. Принято правило «только экспертная таблица». Оговорка, важная для интерпретации: эталон — та же таблица, поэтому вариант, обучавшийся на ней, находится в выигрышном положении; значимо здесь то, что добавление ненадёжных пометок согласие с экспертом снижает, а не повышает.

13. Производительность и системные требования

13.1. Измерения

Измерения выполнены на рабочей машине разработчика (macOS, Apple Silicon) на полном наборе данных — 548 файлов в dataset_hack (544 обучающих плюс 4 тестовых). Инференс принудительно переведён на CPU параметром --device cpu, чтобы числа не зависели от наличия ускорителя.

Отсюда следует прямой ответ на требование «не более 3 минут на исследование»: даже если исследование содержит максимальные по заданию три снимка, обработка занимает доли секунды, а трёхминутный бюджет расходуется практически только на передачу файлов и накладные расходы интеграции. Запас более чем трёхкратный, поэтому узким местом решение не ограничивает.

13.2. Минимальная и рекомендуемая конфигурация

Размер образа (измерено): 1.41 ГБ (1 412 385 143 байт) для сборки под linux/arm64. Базовый образ python:3.11-slim занимает 150 МБ, остальное — зависимости из requirements.txt, включая torch и torchvision из CPU-индекса; CUDA-колёса в образ не попадают. Данные, тесты, labels/ и assets/ в образ не входят, чекпоинт (43 МБ) монтируется отдельно.

14. Сборка, запуск и развёртывание

14.1. Состав образа

Если чекпоинт не смонтирован, сервис всё равно поднимается: /api/v1/health сообщает model_loaded: false, а запросы анализа возвращают ошибку вместо тихой неверной оценки. Это сознательный выбор: отсутствие модели должно быть заметно сразу, а не проявляться как «странные» результаты.

Что проверено на самом образе. Сборка прошла обе внутренние проверки (app import ok, frontend assets ok). Образ запущен и проверен в двух режимах: без смонтированного чекпоинта /api/v1/health отдаёт model_loaded: false и exists: false, а запрос анализа — HTTP 500 с телом {"error": "Model not loaded"}; с примонтированным каталогом моделей /api/v1/health сообщает model_loaded: true, device: cpu, эпоху 39 и файл разметки labels/labels_images.csv, запрос анализа отвечает корректной строкой результата, а /api/v1/export возвращает XLSX с ожидаемым набором столбцов. Сквозная проверка выполнялась в контейнере на той же машине, где снимались измерения производительности.

14.2. Воспроизводимость

• Версии всех зависимостей зафиксированы, базовый образ задан тегом, версии torch и torchvision указаны явно.
• Обучение детерминировано по seed; разбиение выборки сохраняется в файл и переиспользуется.
• Чекпоинт самодостаточен: внутри хранятся backbone, head, параметры предобработки, threshold, а также labels_csv и split_file. Поэтому по файлу видно, на какой разметке и на каком разбиении получена модель, а инференс не может рассинхронизироваться с обучением.
• Отказ от зависимости от рабочего каталога: путь к модели и рабочие каталоги задаются переменными окружения.

14.3. Сборочный конвейер

Jenkinsfile выполняет три шага: сборка образа, публикация в реестр и выкладка в кластер. Скрипт run.sh — единая точка входа для разработки и эксплуатации: обучение, разметка, приведение имён файлов, инференс, сервис, сравнение вариантов разметки и тесты (перечень команд — приложение Б).

15. Тесты и проверки

Тесты — pytest, 209 проверок в шести файлах; запуск — ./run.sh test или python -m pytest tests/ -q. Сверка выполнена на дату документа: 209 passed.

Отдельный контур — браузерные проверки интерфейса (tests/browser/*.js, Node и playwright-core): они открывают интерфейс во временном профиле Chrome, загружают DICOM, кликают по строкам таблицы и снимают содержимое панели деталей. Требуется запущенный сервер на 127.0.0.1:8123; профиль пользователя не затрагивается.

16. Известные ошибки и их обработка

Требование задания — отсутствие необработанных исключений: сбой на одном файле фиксируется в отчёте и не прерывает пакет. Ниже — фактические режимы отказа и способ обработки.

17. Ограничения и достоверность результатов

Ограничения сформулированы так, чтобы читатель мог оценить границы применимости решения, а не только увидеть итоговые метрики.

1. Разметка выведена из оценки исследования, а не снимка. Экспертная таблица описывает исследование; перенос вердикта на снимок однозначен (область встречается один раз), но поштучной экспертной оценки снимков в наборе нет. Оценка качества модели упирается в качество этой разметки, а не только в объём данных.
2. Мало данных. 252 уникальных снимка, 77 нарушений. Доверительные интервалы широкие (ROC-AUC 0.6764 [0.6309, 0.7218] по пяти seed'ам), поэтому оценка на закрытом наборе может отличаться.
3. Эталон — та же таблица. Независимой истины нет, поэтому сравнение правил разметки частично благоприятствует варианту «только таблица» (раздел 12.3).
4. В DICOM нет разметки областей интереса. Ни overlay, ни graphic annotation в файлах нет, поэтому корректность нанесённых областей измерения нельзя проверить прямым сравнением с эталоном: оценивается геометрия видимой зоны.
5. Тип нарушения определяется признаками снимка, а не обученной моделью. Модель решает только бинарную задачу, поэтому в выгрузке тип содержателен только для размеченных снимков, а на инференсе эвристика на текущих данных всегда даёт «не уточнён» (раздел 8.2). Для честного мультикласса нужна разметка типов на уровне снимка; пять снимков имеют только код «не уточнён», потому что источник не указывает критерий.
6. Три снимка размечены по пометке в имени файла — экспертная таблица их область не оценивала. Такие строки помечены признаком filename_fallback.
7. Сторона бедра в семи исследованиях с единственным снимком не проверяема: теги Laterality пусты, оценка взята из единственного заполненного столбца таблицы.
8. Порог определения области привязан к текущему оборудованию. Признак «ширина кадра» безошибочно работает на этом наборе, но при смене аппарата потребует калибровки.
9. Числовые эвристики панели деталей не калиброваны. Их пороги рассчитаны на другой масштаб интенсивностей, поэтому в интерфейсе показываются измерения, а не вердикты.
10. Рабочая точка порога даёт высокий recall при умеренной точности. На обучающем наборе при пороге, подобранном по F1, модель относит к нарушениям 341 строку из 548 (≈ 62 %) при фактической доле нарушений 30.6 %, что согласуется с precision 0.486. Порог выбран в пользу полноты: пропустить непригодное исследование дороже, чем показать лишнее.

18. План развития

• Разметить типы нарушений на уровне снимка и обучить мультилейбл-классификатор — это снимает главное ограничение (тип нарушения определяется признаками, а не моделью).
• Расширить набор до 500+ исследований: доверительные интервалы сузятся, появится возможность честной валидации без пересечения с обучением.
• Заменить признак «ширина кадра» на калибровку по метаданным аппарата, чтобы определение области не зависело от конкретного оборудования.
• Добавить локализацию нарушения (тепловая карта или контур) — в задании это отнесено к дополнительному функционалу, и для него нужна соответствующая разметка.
• Собрать пилотную интеграцию с АРМ: отбор исследований, требующих внимания, и журналирование подтверждений специалиста.

Приложение А. Структура репозитория

bone_2026/
├── src/
│   ├── main.py                     FastAPI: маршруты и загрузка модели
│   ├── dxa/                        действующий модуль оценки качества
│   │   ├── preprocess.py           DICOM -> тензор (общий путь для обучения и API)
│   │   ├── model.py                сеть, метрики, подбор порога, чекпоинт
│   │   ├── train.py                обучение и отчёт (md/json)
│   │   ├── dataset.py              DXADataset, DataLoader
│   │   ├── inference.py            пакетный инференс, определение области, визуализация
│   │   ├── labels.py               разбор имён, метки, склейка дублей, разбиение
│   │   ├── excel_labels.py         разметка снимков по экспертной таблице
│   │   ├── rename_files.py         приведение имён DICOM к единому виду
│   │   ├── violations.py           единый словарь типов нарушений
│   │   ├── model_card.py           карточка решения для API и интерфейса
│   │   ├── compare_labels.py       сравнение источников разметки
│   │   ├── discriminator.py        проверка вклада содержимого снимка
│   │   └── render.py               рендер снимков и контактных листов
│   ├── quality/                    эвристики: измерения снимка
│   ├── api/static/                 веб-интерфейс (офлайн-ассеты)
│   └── utils/                      выбор устройства
├── labels/                         размеченные данные, разбиение, карта переименований
├── assets/                         схемы, скриншоты, обоснование разметки
├── models/dxa_model.pth            рабочий чекпоинт и отчёт обучения
├── tests/                          pytest + браузерные проверки интерфейса
├── docs/                           настоящий документ (HTML и PDF)
├── run.sh, Dockerfile, Dockerfile_cuda, Jenkinsfile, requirements.txt

Приложение Б. Команды

# обучение и разметка
./run.sh label                          разметить датасет по экспертной таблице
./run.sh rename                         план приведения имён файлов (--apply для применения)
./run.sh train                          обучить модель (режим меток по умолчанию)
./run.sh split && ./run.sh compare       сравнить варианты разметки на одном разбиении

# инференс и сервис
./run.sh infer "dataset_hack/Для теста" results.xlsx
./run.sh serve                          API и веб-интерфейс на порту 8000
python -m src.dxa.discriminator         проверка вклада содержимого снимка

# проверки
./run.sh test                           pytest (209 тестов)
node tests/browser/ui_check.js          проверки интерфейса (нужен сервер на 127.0.0.1:8123)

# контейнер
docker build -t dxa-quality .
docker run -v /path/to/data:/data -v /path/to/models:/app/models -p 8000:8000 dxa-quality

Документ подготовлен по фактическому состоянию репозитория; машинные отчёты обучения — models/train_report.json, обоснование разметки — assets/labeling.md.