Reproduire une erreur Kimi K3 avec vLLM en 2026

Une modification du pilote produit une erreur CUDA, un changement d’image fait apparaître un OOM, puis l’activation du cache déclenche un problème de communication : le diagnostic est devenu inexploitable.

La solution la plus rapide consiste à arrêter les changements simultanés, à figer l’hôte, l’image, la commande de démarrage et la requête, puis à reproduire dans cet ordre : compatibilité de base, démarrage minimal, requête unique, fonctionnalité isolée.

Calendrier recommandé cette semaine : le premier jour sert à conserver la scène d’échec, le deuxième à vérifier CUDA 13 et le pilote, puis chaque session suivante ne modifie qu’un paramètre. Si la combinaison officiellement compatible ne reproduit pas le problème de manière stable, passez à un nœud de test isolé au lieu de continuer à modifier le cluster partagé.

Cet article s’adresse aux ingénieurs infrastructure qui ont déjà changé plusieurs fois l’image ou le pilote de Kimi K3, aux équipes de plateformes Agent qui doivent documenter un OOM ou un problème de cache, et aux responsables qui doivent arbitrer entre plusieurs heures de diagnostic dans le cluster existant et une location temporaire de calcul isolé.

Dernière mise à jour : 9 août 2026. Les paramètres d’image, de pilote, de matériel et de cache ont été vérifiés dans la recipe officielle Kimi K3 de vLLM, mise à jour le 6 août 2026, ainsi que dans le billet technique officiel sur le support Kimi K3.

Le premier objectif n’est pas le succès, mais un échec stable

Lorsque chaque démarrage échoue différemment, la tentation est de réduire la longueur de contexte, d’augmenter le nombre de GPU, de remplacer l’image et de modifier le pilote dans la même fenêtre d’intervention. Cette stratégie peut parfois faire démarrer le service, mais elle détruit la chaîne de causalité.

Trois coûts cachés apparaissent immédiatement :

• Le coût de diagnostic : si l’image, le pilote et les paramètres changent ensemble, il devient impossible d’attribuer la nouvelle erreur à une seule cause.
• Le coût de comparaison : deux journaux provenant de deux images différentes ne constituent pas une série de reproduction exploitable.
• Le coût de partage du cluster : un GPU occupé, une configuration NCCL héritée ou un montage de conteneur modifié peuvent faire croire à un problème Kimi K3 alors que l’environnement n’est plus identique.

Il faut également distinguer trois phases qui sont souvent mélangées :

1. l’initialisation du conteneur et la visibilité des GPU ;
2. le chargement des poids et l’initialisation du moteur ;
3. le traitement d’une requête après le démarrage de l’API.

Un OOM survenant pendant la réservation de mémoire n’a pas la même signification qu’un OOM apparu après l’ajout d’un long contexte. De même, une erreur CUDA avant le chargement du modèle doit être traitée avant toute analyse de prefix caching.

Quels paramètres faut-il figer lorsque chaque lancement de Kimi K3 produit un message différent ?

Nous recommandons de conserver, avant toute nouvelle modification :

• le nom exact de l’image Docker et son identifiant immuable ;
• la version réellement chargée par le pilote sur l’hôte ;
• la sortie de nvidia-smi sur l’hôte et dans le conteneur ;
• la commande complète de lancement, y compris les variables d’environnement ;
• le nombre et l’ordre logique des GPU exposés au conteneur ;
• le premier bloc d’erreur, et non uniquement les dernières lignes ;
• une requête représentative, son nombre de tokens approximatif et la limite de sortie ;
• l’heure de chaque changement et la possibilité de revenir à l’état précédent.

Le but de cette collecte n’est pas de constituer immédiatement un dossier complet pour l’amont. Il s’agit d’obtenir une première exécution dont le point de rupture reste identique.

Le socle compatible doit être vérifié avant les paramètres du modèle

