Live API 모범 사례

Live API 모범 사례 (best practices)

미리보기: Live API는 미리보기 상태예요.

이 가이드는 Live API 사용을 최적화하기 위해 따를 수 있는 모범 사례를 다뤄요. 개요와 일반적인 사용 사례의 샘플 코드는 Get started with Live API 페이지를 참고하세요.

출처: 원문

본문

명확한 시스템 지시어 설계하기 (Design clear system instructions)

Live API에서 최고 성능을 얻으려면 에이전트 페르소나, 대화 규칙, 가드레일을 순서대로 정의하는 명확한 시스템 지시어(SI) 집합을 갖추는 걸 권장해요.

최상의 결과를 위해 각 에이전트를 별개의 SI로 분리하세요.

에이전트 페르소나 지정: 에이전트의 이름, 역할, 선호 특성에 대한 세부 정보를 제공하세요. 악센트를 지정하려면 선호 출력 언어도 함께 지정하세요(예: 영어 사용자를 위한 영국식 악센트).
대화 규칙 지정: 모델이 따르길 기대하는 순서대로 규칙을 넣으세요. 대화의 일회성 요소와 대화 루프를 구분하세요. 예:
- 일회성 요소: 고객 세부 정보를 한 번 수집(이름, 위치, 로열티 카드 번호 등).
- 대화 루프: 사용자가 추천, 가격, 반품, 배송을 논의하고 주제를 오갈 수 있어요. 사용자가 원하는 만큼 오래 이 대화 루프에 참여해도 된다는 걸 모델에 알려 주세요.
흐름 안에서 도구 호출을 별개의 문장으로 지정: 예를 들어 고객 세부 정보 수집이라는 일회성 단계에 get_user_info 함수 실행이 필요하다면, *"당신의 첫 단계는 사용자 정보를 수집하는 것입니다. 먼저 사용자에게 이름, 위치, 로열티 카드 번호를 제공하라고 요청하세요. 그런 다음 이 세부 정보로 get_user_info를 호출하세요."*처럼 말할 수 있어요.
필요한 가드레일 추가: 모델이 하지 않길 바라는 일반적인 대화 가드레일을 제공하세요. x가 발생하면 y를 하길 원한다는 구체적인 예시를 자유롭게 제공하세요. 원하는 정밀도를 얻지 못하고 있다면 unmistakably라는 단어를 사용해 모델이 정밀하게 행동하도록 안내하세요.

도구를 정밀하게 정의하기 (Define tools precisely)

Live API에서 도구를 사용할 때 도구 정의를 구체적으로 하세요. Gemini에 도구 호출이 어떤 조건에서 실행되어야 하는지 반드시 알려 주세요. 자세한 내용은 예시 섹션의 도구 정의를 참고하세요.

효과적인 프롬프트 작성 (Craft effective prompts)

명확한 프롬프트 사용: 프롬프트에 모델이 해야 할 일과 하지 말아야 할 일의 예시를 제공하고, 한 번에 페르소나나 역할당 프롬프트 하나로 제한하세요. 길고 여러 페이지짜리 프롬프트 대신 **프롬프트 체이닝(prompt chaining)**을 고려하세요. 모델은 단일 함수 호출이 있는 작업에서 최상의 성능을 보여요.
시작 명령과 정보 제공: Live API는 응답하기 전에 사용자 입력을 기대해요. Live API가 대화를 시작하게 하려면 사용자에게 인사하거나 대화를 시작하라는 프롬프트를 포함하세요. 그 인사를 개인화할 수 있도록 사용자 정보를 포함하세요.

언어 지정하기 (Specify language)

Live API 오디오 모델은 명시적 언어 코드 없이 사용자가 말하는 언어를 자동으로 감지하고 적응해요.

모델이 특정 언어로 응답하길 원한다면 시스템 지시어의 일부로 다음 지시를 포함하세요:

RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.

스트리밍 (Streaming)

실시간 오디오를 구현할 때는 다음 모범 사례를 따르세요:

청크 크기와 지연 시간(Chunk Size and Latency): 오디오를 20ms~40ms 청크로 보내세요.
중단 처리(Interruption Handling): 모델이 응답하는 동안 사용자가 말하면 서버가 "interrupted": true가 포함된 server_content 메시지를 보내요. 에이전트가 사용자 위에서 계속 말하지 않도록 즉시 클라이언트 오디오 버퍼를 버려야 해요.

컨텍스트 관리 (Context management)

네이티브 오디오 토큰이 빠르게 누적되므로(오디오 1초당 약 25토큰) 긴 세션에는 ContextWindowCompressionConfig를 사용하세요.

클라이언트 버퍼링 (Client buffering)

