Multimodal Live API

Multimodal Live API를 사용하면 텍스트, 오디오, 동영상 입력을 사용하여 오디오 및 텍스트 출력과 함께 지연 시간이 짧은 양방향 상호작용을 지원할 수 있습니다. 이렇게 하면 언제든지 모델을 중단할 수 있는 기능을 통해 사람과 같은 자연스러운 음성 대화를 할 수 있습니다. 모델의 동영상 이해 기능은 커뮤니케이션 모달을 확장하여 카메라 입력이나 스크린캐스트를 공유하고 이에 관해 질문할 수 있도록 지원합니다.

기능

Multimodal Live API에는 다음과 같은 주요 기능이 포함됩니다.

  • 멀티모달리티: 모델이 보고, 듣고, 말할 수 있습니다.
  • 지연 시간이 짧은 실시간 상호작용: 모델이 빠른 응답을 제공할 수 있습니다.
  • 세션 메모리: 모델은 단일 세션 내의 모든 상호작용에 관한 메모리를 유지하여 이전에 듣거나 본 정보를 다시 불러옵니다.
  • 함수 호출, 코드 실행, 도구로서의 검색 지원: 외부 서비스 및 데이터 소스와 모델을 통합할 수 있습니다.

멀티모달 라이브 API는 서버 간 통신을 위해 설계되었습니다.

웹 및 모바일 앱의 경우 Daily의 파트너 통합을 사용하는 것이 좋습니다.

시작하기

Multimodal Live API를 사용해 보려면 Vertex AI Studio로 이동한 다음 Multimodal Live 사용해 보기를 클릭합니다.

멀티모달 실시간 API는 WebSockets를 사용하는 상태ful API입니다.

이 섹션에서는 Python 3.9 이상을 사용하여 텍스트 간 생성에 멀티모달 실시간 API를 사용하는 방법의 예를 보여줍니다.

Python용 생성형 AI SDK

Python용 Google Gen AI SDK를 설치하거나 업데이트하는 방법을 알아보세요.
자세한 내용은 Python용 Gen AI SDK API 참고 문서 또는 python-genai GitHub 저장소를 참고하세요.
Vertex AI에서 Gen AI SDK를 사용하도록 환경 변수를 설정합니다. 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import LiveConnectConfig, HttpOptions, Modality

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-exp"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send(input=text_input, end_of_turn=True)

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?

# Yes, I'm here. What would you like to talk about?

통합 가이드

이 섹션에서는 Multimodal Live API와의 통합이 작동하는 방식을 설명합니다.

세션

WebSocket 연결은 클라이언트와 Gemini 서버 간에 세션을 설정합니다.

클라이언트가 새 연결을 시작한 후 세션은 서버와 메시지를 교환하여 다음 작업을 실행할 수 있습니다.

  • 텍스트, 오디오 또는 동영상을 Gemini 서버로 전송합니다.
  • Gemini 서버로부터 오디오, 텍스트 또는 함수 호출 요청을 수신합니다.

세션 구성은 연결 후 첫 번째 메시지로 전송됩니다. 세션 구성에는 모델, 생성 매개변수, 시스템 안내, 도구가 포함됩니다.

다음 구성 예시를 참고하세요.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

자세한 내용은 BidiGenerateContentSetup을 참고하세요.

메시지 보내기

메시지는 WebSocket 연결을 통해 교환되는 JSON 형식의 객체입니다.

메시지를 전송하려면 클라이언트가 열린 WebSocket 연결을 통해 JSON 객체를 전송해야 합니다. JSON 객체는 다음 객체 세트의 필드 중 하나만 포함해야 합니다.


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

지원되는 클라이언트 메시지

지원되는 클라이언트 메시지는 다음 표를 참고하세요.

메시지 설명
BidiGenerateContentSetup 첫 번째 메시지로 전송할 세션 구성
BidiGenerateContentClientContent 클라이언트에서 전송된 현재 대화의 점진적 콘텐츠 업데이트
BidiGenerateContentRealtimeInput 실시간 오디오 또는 동영상 입력
BidiGenerateContentToolResponse 서버에서 수신한 ToolCallMessage에 대한 응답

메시지 수신하기

Gemini에서 메시지를 수신하려면 WebSocket 'message' 이벤트를 수신 대기한 후 지원되는 서버 메시지의 정의에 따라 결과를 파싱합니다.

다음을 참조하세요.

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

서버 메시지에는 다음 객체 세트의 필드 중 하나만 포함됩니다.


