Ten przewodnik pomoże Ci diagnozować i rozwiązywać typowe problemy, które pojawiają się podczas wywoływania interfejsu Gemini API. Możesz napotkać problemy z usługą backendu Gemini API lub pakietami SDK klienta. Nasze pakiety SDK klienta są dostępne jako open source w tych repozytoriach:
Jeśli masz problemy z kluczem interfejsu API, sprawdź, czy został on prawidłowo skonfigurowany zgodnie z przewodnikiem po 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ć żądanie (np. 429 RESOURCE_EXHAUSTED lub 503 UNAVAILABLE), zalecamy wdrożenie strategii wzrastającego czasu do ponowienia. Oznacza to, że przed pierwszą próbą odczekujesz krótko, a potem stopniowo wydłużasz czas oczekiwania między kolejnymi próbami.
Oficjalne pakiety SDK klienta dla interfejsu Gemini API, takie jak Python SDK, domyślnie zawierają logikę automatycznego ponawiania z wzrastającym czasem do ponowienia, która obsługuje błędy przejściowe, takie jak przekroczenie limitu czasu, problemy z siecią i ograniczanie liczby żądań (kody stanu 429 i 5xx). Na przykład pakiet SDK Pythona automatycznie ponawia próby w przypadku błędów przejściowych do 4 razy z początkowym opóźnieniem wynoszącym około 1 sekundę 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 powodzenia żądania i zapobiec przeciążeniu usługi:
- Użyj wzrastającego czasu do ponowienia: odczekaj chwilę przed pierwszą próbą (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 jak400,402lub403), ponieważ wskazują one na 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 wartościach:
| Parametr modelu | Wartości (zakres) |
| Liczba kandydatów | 1–8 (liczba całkowita, nieobsługiwana w Gemini 3 i 4) |
| Temperatura | 0,0–1,0 (ignorowane w Gemini 3.6+ i 4; zachowaj wartość domyślną we wcześniejszych modelach Gemini 3) |
| Maksymalna liczba tokenów wyjściowych | Aby określić maksymalną liczbę tokenów dla używanego modelu, skorzystaj ze strony modeli. |
| TopP | 0,0–1,0 (ignorowane w Gemini 3.6+ i 4; zachowaj wartość domyślną we wcześniejszych modelach Gemini 3) |
Oprócz sprawdzenia 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 funkcje. Jeśli na przykład funkcja jest w wersji beta, będzie dostępna tylko w wersji interfejsu API /v1beta.
Sprawdzanie, czy masz odpowiedni model
Sprawdź, czy używasz obsługiwanego modelu wymienionego na stronie z modelami.
Wyższe opóźnienie lub wykorzystanie tokenów w przypadku modeli myślących
Wyższe opóźnienie lub wykorzystanie tokenów często występuje, ponieważ modele Gemini 3.x mają domyślnie włączone myślenie. Wycofane modele Gemini 2.5 również domyślnie korzystają z myślenia.
Modele myślące generują wewnętrzne tokeny rozumowania, aby poprawić jakość. Ten proces rozumowania zwiększa zarówno czas oczekiwania na odpowiedź, jak i łączne wykorzystanie tokenów.
Jeśli priorytetem jest mniejszy czas oczekiwania lub chcesz zminimalizować koszty, możesz obniżyć poziom rozumowania lub je wyłączyć.
Szczegółowe informacje o konfiguracji i przykładowe kody znajdziesz w przewodniku po procesie myślowym.
Problemy z bezpieczeństwem
Jeśli zobaczysz, ż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ć nieobsługiwane z innych powodów.
Problem z recytacją
Jeśli zobaczysz, że model przestał generować dane wyjściowe z powodu RECYTACJI, oznacza to, że dane wyjściowe modelu mogą przypominać określone dane. Aby rozwiązać ten problem, postaraj się, aby prompt lub kontekst były jak najbardziej unikalne. W przypadku wcześniejszych modeli, które obsługują parametry próbkowania, możesz też użyć wyższej temperatury.
Problem z powtarzającymi się tokenami
Jeśli widzisz powtarzające się tokeny wyjściowe, wypróbuj poniższe sugestie, aby je ograniczyć lub wyeliminować. Dostosowanie temperatury dotyczy tylko wcześniejszych modeli, które obsługują parametry próbkowania. W przypadku modeli Gemini 3 i Gemini 4 użyj zamiast tego obejść związanych z promptami i instrukcjami systemowymi.
| Opis | Przyczyna | Sugerowane obejście problemu |
|---|---|---|
| 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. Jednak wyrównanie w Markdown nie jest konieczne do prawidłowego renderowania. |
Dodaj instrukcje w prompcie, aby przekazać modelowi konkretne wytyczne dotyczące generowania tabel Markdown. Podaj przykłady zgodne z tymi wytycznymi. W przypadku wcześniejszych modeli, które obsługują parametry próbkowania, możesz też spróbować dostosować temperaturę (>= 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 języku Markdown nie jest wymagane do prawidłowego renderowania. |
|
Powtarzające się znaki nowego wiersza (\n) w uporządkowanych danych wyjściowych
|
Gdy dane wejściowe modelu zawierają sekwencje unikodowe 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 uporządkowanych danych wyjściowych | Jeśli dane wyjściowe modelu mają inną kolejność pól niż zdefiniowany schemat uporządkowany, może to prowadzić do powtarzania tekstu. |
|
| Powtarzające się wywołania narzędzi | Może się tak zdarzyć, jeśli model utraci kontekst poprzednich myśli lub wywoła niedostępny punkt końcowy, do którego jest zmuszony. |
Poinstruuj model, aby zachował stan w procesie rozumowania.
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ć. |
|
Projekt jest ograniczony lub niedostępny
Jeśli żądania do interfejsu API zwracają błąd 403 PERMISSION_DENIED („Odmówiono dostępu do projektu”) lub stan projektu w Google AI Studio to Ograniczony, Poziom bezpłatny niedostępny, Wymagana płatność lub Niedostępny, sprawdź, która z poniższych sekcji dotyczy Twojego projektu:
Niedostępność bezpłatnego poziomu Gemini API
Nie wszystkie projekty w chmurze ani konta Google Cloud kwalifikują się do korzystania z poziomu bezpłatnego Gemini API. Jeśli Twój projekt nie może korzystać z poziomu bezpłatnego:
- Utworzenie nowego klucza interfejsu API w tym samym projekcie nie rozwiąże problemu. Google ocenia kwalifikowanie się na poziomie projektu Google Cloud.
- Aby używać interfejsu Gemini API w tym projekcie, musisz przejść na płatną wersję, łącząc aktywne konto rozliczeniowe Cloud.
- Uwaga: przejście na płatną wersję projektu nie odblokowuje limitu poziomu bezpłatnego. Google nalicza opłaty za korzystanie z płatnego poziomu zgodnie z cenami Gemini API lub odlicza je od kwalifikujących się środków Google Cloud.
Wymagana płatność na koncie rozliczeniowym Cloud
Jeśli Twój projekt jest już połączony z kontem rozliczeniowym Cloud i wyświetla się komunikat Wymagana płatność (lub zwracany jest błąd 403 PERMISSION_DENIED z informacją o zaległym saldzie):
- Aby uregulować zaległe saldo lub zaktualizować formę płatności, wejdź na stronę płatności w AI Studio lub otwórz konsolę Rozliczeń usługi Google Cloud.
- Gdy konto rozliczeniowe odzyska dobry stan, projekt automatycznie odzyska dostęp do interfejsu API.
Ujawnione lub zablokowane klucze interfejsu API
Jeśli stan błędu 403 PERMISSION_DENIED informuje, że klucz interfejsu API został zgłoszony jako ujawniony lub zablokowany:
- Otwórz stronę kluczy interfejsu API AI Studio, aby wygenerować nowy klucz interfejsu API i zaktualizować dane logowania aplikacji.
- Nigdy nie umieszczaj kluczy interfejsu API bezpośrednio w kodzie po stronie klienta ani w publicznych repozytoriach.
Zawieszenie projektu lub konta rozliczeniowego z powodu naruszenia zasad
Jeśli Google zawiesi Twój projekt w chmurze Google Cloud lub konto rozliczeniowe Cloud z powodu naruszenia zasad, sprawdź powiązany adres e-mail. Otwórz konsolę Google Cloud, aby sprawdzić powiadomienia o zawieszeniu, i postępuj zgodnie ze wskazówkami dotyczącymi zawieszenia projektu.
Zablokowane lub niedziałające klucze interfejsu API
W tej sekcji opisujemy, jak sprawdzić, czy klucz interfejsu Gemini API jest zablokowany, i co zrobić w takiej sytuacji.
Dlaczego klucze są blokowane
Wykryliśmy lukę w zabezpieczeniach, która mogła spowodować publiczne ujawnienie niektórych kluczy interfejsu API. Aby chronić Twoje dane i zapobiec nieautoryzowanemu dostępowi, proaktywnie zablokowaliśmy dostęp do interfejsu Gemini API za pomocą tych kluczy, które wyciekły.
Sprawdzanie, czy problem dotyczy Twoich kluczy
Jeśli wiadomo, że klucz został ujawniony, nie możesz go już używać z interfejsem Gemini API. Możesz użyć Google AI Studio, aby sprawdzić, czy któryś z Twoich kluczy interfejsu API jest zablokowany i nie może wywoływać interfejsu Gemini API, oraz 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łanie w przypadku zablokowanych kluczy interfejsu API
Nowe klucze interfejsu API do integracji z Gemini API należy wygenerować 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 dostępne.
Nieoczekiwane opłaty spowodowane luką w zabezpieczeniach
Prześlij zgłoszenie do zespołu pomocy ds. płatności Nasz zespół ds. rozliczeń pracuje nad tym problemem. Poinformujemy Cię, gdy tylko będziemy mieć nowe informacje.
Ś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ą?
- Przechodzimy na wydawanie kluczy interfejsu API, gdy poprosisz o nowy klucz za pomocą Google AI Studio. Będą one domyślnie ograniczone tylko do Google AI Studio i nie będą akceptować kluczy z innych usług. Pomoże to zapobiec niezamierzonemu użyciu klucza.
- Domyślnie blokujemy klucze interfejsu API, które wyciekły i są używane z interfejsem Gemini API, aby 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ć o wykryciu wycieku kluczy interfejsu API, aby umożliwić Ci natychmiastowe podjęcie działań.
Ulepszanie danych wyjściowych modelu
Aby uzyskać wyższą jakość danych wyjściowych modelu, 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
Aby dowiedzieć się więcej o liczeniu tokenów i ich limitach, zapoznaj się z naszym przewodnikiem po tokenach.
Znane problemy
- Interfejs API obsługuje tylko kilka wybranych języków. Przesyłanie promptów w nieobsługiwanych językach może skutkować nieoczekiwanymi lub nawet zablokowanymi odpowiedziami. Aktualne informacje znajdziesz na stronach z informacjami o modelach.
Zgłoś błąd
Jeśli masz pytania, dołącz do dyskusji na forum dla deweloperów AI od Google.