Au 9 août 2026, la recette officielle de vLLM indique que l’image dédiée à Kimi K3 est fournie uniquement avec une construction CUDA 13, ou cu130. La même page indique qu’un pilote NVIDIA hôte r580 ou supérieur est requis pour cette combinaison ; un hôte resté en r575 ne doit donc pas être traité comme une base équivalente simplement parce que le paquet CUDA est installé dans le conteneur. (recipe officielle Kimi K3)

La recette officielle précise également une exigence matérielle minimale de 8 GPU GB300 pour le profil NVIDIA documenté. Cette limite concerne la recette publiée, pas une estimation générale de la mémoire nécessaire pour tous les profils possibles. Les estimations communautaires d’un seuil de mémoire global ne doivent pas être utilisées comme preuve de compatibilité. (recipe officielle Kimi K3)

Comment confirmer qu’un changement de pilote n’utilise pas encore une ancienne version ?

Il ne suffit pas de vérifier que le nouveau paquet est installé. Nous exécutons nvidia-smi directement sur l’hôte, puis dans un conteneur lancé avec les mêmes options GPU que le service. La commande expose notamment la version du pilote et la version CUDA supportée par le pilote ; ces informations décrivent la couche effectivement chargée, et non seulement les paquets présents sur le disque.

Un contrôle minimal peut ressembler à ceci :

nvidia-smi
nvidia-smi -L

docker run --rm --gpus all \
  vllm/vllm-openai:kimi-k3 \
  nvidia-smi

Le guide officiel du NVIDIA Container Toolkit fournit la logique de validation de cette étape. Si l’hôte voit les GPU mais que le conteneur n’en voit aucun, il faut d’abord examiner le runtime et NVIDIA_VISIBLE_DEVICES, plutôt que modifier les paramètres de mémoire du modèle.

La différence entre un paquet installé et une bibliothèque réellement chargée est une source fréquente d’erreur après mise à niveau. Un redémarrage incomplet, un nœud qui n’a pas reçu le même pilote ou une image utilisant encore une couche mise en cache peuvent produire une apparence de mélange de versions. Pour cette raison, nous enregistrons les sorties de contrôle au même moment que le lancement du conteneur.

Une commande minimale permet d’identifier le premier stade défaillant

Le démarrage initial doit être volontairement pauvre. Nous retirons l’agent, les outils, le script de pression, le système de reprise automatique et les options de performance qui ne sont pas indispensables à l’ouverture du moteur.

La commande de référence doit conserver uniquement le modèle et les options nécessaires au profil Kimi K3 documenté. Le billet officiel de vLLM montre notamment l’usage de --tensor-parallel-size 8, --trust-remote-code et --load-format fastsafetensors, tandis que l’activation de --enable-prefix-caching apparaît explicitement dans l’exemple de démarrage. (billet technique officiel vLLM)

Pour une première reproduction, nous séparons toutefois le socle du test de cache :

vllm serve moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --load-format fastsafetensors \
  --max-model-len <valeur-fixée>

La valeur de contexte doit rester identique entre deux essais. Si elle n’est pas indispensable à la reproduction, nous la choisissons modestement et nous la documentons, sans prétendre corriger le problème de fond.

Le journal doit être lu dans l’ordre suivant :

Si l’échec apparaît pendant l’initialisation CUDA, il est prématuré d’analyser le nombre de préfixes réutilisés. Si le moteur ne réserve pas sa mémoire, un réglage de concurrence ne constitue pas encore une preuve de correction.

Pour les erreurs d’outillage, de mémoire ou de communication, utilisez ensuite le guide officiel de dépannage vLLM et ne mélangez pas ses variables de diagnostic avec celles du test de base. Les options ajoutées pour déboguer doivent être retirées après l’essai, faute de quoi elles peuvent modifier le comportement d’une session ultérieure.

La requête unique sépare le démarrage du comportement en production

Un serveur qui atteint l’état « prêt » n’est pas nécessairement stable. Il faut maintenant envoyer une seule requête, avec un contenu fixe, une limite de sortie fixe et le même chemin d’appel à chaque tentative.

