Voice Router — голосовой AI‑агент Saqta Insurance (DeTeam)

HackAlem AI, трек Halyk Bank, кейс 2 «Voice Router».

Голосовой робот контакт‑центра, у которого сценарий разговора выбирает LLM, а не классификатор намерений. Он понимает живую русскую, казахскую и смешанную речь, переключается между темами, не теряя контекста, и выполняет 40 сценариев страховой компании на данных. Агент работает в вебе и по настоящему телефону через Asterisk. Супервизор видит трассировку каждого решения. Ошибки маршрутизации исправляются правкой каталога за полминуты с регрессионной проверкой, без переобучения модели.

Содержание

1. Запуск
2. Что умеет
3. Как устроен один ход
4. Сильные стороны
5. Главная фича: эволюция каталога
6. Технологический стек
7. Измеренные результаты
8. Как проверить самому
9. Структура репозитория
10. Ограничения
11. Документы

Запуск

Бэкенд одной командой (нужны Docker и ключ OpenAI):

echo "OPENAI_API_KEY=sk-..." > backend/.env
docker compose up --build            # http://127.0.0.1:8000

Полный стенд с фронтом, телефонией и записью звонков. Пошаговая инструкция с чек‑листом проверки лежит в docs/RUNBOOK.md:

make venv && npm ci --prefix frontend                     # один раз
docker compose -f infra/asterisk/compose.yaml up -d --build  # Asterisk + MinIO + загрузчик записей
make run                                                  # бэкенд :8000, AudioSocket :9092
make web                                                  # фронт http://127.0.0.1:5173

Звонок: софтфон на аккаунт 1001, номер 757507 звонит от имени клиента Сергея, 9999 включает эхо‑тест.

Что умеет

Обязательные требования кейса:

Требование	Как сделано
Голос в вебе	Микрофон браузера, WebSocket /ws/voice, серверный VAD, ответ голосом. Текст как запасной канал
Выбор сценария на LLM	gpt-5.6-luna со строгой JSON‑схемой по каталогу из 40 сценариев. Классификаторов намерений нет
Корректность выбора	Dev‑набор: 99–100% основного сценария, все 40 ходов десяти эталонных диалогов кита
Панель трассировки	После каждой реплики: транскрипт, язык, сценарии с уверенностью и причиной, альтернативы, слоты, действия, задержка по этапам
Русский и казахский	Включая смену языка посреди диалога и смешанную речь в одной фразе

Опциональные пункты ТЗ, все реализованы:

Опция	Реализация
Гибридная архитектура с измеримым выигрышем	Детерминированный fast path без LLM и шаблонные ответы с готовым аудио. Медиана задержки хода 1.0 с против 2.1 с без этих приёмов
Удержание контекста и возврат к теме	Стек тем: прерванная тема откладывается, после новой бот предлагает вернуться. Слоты не теряются
Переспросить вместо угадывания	Уверенность 0.45–0.75 уходит на второе мнение gpt-6-sol, при сомнении бот задаёт уточняющий вопрос с двумя вариантами
Передача оператору с контекстом	По просьбе, после трёх неясных реплик подряд и по правилам сценария. Оператор получает резюме, слоты и хвост диалога
Извлечение параметров из речи	Телефоны словами на русском и казахском, ИИН, госномера, даты «ертең», «три дня назад», суммы «двадцать лямов»
Потоковая обработка	Стриминг роутера с ранним решением, стриминг ответа по предложениям, стриминг синтеза
Эмоция и подстройка тона	Роутер оценивает эмоцию, ответ начинается с эмпатии при жалобе или ДТП
Панель супервизора со статистикой ошибок	Сессии, трассировки, распределение уверенности, спорные ходы, запись звонка с плеером
Редактирование каталога без разработчиков	Эволюция каталога: патч, регрессия, применение, откат. Подробнее ниже

Плюс сверх ТЗ: настоящая телефония через Asterisk, полная запись каждого звонка в MinIO, экран оператора, генератор каверзных реплик для поиска ошибок роутера.

