Guide de dépannage

Utilisez ce guide pour diagnostiquer et résoudre les problèmes courants qui surviennent lorsque vous appelez l'API Gemini. Vous pouvez rencontrer des problèmes avec le service de backend de l'API Gemini ou avec les SDK client. Nos SDK clients sont disponibles en Open Source dans les dépôts suivants :

Si vous rencontrez des problèmes liés à la clé API, vérifiez que vous l'avez correctement configurée en suivant le guide de configuration de la clé API.

Codes d'erreur du service backend de l'API Gemini

Le tableau suivant répertorie les codes d'erreur de backend courants que vous pouvez rencontrer, ainsi que des explications sur leurs causes et des étapes de dépannage :

Code HTTP État Description Exemple Solution
400 INVALID_ARGUMENT Le corps de la requête est mal formé. Votre demande contient une faute de frappe ou un champ obligatoire manquant. Consultez la documentation de référence de l'API pour connaître le format des requêtes, des exemples et les versions compatibles. L'utilisation de fonctionnalités d'une version d'API plus récente avec un point de terminaison plus ancien peut entraîner des erreurs.
400 FAILED_PRECONDITION Le niveau sans frais de l'API Gemini n'est pas disponible dans votre pays. Veuillez activer la facturation pour votre projet dans Google AI Studio. Vous effectuez une requête dans une région où le niveau sans frais n'est pas disponible et vous n'avez pas activé la facturation pour votre projet dans Google AI Studio. Pour utiliser l'API Gemini, vous devez configurer un forfait payant à l'aide de Google AI Studio.
403 PERMISSION_DENIED Votre clé API ne dispose pas des autorisations requises. Vous utilisez la mauvaise clé API. Vous essayez d'utiliser un modèle ajusté sans passer par une authentification appropriée. Vérifiez que votre clé API est définie et qu'elle dispose des droits d'accès appropriés. Assurez-vous également de passer par une authentification appropriée pour utiliser les modèles ajustés.
404 NOT_FOUND La ressource demandée est introuvable. Un fichier image, audio ou vidéo référencé dans votre demande est introuvable. Vérifiez que tous les paramètres de votre requête sont valides pour votre version de l'API.
429 RESOURCE_EXHAUSTED Vous avez dépassé la limite de débit. Vous envoyez trop de requêtes par minute avec le niveau sans frais de l'API Gemini. Vérifiez que vous respectez la limite de fréquence du modèle. Demandez une augmentation de quota si nécessaire.
500 INTERNAL Une erreur inattendue s'est produite du côté de Google. Le contexte de votre saisie est trop long. Réduisez le contexte de votre entrée ou passez temporairement à un autre modèle (par exemple, de Gemini 1.5 Pro à Gemini 1.5 Flash) pour voir si cela fonctionne. Vous pouvez aussi patienter un peu et réessayer. Si le problème persiste après plusieurs tentatives, veuillez le signaler à l'aide du bouton Envoyer des commentaires dans Google AI Studio.
503 UNAVAILABLE Il est possible que le service soit temporairement surchargé ou indisponible. Le service est temporairement saturé. Passez temporairement à un autre modèle (par exemple, de Gemini 1.5 Pro à Gemini 1.5 Flash) et vérifiez si cela fonctionne. Vous pouvez aussi patienter un peu et réessayer. Si le problème persiste après plusieurs tentatives, veuillez le signaler à l'aide du bouton Envoyer des commentaires dans Google AI Studio.
504 DEADLINE_EXCEEDED Le service n'a pas pu terminer le traitement dans le délai imparti. Votre requête (ou votre contexte) est trop volumineuse pour être traitée à temps. Définissez un "délai d'attente" plus long dans votre requête client pour éviter cette erreur.

Vérifier les erreurs de paramètres de modèle dans vos appels d'API

Vérifiez que les paramètres de votre modèle sont compris dans les valeurs suivantes :

Paramètre de modèle Valeurs (plage)
Nombre de candidats 1 à 8 (entier)
Température 0.0-1.0
Nombre maximal de jetons de sortie Utilisez get_model (Python) pour déterminer le nombre maximal de jetons pour le modèle que vous utilisez.
TopP 0.0-1.0

En plus de vérifier les valeurs des paramètres, assurez-vous d'utiliser la version de l'API appropriée (par exemple, /v1 ou /v1beta) et un modèle compatible avec les fonctionnalités dont vous avez besoin. Par exemple, si une fonctionnalité est en version bêta, elle ne sera disponible que dans la version /v1beta de l'API.

Vérifier si vous disposez du bon modèle

Vérifiez que vous utilisez un modèle compatible listé sur notre page des modèles.

Latence ou utilisation de jetons plus élevées avec les modèles 2.5

Si vous constatez une latence ou une utilisation de jetons plus élevées avec les modèles Flash et Pro 2.5, cela peut être dû au fait que la réflexion est activée par défaut pour améliorer la qualité. Si vous privilégiez la rapidité ou que vous devez minimiser les coûts, vous pouvez ajuster ou désactiver la réflexion.

