Voice Router — HackAlem AI · Кейс Halyk Bank

Команда doter · Кейс 2: гибридный голосовой AI-робот с LLM-выбором сценария.

Открыть живое демо · Соответствие кейсу · Проверки

Демо открывается без регистрации. Для локальной проверки жюри в приватный репозиторий включён .env.jury с готовыми ключами: свои API-аккаунты не нужны.

Voice Router превращает разговор на русском, қазақша или смешанном языке в проверяемый сценарий обслуживания. Клиент говорит и слышит ответ, а супервизор видит транскрипт, решение LLM, краткое объяснение, альтернативы, действия и задержки. Перед изменением данных сервер запрашивает отдельное подтверждение.

Это прототип для кейса Halyk Bank на HackAlem AI. Предметные сценарии сохранены из вымышленного страхового датасета организаторов: банковские продукты и факты к нему не добавлялись. Все клиентские данные учебные; приложение не выполняет реальные платежи, SMS или страховые операции.

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

Нужно: Git, запущенный Docker Engine / Docker Desktop с Compose v2 и доступ в интернет. На Windows в Docker Desktop выберите Linux containers. Для голоса нужен современный браузер с микрофоном.

Клонируйте репозиторий под GitHub-аккаунтом, которому организаторы выдали доступ:

git clone https://github.com/BAITC-Hacks/hack-c5d95581-doter.git
cd hack-c5d95581-doter

Из корня проекта запустите приложение и PostgreSQL одной командой — она одинакова в PowerShell, macOS и Linux:

docker compose --env-file .env.jury up --build -d --wait

После успешного завершения откройте http://localhost:3000/. Первый запуск скачивает образы и зависимости; --wait ждёт готовности приложения и БД. Включённая конфигурация уже содержит ключи OpenAI и Gemini для проверки жюри. Ключи передаются серверу при запуске, исключены из Docker-образа и не отправляются браузеру.

Выберите провайдера и модель → «Начать разговор» → разрешите микрофон. В шумном помещении используйте «Без микрофона»: текстовый ввод сохраняет голосовой ответ, маршрутизацию и вызовы инструментов. Для удалённого адреса нужен HTTPS; localhost подходит для локального микрофона.

Проверка готовности: откройте http://localhost:3000/api/health — ожидаются status: "ok" и готовое PostgreSQL-хранилище. История переживает перезапуск, поскольку хранится в Docker volume. Порт базы не опубликован на хосте.

# Состояние контейнеров
docker compose --env-file .env.jury ps

# Остановка с сохранением истории
docker compose --env-file .env.jury down

Не добавляйте -v, если нужна история: этот флаг удаляет volume. Пароль БД в комплектной конфигурации предназначен для изолированного локального демо. Развёртывание на VPS с HTTPS описано в deployment/README.md.

# Windows PowerShell
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

npm ci
node --env-file=.env.jury server.mjs

Демонстрация для жюри

1. Голос и знания: «Где находится офис в Алматы?» — адрес и часы берутся из KB; рядом появляется SC33 и результат get_offices.
2. Контекст и смена языка: «Ал Астанада ше?» — город меняется, тема сохраняется, ответ переходит на казахский.
3. Несколько намерений: «Хочу продлить полис и узнать про КАСКО» — видны активная тема и очередь; незавершённая тема сохраняется при переключении.
4. Точный поиск факта: «Объясните, что не покрывает КАСКО» — SC40 выбирает исключения и показывает путь к факту в KB. Если нужного сведения нет, ассистент уточняет или сообщает об отсутствии данных.
5. Подтверждение действия: попросите изменить контакт учебного клиента из mock_backend.json. Проверьте предварительный просмотр; только отдельное «Да, подтверждаю» или кнопка разрешает действие. Повтор того же события не выполняет операцию снова.
6. Прерывание и супервизор: начните новую реплику во время ответа; проверьте остановку старого аудио. После «Завершить» откройте «История последнего диалога» — там сохраняются тексты, решения, действия и состояние. Проверенный ответ ядра и окончательный транскрипт озвучки хранятся отдельно.

«Новый диалог» создаёт новую копию учебного бэкенда. PostgreSQL сохраняет журнал предыдущего разговора, но не превращает учебные операции в общую CRM. История привязана к HttpOnly cookie браузера: одна ссылка не даёт доступ из другого браузера. Cookie действует 30 дней; запись в БД сама по себе не восстанавливает оборванное Live-соединение.

Реализованные возможности

Полная привязка к требованиям — матрица соответствия; выполненные проверки — журнал верификации. Все 40 маршрутов подключены к серверному ядру; отсутствие календаря или нужного правила приводит к уточнению/оператору, а не к выдуманному успеху операции.

Архитектура

flowchart LR
    B[Браузер: микрофон / текст] <-->|WebSocket| S[Node.js]
    S <-->|аудио и события| L[OpenAI Realtime / Gemini Live]
    L -->|route_turn| R[Сценарное ядро]
    D[Каталог / слоты / KB / mock backend] --> R
    R --> V[Валидация / подтверждение / действия]
    V -->|проверенный ответ| L
    R --> T[Трасса и состояние]
    T --> B
    T -->|очередь записи| P[(PostgreSQL: история)]

LLM выбирает сценарий по описаниям и границам каталога. Размеченные dev-реплики не входят в runtime prompt; таблицы ответов и encoder intent classifier нет. Внутри уже выбранного информационного сценария сервер выбирает конкретные факты из JSON KB — это отдельная операция, не подмена LLM-маршрутизации.