Как устроен один ход

 Браузер (WS, PCM 16 kHz)                 Софтфон → Asterisk → ARI + External Media (AudioSocket, 8 kHz)
            └──────────────────────┬──────────────────────┘
                                   ▼
 1. VAD Silero + конец реплики     семантический (≈0.3 с тишины и законченная фраза) / по тишине 0.8 с / push‑to‑talk
                                   ▼  распознавание стартует спекулятивно уже на паузе
 2. STT gpt-transcribe             два запроса параллельно (казахский + автоопределение), берётся первый непустой
                                   ▼
 3. Понимание                      a) fast path без LLM: ожидаемый слот по шаблону, «да/нет», «оператор», «алло, слышите?», прощание
                                   b) LLM-роутер gpt-5.6-luna: 2 одинаковых стрима, побеждает первый; запасной стрим на gpt-6-luna,
                                      если первого токена нет 1.8 с; каталог 40 сценариев в кэше промпта; строгая JSON-схема
                                   c) ранний колбэк: первый scenario_id в потоке → сразу играем подтверждение из кэша аудио
                                   d) уверенность 0.45–0.75 → второе мнение gpt-6-sol
                                   ▼  решение: run / continue / confirm / cancel / clarify / handoff / goodbye
 4. Исполнитель сценариев          фреймы, стек тем, план на каждый из 40 сценариев: идентификация → слоты по одному →
                                   действия над моками → для необратимых: озвучить данные → явное «да» → выполнить
                                   ▼  план ответа: факты + вопрос
 5. Ответ                          шаблон без LLM (вопросы слотов, уточнения, прощание) или gpt-6-luna стримом строго по фактам;
                                   числа словами, email маскируется, один вопрос за ход
                                   ▼
 6. TTS gpt-4o-mini-tts, голос marin   ≈200 фраз заранее синтезированы; следующее предложение синтезируется, пока звучит текущее
                                   ▼
 PCM обратно в браузер / кадрами по 20 мс в Asterisk; события и trace → фронт, /ws/supervisor, журнал сессии

Сильные стороны

Маршрутизация, которая понимает, а не сопоставляет

• Роутер видит весь каталог: описания, правила разграничения not_this_if и примеры. Кроме того, он видит состояние диалога: активный сценарий, ожидаемый слот, стек тем, последнюю реплику бота.
• В одном вызове роутер определяет язык, режет реплику на несколько намерений, выбирает сценарии с уверенностью и причиной, извлекает и нормализует слоты. Он же распознаёт продолжение сценария и ответ на подтверждение.
• Срочные сценарии идут первыми: ДТП прямо сейчас, болезнь за границей, мошенничество.
• Честная уверенность и второе мнение: модель не угадывает, в зоне сомнения бот переспрашивает.

Задержка, которую можно проверить секундомером

• Мгновенное подтверждение понимания. Как только роутер выдал первый сценарий, звучит первая фраза opening этого сценария из кита, аудио для неё готово заранее. Правила кейса сами требуют начинать с понимания.
• Хеджирование: два одинаковых запроса к роутеру и запасной на другую модель при всплеске задержки у API.
• Спекулятивное распознавание, семантический конец реплики, прогретые соединения к OpenAI.
• Задержка замеряется честно: от последнего озвученного кадра клиента до отправки первого кадра ответа. Все этапы видны в трассировке.

Безопасность и качество ответа

• Необратимые действия выполняются только после явного «да»: оформление, продление, изменение, расторжение полиса, заявления, записи. Перед этим бот зачитывает данные.
• Ответы строятся только из фактов плана: результаты моков и разделы базы знаний. Цены считаются по формулам кита, а не придумываются моделью.
• Персональные данные при повторном озвучивании маскируются. На вопрос «вы робот?» бот отвечает честно.

Живой диалог

• Бот переспрашивает, если значение не подходит, и называет допустимые варианты с ценами.
• Держит контекст: «а если дом, а не квартира?» он пересчитывает по уже известной сумме.
• Спокойно реагирует на грубость и остаётся в теме. Бота можно перебить голосом.
• Опознаёт клиента по номеру звонящего или по телефону, продиктованному словами на русском или казахском.

Инженерия

• Контракты раньше кода: JSON‑схемы событий, трассировки, вывода роутера и эволюции, OpenAPI. По ним параллельно работали фронт, телефония и бэкенд.
• Проверки на каждом уровне: dev‑набор, 10 эталонных диалогов, 80 сценарных диалогов, сквозные голосовой и телефонный тесты, валидация событий по схемам.

Главная фича: эволюция каталога

Знание о маршрутизации живёт не в весах модели, а в человекочитаемом каталоге сценариев. Поэтому ошибку роутера можно исправить за полминуты с регрессионной проверкой. У классификатора намерений тот же цикл занимает дни: разметка, переобучение, релиз.

 ошибка в трассировке ─► кейс ─► патч каталога (gpt-6-sol) ─► валидатор ─► регрессия до/после ─► супервизор применяет ─► новая версия
       ▲                                                                                                                  │
       └───────────────────────────── откат в один клик, заморозка на время зачётного прогона ◄────────────────────────────┘

• Кейсы. Кнопка «Неверно» у любого хода или генератор каверзных реплик на стыках похожих сценариев. Генератор сохраняет только те реплики, на которых роутер реально ошибся.
• Патчер. Меняет только description, not_this_if и примеры: не больше 4 операций и 2 сценариев. Идентификаторы, слоты и действия не трогает, поэтому оценка по исходным 40 сценариям остаётся честной.
• Защита от хардкода. Пример, похожий на текст кейса или dev‑реплику больше чем на 85%, отклоняется, и патчер переписывает его обобщённо.
• Регрессия. Роутер прогоняется по 104 dev‑репликам и всем кейсам на старой и новой версии каталога. Спорные пункты перепроверяются пятью прогонами. Показываются починенные и сломанные кейсы.
• Версии. Каждое применение даёт новую версию с хэшем. Промпт роутера пересобирается и прогревается за 2 секунды.

Технологический стек

Слой	Технологии
Модели, только OpenAI	роутер gpt-5.6-luna; запасной роутер gpt-6-luna; второе мнение и патчер gpt-6-sol; ответы gpt-6-luna; STT gpt-transcribe; TTS gpt-4o-mini-tts-2025-12-15, голос marin. Везде priority tier и кэш промпта
Бэкенд	Python 3.12, FastAPI, asyncio, OpenAI SDK (Responses API, structured outputs strict, streaming), onnxruntime + Silero VAD, numpy, num2words
Голос в вебе	WebSocket, PCM16 16 kHz на вход и 24 kHz на выход, AudioWorklet в браузере, перебивание
Телефония	Asterisk 20 (Docker), ARI‑приложение voice-ai, External Media с инкапсуляцией AudioSocket, PJSIP, перевод на оператора через ARI; запасной режим через диалплан
Записи звонков	MixMonitor → MinIO (S3) → загрузчик → callback в бэкенд → плеер в карточке сессии
Фронтенд	React, Vite, TypeScript: экраны звонка, супервизора, сессии, эволюции, оператора и каталога
Инфраструктура	Docker Compose, Makefile, JSON Schema + OpenAPI контракты, журналы сессий в JSONL
Данные	Стартовый кит кейса: сценарии, слоты, действия, база знаний, мок‑бэкенд, эталонные диалоги, dev‑набор

Почему такая схема, а не speech‑to‑speech модель. В gpt-realtime и gpt-live выбор сценария происходит внутри модели. Тогда нельзя показать слой решения, замерить этапы и проверить маршрутизацию на dev‑наборе. Каскад STT → роутер → ответ → TTS даёт прозрачную трассировку и дословный контроль над тем, что произносит бот.

Выбор модели роутера по замеру на нашем промпте (8 реплик на модель, один запрос без хеджа):

Модель	Первый токен, медиана / p90	Ответ целиком, медиана / p90	Верно
gpt-5.6-luna	1.03 / 1.33 с	1.63 / 1.91 с	8/8
gpt-6-luna	0.95 / 1.29 с	1.65 / 2.82 с	8/8
gpt-6-sol	1.05 / 1.33 с	1.86 / 2.16 с	8/8
gpt-5.6-sol	1.05 / 1.23 с	1.89 / 2.29 с	8/8

gpt-5.6-luna даёт лучший ответ целиком и стабильный хвост, на полном dev‑наборе у неё выше точность. gpt-6-luna стоит запасной на случай всплеска задержки.

Измеренные результаты

Метрика	Значение	Как воспроизвести
Dev‑набор, основной сценарий	0.99–1.00	make bench
Dev‑набор, полное совпадение и намерения в мульти‑запросах	0.99–1.00	make bench
Эталонные диалоги кита	40 из 40 ходов	make replay
Сценарные диалоги: 40 основных и 40 краевых	80 из 80	make test
Задержка хода в текстовом режиме, медиана	≈1.0 с	make replay
Голос в вебе, от конца речи до первого звука	1.5–2.5 с	make probe-voice
Телефон, ход с роутером / fast path	1.9–2.6 с / ≈1 с	звонок или make probe-phone
Патч эволюции от запроса до готовности	27–38 с	вкладка «Эволюция»
События WS по JSON‑схемам контракта	0 ошибок	make validate, голосовой тест

Как проверить самому

make validate     # фикстуры и схемы контрактов
make replay       # 10 эталонных диалогов кита, печатает каждый ход с решением и задержкой
make test         # 80 сценарных диалогов, без сервера
make bench        # dev-набор + официальный data/evaluate.py
make probe-voice  # сквозной голосовой тест без микрофона (сервер запущен)
make probe-phone  # сквозной тест телефонии: притворяемся Asterisk по AudioSocket

Реплики для проверки голосом лежат в docs/RUNBOOK.md, раздел 4. Там же чек‑лист телефонии и таблица «если что‑то не так».

Структура репозитория

Путь	Что внутри
backend/	голосовой агент: VAD, STT, роутер, исполнитель, ответы, TTS, телефония, эволюция, тесты
frontend/	веб: звонок, супервизор, сессии, эволюция, оператор, каталог
infra/asterisk/	Asterisk в Docker (PJSIP, ARI), MinIO и загрузчик полных записей звонков
contracts/	JSON‑схемы событий, трассировки, роутера и эволюции, OpenAPI, конфиги Asterisk
fixtures/	шаблонные сессии и данные супервизора для фронта
tools/	мок‑сервер, проверка фикстур против схем
data/	стартовый кит кейса и evaluate.py
docs/	runbook, концепт, контракты фронта и телефонии, условия кейса

Ограничения

• Задержка зависит от OpenAI. Медиана укладывается в 3 с, но при всплесках API отдельные ходы бывают дольше. Запасной запрос режет большую часть таких хвостов.
• Бенчи параллельно со звонком нельзя. Все компоненты работают на одном ключе, бенч съедает лимит токенов в минуту и замедляет живой разговор.
• Моки вместо реальных систем. Все действия работают поверх mock_backend.json и базы знаний из кита.
• Сценарий SC16 не проходит до конца. В данных кита ни у одного клиента нет полиса от несчастного случая, поэтому бот переводит такого клиента на оператора.
• Роутер недетерминирован. Между прогонами dev‑набора разница около одного процентного пункта.
• Качество казахского синтеза и распознавания ниже русского. Для казахского распознавание идёт двумя вариантами параллельно.

Документы

Кому	Куда смотреть
Запуск и проверка	docs/RUNBOOK.md
Архитектура	ARCHITECTURE.md, ROUTER.md, EVOLUTION.md
Бэкенд	backend/README.md
Фронтенд	docs/frontend/README.md, DIALOG_EXAMPLES.md, frontend/README.md
Телефония	docs/telephony/README.md, infra/asterisk/README.md
Контракты	contracts/
Условия кейса	docs/case/README.ru.md, ТЗ