Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Miocard Bot

Miocard Bot

Telegram-помощник для предварительного разбора фотографий 12-канальной ЭКГ.

Warning

Это прототип системы поддержки врача, а не медицинское изделие и не источник окончательного диагноза. Перед клиническим применением необходимы отдельная валидация, локальная модель и проверка требований к медицинским данным.

Возможности

  • Принимает фотографии и файлы PNG/JPEG/WebP через Telegram.
  • Исправляет EXIF-ориентацию и небольшой наклон, убирает пустые поля и при необходимости мягко повышает контраст.
  • Ограничивает разрешение изображения под визуальный токен-бюджет модели.
  • Измеряет шаг миллиметровой сетки по самому снимку и передаёт его модели, чтобы оценка ЧСС и интервалов не опиралась на клетки «на глаз».
  • Одним API-запросом распознаёт отведения, калибровку и формирует отчёт по строгой JSON-схеме.
  • Держит постоянную часть промпта в кэшируемом системном префиксе.
  • Использует компактные ключи в структурированном ответе модели, а понятные названия разделов восстанавливает локально перед отправкой пользователю.
  • Ищет единичные аномальные комплексы по всей ширине записи.
  • Возвращает до трёх локализованных находок и рисует связанные рамки [1], [2], [3] на копии снимка.
  • Присылает сначала короткое сообщение с выводом и срочными признаками, а подробности — отдельно, со свёрнутыми блоками параметров и ограничений.
  • Прикладывает к ответу PDF с полным структурированным разбором и ЭКГ; найденные локализуемые отклонения показываются на изображении внутри документа.
  • При наличии отметок дополнительно прикрепляет к тому же результату отдельную размеченную ЭКГ для быстрого просмотра в Telegram. Под изображением приводится соответствие каждой отметки конкретному наблюдению; такая же таблица находится непосредственно под ЭКГ в PDF.
  • Не сокращает отчёт многоточиями: длинный результат делится на несколько Telegram-сообщений.
  • Показывает дисклеймер один раз в /start.
  • Кэширует только готовый отчёт; повторный одинаковый запрос не расходует API-токены.
  • Позволяет модераторам менять модель через /model.
  • Показывает модераторам остаток пакета и статистику токенов через /usage.
  • Показывает историю изменений всем разрешённым пользователям через /updates.
  • Позволяет начать обращение к модераторам через /support или кнопку жалобы под конкретным результатом ЭКГ. Случайные сообщения в поддержку не уходят.
  • Отправляет описание новой версии каждому пользователю только один раз, даже если бот перезапускается.
  • В тестовом режиме отправляет модераторам исходную ЭКГ, контекст, точный ответ бота и расход каждого анализа.
  • Позволяет отключить передачу ЭКГ и ответов в журнал, сохранив только сведения о пользователе, времени, модели, статусе и расходе.

Требования

Для локального запуска:

  • Windows 10/11;
  • Python 3.11 или новее (рекомендуется Python 3.12);
  • токен Telegram-бота;
  • совместимый API-ключ;
  • доступ в интернет.

Альтернатива: Docker Desktop с Docker Compose.

1. Настройка Telegram-бота

  1. Откройте @BotFather.
  2. Выполните /newbot, задайте имя и username.
  3. Сохраните выданный токен в TELEGRAM_BOT_TOKEN.
  4. Установите аватар:
    • отправьте BotFather команду /setuserpic;
    • выберите созданного бота;
    • загрузите файл icon.png.

Telegram Bot API не позволяет программно менять фотографию профиля бота, поэтому этот шаг выполняется через BotFather один раз.

2. Настройка .env

Создайте рабочий конфигурационный файл:

Copy-Item .env.example .env

Откройте .env и заполните как минимум:

TELEGRAM_BOT_TOKEN=123456789:telegram_token
ANTHROPIC_API_KEY=sk-fp-tokenator_key
ANTHROPIC_MODEL=gpt-5.6-sol

MODERATOR_USER_IDS=153241307
ALLOWED_USER_IDS=2053404449

Несколько Telegram ID перечисляются через запятую:

MODERATOR_USER_IDS=153241307,987654321
ALLOWED_USER_IDS=2053404449,123456789

Модераторы автоматически имеют доступ к боту и не должны дублироваться в ALLOWED_USER_IDS. Если ALLOWED_USER_IDS оставить пустым, бот будет доступен всем пользователям.

Параметры конфигурации

