Pipecat использует трехслойную архитектуру для интеграции речевых моделей, запущенных на Amazon SageMaker AI. Понимание этого паттерна поможет вам подключить и другие модели помимо сервисов Deepgram, включенных в пример. Исходный код всех слоев находится в репозитории Pipecat в каталоге pipecat/services/aws/sagemaker/.
Слой 1: SageMakerBidiClient
На базовом уровне Pipecat предоставляет SageMakerBidiClient — многократно используемый HTTP/2-клиент, обрабатывающий протокол двунаправленной потоковой передачи SageMaker. Он управляет аутентификацией SigV4, жизненным циклом сеанса и фреймингом бинарных и текстовых сообщений:
Клиент подключается к runtime.sagemaker.<регион>.amazonaws.com:8443 и использует InvokeEndpointWithBidirectionalStream из AWS SDK. Параметры model_invocation_path и model_query_string сопоставляются с внутренней маршрутизацией контейнера, что позволяет направлять запросы к различным API моделей на одном эндпоинте.
Слой 2: Обертка сервиса (TTSService или STTService)
Обертка сервиса расширяет базовый класс TTSService или STTService из Pipecat и реализует протокол, специфичный для конкретной модели. Например, DeepgramSageMakerTTSService преобразует интерфейс run_tts(text) в Pipecat в сообщения протокола WebSocket для Deepgram:
Фоновая задача (_process_responses) непрерывно считывает данные из двунаправленного потока (BiDi stream), разделяя бинарные аудиоданные и JSON-сообщения управления (Flushed, Warning, Error, Close) и направляя их соответствующему обработчику.
Обертка STT следует тому же паттерну с model_invocation_path="v1/listen", отправляя «сырое» аудио с помощью send_audio_chunk() и анализируя JSON-ответы с результатами распознавания от Deepgram. Она также отправляет сообщения KeepAlive каждые 5 секунд для поддержания соединения в периоды тишины и Finalize, когда модуль VAD обнаруживает конец речи, чтобы выдать промежуточные результаты.
Слой 3: Интеграция в конвейер (Pipeline)
Фабрика сервисов (backend/voice-agent/app/services/factory.py) выбирает провайдера во время выполнения на основе переменных среды. Переключайтесь между облачными API и эндпоинтами SageMaker без изменения кода конвейера:
Интеграция собственной модели
Чтобы добавить новую речевую модель, развернутую на Amazon SageMaker AI с поддержкой двунаправленной потоковой передачи, следуйте этому паттерну:
- Определите протокол контейнера. Выясните путь маршрута (например, /v1/synthesize), параметры запроса и формат сообщений, ожидаемый вашим контейнером модели (JSON-команды, бинарное аудио или и то, и другое). Ваш контейнер должен принимать соединения WebSocket на порту 8080 по пути /invocations-bidirectional-stream, куда Amazon SageMaker AI перенаправляет объединенный поток.
- Расширьте базовый класс сервиса. Создайте подкласс TTSService или STTService и реализуйте необходимые методы: для TTS метод run_tts(text) отправляет текст, возвращает чанки TTSAudioRawFrame и обрабатывает сигналы сброса/завершения (flush/completion); для STT метод run_stt(audio) отправляет чанки аудио, а процессор ответов выдает TranscriptionFrame при поступлении результатов распознавания.
- Настройте BiDi-клиент. Установите model_invocation_path и model_query_string в соответствии с маршрутизацией вашего контейнера. SageMakerBidiClient берет на себя аутентификацию и HTTP/2-фрейминг.
- Обрабатывайте события жизненного цикла. Реализуйте _connect() для запуска сеанса и фоновых задач, _disconnect() для корректного завершения работы и handle_interruption(), если ваша модель поддерживает отмену посреди потока.
Любой контейнер модели, предоставляющий интерфейс двунаправленной потоковой передачи на Amazon SageMaker AI, может быть обернут с использованием этого паттерна. Это включает модели из сторонних маркетплейсов и пользовательские модели, развернутые с помощью vLLM или Triton. Чтобы внести свой вклад в виде новой обертки сервиса, сделайте форк репозитория Pipecat, реализуйте свой класс сервиса по описанному выше паттерну и откройте пулл-реквест. Вы можете использовать агент кодирования на базе ИИ, такой как Claude Code или Kiro, чтобы создать заготовку реализации на основе существующих оберток Deepgram в качестве примера.
