Skorzystaj z tego przewodnika, aby diagnozować i rozwiązywać typowe problemy, które pojawiają się podczas wywoływania interfejsu Gemini API. Problemy mogą występować zarówno w usłudze backendu Gemini API, jak i w pakietach SDK klienta. Nasze pakiety SDK klienta są udostępnione na licencji open source w tych repozytoriach:
Jeśli napotkasz problemy z kluczem interfejsu API, sprawdź, czy został on prawidłowo skonfigurowany zgodnie z przewodnikiem konfiguracji klucza interfejsu API.
Kody błędów
Pełną listę wszystkich kodów błędów, w tym kodów stanu HTTP, kodów blokowania generowania i kodów 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ć próbę (np. 429 RESOURCE_EXHAUSTED lub 503 UNAVAILABLE), zalecamy wdrożenie strategii wzrastającego czasu do ponowienia. Oznacza to, że przed pierwszą próbą odczekasz chwilę, a potem stopniowo zwiększysz czas oczekiwania między kolejnymi próbami.
Oficjalne pakiety SDK klienta interfejsu Gemini API, takie jak pakiet SDK w Pythonie, domyślnie zawierają logikę automatycznego ponawiania z wzrastającym czasem do ponowienia, która obsługuje przejściowe błędy, takie jak przekroczenie limitu czasu, problemy z siecią i ograniczanie liczby żądań (kody stanu 429 i 5xx). Na przykład pakiet SDK w Pythonie automatycznie ponawia próby w przypadku błędów przejściowych do 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 REST lub dostosowujesz logikę ponawiania, postępuj zgodnie z tymi sprawdzonymi metodami, aby zwiększyć prawdopodobieństwo powodzenia żądania i zapobiec przeciążeniu usługi:
- Użyj wzrastającego czasu do ponowienia: odczekaj krótki czas przed pierwszą próbą ponowienia (np. 1 sekundę), a potem 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óby przez wszystkich klientów w tym samym czasie.
- Ponawianie w przypadku określonych błędów: ponawiaj tylko w przypadku błędów przejściowych (np.
429,408lub5xx). Nie ponawiaj w przypadku błędów klienta (np.400,402lub403), ponieważ wskazują one problemy takie jak nieprawidłowe klucze interfejsu API, wyczerpane środki przedpłacone 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 wartości:
| Parametr modelu | Wartości (zakres) |
| Liczba kandydatów | 1–8 (liczba całkowita) |
| Temperatura | 0,0–1,0 |
| Maksymalna liczba tokenów wyjściowych | Na stronie modeli możesz sprawdzić maksymalną liczbę tokenów dla używanego modelu. |
| 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) i 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.
Sprawdź, czy masz odpowiedni model
Sprawdź, czy używasz obsługiwanego modelu wymienionego na naszej stronie z modelami.
Większe opóźnienie lub zużycie tokenów w przypadku modeli myślenia
Wyższe opóźnienia lub zużycie tokenów często występują, ponieważ modele Gemini 3.x mają domyślnie włączoną funkcję myślenia. Wycofane modele Gemini 2.5 również korzystają z domyślnego sposobu myślenia.
Modele myślowe generują wewnętrzne tokeny rozumowania, aby poprawić jakość. Ten proces rozumowania zwiększa zarówno czas oczekiwania na odpowiedź, jak i całkowite zużycie tokenów.
Jeśli priorytetem jest mniejsze opóźnienie lub chcesz zminimalizować koszty, możesz obniżyć poziom myślenia lub wyłączyć myślenie.
Szczegółowe informacje o konfiguracji i przykłady kodu znajdziesz w przewodniku.
Problemy z bezpieczeństwem
Jeśli zobaczysz, że prompt został zablokowany z powodu ustawienia bezpieczeństwa w wywołaniu interfejsu API, sprawdź go pod kątem filtrów ustawionych w tym wywołaniu.
Jeśli zobaczysz 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 zobaczysz, że model przestaje generować dane wyjściowe z powodu RECITATION, oznacza to, że dane wyjściowe modelu mogą przypominać określone dane. Aby to naprawić, spróbuj jak najbardziej urozmaicić prompt lub kontekst i użyj wyższej temperatury.
Problem z powtarzającymi się tokenami
Jeśli widzisz powtarzające się tokeny wyjściowe, wypróbuj te sugestie, aby je ograniczyć lub wyeliminować.
| Opis | Przyczyna | Sugerowane obejście |
|---|---|---|
| Powtórzone łą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 Markdownie nie jest jednak konieczne do prawidłowego renderowania. |
Dodaj instrukcje w prompcie, aby podać modelowi konkretne wytyczne dotyczące generowania tabel Markdown. Podaj przykłady zgodne z tymi wytycznymi. Możesz też spróbować dostosować temperaturę. W przypadku generowania kodu lub bardzo uporządkowanych danych wyjściowych, takich jak tabele Markdown, lepiej sprawdzają się wysokie wartości temperatury (≥ 0,8). Oto przykładowy zestaw wytycznych, które możesz dodać do 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 wymagane do prawidłowego renderowania. |
|
Powtórzone znaki nowego wiersza (\n) w uporządkowanych danych wyjściowych
|
Jeśli 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 przypadku korzystania z uporządkowanych danych wyjściowych | Jeśli kolejność pól w danych wyjściowych modelu jest inna niż w zdefiniowanym schemacie strukturalnym, może to prowadzić do powtarzania się tekstu. |
|
| Powtarzające się wywołania narzędzi | Może się tak zdarzyć, jeśli model utraci kontekst poprzednich przemyśleń lub wywoła niedostępny punkt końcowy, do którego jest zmuszony. |
Poinstruuj model, aby zachowywał stan w procesie myślowym.
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ą uporządkowanych danych wyjściowych | Może się tak zdarzyć, jeśli model utknie na żądaniu, którego nie może rozwiązać. |
|
Zablokowane lub niedziałające klucze interfejsu API
Z tej sekcji dowiesz się, jak sprawdzić, czy Twój klucz interfejsu Gemini API jest zablokowany, i co w takiej sytuacji zrobić.
Dlaczego klucze są blokowane
Wykryliśmy lukę w zabezpieczeniach, w wyniku której niektóre klucze interfejsu API mogły zostać publicznie ujawnione. Aby chronić Twoje dane i zapobiegać nieautoryzowanemu dostępowi, aktywnie blokujemy dostęp do interfejsu Gemini API za pomocą tych znanych, ujawnionych kluczy.
Sprawdź, czy zmiana dotyczy Twoich kluczy
Jeśli Twój klucz został ujawniony, nie możesz już używać go w interfejsie Gemini API. W Google AI Studio możesz sprawdzić, czy któryś z Twoich kluczy API jest zablokowany i nie może wywoływać Gemini API, a także 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
Nowe klucze interfejsu API do integracji z Gemini API należy generować za pomocą Google AI Studio. Zdecydowanie zalecamy sprawdzenie metod zarządzania kluczami interfejsu API, aby upewnić się, że nowe klucze są bezpieczne i nie są publicznie udostępniane.
Nieoczekiwane opłaty z powodu luki 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 poinformujemy Cię o postępach.
Środki bezpieczeństwa Google w przypadku wycieku kluczy
Jak Google pomoże mi zabezpieczyć konto przed przekroczeniem kosztów i nadużyciami, jeśli moje klucze interfejsu API wyciekną?
- W przypadku prośby o nowy klucz w Google AI Studio będziemy wydawać klucze API, które domyślnie będą ograniczone tylko do Google AI Studio i nie będą akceptować kluczy z innych usług. Pomoże to zapobiec niezamierzonemu użyciu kluczy.
- Domyślnie blokujemy klucze interfejsu API, które wyciekły i są używane z interfejsem 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. Jeśli wykryjemy, że Twoje klucze interfejsu API zostały ujawnione, będziemy Cię o tym informować, aby umożliwić Ci podjęcie natychmiastowych działań.
Ulepszanie danych wyjściowych modelu
Aby uzyskać wyższą jakość wyników modelu, spróbuj pisać bardziej ustrukturyzowane prompty. Na stronie Przewodnik po inżynierii promptów znajdziesz podstawowe koncepcje, strategie i sprawdzone metody, które pomogą Ci zacząć.
Limity tokenów
Aby dowiedzieć się więcej o tym, jak liczyć tokeny i jakie są ich limity, przeczytaj nasz przewodnik po tokenach.
Znane problemy
- Interfejs API obsługuje tylko wybrane języki. Przesyłanie promptów w nieobsługiwanych językach może skutkować nieoczekiwanymi lub nawet zablokowanymi odpowiedziami. Aktualne informacje o dostępnych językach znajdziesz na tej stronie.
Zgłoś błąd
Jeśli masz pytania, dołącz do dyskusji na forum dla deweloperów Google AI.