Переменная Назначение Значение по умолчанию
TELEGRAM_BOT_TOKEN Токен от BotFather обязательно
ANTHROPIC_API_KEY Ключ Anthropic или Tokenator sk-fp-… обязательно
ANTHROPIC_MODEL Модель анализа gpt-5.6-sol
ANTHROPIC_API_URL Собственный Anthropic-совместимый endpoint определяется автоматически
ANTHROPIC_EFFORT Effort основного разбора (прямой Anthropic) high
ANTHROPIC_SCOUT_EFFORT Effort прохода по увеличенным фрагментам low
ANTHROPIC_THINKING_ENABLED Рассуждение модели перед ответом true
ANTHROPIC_MAX_TOKENS Максимум выходных токенов основного запроса 16000
ANTHROPIC_SCOUT_MAX_TOKENS Максимум выходных токенов на фрагмент 4096
ANTHROPIC_TIMEOUT_SECONDS Таймаут ожидания ответа API 300
PROMPT_CACHE_ENABLED Кэш постоянной части промпта (прямой Anthropic) true
MODERATOR_USER_IDS Модераторы: /model, статистика и автоматический доступ пусто
ADMIN_AUDIT_INCLUDE_CONTENT Добавлять исходную ЭКГ, контекст и ответ в журнал модераторов true
ALLOWED_USER_IDS Разрешённые обычные пользователи пусто = доступ всем
MAX_IMAGE_BYTES Максимальный размер изображения 20971520
MAX_CONCURRENT_ANALYSES Число параллельных анализов 1
USER_COOLDOWN_SECONDS Пауза между запросами одного пользователя 10
ANALYSIS_CACHE_ENABLED Постоянный кэш готовых отчётов false
ANALYSIS_CACHE_DIR Каталог кэша .cache/miocard
SUPPORT_DB_FILE Файл служебных маршрутов поддержки без текста сообщений .cache/miocard/support.sqlite3

Не публикуйте .env и не вставляйте реальные ключи в README, сообщения или Git-репозиторий.

3. Локальный запуск в Windows

Откройте PowerShell в каталоге проекта:

cd C:\Users\Admin\Documents\Miocard

Создайте виртуальное окружение и установите приложение:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Запустите бот:

.\.venv\Scripts\miocard-bot.exe

Окно PowerShell должно оставаться открытым. Для остановки нажмите Ctrl+C. После изменения .env или исходного кода перезапустите процесс.

Если на этом компьютере уже работает экземпляр с тем же Telegram-токеном, повторный запуск попросит его завершиться, дождётся остановки и займёт его место. Экземпляр на другой машине таким способом остановить нельзя.

Приложение автоматически находит .env в корне проекта, поэтому после установки допустим и запуск непосредственно из каталога скриптов:

cd C:\Users\Admin\Documents\Miocard\.venv\Scripts
.\miocard-bot.exe

Запуск в фоне

