목차
- Gemini 3.8 Live 사용법 전에 짚을 GA 출시와 모델 구성
- gemini-3.8-live 마이그레이션 트러블슈팅
- Gemini 3.8 Live 세션 연결: Python·JavaScript SDK
- 입력·출력 포맷과 세션 시간 한도
- Gemini Live VAD 설정과 발화 감지 문제
- Gemini Live 함수 호출과 스케줄링 모드
- 자주 묻는 질문
- 조건별 모델과 설정 선택 기준
Gemini 3.8 Live 사용법에서 가장 흔한 오해는 기존 코드의 모델 문자열만 gemini-3.8-live로 바꾸면 이전과 같이 동작한다는 것이다. 실제로 gemini-3.1-flash-live-preview에서 넘어올 때는 thinking_level 제거, proactive_audio 영구 활성화, affective_dialog 제거, 비동기 함수 호출의 NON_BLOCKING 기본 전환까지 네 가지를 반영해야 한다. 하나라도 빠뜨리면 세션 설정 단계에서 에러가 난다. 에러 없이 응답 방식만 달라지는 경우도 있다.
이 글은 2026-09-26 기준 공식 문서를 근거로 한다. Gemini 3.8 Live 모델 사양 문서에 마이그레이션 요구 사항과 토큰 한도가 정리되어 있다. 본문은 운영·유지보수 관점에서 증상, 발생 조건, 원인, 해결, 재발 방지 순서로 구성했다.
Gemini 3.8 Live 사용법 전에 짚을 GA 출시와 모델 구성
Gemini API 변경 로그에 따르면 2026년 9월 15일에 두 개의 오디오-투-오디오 모델이 GA로 출시되었다. 하나는 gemini-3.8-live, 다른 하나는 gemini-3.8-live-extended-thinking이다. 이전 세대의 gemini-3.1-flash-live-preview는 이름대로 preview 단계였다. 운영 환경에서 GA 모델로 전환할 근거가 생긴 셈이다.
두 모델은 용도가 다르다. gemini-3.8-live는 저지연 음성 에이전트용이다. Extended Thinking 모델은 실시간 음성 대화 중에 복잡한 다단계 문제를 풀기 위한 백그라운드 추론용으로 분류된다.
| 항목 | gemini-3.8-live | gemini-3.8-live-extended-thinking |
|---|---|---|
| 출시 상태 | GA (2026-09-15) | GA (2026-09-15) |
| 모델 유형 | 오디오-투-오디오 | 오디오-투-오디오 |
| 설계 목적 | 저지연 음성 에이전트 | 대화 중 다단계 문제 해결을 위한 백그라운드 추론 |
| 이전 모델 | gemini-3.1-flash-live-preview | 공식 문서에 대응 관계 명시 없음 |
토큰 한도는 gemini-3.8-live 기준 입력 131,072, 출력 65,536이다. 입력 한도 131,072는 128×1024와 같다. 네이티브 오디오 모델의 컨텍스트 윈도우를 128k 토큰으로 적은 capabilities 문서와 같은 값을 다른 단위로 표기한 것으로 보인다.
2026-09-26 기준 공식 모델 문서에는 Gemini 3.8 Live의 가격 정보가 포함되어 있지 않다. 비용 산정이 필요한 경우 Google AI Studio 또는 청구 콘솔에 표시되는 값을 직접 확인해야 한다. 이 글에서도 가격 수치는 다루지 않는다.
gemini-3.1-flash-live-preview 기반 코드를 그대로 두고 모델 문자열만 교체하면 아래 증상이 순서 없이 나타난다. 증상마다 발생 조건과 원인이 다르므로 하나씩 분리해서 점검하는 편이 빠르다.
증상 1: thinking_level이 포함된 설정에서 세션 생성 실패
발생 조건은 세션 config에 thinking_level 키가 남아 있는 경우다. 3.1 preview에서 추론 강도를 조절하던 코드가 흔히 이 키를 갖고 있다. 공식 문서는 3.8 Live로 마이그레이션할 때 이 파라미터를 제거해야 한다고 명시한다.
해결 방법은 config 딕셔너리나 객체에서 해당 키를 삭제하는 것이다. 추론 깊이가 필요한 요구 사항이 있었다면 thinking_level 값을 조정하는 방식으로 옮기는 대신 gemini-3.8-live-extended-thinking 모델을 검토하는 편이 설계 의도에 가깝다.
증상 2: proactive_audio를 false로 설정하면 에러
3.8 Live에서는 proactive_audio가 영구 활성화 상태다. 따라서 이 값을 false로 명시하면 에러가 반환된다. 3.1 preview 시절 모델이 먼저 말을 거는 동작을 막으려고 false를 넣어 둔 코드가 이 조건에 해당한다.
에러 메시지의 정확한 문구는 공식 모델 문서에 실려 있지 않다. 그러니 로그에서 문자열 매칭으로 잡기보다 config 자체를 점검하는 쪽이 확실하다. 해결은 proactive_audio 키를 지우거나 false가 아닌 상태로 두는 것이다. 먼저 발화하는 동작을 끌 수 없으니 이 제약을 전제로 대화 흐름을 설계해야 한다.
증상 3: affective_dialog 설정 관련 에러 또는 무시
affective_dialog 설정은 3.8 Live에서 제거되었다. 이 키가 config에 남아 있으면 마이그레이션 요구 사항을 충족하지 못한다. 감정 톤에 맞춰 응답하도록 설정했던 서비스라면 해당 기능이 모델 설정 수준에서 더 이상 제공되지 않는다는 점을 기획 쪽과 공유해 둘 필요가 있다.
증상 4: 함수 호출 중에도 모델이 계속 말한다
에러는 없는데 동작이 달라지는 대표 사례다. 3.8 Live에서는 비동기 함수 호출, 즉 NON_BLOCKING이 기본값으로 바뀌었다. 도구 실행 결과를 기다리는 동안 대화가 멈추는 흐름을 전제로 만든 클라이언트는 이 변경 때문에 예상과 다른 타이밍에 음성 응답을 받게 된다.
원인이 코드 버그가 아니라 기본값 변경이므로 로그만으로는 찾기 어렵다. 해결 방향은 둘 중 하나다. 비동기 호출을 전제로 결과 반영 시점을 스케줄링 모드로 제어하거나, 도구 호출 구간의 UX를 다시 설계하는 것이다. 스케줄링 모드는 아래 함수 호출 섹션에서 따로 다룬다.
마이그레이션 체크리스트
| 점검 항목 | 3.1 preview 코드에서 흔한 형태 | 3.8 Live 조치 |
|---|---|---|
| 모델 문자열 | gemini-3.1-flash-live-preview | gemini-3.8-live로 교체 |
thinking_level | config에 포함 | 키 제거 |
proactive_audio | false로 비활성화 | false 설정 금지 (영구 활성화) |
affective_dialog | config에 포함 | 설정 제거 |
| 함수 호출 방식 | 동기 대기 전제 | NON_BLOCKING 기본값 전제로 재검토 |
config를 환경 변수나 원격 설정 저장소에서 주입하는 구조라면 코드 저장소만 수정하고 원격 값에 `proactive_audio: false`가 남는 경우가 있다. 이렇게 되면 배포 직후 세션 생성이 실패한다. 배포 전에 실제 주입되는 최종 config를 로그로 한 번 출력해 네 개 키를 대조해야 한다.
Live API SDK 시작 가이드는 Python과 JavaScript 두 가지 연결 방식을 제시한다. Python은 google-genai SDK의 client.aio.live.connect()로 세션을 만들고 send_realtime_input()으로 오디오나 텍스트를 보내는 구조다. JavaScript는 @google/genai SDK의 ai.live.connect()에 콜백을 등록해 WebSocket 세션을 관리한다.
Python 연결 예제
공식 스니펫을 그대로 두고 실행 진입점만 덧붙인 형태다. 비동기 컨텍스트 매니저를 쓰므로 표준 라이브러리의 asyncio.run()으로 감쌌다.
import asyncio
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
async def main():
async with client.aio.live.connect(
model="gemini-3.8-live",
config={"response_modalities": ["AUDIO"]}
) as session:
await session.send_realtime_input(text="Hello")
asyncio.run(main())이 코드는 세션을 열고 텍스트 하나를 보내는 데서 끝난다. 응답 스트림을 받는 부분은 이 스니펫에 없으므로 수신 처리 방식은 공식 가이드의 해당 섹션을 따라야 한다. async with 블록을 벗어나면 세션이 닫힌다. 장시간 대화를 유지하려면 블록 안에서 입력 루프를 돌리는 구조가 필요하다.
JavaScript 연결 예제
JavaScript 스니펫은 onopen, onmessage, onerror, onclose 네 콜백을 식별자로만 넘긴다. 실행 가능한 형태로 만들려면 네 함수를 먼저 정의해야 한다. 아래는 로그 출력용 최소 구현을 덧붙인 예시다.
import { GoogleGenAI, Modality } from '@google/genai';
function onopen() { console.log('session opened'); }
function onmessage(message) { console.log('message', message); }
function onerror(error) { console.error('session error', error); }
function onclose(event) { console.log('session closed', event); }
const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY"});
const session = await ai.live.connect({
model: 'gemini-3.8-live',
config: { responseModalities: [Modality.AUDIO] },
callbacks: { onopen, onmessage, onerror, onclose }
});Python은 response_modalities, JavaScript는 responseModalities로 키 표기가 다르다. 두 언어를 함께 쓰는 팀에서 설정 값을 공유 JSON으로 관리하면 키 이름이 섞이는 일이 생긴다. 언어별 변환 계층을 따로 두는 편이 안전하다.
운영 중 확인할 연결 지표
onerror와 onclose는 장애 분석의 출발점이다. 두 콜백에서 세션 식별자, 연결 시각, 종료 시각을 함께 남기면 세션이 어떤 이유로 끊겼는지 추적하기 쉬워진다. AWS 위에서 운영한다면 이 로그를 CloudWatch Logs 같은 중앙 로그 저장소로 보내고 비정상 종료 비율을 지표로 만들어 두는 방식이 일반적이다.
예제의 `YOUR_API_KEY`를 코드에 직접 넣으면 저장소 유출 시 키가 그대로 노출된다. 서버 측에서는 AWS Secrets Manager 같은 비밀 저장소에서 런타임에 읽어 오고, 브라우저 코드에는 장기 키를 두지 않는 구성이 기본이다.
Live API 기능 문서에 정리된 입출력 사양은 다음과 같다. 포맷 불일치는 에러 없이 음질 저하나 인식 실패로만 나타나는 경우가 많아 초기 점검 대상 1순위다.
| 구분 | 형식 | 제약 |
|---|---|---|
| 오디오 입력 | raw PCM 16bit | 16kHz |
| 텍스트 입력 | 텍스트 | — |
| 비디오 입력 | JPEG/PNG 프레임 | 최대 1fps |
| 오디오 출력 | 오디오 | 24kHz |
| 텍스트 출력 | 텍스트 트랜스크립션 | — |
| 오디오 전용 세션 | — | 최대 15분 |
| 오디오+비디오 세션 | — | 최대 2분 |
증상: 출력 음성이 느리거나 높게 재생된다
입력이 16kHz이고 출력이 24kHz라는 비대칭이 원인이다. 재생 측에서 입력과 같은 16kHz로 버퍼를 해석하면 음성이 느리고 낮게 들린다. 해결은 재생 파이프라인의 샘플레이트를 24kHz로 따로 지정하는 것이다. 입력 캡처와 출력 재생 설정을 한 상수로 공유하는 코드에서 자주 생기는 문제다.
증상: 비디오를 붙이면 세션이 2분 전후로 끊긴다
오디오 전용 세션은 최대 15분이지만 비디오 프레임을 함께 보내면 한도가 2분으로 줄어든다. 음성 상담에 화면 공유를 추가한 직후 세션 종료가 급증했다면 이 조건을 먼저 의심해야 한다. 비디오가 꼭 필요한 구간에서만 프레임을 보내고 나머지는 오디오 전용으로 운영하는 방식이 현실적인 대응이다.
프레임을 1fps보다 빠르게 보내는 경우도 점검 대상이다. 문서상 최대치가 1fps이므로 카메라 캡처 주기를 그 이하로 제한해야 한다.
15분·2분 한도에 도달한 뒤 대화를 이어 가는 재연결 패턴은 공식 문서에 프로덕션 수준 예제가 부족하다. 현재로서는 애플리케이션 계층에서 종료 시점을 감지하고 새 세션을 여는 방식으로 설계해야 한다. 이 경우 이전 대화 맥락을 어떻게 넘길지는 서비스 요구 사항에 따라 직접 정해야 한다.
VAD(Voice Activity Detection)는 사용자가 말을 시작하고 끝낸 시점을 판단하는 기능이다. 응답이 너무 빨리 끼어들거나 반대로 한참 뒤에 나오는 증상은 대부분 여기서 원인을 찾을 수 있다. 3.8 Live에서는 자동 감지, Hybrid VAD, Manual VAD 세 방식을 선택하게 된다.
자동 감지 설정값
공식 capabilities 문서의 설정 스니펫을 하나의 config로 합치면 다음과 같다. 각 키와 값은 문서 스니펫 그대로다.
config = {
"response_modalities": ["AUDIO"],
"speech_config": {
"voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
},
"realtime_input_config": {
"automatic_activity_detection": {
"disabled": False,
"start_of_speech_sensitivity": "LOW",
"end_of_speech_sensitivity": "LOW",
"prefix_padding_ms": 20,
"silence_duration_ms": 100
}
}
}disabled: False는 서버 측 자동 감지를 켠다는 뜻이다. start_of_speech_sensitivity와 end_of_speech_sensitivity는 발화 시작·종료를 판정하는 민감도를 조절한다. prefix_padding_ms는 발화 시작 판정 앞쪽에 포함할 오디오 길이, silence_duration_ms는 발화 종료로 볼 침묵 길이에 해당한다.
증상과 설정의 대응 관계는 다음과 같이 정리된다. 사용자가 문장 중간에 잠깐 멈췄을 때 모델이 끼어든다면 silence_duration_ms가 짧은 경우가 많다. 주변 소음에 반응해 발화가 시작된 것으로 처리된다면 시작 민감도 조정이 우선이다.
Hybrid VAD와 Manual VAD
Hybrid VAD는 클라이언트 측 감지와 서버 폴백을 결합한 방식이다. 클라이언트가 스트림 종료를 판단하면 audio_stream_end 신호를 보낸다. 클라이언트 판단이 실패해도 서버 감지가 받쳐 주는 구조다.
Manual VAD는 클라이언트가 activityStart와 activityEnd 메시지로 발화 구간을 직접 지정한다. 푸시투토크 버튼처럼 발화 구간이 명확한 UI에 맞는다. 다만 최소 500ms의 침묵 임계값이 필요하다는 제약이 있어, 이보다 짧은 간격으로 구간을 끊으면 의도대로 동작하지 않을 수 있다.
flowchart TD
A[발화 구간을 UI에서 명확히 알 수 있나] -->|예: 푸시투토크| B[Manual VAD<br/>activityStart / activityEnd]
A -->|아니오| C{클라이언트에 자체 감지 로직이 있나}
C -->|예| D[Hybrid VAD<br/>audio_stream_end + 서버 폴백]
C -->|아니오| E[자동 감지<br/>automatic_activity_detection]| 방식 | 판단 주체 | 사용 신호 | 적합한 환경 |
|---|---|---|---|
| 자동 감지 | 서버 | automatic_activity_detection 설정 | 일반 음성 대화, 별도 감지 로직 없음 |
| Hybrid VAD | 클라이언트 + 서버 폴백 | audio_stream_end | 클라이언트 감지가 있지만 실패 대비가 필요한 경우 |
| Manual VAD | 클라이언트 | activityStart / activityEnd | 푸시투토크, 발화 구간이 명확한 UI |
VAD 변경 후 모니터링 항목
VAD 값을 바꾼 뒤에는 사용자 발화 중 모델이 끼어든 비율과 발화 종료 후 첫 응답까지의 지연을 함께 봐야 한다. 두 지표는 서로 반대 방향으로 움직이는 편이다. 침묵 판정을 길게 잡으면 끼어들기는 줄지만 응답이 늦어진다. 한 번에 한 파라미터만 바꾸고 지표 변화를 비교해야 원인을 분리할 수 있다.
Gemini Live 함수 호출과 스케줄링 모드
마이그레이션 섹션에서 다룬 대로 3.8 Live는 함수 호출이 NON_BLOCKING으로 기본 동작한다. 도구가 실행되는 동안에도 대화는 이어진다. 그러다 결과가 돌아왔을 때 그 결과를 언제 대화에 반영할지가 새로운 설계 문제로 떠오른다.
3.8 Live는 비동기 함수 호출 시 SILENT, WHEN_IDLE, INTERRUPTED 세 스케줄링 모드를 지원한다. 모드별 세부 동작 정의와 설정 위치는 capabilities 문서를 기준으로 확인해야 한다. 이름으로 보면 SILENT는 결과를 조용히 반영하는 쪽, WHEN_IDLE은 대화가 비는 시점을 기다리는 쪽, INTERRUPTED는 진행 중인 발화를 끊는 쪽에 대응한다.
운영 관점에서 선택 기준은 도구 결과의 긴급도다. 사용자가 방금 물은 질문의 답이라면 기다리게 할 이유가 적다. 반면 백그라운드에서 갱신되는 참고 정보라면 현재 발화를 끊지 않는 모드가 사용자 경험을 덜 해친다. 모드의 정확한 의미가 서비스 요구와 맞는지는 스테이징 환경에서 실제 음성 흐름으로 검증하는 과정이 필요하다.
결제 확인처럼 도구 결과가 나오기 전에 모델이 확정 발언을 하면 안 되는 흐름이 있다. `NON_BLOCKING` 기본값을 전제로 하지 않은 코드에서는 결과가 도착하기 전에 모델이 추측성 응답을 내보낼 위험이 있다. 이런 도구는 호출 전후의 발화 내용을 로그로 남겨 검증하고, 확정 전 안내 문구를 시스템 지시에 명시해야 한다.
- GPT-5 API 사용법 완전 가이드 — Responses API 전환·파라미터 튜닝 7단계 – OpenAI GPT-5는 Responses API를 기본으로 권장하며, verbosity·reasoning_effort 파라미터와 free…
자주 묻는 질문
Gemini 3.8 Live와 Extended Thinking 모델의 차이는 무엇인가?
둘 다 2026년 9월 15일 GA로 출시된 오디오-투-오디오 모델이다. gemini-3.8-live는 저지연 음성 에이전트용이고, gemini-3.8-live-extended-thinking은 실시간 대화 중 다단계 문제 해결을 위한 백그라운드 추론용이다. 지연 시간이 우선이면 전자, 추론 깊이가 우선이면 후자가 맞다.
입력 토큰 131,072와 컨텍스트 128k는 다른 값인가?
131,072는 128×1024이므로 같은 크기를 다른 단위로 표기한 것으로 보인다. 모델 문서는 입력 131,072, 출력 65,536 토큰을 명시하고, capabilities 문서는 네이티브 오디오 모델의 컨텍스트 윈도우를 128k로 적고 있다.
가격은 어디서 확인하나?
2026-09-26 기준 공식 모델 문서에 Gemini 3.8 Live 가격 정보가 없다. 요금 페이지나 청구 콘솔의 실제 표시값을 기준으로 삼아야 한다.
한국어 공식 가이드가 있나?
현재 공식 Live API 문서는 전부 영문이다. 설정 키와 모드 이름은 영문 문서 표기 그대로 쓰는 편이 검색과 대조에 유리하다.
조건별 모델과 설정 선택 기준
마이그레이션 우선순위
gemini-3.1-flash-live-preview에서 이전하는 경우는 모델 문자열 교체보다 config 정리가 먼저다. thinking_level과 affective_dialog를 지우고, proactive_audio: false가 어디에도 남지 않았는지 원격 설정까지 확인한 뒤 배포해야 한다. 추론 강도 조절이 필요했던 서비스라면 파라미터 대신 Extended Thinking 모델로 옮기는 것이 맞는 선택이다.
세션·VAD·함수 호출 선택 기준
세션 길이가 길어지는 음성 상담은 오디오 전용 15분 한도를 기준으로 설계한다. 비디오를 섞는 서비스는 2분 한도를 전제로 필요한 구간에서만 프레임을 보낸다. 발화 구간이 명확한 UI는 Manual VAD, 클라이언트 감지 로직이 있는 앱은 Hybrid VAD, 그 외에는 자동 감지로 시작해 silence_duration_ms부터 조정하는 순서가 무난하다. 도구 호출이 많은 음성 에이전트는 NON_BLOCKING 기본값을 받아들이고, 결과의 긴급도에 따라 스케줄링 모드를 나누는 것이 기준이 된다.
이후 검토할 영역은 세 가지다. 첫째는 Gemini 음성 에이전트 개발에서 세션 한도 도달 후 맥락을 넘기는 재연결 설계다. 둘째는 Google GenAI SDK Live API의 응답 수신 스트림 처리다. 셋째는 Gemini Live 함수 호출 결과를 서버 로그와 대조해 검증하는 모니터링 구성으로, 운영 단계에서 장애 분석 시간을 줄이는 데 직접 영향을 준다.