Документ для печати в PDF. Блоки не разрываются между страницами.

Protocol: архитектура по этапам

Навигатор клинических протоколов Минздрава РБ и ориентировочная проверка консультативных заключений (КЗ).

Документ для методслужбы, разработки и интеграции с МИС: три функциональных блока, конвейер чанков, уровни проверки L0-L2, поиск S0-S2. Развёртывание - локальные серверы в контуре клиники или оператора; языковые модели - доработанные on-prem, без передачи ПДн во внешние API.

Версия документа: 2026-06-24 · Сборка: GET /api/version · Якорный пилот: МЦ «Кравира» · Бренд продукта: Protocol.

0. Три блока системы (обзор)

Protocol - не «один скрипт», а три связанных блока. Каждый блок можно развивать и масштабировать отдельно; на стыках - JSON/API и общий идентификатор PDF протокола (source_path).

Блок I. Корпус и индексы Официальные PDF Минздрава → чанки → каталог правил → индексы поиска. Офлайн-пайплайны, без пациентских данных.

Блок II. clinical_knowledge Детерминированное ядро: парсинг КЗ, 482+ правил, 8 блоков scoring, send_gate, ЦИСЗ readiness, alignment. Решение воспроизводимо.

Блок III. Runtime и интерфейсы API-сервер, lazy-загрузка чанков, оркестрация tier L0/L1/L2, B2B UI и B2C patient. LM-слой - только там, где разрешено политикой.

┌─────────────────── Блок I: корпус ───────────────────┐ │ minzdrav PDF → rich_chunks / legacy chunks → catalog │ └────────────────────────┬─────────────────────────────┘ │ path, chunk_id, tags ┌────────────────────────▼─────────────────────────────┐ │ Блок II: clinical_knowledge (правила, gate, alignment) │ └────────────────────────┬─────────────────────────────┘ │ ComplianceReport, send_gate ┌────────────────────────▼─────────────────────────────┐ │ Блок III: API + index.html + patient.html (tier L0-L2) │ └──────────────────────────────────────────────────────┘

принцип Итоговый gate_score и send_gate определяются детерминированным слоем. Нейросетевой слой (embedder, reranker, narrative) ускоряет поиск и поясняет отчёт, но не подменяет правила и не меняет gate без явной политики.

1. Блок I. Корпус протоколов и справочники

1.1. Источник

Официальный каталог PDF на minzdrav.gov.by (~478 документов, 24 рубрики). Синхронизация: download_minzdrav_protocols.py → каталог minzdrav_protocols/.

1.2. Справочники и метаданные

index.csv, protocols.json, protocol_meta.json - реестр и метаданные файлов.
data/catalog/ - 85 нозологий, 482+ автоизвлечённых правил для rule_checker.
data/protocol_summaries/ - YAML/JSON карточки протоколов для навигации и расширения правил.
config/ - веса 8 блоков scoring, red flags, требования к структуре КЗ.

1.3. Два конвейера чанков (см. раздел 4 подробно)

Конвейер	Скрипт	Назначение	Выход
Legacy (скользящее окно)	`extract_corpus.py` → `build_chunks.py`	Быстрый полнотекстовый поиск по клинической части PDF	`corpus_chunks_parts/*.jsonl`, ~55k записей
Rich (смысловой)	`scripts/build_rich_chunks.py`	Разделы, типы, МКБ, сущности, tags - для L1/L2 и rule_checker	`output/rich_chunks/rich_chunks.jsonl` + паспорт `output/rich_meta/{doc_id}.json`
Pipeline v2	`corpus_pipeline/run_pipeline`	Таблицы, entities, нормализация секций	`output/chunks/`

1.4. Индексы поиска (офлайн + lazy при старте)

Path-scoped lex shards, BM25 (retrieval_bm25.py), опционально vector prefilter (vector_index.py) на предвычисленных эмбеддингах чанков (локальная embedder-модель). Маршрутизация по симптомам: symptom_routing.json. На production: lazy chunk store - manifest corpus_path_manifest.jsonl, чанки с диска по source_path, без загрузки всего корпуса в RAM (RAG_LAZY_CHUNK_STORE=1).

2. Блок II. clinical_knowledge (детерминированное ядро)

Каталог clinical_knowledge/ (~118 модулей). Публичный статус: /api/clinical-knowledge/status.

