← Docs hub

Gemini Live Server 소스 기반 서버 구성 분석

이 서버의 실행 스크립트 기본 구성은 기기 → Python WebSocket Relay → H200 Qwen3-Omni → Qwen3-TTS다. 저장소 이름에는 Gemini가 남아 있지만, run.sh는 Qwen 의도 분석과 별도 한국어 TTS를 기본으로 실행한다. Gemini Live는 RELAY_BACKEND=live로 선택하는 별도 경로다. 릴레이는 세션·모델 호출·명령 변환을 맡고, 실제 기기 동작은 function_call을 받은 기기가 실행한 뒤 function_result로 반환한다.

분석 기준은 gemini_live_server, 브랜치 qwen, 커밋 34b4d45(2026-09-07), 분석일 2026-09-08이다. 현재 체크아웃의 실행 코드·설정·배포 스크립트와 기존 오프라인 테스트를 확인했다. 원격 hop1/H200의 실행 환경·GPU 배치·실기기 성공 여부는 이번에 검증하지 않았다. 모델 이름과 포트는 소스 설정값이며 서비스의 현재 가용성을 뜻하지 않는다.

이 상세판은 배치도에 더해 객체·task 소유 구조, Qwen 명령 턴 시퀀스, 추측 발화 세 가지 타임라인, 기동·장애 확인 단계를 SVG로 설명한다. 표의 함수명과 행 번호는 위 커밋 기준이며, 예시 대화는 실제 캡처 로그가 아니다.

읽는 순서

1. 전체 서버 배치

Qwen HTTP 요청은 Relay의 UNIX socket에 연결되고 SSH가 H200으로 전달한다. 따라서 스크립트는 Relay에 Qwen용 TCP listen 포트를 추가하지 않는다. 실제 방화벽·라우팅은 별도 확인 대상이다. H200 모델 서버를 설치·실행하는 구성, GPU 스케줄링, vLLM 시작 옵션은 이 저장소에 포함되어 있지 않다.

2. 실행 방식에 따라 달라지는 기본값

아래 표는 관련 환경 변수를 사전에 지정하지 않았을 때의 값이다.

RELAY_BACKEND=qwen python server.py만 실행하면 run.sh가 설정하는 qwen_tools, TTS와 UDS는 자동 적용되지 않는다. resolve_command()는 오디오 입력이 있으면 카탈로그 Qwen 경로를 선택하지만, 텍스트 입력은 기본 FUNCTION_AGENT_BACKEND=gemini를 따를 수 있어 시험 경로도 달라진다. 반대로 run.sh의 live 분기에서는 Qwen용 환경 변수 초기화를 하지 않는다.

dev는 Tavily 호출을 막는 검색 profile이다. Gemini backend를 선택했을 때 Gemini API까지 차단하는 전역 무과금/오프라인 모드는 아니다. make_backend_factory()는 알 수 없는 backend 문자열도 Echo로 처리하므로 설정 오타가 명시 오류로 검출되지 않는다.

근거: server.py:271–296, run.sh:27–50, config.py, function_agent.py:185–198.

3. 모듈별 역할

현재 JSON 실수량은 tools_kr.json 35개, 도구 예시 130개, device_qa_kb.json 105개다. 도구 35개에는 device_qa, web_search가 포함된다. KB는 벡터 DB나 임베딩 검색이 아니라 분류 가점과 키워드 일치로 고르며, 점수가 낮으면 같은 분류의 첫 안내문으로 대체한다.

3.1 객체와 비동기 task는 누가 소유하는가

모델마다 OS 프로세스를 생성하는 서버가 아니다. Relay는 하나의 Python 프로세스 안에서 연결별 Broker.handle(ws) coroutine과 backend 객체를 만든다. Qwen 추론 프로세스는 원격 H200에 있다.

