Kimi K3 vLLM OOM : régler ou étendre ?

Le processus s’arrête pendant le chargement des poids avec une erreur de mémoire ? Ne perdez pas du temps à réduire la concurrence : vérifiez d’abord l’environnement et la topologie.

Le serveur démarre, mais tombe en OOM au premier trafic ou lors des longues sessions Agent ? Réduisez alors le contexte, la concurrence ou la rétention du cache, puis mesurez à nouveau sur les mêmes requêtes avant de décider d’étendre.

À qui s’adresse ce diagnostic ?

Ce guide s’adresse aux chercheurs et équipes POC qui veulent savoir si leur environnement suffit pour valider une API, un appel d’outil ou une chaîne de raisonnement.

Il concerne aussi les petites équipes Agent qui doivent préserver les préfixes réutilisés, ainsi que les équipes plateforme qui hésitent entre optimisation du cluster existant, migration vers une topologie conforme ou extension temporaire.

Dernière mise à jour : 16 août 2026. Les éléments techniques ont été vérifiés dans la recipe officielle Kimi K3 de vLLM, mise à jour le 14 août 2026, et dans le billet officiel de vLLM consacré à Kimi K3.

Le premier tri : chargement des poids contre exécution des requêtes

Un message « out of memory » ne donne pas encore la décision. Vous devez relever l’endroit exact du journal où l’échec se produit.

Le critère le plus utile est simple :

• le modèle a-t-il terminé son initialisation ?
• le point de terminaison répond-il à une première requête ?
• l’erreur apparaît-elle seulement lorsque le trafic réel commence ?

Un OOM avant la fin de l’initialisation ne se corrige habituellement pas en abaissant la concurrence. Les poids, les structures du moteur et les allocations nécessaires au démarrage doivent déjà tenir dans la configuration disponible. À l’inverse, un OOM après le démarrage peut être lié au contexte, aux sessions simultanées, au cache KV ou aux états spécifiques de Kimi K3.

Kimi K3 est un modèle MoE multimodal de 2,8 billions de paramètres, avec 16 experts actifs parmi 896 et une fenêtre de contexte annoncée jusqu’à 1 million de jetons. Ces chiffres décrivent l’architecture ; ils ne constituent pas une formule universelle pour déduire votre capacité de production. (recipe officielle Kimi K3)

Point de contrôle : un serveur qui démarre avec une requête courte prouve seulement que le chemin minimal fonctionne. Il ne prouve ni la capacité nominale, ni la stabilité sous concurrence, ni la marge nécessaire aux reprises d’un agent.

Pour le chercheur ou le POC : valider le chemin avant de simuler la production

Votre objectif est généralement de vérifier quatre éléments : l’API compatible, le rendu du modèle, les appels d’outils et la cohérence de la chaîne de raisonnement. Vous n’avez pas encore besoin de reproduire le débit d’un service public.

Dans ce cas, adoptez une validation par réduction contrôlée :

1. Figez l’image et le dépôt du modèle. Notez le nom exact de l’image, la version de vLLM, le modèle utilisé et le format de chargement.
2. Vérifiez le chemin matériel officiel. La recipe actuelle indique une image kimi-k3 construite uniquement pour CUDA 13 et demande un pilote NVIDIA R580 ou ultérieur sur le chemin NVIDIA. Elle décrit également un minimum de huit GPU GB300 pour cette configuration, tandis que le chemin AMD repose sur des GPU MI355X ou MI350X. (prérequis matériels et logiciels officiels)
3. Réduisez la longueur de test. Utilisez des prompts courts, puis augmentez progressivement le contexte. Ne transformez pas la première valeur fonctionnelle en promesse de capacité.
4. Limitez la concurrence à une seule session. Cette étape isole le chargement, le préremplissage et le décodage avant d’introduire les interactions entre requêtes.
5. Désactivez les variables non nécessaires à la preuve. Ne testez pas simultanément l’appel d’outil, la vision, le cache, la spéculation et un trafic parallèle.
6. Conservez le premier résultat exploitable. Notez la fin d’initialisation, la réponse à la première requête, le pic mémoire et le journal complet.
7. Arrêtez l’optimisation lorsque le problème est structurel. Si les poids ne se chargent pas dans une topologie officiellement prise en charge, migrez vers un environnement conforme au lieu d’essayer indéfiniment des options de mémoire.

