문제 해결 가이드

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

• python-genai
• js-genai
• go-genai

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

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

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

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

모델 매개변수가 다음 값 내에 있는지 확인하세요.

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

올바른 모델이 있는지 확인

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

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

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

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

안전 문제

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

BlockedReason.OTHER가 표시되면 쿼리 또는 응답이 서비스 약관을 위반하거나 지원되지 않을 수 있습니다.

인용 문제

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

반복 토큰 문제

출력 토큰이 반복되는 경우 다음 제안사항을 시도하여 토큰을 줄이거나 삭제해 보세요.

          # 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.
        

        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.
      

차단되거나 작동하지 않는 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의 보안 조치

API 키가 유출된 경우 Google에서 비용 초과 및 악용으로부터 내 계정을 보호하는 데 어떻게 도움을 줄 수 있나요?

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

모델 출력 개선

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

토큰 한도 이해

토큰 가이드를 읽고 토큰을 집계하는 방법과 토큰 한도를 자세히 알아보세요.

알려진 문제

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

버그 신고

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