Подблок	Модули	Роль в анализе КЗ
Схемы	`consult_schema.py`	ConsultationDocument, ComplianceReport, 8 блоков
Парсинг	`consult_parser.py`, `text_extract.py`, `fhir_bundle_adapter.py`	PDF / TXT / FHIR Bundle → структура КЗ
Подбор КП	`protocol_match.py`, `diagnosis_icd.py`	МКБ-10 → список протоколов-кандидатов
Правила	`rule_checker.py`, `rules_from_path.py`	482+ правил из catalog + PDF
Scoring	`compliance_engine.py`, `scoring.py`, `compliance_gate.py`	8 блоков, issues, gate_score, send_gate
Alignment	`consult_alignment.py`, `consult_criteria_enrichment.py`	Карточки «КЗ ↔ КП ↔ СОП клиники»
Evidence	`consult_evidence_pack.py`, `consult_l2_review.py`	Выдержки rich chunks только по matched paths
ЦИСЗ	`cisz_readiness.py`	Готовность FHIR Bundle до импорта
Поиск КП	`search_tiering.py`, `search_funnel.py`	Уровни S0 / S1 / S2

Оркестратор анализа: consult_analysis.analyze_consultation_text(). Уровни проверки КЗ: consult_tiering.py. Production pipeline с SSE: consult_review_pipeline.py.

2.1. Восемь блоков compliance (scoring КЗ)

Блок	Что проверяется
Оформление	Структура, реквизиты, подписи, даты
Диагноз	МКБ-10, формулировки, соответствие жалобам
Обследования	Назначенные исследования vs протокол
Лечение	Терапия, дозы, длительность
Безопасность	Противопоказания, red flags, взаимодействия
Наблюдение	Диспансеризация, контрольные визиты
Маршрутизация	Направления, уровень помощи
Документы	Полнота секций для ЦИСЗ / МИС

3. Блок III. Runtime, API и интерфейсы

3.1. Сервер приложения

Python 3.11+, FastAPI, uvicorn. Размещение: on-prem в контуре клиники или частного оператора (Docker). Учётные данные и веса моделей - только в защищённой конфигурации сервера, не в браузере.

3.2. Загрузка при старте

Фоновый поток load_data(): manifest чанков, protocols, meta, summary chunks, lex shards по путям. GET /health/live - liveness; GET /health - готовность индексов и tier-флаги.

3.3. Гибридный retrieve (поиск протоколов)

retrieve(): лексика + BM25 + routing boost + фильтр аудитории + опциональный rerank локальной embedder-моделью. Результат - топ фрагментов с цитатами (source_path, страница, chunk_id).

3.4. Интерфейсы

B2B index.html - проверка КЗ, поиск протоколов, кабинет методиста (?mode=methodist).
B2C patient.html - загрузка PDF КЗ, отчёт для пациента, tier-цены.

Логотипы: wordmark в шапке документов, mini-emblem в UI вкладок (см. protocol-logo-mini.svg).

4. Чанки: разметка, нарезка и использование в анализе

Чанк - атомарный фрагмент текста клинического протокола с метаданными. Именно чанки попадают в evidence_map отчёта («цитата из PDF, стр. N») и в retrieval при L1/L2.

4.1. Этапы rich-конвейера (`build_rich_chunks.py`)

Извлечение текста из PDF постранично; фильтр преамбулы постановления МЗ (is_preamble_block, filter_preamble_pages).
Разбиение на разделы (split_into_sections): заголовки ГЛАВА, ДИАГНОСТИКА, ЛЕЧЕНИЕ, нумерация «1.», «1.1.».
Нарезка раздела на чанки (split_section_into_chunks): сначала по нумерованным пунктам (POINT_RE), иначе по абзацам; лимит ~1200 символов, минимум ~80.
Классификация типа (guess_chunk_type) по заголовку секции и тексту.
Извлечение сущностей: МКБ-10, популяции, care_setting, лекарства, анализы, imaging, дозировки, severity, keywords.
Таблицы - отдельные чанки chunk_type=table с caption.
Overview-чанк (protocol_overview) - один на документ: оглавление, counts по типам.
Теги (build_chunk_tags в chunk_tags.py) - см. таблицу 4.3.
embedding_ready_text - нормализованная строка для локальной embedder-модели (заголовок + МКБ + текст).
Запись в rich_chunks.jsonl + паспорт протокола в rich_meta/{doc_id}.json.

4.2. Типы чанков (`chunk_type`)

