Erreurs Kimi K3 avec vLLM en 2026 : vérifier d’abord

La recette officielle Kimi K3 de vLLM impose actuellement une image construite avec CUDA 13, un pilote NVIDIA r580 ou supérieur, ainsi qu’un environnement matériel adapté.

Symptôme → solution la plus rapide : si Kimi K3 ne démarre pas avec vLLM, vérifiez d’abord l’image Docker, le pilote hôte et la version CUDA avant de modifier les paramètres mémoire.
Si le service démarre mais que le cache semble inactif, confirmez explicitement --enable-prefix-caching, l’identité exacte des préfixes et les métriques de cache avant de réduire le contexte.

Cet article s’adresse aux ingénieurs de plateforme qui doivent classer rapidement une erreur à partir des journaux, aux équipes d’agents IA qui réutilisent de longs prompts, et aux responsables d’infrastructure qui doivent décider entre mise à niveau du cluster, reconstruction de l’environnement ou recours temporaire à une capacité déjà validée.

Dernière vérification : 11 août 2026. Les versions, l’étiquette d’image, les prérequis CUDA et le comportement par défaut du cache doivent être revalidés si vLLM publie une nouvelle recette stable.

Le premier journal avant la dernière ligne d’erreur

Une erreur Kimi K3 avec vLLM est rarement expliquée par la dernière ligne affichée dans le terminal. Un RuntimeError, un CUDA out of memory ou un NCCL error peut être la conséquence d’un échec survenu plusieurs dizaines de lignes plus tôt.

Conservez systématiquement les éléments suivants :

• la commande complète docker run ou vllm serve ;
• le nom exact de l’image et son étiquette ;
• la version de vLLM réellement chargée ;
• la sortie complète de nvidia-smi sur chaque nœud ;
• la première exception Python ou CUDA ;
• les variables d’environnement liées à NCCL, RDMA et UCX ;
• le nombre de GPU visibles par le conteneur ;
• le type d’interconnexion : NVLink, réseau Ethernet ou RDMA.

La recette indique actuellement l’image vllm/vllm-openai:kimi-k3, vLLM 0.27.0 ou ultérieur, une construction CUDA 13 uniquement et un minimum de 8 GPU GB300 pour le chemin NVIDIA documenté. Ces éléments proviennent de la recette officielle mentionnée plus haut. Ils servent de frontière de diagnostic, pas de simple rappel de spécifications. La version minimale, l’étiquette d’image et les GPU compatibles peuvent évoluer ; vérifiez-les avant chaque nouvelle mise en production.

Cette grille évite le réflexe le plus coûteux : modifier max-model-len alors que le conteneur utilise une construction CUDA incompatible.

CUDA 13 et pilote r580 contre les faux correctifs

Pourquoi Kimi K3 exige-t-il CUDA 13 et un pilote r580 ou supérieur ?

La recette officielle précise que l’image Kimi K3 est construite uniquement avec CUDA 13. Elle ne fournit pas d’étiquette cu129, et les wheels compatibles Kimi K3 ne doivent pas être remplacées par un index CUDA 12.9 simplement parce qu’une autre version de vLLM y est disponible. Le même document demande un pilote hôte r580 ou plus récent.

La matrice NVIDIA des pilotes et versions CUDA permet de contrôler la relation entre la branche du pilote et le runtime CUDA. La documentation NVIDIA des notes de publication CUDA complète cette vérification pour les composants CUDA 13.

La conséquence opérationnelle est simple : le conteneur peut embarquer son propre runtime CUDA, mais il dépend toujours du pilote chargé par le noyau de l’hôte. Installer un nouveau Toolkit dans le conteneur ne transforme pas un pilote r570 en pilote r580.

Distinguez bien trois couches :

1. Le pilote NVIDIA de l’hôte : il dialogue avec le noyau et expose les capacités du GPU au conteneur.
2. Le runtime CUDA de l’image : il contient les bibliothèques utilisées par vLLM et les opérateurs compilés.
3. Le CUDA Toolkit local : il sert surtout à compiler ou reconstruire des composants ; sa présence sur l’hôte ne corrige pas un pilote trop ancien.

Contrôlez d’abord l’hôte :

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

Puis inspectez l’image réellement exécutée :