Сервер проверяет значения слотов, принадлежность полисов и правила расчётов. Необратимое mock-действие проходит preview и отдельное подтверждение конкретных аргументов. Смена аргументов требует нового preview; повторная доставка одного хода не создаёт повторную операцию.

Промпт разделяет роль, вызов инструмента, маршрутизацию, источники фактов и подтверждения; сверено с официальными OpenAI Realtime prompting и Gemini Live best practices.

Аудио ответа пропускается только после результата route_turn. Модели предписано озвучивать проверенный ответ без добавлений; эта инструкция не является формальным доказательством побуквенного совпадения речи. При прерывании старое воспроизведение очищается, поздние события прежнего хода отбрасываются.

Стек: Node.js 24, ws, pg, PostgreSQL 17, HTML/CSS/JavaScript, Web Audio / AudioWorklet. Сборщика и UI-фреймворка нет. Noto Sans хранится локально с лицензией OFL; внешних CDN-запросов нет. История записывается отдельно от критического пути голосового ответа; ошибка записи показывается пользователю. Учебные предметные данные изолированы в памяти каждой сессии.

Данные и внешние сервисы

В демо используются только данные организаторов и синтетический ввод. Отдельные STT/TTS API, embeddings, векторная БД, CRM и банковские сервисы не подключены. Клиентский звук не сохраняется приложением.

Выбор провайдера и модели

OpenAI показывает разговорные Realtime-модели из каталога аккаунта. Все варианты остаются доступными в селекторе. Метки описывают проверенный профиль точного model ID; неизвестным моделям не приписываются цена или качество по названию.

Тарифы проверены 23.09.2026 по официальным OpenAI model docs, Realtime 2.1 Mini и Google pricing. Это ставки токенов, не цена минуты разговора: история, кэш, время прослушивания и транскрипция влияют на итог. Сравнительного теста качества OpenAI против Gemini не проводилось. Старые модели отмечены отдельно; их доступность в каталоге не гарантирует успешный вызов.

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

Локальные тесты без API-ключей и платных вызовов:

npm ci
npm test

Тесты покрывают сценарные расчёты, владение объектами, подтверждения, повтор операций, контекст, поиск знаний RU/KK, события Live API, прерывания, старое аудио, выбор модели, историю и изоляцию доступа. Для интеграционного теста настоящей БД задайте HISTORY_TEST_DATABASE_URL; без него этот тест явно пропускается.

Реальный прогон OpenAI gpt-realtime-2.1 на всех 104 dev-репликах, 23.09.2026, с prompt ревизии 44b279c:

Предсказания и отчёт с метаданными опубликованы без разговоров и секретов. Проверить арифметику оригинальным оценщиком можно без платного вызова:

python -X utf8 evaluation/evaluate.py docs/evaluation-predictions.json evaluation/dev_utterances.json

После этого прогона в prompt явно добавлено требование product_type для SC40, уже обязательное в ядре. При финальной проверке также уточнены дословная озвучка ответа инструмента, доступность только route_turn и работа с фоновым шумом. Полный показатель новой редакции ещё не измерен.

Остались расхождения U040 (неясный запрос вместо оценки автомобиля) и U044 (лишнее системное намерение). Это один сохранённый прогон отдельных текстовых реплик; он не доказывает качество всех диалогов, физического микрофона или скрытого набора жюри.

Для нового платного прогона с ключами из .env:

npm run evaluate -- --limit 10
npm run evaluate -- --all --resume
node --env-file=.env tools/smoke-audio.mjs openai
node --env-file=.env tools/smoke-audio.mjs gemini --reuse

--resume проверяет совпадение модели, prompt, схемы и набора. Эталон используется только при подсчёте результата. Ошибки API останавливают прогон, пропуски не заполняются выдуманными ответами. Свежие результаты остаются в gitignored artifacts/.

Оба провайдера прошли синтетический PCM → route_turn → ядро → голосовой ответ. В браузере проверены текстовые запросы с озвучкой, в том числе смена RU → KK и города в Gemini. Физический микрофон и акустическое перебивание требуют ручной проверки с устройством участника.

Честные измерения задержки

Задержка воспроизведения включает передачу событий и не является акустическим измерением. Для нативных STT/TTS отдельных таймингов нет; недоступные значения показаны как «—». Gemini может не отдавать надёжную границу конца речи. Бонусные ориентиры 500 мс / 1,5 с не заявляются как достигнутые; для них нужен отдельный согласованный голосовой прогон и медиана по набору.

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

Границы и развитие

• CRM, телефония, платежи, SMS и календарь не подключены. Моки поверх JSON предусмотрены набором кейса. Поддерживаемые изменения применяются только к копии данных текущего диалога.
• PostgreSQL сохраняет журнал, а не общую предметную CRM. Восстановления активного разговора после разрыва и семантического vector RAG пока нет.
• В KB нет всех возможных определений и правил. В таких случаях нужен уточняющий вопрос или оператор; модель не дополняет базу догадками.
• Для коммерческой эксплуатации понадобятся роли пользователей, политика хранения/удаления, аудит доступа, ограничения нагрузки и реальные интеграции. Демонстрационный доступ по cookie не заменяет полноценную учётную запись.
• Следующие шаги: измерение на реальных RU/KK разговорах, контролируемое расширение KB, production CRM/телефония и сравнение моделей на одинаковом наборе.

Данные и критерии — README организаторов. Интеграции — официальные OpenAI Realtime и Gemini Live. За проект отвечает команда doter; вопросы и воспроизводимые ошибки можно оставить в Issues этого репозитория.

Сдача: push в GitHub не заменяет отправку решения на платформе хакатона. Участнику нужно отдельно подать репозиторий и демонстрацию на странице кейса.