Google Gemini Live

Google Gemini Live

GoogleRealtimeModel은 에이전트를 Gemini Live에 연결해요. 네이티브 오디오, 라이브 이미지, 프로바이더 네이티브 툴을 포함해서요. realtime 퀵스타트나 카메라 예제로 시작하세요.

출처: 문서

본문

설정

Gemini Live 모델을 쓰려면 pydantic-ai-slim을 google-realtime 옵션 그룹과 함께 설치하세요. google-genai SDK를 realtime 전송 의존성과 함께 묶어요:

pip install "pydantic-ai-slim[google-realtime]"

uv add "pydantic-ai-slim[google-realtime]"

인증은 provider에서 와요. GoogleModel을 거울처럼 반영해요. Gemini Developer API에는 provider='google', Vertex AI/ADC에는 provider='google-cloud'를 사용하세요. API 키와 자격증명은 Google 모델 문서에서 설명한 대로 구성해요. 커스텀 자격증명, 프로젝트, 리전, 클라이언트에는 GoogleProvider나 GoogleCloudProvider를 전달하세요.

모델 이름

Gemini Live 모델 ID를 사용하세요. 예: gemini-2.5-flash-native-audio-latest 또는 gemini-3.1-flash-live-preview. 네이티브 오디오와 다른 Live 모델은 thinking, 비동기 툴, 출력 동작이 달라요. 표준 모델과 가용성 출처는 공식 Gemini Live 문서를 사용하세요.

Vertex AI와 Pydantic AI Gateway는 Gemini Developer API와 다른 모델 ID와 위치를 사용해요:

Developer API ID는 Vertex AI에서 사용할 수 없어요. GoogleCloudProvider나 gateway에서 일치하는 Vertex 위치를 구성하세요. 아래 gateway 예제는 gemini-live-2.5-flash를 쓰므로 global이 필요해요.

설정

GoogleRealtimeModelSettings — 모델 실행 설정의 realtime 대응물 — 은 공유 설정을 Google 생성 및 Live 제어로 확장해요:

from pydantic_ai.realtime.google import GoogleRealtimeModel, GoogleRealtimeModelSettings

settings = GoogleRealtimeModelSettings(
    temperature=0.7,
    top_p=0.9,
    google_voice='Puck',
    google_language_code='en-US',
    google_affective_dialog=True,
    google_proactive_audio=True,
    google_vad={'start_sensitivity': 'high', 'end_sensitivity': 'low'},
    google_turn_coverage='all_video',
    google_context_compression={'trigger_tokens': 16000, 'target_tokens': 8000},
)
model = GoogleRealtimeModel('gemini-2.5-flash-native-audio-latest', settings=settings)

google_voice는 프로바이더 음성 설정이에요. 토큰 예산이나 다른 Gemini 특화 제어가 필요할 때 google_thinking_config가 공유 thinking 설정보다 우선해요.

자동 VAD를 켜 두세요

Pydantic AI는 Gemini 활동 마커나 수동 턴 동사를 노출하지 않아요. google_vad={'disabled': True}를 설정하지 마세요. 공유 turn_detection=False도 같은 이유로 거부돼요.

비동기 툴 호출

Gemini는 함수 툴이 대기 중인 동안 보통 생성을 멈춰요. 지원되는 네이티브 오디오 모델에서 google_async_tool_calls=True를 설정해 계속 말하게 하세요. 느린 툴에 최적이에요. 빠른 결과는 거의 시작하지 않은 음성을 중단하고 이력에 빈 중단 턴을 남길 수 있어요. 다른 Live 모델은 설정을 무시해요.

네이티브 툴

Gemini Live는 WebSearch를 Google Search 그라운딩에 매핑해요. 그것이 지원하는 유일한 네이티브 툴이에요. 어떤 Live 모델도 네이티브 코드 실행이나 URL 컨텍스트를 실행하지 않아서, CodeExecutionTool도 WebFetch도 supported_native_tools에 광고되지 않아요. 그것들에 local= 폴백을 주면 세션이 대신 로컬 툴을 실행해요. CodeExecutionTool(local=...), 또는 WebFetch(native=False, local=True). 후자는 web-fetch 옵션 그룹(pip/uv-add "pydantic-ai-slim[google-realtime,web-fetch]")이 필요해요.