docker image inspect vllm/vllm-openai:kimi-k3
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 \
  python -c "import torch; print(torch.__version__); print(torch.version.cuda)"

Deux chemins restent cohérents avec la documentation officielle :

• Mettre à niveau le pilote de l’hôte vers une branche r580 ou ultérieure, puis conserver l’image CUDA 13 validée.
• Reconstruire vous-même l’environnement depuis la branche Kimi K3, avec une combinaison CUDA, PyTorch et vLLM explicitement testée, si la mise à niveau du cluster est impossible.

Évitez le mélange improvisé entre une image générique CUDA 12.9, un wheel nightly ancien et des bibliothèques copiées depuis un autre conteneur. Le démarrage réussi d’un modèle différent ne prouve pas que Kimi K3 puisse charger ses kernels ou son architecture hybride.

Image officielle contre assemblage de dépendances

Lorsque le modèle n’est pas reconnu ou qu’un opérateur manque, commencez par distinguer quatre symptômes :

• unknown model architecture ou classe de modèle absente ;
• ModuleNotFoundError pendant l’import ;
• symbole CUDA ou opérateur FlashInfer introuvable ;
• étiquette d’image inexistante ou impossible à tirer.

Le billet officiel de lancement de Kimi K3 sur vLLM explique que le modèle dépend d’intégrations spécifiques, notamment pour Kimi Delta Attention, le cache hybride, les kernels CUDA et certaines dépendances prépubliées. À la date de cette vérification, l’image Docker officielle reste donc le chemin de référence pour limiter les écarts entre wheel, runtime et extensions.

Procédez dans cet ordre :

1. Relevez l’image exacte avec docker ps --no-trunc.
2. Comparez-la à l’étiquette indiquée dans la recette Kimi K3.
3. Vérifiez que le modèle chargé est bien moonshotai/Kimi-K3.
4. Capturez le traceback complet depuis la première exception.
5. Reproduisez le chargement avec un seul nœud avant de tester le parallélisme distribué.

Ne déduisez pas la cause à partir d’un message trouvé sur un forum concernant un modèle voisin. Les erreurs d’architecture, de chat template et d’opérateurs peuvent se ressembler tout en exigeant des corrections différentes.

Kimi K3 utilise notamment un programme Python pour construire ses séquences de prompt, et non un simple template Jinja classique. Une erreur apparue après l’ajout de --trust-remote-code doit donc être lue avec le traceback complet : elle peut venir du code de génération du prompt, d’un module absent ou d’une incompatibilité de version.

Pour les équipes qui documentent les dépendances du cluster, ajoutez à votre guide d’acceptation des environnements CUDA et pilotes une copie de l’étiquette d’image, de la version vLLM et de la sortie nvidia-smi. Sans cette trace, chaque incident repart de zéro.

Prefix caching activé contre cache réellement réutilisé

Pourquoi le prefix caching de Kimi K3 ne produit-il aucun hit après son activation ?

La première vérification est triviale mais souvent oubliée :

vllm serve moonshotai/Kimi-K3 \
  --enable-prefix-caching \
  --trust-remote-code \
  --load-format fastsafetensors

Le billet officiel de vLLM confirme que Kimi K3 prend en charge le prefix caching, mais que la fonction est actuellement désactivée par défaut pour ce modèle. Le drapeau doit donc être ajouté explicitement. Pour le fonctionnement général du mécanisme, la documentation vLLM sur l’Automatic Prefix Caching rappelle que la réutilisation concerne des blocs de tokens déjà calculés, et non une simple similarité sémantique.

Ensuite, séparez trois situations.

Fonction non activée

Le démarrage ne contient pas --enable-prefix-caching, ou bien la commande exécutée dans le conteneur diffère de celle conservée dans votre fichier de déploiement. Vérifiez les arguments du processus réel :

ps aux | grep vllm
docker inspect <nom_du_conteneur>

Si vous utilisez Kubernetes, inspectez également le manifeste réellement appliqué et non seulement le fichier local :

kubectl get pod <nom_du_pod> -o yaml
kubectl logs <nom_du_pod> --since=30m

Préfixe différent

Deux requêtes visuellement proches ne sont pas nécessairement identiques pour le cache. Contrôlez :

• le message système ;
• l’ordre des messages ;
• les définitions d’outils ;
• les paramètres ajoutés par l’orchestrateur ;
• les images ou pièces jointes ;
• les espaces, marqueurs et tokens de contrôle.