Backend는 abstract base class나 엄격한 interface validator가 아니라 기본 no-op method를 가진 클래스다. barge_in, confirm/cancel, device_event, text 입력 등 추가 기능은 Broker의 hasattr()로 지원 여부를 확인한다. 따라서 wire frame이 정의되어 있다는 사실만으로 모든 backend가 해당 기능을 구현했다고 볼 수 없다.

연결별 수신 루프는 frame handler를 순서대로 await한다. 일반 오디오 턴은 task를 만들어 바로 돌아오므로 기기 결과를 계속 받을 수 있지만, send_text()는 기존 턴을 기다리고 on_device_event()는 설명 생성까지 기다린다. 이 대기 중에는 같은 WebSocket의 다음 frame 처리도 지연될 수 있다. 프로세스 전체가 막힌다는 뜻은 아니다.

근거: server.py:33–51,74–184,186–265, qwen_session.py:88–149,246–267,330–335.

4. Qwen 한 턴의 처리 순서

1. 기기가 session_start를 보낸다. Relay는 일일 횟수를 검사하고 기존 동일 device 세션을 교체한다.
2. Qwen /models와 별도 TTS /audio/voices가 성공하면 session_ready를 보낸다.
3. 기기의 voice_start 이후에만 PCM을 버퍼에 쌓는다. utterance_end에서 발화를 확정한다.
4. PCM을 WAV/base64로 묶어 의도 모델에 보낸다. 별도 STT 서비스 없이 이 호출에서 전사와 의도를 함께 받는다.
5. 결과에 따라 아래 분기로 진행한다. 명령 실행은 기기 응답을 기다린다.
6. Qwen 답변 호출에 페르소나 prompt, 최근 최대 10턴, 현재 입력과 실행 결과/검색 근거를 전달한다.
7. 텍스트 delta를 text_output으로 보내고, 완성된 문장을 Qwen3-TTS에 차례로 전달한다.
8. PCM16 24 kHz를 스트리밍하고 마지막에 audio_end를 보낸다. 재생 완료 ACK는 별도로 받지 않는다.

현재 C 결과의 answer_hint를 그대로 발화하지 않고 _run_turn()이 전사를 다시 _speak()에 전달한다. 즉 의도 모델과 발화 모델은 논리적으로 역할을 나눈 순차 두 호출이며, 별도 모델 프로세스 두 개라는 뜻은 아니다. TTS 문장 합성도 await say(sentence)로 순차 실행되어 이전 문장을 합성하는 동안 다음 텍스트 delta 소비가 대기한다.

근거: qwen_session.py:296–450, qwen_session.py:452–582, function_agent_tools.py:218–270.

4.1 풍량 설정 한 턴을 함수 단위로 따라가기

예시 입력은 “풍량을 강풍으로 해줘”이고 모델이 set_air_cleaner_fan_speed(speed=4)를 골랐다고 가정한다. 도구 선택의 정확도를 주장하는 예시가 아니라, 선택 이후 서버의 실제 분기를 설명한다.

서버는 한 턴에서 모델이 여러 tool call을 써도 첫 번째만 처리한다. 도구 prompt 역시 최대 하나를 지시한다. 이는 여러 기기 작업을 의존성 순서대로 실행하는 planner나 transaction 엔진이 아니다.

4.2 의도 prompt, 답변 prompt, 되묻기 문맥의 차이

기본 의도 호출은 temperature=0, max_tokens=200, modalities=[text]로 응답을 받는다. 입력은 음성일 수 있다. 답변 호출은 temperature=0.7, 기본 max_tokens=160, streaming text를 요청한다. 이 설정은 코드값이며 “항상 같은 도구를 선택한다”거나 “160토큰 안에 항상 문장이 끝난다”는 보증이 아니다.

_history에는 최종적으로 사용자 전사와 assistant 답변만 append된다. 현재 턴의 원본 검색 근거, 기기 결과 구조체, 도구 Future가 그대로 장기 저장되는 구조가 아니다. 다음 의도 판단에 이 이력이 전달되지 않으므로 “방금 것 취소해줘”처럼 이전 실행을 가리키는 표현을 일반적인 작업 기억으로 해결한다고 설명하면 안 된다.

