OpenAI Realtime

OpenAI Realtime

OpenAIRealtimeModel은 에이전트를 OpenAI의 네이티브 음성-대-음성 모델에 연결해요. realtime 퀵스타트나 텍스트-음성 예제로 시작하세요.

출처: 문서

본문

설정

OpenAI realtime 모델을 쓰려면 pydantic-ai-slim을 openai-realtime 옵션 그룹과 함께 설치하세요. openai 패키지를 realtime WebSocket 전송과 함께 묶어요:

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

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

OpenAI 모델 문서에서 설명한 대로 OPENAI_API_KEY를 설정하세요. 인증과 base URL은 provider에서 와요. OpenAIChatModel을 거울처럼 반영해요. 기본 provider='openai'는 환경을 읽고, 커스텀 키나 base URL에는 OpenAIProvider를 전달하세요. realtime WebSocket은 별도로 열리므로 커스텀 프로바이더 httpx 클라이언트는 그것에 사용되지 않아요. 세션은 기본으로 서버 측 WebSocket 위에서 실행돼요. 브라우저 음성을 위해 브라우저가 WebRTC로 미디어를 직접 교환하고 백엔드가 에이전트를 실행할 수 있어요(프론트엔드 연결 참고).

모델 이름

OpenAIRealtimeModel로 프로바이더의 realtime 모델 ID를 사용하세요. 예: gpt-realtime, gpt-realtime-2.1, gpt-realtime-2.1-mini. 모델 가용성과 별칭은 바뀔 수 있어요. 표준 모델 목록은 공식 OpenAI 모델 문서를 사용하세요.

설정

OpenAIRealtimeModelSettings — 모델 실행 설정의 realtime 대응물 — 은 공유 설정을 음성, 노이즈 감소, 출력 속도, 정확한 턴 감지, 자르기로 확장해요:

from pydantic_ai.realtime.openai import (
    OpenAIRealtimeModel,
    OpenAIRealtimeModelSettings,
)

settings = OpenAIRealtimeModelSettings(
    max_tokens=2_000,
    openai_voice='alloy',
    turn_detection={'sensitivity': 'high', 'silence_duration_ms': 400},
    openai_input_noise_reduction='near_field',
    openai_output_speed=1.1,
    openai_turn_detection={'type': 'semantic_vad', 'eagerness': 'high'},
    openai_truncation={'type': 'retention_ratio', 'retention_ratio': 0.8},
)
model = OpenAIRealtimeModel('gpt-realtime', settings=settings)

openai_turn_detection은 ServerVAD나 SemanticVAD를 받아들이고 공유 turn_detection을 덮어써요. openai_truncation은 또한 'auto'나 'disabled'를 받아요. 보존 비율은 세션이 자라며 안정적이고 캐시 가능한 프리픽스를 보존해요. openai_voice는 프로바이더 음성을 선택해요. OpenAI realtime은 Pydantic AI를 통해 temperature를 노출하지 않아요.

입력 전사는 기본 'auto'예요. 지원되는 전사 모델 ID를 설정해 고정하거나 None으로 비활성화하세요. 입력 전사 참고.

Reasoning

공유 thinking 설정(Thinking 참고)은 supports_thinking을 보고하는 프로필을 가진 모델(gpt-realtime-2 계열 포함)에 적용돼요. True는 프로바이더 기본을 사용하고, effort 문자열이 레벨을 선택해요. False는 reasoning을 생략해요. OpenAI realtime이 비활성화 effort를 받아들이지 않기 때문이에요. GA gpt-realtime은 설정을 무시해요.

Reasoning 추적은 ThinkingPart로 드러나지 않아요. API가 effort를 입력 전용으로 노출하기 때문이에요.

브라우저 WebRTC

브라우저 음성 에이전트를 위해 OpenAI는 WebRTC를 권장해요. 오디오가 브라우저 ↔ OpenAI 사이를 직접 흐르고, 백엔드는 에이전트를 실행하기 위해 제어 평면 사이드밴드를 붙여요. AgentRealtime은 두 시그널링 헬퍼를 노출하는데, 둘 다 에이전트의 세션 구성(인스트럭션, 툴, 음성, VAD)을 서버 측에서 해결하고 바인딩해요:

• answer_webrtc_offer — 보안 경로: 브라우저의 SDP offer를 POST /v1/realtime/calls로 릴레이하고 SDP answer와 agent.realtime(model).session(provider_session=...)으로 사이드밴드를 붙일 WebRTCSession을 반환해요. 브라우저는 토큰을 절대 보지 못해요.
• create_client_secret — SDP를 백엔드로 릴레이하지 않을 때, WebRTC 호출을 스스로 협상하는 브라우저를 위해 단기 RealtimeClientSecret(임시 토큰)을 발급해요.

토폴로지, 보안 offer 릴레이 흐름, 사이드밴드 신뢰 모델은 프론트엔드 연결을, 실행 가능한 FastAPI와 브라우저 앱은 realtime WebRTC 예제를 참고하세요.

기능 지원과 한계

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

게이트웨이

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

from pydantic_ai import Agent

agent = Agent(instructions='You are a helpful voice assistant.')
realtime = agent.realtime('gateway/openai:gpt-realtime')

자격증명은 gateway_provider에서 와요. realtime 프로토콜을 노출하는 OpenAI 호환 엔드포인트도 OpenAIProvider를 통해 공급할 수 있어요. Gateway 추적 전파 참고.

프로바이더별 특이점

• 프로바이더 연결에는 재개 가능한 서버 핸들이 없어요. 자동 재연결은 로컬 메시지 재생으로 완성된 이력을 새 세션에 복원해요.

더 알아보기 (Learn more)

• Pydantic AI Realtime 개요
• OpenAI 모델 문서