Cette vérification est importante pour les agents, les assistants audio/vidéo et les workflows de design qui injectent souvent des métadonnées variables au début du prompt. Un identifiant de session placé dans le message système peut suffire à empêcher la réutilisation du préfixe.

Politique de conservation KDA

Kimi K3 combine des blocs KV classiques et des états récurrents KDA. vLLM explique que son cache hybride doit conserver des instantanés d’état à certaines positions, au lieu de sauvegarder un état complet à chaque token. Le cache peut donc être activé sans que chaque requête obtienne un hit complet.

Ne concluez pas à l’échec après une seule mesure de latence. Faites au minimum :

1. une première requête avec un préfixe long et stable ;
2. une seconde requête avec le même préfixe et une question finale différente ;
3. une troisième requête avec une modification volontaire du message système ;
4. la comparaison des journaux et métriques de cache ;
5. la vérification de la mémoire consommée avant et après les appels.

Le bon résultat n’est pas nécessairement une division spectaculaire de la latence totale. Le décodage, la file d’attente, la génération et le transfert réseau peuvent rester dominants.

OOM au démarrage contre OOM pendant l’inférence

Comment distinguer un manque de mémoire GPU d’un paramètre trop ambitieux ?

Un OOM au démarrage apparaît pendant le chargement des poids, la création des groupes parallèles ou la réservation initiale du cache. Un OOM pendant l’inférence survient après que le moteur est prêt, généralement lors d’une requête longue, d’une hausse de concurrence ou d’un changement de batch.

Pour un OOM de démarrage, contrôlez :

• les GPU visibles et leur homogénéité ;
• la topologie PCIe ou NVLink ;
• la mémoire déjà occupée ;
• le mode de chargement des poids ;
• --tensor-parallel-size, --pipeline-parallel-size et le backend MoE ;
• les erreurs précédentes dans le journal.

Pour un OOM pendant l’inférence, contrôlez plutôt :

• max-model-len ;
• le nombre de séquences simultanées ;
• la taille des lots ;
• la longueur réelle des prompts ;
• la politique de cache ;
• le type de cache KV ;
• les requêtes multimodales et leurs tenseurs intermédiaires.

La recette officielle décrit Kimi K3 comme un modèle MoE de 2,8 billions de paramètres, avec 16 experts actifs sur 896 et une fenêtre de contexte pouvant atteindre 1 048 576 tokens. Ces chiffres proviennent de la documentation de déploiement Kimi K3. Ils ne constituent pas une promesse de capacité sur votre cluster ; ils expliquent pourquoi une estimation basée sur un petit modèle dense est dangereuse.

Le billet de vLLM documente un chemin de démarrage avec 8 GPU B300 ou une configuration AMD équivalente, tandis que la recette indique au moins 8 GPU GB300 pour le chemin NVIDIA présenté. Utilisez toujours le profil matériel de la recette correspondant à votre génération de GPU, puis validez avec les journaux réels.

Ne réduisez pas immédiatement le contexte maximal. Si le problème vient d’une image inadéquate, d’un parallélisme incohérent ou d’une mémoire déjà occupée par un autre processus, cette modification masque la cause et fragilise la capacité utile du service.

Le contrôle minimal avant toute modification :

nvidia-smi --query-gpu=index,name,memory.total,memory.used,memory.free \
  --format=csv

Ensuite, rejouez une requête courte, puis une requête longue avec une seule variable modifiée à la fois. Si l’OOM disparaît après la baisse de concurrence mais pas après la baisse du contexte, votre première hypothèse doit porter sur le batch ou le nombre de séquences, pas sur la taille maximale du prompt.

NCCL, RDMA et topologie d’interconnexion

Quelle est la bonne méthode pour une erreur NCCL en multi-nœuds ?

Commencez par identifier le réseau réellement utilisé. NVLink et RDMA ne se corrigent pas avec les mêmes paramètres.

La recette officielle recommande :

• deepep_v2 pour un chemin RDMA ;
• flashinfer_nvlink_one_sided pour NVLink ;
• UCX_TLS="rc,cuda_copy" lorsque RDMA doit transporter les transferts de cache KV.

Contrôlez les variables et les interfaces :

