Voice Router

Голосовой AI-оператор для маршрутизации обращений в контакт-центре вымышленной страховой компании Saqta Insurance.

Кейс: HackAlem AI 2026, Voice Router

Владелец задачи: Halyk Bank / АО «Народный Банк Казахстана»

Дата симуляции данных: 2026-10-01

Voice Router должен принимать речь на русском и казахском языках, передавать согласованный транскрипт в LLM, выбирать один или несколько сценариев из каталога и отвечать по проверенным данным. Супервизор должен видеть выбранный маршрут, альтернативы, краткую причину решения и фактическое время этапов.

Главный критерий кейса — качество LLM-маршрутизации. Качество STT/TTS важно для рабочего голосового демо, но не заменяет корректный выбор сценария.

Текущий статус

Репозиторий содержит работающий starter и незавершённую реализацию Voice Router. Сквозной голосовой продукт пока не готов.

Область	Фактическое состояние
Исходный набор	Подключены неизменённые 40 сценариев, 3 системных намерения, слоты, действия, база знаний, mock backend, примеры и dev-набор.
Контракты и каталог	Реализованы Zod-схемы входа/выхода, загрузка и перекрёстная проверка каталога, допустимых ID и слотов.
Текстовая маршрутизация	Есть серверный POST /api/voice-router/turn: вызов gpt-realtime, tool call route_turn, валидация результата, одна попытка исправления, политика уверенности и генерация ответа по выбранным фактам.
Контекст	В памяти процесса сохраняются активные сценарии, извлечённые слоты, язык ответа и серия низкой уверенности. Повторы одного turnId идемпотентны; конфликтующий повтор отклоняется.
Веб-интерфейс	Сейчас приложение открывает только starter-экран Echo. Клиентский экран Voice Router и панель супервизора ещё не подключены.
Голос	В src/web/features/voice-router/realtime/ подготовлены модули PCM-захвата, воспроизведения и WebSocket-клиента. Серверного WebSocket-маршрута, DSR, Yandex STT и ElevenLabs TTS в рабочем контуре ещё нет.
Действия	Контракты действий загружаются, но исполнитель над mock_backend.json, подтверждения и handoff ещё не реализованы.
Оценивание	Исходный evaluate.py присутствует, но runner реального маршрутизатора и подтверждённые метрики ещё не добавлены.
Deployment	Docker-сборка starter ранее проверялась локально. Публичный URL и сквозной голосовой deployment не зафиксированы.

Актуальные свидетельства, ограничения и следующий шаг ведутся в docs/STATUS.md и docs/progress/. Наличие кода провайдера не означает, что живой внешний API уже проверен.

Целевой пользовательский путь

Микрофон
  → OpenAI STT + VAD ─┐
                      ├→ DSR → согласованный текст
  → Yandex SpeechKit ─┘
       → gpt-realtime: выбор сценария
       → серверная валидация и политика
       → mock-действие / данные Saqta
       → текст ответа по фактам
       → ElevenLabs V3
       → звук в браузере + трассировка для супервизора

Текстовый резервный ввод должен входить в тот же обработчик после DSR. На текущем этапе реализована только серверная часть текстового пути до ответа; голосовой и пользовательский контуры ещё соединяются.

Почему нужен LLM-router

Ключевые слова недостаточны. Фраза «Я попал в аварию вчера, заявление уже подал; когда придут деньги?» относится к статусу страхового случая, а не к сценарию ДТП, которое произошло только что. Одна реплика также может содержать несколько намерений, смену темы или смешение русского и казахского языков.

LLM получает:

• текущую реплику и ограниченный контекст сессии;
• описания всех 40 сценариев и 3 системных намерений;
• границы not_this_if, приоритеты и примеры RU/KK;
• словарь слотов.

LLM возвращает структурированное решение. Сервер повторно проверяет его по Zod-схеме и каталогу, определяет исход respond, clarify, handoff, out_of_scope или goodbye и только затем формирует ответ.

Структура проекта

data/voice-router/                 исходный набор организатора, без правок
data/voice-router-app/             производные привязки приложения к данным
src/shared/                        браузер-безопасные Zod-контракты
src/server/
  features/voice-router/           каталог, LLM-router, policy, сессии и HTTP API
  features/echo/                   инфраструктурная проверка starter
src/web/
  features/voice-router/realtime/  подготовленный браузерный аудиотранспорт
  features/echo/                   текущий экран проверки Vue → H3
tests/                              unit, API и SSR-регрессии
scripts/                            setup, doctor, test, build smoke и snapshot
docs/                               требования, фазы, runbooks и журнал прогресса

Ограничения архитектуры и правила разработки находятся в AGENTS.md. Полные требования и критерии приёмки — в TASK.md.

Требования

Для итоговой сдачи должны работать:

• голосовой ввод и голосовой ответ в браузере;
• содержательный выбор сценария через LLM, без encoder intent classifier;
• весь исходный каталог из 40 сценариев;
• русский, казахский и смешанная речь;
• несколько намерений и смена темы без потери контекста;
• трассировка после каждого хода: транскрипт, решение, причина, альтернативы и реальные задержки;
• ответы и mock-действия только по предоставленным данным;
• уточнение при неуверенности и handoff без выдуманного успеха;
• серверное подтверждение перед необратимым действием;
• воспроизводимый запуск и доступный deployment.

