Tipps zur Fehlerbehebung

In dieser Anleitung erfahren Sie, wie Sie häufige Probleme diagnostizieren und beheben, die beim Aufrufen der Gemini API auftreten. Probleme können entweder im Back-End-Dienst der Gemini API oder in den Client-SDKs auftreten. Unsere Client-SDKs sind Open Source und in den folgenden Repositories verfügbar:

Wenn Sie Probleme mit dem API-Schlüssel haben, prüfen Sie, ob Sie ihn gemäß der Anleitung zum Einrichten von API-Schlüsseln richtig eingerichtet haben.

Fehlercodes für den Backend-Dienst der Gemini API

In der folgenden Tabelle sind häufige Backend-Fehlercodes aufgeführt, die auftreten können, zusammen mit Erklärungen zu ihren Ursachen und Schritten zur Fehlerbehebung:

HTTP-Code Status Beschreibung Beispiel Lösung
400 INVALID_ARGUMENT Der Anfragetext ist fehlerhaft. Ihre Anfrage enthält einen Tippfehler oder ein Pflichtfeld fehlt. Informationen zum Anfrageformat, zu Beispielen und zu unterstützten Versionen finden Sie in der API-Referenz. Wenn Sie Funktionen einer neueren API-Version mit einem älteren Endpunkt verwenden, kann das zu Fehlern führen.
400 FAILED_PRECONDITION Die kostenlose Stufe der Gemini API ist in Ihrem Land nicht verfügbar. Aktivieren Sie die Abrechnung für Ihr Projekt in Google AI Studio. Sie stellen eine Anfrage in einer Region, in der das kostenlose Kontingent nicht unterstützt wird, und haben die Abrechnung für Ihr Projekt in Google AI Studio nicht aktiviert. Wenn Sie die Gemini API verwenden möchten, müssen Sie in Google AI Studio ein kostenpflichtiges Abo einrichten.
403 PERMISSION_DENIED Ihr API-Schlüssel hat nicht die erforderlichen Berechtigungen. Sie verwenden den falschen API-Schlüssel oder versuchen, ein abgestimmtes Modell zu verwenden, ohne die richtige Authentifizierung durchzuführen. Prüfen Sie, ob Ihr API-Schlüssel festgelegt ist und die richtigen Zugriffsrechte hat. Außerdem müssen Sie sich richtig authentifizieren, um abgestimmte Modelle verwenden zu können.
404 NOT_FOUND Die angeforderte Ressource wurde nicht gefunden. Eine in Ihrer Anfrage referenzierte Bild-, Audio- oder Videodatei wurde nicht gefunden. Prüfen Sie, ob alle Parameter in Ihrer Anfrage für Ihre API-Version gültig sind.
429 RESOURCE_EXHAUSTED Sie haben das Ratenlimit überschritten. Sie senden mit der kostenlosen Version der Gemini API zu viele Anfragen pro Minute. Prüfen Sie, ob Sie das Ratenlimit des Modells einhalten. Fordern Sie bei Bedarf eine Kontingenterhöhung an.
500 INTERN Bei Google ist ein unerwarteter Fehler aufgetreten. Der Kontext Ihrer Eingabe ist zu lang. Reduzieren Sie den Eingabekontext oder wechseln Sie vorübergehend zu einem anderen Modell (z.B. von Gemini 1.5 Pro zu Gemini 1.5 Flash) und prüfen Sie, ob es funktioniert. Warten Sie etwas und versuchen Sie es dann noch einmal. Wenn das Problem nach dem erneuten Versuch weiterhin besteht, melden Sie es bitte in Google AI Studio über die Schaltfläche Feedback geben.
503 UNAVAILABLE Möglicherweise ist der Dienst vorübergehend überlastet oder nicht erreichbar. Der Dienst hat vorübergehend keine Kapazitäten mehr. Wechseln Sie vorübergehend zu einem anderen Modell (z.B. von Gemini 1.5 Pro zu Gemini 1.5 Flash) und prüfen Sie, ob es funktioniert. Warten Sie etwas und versuchen Sie es dann noch einmal. Wenn das Problem nach dem erneuten Versuch weiterhin besteht, melden Sie es bitte in Google AI Studio über die Schaltfläche Feedback geben.
504 DEADLINE_EXCEEDED Der Dienst kann die Verarbeitung nicht innerhalb der Frist abschließen. Ihr Prompt (oder Kontext) ist zu groß, um rechtzeitig verarbeitet zu werden. Legen Sie in Ihrer Clientanfrage einen längeren „Timeout“ fest, um diesen Fehler zu vermeiden.