[기기 안내문], [기기 결과], [검색 결과], [그대로 말하기]는 답변 prompt의 의미 표시다. 특히 일반 턴의 “그대로 말하기”도 _speak()를 거치므로 문자열을 TTS에 직접 고정 주입하는 강제 경로가 아니다. 되묻기·timeout·dev 검색 안내도 모델이 다시 생성한다. 문구 보존은 prompt 규칙과 평가 대상이다. 바이탈의 _say_verbatim() + 별도 TTS는 준비된 설명 문장을 직접 합성하는 예외 경로다.

4.3 오디오 형식과 문장 스트리밍

문장 분할은 구두점 → 줄바꿈 → 길이 기준 순서로 검사한다. 길이 기준에서는 공백을 우선 찾고 없으면 설정 길이에서 자른다. 먼저 구두점 조건을 처리하므로 40이 모든 반환 조각의 절대 최대 길이는 아니다. 끝에 남은 텍스트는 flush()로 합성한다.

PCM sample은 2 byte인데 HTTP chunk 크기는 홀수일 수 있다. 홀수 끝 byte를 버리지 않고 다음 chunk와 합쳐 항상 짝수 byte로 전달하는 것이 synth_stream()의 핵심이다. 이는 샘플 정렬 보정이며 샘플률 변환이나 AEC가 아니다. Talker 경로는 base64 WAV chunk를 해독하고 출력률을 검사하지만 불일치 시 resampling 대신 warning을 남긴다.

발화 20초는 정상 실시간 입력 기준 PCM 약 640,000 byte, base64 약 853,336문자에 WAV header가 더해진다. 이는 형식 계산이지 메모리 상한이 아니다. 강제 확정은 PCM 수신 시 벽시계 경과 시간을 보고 수행하므로, 빠르게 몰아 보낸 입력의 byte 수를 20초 분량으로 제한하지 않는다. WebSocket max_size=2**22도 메시지별 제한이다.

근거: function_agent_tools.py:119–164,218–270, qwen_session.py:50–81,345–450,469–582, tts_client.py:25–110, server.py:267–268.

5. 기기와의 통신 계약

WebSocket text frame은 JSON, binary frame은 header 없는 PCM16 mono다. 입력은 16 kHz, 출력은 24 kHz를 전제로 한다. Echo는 입력 byte를 그대로 반환하는 시험용 예외다. 현재 serve()에는 URL path 분기나 /healthz, /readyz HTTP handler가 없다.

예를 들어 풍량 설정은 function_call에 <sk_2>(speed=4) 같은 토큰을 넣어 전달한다. Relay는 기기의 실제 상태를 직접 변경하지 않는다. call_id는 진행 중 Future를 찾는 상관관계 ID이며, 재접속을 넘는 중복 실행 방지 DB나 완료 이력으로 사용되지 않는다.

근거: protocol.py, server.py:121–184, qwen_session.py:452–467.

5.1 제어 frame 예시와 결과 해석

다음은 wire 형식을 설명하기 위한 합성 예시다. 실제 발화 캡처나 기기 실행 증거가 아니다.

{"type":"session_start","device_id":"DOC-DEMO","language":"korean"}
{"type":"session_ready"}
{"type":"voice_start"}

이후 PCM binary frame들을 보내고 아래 제어 frame을 보낸다.

{"type":"utterance_end"}
{"type":"function_call","call_id":"example-call-1","token":"<sk_2>(speed=4)","function":"풍량 설정","available_function":"{\"speed\": 4}"}
{"type":"function_result","call_id":"example-call-1","tts":"풍량을 강풍으로 설정했어요."}
{"type":"text_output","text":"풍량을 강풍으로 설정했어요."}

마지막 text는 응답 형식 예시다. 실제로는 여러 text delta와 PCM frame이 올 수 있고, 그 뒤 {"type":"audio_end"}가 전송된다. audio_end는 스피커 재생 완료도, 실제 기기 명령 성공 ACK도 아니다.

