Skip to content

ADR — Архитектурные решения

Реестр архитектурных решений (Architecture Decision Records) системы помощи в принятии решений врачам в диагностике заболеваний на базе RAG + LLM.

Правила ведения

  • Каждое значимое архитектурное решение фиксируется отдельной записью с порядковым номером ADR-XXXX.
  • Решение не меняется задним числом — отменённое решение помечается как Отменено со ссылкой на новое (см. шаблон).
  • Новые записи добавляются в конец файла, индекс ниже обновляется.

Статусы:

Статус Значение
Принято Решение используется в системе
Предложено Решение обсуждается / не окончательное
Отменено Решение заменено другим (указано в Заменено на)

Индекс

Номер Решение Статус
ADR-0001 RAG как основа генерации ответов Принято
ADR-0002 Hybrid-поиск в OpenSearch Принято
ADR-0003 Стэк LLM: LiteLLM + vLLM Принято
ADR-0004 FastAPI как backend-фреймворк Принято
ADR-0005 React как frontend Принято
ADR-0006 Брокер сообщений: Kafka или NATS Предложено
ADR-0007 Данные из открытых источников США и Европы Принято
ADR-0008 Загрузка результатов анализов пациентами Принято
ADR-0009 Телеметрия медицинских устройств Предложено

ADR-0001: RAG как основа генерации ответов

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Система помогает врачам в диагностике. Ответы LLM должны быть обоснованы проверенными медицинскими данными (истории болезней, медикаменты, клинические руководства), а не «выдуманы» моделью.

Решение. Использовать RAG (Retrieval-Augmented Generation): на запрос врача сначала выполняется retrieval релевантных документов из индекса, затем LLM генерирует ответ строго по собранным фрагментам контекста.

Последствия.

  • Ответы сопровождаются ссылками на источники (Citation Tracker) — обязательное требование для медицинской домены.
  • Необходимы компоненты: Hybrid Retriever, Reranker, Context Builder, Citation Tracker (см. Компонентная диаграмма).
  • Качество ответов сильно зависит от качества индекса и retriever'а — это точка непрерывной работы.

ADR-0002: Hybrid-поиск в OpenSearch

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Нужно искать по корпусу текстов медицинских документов: термины, названия препаратов (точные совпадения) и смысловые запросы (семантика).

Решение. Использовать OpenSearch с hybrid search (BM25 + векторный поиск) как основной механизм retrieval.

Последствия.

  • OpenSearch становится отдельным контейнером инфраструктуры (см. Контейнерная диаграмма).
  • Требуется pipeline индексации документов (см. ADR-0007) и генерации эмбеддингов.
  • Реранжирование кандидатов выполняется отдельным Reranker (ADR-0001).

ADR-0003: Стэк LLM: LiteLLM + vLLM

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Нужна работающая генерация LLM с возможностью использовать как локальные (on-premise) модели, так и облачные провайдеры; медицинская доменная чувствительность требует возможности контроля, где обрабатываются данные.

Решение. Использовать vLLM как движок инференса локальных моделей и LiteLLM как унифицирующий слой/провайдер для переключения между локальным инференсом и внешними LLM API.

Последствия.

  • LLM Service выделен как отдельный контейнер (см. Контейнерная диаграмма).
  • Есть зависимость от доступности GPU-инфраструктуры для vLLM.
  • Выбор конкретных моделей и контекстных окон — отдельное решение, пока не зафиксировано.

ADR-0004: FastAPI как backend-фреймворк

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Нужен API-слой для аутентификации, валидации запросов врачей/пациентов, оркестрации RAG-конвейера и асинхронных задач.

Решение. Использовать FastAPI (Python) как основной API-фреймворк.

Последствия.

  • RAG Engine, Web Search Adapter и остальные Python-компоненты естественно стыкуются с API-слоем.
  • Типизация запросов/ответов (Pydantic) упрощает контракт API.
  • Python 3.x становится основным языком backend-части.