Ориентиры по скорости — около 500 мс на выбор сценария и до 1,5 секунды от конца речи до начала воспроизведения. Это бонусные показатели, а не основание скрывать ошибку или подменять реальный замер константой.

Локальный запуск

Требования

• Node.js 24.21+ в ветке 24.x;
• pnpm 10.28.0;
• ключ OpenAI — только для живого текстового LLM-маршрута.

Установка и настройка

В Phase 2 добавлен управляемый браузерный звонок на существующем /api/voice-router/ws: PCM16/16 кГц подаётся в OpenAI STT/VAD и Yandex SpeechKit, DSR сохраняет обе гипотезы и передаёт один подтверждённый текст тому же handleTurn, ответ озвучивается серверным ElevenLabs V3. Если STT, LLM или TTS недоступен, интерфейс показывает это явно. Локальные тесты не означают, что сквозной звонок с реальными провайдерами уже принят: платные API и микрофон в живом браузере не проверялись.

pnpm install --frozen-lockfile
pnpm run setup

setup создаёт .env из .env.example, только если .env ещё не существует. Секреты не должны попадать в Git или переменные VITE_*.

Для текущего серверного LLM-маршрута заполните:

OPENAI_API_KEY=...

Переменные Yandex и ElevenLabs уже перечислены в .env.example, но их наличие пока не включает рабочий DSR или TTS: соответствующие серверные интеграции ещё не подключены.

Development

pnpm dev

• Web: http://127.0.0.1:5173
• API: http://127.0.0.1:3000
• Health: http://127.0.0.1:3000/api/health

Текущий web-экран проверяет только starter Echo. Текстовый Voice Router API можно вызвать отдельно:

curl -X POST http://127.0.0.1:3000/api/voice-router/turn \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"123e4567-e89b-42d3-a456-426614174000","turnId":"123e4567-e89b-42d3-a456-426614174001","text":"Деньги списались, а полис не пришёл","source":"text"}'

Без OPENAI_API_KEY endpoint отвечает контролируемым статусом unavailable; фиктивный успешный маршрут не создаётся.

Сброс состояния сессии:

curl -X POST http://127.0.0.1:3000/api/voice-router/reset \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"123e4567-e89b-42d3-a456-426614174000"}'

Проверка

pnpm run check
pnpm run verify

• check запускает TypeScript/Vue typecheck и тесты Node.
• verify последовательно запускает doctor, проверку форматирования, check, production build и smoke собранного приложения.
• Обычные тесты не требуют платных API-ключей.
• Живые проверки OpenAI, Yandex, ElevenLabs, микрофона и deployment должны фиксироваться отдельно; unit-тесты не доказывают их работоспособность.

Другие полезные команды:

Команда	Назначение
pnpm run doctor	Проверить версию Node, lockfile, локальный .env и H3 1.x.
pnpm run build	Собрать сервер в dist/server и Vue-приложение в dist/web.
pnpm start	Запустить production-сборку.
pnpm run smoke -- <URL>	Проверить health, API и web уже запущенного экземпляра.
pnpm run format	Отформатировать репозиторий; команда изменяет файлы.

Подробный порядок проверки: docs/runbooks/VALIDATION.md.

Docker

docker compose up --build -d
pnpm run smoke -- http://127.0.0.1:3000

Compose публикует порт только на localhost. Это не является публичным deployment. Ключи провайдеров нужно передавать серверу безопасным способом; в текущем compose.yaml они намеренно не заданы.

Данные и безопасность

• Saqta Insurance, клиенты, полисы, цены, клиники и операции полностью синтетические.
• Данные не описывают реальные продукты Halyk и не являются юридической консультацией.
• Относительные даты вычисляются от 2026-10-01, а не от даты запуска приложения.
• Исходные файлы data/voice-router/ нельзя менять ради улучшения метрик.
• Приложение не должно выполнять реальные звонки, платежи, отправку SMS или изменение production-систем.
• API-ключи остаются только на сервере и не попадают в публичные DTO, трассировку или клиентский bundle.

Документация

• TASK.md — полные требования и финальная приёмка.
• docs/README.md — карта документации.
• docs/STATUS.md — текущий рабочий снимок.
• docs/implementation/README.md — фазы реализации.
• docs/runbooks/DEMO.md — сценарий демонстрации.
• docs/runbooks/SUBMISSION.md — контроль перед сдачей.
• data/voice-router/README.ru.md — оригинальное описание набора на русском языке.

Происхождение

Starter, комплект организатора и возможные компоненты TalkIt не считаются результатом конкурсных пяти часов. Их происхождение, ограничения использования и новый вклад раскрываются в docs/compliance/PREEXISTING.md. Историю, результаты тестов, метрики и разрешения нельзя восстанавливать или отмечать задним числом.

Настройка голосового звонка после интеграции

Для голосового звонка задайте серверные ключи нужных провайдеров из .env.example. Нажатие на визуализатор устанавливает WebSocket-соединение и запускает запись после разрешения микрофона; повторное нажатие завершает звонок. «Закончить реплику» отправляет записанный звук на обработку. Микрофон требует localhost или HTTPS. Локальному запуску нужен ffmpeg в PATH; runtime Docker-образ устанавливает его. Ручного кода доступа нет: перед публичным развёртыванием обеспечьте внешнее ограничение доступа и расходов как для голоса, так и для текстового API. Исполнение действий относится к следующей фазе и не подключено.