입력 오디오를 크게 버퍼링(예: 1초)하지 말고 보내세요. 지연 시간을 최소화하려면 작은 청크(20ms~100ms)를 보내세요.

리샘플링 (Resampling)

클라이언트 애플리케이션이 마이크 입력(흔히 44.1kHz 또는 48kHz)을 전송 전에 16kHz로 리샘플링하도록 보장하세요.

세션 관리 (Session management)

세션 수명 주기를 처리하고 안정적인 사용자 경험을 보장하려면 다음 지침을 따르세요:

컨텍스트 창 압축 활성화: 오디오 토큰이 초당 약 25토큰씩 누적돼요. 압축이 없으면 오디오 전용 세션은 15분, 오디오-비디오 세션은 2분으로 제한돼요. 컨텍스트 창 압축을 활성화하면 세션을 무제한으로 확장할 수 있어요.
세션 재개 구현: 서버가 주기적으로 WebSocket 연결을 재설정할 수 있어요. 세션 재개를 사용해 컨텍스트를 잃지 않고 매끄럽게 재연결하세요. SessionResumptionUpdate 메시지에서 최신 재개 토큰을 보관하고 재연결 시 핸들로 전달하세요. 재개 토큰은 마지막 세션이 종료된 후 2시간 동안 유효해요.
GoAway 메시지 처리: 서버는 연결을 종료하기 전에 GoAway 메시지를 보내요. 이 메시지를 듣고 timeLeft 필드를 사용해 연결이 닫히기 전에 우아하게 마무리하거나 재연결하세요.
generationComplete 신호 처리: generationComplete 메시지를 사용해 모델이 응답 생성을 끝냈을 때를 알아서, 애플리케이션이 UI를 업데이트하거나 다음 동작을 진행하게 하세요.

구현 세부 사항은 Session management를 참고하세요.

예시 (Examples)

이 예시는 모범 사례와 시스템 지시어 설계 지침을 결합해 모델을 커리어 코치로 안내해요.

페르소나 (Persona): 당신은 뉴욕 브루클린 출신의 커리어 코치 Laura입니다. 내담자들이 헤쳐 나가는 커리어 질문에 새로운 관점을 주기 위해 데이터 기반 조언을 제공하는 것을 전문으로 합니다. 당신의 특기는 정량적이고 데이터 기반의 통찰을 제공해 내담자가 자신의 문제를 다른 방식으로 생각하도록 돕는 것입니다. 가능한 한 통계, 연구, 심리학을 활용합니다. 내담자가 어떤 언어로 말해도 영어로만 응답합니다.

대화 규칙 (Conversational Rules):

자기 소개: 내담자를 따뜻하게 인사합니다.
접수(Intake): 내담자의 성명, 생년월일, 거주 주를 물어봅니다. create_client_profile을 호출해 새 환자 프로필을 만듭니다.
내담자의 문제 논의: 세션에서 다루고 싶어 하는 것을 파악합니다. 응답에서 내담자가 말하는 것을 되풀이하지 마세요. 여기서 질문을 몇 개 이상 하지 마세요.
실제 데이터로 내담자의 문제 재구성하기: 상투적인 말(PLATITUDES) 금지. 내담자를 위한 데이터 기반 통찰 제공을 시작하되, 이를 대화 속의 일반적인 사실로 자연스럽게 녹이세요. 이것이 내담자가 당신에게 찾아오는 이유입니다: 그들을 스트레스하게 하는 주제에 대한 당신의 독특한 사고. 새로운 사고 방식을 보여 주세요. 내담자가 원하는 만큼 이 단계를 이어가게 하세요. 이 과정에서 내담자가 어떤 행동을 취하길 원한다고 언급하면 add_action_items_to_profile을 업데이트해 나중에 상기시켜 주세요.
다음 약속: get_next_appointment을 호출해 내담자의 다음 약속이 이미 예약되어 있는지 확인합니다. 있다면 날짜와 시간을 내담자와 공유하고 참석 가능한지 확인합니다. 약속이 없다면 get_available_appointments을 호출해 빈 자리를 확인합니다. 빈 자리 목록을 내담자와 공유하고 선호를 물어봅니다. schedule_appointment으로 선호를 저장합니다. 내담자가 오프라인으로 예약하길 원한다면 전혀 문제없다고 알리고 환자 포털을 사용하라고 안내합니다.

일반 지침 (General Guidelines): 재치 있고 날카로운 대화 상대가 되는 게 목표입니다. 응답을 짧게 유지하고 내담자가 요청하면 점진적으로 더 많은 정보를 공개하세요. 내담자가 말한 것을 되풀이하지 마세요. 각 응답은 대화에 대한 순수한 새 추가이어야 하며, 내담자가 말한 요약이 아니어야 합니다. 브루클린에서 전문적으로 성장한 자신의 배경을 끌어와 공감을 얻으세요. 내담자가 주제를 벗어나려 하면 위에 설명한 워크플로로 부드럽게 되돌리세요.

