문제 해결 가이드

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

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

Gemini API 백엔드 서비스 오류 코드

다음 표에는 발생할 수 있는 일반적인 백엔드 오류 코드와 원인 설명, 문제 해결 단계가 나와 있습니다.

HTTP 코드 상태 설명 해결 방법
400 INVALID_ARGUMENT 요청 본문의 형식이 잘못되었습니다. 요청에 오타가 있거나 필수 입력란이 누락되었습니다. 요청 형식, 예시, 지원되는 버전은 API 참조를 확인하세요. 이전 엔드포인트에서 최신 API 버전의 기능을 사용하면 오류가 발생할 수 있습니다.
400 FAILED_PRECONDITION 거주 국가에서는 Gemini API 무료 등급을 이용할 수 없습니다. Google AI Studio에서 프로젝트에 결제를 사용 설정하세요. 무료 등급이 지원되지 않는 리전에서 요청하고 있으며 Google AI Studio의 프로젝트에서 결제를 사용 설정하지 않았습니다. Gemini API를 사용하려면 Google AI Studio를 사용하여 유료 요금제를 설정해야 합니다.
403 PERMISSION_DENIED API 키에 필요한 권한이 없습니다. 잘못된 API 키를 사용하고 있습니다. 적절한 인증을 거치지 않고 조정된 모델을 사용하려고 합니다. API 키가 설정되어 있고 올바른 액세스 권한이 있는지 확인합니다. 조정된 모델을 사용하려면 적절한 인증을 거쳐야 합니다.
404 NOT_FOUND 요청한 리소스를 찾을 수 없습니다. 요청에서 참조된 이미지, 오디오 또는 동영상 파일을 찾을 수 없습니다. API 버전에 대해 요청의 모든 매개변수가 유효한지 확인합니다.
429 RESOURCE_EXHAUSTED 비율 제한을 초과했습니다. 무료 등급 Gemini API를 사용하여 분당 너무 많은 요청을 보내고 있습니다. 모델의 속도 제한 내에 있는지 확인합니다. 필요한 경우 할당량 상향 조정을 요청합니다.
500 내부 Google 측에서 예기치 않은 오류가 발생했습니다. 입력 컨텍스트가 너무 깁니다. 입력 컨텍스트를 줄이거나 일시적으로 다른 모델 (예: Gemini 1.5 Pro에서 Gemini 1.5 Flash로)로 전환하여 작동하는지 확인합니다. 또는 잠시 기다렸다가 요청을 다시 시도하세요. 다시 시도한 후에도 문제가 계속되면 Google AI Studio의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요.
503 현재 구매할 수 없음 서비스가 일시적으로 과부하되거나 다운되었을 수 있습니다. 서비스의 용량이 일시적으로 부족합니다. 다른 모델 (예: Gemini 1.5 Pro에서 Gemini 1.5 Flash로)로 일시적으로 전환하여 작동하는지 확인합니다. 또는 잠시 기다렸다가 요청을 다시 시도하세요. 다시 시도한 후에도 문제가 계속되면 Google AI Studio의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요.
504 DEADLINE_EXCEEDED 서비스가 기한 내에 처리를 완료할 수 없습니다. 프롬프트 (또는 컨텍스트)가 너무 커서 제때 처리할 수 없습니다. 이 오류를 방지하려면 클라이언트 요청에서 'timeout'을 더 크게 설정하세요.

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

모델 매개변수가 다음 값 범위 내에 있는지 확인합니다.

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

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

올바른 모델이 있는지 확인

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

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

2.5 Flash 및 Pro 모델에서 지연 시간 또는 토큰 사용량이 더 높은 경우 품질을 향상하기 위해 기본적으로 사고가 사용 설정되어 있기 때문일 수 있습니다. 속도를 우선시하거나 비용을 최소화해야 하는 경우 생각을 조정하거나 사용 중지할 수 있습니다.

안내 및 샘플 코드는 생각 페이지를 참고하세요.

안전 문제

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는 일부 언어만 지원합니다. 지원되지 않는 언어로 프롬프트를 제출하면 예상치 못한 응답이 생성되거나 차단될 수 있습니다. 최신 정보는 사용 가능한 언어를 참고하세요.

버그 신고

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