function_result.tts가 일반 문장이면 device_tts로, JSON으로 파싱되면 server 값으로 해석한다. 기기 JSON에 message가 있으면 이를 우선 안내하고, 그렇지 않으면 구조화된 결과를 모델이 문장으로 바꾼다. JSON으로 파싱된다는 사실만 검사하므로 기대하는 object schema까지 검증하는 계약은 아니다. 알 수 없거나 이미 timeout된 call_id는 warning을 남기며 진행 중 결과로 수용하지 않는다.

5.2 값이 없는 설정과 후속 답변

“볼륨 바꿔줘”를 모델이 set_volume으로 선택하되 인자를 비웠다고 가정하면, render_token()의 필수 값 검사에서 token을 만들지 못한다. 알고 있는 도구이므로 need_param이 되고 도구 metadata의 x_ask를 질문으로 사용한다. _last_need_param에 이 결과를 저장한다. 다음 “3으로”는 이전 도구 이름을 보강한 의도 prompt에 들어가 set_volume(volume=3)을 선택할 수 있다.

다만 모델이 처음부터 tool call 없이 설명문을 반환하면 status는 none이고, 이 경로는 동일한 need_param 상태를 보장하지 않는다. “의미상 되묻기처럼 들리는 답변”과 “서버가 되묻기 문맥을 저장한 상태”를 분리해 시험해야 한다.

GET은 get=True를 지원하는 도구에서 다른 인자를 제거하고 조회 token으로 변환한다. 해당 도구에 get 속성이 없으면 상태확인 QA로 보낸다. QA는 실제 기기 조회가 아니므로 안내 KB와 실시간 기기 상태를 같은 것으로 취급하면 안 된다.

근거: function_agent_tools.py:193–270, function_agent.py:168–182, qwen_session.py:337–343,354–356,380–397,452–467.

6. 세션·발화·중단 정책

Qwen barge_in은 진행 턴 취소, pending 기기 결과 대기 정리, 발화 버퍼 초기화 후 interrupted를 보낸다. 기기에서 이미 실행한 명령을 되돌리는 rollback은 없다. utterance_cancel도 아직 보류된 frame을 폐기할 뿐이다. confirm 없이 3초가 지나면 function_call도 전송될 수 있으므로 “명시 확정 없이는 절대 실행하지 않음”은 현재 계약이 아니다.

의도 분석과 검색은 동기 HTTP를 executor thread에서 실행한다. asyncio 턴 task를 취소해도 이미 시작된 thread의 HTTP 요청까지 즉시 중단되는 것은 아니다. 출력 취소와 원격 계산 취소는 구분해야 한다.

근거: server.py:103–119,186–265, qwen_session.py:127–244,306–328,345–379, config.py.

6.1 추측 발화: 먼저 추론하고 나중에 내보내기

짧은 EPD에서 추론을 시작해 지연을 줄이되, 더 긴 확정 판단까지 외부 출력을 보류하는 방식이다. Relay에는 기기의 짧은/긴 EPD 시간을 정하는 코드가 없다. 기기가 보내는 frame을 처리한다. 3초 watchdog은 utterance_end(speculative=true)를 처리할 때 시작한다.

기기 응답 timeout은 실제 소켓 전송 순간이 아니라 _out(function_call) 반환 후 시작한다. 보류 중에는 _out이 즉시 반환하므로 보류 시간도 기본 20초 안에 포함된다. confirm 시각, 의도 모델 완료 시각, watchdog 시각을 함께 봐야 기기의 실제 응답 가능 시간을 계산할 수 있다.

_history append도 _out(audio_end)보다 먼저 실행된다. 일반 대화 턴이 보류 상태에서 끝난 뒤 cancel되면 기기에서 듣지 못한 답변이 이력에 남을 수 있다. 현재 cancel은 이력을 rollback하지 않는다. 또한 _open_gate()는 gate를 먼저 연 뒤 기존 frame을 await 전송하므로, flush 중 새 출력과 순서가 엄격하게 직렬화되는지는 느린 소켓 조건에서 추가 검증할 대상이다.

