Guida alla risoluzione dei problemi

Utilizza questa guida per diagnosticare e risolvere i problemi comuni che si verificano quando chiami l'API Gemini. Potresti riscontrare problemi con il servizio di backend dell'API Gemini o con gli SDK client. I nostri SDK client sono open source nei seguenti repository:

Se riscontri problemi con la chiave API, verifica di averla configurata correttamente seguendo la guida alla configurazione della chiave API.

Codici di errore del servizio di backend dell'API Gemini

La tabella seguente elenca i codici di errore backend comuni che potresti riscontrare, insieme alle spiegazioni delle cause e ai passaggi per la risoluzione dei problemi:

Codice HTTP Stato Descrizione Esempio Soluzione
400 INVALID_ARGUMENT Il corpo della richiesta non è valido. Nella tua richiesta è presente un errore di battitura o manca un campo obbligatorio. Consulta il riferimento API per il formato della richiesta, gli esempi e le versioni supportate. L'utilizzo di funzionalità di una versione dell'API più recente con un endpoint precedente può causare errori.
400 FAILED_PRECONDITION Il livello senza costi dell'API Gemini non è disponibile nel tuo paese. Attiva 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 attivato 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 errata; stai tentando di utilizzare un modello ottimizzato senza eseguire l'autenticazione corretta. Verifica che la chiave API sia impostata e disponga dell'accesso corretto. Inoltre, assicurati di eseguire l'autenticazione corretta per utilizzare i modelli ottimizzati.
404 NOT_FOUND La risorsa richiesta non è stata trovata. Non è stato trovato un file immagine, audio o video a cui viene fatto riferimento nella tua richiesta. Verifica che tutti i parametri della richiesta siano validi per la tua versione dell'API.
429 RESOURCE_EXHAUSTED Hai superato il limite di frequenza. Stai inviando troppe richieste al minuto con l'API Gemini di livello senza costi. Verifica di rientrare nel limite di frequenza del modello. Se necessario, richiedi un aumento della quota.
500 PUBBLICO INTERNO Si è verificato un errore imprevisto da parte di Google. Il contesto dell'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 verifica se funziona. In alternativa, attendi un po' e riprova a inviare 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 verifica se funziona. In alternativa, attendi un po' e riprova a inviare 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.

Controlla le chiamate API per errori nei parametri del modello

Verifica che i parametri del modello rientrino nei seguenti valori:

Parametro del modello Valori (intervallo)
Numero di candidati 1-8 (numero intero)
Temperatura 0.0-1.0
Numero massimo di token di output Utilizza 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 la versione dell'API corretta (ad es. /v1 o /v1beta) e un modello che supporti le funzionalità di cui hai bisogno. Ad esempio, se una funzionalità è in versione beta, sarà disponibile solo nella versione /v1beta dell'API.

Controllare di avere il modello giusto

Verifica di utilizzare un modello supportato elencato nella nostra pagina dei modelli.

Latenza o utilizzo di token più elevati con i modelli 2.5

Se osservi una latenza o un utilizzo di token più elevati con i modelli 2.5 Flash e Pro, ciò può essere dovuto al fatto che la funzione di pensiero è attivata per impostazione predefinita per migliorare la qualità. Se dai la priorità alla velocità o devi ridurre al minimo i costi, puoi regolare o disattivare la funzionalità di pensiero.

Consulta la pagina di approfondimento per indicazioni e codice di esempio.

Problemi di sicurezza

Se vedi che un prompt è stato bloccato a causa di un'impostazione di sicurezza nella chiamata API, esamina il prompt rispetto ai filtri impostati nella chiamata API.

Se visualizzi BlockedReason.OTHER, la query o la risposta potrebbe violare i termini di servizio o non essere supportata.

Problema di recitazione

Se vedi che il modello smette di generare output a causa del motivo RECITATION, significa che l'output del modello potrebbe assomigliare a determinati dati. Per risolvere il problema, prova a rendere il prompt / il contesto il più unico possibile e utilizza una temperatura più elevata.

