Kimi K3 reasoning_effort : guide Agent 2026

reasoning_effort de Kimi K3 accepte trois valeurs — low, high et max — tandis que la valeur par défaut documentée est max. Pour votre Agent, ne conservez donc pas automatiquement le niveau maximal : utilisez low pour les demandes courtes et facilement vérifiables, high pour le code multi-fichier et les appels d’outils courants, puis max pour les planifications longues ou les échecs coûteux. La décision finale doit venir de vos journaux de réussite, de délai et de coût, pas de la longueur apparente du raisonnement. Documentation officielle du dépôt Kimi K3

Qui devrait lire ce guide ? Vous configurez un Kimi K3 API pour un AI Agent, un assistant de recherche ou une chaîne d’outils. Vous souhaitez éviter que toutes les requêtes utilisent l’intensité maximale sans affaiblir la qualité des tâches importantes.

Ce guide s’adresse également aux équipes qui maintiennent des flux de code, d’analyse, d’audio ou de vidéo et doivent comparer le coût des Tokens, le délai de réponse, le taux de réussite et les reprises humaines.

Dernière mise à jour : 2 août 2026. Les paramètres ont été vérifiés dans le dépôt officiel Kimi K3, le guide de démarrage et la documentation consacrée aux appels d’outils.

Le point de départ : trois niveaux, trois usages différents

Kimi K3 active toujours le raisonnement. Vous ne choisissez donc pas entre un modèle qui raisonne et un modèle qui ne raisonne pas. Vous choisissez l’intensité demandée avec le champ supérieur reasoning_effort.

Les valeurs officielles sont :

La documentation officielle indique également que max est la valeur par défaut lorsque vous ne précisez pas le champ. Dans une application de production, envoyez donc explicitement le niveau choisi. Vous éviterez qu’un changement de valeur par défaut ou de route interne modifie silencieusement le comportement de votre Agent. Guide officiel de démarrage de l’API Kimi

Un appel peut prendre cette forme :

from openai import OpenAI

client = OpenAI(
    api_key="$KIMI_API_KEY",
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": "Analyse ce fichier et propose une correction."
        }
    ],
    reasoning_effort="high",
)

Le niveau choisi ne garantit pas à lui seul une meilleure réponse. Il peut modifier le chemin de résolution, mais le résultat dépend aussi du contexte fourni, de la qualité des instructions, des outils disponibles, des tests et de la procédure de reprise.

À retenir : un raisonnement plus long ne signifie pas automatiquement une meilleure réponse. Mesurez le résultat accepté, les outils correctement exécutés et le nombre de reprises avant de modifier votre règle.

low contre high pour les tâches courtes et vérifiables

Commencez par low lorsque la sortie peut être contrôlée rapidement et objectivement. Les cas adaptés comprennent la conversion d’un format, l’extraction de champs, une explication limitée, une correction syntaxique ou une modification locale dans un fichier.

Le même principe s’applique aux usages créatifs. Vous pouvez tester low pour reformuler un titre de vidéo, nettoyer une transcription audio, extraire des métadonnées d’un fichier sonore ou transformer une liste de scènes en tableau. Si un schéma, un test ou une règle de validation peut accepter ou rejeter la réponse, vous disposez d’un filet de sécurité clair.

Ne choisissez pas max simplement parce que la demande appartient à un produit complexe. Une plateforme d’édition vidéo peut contenir des tâches très différentes : générer une description de scène, synchroniser des informations, modifier un projet ou planifier une chaîne complète. Le produit ne détermine pas automatiquement le niveau requis ; l’opération demandée le fait.

Passez à high lorsque la tâche comprend plusieurs opérations liées. Par exemple, l’Agent doit lire une configuration, identifier une dépendance, modifier plusieurs fichiers, exécuter un test et expliquer le résultat. Même si chaque étape est relativement simple, leur enchaînement augmente le risque d’oubli.

Pour décider, posez-vous ces questions :

• La réponse peut-elle être validée sans jugement humain ?
• Une erreur est-elle détectée immédiatement par un test ?
• La tâche reste-t-elle limitée à un fichier ou à une transformation ?
• Une nouvelle tentative coûte-t-elle peu de temps et peu de Tokens ?

