Points clés
- Context windows combine prompt and completion, so long histories drain limits faster than expected.
- Le streaming nécessite de gérer soigneusement les événements SSE pour éviter un JSON corrompu ou des tokens perdus.
- JSON mode demands strict schema adherence; malformed responses cause silent parsing failures.
- La facturation crypto prépayée signifie que les erreurs sont gratuites, mais le comptage des jetons doit être précis pour éviter les surprises.
Pourquoi votre clé API peut être rejetée
Les clés API sont rejetées lorsque le client envoie des en-têtes mal formés ou dépasse les limites du corps de la requête. Le serveur valide l'en-tête d'authentification avant de traiter toute logique. Si l'en-tête est manquant ou contient des espaces superflus, la requête échoue immédiatement.
Une autre cause fréquente est l'envoi d'un payload qui dépasse la limite de taille de corps de 8 Mo. Les grandes fenêtres de contexte avec de nombreux messages peuvent facilement dépasser ce seuil. Vérifiez la longueur de votre tableau de messages et le nombre de tokens avant l'envoi.
- Assurez-vous que l'en-tête Authorization utilise correctement le préfixe 'Bearer'.
- Verify the request body size stays under 8 MB.
- Vérifiez que la clé API est active et n'a pas expiré.
Comprendre les limites de la fenêtre de contexte
La fenêtre de contexte inclut à la fois l'invite d'entrée et la complétion générée. Notre API prend en charge une fenêtre de 100 000 tokens, mais vous devez prendre en compte les deux côtés. Si vous envoyez 80 000 tokens de contexte, il ne vous reste que 20 000 tokens pour la réponse.
La plupart des modèles ont par défaut une limite de sortie faible si vous ne spécifiez pas max_tokens. Cela peut tronquer les réponses longues de manière inattendue. Définissez max_tokens à la longueur souhaitée uniquement si vous voulez une limite. Rappelez-vous que la limite s'applique à la requête totale, et non uniquement à l'invite.
Gestion correcte des interruptions de streaming
Le streaming via les événements envoyés par le serveur (SSE) nécessite une gestion robuste des erreurs. Si la connexion est interrompue, vous risquez de perdre le dernier jeton ou les métadonnées d'utilisation. Mettez toujours en mémoire tampon les chunks entrants et reconstruisez la réponse complète côté client.
Les données d'utilisation des tokens sont généralement envoyées dans le dernier fragment du flux. Si vous fermez la connexion prématurément, vous risquez de manquer le nombre exact de tokens. Cela affecte la précision de la facturation dans les systèmes prépayés. Implémentez un mécanisme de nouvelle tentative avec un backoff exponentiel pour gérer les problèmes réseau transitoires.
Utilisez un client de streaming dédié qui gère automatiquement l'analyse du SSE. Cela réduit le risque d'erreurs d'analyse et garantit que vous capturez toutes les données.
Erreurs d'analyse du mode JSON
Lors de l'utilisation de response_format: {"type": "json_object"}, le modèle doit renvoyer du JSON valide. Toute déviation entraîne des erreurs d'analyse dans votre application. Assurez-vous que votre prompt indique explicitement au modèle de ne produire que du JSON.
Parfois, le modèle inclut des blocs de code markdown autour du JSON, ce qui casse les analyseurs stricts. Supprimez les balises avant l'analyse. De plus, validez la structure du JSON côté client avant d'utiliser les données.
Utilisez une bibliothèque de validation de schéma pour détecter les erreurs précocement. Cela évite les plantages lorsque le modèle renvoie des clés ou des types inattendus.
Surprises de comptage des tokens et de facturation
La facturation prépayée ne facture que l'utilisation réelle des tokens. Les erreurs et les refus sont gratuits, ce qui constitue un avantage significatif par rapport aux modèles d'abonnement. Cependant, le comptage des tokens peut s'avérer délicat si vous ne tenez pas compte du contexte entier.
Chaque message de l'historique de conversation compte pour la limite de jetons d'entrée. Les longues conversations épuisent votre crédit prépayé plus rapidement que prévu. Surveillez régulièrement votre consommation pour éviter de manquer de crédits en cours de session.
Configurez des alertes pour les soldes de crédits bas. Cela vous permet de recharger avant que vos requêtes ne échouent. N'oubliez pas que les crédits n'expirent jamais, vous pouvez donc recharger quand vous le souhaitez.
Éviter les refus doux dans les prompts NSFW
Les refus doux se produisent lorsque le modèle hésite ou fournit une réponse partielle au lieu d'une réponse directe. Cela se produit souvent avec des sujets controversés ou pour adultes. Même dans un modèle sans censure, certains déclencheurs peuvent provoquer une hésitation.
Ajustez le paramètre temperature pour réduire l'aléa. Une température plus basse rend le modèle plus déterministe et moins enclin à se montrer prudent. Assurez-vous également que votre prompt soit clair et direct. Évitez les formulations ambiguës qui pourraient perturber le modèle.
Si vous rencontrez fréquemment des refus doux, essayez de reformuler légèrement la demande. De petits changements de formulation peuvent souvent contourner l'hésitation et obtenir une réponse directe.
Sauts de limite de débit et stratégies de backoff
L'API autorise 300 requêtes par minute et 8 requêtes simultanées par clé. Les pics de trafic peuvent rapidement atteindre ces limites. Implémentez une rétroaction exponentielle pour gérer les erreurs de limite de débit avec élégance.
Lorsque vous recevez un code d'état 429, attendez avant de réessayer. Commencez par un court délai et augmentez-le à chaque tentative. Cela évite de surcharger le serveur pendant les périodes de pointe.
Surveillez votre taux de requêtes et ajustez vos niveaux de concurrence en conséquence. Si vous effectuez de nombreuses requêtes simultanées, envisagez de les répartir dans le temps. Cela garantit un débit stable sans atteindre les limites.
Structures de charge utile d'appel de fonction
L'appel de fonction nécessite une structure de charge utile spécifique. Définissez vos fonctions dans le paramètre tools et spécifiez le tool_choice. Le modèle renverra un appel de fonction s'il estime que c'est la réponse appropriée.
Assurez-vous que vos définitions de fonctions soient précises et complètes. Des paramètres manquants ou des types incorrects peuvent amener le modèle à générer des appels invalides. Validez toujours les arguments de l'appel de fonction avant de les exécuter.
Utilisez le paramètre tool_choice pour contrôler quand le modèle appelle des fonctions. Vous pouvez forcer un appel de fonction, laisser le modèle décider ou désactiver complètement l'appel de fonctions. Cela vous donne un contrôle précis du comportement du modèle.
Débogage des erreurs 400 vs 500
Les erreurs 400 indiquent des problèmes côté client, comme un JSON invalide ou des paramètres manquants. Les erreurs 500 suggèrent des problèmes côté serveur, comme des erreurs internes ou des timeouts. Les distinguer vous aide à déboguer plus rapidement.
Pour les erreurs 400, vérifiez le message d'erreur fourni dans la réponse. Il indique généralement directement le problème. Pour les erreurs 500, réessayez la requête après un court délai. Si l'erreur persiste, contactez le support en fournissant l'ID de la requête.
Journalisez les détails de la requête et de la réponse pour chaque erreur. Cela permet d'identifier des schémas récurrents et des problèmes qui se répètent. Utilisez un service de journalisation pour suivre les erreurs au fil du temps et améliorer votre intégration API.
