ADK-Rust

실시간 제공자

ADK-Rust는 동일한 RealtimeModel 인터페이스 뒤에서 두 가지 실시간 백엔드를 지원하므로, 애플리케이션은 두 백엔드를 모두 제공하고 세션별로 전환할 수 있습니다. 이 페이지에서는 모델, 음성, 엔드포인트, 인증 및 선택 방법을 다룹니다.

OpenAI 실시간(GA)

use adk_realtime::openai::OpenAIRealtimeModel;
use adk_realtime::model::BoxedModel;
use std::sync::Arc;

let model: BoxedModel = Arc::new(OpenAIRealtimeModel::new(
    std::env::var("OPENAI_API_KEY")?,
    "gpt-realtime-2.1",
));
모델용도
gpt-realtime-2.1현재 프로덕션 음성 간 모델이자 기본 선택 항목입니다.
gpt-realtime-translate전용 번역 인터프리터(다른 엔드포인트를 사용합니다. 실시간 번역 예제 참조).
  • 전송: WebSocket (openai 기능) 또는 WebRTC (openai-webrtc, cmake 필요).
  • 오디오: 24 kHz PCM16 입출력.
  • 음성: marin (자연스러운 GA 음성), alloy 및 기타 음성. RealtimeConfig::with_voice("marin")로 설정합니다.
  • 인증: OPENAI_API_KEY. 키는 서버에 저장됩니다(브라우저에는 절대 저장하지 않음).

Gemini Live

use adk_realtime::gemini::{GeminiLiveBackend, GeminiRealtimeModel};

let model: BoxedModel = Arc::new(GeminiRealtimeModel::new(
    GeminiLiveBackend::studio(std::env::var("GEMINI_API_KEY")?),
    "models/gemini-3.1-flash-live-preview",
));
모델용도
models/gemini-3.1-flash-live-preview하프 캐스케이드 라이브 모델. 도구를 안정적으로 호출하며 비디오 프레임을 지원합니다. 기본 선택입니다.
models/gemini-live-2.5-flash-native-audio네이티브 오디오 모델 — 가장 자연스러운 음성을 제공하며 감정적 대화를 지원하는 모델입니다. 도구 호출 성능은 더 약합니다.
models/gemini-3.5-live-translate-preview전용 번역 모델(번역 예제 참조).
  • 전송: WebSocket (gemini 기능, AI Studio) 또는 Vertex AI Live (vertex-live, OAuth2 / ADC — 실시간 에이전트 참조).
  • 오디오: 16 kHz PCM16 입력, 24 kHz PCM16 출력.
  • 음성: Kore 및 기타 음성, with_voice("Kore").
  • 인증: GEMINI_API_KEY (또는 GOOGLE_API_KEY).

모델 이름은 엔드포인트에 따라 다릅니다. AI Studio (API-key)는 models/gemini-3.1-flash-live-preview과 같은 이름을 사용하며, Vertex/Agent Platform은 다른 이름을 사용합니다. crate의 GeminiLiveBackend::studio(...)는 v1alpha 엔드포인트를 통해 AI Studio를 대상으로 합니다 (감정 대화에도 사용되는 엔드포인트입니다).

모델 선택

  • 일반적인 음성 + 도구 → gpt-realtime-2.1 또는 gemini-3.1-flash-live-preview. 두 모델 모두 도구를 안정적으로 호출합니다. 연속 동영상에는 Gemini가 더 적합합니다.
  • 가장 자연스러운 음성 / 감정 인식 → Gemini 네이티브 오디오 (gemini-live-2.5-flash-native-audio)와 감정 대화 — 도구 호출 안정성은 어느 정도 낮아질 수 있습니다.
  • 추론 중심 → gpt-realtime-2.1.
  • 번역 → 전용 번역 모델(각자의 프로토콜 사용).

세션별 제공자 선택

애플리케이션은 일반적으로 요청에서 제공자를 읽고 이에 맞는 모델을 구성합니다. 오디오 샘플링 레이트가 다르므로 다음 값도 노출해야 합니다.

#[derive(Clone, Copy)]
enum Provider { OpenAI, Gemini }

impl Provider {
    fn audio_rates(self) -> (u32, u32) {   // (input, output)
        match self {
            Provider::OpenAI => (24_000, 24_000),
            Provider::Gemini => (16_000, 24_000),
        }
    }
}

fn build_model(p: Provider) -> anyhow::Result<(BoxedModel, &'static str)> {
    Ok(match p {
        Provider::OpenAI => (
            Arc::new(OpenAIRealtimeModel::new(std::env::var("OPENAI_API_KEY")?, "gpt-realtime-2.1")),
            "marin",
        ),
        Provider::Gemini => (
            Arc::new(GeminiRealtimeModel::new(
                GeminiLiveBackend::studio(std::env::var("GEMINI_API_KEY")?),
                "models/gemini-3.1-flash-live-preview",
            )),
            "Kore",
        ),
    })
}

예제에서는 환경 변수(OPENAI_REALTIME_MODEL, GEMINI_REALTIME_MODEL)를 사용해 이 모든 값을 재정의할 수 있으므로, 다시 컴파일하지 않고도 모델을 고정할 수 있습니다.

기능 매트릭스

OpenAI gpt-realtime-2.1Gemini 3.1-flash-liveGemini 네이티브 오디오
음성 (오디오 입력/출력)✅✅✅
실시간 전사✅✅✅
서버 측 도구✅ (신뢰할 수 있음)✅ (신뢰할 수 있음)⚠️ (더 약함)
비디오 프레임✅ (이미지 항목)✅ (연속적)✅ (연속적)
정서적 대화❌❌✅

다음: 도구 →

진단 및 페이로드 개인정보 보호

실시간 프레임에는 전사 내용, 도구 인수, 도구 결과 및 식별자가 포함됩니다. 인식된 이벤트를 역직렬화하지 못하면 — 제공업체 스키마 변경 — 경고에는 필드 안전 요약이 보고되며 프레임은 공개되지 않습니다:

필드내용
event_type실패한 공급자 이벤트 유형
error역직렬화 오류
payload.bytes바이트 단위의 프레임 크기
payload.digest동일한 드리프트의 반복을 연관 짓기 위한 짧은 다이제스트
payload.raw페이로드 기록이 컴파일에 포함되지 않는 한 <redacted>

참고: digest는 실행 내의 로그 행을 그룹화합니다. 이는 암호화 digest가 아니며 프로세스 간에 안정적이지 않습니다.

프레임을 확보한 상태에서 드리프트를 진단하려면 record-payloads 기능과 함께 adk-realtime을 컴파일하십시오. 이 기능은 처음 300바이트를 기록합니다:

[dependencies]
adk-realtime = { version = "2.1.0", features = ["openai", "record-payloads"] }

이 기능은 기본적으로 비활성화되어 있으며 빌드별로 의도적으로 선택됩니다. 스키마 드리프트가 발생하는 시점이 바로 운영자가 로그 수집 및 보존 기간을 확대하는 때이기 때문입니다.

실시간 제공자 - ADK-Rust 문서 | ADK-Rust