env | grep -E 'NCCL|UCX|CUDA_VISIBLE_DEVICES'
ibv_devinfo
ip link
lsmod | grep -E 'mlx5|nvidia_peermem'

Pour les environnements NVLink multi-nœuds, la recette mentionne également les variables liées à MNNVL, notamment NCCL_MNNVL_ENABLE, NCCL_CUMEM_ENABLE et NCCL_NVLS_ENABLE. Ne les copiez toutefois pas dans un cluster RDMA sans vérifier la topologie et la version des composants.

Un cas particulier est documenté pour l’échec d’enregistrement mlx5_dmabuf, parfois accompagné de NCCL error: unhandled system error et de mlx5dv_reg_dmabuf_mr avec l’erreur errno 524. La recette indique alors de désactiver NCCL_DMABUF_ENABLE pour revenir à nvidia_peermem, à condition que le module requis soit chargé sur les nœuds. Il s’agit d’un contournement lié à une condition noyau et pilote précise, pas d’un réglage universel.

Le guide NVIDIA de dépannage NCCL recommande de contrôler la visibilité des GPU, les interfaces réseau, les permissions et les composants d’interconnexion avant de modifier les paramètres collectifs. Appliquez cette logique à Kimi K3 : confirmez d’abord que chaque nœud voit la même topologie et les mêmes périphériques.

Pour éviter un faux diagnostic, exportez les journaux NCCL uniquement pendant le test :

export NCCL_DEBUG=INFO
export NCCL_DEBUG_SUBSYS=INIT,NET

Puis revenez au niveau de journalisation normal une fois la cause isolée. Des journaux trop verbeux conservés en permanence compliquent souvent la lecture des erreurs applicatives et augmentent le volume de collecte.

Pour fermer l’incident, rétablissez la chaîne dans cet ordre :

1. démarrage du moteur sur chaque nœud ;
2. requête minimale via l’API compatible OpenAI ;
3. seconde requête avec préfixe partagé ;
4. test de concurrence contrôlée ;
5. test multi-nœuds avec le backend correspondant à l’interconnexion ;
6. observation prolongée des erreurs NCCL, des retransmissions et de la mémoire.

Le runbook de reprise en cinq étapes

Si vous devez intervenir sous pression, utilisez cette séquence sans la raccourcir :

1. Geler les preuves : commande, image, versions, nvidia-smi, journaux complets et variables d’environnement.
2. Valider l’environnement : image officielle Kimi K3, CUDA 13 et pilote r580 ou ultérieur sur l’hôte NVIDIA.
3. Réduire la surface de test : un nœud, un profil de parallélisme documenté et une requête minimale.
4. Classer l’échec : chargement, opérateur, OOM, cache ou communication ; ne corrigez qu’une couche à la fois.
5. Rejouer les mêmes tests : démarrage, requête courte, préfixe répété, concurrence, puis multi-nœuds.

Pour les équipes qui ne peuvent pas encore modifier leur cluster, comparez le coût d’une reconstruction complète avec celui d’un environnement temporaire déjà contrôlé. La console MacHTML peut servir à tester l’orchestration, les clients API, les chaînes d’agents et les intégrations audio, vidéo ou design autour d’un endpoint distant. Elle ne remplace pas les GPU NVIDIA requis pour servir Kimi K3 lui-même, mais elle peut isoler la couche applicative pendant que l’équipe corrige le cluster d’inférence.

Si votre environnement actuel repose sur un ancien pilote, des images CUDA mélangées et une topologie multi-nœuds mal documentée, vous payez trois fois : temps d’investigation, capacité GPU immobilisée et risque de régression à chaque mise à jour. Le déploiement direct sur un cluster existant reste pertinent pour une charge stable et maîtrisée, mais il devient un mauvais choix lorsque vous devez livrer rapidement un prototype d’agent, tester un pipeline multimodal ou attendre une fenêtre de maintenance.

Dans ce cas, louer temporairement une capacité MacHTML pour les composants compatibles, les tests d’API et la validation de votre chaîne applicative permet de ne pas continuer à modifier à l’aveugle les nœuds Kimi K3 non conformes. La décision doit rester technique : utilisez le GPU validé pour l’inférence du modèle, et une capacité temporaire séparée pour les couches d’intégration qui n’ont pas besoin de CUDA 13.