Si vous répondez oui à la majorité de ces questions, low constitue le meilleur premier test. Si plusieurs réponses sont négatives, essayez high.

Première étape : classer la demande avant l’appel

Un routeur simple est souvent plus utile qu’une consigne générale du type « utilisez le niveau adapté ». Classez chaque demande selon quatre critères :

1. Complexité : instruction locale ou séquence de décisions dépendantes ;
2. Vérifiabilité : test automatique disponible ou jugement humain nécessaire ;
3. Coût d’un échec : reformulation rapide ou reprise d’un long traitement ;
4. Délai accepté : réponse à l’écran ou exécution en arrière-plan.

Cette classification répond aussi à une question fréquente sur le Kimi K3 API : le niveau par défaut ne doit pas devenir votre politique d’entreprise. Il s’agit d’un comportement de l’API, pas d’une preuve que chaque requête a besoin de max.

high contre max pour le code et les outils

Pour un Agent de programmation, high est généralement le point de départ le plus équilibré lorsque la tâche couvre plusieurs fichiers et quelques outils. Votre objectif n’est pas d’obtenir le raisonnement le plus développé, mais de produire une modification complète, testable et reproductible.

L’évaluation doit séparer trois résultats :

• le code final passe-t-il les tests prévus ;
• les appels d’outils ont-ils été produits avec les bons arguments et dans le bon ordre ;
• combien de retouches humaines ont été nécessaires après la réponse ?

Le dernier indicateur est essentiel. Un Agent peut générer un correctif plausible tout en oubliant un fichier, en interrompant une étape ou en vous obligeant à reformuler la demande. Dans ce cas, le coût réel inclut les Tokens de la reprise, le temps de contrôle et le délai avant livraison.

Réservez max aux tâches où une erreur de planification est difficile à repérer ou chère à corriger. Cela peut concerner une refonte qui traverse plusieurs modules, une analyse répartie sur un grand dépôt, une recherche comportant plusieurs hypothèses ou une automatisation qui doit enchaîner des actions dépendantes.

Dans un appel d’outils multi-tour, vous devez conserver le message assistant complet renvoyé par l’API. Les éléments de raisonnement et les appels d’outils ne doivent pas être remplacés par le seul texte final lorsque la conversation continue. La documentation officielle décrit cette exigence pour les champs reasoning_content et tool_calls. Guide officiel des appels d’outils Kimi

Si votre Agent perd le contexte d’un appel, ne concluez pas immédiatement que high est trop faible. Vérifiez d’abord les éléments suivants :

• le message assistant original est-il renvoyé intégralement ;
• le résultat de l’outil est-il associé au bon appel ;
• le schéma des arguments est-il valide ;
• l’outil renvoie-t-il une erreur lisible ;
• la prochaine instruction indique-t-elle clairement l’étape attendue ?

Une mauvaise conservation de l’historique peut ressembler à un problème de raisonnement alors qu’il s’agit d’un problème d’intégration.

Temps réel contre traitement asynchrone

Dans une interface interactive, la qualité finale ne suffit pas. Vous devez mesurer le délai avant le premier contenu, le délai jusqu’à la fin du message et le temps nécessaire pour obtenir un résultat validé.

Pour une correction affichée directement dans un éditeur, commencez par low ou high selon le nombre d’étapes. Le mode de sortie en flux peut améliorer la perception de progression, mais il ne réduit pas nécessairement le temps total de calcul. Il faut donc enregistrer les deux indicateurs séparément.

Pour une tâche de recherche, de génération vidéo ou d’analyse audio, le traitement asynchrone offre davantage de liberté. Vous pouvez accepter un délai supérieur si l’Agent doit collecter des informations, les comparer, produire un livrable puis effectuer une vérification. Dans ce cas, max peut être pertinent, à condition de fixer une limite de temps et un mécanisme d’arrêt.

Mesurez au minimum :

• le délai avant le premier fragment ;
• le délai jusqu’au message final ;
• le délai de chaque appel d’outil ;
• le nombre de reprises ;
• le délai jusqu’au résultat accepté.