Pour une équipe travaillant sur de l’audio, de la vidéo ou du design, l’échantillon peut être un court brief créatif ou une image de référence, mais il doit rester strictement identique. Une requête texte lors d’un essai et une requête multimodale lors du suivant ne permettent pas de comparer l’allocation mémoire.

Nous fixons au minimum :

• le modèle demandé dans l’API ;
• le contenu et l’ordre des messages ;
• la limite de sortie ;
• la température et les paramètres d’échantillonnage ;
• le délai d’attente ;
• le nombre de requêtes simultanées, égal à un pour la base.

Comment distinguer un OOM racine d’un OOM provoqué par une erreur CUDA précédente ?

Nous regardons la position de l’OOM dans la chronologie. Si le moteur échoue avant que tous les GPU soient visibles ou avant la fin de l’initialisation des bibliothèques, l’OOM peut être une conséquence secondaire d’un état CUDA incomplet, d’un mauvais runtime ou d’une allocation déjà réservée. Si le serveur démarre, accepte la requête unique, puis échoue uniquement après une augmentation contrôlée du contexte ou de la concurrence, l’hypothèse mémoire devient plus solide.

La comparaison doit donc conserver les preuves suivantes :

Pour la reproductibilité du résultat, les attentes doivent rester réalistes. vLLM indique que la reproductibilité dépend notamment du même matériel et de la même version, et que le comportement en ligne peut varier avec la planification des requêtes. Le guide officiel de reproductibilité vLLM explique également le rôle de la graine et des mécanismes d’invariance par lot.

Nous ne qualifions donc pas une exécution de « stable » parce qu’elle a réussi une fois. Nous répétons le même test dans la même fenêtre d’environnement et nous vérifions que le stade d’échec, ou le stade de succès, reste comparable.

Les fonctionnalités doivent être réintroduites une par une

Le prefix caching ne doit pas être ajouté au premier test si l’objectif est de savoir si le modèle peut simplement s’initialiser. En revanche, il doit être inclus dans une étape dédiée dès que la requête unique fonctionne, car Kimi K3 ne doit pas être évalué avec l’hypothèse d’un cache actif par défaut.

La recette officielle indique que le cache de préfixe doit être activé explicitement. Le billet technique décrit par ailleurs un mécanisme hybride qui doit gérer à la fois l’état récurrent et les blocs de cache d’attention ; un succès de démarrage ne prouve donc pas encore qu’un préfixe partagé est effectivement réutilisé. (recipe officielle Kimi K3)

La séquence de retour est la suivante :

1. démarrer sans prefix caching ;
2. vérifier une requête unique ;
3. ajouter uniquement --enable-prefix-caching ;
4. envoyer deux requêtes partageant exactement le même préfixe ;
5. observer les métriques ou journaux de cache disponibles ;
6. conserver le reste de la commande inchangé ;
7. revenir à l’étape précédente si l’erreur change.

Le prefix caching doit-il figurer dans la commande minimale ?

Il doit figurer dans la reproduction minimale de l’incident lorsque l’incident dépend du cache, mais pas dans la base destinée à vérifier CUDA, le pilote ou le chargement des poids. Cette distinction évite de transformer une commande de référence en commande de production complète.

Nous ajoutons ensuite le contexte long, puis la concurrence, puis la configuration multi-nœuds. Pour chaque ajout, nous conservons une seule question : le service démarre-t-il, le cache produit-il le signal attendu, la mémoire échoue-t-elle ou la communication devient-elle instable ? Si le type d’erreur change, nous revenons au dernier niveau stable avant de poursuivre.

La checklist de remise en état rend la décision transmissible

Avant de demander une correction à une autre équipe, nous validons la base suivante :