Le bon résultat pour un POC n’est donc pas « le modèle tient dans n’importe quelle machine ». C’est : le parcours fonctionnel est reproductible dans un environnement identifié, avec une charge minimale documentée.

Pour conserver vos versions, variables et commandes, centralisez vos paramètres dans un espace de travail contrôlé, puis consultez la console MacHTML si vous avez besoin de comparer plusieurs environnements de test sans modifier votre cluster principal.

Pour une petite équipe Agent : réduire la charge sans détruire la réutilisation

Les applications Agent rendent le diagnostic plus délicat. Un tour de conversation peut répéter le message système, les définitions d’outils, un extrait de dépôt, des instructions de sécurité et les résultats de plusieurs actions. Ces éléments augmentent le contexte, mais certains sont aussi de bons candidats à la réutilisation.

C’est ici que prefix caching devient une variable de décision, et non un simple bouton à activer ou à couper. Le billet officiel précise que la prise en charge du cache de préfixe pour l’architecture hybride de Kimi K3 nécessite une gestion conjointe de l’état récurrent KDA et du cache d’attention. La fonction est prise en charge, mais la recipe indique qu’elle doit être activée explicitement ; elle n’est donc pas à considérer comme active par défaut. (prise en charge du prefix caching dans vLLM)

La comparaison doit porter sur le même jeu de requêtes :

Ne concluez pas à partir d’une seule invite courte. Faites rejouer :

• un message système identique ;
• les mêmes définitions d’outils ;
• plusieurs tours de conversation ;
• des résultats d’outils de taille réaliste ;
• une session longue avec interruption puis reprise ;
• un mélange de requêtes courtes et longues.

Le billet vLLM présente deux politiques de rétention adaptées aux charges Agent : des points de contrôle périodiques et une rétention sélective lorsqu’un préfixe est observé plusieurs fois. Il indique notamment que l’intervalle de rétention peut être contrôlé par VLLM_PREFIX_CACHE_RETENTION_INTERVAL, avec une valeur nulle qui conserve les états de fin de prompt et désactive les points de contrôle périodiques. Ce réglage doit être validé sur votre distribution réelle, pas copié comme une recette universelle. (détails des politiques de rétention)

La checklist de décision pour votre service Agent

• [ ] Le moteur termine son initialisation avant toute charge parallèle.
• [ ] Le test inclut le message système réellement utilisé.
• [ ] Les définitions d’outils et leurs résultats sont représentés.
• [ ] Le contexte maximal attendu est mesuré séparément du contexte moyen.
• [ ] Le prefix caching est testé activé puis désactivé sur le même jeu de requêtes.
• [ ] Le taux de hit est enregistré avec le pic de mémoire, et non isolément.
• [ ] La concurrence nominale et la concurrence de pointe sont distinguées.
• [ ] Une marge reste disponible après les reprises et les requêtes longues.
• [ ] Une réduction de concurrence acceptable pour le produit est explicitement définie.
• [ ] L’extension est déclenchée si la stabilité dépend d’une limite artificiellement basse.

Si le cache améliore la réutilisation mais pousse la mémoire au-delà de la marge acceptable, vous pouvez étudier une politique de rétention moins agressive. Si le cache ne produit presque aucun hit sur vos requêtes, le conserver uniquement pour des raisons théoriques n’a pas de sens. Dans les deux cas, mesurez le compromis entre mémoire, recalcul et stabilité.

Questions fréquentes avant de modifier le cluster

Un OOM pendant le chargement peut-il être résolu par des paramètres ?

Pas si l’échec survient avant l’initialisation complète du moteur. La concurrence ne consomme pas encore la mémoire de service de la même manière qu’après le démarrage. Vérifiez d’abord la chaîne CUDA 13, le pilote R580 ou ultérieur, l’image officielle et la topologie. Si le chemin matériel n’est pas conforme, le test doit être déplacé avant toute optimisation fine.

Que faire quand le prefix caching provoque une pression mémoire ?

Comparez la mémoire et les hits sur des requêtes identiques, puis examinez la politique de rétention. Pour des agents à préfixes très répétitifs, supprimer tout le cache peut augmenter le recalcul et dégrader la stabilité temporelle. Pour des prompts presque toujours uniques, une rétention importante peut immobiliser de la mémoire sans bénéfice. La décision doit suivre la distribution réelle des requêtes.

