Stone — Saqta Insurance Voice Router

Описание решения и назначение

Веб-демо голосового агента вымышленной страховой компании Saqta Insurance. LLM выбирает сценарии из 40 бизнес-сценариев и трёх системных намерений, извлекает слоты, а приложение выполняет мок-действия над синтетическим датасетом. Основной ввод — микрофон, ответ озвучивается; текст доступен как дополнение. Данные и цены не относятся к реальной страховой компании.

Архитектура

app.py записывает микрофон → backend.speech распознаёт RU/KK/mixed через gpt-4o-transcribe → backend.language предварительно определяет язык, backend.triage нормализует телефон → backend.router через OpenAI API возвращает JSON с выбранными сценариями, уверенностью и слотами → backend.decision_policy применяет пороги 0,75/0,45 → backend.executor проверяет идентификацию и слоты, показывает предварительный результат и запрашивает подтверждение перед необратимыми действиями → backend.actions_mock обращается к синтетическим данным. Язык из LLM-ответа определяет язык реплики бота; для смешанной речи выбирается преобладающий язык клиента. Каталожные вопросы уже двуязычные, динамические данные переводит отдельный слой представления, не выбирающий сценарии. gpt-4o-mini-tts озвучивает ответ. Справа показаны транскрипт, язык входа и ответа, сценарии и времена STT/router/dialog/reply/TTS/total.

Маршрутизация сценариев выполняется LLM. После ответа модели код только проверяет допустимость ID и уверенности, убирает дубли и ставит срочные сценарии первыми согласно ТЗ. Лексические правила не подменяют выбранный моделью сценарий. Обученный encoder-классификатор намерений в проекте не используется.

Используемые технологии

Python 3.11+, Streamlit, OpenAI API, python-dotenv; JSON-файлы из data/case_2/voice_router_dataset служат каталогом сценариев, мок-бэкендом и базой знаний. Данные читаются локально, внешняя база данных не нужна.

Установка

Из корня репозитория:

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip install -r requirements.txt

Запуск

Создайте .env в корне репозитория, задайте OPENAI_API_KEY, затем:

python -m streamlit run app.py

Откройте локальный адрес, который выведет Streamlit. Для демо нужен доступ к OpenAI API; личный аккаунт эксперта в приложении не требуется. Разрешите браузеру доступ к микрофону, нажмите запись, произнесите фразу и остановите запись. Ответ появляется текстом и в аудиоплеере; если браузер блокирует автозапуск, нажмите Play. Для телефона нужен HTTPS-адрес приложения (или локальный localhost на том же устройстве), а не HTTP-адрес ноутбука. Поле чата служит запасным вводом.

Зависимости

Зависимости перечислены в requirements.txt. Датасет уже включён в репозиторий. При запуске роутер отправляет реплику и каталог сценариев в OpenAI API; без доступного ключа маршрутизация не работает.

Переменные окружения

Переменная	Обязательна	Назначение
OPENAI_API_KEY	Да	Ключ OpenAI API для роутера, STT, TTS и локализации
ROUTER_MODEL	Нет	Модель роутера; по умолчанию gpt-4o-mini
STT_MODEL	Нет	Распознавание; gpt-4o-transcribe
TTS_MODEL	Нет	Озвучка с инструкциями языка; gpt-4o-mini-tts
TTS_VOICE	Нет	Голос; alloy
REPLY_MODEL	Нет	Перевод динамических данных; gpt-4o-mini

.env исключён из Git. Не помещайте ключ в коммиты и скриншоты.

Развёрнутая версия

Публичное демо (без установки): https://examined-sandwich-rocky-screensavers.trycloudflare.com — временный туннель на локально запущенный app.py, доступен, пока запущен процесс на машине команды. Для гарантированной проверки используйте локальный запуск по инструкции выше.

Порядок проверки основного сценария

1. Запустите приложение и введите: «Сколько стоит ОГПО для легковой машины в Алматы?». Панель трассировки должна показать SC01; бот запросит недостающие слоты.
2. Введите ИИН водителя из data/case_2/voice_router_dataset/mock_backend.json и остальные запрошенные данные. Проверьте расчёт стоимости и действия в панели трассировки.
3. Для проверки подтверждения запросите покупку ОГПО (SC02), предоставьте запрошенные номер автомобиля, ИИН и телефон синтетического клиента. До ответа «да» действие create_policy должно оставаться в режиме pending.
4. Для проверки системного намерения введите запрос о кредите: ожидается SYS_OUT_OF_SCOPE.

Датасет и полное описание кейса: data/case_2/voice_router_dataset/README.ru.md. Оценка на размеченных репликах:

python predictions.py
python data/case_2/voice_router_dataset/evaluate.py predictions.json data/case_2/voice_router_dataset/dev_utterances.json

Проверка текущего роутера после удаления трёх функций, вручную переписывавших выбор сценария, и добавления каталоговых RU/KK примеров в промпт: 104 реплики dev_utterances.json через OpenAI API и официальный evaluate.py (23.09.2026). Точность основного сценария — 99,0% (103/104); полное совпадение списка — 97,1% (101/104); полнота интентов в многоцелевых запросах — 92,3%. Остались три несовпадения: U034 (SC30 вместо SC17), U086 (пропущен SC31), U093 (пропущен SC33). Это открытая выборка разработки, не независимая итоговая оценка; повторный вызов API может дать другой результат. Веса LLM не дообучались: дополнительные примеры из scenarios.json передаются в контексте запроса.

Переиспользованные компоненты

backend.triage.detect_language() первоначально переиспользован из предыдущего проекта команды AI Firewall; теперь заменён на RU/KK/mixed fallback в backend.language, основной язык полной реплики возвращает LLM. Это вспомогательное определение языка, не классификатор намерений и не основная часть решения. Обученная модель DistilBERT для классификации намерений из того проекта здесь не используется.

Проверка голосового демо

Произнесите последовательно русскую, казахскую и смешанную фразы о страховании. В Trace panel проверьте transcript, language (ru, kk, mixed) и response_language (ru или kk), затем прослушайте ответ. Для KK и смешанной речи с преобладанием казахского вопросы и голос должны быть казахскими; при преобладании русского — русскими. Номер телефона или ИИН сам по себе не меняет язык диалога. Новая русская реплика переключает ответ обратно на русский.

Ошибки распознавания и озвучки видны в интерфейсе; кнопки повтора не выполняют страховую операцию заново. При неточной транскрипции введите исправленную фразу в чат. Автоматическое тестирование без API:

python -m unittest discover -s tests -v

STT API: язык в запросе не фиксируется, чтобы сохранить смешанную речь. Для gpt-4o-transcribe используется JSON; verbose_json/языковые сегменты этой моделью не поддерживаются. TTS API принимает текст ответа и инструкции произношения. Текущая реализация ждёт полный MP3: поле tts означает полное время синтеза, а total включает STT; это не замер времени до первого аудиофрагмента и не подтверждение секундного бюджета ТЗ.