Realtime VoiceChat API¶

NemotronLabs VoiceChat(model_type: "nemotron_voicechat", architectures: ["NemotronVoiceChatForConditionalGeneration"])은 전이중(full-duplex) 음성 대 음성 모델입니다. 16 kHz 오디오를 80 ms 프레임 단위로 받고, 프레임마다 assistant 텍스트 토큰, function 채널 토큰, 사용자 전사 갱신, 22.05 kHz assistant 음성 80 ms를 하나의 공통 타임라인 위에 출력합니다. 침묵과 겹치는 발화도 타임라인에 그대로 포함되며 음성 구간 검출(VAD) 단계는 없습니다.

mlxcel은 이 모델을 mlxcel generate로 오프라인 실행하고, mlxcel serve와 mlxcel-server의 /v1/realtime WebSocket으로 실시간 서비스합니다. 프로토콜은 mlx-vlm 레퍼런스 서버(mlx_vlm/server/realtime.py)를 따릅니다.

체크포인트¶

양자화 변환본에서도 음성 인코더, RNNT 전사 분기, EAR-TTS 음성 생성기, codec은 bf16으로 남습니다. 변환된 MLX safetensors 레이아웃만 로드하며 원본 NeMo .nemo 체크포인트는 로드하지 않습니다.

프레임 생성 과정¶

오프라인 CLI¶

mlxcel generate -m models/NemotronLabs-VoiceChat-11B-4bit \
  --audio question.wav --output-audio response.wav \
  -p "Be concise and answer in one sentence."

이 명령은 [user] <transcript>, assistant 텍스트, 그리고 function 채널 출력이 있으면 [function] <text>를 출력하고, 타임라인 전체를 담은 22050 Hz mono PCM16 response.wav를 씁니다.

--audio 없이 대화형 mlxcel generate를 실행하면 오프라인 명령을 안내하며 이 체크포인트를 거부합니다.

스트리밍 프로파일¶

--stream --profile은 단계별(perception, rnnt, language, tts, codec, total) 프레임 시간의 평균, p50, p95, 최댓값과 realtime_factor = mean total / 80 ms를 보고합니다. 이 값이 1.0을 넘으면 실시간보다 느립니다. 다른 작업이 없는 Apple M1 Ultra(128 GB)에서 짧은 질문에 추가 디코딩 3초를 붙여 측정한 결과는 다음과 같습니다.

로더는 인코더, EAR-TTS backbone, EAR-TTS mixture-of-Gaussians head를 f32로 보관합니다(bf16에서 정확히 변환). 상주 메모리가 약 2.7 GB 늘어나는 대신 프레임마다 가중치를 캐스팅하지 않습니다.

진단용 변수 두 개로 프로파일을 더 세분할 수 있습니다.

서비스¶

mlxcel-server -m models/NemotronLabs-VoiceChat-11B-4bit --port 8080
# 또는
mlxcel serve --model models/NemotronLabs-VoiceChat-11B-4bit --port 8080

서버는 전용 realtime 엔진 스레드에서 체크포인트를 로드하고 GET /v1/realtime을 WebSocket 업그레이드 경로로 마운트합니다. 이 체크포인트에서는 chat worker, batch scheduler, 텍스트 warmup을 시작하지 않습니다. /v1/chat/completions, /v1/completions, /v1/responses, /v1/messages는 /v1/realtime을 안내하는 메시지와 함께 501 Not Implemented를 반환합니다.

제한¶

세션 슬롯은 세션이 끝나면 반환됩니다. commit이나 cancel 뒤에 반환되고, 클라이언트가 연결을 끊으면 서버가 flush하지 않은 세션을 먼저 취소한 뒤 반환합니다.

프로토콜¶

모든 메시지는 JSON 텍스트 프레임입니다.

클라이언트 메시지¶

session.update 전에는 session.update와 session.ping을 제외한 모든 메시지에 invalid_request 오류("send session.update before audio")로 응답합니다. 설정 후에는 알 수 없는 type이 invalid_request 오류이고, JSON 객체가 아닌 프레임도 invalid_request 오류를 받지만 연결은 유지됩니다.

서버 이벤트¶

모든 이벤트에는 event_id(event_ 뒤에 16자리 16진수)가 붙습니다.

기준이 되는 값은 누적 필드인 text와 transcript입니다. delta는 누적 디코딩 결과가 이전 결과를 이어 늘린 경우 새로 붙은 부분입니다.

오류 코드¶

교환 예시¶

>로 시작하는 줄은 클라이언트 메시지이며 event_id 값과 오디오 payload는 생략했습니다.

{"type":"session.created","session":{"id":"sess_…","state":"configuring","input_audio_format":{"type":"pcm16","sample_rate":16000},"output_audio_format":{"type":"pcm16","sample_rate":22050}}}
> {"type":"session.update","session":{"system_prompt":"Be concise and answer in one sentence.","seed":0}}
{"type":"session.updated","session":{"id":"sess_…","state":"ready","model":"nemotronlabs-voicechat-11b-4bit","frame_samples":1280,"input_audio_format":{"type":"pcm16","sample_rate":16000},"output_audio_format":{"type":"pcm16","sample_rate":22050}}}
> {"type":"input_audio_buffer.append","audio":"…","sample_rate":16000}
{"type":"response.audio.delta","frame_index":0,"delta":"…","format":"pcm16","sample_rate":22050,"channels":1,"audio_codes":[…]}
{"type":"conversation.item.input_audio_transcription.delta","frame_index":5,"delta":"What","transcript":"What"}
{"type":"response.text.delta","frame_index":24,"token_id":…,"delta":"The","text":"The"}
> {"type":"input_audio_buffer.commit"}
{"type":"input_audio_buffer.committed"}
{"type":"response.done","frame_index":61}

입력, system prompt, seed가 같으면 세션은 mlxcel generate --stream과 같은 결과를 계산합니다. 다만 CLI의 WAV writer는 샘플에 32768을 곱하고 wire 형식은 32767을 곱하므로 오디오 파일이 바이트 단위로 같지는 않고, 샘플마다 양자화 한 단계만큼 차이가 날 수 있습니다.

모델은 말하는 동안에도 입력을 계속 받고 서버는 음향 반향 제거를 하지 않습니다. 마이크를 쓰는 실시간 클라이언트는 헤드폰으로 응답을 재생해야 하며, 스피커로 재생하면 모델이 자신의 답변을 다시 입력으로 받습니다.