Contexte long : réduire la concurrence ou ajouter des GPU ?

Pour un POC, réduisez d’abord la concurrence afin de prouver le parcours fonctionnel. Pour une production, cette réduction n’est acceptable que si elle correspond au contrat de service. Si les conversations longues, les sessions simultanées et les reprises dépassent durablement la marge, l’extension devient préférable. La topologie de parallélisme et le réseau doivent toutefois être vérifiés avant de compter les GPU.

Faut-il reconstruire l’environnement soi-même ?

La reconstruction peut servir de voie de secours lorsque vous contrôlez le pilote hôte, l’image et le réseau. Elle devient risquée si vous ne pouvez modifier que le conteneur. La recipe précise que l’image Kimi K3 actuelle est CUDA 13 uniquement ; un hôte CUDA 12.9 associé à un pilote R575 exige une mise à niveau du pilote ou une construction spécifique depuis la branche K3. Cette dernière voie accroît la charge de maintenance. (compatibilité CUDA et pilotes)

Quel signal indique qu’une extension est devenue nécessaire ?

Le signal n’est pas seulement l’OOM. Une extension est justifiée lorsque la charge nominale exige une concurrence réduite, que les pics approchent régulièrement la limite, que les files d’attente s’allongent ou qu’une reprise après erreur consomme toute la marge. Rejouez un échantillon réaliste et conservez les journaux. Si la limite artificielle nécessaire au fonctionnement est incompatible avec le trafic attendu, l’optimisation a atteint sa limite.

Pour une équipe plateforme : compatibilité avant capacité

Une équipe qui possède déjà un cluster ne doit pas reprendre toute l’installation depuis zéro. Elle doit d’abord déterminer ce qu’elle peut réellement contrôler.

Posez ces questions dans l’ordre :

1. Pouvez-vous mettre à niveau le pilote des hôtes, ou seulement reconstruire l’image ?
2. Pouvez-vous utiliser l’image officielle vllm/vllm-openai:kimi-k3 ?
3. Les nœuds disposent-ils d’une interconnexion adaptée au parallélisme retenu ?
4. Pouvez-vous configurer le backend all-to-all et les variables réseau ?
5. Pouvez-vous faire évoluer la répartition entre préremplissage et décodage ?
6. Pouvez-vous rejouer la même charge après chaque changement ?

La recipe officielle recommande deepep_v2 pour la communication RDMA et flashinfer_nvlink_one_sided pour NVLink. Elle précise également que certains chemins MoE ne sont pas compatibles avec le RDMA inter-nœuds. Ces indications montrent pourquoi l’ajout mécanique de GPU ne suffit pas : deux configurations ayant le même nombre de cartes peuvent présenter des comportements très différents selon le réseau et le backend. (recommandations officielles de topologie)

Le billet vLLM présente aussi des profils de parallélisme expert et une séparation préremplissage/décodage pour les déploiements à haut débit. Cette séparation permet de dimensionner différemment les phases dominées par l’entrée et celles dominées par la génération, mais elle introduit des exigences supplémentaires sur le transfert d’état et la communication entre nœuds.

Si votre équipe ne contrôle ni le pilote hôte ni le réseau, construisez un dossier de décision plutôt qu’un environnement fragile :

• incompatibilité de version confirmée ;
• capacité de mémoire insuffisante ;
• réseau inadapté ;
• cache trop coûteux ;
• concurrence irréaliste ;
• absence de marge pour les reprises.

Consignez la version du conteneur, le pilote, la construction CUDA, les options de lancement et les journaux. Le centre d’aide MacHTML peut compléter cette documentation lorsque vous devez préparer une migration ou une validation à distance.

Pour la production : l’extension doit suivre le trafic cible

Une production Kimi K3 ne se valide pas avec « le serveur démarre ». Vous devez définir le trafic que le système doit absorber :

• longueur moyenne et maximale des contextes ;
• nombre de sessions simultanées ;
• fréquence des tours Agent ;
• taille des définitions et résultats d’outils ;
• part des préfixes réutilisés ;
• délai acceptable après une reprise ;
• marge mémoire nécessaire pendant les pointes.

