Gemini Live API, LiveKit 및 Google Cloud Run을 사용한 실시간 번역 앱 구축

영어로 말하면 전 세계의 청취자들이 스페인어, 일본어 또는 프랑스어로 실시간으로, 낮은 지연 시간과 자연스러운 음성 전달로 듣게 되는 것을 상상해 보세요.

이 가이드에서는 실시간 다국어 번역 방송(Real-Time Multilingual Translation Broadcast) 웹 애플리케이션을 구축하고 배포할 것입니다. 프론트엔드에는 Next.js를, 초저지연 WebRTC 오디오 전송에는 LiveKit Cloud를, 그리고 실시간으로 오디오 스트림을 번역하는 데는 Gemini Live API를 활용합니다.

마지막으로, 전체 애플리케이션을 컨테이너화하여 Google Cloud Run에서 프로덕션 준비가 된 자동 확장 서비스로 배포할 것입니다.

아키텍처 (Architecture)

저희 애플리케이션은 신호(signaling)를 빠르고 간단하게 유지하기 위해 단일 LiveKit Room 내에서 완전히 실행됩니다:

Organizer (말하는 사람)
      │ (WebRTC를 통한 음성 오디오)
      ▼
...

1. 오디오 수집(The Ingest): 호스트가 방송을 시작합니다. 그들의 음성 오디오는 LiveKit Room으로 스트리밍됩니다.

2. 요청 시 스핀업(On-Demand Spin-up): 청취자가 참여하여 언어(예: 스페인어)를 선택하면, Next.js 백엔드는 **번역 브릿지(Translation Bridge)**라고 불리는 전용 백그라운드 워커 스레드를 실행합니다.

3. 음성 번역(Vocal Translation): Gemini가 음성 스트림을 처리하고 실시간으로 번역된 오디오로 응답합니다.

4. 재생(Playback): 봇이 번역된 오디오 트랙을 LiveKit Room에 다시 게시하고, 청취자는 이 특정 봇 트랙을 렌더링합니다.

🛠️ 전제 조건 (Prerequisites)

시작하기 전에 다음 사항들을 준비했는지 확인하세요:

• 로컬에 Node.js 18+ 설치.
• LiveKit Cloud 계정 (무료 티어가 완벽합니다).
• gcloud CLI가 설치 및 인증된 Google Cloud 프로젝트.
• Live API 모델에 대한 접근 권한이 있는 Gemini API 키.

💻 단계별 설정 가이드 (Step-by-Step Setup Guide)

Step 1: 의존성 설치 (Install Dependencies)

프로젝트 루트로 이동하여 NPM 패키지를 설치합니다:

npm install

Step 2: 로컬 LiveKit 서버 시작 (Start a Local LiveKit Server)

2단계: 로컬 LiveKit 서버 시작 (Start a Local LiveKit Server)

로컬에서 설정을 테스트하려면, Docker를 사용하여 로컬 LiveKit 개발 서버를 쉽게 실행할 수 있습니다:

docker run --rm -p 7880:7880 -p 7881:7881 -p 7882:7882/udp \
  -e LIVEKIT_KEYS="devkey: secret" \
  livekit/livekit:latest \
...

3단계: 환경 변수 설정 (Configure Environment Variables)

프로젝트 루트에 .env.local 파일을 생성합니다. 이 파일은 로컬 환경에서 사용됩니다:

LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret
NEXT_PUBLIC_LIVEKIT_URL=ws://localhost:7880
...

4단계: 애플리케이션 로컬 실행 (Run the Application Locally)

Next.js 개발 서버를 실행합니다:

npm run dev

http://localhost:3000을 열어 애플리케이션을 확인하세요. 번역 테스트를 위해 한 탭은 방송 (Broadcast) (호스트)으로, 다른 탭은 시청 (Watch) (참석자)으로 여세요.

⚡ 지연 시간 및 성능 최적화: 100ms 청크 (Latency & Performance Optimization: 100ms Chunks)

실시간 WebRTC 스트림을 다룰 때, 표준 패킷 전송은 20ms 간격으로 작동합니다. 오디오 청크를 Gemini Live API로 50 Hz(초당 50회)로 전달하면 높은 네트워크 오버헤드와 CPU 사이클이 발생합니다.

성능을 최적화하기 위해, LiveKit의 네이티브 FFI 오디오 스트림을 사용하여 대신 100ms 청크를 캡처하도록 설정합니다.

translation-bridge.ts 파일에서 AudioStreamOptions 객체를 사용하여 AudioStream을 초기화합니다:

