함수 호출 기능 및 양방향 오디오 스트리밍을 지원하는 실시간 음성 AI 어시스턴트

저희는 Google의 Gemini Live API를 기반으로 하는 실시간 음성 AI 어시스턴트를 구축했습니다. 이 어시스턴트는 네이티브 오디오 기능, 도메인별 계산을 위한 맞춤형 함수 호출 기능, 그리고 WebSocket 기반 오디오 스트리밍을 사용하는 React 프런트엔드를 갖추고 있습니다.

아키텍처

• AI 모델: 네이티브 오디오 입/출력 및 함수 호출 기능을 갖춘 Gemini
• 백엔드: 양방향 오디오를 위한 WebSocket 엔드포인트를 갖춘 Python/FastAPI
• 오디오 파이프라인: 실시간 스트리밍을 위한 마이크/스피커 I/O용 PyAudio
• 프런트엔드: 세션 제어 UI를 위한 Vite 및 Tailwind CSS를 사용한 React
• 통신: 저지연 JSON 메시징 및 바이너리 오디오 전송을 위한 WebSocket
• 멀티모달: 시각적 맥락을 위한 선택적 카메라 및 화면 캡처

실시간 오디오 파이프라인

양방향 스트리밍

시스템은 양방향으로 지속적인 오디오 스트림을 유지합니다:

• 입력: 16kHz 모노로 캡처된 마이크 오디오를 작은 프레임으로 분할하여 AI 모델로 실시간 스트리밍
• 출력: 24kHz로 수신된 AI 생성 음성을 스피커를 통해 즉시 재생
• 배칭 없음: 오디오 청크는 캡처되는 즉시 전송 — 축적 지연 없음
• 인터럽트 처리: 사용자가 어시스턴트의 응답 중간에 자연스럽게 중단할 수 있음

오디오 처리

• 입력 및 출력 모두 16비트 PCM 형식
• 음성 최적화를 위한 별도의 샘플 속도(16kHz 캡처, 24kHz 재생)
• 최소 지연 시간을 위한 작은 버퍼 크기
• 턴 사이의 시작/정지 간격 없는 연속 스트리밍

함수 호출 통합

작동 방식

도메인별 계산이 필요할 때 AI 모델은 대화 도중 로컬 Python 함수를 호출할 수 있습니다:

1. 사용자가 요청을 말합니다 (예: "오늘 점심을 놓쳤어요")
2. AI 모델이 음성을 텍스트로 변환하고 의도를 이해합니다.
3. 모델은 함수 호출이 필요하다고 판단하고 구조화된 요청을 보냅니다.
4. 백엔드는 함수 이름, 인수, 호출 ID를 추출합니다.
5. 로컬 함수가 도메인 계산을 실행합니다.
6. 결과는 구조화된 응답으로 모델에 다시 전송됩니다.
7. 모델은 결과를 포함하는 자연어 음성 응답을 생성합니다.

도메인 함수

시스템은 다음과 같은 시나리오에 대한 영양 중심의 함수 호출을 지원합니다:

• 놓친 식사 — 놓친 다량 영양소를 남은 식사에 재분배합니다.
• 계획되지 않은 음식 — 예상치 못한 섭취량에 맞춰 다가오는 식사를 조정합니다.
• 식사 대체 — 매크로 목표를 유지하면서 재료를 교체합니다.
• 활동 추적 — 칼로리 소모량을 추정하고 영양 버퍼를 조정합니다.

각 함수는 식품별 영양 프로필을 가진 매크로 데이터베이스를 사용하며, 자연스러운 응답을 위해 약간의 확률적 변동을 포함한 동적 계산을 수행합니다.

실행 안전성

• 함수 실행 중 마이크 입력은 중복을 방지하기 위해 일시 중지됩니다.
• 오래된 컨텍스트를 피하기 위해 대기 중인 오디오 프레임은 삭제됩니다.
• 함수 실행이 실패할 경우 오류 응답이 정상적으로 반환됩니다.
• 함수 완료 직후 정상적인 스트리밍이 재개됩니다.

백엔드 아키텍처

FastAPI WebSocket 서버

• 모든 클라이언트 통신을 위한 단일 WebSocket 엔드포인트
• 세션 라이프사이클 관리 (시작, 중지, 핑/퐁 헬스 체크)
• 세션 잠금으로 한 번에 하나의 활성 세션
• 개발 환경을 위한 CORS 미들웨어
• 모니터링을 위한 헬스 체크 엔드포인트

세션 관리

• 클라이언트 연결 시 모드 선택(오디오 전용, 카메라 또는 화면)과 함께 세션이 생성됩니다.
• 백그라운드 비동기 작업이 오디오 캡처, 처리 및 재생을 동시에 처리합니다.
• 리소스 정리와 함께 정상적인 연결 해제
• API 키 유효성 검사 및 오류 전파

멀티모달 입력 (선택 사항)

음성 외에도 시스템은 선택적 시각적 맥락을 지원합니다:

• 카메라 모드 — 대화의 시각적 맥락을 위해 웹캠 프레임(1fps)을 스트리밍합니다.
• 화면 모드 — 화면 정보 논의를 위해 화면 콘텐츠를 캡처합니다.
• 이미지는 전송 전에 크기가 조정되고 압축됩니다.
• 시각적 맥락은 AI가 관련성 높은 응답을 제공하는 능력을 향상시킵니다.

프런트엔드 인터페이스

• 세션 제어 — 명확한 상태 표시기와 함께 듣기 시작/중지
• 상태 표시 — 실시간 연결 및 세션 상태 (유휴, 연결 중, 활성, 오류)
• 테마 지원 — 지속성을 가진 밝은/어두운 모드
• 가이드 워크스루 — 첫 사용자들을 위한 단계별 데모
• WebSocket 관리 — 자동 재연결 로직

AI 모델 구성

• 네이티브 오디오 모달리티 (별도의 STT/TTS 파이프라인 없음)
• 여러 사전 설정된 음성 중 구성 가능한 음성 선택
• 어시스턴트의 개성, 응답 스타일 및 언어 처리를 정의하는 시스템 지침
• 매개변수 스키마를 포함한 모든 사용 가능한 함수에 대한 도구 정의
• 동일 언어 응답을 포함한 자동 언어 감지

주요 기능

1. 1초 미만 지연 시간 — 네이티브 오디오 모델은 STT/TTS 파이프라인 오버헤드를 제거합니다.
2. 실시간 양방향 오디오 — 청크당 50ms 미만의 지연 시간으로 연속 스트리밍
3. 함수 호출 — 대화 도중 실행되는 도메인별 계산
4. 자연스러운 중단 — 사용자는 특별한 명령 없이 어시스턴트를 자연스럽게 중단할 수 있습니다.
5. 다국어 지원 — 동일 언어 응답을 포함한 자동 언어 감지
6. 멀티모달 입력 — 시각적 이해를 위한 선택적 카메라 및 화면 컨텍스트
7. 세션 관리 — 잠금 및 리소스 정리 기능을 포함한 세션 라이프사이클 제어
8. 매크로 계산 — 식품별 매크로 프로필을 통한 동적 영양 조정
9. 오류 복구 — 함수 실패 및 네트워크 중단에 대한 정상적인 처리
10. 확장 가능 — 스키마 및 핸들러 정의를 통해 새로운 함수 추가 가능 — 아키텍처 변경 없음