La documentation vLLM décrit plusieurs chemins, dont le tensor parallelism, l’expert parallelism et la séparation préremplissage/décodage. Elle indique aussi que les compromis changent selon l’objectif : le parallélisme tensoriel favorise l’interactivité, alors que des configurations expertes à grande échelle peuvent dépendre fortement de la bande passante réseau. Vous ne pouvez donc pas extrapoler une capacité à partir du seul nombre de GPU.

Pour une équipe de production, appliquez cette règle :

• Le modèle ne charge pas : corrigez ou changez l’environnement.
• Le modèle charge, mais la charge réduite échoue : ne concluez pas à un simple problème de concurrence ; revérifiez la capacité et la topologie.
• La charge réduite réussit, la charge nominale échoue : mesurez contexte, concurrence et cache sur un jeu représentatif.
• La charge nominale réussit sans marge : préparez l’extension avant l’incident.
• La charge nominale réussit avec marge et suivi : conservez l’environnement, mais automatisez la régression après chaque mise à jour de vLLM.

Les chiffres de performance publiés par vLLM doivent être lus avec leur topologie. Le billet rapporte notamment 118 jetons par seconde sans spéculation et 370 jetons par seconde avec DSpark, mesurés sur 16 GPU GB300 NVL72 dans un test spécifique. Ces résultats ne sont pas transposables directement à votre réseau, votre longueur de contexte ou votre distribution Agent. (résultats publiés et topologie de test)

Transformer le résultat en réglage, migration ou extension

À la fin de la campagne, produisez une fiche courte mais exploitable :

• image et version de vLLM ;
• pilote et chaîne CUDA ;
• type de matériel ;
• nombre de nœuds et interconnexion ;
• paramètres de parallélisme ;
• état du prefix caching ;
• politique de rétention ;
• jeu de requêtes ;
• concurrence testée ;
• pic de mémoire ;
• erreurs observées ;
• marge restante ;
• date du test.

Une validation temporaire sur une capacité livrée par période peut être utile lorsque votre cluster mélange plusieurs incertitudes. Rejouez exactement les mêmes requêtes dans un environnement conforme, avec les mêmes paramètres applicatifs. Vous saurez alors si votre cluster souffre d’une incompatibilité de chaîne, d’une topologie réseau inadéquate ou d’un manque de mémoire réellement lié à la charge.

Cette méthode est souvent moins risquée qu’une mise à niveau directe de l’infrastructure de production. Elle vous donne un point de comparaison avant de modifier le pilote, l’image ou la distribution des nœuds. Les capacités MacHTML disponibles pour une validation temporaire peuvent servir de point de départ ; vérifiez toutefois que la configuration livrée correspond bien au chemin Kimi K3 que vous souhaitez reproduire.

Quand le réglage cesse d’être le bon choix

Le réglage reste pertinent lorsque votre objectif est limité : démonstration fonctionnelle, POC, intégration d’outils ou petit service interne. Dans ce cas, réduire le contexte et la concurrence peut être un compromis parfaitement rationnel.

Il devient moins pertinent lorsque :

• la réduction de contexte supprime des informations nécessaires à l’agent ;
• la concurrence doit rester sous le niveau attendu par le produit ;
• le prefix caching est supprimé alors que les préfixes sont fortement réutilisés ;
• les reprises après erreur ne laissent aucune marge ;
• le modèle ne charge pas dans le chemin officiellement pris en charge ;
• le réseau empêche le parallélisme prévu ;
• chaque mise à jour exige une reconstruction manuelle non reproductible.

L’extension n’est pas automatiquement la solution non plus. Si le problème vient d’un pilote trop ancien, d’une image inadaptée ou d’un backend réseau mal choisi, ajouter des GPU peut seulement augmenter le coût et la complexité. La bonne séquence est donc : compatibilité, reproduction, charge cible, marge, puis extension.

Si votre cluster actuel ne permet pas de séparer clairement incompatibilité d’environnement et capacité insuffisante, louez d’abord une capacité conforme pour rejouer le même scénario Kimi K3. Vous éviterez de sacrifier les paramètres métier à un matériel qui ne correspond pas au chemin officiel, tout en obtenant des données comparables pour décider entre mise à niveau, migration et extension durable.

FAQ