const audioStream = new AudioStream(track, {
  sampleRate: this.inputSampleRate,
  numChannels: this.channels,
...

이렇게 하는 이유?

• 주파수 감소 (Frequency Drop): Gemini로의 전송 주파수를 50 Hz에서 10 Hz (초당 10회)로 낮춥니다.
• 절충점 (The Trade-Off): 이는 서버 측 네트워크/CPU 직렬화 오버헤드를 극적으로 줄여주며, 지연 시간은 약간 증가하는 (~80ms) 수준에 그칩니다.

🐳 5단계: Docker를 사용한 컨테이너화 (Containerizing with Docker)

Next.js의 standalone 출력 빌드는 배포에 필요한 정확한 파일만 포함하는 고도로 최적화된 프로덕션 번들을 생성합니다.

The @livekit/rtc-node SDK는 네이티브 컴파일된 WebRTC 코어를 사용합니다. 초기화 과정에서 이 코어는 Cloud 설정을 확인하기 위해 HTTPS 요청을 수행합니다. node:slim과 같은 최소한의 Linux 이미지는 SSL 인증서를 포함하고 있지 않아 보안 연결에 실패할 수 있으며, 이는 조용히(silently) 발생할 수 있습니다. 따라서 저희는 멀티 스테이지 Dockerfile에서 명시적으로 ca-certificates를 설치했습니다:

# --- Build stage ---
FROM node:22-slim AS builder
WORKDIR /app
...

🚀 Step 6: Google Cloud Run에 배포하기

번역 브릿지(translation bridges)는 Gemini 및 LiveKit으로의 WebSocket 연결과 같은 장기 실행 프로세스이므로, 영구적인 컨테이너와 장기 실행 요청을 지원하는 Google Cloud Run에 배포할 것을 권장합니다.

1. Google Secret Manager에 비밀 정보 저장하기

자격 증명을 환경 변수(env vars)로 노출하는 대신, Google Secret Manager에 저장하세요:

source <(grep -v '^#' .env.local | sed 's/^/export /')

echo -n "$GEMINI_API_KEY" | gcloud secrets create gemini-api-key --data-file=-
...

2. Cloud Run에 비밀 정보 접근 권한 부여하기

기본 Compute Engine 서비스 계정(Default Compute Engine Service Account)에 이러한 비밀 정보를 읽을 수 있는 권한을 부여하세요:

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")

gcloud secrets add-iam-policy-binding gemini-api-key \
...

3. 서비스 배포하기

배포 명령을 실행하세요. 필요한 특정 Cloud Run 프로덕션 스케일링 구성에 유의하세요:

• --min-instances 1: 컨테이너가 따뜻하게(warm) 유지되어 활성 세션이 종료되는 것을 방지합니다.
• --max-instances 1: TranslationSessionManager 싱글톤은 단일 인스턴스를 필요로 합니다.
• --timeout 3600: 최대 1시간 동안 번역 세션을 허용합니다.
• --no-cpu-throttling: 요청 간 CPU 할당을 유지하여 오디오 처리 지연이 전혀 없도록 보장합니다.

gcloud run deploy live-translate \
  --source . \
  --region us-central1 \
...

4. 미래 코드 업데이트 배포하기 (환경 변수 변경 없이)

4. 미래 코드 업데이트 배포하기 (환경 변수 변경 없이)

서비스 구성 및 비밀 정보(secrets)를 설정했다면, 환경 변수를 반복하거나 재정의할 필요 없이 코드 업데이트를 배포할 수 있습니다:

gcloud run deploy live-translate --source . --region us-central1

Google Cloud Run은 이전 리비전에서 사용된 모든 환경 변수, 비밀 정보, 스케일링 제한 및 CPU 할당을 자동으로 유지합니다.

🎉 결론

이제 Google Cloud Run에 배포된 완벽하게 기능하는 프로덕션 레디 실시간 다국어 번역 방송 앱을 갖게 되었습니다!

우리가 배운 것:

• LiveKit WebRTC 오디오를 Gemini Live API와 연결하여 음성 스트림을 실시간으로 번역하는 방법.
• 네트워크 패킷 오버헤드를 최적화하기 위해 네이티브 FFI 스트림 옵션(frameSizeMs: 100)을 조정하는 방법.
• Google Secret Manager를 설정하고 견고한 다단계 Docker 구성을 Google Cloud Run에 배포하는 방법.

방송 활동 즐기세요! 🌐🎙️

다음 단계

• 문서를 읽어보세요.
• Google Colab을 실행해 보세요.
• GitHub에서 Gemini [Live API 예제]를 확인하세요: https://github.com/google-gemini/gemini-live-api-examples