이 도식의 gate는 일반 _run_turn() 출력 경로 기준이다. 바이탈 _say_verbatim()의 text/audio_end와 일부 Broker 제어 메시지는 _send()를 직접 사용하므로 모든 서버 송신을 포괄하는 전역 장벽이 아니다.

6.2 끼어들기와 세션 종료는 다른 동작

세션 시작은 “새 backend 준비 → 기존 세션 교체” 순서가 아니라 기존 세션 종료 → 새 backend 준비 순서다. 또한 새 세션을 dict에 넣기 전에 backend start를 await하므로 같은 ID의 동시 start가 교차할 수 있다. 일반 순차 교체 테스트 통과와 경쟁 상황의 단일 세션 보장은 별도 문제다.

Qwen stop phrase는 의도 모델이 반환한 전사에서 공백을 제거한 부분 문자열로 찾는다. 따라서 종료 의도가 부정·인용된 문장까지 의도적으로 제외하는 parser는 아니다. stop 감지 뒤에도 실제 goodbye PCM의 재생 완료를 확인하지 않고 송신 byte 길이 + 유예 시간을 기다린다.

근거: qwen_session.py:151–244,315–328,345–379,441–467,574–582, server.py:186–265.

7. Gemini 경로와의 차이

Gemini 모델 후보는 gemini-3.1-flash-live-preview, gemini-2.5-flash-native-audio-latest다. 후보 전환은 세션 setup 실패 시 적용하며 Qwen/Gemini 간 자동 장애 전환은 없다. Gemini Live 키는 synthetic 키 또는 일반 키를 사용할 수 있지만 기존 Gemini 명령 해석기의 _get_client()는 GEMINI_SYNTHETIC_KEY만 읽는다. 일반 키 하나만으로 모든 Gemini 명령 기능이 준비됐다고 판단하면 안 된다. qwen_tools와 Live를 임의 혼합하면 Live가 해석 결과의 token을 직접 쓰지 않는 차이도 호환 시험이 필요하다.

근거: live_session.py:58–109,155–287, function_agent.py:44–52, config.py.

8. 배포와 운영 관측

deploy_hop1.sh는 코드 rsync → 기존 Relay 종료 → run.sh 실행 → TCP 8765 연결 확인 순서다. rsync --delete를 사용하고 logs/, test/, run/, .git/ 등은 제외한다. Python 의존성을 설치하지 않으며, 이 체크아웃에는 requirements/lockfile, Dockerfile, compose, systemd unit이 없다. server.py의 audioop 의존성도 런타임 버전 검토 대상이다.

run.sh는 중복 프로세스를 검사한 뒤 setsid nohup으로 백그라운드 실행하고 logs/relay.log에 기록한다. cron @reboot 연결은 주석에 설명돼 있으나 cron 등록 명령은 포함하지 않는다. 터널은 실패 후 5초 간격으로 재시도하지만 Relay 프로세스를 재기동하는 supervisor는 없다. 터널 준비 검사는 Qwen /models, 실제 Qwen 세션 준비는 TTS /audio/voices까지 확인한다. 배포 마지막 TCP 검사만으로 모델 추론·TTS·기기 명령 왕복이 정상임을 증명할 수 없다.

로그에는 세션 device ID/종료 이유/수명, 사용자 전사, 모델 답변, 도구 판단과 기기 안내문, Qwen 첫 오디오 및 전체 처리 시간이 기록된다. opt 검색은 logs/tavily/에 질의와 raw 응답도 저장한다. 따라서 이 서버를 “전사나 대화 내용을 저장하지 않는 단순 프록시”로 설명하면 틀린다. Qwen last_total_tokens는 최근 관측 응답의 값을 대입하므로 의도·답변·TTS를 합한 세션 총 비용 지표가 아니다.

8.1 기동 순서와 health check의 층

