Skorzystaj z tego przewodnika, aby diagnozować i rozwiązywać 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 na licencji open source 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 Python SDK, 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 Python SDK 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 API (typu) REST 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 losowe opóźnienie: dodaj losowe opóźnienie, 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 jak400,402lub403), ponieważ wskazują one na problemy takie jak nieprawidłowe klucze interfejsu API, wyczerpanie środków przedpłaconych 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 wartościach:
| 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, skorzystaj ze strony Modele. |
| 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 /v1beta interfejsu API.
Sprawdzanie, czy używasz odpowiedniego modelu
Sprawdź, czy używasz obsługiwanego modelu wymienionego na naszej stronie Modele.
Większe opóźnienie lub zużycie tokenów w przypadku modeli myślących
Większe opóźnienie lub zużycie tokenów często występuje, ponieważ modele Gemini 3.x mają domyślnie włączone myślenie. Modele Gemini 2.5, które nie są już obsługiwane, również korzystają z domyślnego myślenia.
Modele myślące generują wewnętrzne tokeny rozumowania, aby poprawić jakość. Ten proces rozumowania zwiększa zarówno opóźnienie odpowiedzi, jak i całkowite zużycie tokenów.
Jeśli priorytetem jest mniejsze opóźnienie lub musisz zminimalizować koszty, możesz obniżyć poziom myślenia lub wyłączyć myślenie.
Szczegóły konfiguracji i przykłady kodu znajdziesz w przewodniku po myśleniu.
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 nie być obsługiwane z innych powodów.
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 sprawić, 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ę to 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.
|
|
| Powtarzający się tekst w ustrukturyzowanych danych wyjściowych | Gdy dane wyjściowe modelu mają inną kolejność pól niż zdefiniowany schemat ustrukturyzowany, może to prowadzić do powtarzania się tekstu. |
|
| Powtarzające się wywoływanie narzędzia | Może się to zdarzyć, jeśli model utraci kontekst poprzednich myśli lub wywoła niedostępny punkt końcowy, do którego jest zmuszony. |
Poinformuj model, aby zachowywał stan w procesie myślenia.
Dodaj ten tekst na końcu instrukcji systemowych:
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.
|
| Powtarzający się tekst, który nie jest częścią ustrukturyzowanych danych wyjściowych | Może się to zdarzyć, jeśli model utknie na żądaniu, którego nie może rozwiązać. |
|
Zablokowane lub niedziałające klucze interfejsu API
W tej sekcji opisujemy, jak sprawdzić, czy klucz Gemini API jest zablokowany, i co z tym zrobić.
Przyczyny blokowania kluczy
Zidentyfikowaliśmy lukę w zabezpieczeniach, która mogła spowodować publiczne ujawnienie niektórych kluczy interfejsu API. Aby chronić Twoje dane i zapobiegać nieautoryzowanemu dostępowi, proaktywnie zablokowaliśmy te znane ujawnione klucze przed dostępem do Gemini API.
Sprawdzanie, czy Twoje klucze są objęte problemem
Jeśli Twój klucz został ujawniony, nie możesz go już używać z Gemini API. W Google AI Studio możesz sprawdzić, czy któryś z Twoich kluczy interfejsu API jest zablokowany przed wywoływaniem Gemini API, i wygenerować nowe klucze. Podczas próby użycia tych kluczy może też pojawić się ten błąd:
Your API key was reported as leaked. Please use another API key.
Działania w przypadku zablokowanych kluczy interfejsu API
W Google AI Studio wygeneruj nowe klucze interfejsu API na potrzeby integracji z Gemini API. Zdecydowanie zalecamy sprawdzenie swoich praktyk zarządzania kluczami interfejsu API, aby mieć pewność, że nowe klucze są bezpieczne i nie są publicznie ujawnione.
Nieoczekiwane opłaty spowodowane luką w zabezpieczeniach
Prześlij zgłoszenie do zespołu pomocy ds. płatności. Nasz zespół ds. płatności pracuje nad tym problemem i jak najszybciej poinformuje Cię o postępach.
Środki bezpieczeństwa Google w przypadku ujawnionych kluczy
Jak Google pomoże zabezpieczyć moje konto przed przekroczeniem kosztów i nadużyciami, jeśli moje klucze interfejsu API zostaną ujawnione?
- Wprowadzamy zmiany, które spowodują, że klucze interfejsu API będą wydawane tylko wtedy, gdy poprosisz o nowy klucz w Google AI Studio. Domyślnie będą one ograniczone tylko do Google AI Studio i nie będą akceptować kluczy z innych usług. Pomoże to zapobiec przypadkowemu użyciu klucza w niewłaściwym miejscu.
- Domyślnie blokujemy klucze interfejsu API, które zostały ujawnione i są używane z Gemini API, co pomaga zapobiegać nadużyciom związanym z kosztami i danymi aplikacji.
- Stan kluczy interfejsu API możesz sprawdzić w Google AI Studio. Będziemy też proaktywnie informować Cię, gdy wykryjemy, że Twoje klucze interfejsu API zostały ujawnione, aby umożliwić Ci podjęcie natychmiastowych działań.
Poprawianie danych wyjściowych modelu
Aby uzyskać dane wyjściowe modelu o wyższej jakości, spróbuj pisać bardziej ustrukturyzowane prompty. Na stronie Przewodnik po inżynierii promptów znajdziesz podstawowe pojęcia, strategie i sprawdzone metody, które pomogą Ci zacząć.
Limity tokenów
Przeczytaj nasz przewodnik po tokenach, aby dowiedzieć się, jak liczyć tokeny i jakie są ich limity.
Znane problemy
- Interfejs API obsługuje tylko wybrane języki. Przesyłanie promptów w nieobsługiwanych językach może spowodować nieoczekiwane lub nawet zablokowane odpowiedzi. Aktualne informacje znajdziesz w sekcji Dostępne języki for updates.
Zgłoś błąd
Jeśli masz pytania, dołącz do dyskusji na forum dla deweloperów AI od Google.