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:

• python-genai
• js-genai
• go-genai

Se riscontri problemi con la chiave API, verifica di aver configurato la tua chiave API 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 di backend comuni che potresti riscontrare, insieme alle spiegazioni delle cause e ai passaggi per la risoluzione dei problemi:

Controllare la presenza di errori nei parametri del modello nelle chiamate API

Verifica che i parametri del modello rientrino nei seguenti valori:

Oltre a controllare i valori dei parametri, assicurati di utilizzare la versione API corretta (ad es. /v1 o /v1beta) e il modello che supporta le funzionalità di cui hai bisogno. Ad esempio, se una funzionalità è in versione beta, sarà disponibile solo nella versione API /v1beta.

Verificare di avere il modello corretto

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

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

Se noti una latenza o un utilizzo dei token più elevati con i modelli 2.5 Flash e Pro, è possibile che sia perché la funzionalità di ragionamento è attivata per impostazione predefinita per migliorare la qualità. Se dai la priorità alla velocità o devi ridurre al minimo i costi, puoi modificare o disattivare la funzionalità di ragionamento.

Consulta la pagina relativa alla funzionalità di ragionamento per indicazioni e codice campione.

Problemi di sicurezza

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

Se vedi BlockedReason.OTHER, la query o la risposta potrebbero violare i Termini di servizio o non essere supportate.

Problema di citazione

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 / contesto il più univoco possibile e utilizza una temperatura più elevata.

Problema dei token ripetitivi

Se vedi token di output ripetuti, prova a seguire questi suggerimenti per ridurli o eliminarli.

          # 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.
        

        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.
      

Chiavi API bloccate o non funzionanti

Questa sezione descrive come verificare se la chiave API Gemini è bloccata e cosa fare in merito.

Comprendere perché le chiavi sono bloccate

Abbiamo identificato una vulnerabilità per cui alcune chiavi API potrebbero essere state esposte pubblicamente. Per proteggere i tuoi dati e impedire accessi non autorizzati, abbiamo bloccato in modo proattivo l'accesso all'API Gemini di queste chiavi di cui è stata accertata la compromissione.

Verificare se le chiavi sono interessate

Se è noto che la tua chiave è stata compromessa, non puoi più utilizzarla con l'API Gemini. Puoi utilizzare Google AI Studio per verificare se alcune delle tue chiavi API sono bloccate per le chiamate all'API Gemini e generare nuove chiavi. Quando tenti di utilizzare queste chiavi, potresti anche visualizzare il seguente errore:

Your API key was reported as leaked. Please use another API key.

Azioni per le chiavi API bloccate

Devi generare nuove chiavi API per le integrazioni dell'API Gemini utilizzando Google AI Studio. Ti consigliamo vivamente di esaminare le tue pratiche di gestione delle chiavi API per assicurarti che le nuove chiavi siano protette e non siano esposte pubblicamente.

Addebiti imprevisti a causa della vulnerabilità

Invia una richiesta di assistenza per la fatturazione. Il nostro team di fatturazione sta lavorando al problema e ti comunicheremo gli aggiornamenti il prima possibile.

Misure di sicurezza di Google per le chiavi compromesse

In che modo Google mi aiuterà a proteggere il mio account da costi eccessivi e comportamenti illeciti se le mie chiavi API vengono compromesse?

• Stiamo passando all'emissione di chiavi API quando richiedi una nuova chiave utilizzando Google AI Studio che per impostazione predefinita sarà limitata solo a Google AI Studio e non accetterà chiavi di altri servizi. In questo modo si eviterà l'utilizzo involontario di chiavi incrociate.
• Per impostazione predefinita, blocchiamo le chiavi API compromesse e utilizzate con l'API Gemini, contribuendo a prevenire comportamenti illeciti relativi ai costi e ai dati delle applicazioni.
• Potrai trovare lo stato delle tue chiavi API in Google AI Studio e lavoreremo per comunicare in modo proattivo quando identifichiamo che le tue chiavi API sono state compromesse per un'azione immediata.

Migliorare l'output del modello

Per ottenere output del modello di qualità superiore, prova a scrivere prompt più strutturati. La pagina della guida all'ingegneria del prompt introduce alcuni concetti di base, strategie e best practice per iniziare.

Informazioni sui limiti dei token

Leggi la nostra guida ai token per comprendere meglio come contarli 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 impreviste o persino bloccate. Per gli aggiornamenti, consulta le lingue disponibili per aggiornamenti.

Segnala un bug

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