# WebRTC / Voice AI Короткая голосовая или текстовая сессия через собственную WebRTC-инфраструктуру. Транспорт и LangGraph работают реально, ASR/LLM/TTS заменены обозначенными моками. Статус: passed Версия: `b16c97886356285f0c0624d16803dd96edcef2e8`. История кода: с октября 2025. Публичный runtime и собственный TURN: 7 сентября 2026. ## Задача Диалоговый runtime должен связать сигналинг, передачу медиа, маршрутизацию запроса и завершение сессии, не оставляя незакрытых соединений. ## Аудитория Разработчики голосовых интерфейсов и real-time AI-систем. ## Личный вклад - WebRTC-транспорт, обмен через DataChannel и оркестрация исходного LangGraph. - Сценарии echo, маршрутизация в free_speech, отмена по таймауту и повтор. - Собственный ограниченный TURN, короткие сессии и наблюдаемые счётчики без записи аудио. ## Решения - Браузер использует relay через собственный coturn. SDP ограничен одним аудиопотоком и DataChannel. - Исходный WorkflowEngine и handlers сохранены; MockIO заменяет внешние AI-вызовы. - ASR возвращает фиксированную фразу только после фактического получения аудиокадров. Вместо TTS передаётся короткий тон. - Сессия живёт 90 секунд и допускает десять сообщений. Старое закрытие соединения проверяет идентичность сессии и не завершает новую. ## Границы и ограничения - Фиксированная ASR-фраза не является распознаванием речи. Короткий тон не является синтезированной речью. - Одновременно разрешены две сессии; третья отклоняется. Аудио не записывается, контекст хранится в памяти и удаляется. - TURN разрешает peer только на адресе собственной VPS, имеет квоты и короткие credentials. - Микрофонные QA-потоки созданы синтетическим устройством Chromium; передача DTLS/SRTP, TURN и счётчики медиа реальны. ## Что попробовать - Подключитесь без микрофона и отправьте echo: ответ проходит исходный граф. - Проверьте шаблонный ответ, таймаут LLM и успешный запрос после отмены. - Разрешите микрофон, дождитесь аудиокадров на сервере и примените мок ASR. - Откройте stats, сбросьте контекст и дождитесь автоматического завершения через 90 секунд. ## Проверки - Два unit-теста графа, 14 production-кадров, две одновременные аудиосессии и фактический TTL 90 секунд. - Real relay/DataChannel, original echo, mock LLM, timeout then retry, context reset and close - Two real simultaneous audio sessions; third rejected; closing other session preserves first - Actual 90-second expiry closes RTC and deletes context - Подтверждённого GitHub CI для этого SHA нет; перечислены выполненные локальные проверки и сценарии опубликованной версии. Исторические CI-ссылки, если есть, отмечены отдельно. ## Результаты - Сохранено 14 содержательных кадров фактического интерфейса. - Дата, сценарий и версия указаны у каждого кадра. - Максимум RAM контейнеров в коротком тесте: 89.62 MiB. Общие службы учитываются отдельно; магазин включает свою БД. - Измерено 2 повторений сценария; медиана 3660.5 мс, максимум 4226 мс. Время включает браузер и HTTPS; методика и ограничения приложены. - Два аудиопотока подтверждены серверными кадрами и browser getStats. Третье подключение отклонено лимитом. ## Запуск и эксплуатация - Исходная архитектура допускает внешние ASR/LLM/TTS. Публичный runtime использует только MockIO и не хранит аудио. Реальная транспортная часть проверена getStats и серверным счётчиком кадров. - Dockerfile.portfolio собирается вне VPS. App слушает 127.0.0.1:18406, coturn — 3478 UDP/TCP. Host network нужен для ICE на публичном интерфейсе; служебные HTTP-порты наружу не открыты. - TURN-конфигурация root-only содержит auth secret; её нельзя публиковать в документации. Разрешён только peer VPS, не произвольные внешние адреса. До 16 краткоживущих TURN allocations, но не более двух пользовательских RTC-сессий. - Проверять /healthz, ICE relay, поступающие кадры и DataChannel. При сетевом сбое завершить сессию и повторить. TTL закрывает соединение через 90 секунд; таймаут графа через две секунды не мешает следующему запросу. - Общие правила эксплуатации: готовые файлы и закреплённые образы собираются вне VPS; секреты не входят в артефакты. Общесерверный docker prune не применяется. Логи backend ограничены ротацией, изменения log options требуют пересоздания контейнера. - Перед изменением пройти code-map от функции к экрану/API, модулю и данным. После изменения обновить карту и схемы, выполнить связанные сценарии, включая ошибку, повтор и сброс. Источник истины — конкретная версия кода, а не старая диаграмма. - Откат проверен 2026-09-07T01:06:33.669720+00:00: 20260907-verified → 20260907e → 20260907-verified. После каждого переключения подтверждены HTTPS, readiness и SHA. Это проверка конфигурации и артефактов на одном проверенном SHA; обратная миграция БД не выполнялась. ## Стек и роль - **WebRTC / aiortc**: Настоящие ICE, DTLS/SRTP, аудио и DataChannel. - **coturn**: Собственный ограниченный relay, временные credentials и peer allowlist. - **Python / aiohttp**: HTTPS-сигналинг за Nginx, жизненный цикл сессий и счётчики. - **LangGraph**: Исходная маршрутизация echo/free_speech, память и отмена. ## Code-map |Функция|Экран / API|Модуль|Данные / проверка| |---|---|---|---| |Сигналинг|GET config / POST offer|portfolio/server.py config, offer|HMAC cookie; SDP validate; production QA| |Аудио|Микрофон / stats|receive_audio; MockTone|кадры без записи; два настоящих потока| |Граф|DataChannel text/asr|portfolio/runtime.py; WorkflowEngine|echo/free_speech; два unit-теста| |Таймаут / повтор|LLM timeout button|DemoRuntime.run / asyncio.wait_for|отмена через 2 с; успешный повтор| |Срок сессии|status / DELETE session|expiry; close; state_change|память; 90-секундная production QA| ## Схемы - Компоненты опубликованного демо — `diagrams/components.mmd` - Основной сценарий — `diagrams/scenario.mmd` - Размещение опубликованной версии — `diagrams/deployment.mmd` - Исходный интеграционный контур — не развёрнут в демо — `diagrams/original.mmd` ## Индекс изображений - 01-overview: Назначение, реальный транспорт и явные моки ASR/LLM/TTS; 2026-09-07T00:37:52.304Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 02-disconnected: Начальное состояние с выбором микрофонного или текстового режима; 2026-09-07T00:37:52.780Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 03-connected: Реальный WebRTC DataChannel и ICE relay через собственную VPS; 2026-09-07T00:37:55.095Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 04-echo: Исходный LangGraph echo без вызова модели; 2026-09-07T00:37:55.684Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 05-llm-mock: Ответ через исходный граф и детерминированный MockIO; 2026-09-07T00:37:56.199Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 06-timeout: Отмена графа по таймауту через две секунды; 2026-09-07T00:37:59.018Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 07-retry: Успешный запрос после отмены предыдущего графа; 2026-09-07T00:37:59.517Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 08-stats: Фактические getStats, принятые аудиобайты и серверные счётчики; 2026-09-07T00:37:59.988Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 09-audio-ingress: Настоящие микрофонные кадры на сервере; ASR отдаёт явно фиксированную фразу; 2026-09-07T00:38:03.574Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 10-second-audio-mobile: Вторая параллельная голосовая сессия на мобильном экране; 2026-09-07T00:38:07.508Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 11-session-limit: Третье соединение отклонено серверным лимитом двух сессий; 2026-09-07T00:38:08.479Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 12-mobile-overview: Мобильное описание транспорта и моков; 2026-09-07T00:38:08.930Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 13-mobile-dialog: Текстовый сценарий через WebRTC на узком экране; 2026-09-07T00:38:11.431Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 - 14-expiry: Автоматическое закрытие и удаление контекста через 90 секунд; 2026-09-07T00:39:41.262Z; SHA b16c97886356285f0c0624d16803dd96edcef2e8 ## Подробности runtime из репозитория # Voice AI: один Python runtime и собственный WebRTC relay Адрес https://voice.komaroff-dev.ru/. Демо подготовлено 7 сентября 2026. Дата подготовки не является датой начала разработки исходной системы. ## Что работает реально Браузер создаёт RTCPeerConnection с audio + DataChannel. HTTPS используется только для config/SDP/status; сообщения сценария идут через настоящий DataChannel. Собственный coturn на этой VPS принудительно используется как relay. SDP фильтруется до публичного адреса VPS; TURN может обращаться только к этой же VPS, без произвольного проксирования. Краткоживущие TURN credentials действуют 120 секунд. Медиа защищены DTLS/SRTP. `portfolio.runtime.DemoRuntime` вызывает исходный `src_langgraph.engine.WorkflowEngine`. Используются исходные dispatch, echo, free_speech, contracts и bounded conversation memory. RuntimeIO заменён MockIO; отдельные NATS/LLM/ASR/TTS/Ruby процессы в демо не запускаются. Это консолидация публичного сценария, а не исходная распределённая топология проекта. ASR отдаёт фиксированную фразу только после приёма аудиокадров; это не транскрипция речи. LLM router/response детерминированы. TTS заменён коротким синусоидальным тоном и текстом. По команде «таймаут» мок задерживается, asyncio.wait_for отменяет граф через две секунды. Сценарий echo проходит настоящий граф без LLM-вызова. ## Изоляция и ограничения Два одновременных соединения, одно на подписанную cookie, до 90 секунд и 10 сообщений. Текст до 280 символов, один audio stream и один DataChannel. Произвольные uploads, внешние tools, API и запись аудио отключены. Сервер считает кадры и сразу отбрасывает их. Контекст хранится только в памяти процесса, удаляется при завершении/таймауте/рестарте. Сброс очищает контекст, сохраняя лимит сообщений и время текущей сессии. Микрофон активируется только соответствующей кнопкой. Есть полноценный текстовый режим без разрешения на микрофон; транспорт остаётся WebRTC. ## Code-map | Функция | Экран/API | Модуль | Данные / проверка | |---|---|---|---| | Подключение | кнопка → config/offer | portfolio/server.py, исходный validate_sdp | SDP + короткая TURN auth; live ICE QA | | Аудио | getUserMedia → RTCPeerConnection | receive_audio / MockTone | только счётчики, без записи; media byte/frame QA | | Текст | DataChannel portfolio | handle_message → DemoRuntime | память одной сессии; runtime tests | | Оркестрация | события LangGraph | src_langgraph.engine + scenarios | исходные trace/runtime contracts | | Timeout/retry | «Таймаут LLM» | MockIO + wait_for | отмена графа; timeout then echo test | | Завершение | DELETE session / 90 s | close + expiry | освобождение PC/track/tasks/memory | Перед изменением проследить сигналинг, ICE, медиа, DataChannel, граф и ответ. После правки обновить карту/схемы и проверить два соединения, таймаут, повтор и очистку. Рабочую и демонстрационную архитектуру показывать раздельно. ## Сборка / эксплуатация Dockerfile.portfolio: Python3.12 digest + полный requirements.lock. Сборка вне VPS. Runtime 384 MiB / 0.8 CPU, coturn 96 MiB / 0.3 CPU, logs 3×5 MB. Host networking нужен для ICE публичного интерфейса; HTTP привязан только к 127.0.0.1:18406. Открыт TURN3478 UDP/TCP, relay ports 49160–49179 используются локальными peers этой VPS. TURN quota 2 на пользователя / 8 всего, bandwidth 128000 B/s на сессию и 512000 B/s всего. Healthcheck приложения проверяет процесс; фактическое прохождение медиа проверяется отдельно. LangSmith tracing отключён. Секреты только в серверном .env, не в Git или образе. Источники технических контрактов: https://aiortc.readthedocs.io/en/latest/api.html, https://github.com/coturn/coturn/blob/master/README.turnserver.