Build real-time voice applications with vLLM-Omni on SageMaker AI – Part 1

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

AWS vLLM-Omni DLC로 Amazon SageMaker AI에 Qwen3-TTS를 배포하고, 하나의 지속적인 양방향 연결에서 텍스트를 보내며 생성 중인 음성을 스트리밍하는 구현 방법을 설명한다.

📌 핵심 요약

• Qwen3-TTS와 AWS vLLM-Omni DLC를 사용하는 예제는 Amazon SageMaker AI에서 전체 음성 생성이 끝나기 전에 오디오를 재생하며, Gradio 애플리케이션으로 동작을 확인한다.
• vLLM-Omni는 텍스트·오디오·이미지·비디오 모델을 지원하는 런타임이다. 이전 Voxtral-Mini-4B 실시간 STT 예제와 이번 TTS 예제는 음성 입력과 출력을 각각 담당하지만, 두 엔드포인트 사이의 오케스트레이션은 설명 범위에서 제외된다.
• SageMaker 양방향 스트리밍은 포트 8443에서 HTTP/2로 전송되는 전이중 WebSocket을 사용한다. vLLM-Omni v1.5 DLC의 라우팅 미들웨어와 v1/audio/speech/stream 경로를 통해 텍스트 이벤트를 전달하고 24 kHz PCM 오디오 청크를 받는다.
• 인스턴스 풀은 ml.g6.xlarge를 우선 시도하고 용량이 없으면 ml.g6e.xlarge, ml.g5.xlarge, ml.g4dn.xlarge 순으로 대체하되 인스턴스는 하나만 배포한다. 구성에 포함된 모든 유형의 할당량이 필요하며, 선택된 유형에 따라 시간당 비용이 달라질 수 있다.
• 배포에는 Python 3.12 이상, Boto3 1.40.0 이상, SageMaker Runtime HTTP/2 Python 클라이언트 0.4.0과 실행 역할·권한이 필요하다. 배포 스크립트는 스트리밍 스모크 테스트 결과를 validation-output.wav로 저장하며, 사용 후 엔드포인트·엔드포인트 구성·모델을 삭제해야 실행 중인 GPU 엔드포인트의 지속적인 과금을 피할 수 있다.

🧩 주요 포인트

1. 전문 런타임과 AWS 배포 통합 → vLLM-Omni의 다단계 멀티모달 처리 및 스트리밍 기능을 DLC로 패키징해 SageMaker AI에서 활용한다.
2. 음성 입력·출력 예제의 분리 → Voxtral-Mini-4B와 Qwen3-TTS는 상호 보완적이지만, 완전한 음성 애플리케이션에는 별도의 대화 로직과 오케스트레이션이 필요하다.
3. 인스턴스 대체와 리소스 수명 관리 → --instance-types로 할당량·가격·성능 조건에 맞게 풀을 제한하고, 스트리밍 검증부터 사용 후 삭제까지 배포 과정에 포함한다.

🧠 상세 정리

1. 전체 생성 완료를 기다리지 않는 음성 출력

음성 에이전트, 대화형 학습 애플리케이션, 접근성 도구, 고객 서비스 보조 도구는 긴 침묵 없이 응답해야 한다는 요구에서 출발한다. 이 글은 AWS vLLM-Omni Deep Learning Container(DLC)를 이용해 Amazon SageMaker AI에 Qwen3-TTS를 배포하고, 전체 응답의 음성 생성이 끝나기 전에 재생을 시작하는 방법을 설명한다. 클라이언트는 하나의 지속적인 양방향 연결로 텍스트를 보내고 생성된 오디오를 받으며, Gradio 애플리케이션에서 이를 체험한다. 글은 vLLM-Omni, WhisperX, llama.cpp 등 전문 DLC를 다루는 시리즈의 Part 1이고, Part 2는 같은 DLC 계열을 활용한 이미지·비디오 생성을 다룬다.

2. 전문 DLC와 vLLM-Omni의 역할

AWS Deep Learning Containers는 AWS에서 학습과 추론에 필요한 딥러닝 프레임워크 및 의존성을 Docker 이미지로 제공한다. 전문 추론 런타임용 DLC는 일반적인 텍스트 생성과 다른 모델 구조 및 미디어 처리 과정을 지원하도록 런타임과 배포 설정을 함께 패키징한다. vLLM-Omni는 vLLM을 확장해 텍스트, 오디오, 이미지, 비디오를 처리하거나 생성하는 모델을 제공하며, 이기종 파이프라인 추상화로 자기회귀 단계와 확산 단계를 포함한 다단계 작업을 조정한다. 스트리밍 출력과 OpenAI 호환 API도 제공하고, 지원 범위에는 통합 omni 모델, 자동 음성 인식, TTS, 오디오·이미지·비디오 생성이 포함된다. AWS vLLM-Omni DLC는 관리 대상 vLLM-Omni 릴리스를 AWS 이미지에 담고 SageMaker AI용 라우팅 미들웨어를 추가하며, 이 글은 양방향 오디오 출력을 보여주는 구체적인 사례로 Qwen3-TTS를 선택한다.

