Utilizza questa guida per diagnosticare e risolvere i problemi più comuni che si verificano quando che chiamiamo l'API Gemini. A livello generale, potresti riscontrare problemi il servizio di backend dell'API Gemini o gli SDK client. Gli SDK dei nostri client sono open source nei seguenti repository:
- generative-ai-python
- generative-ai-js
- generative-ai-android
- generative-ai-swift
- generative-ai-dart
- generative-ai-go
Se riscontri problemi relativi alle chiavi API, assicurati di aver configurato la tua chiave API correttamente in base alla guida alla configurazione della chiave API.
Codici di errore del servizio di backend dell'API Gemini
La tabella seguente elenca i codici di errore comuni del backend che potresti riscontrare, insieme con spiegazioni delle cause e procedure per la risoluzione dei problemi:
| Codice HTTP | Stato | Descrizione | Esempio | Soluzione |
| 400 | INVALID_ARGUMENT | Il corpo della richiesta non è valido. | La tua richiesta contiene un errore di battitura o un campo obbligatorio mancante. | Controlla il riferimento API per il formato della richiesta, gli esempi e le versioni supportate. L'utilizzo di funzionalità di una versione più recente dell'API con un endpoint meno recente può causare errori. |
| 400 | FAILED_PRECONDITION | Il Livello senza costi dell'API Gemini non è disponibile nel tuo paese. Abilita la fatturazione per il tuo progetto in Google AI Studio. | Stai effettuando una richiesta in una regione in cui il livello senza costi non è supportato e non hai abilitato la fatturazione per il tuo progetto in Google AI Studio. | Per utilizzare l'API Gemini, devi configurare un piano a pagamento utilizzando Google AI Studio. |
| 403 | PERMISSION_DENIED | La tua chiave API non dispone delle autorizzazioni necessarie. | Stai utilizzando la chiave API sbagliata. tu stai tentando di utilizzare un modello ottimizzato senza seguire un'autenticazione corretta. | Verifica che la chiave API sia impostata e che disponga dell'accesso corretto. Inoltre, assicurati di seguire la procedura di autenticazione adeguata per utilizzare i modelli ottimizzati. |
| 404 | NOT_FOUND | Impossibile trovare la risorsa richiesta. | Impossibile trovare un file immagine, audio o video a cui viene fatto riferimento nella tua richiesta. | Controlla se tutti i parametri nella tua richiesta sono validi per la tua versione API. |
| 429 | RESOURCE_EXHAUSTED | Hai superato il limite di frequenza. | Stai inviando troppe richieste al minuto con l'API Gemini del livello senza costi. | Assicurati di rientrare nel limite di frequenza del modello. Se necessario, richiedi un aumento della quota. |
| 500 | INTERNAL | Si è verificato un errore imprevisto da parte di Google. | Il contesto di input è troppo lungo. | Riduci il contesto di input o passa temporaneamente a un altro modello (ad es. da Gemini 1.5 Pro a Gemini 1.5 Flash) e controlla se funziona. In alternativa, attendi qualche istante e riprova a effettuare la richiesta. Se il problema persiste dopo aver riprovato, segnalalo utilizzando il pulsante Invia feedback in Google AI Studio. |
| 503 | UNAVAILABLE | Il servizio potrebbe essere temporaneamente sovraccarico o non disponibile. | Il servizio sta temporaneamente esaurendo la capacità. | Passa temporaneamente a un altro modello (ad es. da Gemini 1.5 Pro a Gemini 1.5 Flash) e controlla se funziona. In alternativa, attendi qualche istante e riprova a effettuare la richiesta. Se il problema persiste dopo aver riprovato, segnalalo utilizzando il pulsante Invia feedback in Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | Il servizio non è in grado di completare l'elaborazione entro la scadenza. | Il prompt (o il contesto) è troppo grande per essere elaborato in tempo. | Imposta un "timeout" più lungo nella richiesta del client per evitare questo errore. |
Codici di errore dell'SDK del client Python
Nella tabella seguente sono elencati i comuni Errore dell'SDK client Python codici che potresti incontrare, insieme alle relative cause:
| Tipo di eccezione/errore | Classe | Descrizione |
|---|---|---|
| BlockedPromptException | google.generativeai.types.BlockedPromptException | La richiesta è bloccata per motivi di sicurezza. |
| BrokenResponseError | google.generativeai.types.BrokenResponseError | Una risposta in modalità flusso non funziona. Segnalato quando si accede a qualcosa che richiede una risposta completa, ad esempio la cronologia chat. Visualizza i dettagli dell'errore forniti nell'analisi dello stack. |
| IncompleteIterationError | google.generativeai.types.IncompleteIterationError | Rilevata quando si accede a qualcosa che richiede una risposta API completa, ma una risposta in modalità flusso non è stata completamente iterata. Richiama resolve() sull'oggetto di risposta per utilizzare l'iteratore. |
| StopCandidateException | google.generativeai.types.StopCandidateException | L'API ha risposto con un finish_reason eccezionale. Controlla il motivo dei consigli su come procedere. |
| PermissionDenied | google.api_core.exceptions.PermissionDenied | Non hai l'autorizzazione per la risorsa richiesta (ad es. modello). |
| ResourceExhausted | google.api_core.exceptions.ResourceExhausted | La tua quota è esaurita. Riprova tra un istante. Valuta la possibilità di configurare nuovi tentativi automatici per gestire questi errori. |
| AlreadyExists | google.api_core.exceptions.AlreadyExists | Esiste già un modello ottimizzato con lo stesso ID. Specifica un ID modello univoco durante l'ottimizzazione di un nuovo modello. |
| InvalidArgument | google.api_core.exceptions.InvalidArgument | Argomento non valido. Ad esempio, il file è troppo grande e supera il limite di dimensioni del payload. Un altro sta fornendo una chiave API non valida. |
| DefaultCredentialsError | google.auth.exceptions.DefaultCredentialsError | L'autenticazione non riesce. Controlla la chiave API e riprova. |
| RetryError | google.api_core.exceptions.RetryError | Può verificarsi quando si utilizza un proxy che non supporta gRPC. Prova a utilizzare il trasporto REST con genai.configure(..., transport="rest"). |
Verifica la presenza di errori nei parametri del modello nelle chiamate API
Assicurati che i parametri del modello rientrino nei seguenti valori:
| Parametro modello | Valori (intervallo) |
| Numero di candidati | 1-8 (numero intero) |
| Temperatura | 0,0-1,0 |
| Numero massimo di token di output |
Utilizza le funzionalità di
get_model (Python)
per determinare il numero massimo di token per il modello che stai utilizzando.
|
| TopP | 0,0-1,0 |
Oltre a controllare i valori dei parametri, assicurati di utilizzare i valori corretti
Versione API (ad es. /v1 o /v1beta) e
che supporti le caratteristiche di cui hai bisogno. Ad esempio, se una funzionalità è in versione beta
, sarà disponibile solo nella versione API /v1beta.
Verifica di avere il modello giusto
Assicurati di utilizzare uno dei modelli supportati elencati nel nostro pagina Modelli.
Problemi di sicurezza
Se vedi che una richiesta è stata bloccata a causa di un'impostazione di sicurezza nella chiamata API, esaminare il prompt in base ai filtri impostati nella chiamata API.
Se visualizzi BlockedReason.OTHER, la query o la risposta potrebbe violare i termini
di servizio o non essere supportati in altro modo.
Problema relativo alla citazione
Se vedi che il modello smette di generare output a causa del motivo RECITATION, questo significa che l'output del modello potrebbe assomigliare a determinati dati. Per risolvere il problema, prova a il prompt / il contesto più univoci possibile e usare una temperatura più alta.
Migliora l'output del modello
Per ottenere output del modello di qualità superiore, esplora la scrittura di prompt più strutturati. La la pagina introduzione alla progettazione dei prompt introduce alcuni concetti di base, strategie e best practice per iniziare.
Se hai centinaia di esempi di buone coppie input/output, puoi anche prendi in considerazione l'ottimizzazione del modello.
Informazioni sui limiti dei token
Leggi la nostra guida ai token per comprendere meglio come per contare i token e i relativi limiti.
Problemi noti
- L'API supporta solo un certo numero di lingue selezionate. Invio di prompt in lingue non supportate possono produrre risposte impreviste o persino bloccate. Consulta: lingue disponibili per gli aggiornamenti.
Segnala un bug
Partecipa alla discussione nel forum degli sviluppatori di IA di Google se avete domande.