API-Aufrufe auf Fehler bei Modellparametern prüfen

Prüfen Sie, ob die Parameter Ihres Modells die folgenden Werte einhalten:

Modellparameter Werte (Bereich)
Anzahl der Kandidaten 1–8 (Ganzzahl)
Temperatur 0,0–1,0
Maximale Ausgabetokens Verwenden Sie get_model (Python), um die maximale Anzahl von Tokens für das verwendete Modell zu ermitteln.
TopP 0,0–1,0

Achten Sie nicht nur auf die Parameterwerte, sondern auch darauf, dass Sie die richtige API-Version verwenden (z.B. /v1 oder /v1beta) und ein Modell, das die benötigten Funktionen unterstützt. Wenn sich eine Funktion beispielsweise in der Betaphase befindet, ist sie nur in der /v1beta-API-Version verfügbar.

Prüfen, ob Sie das richtige Modell haben

Prüfen Sie, ob Sie ein unterstütztes Modell verwenden, das auf unserer Seite „Modelle“ aufgeführt ist.

Höhere Latenz oder Tokennutzung bei 2.5-Modellen

Wenn Sie bei den Modellen 2.5 Flash und Pro eine höhere Latenz oder Tokennutzung feststellen, kann das daran liegen, dass Thinking standardmäßig aktiviert ist, um die Qualität zu verbessern. Wenn Sie Geschwindigkeit priorisieren oder Kosten minimieren müssen, können Sie die Denkphase anpassen oder deaktivieren.

Denkseite mit Anleitung und Beispielcode

Sicherheitsprobleme

Wenn Sie sehen, dass ein Prompt aufgrund einer Sicherheitseinstellung in Ihrem API-Aufruf blockiert wurde, überprüfen Sie den Prompt im Hinblick auf die Filter, die Sie im API-Aufruf festgelegt haben.

Wenn Sie BlockedReason.OTHER sehen, verstößt die Anfrage oder Antwort möglicherweise gegen die Nutzungsbedingungen oder wird anderweitig nicht unterstützt.

Problem mit der Rezitation

Wenn das Modell die Ausgabe aufgrund des RECITATION-Grundes beendet, bedeutet das, dass die Modellausgabe bestimmten Daten ähneln kann. Um das Problem zu beheben, sollten Sie den Prompt bzw. Kontext so einzigartig wie möglich gestalten und eine höhere Temperatur verwenden.

Problem mit sich wiederholenden Tokens

Wenn Sie wiederholte Ausgabetokens sehen, können Sie versuchen, sie mit den folgenden Vorschlägen zu reduzieren oder zu eliminieren.

Beschreibung Ursache Vorgeschlagene Problemumgehung
Wiederholte Bindestriche in Markdown-Tabellen Dies kann passieren, wenn der Inhalt der Tabelle lang ist, da das Modell versucht, eine visuell ausgerichtete Markdown-Tabelle zu erstellen. Die Ausrichtung in Markdown ist jedoch für das korrekte Rendern nicht erforderlich.

Fügen Sie in Ihren Prompt Anweisungen ein, um dem Modell spezifische Richtlinien für das Generieren von Markdown-Tabellen zu geben. Geben Sie Beispiele an, die diesen Richtlinien entsprechen. Sie können auch versuchen, die Temperatur anzupassen. Für das Generieren von Code oder sehr strukturierten Ausgaben wie Markdown-Tabellen hat sich eine hohe Temperatur (>= 0,8) als besser erwiesen.