ADR-0005: React как frontend

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Нужен UI для двух ролей — врач (запросы, просмотр ответов с цитатами) и пациент (загрузка анализов и данных).

Решение. Использовать React для frontend-части.

Последствия.

  • Один фронтенд-контейнер обслуживает обе роли; разграничение по ролям — на уровне API/пермишенов.
  • Фронтенд общается только с FastAPI Gateway по HTTPS.

ADR-0006: Брокер сообщений: Kafka или NATS

  • Статус: Предложено (не финализирован)
  • Дата: 2026-09-30

Контекст. В системе есть асинхронные потоки: события из API, фоновые задачи RAG (индексация, генерация эмбеддингов), в перспективе — телеметрия медицинских устройств (ADR-0009).

Решение. Брокер сообщений выбран как часть архитектуры, но конкретная технология (Kafka или NATS) пока не зафиксирована.

Открытые вопросы для выбора:

  • Нужна ли долговременная репликация событий (Kafka — да; NATS JetStream — частично)?
  • Какой ожидаемый throughput и задержка?
  • Сложность эксплуатации (Kafka тяжелее, NATS легче).
  • Требования к ordering/guarantees доставки.

Последствия (пока).

  • В диаграммах брокер обозначен как абстракция «Kafka/NATS» (см. Контейнерная диаграмма).
  • До выбора технологии API-слой не должен напрямую зависеть от конкретного протокола брокера (изолировать за интерфейсом).

ADR-0007: Данные из открытых источников США и Европы

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Для RAG нужен корпус медицинских данных: истории болезней, справочники по медикаментам, клинические руководства.

Решение. В качестве источников использовать открытые медицинские данные США и Европы (open data): истории болезней, препараты, клинические рекомендации.

Последствия.

  • Требуется pipeline загрузки и индексации в OpenSearch (см. ADR-0002).
  • Необходим учёт лицензий/прав на использование данных (медицинские данные могут быть чувствительными).
  • Языковой аспект: значительная часть данных — англоязычные (США/Европа) — влияет на качество эмбеддингов и генерации.

ADR-0008: Загрузка результатов анализов пациентами

  • Статус: Принято
  • Дата: 2026-09-30

Контекст. Врач при диагностике опирается не только на общие медицинские данные, но и на конкретные результаты анализов пациента.

Решение. Предоставить пациентам возможность загружать результаты своих анализов; эти данные используются как дополнительный контекст при диагностике.

Последствия.

  • Нужен механизм загрузки (файлы, структура данных) и хранения.
  • Привязка данных к пациенту/врачу — вопросы безопасности и приватности (см. ADR-0007).
  • Расширение области RAG: retrieval может учитывать и загруженные анализы, а не только общие медицинские документы.

ADR-0009: Телеметрия медицинских устройств

  • Статус: Предложено (отложено на дальнейшую разработку)
  • Дата: 2026-09-30

Контекст. Планируется приём данных с индивидуальных медицинских устройств (носимые гаджеты, мониторинговые датчики) как дополнительный источник контекста для диагностики.

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

Открытые вопросы:

  • Протокол передачи (MQTT? HTTPS? через Kafka?).
  • Аутентификация устройств.
  • Частота и объём телеметрии (влияет на выбор брокера, см. ADR-0006).
  • Хранение временных рядов (OpenSearch / Timescale / другое).

Последствия.

  • В Контекстной диаграмме «Медицинские устройства» вынесены как внешняя система с пометкой «future».
  • Брокер сообщений (ADR-0006) должен быть способен принимать потоковые события — это аргумент в пользу Kafka, если телеметрия станет приоритетом.

Шаблон ADR

## ADR-XXXX: Краткое название

- **Статус:** Принято | Предложено | Отменено
- **Дата:** ГГГГ-ММ-ДД
- **Заменено на:** ADR-YYYY *(если статус = Отменено)*

**Контекст.** Ситуация, проблема, требования.

**Решение.** Что принято.

**Последствия.** Что это даёт, какие ограничения, влияние на другие компоненты.