トラブルシューティング ガイド

このガイドは、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 で 1 分あたりのリクエスト数が多すぎます。 モデルのレート上限を超えていないことを確認します。必要に応じて、割り当ての増加をリクエストします。
500 INTERNAL Google 側で予期しないエラーが発生しました。 入力コンテキストが長すぎます。 入力コンテキストを減らすか、別のモデルに一時的に切り替えて（Gemini 1.5 Pro から Gemini 1.5 Flash など）、動作するかどうかを確認します。しばらく待ってからリクエストを再試行してください。再試行しても問題が解決しない場合は、Google AI Studio の [フィードバックを送信] ボタンを使用してご報告ください。
503 UNAVAILABLE サービスが一時的に過負荷状態になっているか、ダウンしている可能性があります。 サービスで一時的に容量が不足しています。 別のモデル（Gemini 1.5 Pro から Gemini 1.5 Flash など）に一時的に切り替えて、動作するかどうかを確認します。しばらく待ってからリクエストを再試行してください。再試行しても問題が解決しない場合は、Google AI Studio の [フィードバックを送信] ボタンを使用してご報告ください。
504 DEADLINE_EXCEEDED サービスが期限内に処理を完了できない。 プロンプト（またはコンテキスト）が大きすぎて、時間内に処理できません。 このエラーを回避するには、クライアント リクエストで「タイムアウト」を大きく設定します。

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 という理由でモデルの出力生成が停止した場合は、モデルの出力が特定のデータに類似している可能性があります。この問題を解決するには、プロンプト / コンテキストをできるだけ一意にし、より高い温度を使用してみてください。

トークンの繰り返しに関する問題

出力トークンが繰り返し表示される場合は、次の提案を試して、出力トークンを減らすか、削除してください。

説明 原因 推奨される回避策
マークダウン テーブルでハイフンが繰り返される これは、モデルが視覚的に整列された Markdown テーブルを作成しようとしたときに、テーブルの内容が長い場合に発生する可能性があります。ただし、Markdown の配置は正しくレンダリングするために必要ではありません。

プロンプトに指示を追加して、Markdown テーブルを生成するための具体的なガイドラインをモデルに提供します。これらのガイドラインに沿った例を示します。温度を調整してみることもできます。コードや Markdown テーブルのような構造化された出力を生成する場合は、高い温度（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.
マークダウン テーブル内の繰り返しトークン ハイフンが繰り返されるのと同様に、これはモデルが表の内容を視覚的に揃えようとしたときに発生します。Markdown の配置は、正しくレンダリングするために必須ではありません。
  • 次のような指示をシステム プロンプトに追加してみてください。
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • 温度を調整してみてください。温度が高い（0.8 以上）ほど、一般的に出力の繰り返しや重複を排除できます。
構造化出力内の改行の繰り返し（\n） モデル入力に \u や \t などの Unicode またはエスケープ シーケンスが含まれていると、改行が繰り返されることがあります。
  • プロンプトで禁止されているエスケープ シーケンスを確認し、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 以上に設定してみてください。
  • 「簡潔に答えて」、「同じことを繰り返さないで」、「答えは 1 回だけ提供して」などの指示を追加します。

モデル出力を改善する

モデルの出力の品質を高めるには、より構造化されたプロンプトの作成を検討してください。プロンプト エンジニアリング ガイドのページでは、基本的なコンセプト、戦略、ベスト プラクティスについて説明します。

優れた入出力ペアの例が数百件ある場合は、モデル チューニングも検討できます。

トークンの上限について

トークン ガイドを読んで、トークンのカウント方法と上限について理解を深めます。

既知の問題

  • この API は、一部の言語のみをサポートしています。サポートされていない言語でプロンプトを送信すると、予期しない回答が生成されたり、回答がブロックされたりする可能性があります。最新情報については、利用可能な言語をご覧ください。

バグを報告

ご不明な点がある場合は、Google AI デベロッパー フォーラムでディスカッションにご参加ください。