Blog

Guide d'utilisation

Gestion des réponses Kimi K3 en pratique : JSON complet, interruption de flux et limites de la logique de retry

Nov 18, 2026
Image de couverture géométrique abstraite sur fond vert foncé profond, où deux ensembles de sangles plates s'entrelacent en une grille ouverte, agrémentée de discrètes touches de couleur laiton.
Sur cette page

Distinguer d'abord les deux chemins de réponse

Avec la même interface Kimi K3, vous pouvez recevoir deux choses complètement différentes : une réponse JSON complète, ou une suite de blocs de données en streaming qui arrivent dans l'ordre. La première est une livraison de document en « question-réponse », la seconde une séquence incrémentale « générée et poussée au fur et à mesure ». La racine de nombreux bugs de traitement des réponses n'est pas une erreur d'analyse, mais le fait de ne pas avoir clarifié dès le départ sur quel chemin on se trouve.

Les deux chemins partagent le même protocole de requête (openai_chat_completions, version de contrat 2), les différences se concentrent sur le mode de consommation :

  • Non-streaming : une fois la requête retournée, vous obtenez un corps de réponse complet, contenant le texte, le contenu de raisonnement et l'usage, lisible en une seule fois.
  • Streaming : activé en mode optionnel, le serveur pousse continuellement des chunks, et termine le flux par le marqueur SSE [DONE]. Vous pouvez recevoir des dizaines ou des centaines de blocs en cours de route, ou une coupure en plein milieu ; [DONE] indique seulement la fin du flux, pas que le contenu est complet.

Confirmez d'abord ce point, toutes les discussions suivantes n'ont de sens qu'à cette condition. Si votre chaîne métier comporte les deux types d'appels (par exemple, un traitement par lots en arrière-plan et un dialogue frontal partageant une même encapsulation), il est recommandé d'annoter explicitement le chemin côté client, plutôt que de le distinguer par un jugement implicite du type « y a-t-il un callback » — cela poserait des mines de désérialisation lors d'une refonte.

Une règle de décision simple : utilisez le streaming lorsqu'il faut afficher caractère par caractère à l'utilisateur, ou que la sortie peut être longue ; utilisez le non-streaming lorsqu'il faut obtenir un résultat structuré en une fois, pour le persister en base ou le retraiter. Le code d'analyse des deux chemins doit être écrit séparément ; seules la construction de requête et le mapping d'erreurs sont partagés.

La même entrée de requête se divise en deux chemins de consommation : l'un renvoie la réponse entière, l'autre des fragments successifs.

Analyser le JSON complet : texte, contenu de raisonnement et champs structurés

La réponse non-streaming suit le format de corps de réponse d'OpenAI Chat Completions, mais un point est facilement négligé : le texte et le contenu de raisonnement sont deux champs distincts.

Le texte se trouve à l'emplacement standard du contenu de message, tandis que le processus de raisonnement de Kimi K3 est livré via le champ reasoning_content. Cela signifie que votre couche d'analyse doit faire au moins trois choses :

  • extraire la réponse finale destinée à l'utilisateur depuis le contenu du message ;
  • déterminer si reasoning_content existe, et décider s'il faut le journaliser, l'afficher à l'utilisateur ou le supprimer ;
  • conserver séparément usage pour la facturation et le calcul des quotas.

Afficher reasoning_content comme texte principal est un accident courant : il est destiné aux scénarios de débogage et d'explicabilité, et l'intégrer directement dans un texte produit ou une réponse au service client donne un ton et un contenu inappropriés. La bonne approche est de lui réserver un chemin de consommation distinct, par exemple vers un journal de débogage ou une entrée optionnelle du type « voir le processus de raisonnement ».

Comment utiliser la sortie structurée

Ce contrat prend en charge le paramètre response_format et la capacité de sortie structurée jsonObject. Vous pouvez demander au modèle de renvoyer un objet JSON, ce qui évite une couche fragile d'extraction par expressions régulières. Mais deux prérequis doivent être précisés : la capacité jsonObject ne signifie pas prise en charge du mode JSON Schema ; et la sortie structurée n'est pas une garantie de « succès assuré ».

