← Docs hub

해외 업체 LLM Live 테스트 가이드

해외 업체가 Release APK로 Gemini Live의 음성 대화와 Barge-in을 확인할 때 필요한 구성을 두 가지로 정리한다. Gemini API key는 APK에 넣지 않는다.

현재 PoC 기준 브랜치

이 문서는 아래 Live 전용 브랜치를 기준으로 한다. 일반 릴리즈 브랜치가 아니라 두 브랜치의 형상을 함께 사용해야 앱과 Broker의 WebSocket 계약이 일치한다.

먼저 선택할 방식

A. SK Staging Gateway

SK Cloud가 외부에서 접근 가능한 wss://.../llm/live를 제공한다. 업체는 Release APK와 endpoint만 설정한다. API key, model, prompt와 Gemini 연결은 SK Cloud가 관리한다.

이 방식은 설치가 가장 단순하지만, 현재 로컬 Broker를 그대로 인터넷에 공개해서는 안 된다. 운영 전에는 TLS, 기기 인증, 연결 제한과 원본 PCM 비저장 로그가 적용된 Staging Gateway가 필요하다.

B. 업체 PC Local Broker

업체 PC가 Python Broker를 실행하고 실기기가 그 PC에 연결한다. 이 경우 업체는 Gemini API key를 PC 환경 변수로만 설정한다. 소스, APK, Android property와 전달 문서에는 키를 넣지 않는다.

Local Broker 준비

cd backend-cloud-llm-lambda-main
python3 -m pip install -r requirements-live-local.txt
export GEMINI_API_KEY='<server-side-api-key>'
./scripts/run_gemini_live_broker.sh

기본 주소는 다음과 같다.

Live WebSocket: ws://0.0.0.0:8765/llm/live
Health:         http://0.0.0.0:8766/healthz
Readiness:      http://0.0.0.0:8766/readyz

키가 로그에 출력되지 않는지 확인하고, 테스트가 끝나면 해당 shell의 환경 변수를 해제한다.

기기 연결

방법 1. adb reverse

기기가 업체 PC의 adb에 연결돼 있다면 이 방식이 가장 단순하다.

adb reverse tcp:8765 tcp:8765
adb shell setprop persist.sys.debug.deviceagent.LlmManager.enableGeminiLive true
adb shell setprop persist.sys.debug.deviceagent.LlmManager.geminiLiveEndpoint \
  'ws://127.0.0.1:8765/llm/live?device_id=<serial>'
adb shell setprop persist.sys.debug.deviceagent.LlmManager.geminiLiveApiKey ''

방법 2. 같은 LAN

기기에서 접근 가능한 PC LAN IP를 사용한다. WSL 내부 IP가 아니라 Windows 또는 Linux PC의 실제 LAN IP가 필요하며, 방화벽에서 TCP 8765를 허용해야 한다.

adb shell setprop persist.sys.debug.deviceagent.LlmManager.enableGeminiLive true
adb shell setprop persist.sys.debug.deviceagent.LlmManager.geminiLiveEndpoint \
  'ws://<PC_LAN_IP>:8765/llm/live?device_id=<serial>'
adb shell setprop persist.sys.debug.deviceagent.LlmManager.geminiLiveApiKey ''

SK Staging Gateway를 사용할 때는 endpoint만 wss://<staging-host>/llm/live?...로 바꾼다.

테스트 순서

1. /readyz가 정상이고 model, broker path가 기대값인지 확인한다.
2. Release APK가 플랫폼 인증서로 서명됐는지 확인하고 설치한다. Debug APK는 사용하지 않는다.
3. Wake-up 뒤 일반 질문으로 SK_19 Live 진입과 첫 PCM 재생을 확인한다.
4. 답변 중 사용자가 말해 TTS가 멈추고 새 질문이 처리되는지 Barge-in을 확인한다.
5. 두 번째와 세 번째 질문까지 대화 문맥과 자막이 이어지는지 확인한다.
6. 제품 명령은 Device API가 한 번만 실행되고 Live 음성과 중복 발화하지 않는지 확인한다.
7. “그만하자”와 5초 무발화에서 UI, AudioRecord, AudioTrack과 WebSocket이 함께 닫히는지 확인한다.
8. 위 시나리오를 20회 반복해 앱 재시작, 무음, 중복 TTS와 자원 누수가 없는지 확인한다.

로그에서 볼 항목

원본 음성과 전체 전사는 기본적으로 저장하지 않는다. 문제 분석에 샘플이 필요하면 시험자 동의, 보관 기간과 삭제 절차를 먼저 정한다.

전달 패키지

현재 PoC와 운영의 차이

현재 Python Broker는 평문 ws://와 device_id query만 사용한다. 같은 LAN 또는 adb reverse 시험에는 사용할 수 있지만 인터넷 공개용 서버가 아니다. 외부 Staging/운영 환경에는 아래가 필수다.

• wss:// TLS와 기기 인증
• API key의 Secret Manager 보관
• 동시 연결, frame 크기, 전송률과 세션 시간 제한
• 느린 client backpressure와 양쪽 WebSocket 동시 정리
• 원본 PCM·전체 전사를 남기지 않는 구조화 지표
• 장애 시 Live 세션 종료와 기존 경로 1회 fallback

관련 문서

• LLM Live
• 현재 Broker
• 기기 Runtime
• 튜닝 파라미터
• 향후 릴리즈 구조