문제 해결 가이드

이 가이드를 사용하여 Gemini API를 호출할 때 발생하는 일반적인 문제를 진단하고 해결하세요. Gemini API 백엔드 서비스 또는 클라이언트 SDK에서 문제가 발생할 수 있습니다. 클라이언트 SDK는 다음 저장소에서 오픈소스로 제공됩니다.

API 키 문제가 발생하면 API 키 설정 가이드에 따라 API 키를 올바르게 설정했는지 확인하세요.

오류 코드

HTTP 상태 코드, 생성 차단 코드, 콘텐츠 오류 코드를 비롯한 모든 오류 코드의 전체 참조는 API 오류 페이지를 참고하세요.

재시도 전략

요청을 다시 시도해야 함을 나타내는 오류 (예: 429 RESOURCE_EXHAUSTED 또는 503 UNAVAILABLE)가 표시되면 지수 백오프 전략을 구현하는 것이 좋습니다. 즉, 첫 번째 재시도 전에 잠시 기다린 다음 후속 재시도 간 대기 시간을 점차 늘립니다.

Python SDK와 같은 Gemini API의 공식 클라이언트 SDK에는 시간 초과, 네트워크 문제, 비율 제한 (429 및 5xx 상태 코드)과 같은 일시적인 오류를 처리하기 위해 기본적으로 지수 백오프를 사용하는 자동 재시도 로직이 포함되어 있습니다. 예를 들어 Python SDK는 초기 지연 시간 약 1초, 최대 지연 시간 60초로 일시적인 오류를 최대 4회 자동으로 재시도합니다.

직접 REST API 요청을 하거나 재시도 로직을 맞춤설정하는 경우 다음 권장사항을 따라 요청이 성공할 가능성을 높이고 서비스가 과부하되지 않도록 하세요.

  • 지수 백오프 사용: 첫 번째 재시도 전에 잠시 기다린 후 (예: 1초) 지연 시간을 지수적으로 늘립니다 (예: 2초, 4초, 8초).
  • 지터 추가: 모든 클라이언트가 정확히 동시에 재시도하지 않도록 지연에 임의의 '지터'를 추가합니다.
  • 특정 오류 시 재시도: 일시적인 오류 (예: 429, 408, 5xx)에 대해서만 재시도하세요. 클라이언트 오류 (예: 400, 402, 403)는 무효한 API 키, 선불 크레딧 소진, 잘못된 구문과 같은 문제를 나타내므로 재시도하지 마세요.
  • 최대 재시도 횟수 설정: 무한 루프를 방지하기 위해 최대 재시도 횟수를 정의합니다.

모델 매개변수 오류가 있는지 API 호출 확인

모델 파라미터가 다음 값 범위 내에 있는지 확인합니다.

모델 매개변수 값 (범위)
후보 수 1~8 (정수)
온도 0.0~1.0
최대 출력 토큰 모델 페이지를 사용하여 사용 중인 모델의 최대 토큰 수를 확인합니다.
TopP 0.0~1.0

매개변수 값을 확인하는 것 외에도 필요한 기능을 지원하는 올바른 API 버전 (예: /v1 또는 /v1beta)과 모델을 사용하고 있는지 확인하세요. 예를 들어 기능이 베타 버전인 경우 /v1beta API 버전에서만 사용할 수 있습니다.

올바른 모델이 있는지 확인

모델 페이지에 나열된 지원되는 모델을 사용하고 있는지 확인합니다.

사고 모델 사용 시 지연 시간 또는 토큰 사용량 증가

지연 시간 또는 토큰 사용량이 증가하는 이유는 Gemini 3.x 모델에서 기본적으로 사고가 사용 설정되어 있기 때문인 경우가 많습니다. 지원 중단된 Gemini 2.5 모델도 기본 사고를 사용합니다.

사고 모델은 품질을 개선하기 위해 내부 추론 토큰을 생성합니다. 이 추론 프로세스는 응답 지연 시간과 총 토큰 소비량을 모두 늘립니다.

지연 시간을 줄이거나 비용을 최소화해야 하는 경우 사고 수준을 낮추거나 사고를 사용 중지하면 됩니다.

구성 세부정보와 코드 샘플은 사고 가이드를 참고하세요.

안전 문제

API 호출의 안전 설정으로 인해 프롬프트가 차단된 경우 API 호출에서 설정한 필터를 기준으로 프롬프트를 검토하세요.

BlockedReason.OTHER가 표시되면 질문 또는 대답이 서비스 약관을 위반하거나 지원되지 않는 것일 수 있습니다.

인용 문제

RECITATION 이유로 모델이 출력을 중지하는 경우 모델 출력이 특정 데이터와 유사할 수 있습니다. 이 문제를 해결하려면 프롬프트 / 컨텍스트를 최대한 고유하게 만들고 더 높은 온도를 사용해 보세요.

반복적인 토큰 문제

출력 토큰이 반복되는 경우 다음 제안을 따라 토큰을 줄이거나 없애 보세요.

설명 원인 추천 해결 방법
마크다운 표에서 하이픈이 반복됨 모델이 시각적으로 정렬된 마크다운 테이블을 만들려고 할 때 테이블의 콘텐츠가 길면 이 문제가 발생할 수 있습니다. 하지만 마크다운의 정렬은 올바른 렌더링에 필요하지 않습니다.

프롬프트에 요청 사항을 추가하여 마크다운 표를 생성하기 위한 구체적인 가이드라인을 모델에 제공합니다. 이러한 가이드라인을 따르는 예시를 제공하세요. 온도를 조정해 볼 수도 있습니다. 코드를 생성하거나 마크다운 표와 같은 매우 구조화된 출력을 생성하는 경우 온도가 높을수록 (>= 0.8) 더 나은 결과를 얻을 수 있습니다.

