In dieser Anleitung erfahren Sie, wie Sie häufige Probleme diagnostizieren und beheben, die beim Aufrufen der Gemini API auftreten. Probleme können entweder durch den Gemini API-Back-End-Dienst oder durch die Client-SDKs verursacht werden. 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 über 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.
Hier finden Sie eine 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 versuchen, den Prompt / Kontext so einzigartig wie möglich zu gestalten und eine höhere Temperatur zu 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 eine Anleitung 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. |
|
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.
|
|
| 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. |
|
| 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. |
|
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.
Wenn Sie Hunderte von Beispielen für gute Eingabe-/Ausgabe-Paare haben, können Sie auch Modellabstimmung in Betracht ziehen.
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.