3. 기존 음성 인식 예제와의 연결 범위

이전 글인 Build real-time voice applications with Amazon SageMaker AI and vLLM은 음성 파이프라인의 입력 측을 다룬다. 해당 예제에서는 마이크 오디오를 Voxtral-Mini-4B Realtime STT 모델로 스트리밍하고, 애플리케이션에 전사 이벤트를 반환한다. 이번 글은 출력 측을 추가해 응답 텍스트를 Qwen3-TTS로 보내고, vLLM-Omni DLC를 통해 생성된 음성을 스트리밍한다. 음성 애플리케이션은 전사 결과를 대화 로직에 전달한 다음 그 응답을 이번 TTS 예제에 연결할 수 있지만, 두 엔드포인트를 조정하는 오케스트레이션은 이번 설명에 포함되지 않는다. 따라서 두 예제는 음성 입력과 출력의 상호 보완적인 경로를 보여주며, 완전한 대화 흐름을 통합하는 부분은 별도로 남는다.

4. 양방향 연결과 오디오 이벤트의 이동 경로

전체 샘플은 저장소의 03-features/bidirectional-streaming-vLLM-Omni에 있으며, 배포 스크립트와 공통 스트리밍 전송 코드, Gradio 클라이언트를 함께 사용한다. SageMaker 양방향 스트리밍은 HTTP/2로 전송되는 전이중 WebSocket을 노출하고, 클라이언트는 포트 8443의 SageMaker Runtime 엔드포인트에 연결한다. SageMaker 추론 사이드카는 연결을 컨테이너 내부의 vLLM-Omni 기본 WebSocket 경로로 전달한다. 클라이언트가 세션 설정과 텍스트 이벤트를 보내면 Qwen3-TTS는 같은 연결로 오디오 생명주기 이벤트와 24 kHz PCM 청크를 반환한다. vLLM-Omni v1.5 DLC에는 SageMaker AI에 필요한 양방향 스트리밍 기능 레이블과 라우팅 미들웨어가 추가되었으며, 샘플은 v1/audio/speech/stream 경로를 사용한다.

5. 인스턴스 풀의 대체 순서와 할당량 조건

엔드포인트 구성은 하나의 프로덕션 변형에 호환 인스턴스 유형을 우선순위 순으로 지정하는 SageMaker 인스턴스 풀을 사용한다. SageMaker는 ml.g6.xlarge를 먼저 시도하고 용량을 확보할 수 없으면 ml.g6e.xlarge, ml.g5.xlarge, ml.g4dn.xlarge 순으로 대체한다. 이 구성은 풀 항목마다 인스턴스를 만드는 방식이 아니라 최종적으로 인스턴스 하나를 프로비저닝한다. 엔드포인트 생성 시에는 구성된 모든 풀 항목의 할당량을 검증하므로, 실제 선택되는 유형뿐 아니라 포함한 각 유형의 가용 할당량이 필요하다. 대체 유형에 따라 시간당 비용도 달라질 수 있어, 샘플의 --instance-types 옵션으로 할당량·가격·성능 요구에 맞는 유형만 남길 수 있다.

6. 실행 환경 준비와 스트리밍 배포 설정

사전 준비에는 AWS CLI 또는 AWS SDK용 자격 증명이 설정된 AWS 계정, Git, Python 3.12 이상, SageMaker AI 실행 역할, 엔드포인트 생성·호출 권한이 포함된다. 라이브러리 조건은 Boto3 1.40.0 이상과 SageMaker Runtime HTTP/2 Python 클라이언트 0.4.0이며, 사용할 풀 인스턴스 유형의 엔드포인트 할당량도 필요하다. 예제는 미국 동부 버지니아 북부 리전인 us-east-1을 기본으로 사용하고, AWS_REGION을 바탕으로 DLC 이미지 URI와 런타임 엔드포인트를 구성하며 --region으로 다른 지원 리전을 지정할 수 있다. 저장소를 복제해 샘플 디렉터리로 이동한 뒤 가상 환경에서 requirements.txt를 설치하고 SAGEMAKER_EXECUTION_ROLE_ARN을 설정한다. HTTP/2 WebSocket을 처리하는 SageMaker 사이드카에는 추론 AMI 설정이 필요하며, 모델 호출 경로의 선행 슬래시는 SageMaker가 전달 전에 추가하므로 설정에서는 생략해야 한다.