Тип	Когда ставится	Использование
`protocol_overview`	Авто, 1 на PDF	Карточка протокола, навигация
`diagnostics`	Раздел диагностики, обследования	Блок «Обследования», evidence pack
`treatment`	Лечение, терапия	Блок «Лечение», правила required_exam
`criteria_block`	Показания / противопоказания	rule_checker, alignment
`drug_list`	Списки препаратов	Фармакотерапия, safety
`pharmacotherapy`	Фармакотерапия	Дозы, схемы
`algorithm`	Алгоритмы, схемы	Маршрутизация, L1 cards
`table`	Таблицы PDF	Структурированные критерии
`prevention`, `rehabilitation`, `dispensary`	Профилактика, реаб., диспансеризация	Блоки наблюдения / followup
`routing`	Маршрутизация, госпитализация	Уровень помощи
`classification`	Классификация, МКБ	Диагноз, ICD profile
`terms`, `body`	Определения, прочий текст	Низкий signal, fallback RAG

4.3. Метки чанка (`tags` в `chunk_tags.py`)

Поле	Значения	Смысл
`signal`	high / medium / low	Приоритет для retrieval и evidence pack
`obligation`	required, recommended, optional, contraindicated	Сила формулировки в протоколе
`clinical_intent`	diagnose, treat, monitor, refer, other	Зачем фрагмент в клиническом потоке
`care_setting`	ambulatory, inpatient, any	Где применимо
`is_preamble`	true / false	Исключить из scoring
`icd10_weights`	0-1 на код	Усиление релевантности по МКБ
`entities`	exam, drug	Нормализованные сущности для правил
`extractability`	rule_ready / narrative	Готовность к автоматическим правилам

4.4. Legacy-чанки (`build_chunks.py`)

Скользящее окно: 880 символов, перекрытие 120, только клиническая часть PDF (после clinical_start). Поле kind: diagnostic, treatment, general - по эвристике ключевых слов. Подходит для быстрого BM25; rich-чанки - для L1 alignment и цитат с типом секции.

4.5. Как чанки участвуют в анализе КЗ

КЗ → МКБ + match_protocol_cards → список source_path (1-5 PDF) → L0: правила catalog (без подгрузки всех чанков) → L1: rich chunks ТОЛЬКО по matched paths (consult_memory / lazy load) → consult_alignment + criteria_enrichment: цитаты + chunk_id + page → L2-lite: consult_evidence_pack фильтрует chunk_type + signal=high → evidence_map в отчёте (пациент / врач)

важно На tier L0 полный обход ~55k чанков не выполняется. Это ключ к масштабу 25 000+ КЗ/мес в якорной клинике.

5. Уровни проверки КЗ (L0, L1, L2, L3)

Уровень	Охват	Содержание	Время	LM / RAG
L0	100% КЗ в МИС	Парсинг + 8 блоков + send_gate + cisz_readiness	< 2 с	Нет
L1	UI по умолчанию; 10-20% в batch	L0 + alignment + СОП + rich chunks по matched PDF	5-15 с	Нет полного corpus RAG
L2-lite	2-5% / по кнопке	L1 + evidence pack + narrative (локальная LM)	15-30 с	Только matched paths
L2 full	Лаб / методслужба	Гибридный retrieve по корпусу + synthesize	30-90 с	On-prem LM, opt-in
L3	0.5-1%	Ручной аудит методиста по «красному» списку	-	Human-in-the-loop

5.1. Конвейер L1 (основной для врача)

PDF / FHIR Bundle / текст → consult_parser → ConsultationDocument → diagnosis_icd + protocol_match → analyze_consultation_text → 8 блоков + issues → consult_alignment (КЗ ↔ КП ↔ СОП) → consult_criteria_enrichment → compliance_gate: gate_score, send_gate → cisz_readiness + HTML/MD отчёт

5.2. send_gate и gate_score

gate_score = min(клинический scoring, cisz_score). Режимы МИС: inform, soft_gate, hard_gate, critical_only - политика учреждения, не жёсткое требование Protocol.

6. Уровни поиска протоколов (S0, S1, S2)

Уровень	Когда	Механизм
S0	Известен МКБ	Каталог + фильтры, без retrieve
S1	Default в UI	retrieve (lex + BM25) на lazy index, без narrative LM
S2	Сложный запрос	S1 + уточнение запроса и пояснение локальной LM

7. Семантический слой (локальные модели, 5 фаз)

on-prem ML Аддитивный контур поверх lex+BM25+rules. Scoring и send_gate не заменяются.

Фаза	Артефакт	Эффект
1	Офлайн-эмбеддинги чанков (`build_chunk_embeddings.py`)	Один forward pass на запрос вместо пула сотен
2	Vector index (`build_vector_index.py`)	Top-K векторов → lex/BM25 → rerank
3	Semantic rule fallback	Синонимы для required_exam после substring-match
4	consult_tiering L0/L1/L2	100% КЗ без LM; LM только на L2-lite/full
5	Batch enrichment правил	LM-assisted извлечение structured rules → rule_checker