{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

지원되는 서버 메시지

다음 표에서 지원되는 서버 메시지를 확인하세요.

메시지 설명
BidiGenerateContentSetupComplete 설정이 완료될 때 클라이언트에서 전송하는 BidiGenerateContentSetup 메시지
BidiGenerateContentServerContent 클라이언트 메시지에 대한 응답으로 모델에서 생성한 콘텐츠
BidiGenerateContentToolCall 클라이언트가 함수 호출을 실행하고 일치하는 ID와 함께 응답을 반환하도록 요청
BidiGenerateContentToolCallCancellation 사용자가 모델 출력을 중단하여 함수 호출이 취소되면 전송됩니다.

증분 콘텐츠 업데이트

증분 업데이트를 사용하여 텍스트 입력을 전송하거나, 세션 컨텍스트를 설정하거나, 세션 컨텍스트를 복원합니다. 짧은 컨텍스트의 경우 세부 경로 상호작용을 전송하여 정확한 이벤트 시퀀스를 나타낼 수 있습니다. 컨텍스트가 긴 경우 후속 상호작용에 사용할 수 있도록 컨텍스트 창을 확보할 수 있도록 단일 메시지 요약을 제공하는 것이 좋습니다.

다음 컨텍스트 메시지 예시를 참고하세요.

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

콘텐츠 부분은 functionResponse 유형일 수 있지만 BidiGenerateContentClientContent은 모델에서 실행된 함수 호출에 응답을 제공하는 데 사용해서는 안 됩니다. 대신 BidiGenerateContentToolResponse를 사용해야 합니다. BidiGenerateContentClientContent는 이전 맥락을 설정하거나 대화에 텍스트 입력을 제공하는 데만 사용해야 합니다.

오디오 및 동영상 스트리밍

코드 실행

코드 실행에 관해 자세히 알아보려면 코드 실행을 참고하세요.

함수 호출

모든 함수는 BidiGenerateContentSetup 메시지의 일부로 도구 정의가 전송되어 세션 시작 시 선언되어야 합니다.

JSON을 사용하여 함수를 정의합니다. 특히 OpenAPI 스키마 형식의 선택된 하위 집합을 사용합니다. 단일 함수 선언에는 다음 매개변수가 포함될 수 있습니다.

  • name (문자열): API 호출 내 함수의 고유 식별자입니다.

  • description (문자열): 함수의 목적과 기능에 관한 포괄적인 설명입니다.

  • parameters (객체): 함수에 필요한 입력 데이터를 정의합니다.

    • type (문자열): 객체와 같은 전체 데이터 유형을 지정합니다.

    • properties (객체): 개별 매개변수를 나열하며 각 매개변수에는 다음이 포함됩니다.

      • type (문자열): 문자열, 정수, 불리언과 같은 매개변수의 데이터 유형입니다.
      • description (문자열): 매개변수의 목적과 예상 형식을 명확하게 설명합니다.

    • 필수 (배열): 함수가 작동하는 데 필수인 매개변수 이름을 나열하는 문자열 배열입니다.

curl 명령어를 사용하는 함수 선언의 코드 예시는 Gemini API를 사용한 함수 호출 소개를 참고하세요. Gemini API SDK를 사용하여 함수 선언을 만드는 방법의 예는 함수 호출 튜토리얼을 참고하세요.

모델은 단일 프롬프트에서 여러 함수 호출과 출력을 연결하는 데 필요한 코드를 생성할 수 있습니다. 이 코드는 샌드박스 환경에서 실행되어 후속 BidiGenerateContentToolCall 메시지를 생성합니다. 각 함수 호출의 결과를 사용할 수 있을 때까지 실행이 일시중지되므로 순차 처리가 보장됩니다.

클라이언트는 BidiGenerateContentToolResponse로 응답해야 합니다.

자세한 내용은 함수 호출 소개를 참고하세요.

오디오 형식

Multimodal Live API는 다음 오디오 형식을 지원합니다.

  • 입력 오디오 형식: 16kHz little-endian의 원시 16비트 PCM 오디오
  • 출력 오디오 형식: 24kHz little-endian의 원시 16비트 PCM 오디오

시스템 안내

시스템 안내를 제공하여 모델의 출력을 더 효과적으로 제어하고 오디오 응답의 어조와 감정을 지정할 수 있습니다.

시스템 안내는 상호작용이 시작되기 전에 프롬프트에 추가되며 전체 세션 동안 유효합니다.

시스템 안내는 초기 연결 직후 세션이 시작될 때만 설정할 수 있습니다. 세션 중에 모델에 추가 입력을 제공하려면 점진적 콘텐츠 업데이트를 사용하세요.

중단

사용자는 언제든지 모델의 출력을 중단할 수 있습니다. 음성 활동 감지 (VAD)가 중단을 감지하면 진행 중인 생성이 취소되고 삭제됩니다. 이미 클라이언트로 전송된 정보만 세션 기록에 보관됩니다. 그런 다음 서버는 BidiGenerateContentServerContent 메시지를 전송하여 중단을 보고합니다.

또한 Gemini 서버는 대기 중인 모든 함수 호출을 삭제하고 취소된 호출의 ID가 포함된 BidiGenerateContentServerContent 메시지를 전송합니다.

음성

Multimodal Live API는 다음 음성을 지원합니다.

  • 퍽
  • 카론
  • Kore
  • 펜리르
  • Aoede

음성을 지정하려면 세션 구성의 일부로 speechConfig 객체 내에서 voiceName를 설정합니다.

speechConfig 객체의 다음 JSON 표현을 참고하세요.

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

제한사항

프로젝트를 계획할 때는 멀티모달 실시간 API 및 Gemini 2.0의 다음 제한사항을 고려하세요.

클라이언트 인증

멀티모달 라이브 API는 서버 간 인증만 제공하며 직접 클라이언트용으로 사용하지 않는 것이 좋습니다. 클라이언트 입력은 멀티모달 라이브 API와의 보안 인증을 위해 중간 애플리케이션 서버를 통해 라우팅되어야 합니다.

대화 기록

모델은 세션 내 상호작용을 추적하지만 대화 기록은 저장되지 않습니다. 세션이 종료되면 해당 컨텍스트가 삭제됩니다.

이전 세션을 복원하거나 모델에 사용자 상호작용의 이전 맥락을 제공하려면 애플리케이션이 자체 대화 로그를 유지하고 BidiGenerateContentClientContent 메시지를 사용하여 새 세션이 시작될 때 이 정보를 전송해야 합니다.

최대 세션 시간

세션 시간은 오디오의 경우 최대 15분, 오디오 및 동영상의 경우 최대 2분으로 제한됩니다. 세션 시간이 한도를 초과하면 연결이 종료됩니다.

또한 모델은 컨텍스트 크기에 따라 제한됩니다. 동영상 및 오디오 스트림과 함께 대용량 콘텐츠를 전송하면 세션이 더 일찍 종료될 수 있습니다.

음성 활동 감지 (VAD)

이 모델은 연속 오디오 입력 스트림에서 음성 활동 감지 (VAD)를 자동으로 실행합니다. VAD는 항상 사용 설정되어 있으며 매개변수는 구성할 수 없습니다.

추가 제한사항

수동 엔드포인트 지정은 지원되지 않습니다.

오디오 입력과 오디오 출력은 모델의 함수 호출 사용 능력에 부정적인 영향을 미칩니다.

토큰 수

토큰 수는 지원되지 않습니다.

비율 제한

다음 비율 한도가 적용됩니다.

  • API 키당 동시 세션 3개
  • 분당 토큰 4백만 개

메시지 및 이벤트

BidiGenerateContentClientContent

클라이언트에서 전송된 현재 대화의 증분 업데이트입니다. 여기에 있는 모든 콘텐츠는 무조건 대화 기록에 추가되며 콘텐츠를 생성하기 위한 모델의 프롬프트의 일부로 사용됩니다.

여기에 메시지가 표시되면 현재 모델 생성이 중단됩니다.

필드
turns[]

Content

(선택사항) 모델과의 현재 대화에 추가된 콘텐츠입니다.

싱글턴 쿼리의 경우 이는 단일 인스턴스입니다. 멀티턴 쿼리의 경우 이는 대화 기록과 최근 요청이 포함된 반복 필드입니다.
turn_complete

bool

(선택사항) true인 경우 서버 콘텐츠 생성이 현재 누적된 프롬프트로 시작해야 함을 나타냅니다. 그렇지 않으면 서버는 생성을 시작하기 전에 추가 메시지를 기다립니다.

BidiGenerateContentRealtimeInput

실시간으로 전송되는 사용자 입력입니다.

이는 ClientContentUpdate와 몇 가지 차이점이 있습니다.

  • 모델 생성을 중단하지 않고 연속으로 전송할 수 있습니다.
  • ClientContentUpdate와 RealtimeUpdate에서 교차로 삽입된 데이터를 혼합해야 하는 경우 서버는 최적의 응답을 위해 최적화하려고 시도하지만 보장되지는 않습니다.
  • 턴 종료는 명시적으로 지정되지 않으며 대신 사용자 활동 (예: 음성 종료)에서 파생됩니다.
  • 턴이 끝나기 전에도 모델의 응답을 빠르게 시작할 수 있도록 데이터가 점진적으로 처리됩니다.
  • 항상 사용자의 입력으로 간주됩니다 (대화 기록을 채우는 데 사용할 수 없음).
필드
media_chunks[]

Blob

(선택사항) 미디어 입력을 위한 인라인 바이트 데이터입니다.

BidiGenerateContentServerContent

클라이언트 메시지에 대한 응답으로 모델에서 생성된 서버 증분 업데이트입니다.

콘텐츠는 실시간이 아닌 최대한 빨리 생성됩니다. 클라이언트는 버퍼링하고 실시간으로 재생할 수 있습니다.

필드
turn_complete

bool

출력 전용입니다. true인 경우 모델 생성이 완료되었음을 나타냅니다. 생성은 추가 클라이언트 메시지에 대한 응답으로만 시작됩니다. content와 함께 설정하여 content가 턴의 마지막임을 나타낼 수 있습니다.
interrupted

bool

출력 전용입니다. true인 경우 클라이언트 메시지가 현재 모델 생성을 중단했음을 나타냅니다. 클라이언트가 콘텐츠를 실시간으로 재생하는 경우 현재 재생목록을 중지하고 비우는 것이 좋습니다. 클라이언트가 콘텐츠를 실시간으로 재생하는 경우 현재 재생목록을 중지하고 비우는 것이 좋습니다.
grounding_metadata

GroundingMetadata

출력 전용입니다. 메타데이터는 생성된 콘텐츠를 기반으로 하는 데 사용되는 소스를 지정합니다.
model_turn

Content

출력 전용입니다. 모델이 사용자와의 현재 대화의 일부로 생성한 콘텐츠입니다.

BidiGenerateContentSetup

첫 번째이자 유일한 첫 번째 클라이언트 메시지로 전송할 메시지입니다. 스트리밍 세션 기간 동안 적용할 구성을 포함합니다.

클라이언트는 추가 메시지를 보내기 전에 BidiGenerateContentSetupComplete 메시지를 기다려야 합니다.

필드
model

string

필수 입력란입니다. 사용할 게시자 모델 또는 조정된 모델 엔드포인트의 정규화된 이름입니다.

게시자 모델 형식: projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config

GenerationConfig

(선택사항) 생성 구성

다음 필드는 지원되지 않습니다.

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

(선택사항) 사용자가 모델의 시스템 지침을 제공했습니다. 참고: 부분에는 텍스트만 사용해야 합니다. 각 부분의 콘텐츠는 별도의 단락에 위치합니다.
tools[]

Tool

(선택사항) 모델이 다음 응답을 생성하는 데 사용할 수 있는 Tools 목록입니다.

Tool는 시스템이 모델의 지식과 범위를 벗어나 외부 시스템과 상호작용하여 작업 또는 작업 집합을 수행할 수 있도록 하는 코드 조각입니다.

BidiGenerateContentSetupComplete

이 유형에는 필드가 없습니다.

클라이언트의 BidiGenerateContentSetup 메시지에 대한 응답으로 전송됩니다.

BidiGenerateContentToolCall

클라이언트가 functionCalls를 실행하고 일치하는 id와 함께 응답을 반환하도록 요청합니다.

필드
function_calls[]

FunctionCall

출력 전용입니다. 실행할 함수 호출입니다.

BidiGenerateContentToolCallCancellation

지정된 id가 포함된 이전에 발급된 ToolCallMessage가 실행되지 않았으며 취소되어야 한다는 클라이언트 알림 이러한 도구 호출에 부작용이 있는 경우 클라이언트는 도구 호출을 실행취소하려고 시도할 수 있습니다. 이 메시지는 클라이언트가 서버 전환을 중단하는 경우에만 표시됩니다.

필드
ids[]

string

출력 전용입니다. 취소할 도구 호출의 ID입니다.

BidiGenerateContentToolResponse

클라이언트가 서버에서 수신한 ToolCall에 대한 응답을 생성했습니다. 개별 FunctionResponse 객체는 id 필드를 통해 각 FunctionCall 객체와 일치합니다.

단항 및 서버 스트리밍 GenerateContent API에서는 Content 부분을 교환하여 함수를 호출하는 반면, bidi GenerateContent API에서는 이러한 전용 메시지 세트를 통해 함수를 호출합니다.

필드
function_responses[]

FunctionResponse

(선택사항) 함수 호출에 대한 응답입니다.

다음 단계