7. 엔드포인트 배포와 Gradio 스트리밍 검증

deploy_bidi_stream.py를 --keep-endpoint와 함께 실행하면 DLC 기반 SageMaker 모델, 엔드포인트 구성, 실시간 엔드포인트가 생성되며, SM_VLLM_MODEL 환경 변수가 로드할 모델을 지정한다. 스크립트는 스트리밍 스모크 테스트를 실행해 validation-output.wav를 저장하고, 첫 배포에서는 DLC 이미지와 모델 아티팩트를 내려받는 시간이 필요하므로 엔드포인트가 InService 상태가 될 때까지 기다린다. 이후 sagemaker_bidi_tts_client.py를 실행하고 브라우저에서 http://127.0.0.1:6006에 접속하며, 공개 링크를 만드는 --share 옵션은 필요한 경우에만 사용한다. 사용자가 텍스트와 음성·언어를 선택하면 클라이언트는 session.config로 PCM 출력과 stream_audio를 설정하고 input.text 및 input.done 이벤트를 보낸다. Gradio 오디오 구성 요소는 수신하는 24 kHz PCM 청크를 차례로 재생하고, 상태 필드는 청크 수와 전체 오디오 바이트 수를 표시한다.

8. 리소스 정리와 후속 활용

샘플 사용이 끝나면 Gradio 프로세스를 중지하고 deploy_bidi_stream.py의 --delete-endpoint 옵션으로 엔드포인트, 엔드포인트 구성, 모델을 삭제한다. 정리 명령이 세 리소스의 삭제를 보고하는지 확인해야 하며, 도중에 프로세스가 중단되면 SageMaker AI 콘솔이나 API로 삭제를 완료한다. 실행 중인 GPU 엔드포인트는 계속 과금되므로, 리소스 정리는 실습 종료 과정의 중요한 부분이다. 이 사례는 전문 AWS DLC가 일반 텍스트 생성과 다른 실행·스트리밍 패턴을 갖는 멀티모달 모델을 지원하는 방식을 보여주고, 이전 STT 예제와 함께 음성 입력 및 출력 경로를 제시한다. 글은 다른 지원 멀티모달 모델에 적용할 때 코드 샘플, vLLM-Omni DLC 문서, SageMaker AI 양방향 스트리밍 개발자 가이드를 참고하도록 안내하며, Part 2에서는 이미지와 비디오 생성을 다룬다.

🧾 핵심 주장 / 시사점

• 이 예제의 핵심은 전체 음성 생성이 끝나기 전에 청크를 재생하는 동작이며, 원문에는 지연 시간이나 처리량을 정량적으로 비교한 성능 수치는 제시되지 않는다.
• Voxtral-Mini-4B와 Qwen3-TTS 예제를 함께 사용하면 음성 입출력 경로를 구성할 수 있지만, 전사 결과에서 응답 텍스트로 이어지는 대화 로직과 엔드포인트 오케스트레이션은 별도로 구현해야 한다.
• 인스턴스 풀의 용량 대체 기능은 모든 포함 유형의 할당량 검증 및 유형별 비용 변동과 함께 고려해야 하므로, 기본 풀을 그대로 사용하는 것이 모든 환경에 적합한 것은 아니다.

✅ 액션 아이템

• Python 3.12 이상, Boto3 1.40.0 이상, SageMaker Runtime HTTP/2 Python 클라이언트 0.4.0과 실행 역할·권한을 확인하고 Qwen3-TTS 배포를 준비한다.
• --instance-types로 할당량·가격·성능 조건에 맞는 인스턴스 유형을 지정한다.
• validation-output.wav와 Gradio로 스트리밍 동작을 검증하고, 사용 후 엔드포인트·엔드포인트 구성·모델을 삭제한다.

❓ 열린 질문

• Voxtral-Mini-4B와 Qwen3-TTS 사이의 대화 로직과 오케스트레이션은 어떻게 구현할 것인가?
• --instance-types에 포함할 유형 중 할당량·가격·성능 조건을 충족하는 것은 무엇인가?
• Gradio에서 전체 음성 생성이 끝나기 전에 24 kHz PCM 오디오 청크가 재생되는가?