N'essayez d'analyser le JSON qu'après une réponse correctement terminée et un contenu complet. Après l'analyse, trois types d'échecs restent à gérer :

  • Échec d'analyse : le contenu renvoyé n'est pas un JSON valide, ou des champs manquent ou ont un type incorrect. Il ne faut pas alors jeter la chaîne brute directement au métier en amont, mais basculer vers une branche de repli.
  • Échec de validation de schéma : la syntaxe JSON est valide, mais ne respecte pas la structure déclarée. jsonObject ne garantit pas les contraintes de niveau JSON Schema ; le côté métier doit encore valider lui-même les champs, les types et les champs obligatoires.
  • Troncature : lorsque la longueur de sortie atteint la limite de tokens de sortie de ce modèle (131072), finish_reason peut valoir length, et le JSON peut s'interrompre en cours. On ne peut pas considérer length comme un succès JSON complet. Un analyseur face à un JSON incomplet signalera une erreur, mais le cas plus dangereux est qu'il « réussisse tant bien que mal à analyser » et que vous continuiez la logique métier avec un demi-objet.

Il est recommandé d'ajouter après l'analyse une vérification de complétude des champs métier et des preuves, plutôt que de se fier uniquement à la validité syntaxique du JSON. La fenêtre de contexte est de 1000000 ; dans les scénarios de documents longs, l'entrée n'est pas le goulot d'étranglement, mais la troncature de sortie reste une limite bien réelle.

L'enveloppe de réponse est décomposée en couches : texte, contenu de raisonnement et usage forment chacun une branche, dirigée vers son propre consommateur.

Lecture en streaming : [DONE], finish_reason et usage

En mode streaming, le serveur pousse les chunks dans l'ordre, et le marqueur de terminaison réseau SSE est [DONE]. Cette phrase semble anodine, mais elle est souvent mal interprétée : [DONE] indique seulement que ce flux est terminé, ni que la génération a réussi, ni que le contenu est complet.

Pour juger de l'état terminal, il faut examiner choices[].finish_reason dans chaque chunk. Le frontend actuel identifie l'état terminal par un finish_reason non vide ; même si [DONE] est reçu, l'absence de finish_reason doit être considérée comme une interruption. Une trame error dans le flux indique l'échec de cette requête.

Le flux peut se terminer dans plusieurs états :

  1. Achèvement normal : finish_reason est un état terminal de succès, puis [DONE] est reçu ; le contenu accumulé peut être considéré comme le résultat complet ;
  2. Troncature par longueur : finish_reason=length, la sortie est tronquée par la limite de longueur, le contenu peut être incomplet et ne peut pas être considéré comme un succès JSON complet ;
  3. Autres raisons non réussies : par exemple le filtrage de contenu, à traiter séparément, sans les considérer comme un achèvement normal ;
  4. Coupure en cours de route : fermeture de connexion, timeout, ou réception d'une trame error dans le flux ; seul un contenu partiel est alors disponible, à marquer comme échec ou incomplet.