Ne publiez pas de promesse de vitesse issue d’un autre environnement. Le réseau, la longueur du contexte, la concurrence, le flux de sortie et les outils changent fortement le résultat observé. La méthode de référence doit être votre propre chaîne d’exécution, avec des requêtes représentatives et des répétitions comparables. Recommandations officielles pour les tests de performance

FAQ : choisir et automatiser reasoning_effort

Quelle différence entre low, high et max ?

Ces trois valeurs règlent l’effort de raisonnement demandé à Kimi K3. Le raisonnement reste actif, mais l’intensité sélectionnée change la manière dont le modèle traite une demande. Utilisez low pour une tâche simple et contrôlable, high pour une séquence multi-étapes ou plusieurs outils, et max pour une planification longue ou une opération sensible. La qualité exacte doit être mesurée sur vos propres cas.

Quelle valeur Kimi K3 utilise-t-il par défaut ?

La valeur par défaut documentée est max lorsque reasoning_effort n’est pas précisé. Vous ne devez toutefois pas interpréter cette valeur comme une recommandation pour toutes les applications. Dans un environnement de production, définissez explicitement le niveau dans votre routeur, journalisez votre choix et ajoutez une règle d’escalade. Vous éviterez ainsi une consommation imprévisible sur les demandes simples.

Pour un Agent de code, faut-il commencer avec high ou max ?

Commencez par high pour une modification multi-fichier accompagnée de quelques appels d’outils et de tests. Passez à max si les journaux montrent des erreurs de planification, des appels incomplets ou des reprises répétées. Une correction locale et automatiquement testée peut commencer avec low. Le bon niveau dépend donc de la structure de la tâche et non du mot « code » seul.

reasoning_effort augmente-t-il le coût de l’API ?

Il peut augmenter le coût total d’une tâche, mais vous ne devez pas déduire un montant fixe uniquement à partir du niveau choisi. Le coût dépend des Tokens d’entrée et de sortie, des appels d’outils, des reprises et des délais d’expiration. Comparez le coût par tâche réussie, puis vérifiez les règles de facturation actuellement publiées avant de définir un budget. Documentation officielle de la tarification

Comment changer automatiquement le niveau selon la demande ?

Placez un routeur avant l’appel API. Il peut utiliser la complexité, la vérifiabilité, le coût d’un échec et le délai accepté. Orientez les tâches simples vers low, les tâches multi-étapes vers high et les chaînes longues vers max. Conservez une surcharge manuelle, journalisez chaque décision et prévoyez un retour rapide vers un niveau inférieur si la durée dépasse votre seuil produit.

Les longues chaînes ont besoin de reprises contrôlées

max ne corrige pas une architecture fragile. Si le contexte est ambigu, si les outils renvoient des résultats incomplets ou si aucune étape de validation n’existe, un raisonnement plus intense peut seulement prolonger le problème.

Découpez votre chaîne en étapes observables :

• définir l’objectif et les critères d’acceptation ;
• produire un plan ;
• exécuter une action ;
• contrôler le résultat intermédiaire ;
• poursuivre ou revenir en arrière ;
• produire le livrable final.

Pour un traitement documentaire, low peut servir à l’extraction structurée, high à l’analyse croisée et max à une synthèse dépendant de plusieurs hypothèses. Pour un flux audio ou vidéo, séparez la transcription, le découpage, l’interprétation et la génération du livrable. Vous localiserez plus facilement les erreurs et le coût des reprises.

Ajoutez également une limite de temps, un nombre maximal de relances et une validation humaine pour les opérations irréversibles. Un Agent qui répète le même appel ne doit pas pouvoir consommer indéfiniment votre budget.

Deuxième étape : appliquer une règle de routage claire

Vous pouvez commencer par cette politique :

• Si la sortie est courte, structurée et contrôlable automatiquement, choisissez low.
• Si la demande touche plusieurs fichiers ou quelques outils, choisissez high.
• Si la tâche comprend une planification longue, une recherche multi-tour ou un échec coûteux, choisissez max.
• Si l’utilisateur attend à l’écran, préférez le niveau inférieur compatible avec vos tests.
• Si deux validations consécutives échouent au même niveau, escaladez une fois, puis réduisez la portée ou demandez une intervention.
• Si le délai dépasse le seuil accepté, revenez à high ou low, découpez la tâche et proposez un traitement asynchrone.

