SaqtaDauys

Страховой ассистент, с которым можно говорить своими словами.
Хакатонный прототип для кейса Voice Router · Saqta Insurance

Запустить · Показать жюри · Архитектура · Результаты

Python 3.10+   gpt-4o-mini   RU · KK · mixed   Web + Telegram

«Можно своими словами?» — Именно так и задумано.

Что мы делаем

«Запишите меня к лору. И ещё скажите, покроет ли страховка лекарства» — в одной реплике уже две просьбы. Клиент может передумать, сменить язык или вернуться к предыдущему вопросу. Голосовому роботу нужно понимать такой разговор и выбирать подходящий сценарий обслуживания.

SaqtaDauys соединяет LLM-маршрутизатор с диалоговым движком на Python. Модель разбирает речь и выбирает намерения; движок уточняет данные, проверяет полис, ведёт очередь вопросов и запрашивает подтверждение перед действием. Основное демо — микрофон и голосовой ответ в браузере, рядом панель супервизора. Также доступны Telegram-бот и текстовый чат в терминале.

Статус: хакатонный прототип. Клиенты, полисы и операции учебные. Результат маршрутизации на dev-наборе — 100%; свободный диалог ещё требует доработки.

За минуту для жюри

Показ на 3–4 минуты: приветствие → запись к врачу → смена темы → возврат к задаче → подтверждение. Реплики и пояснения для выступления уже подготовлены; для оценки можно задавать и свои вопросы.

Что можно попробовать

Одна реплика — несколько задач

Иллюстрация работы с несколькими намерениями, а не запись конкретного прогона. SC21 отвечает за запись к врачу, SC22 — за проверку покрытия. Вторая просьба остаётся в очереди; перед выполнением записи движок запрашивает согласие.

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

Выберите удобный вход

Один движок диалога, три способа поговорить с ним. Команды выполняются после подготовки окружения; данные для первого разговора — ниже.

_{Сеансы разных интерфейсов независимы: разговор из браузера не переносится в Telegram.}

Быстрый старт

Нужны Python 3.10+, интернет и ключ OpenAI API. Для браузера и текстового чата достаточно ключа OpenAI; токен нужен только Telegram. Команды ниже выполняются из корня проекта.

1. Подготовить окружение

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Если .env ещё нет, скопируйте шаблон:

cp -n .env.example .env

Заполните файл своими значениями. Существующие ключи менять не нужно.

OPENAI_API_KEY=ваш_ключ_OpenAI
TELEGRAM_BOT_TOKEN=токен_от_BotFather
TELEGRAM_ALLOWED_USER_IDS=

Токен Telegram выдаёт @BotFather по команде /newbot. Пустой TELEGRAM_ALLOWED_USER_IDS разрешает доступ всем, кто напишет боту. Чтобы оставить доступ команде, узнайте ID через /id, перечислите их через запятую и перезапустите процесс. Файл .env исключён из Git.

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
if (!(Test-Path .env)) { Copy-Item .env.example .env }

2. Открыть голосовое веб-демо

python src/web_demo.py

Откройте http://localhost:8000, разрешите микрофон и нажмите «Говорить». После реплики нажмите «Стоп». Ответ прозвучит в браузере; справа появятся сценарий, объяснение, альтернативы, поля, действия и время этапов. Если браузер запретил автоматическое воспроизведение, нажмите ▶ на плеере. Для другого порта: python src/web_demo.py --port 8080.

Объяснение готовится отдельным фоновым запросом и не меняет выбранные сценарии. Его оценка уверенности не является калиброванной вероятностью. Текстовый ввод пригодится для учебного телефона или при ошибке распознавания.

python src/telegram_bot.py

3. Провести первый разговор

В браузере нажмите «Новый разговор»; в Telegram отправьте /reset и /demo. Отправляйте по одной реплике и дожидайтесь ответа:

Хочу записаться к лору завтра в Астане по ДМС.
+77010000002
Да.

«Да» отправьте после предложения подтвердить запись. Телефон удобно вводить текстом; остальные реплики можно произнести. В учебной базе «сегодня» — 1 октября 2026, поэтому «завтра» означает 2 октября.

Личный номер может отсутствовать в учебной базе. «Новый разговор» в браузере или /reset в Telegram возвращает исходные данные. Готовый план выступления — демо за 3–4 минуты.

Как это работает

flowchart LR
    T["Браузер / Telegram<br/>голос или текст"] -->|голос| S["Распознавание<br/>голоса"]
    T -->|текст| D["Диалоговый движок<br/>состояние · проверки"]
    S --> D
    D <--> L["LLM<br/>сценарии · поля · ответ"]
    D <--> B["Учебный backend<br/>полисы · расчёты · запись"]
    D --> R["Ответ<br/>текст + голос"]
    R --> T
    classDef accent fill:#d1fae5,stroke:#059669,color:#064e3b
    class D,L accent

LLM получает каталог сценариев, контекст и факты. Python проверяет допустимые ID, формат данных, принадлежность полиса и подтверждение операции. На новом запросе маршрутизация и извлечение полей выполняются параллельно; действия — последовательно. В браузер озвучка передаётся потоком. При смене темы незавершённая задача сохраняется; у каждого пользователя свой сеанс.

Подробнее: карта модулей, состояние и подтверждения.

Результаты и проверки

Сохранённый predictions.json проверен на 104 репликах открытого dev-набора. Для сравнения приведены результаты первого прогона:

Промпт дорабатывался по этому набору. Результат на скрытых данных пока неизвестен. Эта оценка относится к маршрутизации текста; она не измеряет распознавание голоса или качество всего диалога. В свободных разговорах ещё встречаются ошибки сумм, языка ответа и продолжения предыдущего запроса.