Le dernier cas est le plus souvent traité en « on prend ce qu'on a ». Pour l'affichage d'un chat, c'est peut-être acceptable (l'utilisateur voit une phrase incomplète et peut renvoyer), mais pour la persistance, la facturation ou le déclenchement d'actions en aval, ce sont des données erronées. Utilisez « la réception d'un finish_reason terminal de succès » comme critère de complétude, et non le seul [DONE].

L'usage est agrégé après la fin du flux

En mode streaming, usage peut apparaître dans une trame choices:[] après finish_reason. Le client doit agréger l'usage après avoir lu tout le flux ; on ne peut pas garantir que [DONE] lui-même porte l'usage.

Cela impose deux contraintes de codage directes :

  • Ne pas facturer ni régler les quotas dès le premier chunk. À ce moment, vous ne connaissez ni la longueur finale de la sortie, ni le champ d'usage.
  • Ne pas accumuler l'usage dans les blocs intermédiaires, ni considérer [DONE] comme le support de l'usage. Les blocs intermédiaires ne contiennent pas de données d'usage fiables ; toute « estimation » s'écartera de la valeur finale.

L'ordre correct est le suivant : pendant le streaming, se contenter d'accumuler le texte et l'état ; après la lecture du flux, agréger l'usage depuis les trames choices:[] pour un règlement unique. Si le flux est coupé en cours et que vous avez déjà affiché du contenu à l'utilisateur, l'état d'usage de cet appel est inconnu — vous avez besoin d'un indicateur d'état « incomplet », plutôt que de comptabiliser par défaut à 0 ou selon une estimation.

Il faut aussi distinguer les métadonnées internes des champs réseau : response.stream.terminal=done et response.usage.delivery=final_chunk sont des étiquettes de métadonnées internes à la plateforme, et non des champs réseau SSE ni des chaînes de terminaison à faire correspondre côté client. Le client ne doit s'appuyer que sur [DONE], finish_reason, les trames error et le champ usage lui-même.

Autre détail pratique : pour accumuler le texte, utilisez l'ajout dans une liste puis un join, plutôt qu'une concaténation répétée de chaînes ; la différence de performance est notable sur les sorties longues.

La ligne temporelle du haut atteint le bloc terminal couleur laiton avec un finish_reason de succès ; celle du bas se rompt en cours de route sans atteindre l'état terminal de succès, on ne peut donc pas supposer avoir obtenu un résultat complet.

Pourquoi un retry POST n'est pas une idempotence gratuite

Beaucoup de logiques de retry s'écrivent ainsi : la requête lève une exception de timeout, on la capture, on attend un peu, on renvoie. Cet article ne traite que la sémantique des opérations POST de génération comme les complétions de chat : ce type de retry peut entraîner une double facturation et des effets de bord en double, on ne peut pas le considérer comme une idempotence gratuite.

La raison est simple : le timeout est un jugement du client, pas un engagement du serveur. Lorsque votre minuteur se déclenche, la requête a peut-être déjà atteint complètement le serveur, déjà commencé l'inférence, voire déjà abouti et été facturée, et seule la réponse s'est perdue en chemin. Le client ne peut pas distinguer ces deux situations par le seul type d'exception :

  • la requête n'a pas atteint le serveur, le retry ne produira pas de seconde exécution ;
  • la requête a été acceptée et a produit un effet, le retry est alors un second appel.

« L'effet » d'une complétion de chat inclut généralement la consommation de tokens et la facturation, ainsi que les actions que vous déclenchez côté métier à partir de la réponse (écriture en base, envoi de formulaire, envoi de message). Rejouer un POST au résultat incertain revient à exécuter ces effets de bord deux fois. Ce n'est pas un risque théorique : les fluctuations réseau, les timeouts de passerelle, les connexions réinitialisées par un équipement intermédiaire produisent tous régulièrement ces états ambigus.

Plus gênant encore : une réponse 5xx complète, un timeout, une déconnexion ou un échec d'analyse JSON ne prouvent ni que la requête n'a pas généré, ni qu'elle n'a pas été débitée, ni qu'il n'y a pas eu d'effet de bord. L'erreur que vous voyez indique seulement que le client n'a pas obtenu de résultat exploitable cette fois-ci.

Ainsi, la bonne condition préalable au retry n'est pas « une erreur s'est produite », mais « cette requête ne s'est certainement pas exécutée ». Avant d'écrire le moindre code de retry, répondez à cette question ; si vous ne pouvez pas, ne rejouez pas automatiquement.

Délimiter les limites du retry : quels cas peuvent être rejoués

Faire du retry un tableau de niveaux est plus fiable que d'écrire une boucle uniforme for retry in range(3). Voici la stratégie de traitement par type d'erreur.

Exécution certainement absente, retry possible

  • Échec d'établissement de connexion (échec DNS, connexion refusée) : la requête n'a manifestement pas atteint le serveur, il s'agit d'un non-envoi certain, le retry ne produira pas de seconde exécution.
  • Réponse de limitation de débit (par exemple 429) : ne procéder à un retry avec backoff selon cette sémantique que si la documentation de l'API ou la sémantique de la réponse garantit explicitement le rejet avant exécution ; un simple 429 ou un autre code de statut ne permet pas de déduire une non-exécution ou une non-facturation. Le backoff doit inclure une gigue aléatoire pour éviter que plusieurs clients ne réessaient en synchronisation.
  • Mécanisme de déduplication explicitement fourni par l'interface et réellement utilisé par le serveur : ne réessayer selon sa sémantique que si la documentation de l'API le précise explicitement et que le serveur s'en sert réellement pour dédupliquer. Un identifiant de requête généré par le client ne sert qu'au suivi, on ne peut pas supposer qu'un en-tête ou un champ donné ait un effet idempotent.

Résultat inconnu, traitement explicite requis

  • Timeout : c'est la catégorie la plus dangereuse. Un timeout ne prouve pas que la requête n'a pas été exécutée ; un renvoi peut produire une nouvelle génération facturée. Un identifiant de requête généré par le client ne sert qu'au suivi ; seul un mécanisme de déduplication explicitement pris en charge et réellement utilisé par le serveur peut empêcher une inférence et une facturation en double. La déduplication côté métier peut au mieux empêcher une répétition d'action en aval, pas empêcher le modèle de générer et de facturer à nouveau. Si la sémantique de déduplication du serveur ne peut être confirmée, ne rejouez pas automatiquement, mais signalez l'erreur à l'utilisateur ou basculez vers un processus de compensation manuel/asynchrone.
  • Réponse 5xx complète : même si le corps de réponse est lisible en entier, cela ne prouve pas l'absence de génération, de débit ou d'effet de bord. Un retry n'est possible que si l'absence d'exécution est certaine, ou si la documentation de l'API précise explicitement que le serveur dédupliquera réellement selon l'identifiant de déduplication ; sinon, traiter comme résultat inconnu.
  • Échec d'analyse de la réponse : inclut l'échec d'analyse JSON et l'échec de validation de schéma. La requête a peut-être réussi et été facturée ; un échec d'analyse ne prouve pas l'absence de génération. Un retry peut entraîner un double débit et des effets de bord en double ; il est recommandé de marquer explicitement le résultat comme inconnu et de le journaliser, pour permettre une vérification ultérieure de l'usage.
  • Coupure du flux en cours ou réception d'une trame error dans le flux : le contenu déjà poussé ne peut pas être concaténé au nouveau résultat ; le rejeu sera considéré comme une génération entièrement nouvelle.

Ne pas réessayer automatiquement

  • Erreur de paramètre de requête (erreurs de type paramètre parmi les 4xx) : quel que soit le nombre de retries, le résultat sera le même, cela ne fera qu'amplifier l'erreur.
  • Refus de type modération de contenu : le rejeu ne changera pas la conclusion.
  • Tout cas où vous ne pouvez pas déterminer « si cela a pris effet » et où il n'existe pas de sémantique de déduplication côté serveur.

Inscrire les limites dans le code

Deux contraintes d'ingénierie méritent d'être figées : plafonner le nombre de retries (généralement 1 à 2 suffisent), et ne les appliquer qu'aux cas de non-envoi certain, ou aux cas où la documentation de l'API garantit explicitement un rejet avant exécution ; journaliser à chaque retry l'identifiant de requête, le type d'erreur et la durée, car le « nombre de retries » détermine directement votre facture d'usage et votre parcours de dépannage. Le retry des requêtes en streaming demande une attention supplémentaire : une fois la connexion rompue en cours, le rejeu produira une génération entièrement nouvelle et facturée, et le contenu déjà poussé ne peut pas être concaténé au nouveau résultat.

Si vous êtes encore en phase de choix, vous pouvez d'abord consulter la page du modèle Kimi K3 pour comprendre les détails du contrat, puis décider de la granularité de votre stratégie de retry.

Checklist de mise en œuvre

Réunir les règles précédentes en une liste à vérifier point par point lors d'une revue :

  • Le client distingue-t-il explicitement les deux chemins de consommation, streaming et non-streaming, plutôt que par un jugement implicite ?
  • L'analyse non-streaming traite-t-elle séparément le texte et reasoning_content, et reasoning_content n'entre-t-il pas directement dans un texte visible par l'utilisateur ?
  • usage est-il conservé séparément et corrélable aux enregistrements métier ?
  • La sortie structurée n'est-elle analysée qu'après un achèvement normal et un contenu complet, avec un repli indépendant pour l'échec d'analyse, l'échec de validation de schéma, l'échec de validation métier et de preuves, ainsi que finish_reason=length ?
  • La lecture en streaming identifie-t-elle l'état terminal par un finish_reason non vide, plutôt que par l'attente seule de [DONE] ?
  • [DONE] est-il traité uniquement comme marqueur de fin de flux, avec un marquage comme interruption en l'absence de finish_reason ?
  • L'usage est-il agrégé depuis les trames choices:[] après la lecture du flux, sans supposer que [DONE] porte l'usage ?
  • Les trames error dans le flux sont-elles identifiées comme échec, et non comme une fin normale ?
  • Le retry est-il gradué par type d'erreur, et appliqué uniquement aux cas de non-envoi certain ou aux cas où la documentation de l'API garantit explicitement un rejet avant exécution ?
  • Le timeout, la déconnexion, une réponse 5xx complète ou un échec d'analyse JSON sont-ils traités explicitement comme « résultat inconnu », plutôt que de promettre la sécurité d'un retry ?
  • Le nombre de retries est-il plafonné, et chaque retry dispose-t-il de journaux permettant de vérifier l'usage ?
  • Le rejeu après une interruption de flux est-il considéré comme une nouvelle génération, et non comme une continuation ?

Cette liste n'a pas besoin d'être satisfaite entièrement d'un coup, mais chaque point correspond à un problème réel qui se produit en production. Traitez d'abord les deux points du critère d'état terminal finish_reason et des limites de retry, le gain est le plus direct.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API