가드레일 (Guardrails): 내담자가 자신을 힘들게 하면 절대 그런 태도를 부추기지 마세요. 궁극적인 목표는 내담자가 성장할 수 있는 지지적인 환경을 만드는 것임을 기억하세요.

도구 정의 (Tool definitions)

이 JSON은 커리어 코치 예시에서 호출되는 관련 함수를 정의해요. 함수를 정의할 때는 이름, 설명, 매개변수, 실행 조건을 포함하는 것이 가장 좋아요.

[
  {
    "name": "create_client_profile",
    "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
    "parameters": {
      "type": "object",
      "properties": {
        "full_name": { "type": "string", "description": "The client's full name." },
        "date_of_birth": { "type": "string", "description": "The client's date of birth in YYYY-MM-DD format." },
        "state": { "type": "string", "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')." }
      },
      "required": ["full_name", "date_of_birth", "state"]
    }
  },
  {
    "name": "add_action_items_to_profile",
    "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
    "parameters": {
      "type": "object",
      "properties": {
        "client_id": { "type": "string", "description": "The unique ID of the client, obtained from create_client_profile." },
        "action_items": { "type": "array", "items": { "type": "string" }, "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])." }
      },
      "required": ["client_id", "action_items"]
    }
  },
  {
    "name": "get_next_appointment",
    "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
    "parameters": { "type": "object", "...": "..." }
  }
]

참고: 도구 정의 JSON의 일부는 원문에서 길게 이어지므로 여기서는 구조를 대표하는 형태로 요약했어요. 원문의 전체 도구 정의는 [원문 페이지]를 확인하세요.

가격 및 청구 (Pricing and billing)

Gemini Live API는 토큰 사용량으로만 청구해요. Live API는 영구 WebSocket 세션을 유지하므로, 청구는 활성 컨텍스트 창에 기반한 복리 방식을 따릅니다.

세션 컨텍스트 창 (복리 비용)

API는 세션 컨텍스트 창에 있는 모든 토큰에 대해 턴마다 청구해요. "턴(turn)"은 사용자 입력 하나와 그에 대한 모델 응답으로 정의돼요.

누적(Accumulation): 컨텍스트 창에는 현재 턴의 새 토큰과 이전 턴에서 누적된 모든 토큰이 포함돼요.
재청구(Re-billing): 이전 토큰은 구성한 컨텍스트 창 크기까지 각 새 턴에서 다시 처리되고 계산돼요. 세션이 길어질수록 대화 기록을 다시 처리하므로 턴당 비용이 증가해요.

오디오 토큰과 전사

Live API는 기본적으로 멀티모달이에요. 음향적 뉘앙스와 톤을 보존하기 위해 대화 기록을 원시 오디오 토큰으로 유지해요.

오디오 청구: 매 턴 누적된 네이티브 오디오 토큰을 표준 오디오 입력 요율로 청구해요.
전사 추가 요금: 오디오-텍스트 전사가 활성화되면(inputAudioTranscription 또는 outputAudioTranscription), 전사를 위해 생성된 모든 텍스트 토큰을 표준 오디오 토큰 비용에 더해 텍스트 토큰 출력 요율로 청구해요.

컨텍스트 한도로 비용 관리하기

긴 세션에서 무한 비용 증가를 막으려면 contextWindowCompression으로 컨텍스트 창 크기를 구성하세요.

압축 트리거(예: 25,000토큰)와 슬라이딩 창(예: 8,000토큰)을 설정하면, 임계값에 도달했을 때 API가 오래된 토큰을 자동으로 방출해요. 이후 턴은 유지된 기록과 새 토큰에 대해서만 청구돼요.

선제적 오디오 (Proactive audio)

선제적 오디오가 활성화되면 API는 Live API가 듣고 있는 동안 내내 입력 토큰에 대해 청구하고, API가 응답할 때만 출력 토큰에 대해 청구해요.

Gemini 3.8 참고: gemini-3.8-live와 gemini-3.8-live-extended-thinking에서는 선제적 오디오가 영구적으로 활성화돼 있어요.
Gemini 3.1 참고: gemini-3.1-flash-live-preview에서는 선제적 오디오가 지원되지 않아요. 이 모델에서는 입력을 적극적으로 스트리밍할 때만 오디오에 대해 청구돼요.

자세한 가격 정보는 Gemini API pricing 페이지를 참고하세요.

더 알아보기 (Learn more)

Get started with Live API — 개요와 샘플 코드.
Session management — 세션 수명 주기 상세.
Gemini API pricing — 가격 세부 정보.