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.
- Откройте @BotFather.
- Выполните
/newbot, задайте имя и username. - Сохраните выданный токен в
TELEGRAM_BOT_TOKEN. - Установите аватар:
- отправьте BotFather команду
/setuserpic; - выберите созданного бота;
- загрузите файл
icon.png.
- отправьте BotFather команду
Telegram Bot API не позволяет программно менять фотографию профиля бота, поэтому этот шаг выполняется через BotFather один раз.
Создайте рабочий конфигурационный файл:
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-репозиторий.
Откройте 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.exeStart-Process `
-FilePath ".\.venv\Scripts\miocard-bot.exe" `
-WorkingDirectory (Get-Location) `
-WindowStyle HiddenСоберите и запустите контейнер:
docker compose up --build -dПосмотреть журнал:
docker compose logs -f botПерезапустить:
docker compose restart botОстановить:
docker compose downБоту достаточно исходящих HTTPS-соединений: он работает через long polling, поэтому домен, TLS-сертификат и открытые входящие порты не нужны. Проверенная конфигурация — 1 vCPU, 2 ГБ RAM, 15 ГБ диска.
Скопируйте и запустите скрипт провижининга от 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.
.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"С рабочей машины:
.\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 тоже вернёт ненулевой код,
так что неудачный деплой не останется незамеченным.
Деплоится именно закоммиченная ревизия, поэтому незакоммиченные изменения на сервер не попадут; скрипт предупреждает об этом.
Telegram отдаёт обновления только одному getUpdates-клиенту. Перед первым
деплоем остановите локальный экземпляр бота на рабочей машине, иначе оба
процесса будут перехватывать друг у друга обновления и в журнале появится
TelegramConflictError.
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- Откройте созданного Telegram-бота.
- Нажмите Start или отправьте
/start. - Пришлите полный снимок ЭКГ как фотографию или, предпочтительно, как файл.
- При необходимости добавьте обезличенный контекст в подпись: возраст, пол, симптомы, препараты, а также прошлые осмотры и заключения предыдущих ЭКГ для оценки динамики.
- Дождитесь текстового отчёта и размеченной копии снимка.
Команды:
| Команда | Доступ | Назначение |
|---|---|---|
/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-провайдеру.
Ключ 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.
Это может быть ограничение частоты, выходного лимита или пакетного баланса API-провайдера. Проверьте служебное сообщение модератора и состояние ключа.
Такой конфликт означает, что тот же Telegram-токен используется ещё одним polling-процессом. Локальные экземпляры из этой установки теперь сменяют друг друга автоматически. Если ошибка повторяется, бот запущен на другой машине или из другой копии старой версии проекта: остановите её либо перевыпустите токен у BotFather.
Настройки читаются при запуске. Полностью перезапустите локальный процесс или контейнер.
Убедитесь, что существует файл
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