Im Folgenden finden Sie ein Beispiel für Richtlinien, die Sie Ihrem Prompt hinzufügen können, um dieses Problem zu vermeiden: 

          # 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.
Wiederholte Tokens in Markdown-Tabellen Ähnlich wie bei den wiederholten Bindestrichen tritt dies auf, wenn das Modell versucht, den Inhalt der Tabelle visuell auszurichten. Die Ausrichtung in Markdown ist für das korrekte Rendern nicht erforderlich.
  • Fügen Sie Ihrem System-Prompt Anweisungen wie die folgenden hinzu: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Versuche, die Temperatur anzupassen. Höhere Temperaturen (>= 0,8) tragen in der Regel dazu bei, Wiederholungen oder Duplikate in der Ausgabe zu vermeiden.
Wiederholte Zeilenumbrüche (\n) in der strukturierten Ausgabe Wenn die Modelleingabe Unicode- oder Escape-Sequenzen wie \u oder \t enthält, kann dies zu wiederholten Zeilenumbrüchen führen.
  • Suchen Sie in Ihrem Prompt nach verbotenen Escape-Sequenzen und ersetzen Sie sie durch UTF-8-Zeichen. Wenn Sie beispielsweise die Escape-Sequenz \u in Ihren JSON-Beispielen verwenden, kann es sein, dass das Modell sie auch in seiner Ausgabe verwendet.
  • Weisen Sie das Modell auf zulässige Escapes hin. Fügen Sie eine Systemanweisung wie diese hinzu: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Wiederholter Text bei Verwendung strukturierter Ausgabe Wenn die Felder in der Modellausgabe in einer anderen Reihenfolge als im definierten strukturierten Schema stehen, kann dies zu sich wiederholendem Text führen.
  • Geben Sie die Reihenfolge der Felder nicht in Ihrem Prompt an.
  • Machen Sie alle Ausgabefelder zu Pflichtfeldern.
Wiederholte Tool-Aufrufe Das kann passieren, wenn das Modell den Kontext früherer Überlegungen verliert und/oder einen nicht verfügbaren Endpunkt aufruft, zu dem es gezwungen wird. Weisen Sie das Modell an, den Status in seinem Denkprozess beizubehalten. Fügen Sie am Ende Ihrer Systemanweisung Folgendes hinzu: 
        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.
Wiederholter Text, der nicht Teil der strukturierten Ausgabe ist Das kann passieren, wenn das Modell bei einer Anfrage hängen bleibt, die es nicht beantworten kann.
  • Wenn die Funktion „Denken“ aktiviert ist, sollten Sie in der Anleitung keine expliziten Anweisungen dazu geben, wie ein Problem durchdacht werden soll. Fragen Sie einfach nach der endgültigen Ausgabe.
  • Versuchen Sie es mit einer höheren Temperatur ≥ 0,8.
  • Fügen Sie Anweisungen wie „Fasse dich kurz“, „Wiederhole dich nicht“ oder „Gib die Antwort nur einmal“ hinzu.

Modellausgabe verbessern

Wenn Sie eine höhere Qualität der Modellausgabe wünschen, sollten Sie strukturiertere Prompts schreiben. Auf der Seite Leitfaden zum Prompt Engineering werden einige grundlegende Konzepte, Strategien und Best Practices vorgestellt, die Ihnen den Einstieg erleichtern.

Informationen zu Tokenlimits

In unserem Leitfaden zu Tokens erfahren Sie mehr darüber, wie Tokens gezählt werden und welche Limits gelten.

Bekannte Probleme

  • Die API unterstützt nur eine begrenzte Anzahl von Sprachen. Wenn Sie Prompts in nicht unterstützten Sprachen eingeben, kann das zu unerwarteten oder sogar blockierten Antworten führen. Verfügbare Sprachen

Fehler melden

Wenn Sie Fragen haben, können Sie sich im Google AI-Entwicklerforum an der Diskussion beteiligen.