Gemini 2.5는 또한 네이티브 Google Search 그라운딩을 함수 툴과 결합할 수 없어요. 그 조합을 지원하는 모델을 쓰지 않으면 네이티브 그라운딩 또는 로컬 함수 툴 폴백 중 하나를 선택하세요.

전문 스트리밍 모델

내장 프로필은 음성-대-음성 Live 모델을 묘사해요. Gemini는 또한 같은 엔드포인트에서 다르게 동작하는 전문 스트리밍 모델을 제공해요. 예를 들어 gemini-robotics-er-2-streaming-preview는 텍스트 전용이고 오디오 출력을 거부해요. 그런 것 중 하나에 세션을 가리키면 profile=로 사실을 고치세요. 그것은 표준 모델 프로필처럼 해석돼요. 예: GoogleRealtimeModel('gemini-robotics-er-2-streaming-preview', profile={'supports_text_output': True}).

Vertex 하프 캐스케이드 모델 gemini-live-2.5-flash는 또 다른 예외예요. TEXT를 받아들이지만, 내장 음성-대-음성 프로필은 모든 Gemini ID에 대해 연결 전 output_modality='text'를 거부해요. profile={'supports_text_output': True}로 명시적으로 옵트인하세요.

기능 지원과 한계

프로바이더 무관 워크플로우는 오디오, 이미지, 전사, 턴과 중단, 툴, 연결 라이프사이클을 참고하세요.

게이트웨이

Pydantic AI Gateway를 통해 라우팅하려면 gateway/로 시작하는 모델 문자열을 사용하세요:

from pydantic_ai import Agent

agent = Agent(instructions='You are a helpful voice assistant.')
realtime = agent.realtime('gateway/google:gemini-live-2.5-flash')

gateway는 Vertex 업스트림을 통해 Gemini Live를 프록시하므로, 모델 이름에 나열된 대로 선택한 모델을 지원하는 리전을 구성하세요. gateway/google-cloud는 별칭이에요. Gateway 추적 전파 참고.

세션 재개

상태 복원 재연결을 위해 reconnect 설정을 ReconnectPolicy로 설정하세요. 세션 재개가 그것과 함께 자동으로 활성화돼요(google_enable_session_resumption은 정책 없이도 핸들을 요청할 수 있고, 정책 옆에 명시적으로 False로 설정하면 대화를 조용히 잃는 대신 UserError가 발생해요). 재연결은 최신 인메모리 서버 핸들을 사용하고 state_restored=True를 방출해요.

연결 상한이 턴을 잠깐 중단할 수 있다

Gemini는 프로바이더 정의 연결 상한 직전에 GoAway를 보내요. Pydantic AI는 GoAway에 선제적으로 재연결하는 대신 드롭 후 재연결하므로, 긴 호출은 턴 중간에 잠깐 끊길 수 있어요. #6643에 추적돼요.

프로바이더별 특이점

• 응답이 진행 중일 때 보낸 텍스트 턴은 Gemini 2.5에서 순서대로 답해요. Gemini 3.1에서는 활성 응답을 중단하고, RealtimeResponseInterruptedEvent를 방출하며, 텍스트 턴에 답하기 전에 부분 응답을 중단된 것으로 기록해요.
• Gemini는 응답 중단을 보고하지만 사용자 음성 시작/끝 이벤트는 보고하지 않아서, RealtimeResponseInterruptedEvent에서 로컬 재생이 플러시되고 Gemini 세션은 user speech 스팬을 기록하지 않아요(Logfire 인스트루멘테이션 참고).
• 시드된 함수 호출/결과는 Live가 시드된 턴에 함수 파트를 받아들일 수 없으므로 읽을 수 있는 텍스트로 표현돼요.
• 네이티브 전사는 일부 모델에서 완성된 문장만 만들 수 있어요. 캡션 UI는 증가 델타를 가정하지 말고 TranscriptUpdate.transcript에서 텍스트를 교체해야 해요.

더 알아보기 (Learn more)

• Pydantic AI Realtime 개요
• Gemini Live 공식 문서