• [ ] Image Docker identifiée par son nom et son identifiant immuable.
• [ ] Version vLLM enregistrée depuis l’environnement réellement exécuté.
• [ ] Sortie nvidia-smi conservée sur l’hôte et dans le conteneur.
• [ ] GPU visibles et nombre de GPU vérifiés avec nvidia-smi -L.
• [ ] Commande minimale copiée sans troncature.
• [ ] Variables d’environnement listées séparément de la commande.
• [ ] Premier bloc d’erreur conservé avec son horodatage.
• [ ] Requête unique enregistrée avec ses paramètres.
• [ ] Une seule variable modifiée entre deux essais.
• [ ] Point de retour identifié après chaque essai.
• [ ] Activation de prefix caching testée dans une étape dédiée.
• [ ] Contexte et concurrence augmentés seulement après validation de la requête unique.
• [ ] Résultat comparé sur le même nœud ou sur un nœud dont l’empreinte est documentée.

Ce paquet est plus utile qu’un journal de plusieurs gigaoctets issu d’une semaine de modifications. Il permet au responsable de plateforme de décider si le problème relève de la compatibilité CUDA, de l’allocation mémoire, du cache, du réseau GPU ou de la couche applicative.

Le résultat de la reproduction détermine la suite

Trois situations doivent être distinguées.

Le même échec apparaît dans la même phase. La reproduction est exploitable. Nous pouvons alors ouvrir le chantier spécialisé correspondant, en joignant la commande, l’empreinte d’environnement et la requête.

L’échec est devenu intermittent dans le cluster d’origine. Nous ne modifions plus le modèle au hasard. Nous vérifions l’occupation des GPU, les montages, le runtime et les variables héritées, puis nous lançons le même test sur un nœud réservé.

La base officiellement compatible ne reproduit plus le problème. Il faut cesser d’utiliser l’ancien cluster comme preuve. Une différence d’image, de pilote, de matériel ou de communication peut avoir supprimé ou déplacé le défaut.

Quand faut-il abandonner le cluster d’origine au profit d’un environnement de test ?

Le changement devient rationnel lorsque les versions ne peuvent pas être gelées, que d’autres tâches occupent les GPU, qu’un retour arrière est impossible ou que chaque essai ajoute une nouvelle modification. Dans ce cas, l’objectif n’est pas de masquer le problème, mais de réaliser une comparaison contrôlée sur une machine où l’image, le pilote, le nombre de GPU et la commande peuvent rester identiques.

Si l’équipe doit continuer à servir des tâches audio, vidéo ou de design pendant le diagnostic, une capacité isolée évite que les essais de contexte ou de concurrence perturbent les travaux existants. Nous recommandons de préparer d’abord le paquet de reproduction, puis de louer l’environnement temporaire, plutôt que de déplacer un déploiement non documenté et de perdre la comparaison.

Le coût réel oppose le cluster partagé à l’environnement isolé

Nous ne conseillons pas la location pour une charge longue et prévisible qui nécessite une infrastructure permanente, ni pour une installation dépendant d’interfaces physiques particulières. En revanche, lorsque le problème est précisément l’impossibilité de figer l’environnement, un nœud isolé peut coûter moins cher qu’une suite d’essais non comparables et qu’une interruption de tâches déjà planifiées.

Pour estimer cette alternative, consultez les options de location de calcul Mac proposées par JexMac, puis vérifiez dans le centre d’aide JexMac les modalités d’accès et de remise en état avant de réserver une période de test.

La décision finale doit rester technique : si l’erreur ne survient plus dans l’environnement isolé, comparez les empreintes au lieu de déclarer le problème résolu ; si elle réapparaît au même stade, vous disposez enfin d’une base transmissible ; si elle disparaît uniquement après avoir supprimé les paramètres de production, vous avez identifié une variable à réintroduire séparément.

Lorsque le cluster actuel ne permet ni de geler les versions ni d’éviter les interférences d’autres tâches, l’approche la plus propre consiste donc à conserver la commande minimale, l’empreinte CUDA et le journal du premier échec, puis à effectuer une reproduction contrôlée sur une capacité JexMac isolée. Cela ne remplace pas une infrastructure de production correctement conçue, mais offre un cadre plus fiable pour décider ensuite s’il faut corriger le cluster, mettre à niveau le pilote ou revoir les paramètres de Kimi K3.