Дообучение: каталог ml/, feedback data/ml/feedback/, экспорт export_training_feedback.py. Embedder fine-tune on-prem; в production - manifest моделей ml/registry/.

8. Интеграция с МИС и ЦИСЗ (целевой этап)

Система	Роль
ЦИСЗ	FHIR BY, структура Bundle, НСИ, импорт пакета
Protocol	Клиническое соответствие содержания КЗ протоколам (ориентир, не МЭЭ)
МИС	Формирование КЗ, вызов Protocol до ЭЦП, UI врача

Врач заполняет КЗ в МИС → FHIR Bundle → POST /api/consult-review (tier=L0) на локальном Protocol → send_gate / отчёт → ЭЦП → импорт в ЦИСЗ

Подробнее: architecture-kravira-fhir-mis-print.html (PDF: architecture-kravira-fhir-mis.pdf).

9. B2C patient.html

Отдельный контур для физлиц: загрузка PDF, tier L1, sanitize ответа, ERIP. Тот же scoring и evidence_map, упрощённый язык. См. docs/architecture-b2c-patient.md.

10. Глоссарий

Protocol: Платформа контроля качества КЗ и навигации по КП Минздрава РБ. Бренд продукта; якорный пилот - МЦ «Кравира».
КЗ (консультативное заключение): Текстовый медицинский документ по итогам приёма; объект проверки в B2B/B2C.
КП (клинический протокол): Официальный PDF Минздрава с диагностикой, лечением, критериями.
Чанк (chunk): Фрагмент текста протокола с chunk_id, chunk_type, метками и привязкой к странице PDF.
Rich chunk: Смысловой чанк из build_rich_chunks.py с сущностями, tags и embedding_ready_text.
Legacy chunk: Скользящее окно 880 символов для BM25; поле kind: diagnostic / treatment / general.
source_path: Относительный путь к PDF в minzdrav_protocols/ - ключ связи правил, чанков и UI.
evidence_map: Набор цитат из протокола в отчёте: текст, страница, chunk_id, блок compliance.
8 блоков compliance: Оформление, диагноз, обследования, лечение, безопасность, наблюдение, маршрутизация, документы.
gate_score: Итоговый процент соответствия; минимум из клинического scoring и cisz_score.
send_gate: Рекомендация: allow / warn / block перед подписью ЭЦП (политика МИС).
L0 / L1 / L2 / L3: Уровни глубины проверки КЗ: от мгновенного скрининга до ручного аудита (см. раздел 5).
L2-lite: L1 + evidence pack по matched paths + краткий narrative; без полного RAG по всему корпусу.
S0 / S1 / S2: Уровни поиска протоколов: каталог → retrieve → retrieve + LM-пояснение.
alignment card: Карточка сопоставления факта из КЗ с пунктом КП и чек-листом СОП клиники.
rule_checker: Детерминированная проверка 482+ правил из catalog и PDF.
lazy chunk store: Чанки читаются с диска по manifest при запросе path, не все в RAM.
LM-слой (языковая модель): Локально развёрнутая доработанная модель для rerank, narrative, enrichment. Не участвует в L0.
embedder: Локальная модель векторизации текста; fine-tune на парах «запрос - фрагмент КП» (каталог ml/).
RAG: Retrieval-Augmented Generation: поиск чанков + опциональный синтез ответа LM.
BM25 / lex shard: Лексический индекс по подмножеству протоколов (path-scoped) для быстрого retrieve.
ЦИСЗ / FHIR BY: Государственный контур электронного здравоохранения; Protocol проверяет клинику, ЦИСЗ - упаковку данных.
patient.html: B2C витрина «Проверь КЗ» для физлиц.
Методслужба: Режим UI с workbench, feedback, ML-отчётами; human-in-the-loop для правил и шаблонов.

11. Заключение

Protocol объединяет три блока: подготовленный корпус с размеченными чанками, детерминированное ядро clinical_knowledge и runtime с tier L0-L2. Масштаб на поток 25 000+ КЗ/мес достижим за счёт L0 на каждом сохранении, выборочного L1/L2 и lazy-загрузки чанков только по релевантным протоколам.

Развёртывание проектируется локально: сервер в контуре клиники, доработанные модели on-prem, без обязательной зависимости от внешних облачных API. Интеграция с МИС - до подписи ЭЦП; ЦИСЗ остаётся контролёром структуры данных, Protocol - ориентиром клинического качества по официальным протоколам.

Protocol · Документ для внутреннего использования, методслужбы и интеграторов МИС. Связанные файлы: architecture-kravira-fhir-mis.pdf, mvp-presentation.html, docs/project-docs-maintenance.md.