Skorzystaj z tego przewodnika, aby zdiagnozować i rozwiązać typowe problemy, które mogą wystąpić podczas wywoływania interfejsu Gemini API. Problemy mogą występować zarówno w usłudze backendowej Gemini API, jak i w pakietach SDK klienta. Nasze pakiety SDK klienta są dostępne w tych repozytoriach:
Jeśli masz problemy z kluczem interfejsu API, sprawdź, czy został on prawidłowo skonfigurowany zgodnie z przewodnikiem konfiguracji klucza interfejsu API.
Kody błędów
Pełne informacje o wszystkich kodach błędów, w tym o kodach stanu HTTP, kodach zablokowania generowania i kodach błędów treści, znajdziesz na stronie Błędy interfejsu API.
Strategia ponawiania
Jeśli otrzymasz błąd wskazujący, że należy ponowić żądanie (np. 429 RESOURCE_EXHAUSTED lub 503 UNAVAILABLE), zalecamy wdrożenie strategii wzrastającego czasu do ponowienia. Oznacza to, że przed pierwszą próbą ponowienia czekasz krótko, a następnie stopniowo zwiększasz czas oczekiwania między kolejnymi próbami.
Oficjalne pakiety SDK klienta dla Gemini API, takie jak pakiet SDK Pythona, domyślnie zawierają logikę automatycznego ponawiania z wzrastającym czasem do ponowienia w celu obsługi błędów przejściowych, takich jak przekroczenie limitu czasu, problemy z siecią i ograniczanie liczby żądań (429 i 5xx kody stanu). Na przykład pakiet SDK Pythona automatycznie ponawia próby w przypadku błędów przejściowych maksymalnie 4 razy z początkowym opóźnieniem wynoszącym około 1 sekundy i maksymalnym opóźnieniem wynoszącym 60 sekund.
Jeśli wysyłasz bezpośrednie żądania do interfejsu REST API lub dostosowujesz logikę ponawiania, postępuj zgodnie z tymi sprawdzonymi metodami, aby zwiększyć prawdopodobieństwo pomyślnego wysłania żądania i zapobiec przeciążeniu usługi:
- Używaj wzrastającego czasu do ponowienia: przed pierwszą próbą ponowienia poczekaj krótko (np. 1 sekundę), a następnie zwiększaj opóźnienie wykładniczo (np. 2 s, 4 s, 8 s).
- Dodaj jitter: dodaj losowy „jitter” do opóźnienia, aby zapobiec ponawianiu prób przez wszystkich klientów w tym samym czasie.
- Ponawiaj próby w przypadku określonych błędów: ponawiaj próby tylko w przypadku błędów przejściowych (takich jak
429,408lub5xx). Nie ponawiaj prób w przypadku błędów klienta (takich jak400lub403), ponieważ wskazują one na problemy takie jak nieprawidłowe klucze interfejsu API lub nieprawidłowa składnia. - Ustaw maksymalną liczbę ponownych prób: określ maksymalną liczbę ponownych prób, aby zapobiec nieskończonym pętlom.
Sprawdzanie wywołań interfejsu API pod kątem błędów parametrów modelu
Sprawdź, czy parametry modelu mieszczą się w tych zakresach:
| Parametr modelu | Wartości (zakres) |
| Liczba kandydatów | 1–8 (liczba całkowita) |
| Temperatura | 0,0–1,0 |
| Maksymalna liczba tokenów wyjściowych | Aby określić maksymalną liczbę tokenów dla używanego modelu, otwórz stronę modeli. |
| TopP | 0,0–1,0 |
Oprócz sprawdzania wartości parametrów upewnij się, że używasz prawidłowej
wersji interfejsu API (np. /v1 lub /v1beta) oraz
modelu, który obsługuje potrzebne Ci funkcje. Jeśli na przykład funkcja jest w wersji beta, będzie dostępna tylko w wersji interfejsu API /v1beta.
Sprawdzanie, czy używasz odpowiedniego modelu
Sprawdź, czy używasz obsługiwanego modelu wymienionego na naszej stronie modeli.
Większe opóźnienie lub wykorzystanie tokenów w przypadku modeli 2.5
Jeśli zauważysz większe opóźnienie lub wykorzystanie tokenów w przypadku modeli 2.5 Flash i Pro, może to być spowodowane tym, że domyślnie mają one włączone myślenie , aby poprawić jakość. Jeśli priorytetem jest dla Ciebie szybkość lub musisz zminimalizować koszty, możesz dostosować lub wyłączyć myślenie.
Wskazówki i przykładowy kod znajdziesz na stronie dotyczącej myślenia.
Problemy związane z bezpieczeństwem
Jeśli widzisz, że prompt został zablokowany z powodu ustawienia bezpieczeństwa w wywołaniu interfejsu API, sprawdź prompt pod kątem filtrów ustawionych w wywołaniu interfejsu API.
Jeśli widzisz BlockedReason.OTHER, zapytanie lub odpowiedź mogą naruszać warunki
korzystania z usługi lub być w inny sposób nieobsługiwane.
Problem z recytacją
Jeśli widzisz, że model przestaje generować dane wyjściowe z powodu RECITATION, oznacza to, że dane wyjściowe modelu mogą przypominać określone dane. Aby rozwiązać ten problem, spróbuj, aby prompt lub kontekst były jak najbardziej unikalne, i użyj wyższej temperatury.
Problem z powtarzającymi się tokenami
Jeśli widzisz powtarzające się tokeny wyjściowe, spróbuj zastosować te sugestie, aby je ograniczyć lub wyeliminować.
| Opis | Przyczyna | Sugerowane obejście |
|---|---|---|
| Powtarzające się łączniki w tabelach Markdown | Może się tak zdarzyć, gdy zawartość tabeli jest długa, ponieważ model próbuje utworzyć wizualnie wyrównaną tabelę Markdown. Wyrównanie w Markdown nie jest jednak konieczne do prawidłowego renderowania. |
Dodaj do prompta instrukcje, aby podać modelowi konkretne wytyczne dla generowania tabel Markdown. Podaj przykłady zgodne z tymi wytycznymi. Możesz też spróbować dostosować temperaturę. W przypadku generowania kodu lub bardzo ustrukturyzowanych danych wyjściowych, takich jak tabele Markdown, lepiej sprawdzają się wysokie temperatury (>= 0,8). Oto przykładowy zestaw wytycznych, które możesz dodać do swojego prompta, aby zapobiec temu problemowi:
# 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.
|
| Powtarzające się tokeny w tabelach Markdown | Podobnie jak w przypadku powtarzających się łączników, dzieje się tak, gdy model próbuje wizualnie wyrównać zawartość tabeli. Wyrównanie w Markdown nie jest nie jest wymagane do prawidłowego renderowania. |
|
Powtarzające się znaki nowego wiersza (\n) w ustrukturyzowanych danych wyjściowych
|
Gdy dane wejściowe modelu zawierają znaki Unicode lub sekwencje ucieczki, takie jak
\u lub \t, może to prowadzić do powtarzających się znaków nowego wiersza.
|
|