Voice Router

Голосовой AI-робот для контакт-центра. Клиент говорит свободным текстом на русском или казахском языке, система сохраняет контекст разговора, выбирает один или несколько из 40 сценариев и формирует голосовой ответ. Супервизор видит транскрипт, причины выбора, альтернативы, действия и задержки.

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

• голосовой ввод через микрофон и резервный текстовый ввод;
• OpenAI STT, LLM-маршрутизация и TTS;
• 40 бизнес-сценариев и 3 системных маршрута;
• русский, казахский и смешанная речь;
• несколько намерений в одной реплике;
• история до 10 пар реплик, очередь запросов и возврат к отложенной теме;
• Structured Outputs с выбранным сценарием, уверенностью и альтернативами;
• все 31 mock-действие из actions.json;
• ответы на основе базы знаний и mock backend;
• подтверждение перед необратимыми действиями;
• очередь оператора с полным контекстом разговора;
• панель супервизора со статистикой, сомнениями, ошибками и задержками;
• официальный открытый dev-набор и локальные регрессионные тесты.

Быстрый запуск

Требуется Python 3.11 или новее. Сторонние Python-пакеты не нужны.

PowerShell:

$env:OPENAI_API_KEY="ваш-новый-ключ"
$env:OPENAI_MODEL="gpt-4o-mini"
python app.py

Откройте http://127.0.0.1:8000.

Без OPENAI_API_KEY интерфейс запускается в демонстрационном режиме. Для реальной маршрутизации, распознавания и синтеза речи ключ обязателен. Не записывайте ключ в исходный код или JSON-файлы.

Как работает система

Микрофон или текст
        ↓
OpenAI STT
        ↓
Контекст диалога и активные темы
        ↓
LLM Router → сценарий, confidence, причины, альтернативы
        ↓
Сценарный движок → mock-действия и ответ из данных
        ↓
OpenAI TTS + трассировка для супервизора

Если в реплике несколько запросов, первый становится активным, а остальные сохраняются в очереди. При смене темы текущий сценарий помещается в стек. После явного завершения или отмены система закрывает только указанную тему.

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

.
├── app.py                 # HTTP-сервер, LLM Router, действия, STT/TTS
├── data/                  # все JSON-данные и результаты оценки
├── static/
│   ├── index.html         # интерфейс
│   ├── styles.css         # дизайн
│   └── app.js             # клиентская логика
├── predict_dev.py         # получение предсказаний на dev-наборе
├── evaluate.py            # расчёт метрик dev-набора
├── evaluate_edges.py      # многошаговые пограничные проверки
├── test_router.py         # локальные тесты логики
└── README.md

Данные

Все JSON-файлы находятся в папке data/.

Файл	Назначение
scenarios.json	40 сценариев, примеры, границы, слоты и действия
slots.json	Типы слотов и вопросы на русском и казахском
actions.json	31 mock-действие и очереди операторов
knowledge_base.json	Продукты, тарифы, офисы, клиники и правила
mock_backend.json	Тестовые клиенты, полисы, выплаты и платежи
dialogs_sample.json	Размеченные примеры диалогов
dev_utterances.json	104 открытых тестовых реплики
edge_dialogues.json	Пограничные многошаговые диалоги
predictions.json	Последние предсказания модели; не добавляется в Git
dev_metrics.json	Последние рассчитанные метрики

Mock backend работает в памяти. Созданные полисы, заявки и изменения контактов сбрасываются после перезапуска сервера.

Проверка

Локальные тесты без запросов к OpenAI:

python -B -m unittest test_router.py

Проверка синтаксиса:

python -B -m py_compile app.py evaluate.py predict_dev.py evaluate_edges.py
node --check static/app.js

Получение предсказаний и расчёт метрик:

$env:OPENAI_API_KEY="ваш-новый-ключ"
python predict_dev.py
python evaluate.py

Результаты сохраняются в data/predictions.json и data/dev_metrics.json. Последний прогон открытого набора: 104 из 104 по основному и полному маршруту. Это не гарантирует такой же результат на скрытых данных.

Проверка многошаговых пограничных диалогов:

python -B evaluate_edges.py

API

Метод	Адрес	Назначение
GET	/api/config	Модели, количество сценариев и действий
GET	/api/stats	Статистика супервизора и dev-метрики
GET	/api/handoffs	Последние передачи оператору
POST	/api/route	Маршрутизация текстовой реплики
POST	/api/transcribe	Распознавание аудио
POST	/api/speech	Синтез ответа

Пример текстового запроса:

{
  "session_id": "demo-1",
  "text": "Деньги списались, но полис не появился. И ещё нужен офис в Алматы"
}

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

Переменная	Значение по умолчанию
OPENAI_API_KEY	не задано
OPENAI_MODEL	gpt-4o-mini
OPENAI_STT_MODEL	gpt-4o-mini-transcribe
OPENAI_TTS_MODEL	gpt-4o-mini-tts
OPENAI_TTS_VOICE	marin
OPENAI_SERVICE_TIER	fast
OPENAI_BASE_URL	https://api.openai.com/v1
EVAL_WORKERS	4
PORT	8000

Ограничения

• бизнес-интеграции сейчас являются mock-реализацией;
• данные не сохраняются после перезапуска;
• dev-набор открытый и использовался при разработке;
• для production нужны авторизация, постоянная база данных, аудит действий, независимый hidden-набор и отдельная проверка казахского STT на реальном аудио.