마지막 기능 확인은 별도 시험이 필요하며 배포 스크립트가 자동 수행하지 않는다. Qwen과 TTS 설정의 30초 HTTP timeout은 요청의 네트워크 timeout 설정이지, 전체 의도→기기→답변→TTS를 합친 턴 전체의 30초 deadline이 아니다.

8.2 지연을 어느 구간에서 나눠 봐야 하는가

정상 명령 턴의 첫 소리 지연을 해석하는 구성식은 다음과 같다. 실측 숫자를 대입한 결과가 아니다.

사용자 발화 끝 → 첫 소리
  ≈ 기기 EPD 대기 + 입력 전달/변환 + 의도 모델
    + 기기 왕복 + 답변의 첫 문장 생성 + 첫 TTS chunk
    + 출력 네트워크 + 기기 재생 queue

추측 발화에서는 계산과 확정 대기가 겹치므로 두 지연을 단순 합산하면 안 된다. 명령이 있는 턴은 command gate가 먼저 열려야 기기 왕복을 시작할 수 있다. 일반 대화는 PCM을 미리 합성해 보류할 수 있으므로 두 경우의 이득도 같다고 가정할 수 없다.

_run_turn()의 t0는 Relay가 턴 task를 시작할 때다. 로그의 intent: ... ms는 이 t0 이후 의도 해석까지, first_audio는 이 t0부터 TTS PCM을 처음 얻을 때까지다. 사용자가 듣기 시작한 시각은 아니다. gate가 닫혀 있어도 첫 PCM이 생성되면 first_audio가 기록될 수 있다. total 역시 기기 재생 완료를 기다린 시간이 아니며 기기 EPD 대기는 이 t0 밖에 있다.

8.3 증상별 확인 순서

검색은 기본 최대 5개 결과, 결과당 content 최대 700자를 근거로 만든다. 현재 날짜와 제목·출처·내용을 답변 모델 입력에 넣고 읽을 때 출처·번호는 말하지 않도록 prompt로 지시한다. Tavily 오류와 실제 무결과는 사용자 안내가 같을 수 있으므로 내부 source 값으로 구분해야 한다.

8.4 변경 시 어느 파일과 시험을 함께 봐야 하는가

이 표는 다음 변경의 영향 범위다. 이번 상세화 작업은 서버 로직을 수정하거나 원격 서버를 재기동하지 않는다.

9. 운영 전 확인할 구현 공백

아래는 소스에서 확인한 구조적 공백 또는 위험 후보다. 이번 작업에서 운영 장애를 재현했다는 뜻은 아니다.

10. 기존 문서와의 관계 및 검증 범위

기존 현재 Broker는 backend-cloud-llm-lambda-main/gemini/live_broker.py를 다룬다. 그 문서의 /llm/live, search_rag, /healthz, /readyz와 이번 저장소의 session_start, binary PCM, device_command, Qwen 경로는 서로 다른 구현이다. 기존 페이지의 2026-08 PoC 결과를 이 서버의 검증 결과로 옮기지 않는다.

이 저장소의 implementation_notes/01_gemini_live_server_구현_기록.md에는 과거 GPU4 배치, 성능·비용 측정과 기기 시험 이력이 있다. 이번 체크아웃의 Git은 fresh history로 시작하므로 기록에 등장하는 이전 plan 커밋들이 모두 현재 Git에 존재한다고 가정할 수 없다. 과거 처리량·비용 수치는 이번 분석에서 재측정하지 않았다.

검증 결과는 아래에 기록한다. 오프라인 테스트 통과는 실제 음성 인식 정확도, 검색 품질, GPU 처리량이나 APK 실행을 보장하지 않는다.

Connections

• LLM Live 문서 허브 — 기존 온디바이스·클라우드 설계와 관련 문서
• 기존 Gemini PoC Broker — 다른 저장소 구현과 비교
• 향후 릴리즈 구조 — 기존 제품 릴리즈 목표와 책임
• SK-Intellix 문서 홈 — 전체 기술 문서 진입점