Start-Process `
  -FilePath ".\.venv\Scripts\miocard-bot.exe" `
  -WorkingDirectory (Get-Location) `
  -WindowStyle Hidden

4. Запуск через Docker

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

docker compose up --build -d

Посмотреть журнал:

docker compose logs -f bot

Перезапустить:

docker compose restart bot

Остановить:

docker compose down

5. Деплой на сервер Ubuntu 24.04

Боту достаточно исходящих HTTPS-соединений: он работает через long polling, поэтому домен, TLS-сертификат и открытые входящие порты не нужны. Проверенная конфигурация — 1 vCPU, 2 ГБ RAM, 15 ГБ диска.

5.1. Разовая подготовка сервера

Скопируйте и запустите скрипт провижининга от root:

scp scripts/server-setup.sh root@<ip-сервера>:/root/
ssh root@<ip-сервера> "bash /root/server-setup.sh"

Скрипт ставит Docker Engine с плагином Compose, добавляет 2 ГБ swap (сборка образа на 2 ГБ RAM идёт впритык), создаёт каталог деплоя /srv/miocard с томом состояния /srv/miocard/data, владельцем которого делает uid 10001 — пользователя контейнера, — и поднимает bare-репозиторий /srv/miocard.git с хуком post-receive.

5.2. Конфигурация на сервере

.env содержит секреты и не попадает в git, поэтому его нужно передать один раз вручную:

scp .env root@<ip-сервера>:/srv/miocard/.env

Для продуктивной установки поставьте в этом файле ADMIN_AUDIT_INCLUDE_CONTENT=false, чтобы снимки ЭКГ и ответы бота не оседали в журнале модератора.

Пути к состоянию задавать не нужно: compose.yaml переопределяет ANALYSIS_CACHE_DIR, RELEASE_NOTIFICATION_STATE_FILE и SUPPORT_DB_FILE на том /data. Внутри образа пакет установлен в site-packages, поэтому вычисленный от него PROJECT_ROOT указывает на каталог, недоступный для записи; без этого переопределения база обращений в поддержку и отметки о разосланных релиз-нотах не создались бы.

Убедитесь, что с сервера доступны нужные API:

ssh root@<ip-сервера> "curl -sS -o /dev/null -w 'telegram %{http_code}\n' https://api.telegram.org; curl -sS -o /dev/null -w 'api %{http_code}\n' https://api.tokenator.cloud"

5.3. Первый и последующие деплои

С рабочей машины:

.\scripts\deploy.ps1 -Server root@<ip-сервера>

Параметр -Server нужен только при первом запуске: скрипт создаёт git-remote server, дальше достаточно .\scripts\deploy.ps1. Перед отправкой выполняются ruff check и pytest; пропустить их можно флагом -SkipTests.

Скрипт отправляет текущий коммит в /srv/miocard.git, а хук post-receive на сервере выкладывает эту ревизию в /srv/miocard, выполняет docker compose up -d --build, чистит старые образы и проверяет, что контейнер жив через 10 секунд после старта. Если контейнер упал, хук печатает последние строки журнала и завершается с ошибкой — git push тоже вернёт ненулевой код, так что неудачный деплой не останется незамеченным.

Деплоится именно закоммиченная ревизия, поэтому незакоммиченные изменения на сервер не попадут; скрипт предупреждает об этом.

5.4. Один polling-процесс на токен

Telegram отдаёт обновления только одному getUpdates-клиенту. Перед первым деплоем остановите локальный экземпляр бота на рабочей машине, иначе оба процесса будут перехватывать друг у друга обновления и в журнале появится TelegramConflictError.

5.5. Эксплуатация

ssh root@<ip-сервера> "cd /srv/miocard && docker compose logs -f --tail 100 bot"
ssh root@<ip-сервера> "cd /srv/miocard && docker compose restart bot"
ssh root@<ip-сервера> "cd /srv/miocard && docker compose down"

Журналы Docker ограничены тремя файлами по 10 МБ, так что 15 ГБ диска они не займут. Состояние бота целиком лежит в /srv/miocard/data, поэтому резервная копия — это копия этого каталога и файла /srv/miocard/.env:

ssh root@<ip-сервера> "tar czf - -C /srv/miocard data .env" > miocard-backup.tar.gz

Использование

  1. Откройте созданного Telegram-бота.
  2. Нажмите Start или отправьте /start.
  3. Пришлите полный снимок ЭКГ как фотографию или, предпочтительно, как файл.
  4. При необходимости добавьте обезличенный контекст в подпись: возраст, пол, симптомы, препараты, а также прошлые осмотры и заключения предыдущих ЭКГ для оценки динамики.
  5. Дождитесь текстового отчёта и размеченной копии снимка.

Команды:

Команда Доступ Назначение
/start все разрешённые пользователи приветствие и правила
/help все разрешённые пользователи справка
/support все разрешённые пользователи начать обращение к модераторам
/cancel все разрешённые пользователи отменить начатое обращение
/updates все разрешённые пользователи полная история версий
/prompt модераторы и Мария скачать текущий рабочий промпт анализа
/model только модераторы глобальный выбор модели
/usage только модераторы остаток пакета и статистика токенов
/announce <текст> только модераторы разослать сообщение всем известным пользователям бота
/shutdown только модераторы уведомить всех пользователей и остановить бота

/announce рассылает произвольный текст всем пользователям, с которыми бот хоть раз взаимодействовал (плюс все ID из MODERATOR_USER_IDS и ALLOWED_USER_IDS), кроме самого модератора, который отправил команду. Список получателей ведётся автоматически и переживает перезапуск бота, так как хранится в SUPPORT_DB_FILE.

/shutdown сначала рассылает всем известным пользователям сообщение о том, что бот временно остановлен, и только после этого завершает процесс. Если бот запущен через Docker/systemd с автоматическим перезапуском, он снова поднимется штатным образом — /shutdown останавливает текущий процесс, а не отключает автозапуск на сервере.

/usage показывает общий запас, использованные и оставшиеся токены пакета Tokenator, а также накопленную с момента запуска бота статистику: число разборов и попаданий в кэш, количество API-запросов и ошибок, входящие и исходящие токены и разбивку по моделям. Разделение на входящие и исходящие токены ведётся локально, потому что шлюз отдаёт только один общий счётчик; после перезапуска бота эта часть статистики обнуляется.

После /support пользователь выбирает причину и отправляет одно сообщение — текст, пересланное сообщение, фотографию или документ. Под каждым результатом ЭКГ также есть кнопки «Ошибка анализа» и «Неверный результат», привязанные к этому анализу. Модератор отвечает через функцию Telegram «Ответить». Если пользователь продолжает диалог таким же способом, ответ получает только тот модератор, который ему написал. В базе сохраняются идентификаторы маршрутов, категории и время, но не содержание сообщений поддержки.

Поддерживаемые варианты в /model:

  • Sol — gpt-5.6-sol;
  • Terra — gpt-5.6-terra;
  • Opus — claude-opus-5;
  • Opus 4.8 — claude-opus-4-8;
  • Sonnet — claude-sonnet-5;
  • Flash — gemini-3.5-flash;
  • Fable — claude-fable-5.

Выбранная через /model модель действует для всех новых запросов до перезапуска. После перезапуска снова используется ANTHROPIC_MODEL из .env.

Правила разбора

Системный промпт вынесен в src/miocard/analyze.md и загружается при импорте miocard.prompt. Сама спецификация написана по-английски, но требует, чтобы весь пользовательский текст отчёта модель возвращала по-русски. Плейсхолдер {non_ecg_impression} подставляется из NON_ECG_IMPRESSION; без него загрузка падает с ошибкой.

Файл можно править без изменения кода: достаточно перезапустить бота. Текст промпта входит в ключ кэша разборов, поэтому после правки прошлые ответы из кэша не переиспользуются.

Как подготовить изображение

  • Отправляйте весь лист целиком.
  • Лучше использовать режим файл, чтобы Telegram не пережимал изображение.
  • Избегайте перспективного наклона, бликов, теней и закрытых краёв.
  • На снимке должны читаться отведения, сетка, скорость и усиление.
  • Не добавляйте ФИО и другие прямые идентификаторы пациента.

Исходный файл обрабатывается в памяти. Локальный кэш содержит только структурированный отчёт, но изображение всё равно передаётся через Telegram и настроенному внешнему API-провайдеру.

Tokenator

Ключ sk-fp-… автоматически включает endpoint:

https://api.tokenator.cloud/anthropic/v1/messages

Для экономии выходного лимита бот отключает reasoning и streaming. После каждого анализа модераторам отправляются:

  • исходящие токены ответа модели;
  • фактическое изменение пакетного баланса;
  • использованный и оставшийся объём пакета.

Для повторного идентичного запроса кэш возвращает готовый отчёт с расходом 0.

Журнал тестирования

После каждого принятого анализа каждому ID из MODERATOR_USER_IDS приходит одно сообщение: PDF-отчёт с карточкой журнала в подписи — пользователь, время, модель, результат и расход токенов. При ADMIN_AUDIT_INCLUDE_CONTENT=true PDF содержит контекст, полный структурированный разбор и ЭКГ с разметкой, но не показывает название модели. Telegram-чат модератора служит журналом; отдельные копии изображений на диске бот не создаёт.

Для продакшена установите:

ADMIN_AUDIT_INCLUDE_CONTENT=false

После перезапуска в журнале останутся только метаданные и расход. Сами ЭКГ и тексты ответов модераторам пересылаться не будут.

Проверка

Запустить тесты:

.\.venv\Scripts\python.exe -m pytest -q

Проверить стиль:

.\.venv\Scripts\python.exe -m ruff check .

Частые проблемы

Бот не отвечает

  • Проверьте TELEGRAM_BOT_TOKEN.
  • Убедитесь, что ID пользователя находится в ALLOWED_USER_IDS или MODERATOR_USER_IDS.
  • Проверьте, не запущено ли одновременно несколько экземпляров бота.
  • Посмотрите ошибки в окне PowerShell или через docker compose logs -f bot.

429 Too Many Requests

Это может быть ограничение частоты, выходного лимита или пакетного баланса API-провайдера. Проверьте служебное сообщение модератора и состояние ключа.

TelegramConflictError: terminated by other getUpdates request

Такой конфликт означает, что тот же Telegram-токен используется ещё одним polling-процессом. Локальные экземпляры из этой установки теперь сменяют друг друга автоматически. Если ошибка повторяется, бот запущен на другой машине или из другой копии старой версии проекта: остановите её либо перевыпустите токен у BotFather.

Изменения .env не применились

Настройки читаются при запуске. Полностью перезапустите локальный процесс или контейнер.

telegram_bot_token / anthropic_api_key: Field required

Убедитесь, что существует файл C:\Users\Admin\Documents\Miocard\.env и в нём заполнены TELEGRAM_BOT_TOKEN и ANTHROPIC_API_KEY. Бот ищет этот файл независимо от текущего каталога PowerShell.

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

Miocard/
├── icon.png
├── src/miocard/
│   ├── analyze.md            # спецификация разбора (системный промпт)
│   ├── anthropic_client.py   # API, кэш и баланс токенов
│   ├── bot.py                # Telegram handlers
│   ├── config.py             # переменные окружения
│   ├── formatting.py         # Telegram-отчёт
│   ├── imaging.py            # обработка и разметка изображения
│   ├── models.py             # строгая JSON-схема
│   └── prompt.py             # загрузка analyze.md и запрос пользователя
├── scripts/
│   ├── deploy.ps1            # проверки и push-деплой с рабочей машины
│   └── server-setup.sh       # разовая подготовка сервера Ubuntu
├── tests/
├── .dockerignore
├── .env.example
├── compose.yaml
├── Dockerfile
└── pyproject.toml

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages