Voice Router — гибридный голосовой AI-агент с LLM-слоем выбора сценария

Проект для HackAlem (кейс 2): голосовой агент контакт-центра страховой компании Saqta Insurance (компания вымышленная, все данные синтетические). Агент понимает русскую, казахскую и смешанную речь, с помощью LLM выбирает один из 40 бизнес-сценариев, собирает недостающие данные, выполняет действия и отвечает голосом. Фронтенд называется Neonic Samurais.

1. Какую проблему решает проект

В звонки страховой компании приходят похожие друг на друга запросы: «авария» может быть ДТП, которое только что произошло (SC11), обращением пострадавшего (SC12) или страховым случаем по КАСКО (SC13). Клиенты переходят с русского на казахский посреди фразы, меняют тему и задают несколько вопросов сразу. Многие действия, например оформление или расторжение полиса и регистрация страхового случая, необратимы.

Проект показывает, как автоматизировать первую линию такого контакт-центра. Нужно правильно выбрать сценарий, объяснить этот выбор, не выполнять необратимых действий без явного «да» и передать разговор оператору вместе с контекстом, если бот не уверен.

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

2. Что реализовано

• Голосовой чат в браузере (chat/): удержание кнопки или Space для разговора, режим hands-free, промежуточная расшифровка во время речи, ввод текстом, выбор языка ответа (Auto / Русский / Қазақша).
• Панель трассировки после каждой реплики: язык, выбранные сценарии с уверенностью, причина выбора, альтернативы, выполненные действия, задержка по этапам (stt / router / tts / total).
• Распознавание речи (stt/): локальная модель для казахского, русского и смешанной речи, VAD, тестовая консоль с подсчётом WER/CER.
• Синтез речи (tts/): русский голос Silero v5 и казахский ISSAI KazakhTTS. Язык выбирается для каждого предложения отдельно.
• LLM-маршрутизатор (backend/, Go), основная часть решения:
  • гибридный конвейер: детерминированный пре-роутер → лексический поиск кандидатов → быстрый или полный маршрут через LLM → оценка неопределённости → исполнение сценария;
  • несколько намерений в одной фразе: срочные сценарии (SC11, SC15, SC38) идут первыми, остальные ставятся в очередь;
  • смена темы с возвратом к прерванному сценарию (стек сценариев, у каждого свои слоты);
  • уточняющий вопрос вместо угадывания при низкой уверенности;
  • предпросмотр и явное подтверждение («Да» / «Иә») на следующей реплике перед каждым необратимым действием;
  • перевод на оператора с кодом причины и контекстом (последние реплики, слоты, альтернативы, компоненты неопределённости), API для операторской консоли и необязательный webhook;
  • необязательная проверка намерения пользователем или оператором (intent review);
  • «лестница» отказоустойчивости: при ошибке модели запрос уходит на резервную модель, затем на уточнение только по результатам поиска, затем на оператора;
  • синтетический бэкенд: все 31 действие из actions.json реализованы как моки поверх данных датасета;
  • хранение сессий, реплик и контрольных точек в SQLite, идемпотентность по request_id, восстановление после перезапуска.
• Харнес оценки (backend/cmd/evaluate): прогон dev-набора, многоходовых диалогов, проб и офлайн-оценка поиска кандидатов, вывод точности и задержек.
• Запуск одной командой через Docker Compose (CPU, опционально GPU).

3. Как работает решение

Основной сценарий: клиент говорит в микрофон и получает голосовой ответ.

1. Браузер записывает PCM 16 кГц и передаёт его по WebSocket в шлюз чата (:9102).
2. Шлюз отправляет аудио в STT (:9100) и получает текст и подсказку о языке (ru / kk / mixed).
3. Шлюз отправляет текст в Go-маршрутизатор: POST /v1/turns (:8080).
4. Маршрутизатор обрабатывает реплику:
   • Пре-роутер (без LLM): если бот ждал слот (телефон, ИИН, дату) или «да/нет» и реплика точно является таким ответом, сценарий продолжается без вызова модели.
   • Поиск кандидатов: TF-IDF по символьным n-граммам сравнивает фразу с примерами сценариев и формирует шорт-лист из 8 сценариев. Поиск только сужает выбор и никогда не выбирает сценарий сам.
   • Шлюз быстрого пути: если лидер шорт-листа явно впереди и помечен в датасете fast_path_eligible, вызывается быстрая модель (gpt-4.1-nano) с тремя кандидатами. Иначе вызывается основная модель (gpt-4.1-mini) с шорт-листом, границами not_this_if, состоянием диалога и последними 10 репликами.
   • Ответ модели (Structured Outputs, строгая JSON-схема) проверяется в Go по каталогу.
   • Оценка неопределённости строится по наблюдаемым сигналам: уверенность модели, согласие с поиском, отрыв лидера, конфликт с правилами not_this_if. По порогам (0.25 / 0.55) принимается решение: выполнить, уточнить или перевести на оператора.
   • Исполнитель идентифицирует клиента, по одному запрашивает слоты, выполняет действия сценария. Необратимые действия проходят через предпросмотр и подтверждение.
   • Ответ собирается из шаблонов датасета. LLM формулирует текст только там, где шаблона нет: уточнения, ответы по базе знаний, ошибки.
5. Шлюз отправляет ответ в TTS (:9101), и браузер воспроизводит аудио вместе с трассировкой.

4. Технологии

Слой	Технологии
Маршрутизатор	Go 1.25, стандартный net/http, modernc.org/sqlite (SQLite без cgo)
LLM	OpenAI Responses API, Structured Outputs, store: false; модели по умолчанию gpt-4.1-mini (основная) и gpt-4.1-nano (быстрая и резервная), настраиваются через переменные окружения
STT	Python, FastAPI, PyTorch, модель wav2vec2 + CTC alibiserikbay/kazakh-russian-mixed-stt, VAD, ffmpeg
TTS	Python, FastAPI, Silero TTS v5 (русский), ISSAI KazakhTTS: ESPnet Tacotron2 + ParallelWaveGAN (казахский)
Чат и шлюз	Python, FastAPI, WebSocket, HTML/CSS/JavaScript без сборки, AudioWorklet
Инфраструктура	Docker, Docker Compose (CPU и NVIDIA GPU), Makefile, bash-скрипт запуска
Оценка	Go-харнес cmd/evaluate, эталонный скрипт voice_router_dataset/evaluate.py

5. Архитектура

браузер ──ws──▶ chat gateway (:9102) ──▶ STT (:9100)                 текст + язык
                                     ──▶ Go-маршрутизатор (:8080)     POST /v1/turns ──▶ ответ + trace
                                     ──▶ TTS (:9101)                  аудио ответа ──▶ браузер

Каталог	Компонент	Порт
backend/	Слой 2: LLM-маршрутизатор, исполнитель сценариев, синтетический бэкенд, SQLite, операторский API	8080
stt/	Слой 1: распознавание речи и тестовая консоль	9100
tts/	Слой 3: синтез речи	9101
chat/	Фронтенд Neonic Samurais и шлюз, который связывает STT, маршрутизатор и TTS	9102
voice_router_dataset/	Датасет организаторов: сценарии, слоты, действия, база знаний, мок-данные, dev-набор. Встраивается в бинарник Go
docker/, docker-compose*.yml	Контейнеры четырёх сервисов
scripts/	Запуск Python-сервисов без Docker, загрузка весов моделей в Docker-том
docs/	Справочник API (api.md) и визуализация цикла обработки реплики (agentic-loop.html)

Основные модули маршрутизатора (backend/internal/router/):

Файл	Назначение
catalog.go	Загрузка и валидация каталога сценариев, слотов и действий из датасета
prerouter.go	Продолжение сценария без LLM (слот или да/нет)
retrieval.go	Шорт-лист кандидатов: TF-IDF по n-граммам, косинусная близость
openai.go, context.go	Запросы к OpenAI и сборка промпта
uncertainty.go	Вердикт «выполнить / уточнить / оператор»
engine.go, workflow.go	Цикл обработки реплики, фреймы сценариев, стек и очередь, лимиты
backend.go	Моки бизнес-действий
templates.go	Шаблонные ответы из датасета
operator.go	Тикеты перевода на оператора и webhook
store.go, repository.go	SQLite, контрольные точки, идемпотентность
http.go	HTTP API

Шлюз чата умеет работать без Go-маршрутизатора: в режиме ROUTER_MODE=auto при недоступном маршрутизаторе он использует простой mock по ключевым словам, и такие ответы помечаются mock router.

6. Установка и запуск

Вариант А: Docker (рекомендуется)

Нужны Docker с Compose и ключ OpenAI API.

1. В корне репозитория создайте файл .env:

   OPENAI_API_KEY=sk-...
   # необязательно:
   # OPENAI_MODEL=gpt-4.1-mini
   # API_TOKEN=...          # bearer-токен маршрутизатора; чат передаёт его сам
   # HF_TOKEN=hf_...        # если Hugging Face отвечает 401 при загрузке весов
   

2. Соберите и запустите:

   docker compose up --build -d      # или: make up
   

   При первом запуске в том speech-models скачивается около 1 ГБ весов моделей речи.

3. Откройте:

   • http://localhost:9102 — голосовой чат;
   • http://localhost:9100 — тестовая консоль STT;
   • http://localhost:8080/healthz — проверка маршрутизатора.

4. Логи и остановка:

   docker compose logs -f router
   docker compose down               # веса остаются в томе
   

С NVIDIA GPU и NVIDIA Container Toolkit:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d

Если порт 8080 занят, задайте ROUTER_PORT=18080 в .env.

Вариант Б: локально, без Docker

Маршрутизатор (Go 1.25+):

cd backend
cp .env.example .env              # укажите OPENAI_API_KEY; файл .env читается при старте
go run ./cmd/router               # http://127.0.0.1:8080, база voice_router.db создаётся автоматически

STT, TTS и чат (Python, ffmpeg). Нужны два виртуальных окружения: .venv для STT и чата, .venv-tts на Python 3.12/3.13 для TTS. Первичная установка описана в stt/README.md и tts/README.md. Затем:

.venv/bin/pip install -r chat/requirements.txt
scripts/speech_services.sh start          # STT + TTS + чат; --ui дополнительно включает консоль STT
scripts/speech_services.sh status | stop | logs

Скрипт написан для bash в Linux (использует ss, setsid). На Windows удобнее вариант с Docker.

7. Как проверить решение

Автотесты (ключ API не нужен, модель подменяется фейком):

cd backend
go test ./...

Голосом в браузере (после запуска по варианту А):

1. Откройте http://localhost:9102, разрешите доступ к микрофону и убедитесь, что индикатор ROUTER показывает go, а не mock.
2. Удерживая кнопку или Space, скажите: «Скажите, почём сейчас ОГПО на машину в Астане?» Ожидаемый сценарий: SC01 (расчёт стоимости ОГПО).
3. Откройте панель ⌁ trace: там видны сценарий, причина, альтернативы, путь (fast / full) и задержки по этапам.
4. Смешанная речь с двумя намерениями: «Сәлеметсіз бе, Түркияға баруға сақтандыру керек, и ещё скажите, где ваш офис в Астане». Ожидаются SC06 (страховка для путешествий) и SC33 (адреса офисов).
5. Идентификация и подтверждение: попросите оформить полис ОГПО и на вопрос о телефоне назовите номер клиента из мок-данных, например +77010000001. Перед оформлением бот озвучит данные и подождёт явного «Да» / «Иә».
6. Скажите «соедините с оператором»: ответ получит статус handoff, в трассировке появится код причины и номер тикета.

Через API (без голоса):

curl -s http://localhost:8080/v1/scenarios | head -c 300
curl -s http://localhost:8080/v1/turns -H "Content-Type: application/json" -d '{
  "session_id": "demo-1", "request_id": "t1",
  "text": "Подскажите адрес офиса в Алматы", "language": "ru"}'

Ожидаемый сценарий: SC33. Если в .env задан API_TOKEN, добавьте заголовок Authorization: Bearer <API_TOKEN>. Полный контракт API описан в docs/api.md (на английском, часть разделов о PostgreSQL устарела: сейчас используется SQLite).

Оценка точности маршрутизации на dev-наборе (104 фразы, платные запросы к OpenAI, нужен Python для evaluate.py):

cd backend
go run ./cmd/evaluate -limit 5                  # пробный прогон
go run ./cmd/evaluate                           # весь dev-набор + evaluate.py
go run ./cmd/evaluate -mode dialogs             # 10 многоходовых диалогов
go run ./cmd/evaluate -mode retrieval           # офлайн, без API: качество шорт-листа

8. Данные и интеграции

• Датасет организаторов (voice_router_dataset/): 40 сценариев и 3 системных намерения, каталог слотов, 31 действие, база знаний (офисы, продукты, формулы цен, клиники, правила), мок-бэкенд (11 клиентов, 11 полисов, 4 страховых случая, 2 платежа), 10 размеченных диалогов, 104 dev-фразы. Дата среза данных — 2026-10-01, она считается «сегодняшней». Dev-фразы и их метки в модель не передаются.
• OpenAI API (Responses API): выбор сценария и формулировка ответов, где нет шаблона. Это единственный внешний сервис во время работы.
• Hugging Face и сервер ISSAI: однократная загрузка весов STT и TTS. После загрузки распознавание и синтез речи работают локально.
• Operator webhook (необязательно, OPERATOR_WEBHOOK_URL): уведомление о новом тикете, телефон, ИИН и e-mail маскируются.
• Реальных интеграций со страховыми системами, SMS, платежами или телефонией нет. Все действия выполняются над синтетическими данными, результаты помечены mock: true.

9. Ограничения

• Компания, клиенты, цены и правила вымышлены. Идентификация по телефону или ИИН демонстрационная и не является настоящей аутентификацией.
• В моках есть упрощения: КАСКО рассчитывается только по тарифу Standard, один слот записи в день на локацию, условные цены продления.
• Без ключа OpenAI маршрутизатор не запускается, а чат переключается на упрощённый mock по ключевым словам.
• STT выдаёт текст без пунктуации и регистра, числа словами. Потоковое распознавание не реализовано, аудио отправляется после окончания фразы.
• Казахский TTS произносит русские слова внутри казахских предложений с акцентом. Цифры в тексте ответа нужно писать словами.
• SQLite рассчитан на один процесс маршрутизатора. Горизонтальное масштабирование не предусмотрено.
• Сценарии фиксированы датасетом, API для их редактирования нет.
• Реальная телефония и живой перевод звонка оператору не реализованы: есть только тикет, API операторской консоли и webhook. Отдельного интерфейса оператора нет, каталог frontend/ пуст.
• Целевые задержки (500 мс на выбор сценария, 1,5 с до начала ответа) заложены в дизайн, но в репозитории нет зафиксированных результатов замеров. Точность маршрутизации также не зафиксирована. Её можно измерить командой go run ./cmd/evaluate.
• Микрофон в браузере работает только на localhost или по HTTPS.

10. Deployed-версия

В репозитории нет ссылки на развёрнутую версию. Решение запускается локально (см. раздел 6).

Дополнительные материалы

• DESIGN.md: целевой дизайн цикла обработки реплики (на английском).
• docs/agentic-loop.html: визуальная схема цикла, открывается в браузере.
• docs/api.md: справочник HTTP API маршрутизатора.
• chat/README.md, stt/README.md, tts/README.md: документация сервисов.
• voice_router_dataset/README.ru.md: описание датасета и правил кейса.
• PDF с описанием решения в корне репозитория.