다음은 이 문제를 방지하기 위해 프롬프트에 추가할 수 있는 가이드라인의 예시입니다. 

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
마크다운 표의 반복 토큰 반복되는 하이픈과 마찬가지로 모델이 표의 콘텐츠를 시각적으로 정렬하려고 할 때 발생합니다. 마크다운의 정렬은 올바른 렌더링에 필요하지 않습니다.
  • 시스템 프롬프트에 다음과 같은 요청 사항을 추가해 보세요. 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • 온도를 조정해 보세요. 온도가 높을수록 (>= 0.8) 일반적으로 출력에서 반복이나 중복을 없애는 데 도움이 됩니다.
구조화된 출력에서 반복되는 줄바꿈 (\n) 모델 입력에 유니코드나 \u, \t과 같은 이스케이프 시퀀스가 포함되면 줄바꿈이 반복될 수 있습니다.
  • 프롬프트에서 금지된 이스케이프 시퀀스를 확인하고 UTF-8 문자로 대체합니다. 예를 들어 JSON 예시의 \u 이스케이프 시퀀스로 인해 모델이 출력에서도 이를 사용할 수 있습니다.
  • 허용된 이스케이프에 관해 모델에 안내합니다. 다음과 같은 시스템 안내를 추가합니다. 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
구조화된 출력을 사용할 때 텍스트가 반복됨 모델 출력의 필드 순서가 정의된 구조화된 스키마와 다르면 텍스트가 반복될 수 있습니다.
  • 프롬프트에서 필드의 순서를 지정하지 마세요.
  • 모든 출력 필드를 필수 항목으로 만듭니다.
반복적인 도구 호출 이는 모델이 이전 생각의 맥락을 잃거나 사용할 수 없는 엔드포인트를 호출해야 하는 경우에 발생할 수 있습니다. 모델에 사고 과정 내에서 상태를 유지하도록 지시합니다. 시스템 요청 사항 끝에 다음을 추가합니다. 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
구조화된 출력에 포함되지 않는 반복적인 텍스트 모델이 해결할 수 없는 요청에 갇히면 이 문제가 발생할 수 있습니다.
  • 사고가 사용 설정된 경우, 문제에 대해 생각하는 방법을 안내에 명시적으로 지시하지 마세요. 최종 출력을 요청하기만 하면 됩니다.
  • 온도를 0.8 이상으로 높여 보세요.
  • '간결하게 작성해', '반복하지 마', '답변을 한 번만 제공해'와 같은 요청 사항을 추가합니다.

차단되었거나 작동하지 않는 API 키

이 섹션에서는 Gemini API 키가 차단되었는지 확인하는 방법과 차단된 경우 취해야 할 조치를 설명합니다.

키가 차단되는 이유 이해하기

일부 API 키가 공개적으로 노출되었을 수 있는 취약점이 확인되었습니다. 데이터를 보호하고 무단 액세스를 방지하기 위해 Google에서는 유출된 것으로 알려진 이러한 키가 Gemini API에 액세스하지 못하도록 사전 조치를 취했습니다.

키가 영향을 받는지 확인하기

키가 유출된 것으로 알려진 경우 더 이상 Gemini API에서 해당 키를 사용할 수 없습니다. Google AI Studio를 사용하여 Gemini API 호출이 차단된 API 키가 있는지 확인하고 새 키를 생성할 수 있습니다. 이러한 키를 사용하려고 할 때 다음 오류가 반환될 수도 있습니다.

Your API key was reported as leaked. Please use another API key.

차단된 API 키에 대한 작업

Google AI Studio를 사용하여 Gemini API 통합을 위한 새 API 키를 생성해야 합니다. 새 키가 안전하게 유지되고 공개적으로 노출되지 않도록 API 키 관리 관행을 검토하는 것이 좋습니다.

취약점으로 인한 예상치 못한 청구

결제 지원 케이스를 제출합니다. Google 결제팀에서 이 문제를 해결하기 위해 노력하고 있으며, 최대한 빨리 업데이트를 알려드리겠습니다.

유출된 키에 대한 Google의 보안 조치

API 키가 유출되면 Google은 비용 초과 및 악용으로부터 내 계정을 어떻게 보호하나요?

  • Google AI Studio를 사용하여 새 키를 요청할 때 API 키를 발급하는 방향으로 전환하고 있습니다. 이 API 키는 기본적으로 Google AI Studio로만 제한되며 다른 서비스의 키는 허용되지 않습니다. 이렇게 하면 의도하지 않은 교차 키 사용을 방지할 수 있습니다.
  • 비용 및 애플리케이션 데이터의 악용을 방지하기 위해 유출되어 Gemini API와 함께 사용되는 API 키는 기본적으로 차단됩니다.
  • Google AI Studio에서 API 키의 상태를 확인할 수 있으며, Google에서는 즉각적인 조치를 위해 API 키가 유출된 것으로 확인되면 선제적으로 알려드릴 것입니다.

모델 출력 개선

모델 출력의 품질을 높이려면 더 구조화된 프롬프트를 작성해 보세요. 프롬프트 엔지니어링 가이드 페이지에서는 시작하는 데 도움이 되는 몇 가지 기본 개념, 전략, 권장사항을 소개합니다.

토큰 한도 이해하기

토큰 가이드를 읽고 토큰 수와 한도를 파악하세요.

알려진 문제

  • API는 일부 언어만 지원합니다. 지원되지 않는 언어로 프롬프트를 제출하면 예기치 않은 응답이 생성되거나 응답이 차단될 수 있습니다. 사용 가능한 언어에서 업데이트를 확인하세요.

버그 신고

궁금한 점이 있으면 Google AI 개발자 포럼에서 토론에 참여하세요.