Problema con i token ripetitivi

Se visualizzi token di output ripetuti, prova i seguenti suggerimenti per ridurli o eliminarli.

Descrizione Causa Soluzione alternativa suggerita
Trattini ripetuti nelle tabelle Markdown Ciò può verificarsi quando i contenuti della tabella sono lunghi, poiché il modello tenta di creare una tabella Markdown allineata visivamente. Tuttavia, l'allineamento in Markdown non è necessario per il rendering corretto.

Aggiungi istruzioni nel prompt per fornire al modello linee guida specifiche per la generazione di tabelle Markdown. Fornisci esempi che seguano queste linee guida. Puoi anche provare a regolare la temperatura. Per generare codice o output molto strutturato come tabelle Markdown, è stato dimostrato che una temperatura elevata funziona meglio (>= 0,8).

Di seguito è riportato un esempio di linee guida che puoi aggiungere al prompt per evitare questo problema: 

          # 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.
Token ripetuti nelle tabelle Markdown Come per i trattini ripetuti, ciò si verifica quando il modello tenta di allineare visivamente i contenuti della tabella. L'allineamento in Markdown non è obbligatorio per il rendering corretto.
  • Prova ad aggiungere istruzioni come le seguenti al prompt di sistema: 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Prova a regolare la temperatura. Temperature più alte (>= 0,8) generalmente aiutano a eliminare ripetizioni o duplicazioni nell'output.
Nuove righe ripetute (\n) nell'output strutturato Quando l'input del modello contiene sequenze di escape o Unicode come \u o \t, possono verificarsi interruzioni di riga ripetute.
  • Controlla e sostituisci le sequenze di escape vietate con caratteri UTF-8 nel prompt. Ad esempio, la sequenza di escape \u negli esempi JSON può indurre il modello a utilizzarla anche nel suo output.
  • Istruisci il modello sugli escape consentiti. Aggiungi un'istruzione di sistema come questa: 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Testo ripetuto nell'utilizzo dell'output strutturato Quando l'output del modello ha un ordine diverso per i campi rispetto allo schema strutturato definito, ciò può comportare la ripetizione del testo.
  • Non specificare l'ordine dei campi nel prompt.
  • Rendi obbligatori tutti i campi di output.
Chiamate ripetitive Ciò può verificarsi se il modello perde il contesto dei pensieri precedenti e/o chiama un endpoint non disponibile a cui è costretto. Chiedi al modello di mantenere lo stato durante il processo di pensiero. Aggiungi questo testo alla fine delle istruzioni di sistema: 
        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.
Testo ripetitivo che non fa parte dell'output strutturato Ciò può verificarsi se il modello si blocca su una richiesta che non riesce a risolvere.
  • Se la funzionalità di pensiero è attiva, evita di dare ordini espliciti su come affrontare un problema nelle istruzioni. Chiedi semplicemente l'output finale.
  • Prova una temperatura più alta >= 0,8.
  • Aggiungi istruzioni come "Sii conciso", "Non ripeterti" o "Fornisci la risposta una sola volta".

Migliorare l'output del modello

Per ottenere output del modello di qualità superiore, prova a scrivere prompt più strutturati. La pagina Guida al prompt engineering introduce alcuni concetti di base, strategie e best practice per iniziare.

Se hai centinaia di esempi di coppie input/output valide, puoi anche prendere in considerazione l'ottimizzazione del modello.

Informazioni sui limiti di token

Leggi la nostra guida ai token per capire meglio come contare i token e i relativi limiti.

Problemi noti

  • L'API supporta solo un numero limitato di lingue. L'invio di prompt in lingue non supportate può produrre risposte inaspettate o persino bloccate. Per gli aggiornamenti, consulta le lingue disponibili.

Segnala un bug

Partecipa alla discussione nel forum per sviluppatori di Google AI se hai domande.