Свежий независимый вызов текущего маршрутизатора тоже дал 104/104: отчёт проверки. Сохранённый predictions.json при аудите не перезаписывался.

Проверить сохранённые результаты и запустить тесты без внешних API и ключа (HTTP-тесты используют локальный loopback):

python data/evaluate.py predictions.json data/dev_utterances.json
python -m unittest discover -s tests -v

126 тестов проверяют загрузку данных, ответы маршрутизатора, переходы диалога, подтверждения, разбор номеров, Telegram и QR, изоляцию веб-сеансов, потоковую передачу аудио и независимость объяснений от выбора сценария. Внешние API в них подменены. Отдельно проверен живой диалог ДТП: сообщение о погибшем заполняет признак пострадавших, короткий адрес сохраняется дословно, бот сообщает о необходимости экстренного обращения и учебном характере передачи.

В финальном прогоне перед сдачей через настоящий API прошли запись к лору с подтверждением, проверка полиса на казахском, ДТП и возврат к задаче после обращения к оператору. Отдельно проверены смешанная реплика и голосовой запрос в браузере с объяснением маршрута. В последнем прогоне голос зазвучал через 4765 мс от оценённого конца речи; это один замер, а не новая медиана и не гарантия времени ответа на площадке.

# Интерактивный чат с трассировкой
python src/chat_demo.py --trace

# Диалоги из файлов
python src/chat_demo.py --script examples/chat_demo.json --trace
python src/chat_demo.py --script examples/dialog_regression.json --trace
python src/chat_demo.py --script examples/handoff_regression.json --trace
python src/chat_demo.py --script examples/accident_regression.json --trace

# Заново классифицировать dev-набор и заменить predictions.json
python src/main_router.py
python data/evaluate.py predictions.json data/dev_utterances.json

Задержка: что измерено

_{Нажмите на карточку, чтобы открыть методику. Значения взяты из сохранённых отчётов; условия двух измерений различаются.}

На пяти запросах, повторённых дважды в обоих режимах, медиана обработки диалога снизилась с 2566,5 до 1559,5 мс — на 39,2%. Все 10 пар сохранили выбранные сценарии. Это время диалога без STT, TTS и воспроизведения.

Полный голосовой smoke-тест с настоящим OpenAI API и синтетическим голосом дал 5190 мс от оценённого конца речи до события playing в Chromium; сам маршрутизатор занял 733 мс. Это один замер, не репрезентативная медиана. Ориентиры 500 мс / 1,5 с пока не достигнуты. По PDF они дают бонус за скорость и не являются условием сдачи.

Методика, сырые замеры и повторный запуск · Сверка с техническим заданием PDF

От результата — к доказательствам

Границы демо

• Исполнение сценариев. Для 33 бизнес-сценариев есть обработчики. SC02, SC04, SC05, SC06, SC12, SC27, SC28 передаются оператору в демо. Полное оформление всех продуктов ещё не реализовано.
• Учебные операции. Записи, обращения и изменения контактов хранятся в памяти. Реальные полисы, SMS и письма не отправляются; живой оператор не подключается. Расписание клиник сгенерировано для демонстрации.
• Голосовые сообщения. Записи до 60 секунд и 10 МБ. Телефонные звонки, непрерывный разговор и перебивание бота пока не реализованы.
• Качество и скорость. При ошибке распознавания можно отправить текст. Браузер оценивает конец речи по энергии микрофона и измеряет начало воспроизведения. Для оценки жюри нужна серия живых реплик и контроль секундомером. Telegram не сообщает момент первого звука на телефоне; эта метрика там остаётся пустой.
• Локальный сервер. Веб-демо слушает только 127.0.0.1; оно предназначено для запуска на ноутбуке. Публичный хостинг, телефония и промышленная авторизация не настроены. Chromium проверен; другие браузеры требуют отдельной проверки.

Текст, короткая история и аудио обрабатываются OpenAI; при использовании Telegram сообщения также остаются в чате. Используйте синтетические данные из комплекта. Аудио приложения хранится в памяти. В .runtime/ сохраняются номер обновления Telegram и отчёты, если запускать диагностику. Идентификация по телефону упрощена. Внутри одного сеанса реплики обрабатываются последовательно; сеанс сбрасывается после часа простоя или перезапуска.

Где что лежит

src/
├── main_router.py      # Пакетная маршрутизация → predictions.json
├── chat_demo.py        # Разговор в терминале
├── web_demo.py         # Локальный HTTP-сервер и голосовой API
├── web/                # Микрофон, плеер и панель супервизора
├── telegram_bot.py     # Telegram и QR текущего бота
├── benchmark.py        # Парные замеры диалога через настоящий API
├── config.py           # Модели, пути и лимиты
├── agent/              # Состояние, каталог и управление диалогом
└── tools/              # Учебный backend, аудио и Telegram API
data/                   # Материалы кейса и оценщик
examples/               # Реплики для повторяемых прогонов
tests/                  # Проверки без внешних API
docs/                   # Архитектура и сценарий выступления

Для работы с кодом:

python -m pip install -r requirements-dev.txt
ruff check src tests
ruff format --check src tests

Общий стиль задан в pyproject.toml. Применить форматирование: ruff format src tests.

Команда Zethus · Voice Router

Материалы кейса · Қазақша сипаттама · План демонстрации · Архитектура

Слушать человека. Понимать просьбу. Показывать решение.
_{SaqtaDauys · HackAlem AI · Команда Zethus}

↑ Вернуться к началу