Consultez la page de réflexion pour obtenir des conseils et un exemple de code.

Problèmes de sécurité

Si vous voyez qu'une invite a été bloquée en raison d'un paramètre de sécurité dans votre appel d'API, examinez l'invite par rapport aux filtres que vous avez définis dans l'appel d'API.

Si le code BlockedReason.OTHER s'affiche, cela signifie que la requête ou la réponse ne respecte peut-être pas les Conditions d'utilisation ou n'est pas acceptée.

Problème de récitation

Si le modèle cesse de générer des résultats pour la raison "RÉCITATION", cela signifie que les résultats du modèle peuvent ressembler à certaines données. Pour résoudre ce problème, essayez de rendre la requête / le contexte aussi uniques que possible et utilisez une température plus élevée.

Problème de jetons répétitifs

Si vous voyez des jetons de sortie répétés, essayez les suggestions suivantes pour les réduire ou les éliminer.

Description Cause Solution suggérée
Tirets répétés dans les tableaux Markdown Cela peut se produire lorsque le contenu du tableau est long, car le modèle tente de créer un tableau Markdown visuellement aligné. Toutefois, l'alignement dans Markdown n'est pas nécessaire pour un rendu correct.

Ajoutez des instructions à votre requête pour donner au modèle des consignes spécifiques pour générer des tableaux Markdown. Fournissez des exemples qui respectent ces consignes. Vous pouvez également essayer de régler la température. Pour générer du code ou des résultats très structurés comme des tableaux Markdown, il est préférable d'utiliser une température élevée (>= 0,8).

Voici un exemple de consignes que vous pouvez ajouter à votre requête pour éviter ce problème : 

          # 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.
Jetons répétés dans les tableaux Markdown Comme pour les tirets répétés, cela se produit lorsque le modèle tente d'aligner visuellement le contenu du tableau. L'alignement en Markdown n'est pas nécessaire pour un rendu correct.
  • Essayez d'ajouter des instructions comme celles ci-dessous à votre requête système : 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • Essayez d'ajuster la température. Des températures plus élevées (>= 0,8) permettent généralement d'éliminer les répétitions ou les doublons dans le résultat.
Sauts de ligne répétés (\n) dans la sortie structurée Lorsque l'entrée du modèle contient des séquences Unicode ou d'échappement telles que \u ou \t, cela peut entraîner des retours à la ligne répétés.
  • Recherchez les séquences d'échappement interdites dans votre requête et remplacez-les par des caractères UTF-8. Par exemple, la séquence d'échappement \u dans vos exemples JSON peut inciter le modèle à les utiliser également dans sa sortie.
  • Indiquez au modèle les échappements autorisés. Ajoutez une instruction système comme celle-ci : 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
Texte répété lors de l'utilisation de la sortie structurée Lorsque l'ordre des champs dans la sortie du modèle est différent de celui du schéma structuré défini, cela peut entraîner la répétition de texte.
  • Ne spécifiez pas l'ordre des champs dans votre requête.
  • Rendez tous les champs de sortie obligatoires.
Appels d'outils répétitifs Cela peut se produire si le modèle perd le contexte des pensées précédentes et/ou appelle un point de terminaison indisponible auquel il est forcé. Demandez au modèle de conserver l'état dans son processus de réflexion. Ajoutez ce qui suit à la fin de vos instructions système : 
        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.
Texte répétitif qui ne fait pas partie de la sortie structurée Cela peut se produire si le modèle est bloqué sur une requête qu'il ne peut pas résoudre.
  • Si la fonctionnalité de réflexion est activée, évitez de donner des instructions explicites sur la manière de réfléchir à un problème. Il vous suffit de demander le résultat final.
  • Essayez une température plus élevée (≥ 0,8).
  • Ajoutez des instructions comme "Sois concis", "Ne te répète pas" ou "Donne la réponse une seule fois".

Améliorer le résultat du modèle

Pour obtenir des sorties de modèle de meilleure qualité, essayez d'écrire des requêtes plus structurées. La page du guide du prompt engineering présente des concepts, des stratégies et des bonnes pratiques de base pour vous aider à vous lancer.

Si vous disposez de centaines d'exemples de paires entrée/sortie de qualité, vous pouvez également envisager de régler le modèle.

Comprendre les limites de jetons

Consultez notre guide sur les jetons pour mieux comprendre comment les compter et connaître leurs limites.

Problèmes connus

  • L'API n'est compatible qu'avec un certain nombre de langues. L'envoi de requêtes dans des langues non acceptées peut générer des réponses inattendues, voire bloquées. Consultez la liste des langues disponibles pour en savoir plus.

Signaler un bug

Si vous avez des questions, rejoignez la discussion sur le forum des développeurs Google IA.