Votre journal doit contenir le type de demande, le niveau sélectionné, les Tokens d’entrée et de sortie, les appels d’outils, le délai total, les erreurs, les reprises et le verdict final. Calculez ensuite le coût par tâche réussie. Une configuration qui consomme moins de Tokens par appel mais échoue souvent peut être plus chère à l’échelle de votre équipe.

Les limites de compte, de concurrence et de Tokens peuvent également influencer le comportement d’une chaîne continue. Vérifiez les limites actuellement publiées avant de lancer une montée en charge. Documentation officielle des limites d’utilisation

Troisième étape : valider avant d’élargir le trafic

Sélectionnez trois tâches représentatives :

• une demande courte et très vérifiable ;
• une modification de code avec plusieurs fichiers et outils ;
• une chaîne longue dont l’échec impose une reprise importante.

Exécutez chaque tâche avec les niveaux nécessaires dans un environnement isolé. Ne cherchez pas uniquement la meilleure réponse. Comparez la réussite, le délai, les Tokens, les appels d’outils, les reprises et la validation humaine.

Cochez ensuite votre procédure d’acceptation :

• [ ] Le champ reasoning_effort est envoyé explicitement.
• [ ] Les valeurs non autorisées sont bloquées avant l’appel.
• [ ] Le message assistant complet est conservé en multi-tour.
• [ ] reasoning_content et tool_calls sont préservés lorsque nécessaire.
• [ ] Le premier fragment et le délai total sont mesurés séparément.
• [ ] Les erreurs d’outil et les relances sont comptabilisées.
• [ ] Le coût est calculé par tâche réussie.
• [ ] Une surcharge manuelle existe pour les cas sensibles.
• [ ] Une règle de dégradation rapide est documentée.
• [ ] Une petite phase de grisage précède l’augmentation du volume.

Si votre Agent dépend d’un environnement distant, vérifiez également la continuité de la machine, les permissions, l’accès SSH et la conservation des journaux. Le choix d’un environnement de calcul distant pour un Agent IA fait partie de votre mesure : la stabilité de l’environnement influence le délai total et la reproductibilité des résultats.

Ce que votre choix change en production

Un niveau global fixé sur max simplifie la configuration, mais il présente quatre défauts : les demandes simples attendent plus longtemps, le budget devient moins prévisible, les interactions en temps réel sont moins confortables et les erreurs de routage restent invisibles.

Un niveau global fixé sur low crée le problème inverse. Les tâches multi-outils risquent de perdre des étapes, de produire un plan trop court ou de multiplier les reprises humaines.

La politique la plus lisible pour une équipe repose donc sur trois routes :

• low pour les sorties locales et contrôlables ;
• high pour le travail courant d’un Agent de code ou d’analyse ;
• max pour les exceptions documentées, les longues chaînes et les opérations à fort enjeu.

Votre poste local peut suffire pour des essais ponctuels. Il devient moins pratique lorsque la machine doit rester allumée, conserver plusieurs environnements, exécuter des tests pendant plusieurs heures ou fournir des journaux reproductibles à toute l’équipe. Si votre Mac ne peut pas maintenir cette campagne de comparaison, louer une machine Mac auprès de Hashvps peut vous fournir un environnement isolé pour rejouer les trois tâches, sauvegarder les journaux et choisir un niveau par défaut sur des observations réelles.

Cette solution n’est toutefois pas idéale pour tous les profils. Un achat local reste plus cohérent si vous avez besoin d’un accès physique permanent, d’une charge lourde stable toute l’année ou d’interfaces matérielles spécifiques. Pour un test de courte durée, une validation de migration ou une comparaison avant mise en production, l’environnement distant évite surtout de perturber votre poste principal. Vous pouvez aussi consulter notre guide sur l’architecture des Agents et l’automatisation des flux de travail.

Cette semaine, isolez vos trois tâches représentatives, imposez explicitement low, high et max, puis enregistrez chaque résultat dans le même format. Vous saurez alors si votre Agent doit rester sur low, démarrer sur high ou réserver max aux situations où la réussite vaut réellement le délai et le coût supplémentaires.