TL;DR
Déployez Kimi K3.1 Pro sur un serveur GPU Linux, puis connectez une application locale à son endpoint d’inférence. Ce guide utilise un nœud NVIDIA B300 à huit GPU avec vLLM. Vous aurez besoin d’un accès shell au serveur, de pilotes compatibles et d’un espace de stockage pour l’intégralité du checkpoint. Commencez par réussir une requête texte courte avant de tester des entrées plus longues ou des workflows d’agent.
Sans GPU adaptés, vous pouvez exécuter votre application localement et la connecter à l’API Kimi officielle ou à un fournisseur tiers comme CometAPI.
Points clés
- Les 104B paramètres actifs du modèle ne correspondent pas à ses besoins de stockage complets.
- La compatibilité matérielle couvre la mémoire GPU, les interconnexions, la prise en charge de la quantification et les kernels d’inférence.
- D’excellents résultats de benchmark valent l’essai, sans garantir des performances équivalentes dans votre application.
- Un endpoint d’inférence fonctionnel n’inclut pas automatiquement un navigateur, un bac à sable de code ou un runtime d’agent complet.
- Comparez l’auto-hébergement et l’accès via API par le coût par tâche réussie, y compris les reprises et la maintenance.
Qu’est-ce que Kimi K3.1 Pro ?
Kimi K3.1 Pro est le modèle multimodal à poids ouverts de Moonshot AI pour le code, l’analyse de documents et l’usage d’outils. Ses principales spécifications sont listées ci-dessous, d’après la fiche du modèle officielle .
Le modèle active 104B paramètres par jeton, mais le déploiement requiert toujours le checkpoint complet de 2,8T paramètres. Le moteur d’inférence doit également prendre en charge ses couches KDA et Gated DSA, ainsi que la quantification MXFP4.
Quel matériel est nécessaire pour exécuter Kimi K3.1 Pro en local ?
Le tableau ci-dessous récapitule les configurations vLLM pertinentes pour ce guide. Le pas-à-pas utilise un nœud B300 à huit GPU ; les déploiements GB300 et AMD exigent leurs configurations correspondantes.
Pour l’échelle uniquement, 2,8T paramètres occuperaient environ 5,6 To en BF16, 2,8 To en huit bits, ou 1,4 To dans un hypothétique quatre bits. Ce sont des calculs bruts de stockage de paramètres, pas des tailles réelles de checkpoints ni des minima VRAM à l’exécution. La précision mixte et les métadonnées modifient la taille des fichiers ; le cache et les allocations runtime augmentent les besoins en service.
Réservez de la capacité NVMe pour le téléchargement complet, les fichiers temporaires et une copie de rollback. Sur des systèmes multi-nœuds, validez la communication avant de charger le modèle.
Comment déployer Kimi K3.1 Pro
Utilisez l’auto-hébergement si vous avez le matériel adapté ; sinon, commencez avec une API hébergée. Les étapes ci-dessous utilisent vLLM, avec SGLang en alternative en fin de section. Comparez les coûts d’hébergement une fois une requête fonctionnelle établie.
Exécutez les commandes d’installation, de téléchargement, de lancement et de vérification initiale dans un shell Bash sur le serveur GPU. Si vous travaillez depuis un portable, connectez-vous d’abord au serveur via SSH. Le client Python pourra ensuite tourner sur l’une ou l’autre machine en suivant les instructions de connexion ci-dessous.
Ce pas-à-pas suit la recette de déploiement officielle ; il n’a pas été testé indépendamment pour cet article.
1. Vérifier la visibilité des GPU, le stockage et la connectivité
Commencez par des vérifications d’infrastructure basiques :
nvidia-smi
nvidia-smi topo -m
df -h
Confirmez que tous les GPU cibles sont visibles et que le répertoire du modèle dispose de suffisamment d’espace. Prévoyez un stockage supplémentaire pour les caches de téléchargement, les logs et les futures versions du checkpoint.
Pour les déploiements multi-nœuds, vérifiez la communication entre les nœuds avant d’essayer de démarrer le modèle.
Limitez le premier jalon : chargez le checkpoint et réussissez une requête texte courte. Cela facilite le diagnostic des échecs.
2. Préparer l’environnement de service
Utilisez un hôte Linux avec huit GPU B300 pour cet exemple mono-nœud. Dans un environnement CUDA compatible avec la recette publiée, créez un environnement isolé et installez les outils de service :
python3 -m venv kimi-env
source kimi-env/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade huggingface_hub
python -m pip install "vllm>=0.34.0" fastsafetensors
python -c "import vllm; print(vllm.__version__)"
La version minimale ne garantit pas la compatibilité avec chaque pilote ou roue. Si la recette matérielle exige un conteneur ou une build dédiée, utilisez cet environnement à la place. Figez la version validée avant la production.
3. Télécharger le checkpoint complet
Installez le CLI Hugging Face et téléchargez le dépôt du modèle :
python -m pip install --upgrade huggingface_hub
hf download moonshotai/Kimi-K3.1-Pro \
--local-dir /srv/models/Kimi-K3.1-Pro
Conservez les fichiers de configuration, tokenizer, processor et l’index des poids aux côtés des fragments de poids. Copier uniquement certains fichiers de tenseurs peut laisser un déploiement incomplet.
Pour des déploiements de production reproductibles, enregistrez et figez la révision du dépôt que vous avez validée. Examinez la licence personnalisée du dépôt avant tout usage commercial.
4. Lancer le serveur vLLM
La recette officielle spécifie vLLM 0.34.0 ou supérieur. Commencez par la configuration d’environnement spécifique au matériel, puis figez la version et les dépendances qui réussissent vos tests.
Après préparation de l’environnement, utilisez la commande de base suivante. Elle démarre un parallélisme tensoriel en huit voies et limite la fenêtre de contexte initiale à 32 768 jetons :
export VLLM_ENGINE_READY_TIMEOUT_S=3600
vllm serve /srv/models/Kimi-K3.1-Pro \
--served-model-name kimi-local \
--tensor-parallel-size 8 \
--trust-remote-code \
--load-format fastsafetensors \
--enable-auto-tool-choice \
--tool-call-parser kimi_k3 \
--reasoning-parser kimi_k3 \
--max-model-len 32768 \
--host 127.0.0.1 \
--port 8000
Le nom kimi-local est un alias côté application. Utilisez le même nom dans les requêtes suivantes.
Le paramètre 32 768 jetons est un point de départ prudent pour ce pas-à-pas, et non le contexte maximal pris en charge par le modèle.
L’option --trust-remote-code autorise le chargement de code personnalisé du dépôt. Associez-la à une révision du checkpoint revue et figée.
Ici, 127.0.0.1 désigne la machine exécutant le client. Les vérifications curl ci-dessous s’exécutent sur le serveur GPU, où elles atteignent son processus d’inférence. Pour utiliser le client Python depuis votre portable, ouvrez un tunnel SSH dans un terminal séparé et laissez-le actif :
ssh -N -L 8000:127.0.0.1:8000 user@gpu-server
Remplacez user@gpu-server par votre identifiant SSH et l’adresse du serveur. Avec ce tunnel ouvert, le client du portable peut utiliser http://127.0.0.1:8000/v1. Si le port 8000 est déjà occupé sur le portable, choisissez un autre port local et mettez à jour l’URL du client.
5. Vérifier l’endpoint local
Vérifiez si le serveur expose le modèle :
curl http://127.0.0.1:8000/v1/models
Envoyez ensuite une requête de complétion courte :
curl http://127.0.0.1:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-local",
"messages": [
{
"role": "user",
"content": "Explain database indexes in three sentences."
}
],
"reasoning_effort": "low",
"max_tokens": 2048
}'
Vérifiez la réponse et les logs serveur pour :
- Le nom de modèle attendu.
- Une réponse finale dans la sortie.
- Un
finish_reasonindiquant si la génération a abouti ou atteint sa limite. - Des erreurs de mémoire GPU ou d’opérations non prises en charge.
Le raisonnement peut consommer une partie du budget de génération. Si la requête atteint sa limite avant de produire une réponse finale, augmentez le budget et réessayez avant de conclure que le serveur est défaillant.
6. Connecter une application Python locale
python -m pip install openai
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8000/v1",
api_key="EMPTY",
timeout=300.0,
max_retries=1,
)
response = client.chat.completions.create(
model="kimi-local",
messages=[{"role": "user", "content": "Write a Python function that removes duplicate filenames while preserving order."}],
reasoning_effort="low",
max_tokens=2048,
)
print(response.choices[0].message.content)
print(response.choices[0].finish_reason)
EMPTY est un placeholder pour ce serveur en loopback sans authentification par clé API. Utilisez votre identifiant configuré pour un endpoint authentifié. Validez l’entrée d’images et l’exécution d’outils séparément avant de connecter un agent.
Alternative SGLang
Pour SGLang, utilisez le cookbook officiel spécifique au matériel. Sélectionnez B300, Unified et Low-Latency (TP8) pour coller au plus près de ce pas-à-pas mono-nœud. Vérifiez l’état de validation affiché ; une configuration générée n’est pas nécessairement une configuration testée.
Sur le serveur GPU, installez Docker et configurez NVIDIA Container Toolkit, puis créez un conteneur avec le checkpoint téléchargé monté sur /models/Kimi-K3.1-Pro. Arrêtez d’abord vLLM pour éviter que les deux moteurs ne se disputent les mêmes GPU.
docker pull lmsysorg/sglang:dev-kimi-k31-pro
docker run --rm -it --gpus all \
--shm-size 32g --ipc=host \
-p 127.0.0.1:30000:30000 \
-v /srv/models/Kimi-K3.1-Pro:/models/Kimi-K3.1-Pro:ro \
lmsysorg/sglang:dev-kimi-k31-pro bash
Dans le conteneur, collez la commande de lancement complète produite par le cookbook pour votre configuration sélectionnée. Remplacez son chemin de modèle par /models/Kimi-K3.1-Pro, définissez l’hôte de service sur 0.0.0.0 et le port sur 30000, et conservez les indicateurs spécifiques au matériel. Le conteneur doit écouter sur son interface réseau pour que le transfert de port Docker fonctionne ; le port côté hôte ci-dessus reste lié à loopback. Attendez le message indiquant que le service est prêt avant de tester.
Dans un second shell sur le serveur GPU, listez le modèle servi, puis envoyez une requête en utilisant l’ID de modèle exact renvoyé :
curl http://127.0.0.1:30000/v1/models
MODEL_ID="replace-with-id-from-models-response"
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain database indexes in three sentences.\"}],\"reasoning_effort\":\"low\",\"max_tokens\":2048}"
Une réponse réussie doit contenir une réponse finale. Si le démarrage échoue, inspectez les logs du conteneur et confirmez que la recette matérielle et l’image sélectionnées correspondent. Pour l’accès depuis un portable, utilisez le même schéma de tunnel SSH avec le port 30000. Consultez le guide d’installation Docker de SGLang pour les prérequis du conteneur.
Comment Kimi K3.1 Pro se comporte-t-il sur les benchmarks ?
Utilisez les résultats d’évaluation officiels ci-dessous pour choisir les tâches de votre test de déploiement. Ces scores décrivent la configuration d’évaluation publiée ; ils ne mesurent pas le serveur local configuré dans ce guide.
Le tableau suivant présente des résultats sélectionnés et leur position au sein de l’ensemble de comparaison publié dans la fiche du modèle.
Ces résultats encouragent à tester le modèle pour des tâches d’ingénierie étendues et des workflows documentaires. Kimi K3.1 Pro mène cette comparaison sur SWE Marathon mais se classe quatrième sur ProgramBench, ce qui en fait deux candidats utiles pour des tests spécifiques à l’application.
Ces positions sont calculées au sein du tableau de comparaison officiel, et non d’un classement mondial en direct. Les harnais d’évaluation, outils, budgets de raisonnement et sélections d’échantillons diffèrent selon les benchmarks.
Pour une décision de déploiement, construisez un petit jeu d’évaluation issu du travail réel : correctifs de dépôt, questions interdocuments et tâches multi-étapes avec outils. Mesurez la qualité d’achèvement, les corrections humaines et le temps écoulé. Les scores publiés servent à présélectionner ; les tests applicatifs déterminent si le déploiement est pertinent.
Comment optimiser l’inférence locale de Kimi K3.1 Pro ?
Maîtriser le contexte et la concurrence
Une fois les requêtes courtes validées, testez séparément les documents longs, les images, les conversations multi-tours et les appels d’outils.
Suivez la latence du premier jeton, les jetons produits par seconde et le pic de mémoire GPU à votre longueur de contexte et concurrence visées. Enregistrez aussi le taux de réussite des tâches et le coût par tâche réussie, pour que des sorties plus rapides ne masquent pas davantage de reprises ou de corrections humaines.
Modifiez une variable majeure à la fois. Augmenter simultanément la longueur de contexte, la concurrence et les réglages d’optimisation complique l’explication des régressions.
Choisir délibérément l’effort de raisonnement et les paramètres de cache
Utilisez un effort de raisonnement faible, élevé ou maximal selon la tâche. Commencez par faible pour les vérifications d’interface, puis comparez élevé et maximal sur les tâches difficiles en prenant en compte la qualité de la complétion et le temps écoulé. Une trace de raisonnement plus longue n’est pas en soi la preuve d’un meilleur résultat.
Pour les sessions longues, évaluez la capacité du cache et la réutilisation de préfixe avant d’ajouter le décodage spéculatif ou davantage de concurrence. Conservez une ligne de base validée et changez un paramètre à la fois.
Pourquoi l’appel d’outils de Kimi K3.1 Pro peut-il échouer après le déploiement ?
Votre application exécute les appels d’outils, renvoie leurs résultats et poursuit la conversation. Préservez le message complet de l’assistant — y compris reasoning_content et tool_calls — et renvoyez chaque résultat d’outil avec son tool_call_id correspondant.
La gestion multi-tours compte aussi. Les consignes d’utilisation du modèle exigent de préserver le message complet de l’assistant, y compris les champs de raisonnement et d’appel d’outil, plutôt que de conserver seulement le texte final.
Utilisez une requête minimale reproductible pour isoler chaque échec. Une fois que cela fonctionne, réintroduisez les réglages supplémentaires de l’application un à un.
Faut-il s’auto-héberger ou utiliser une API hébergée ?
Choisissez l’auto-hébergement si vous avez besoin de contrôler les poids, l’infrastructure ou l’emplacement des données, et si vous pouvez maintenir les GPU utilement occupés. Pour une évaluation initiale ou une demande variable, comparez l’API Kimi officielle et CometAPI avec les mêmes invites et critères d’acceptation. Confirmez l’accès au modèle, les paramètres pris en charge, les quotas et les modalités de gestion des données de chaque service.
Une comparaison utile est :
Coût par tâche réussie = (calcul GPU ou frais API + stockage et réseau + opérations + correction humaine) / tâches réussies.
Utilisez des coûts et des comptages de tâches réussies sur la même période de mesure. Incluez les tentatives échouées et les reprises dans le total de calcul ou d’API une seule fois ; n’ajoutez pas un deuxième coût pour la reprise. Pour un workflow hybride, incluez à la fois le calcul et les frais API. Comptez les tâches complétées uniques, pas les tentatives de requêtes.
Un serveur sous-utilisé peut rester coûteux même si son débit théorique est excellent. À l’inverse, une équipe disposant d’une infrastructure existante, d’une demande stable et d’exigences strictes de résidence des données peut tirer une valeur substantielle de l’auto-hébergement.
Utilisez des invites et des critères d’acceptation identiques lors de la comparaison des voies de déploiement. Incluez la latence de bout en bout et la qualité de sortie dans la décision.
Essayer l’endpoint hébergé sans charger de poids
Le guide de démarrage rapide de l’API Kimi officielle utilise l’endpoint ci-dessous. Définissez MOONSHOT_API_KEY dans votre environnement et confirmez l’accès au modèle dans votre compte. Cette requête s’exécute sur l’infrastructure du fournisseur.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.ai/v1",
)
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Explain database indexes in three sentences."}],
reasoning_effort="low",
max_completion_tokens=2048,
)
print(response.choices[0].message.content)
Pour l’API Kimi K3.1 Pro dans CometAPI, définissez COMETAPI_API_KEY dans votre environnement et confirmez que votre compte a accès au modèle demandé. La requête s’exécute à distance :
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_API_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Explain database indexes in three sentences."}],
max_tokens=2048,
)
print(response.choices[0].message.content)
Comparez le résultat avec votre endpoint local en utilisant les mêmes critères d’acceptation. Vérifiez le prix actuel de la voie et les paramètres pris en charge avant d’estimer les coûts de production.
Conclusion
L’auto-hébergement de Kimi K3.1 Pro est réalisable avec une configuration GPU prise en charge et l’environnement d’inférence adéquat. Utilisez les étapes de déploiement ci-dessus pour établir un endpoint fonctionnel, puis mesurez la qualité des tâches, la latence et le coût sur votre propre charge de travail. Optez pour une API hébergée si vous validez encore l’application ou si vous ne disposez pas du matériel requis.
FAQ
Un ordinateur portable standard peut-il exécuter le modèle complet ?
Un ordinateur portable standard n’est pas une cible pratique au vu des besoins de capacité du checkpoint original. Il peut servir de client connecté à votre propre serveur d’inférence ou à une API hébergée.
L’installation de l’application de bureau compte-t-elle comme un déploiement local ?
Le lieu d’installation de l’application n’indique pas où l’inférence a lieu. L’auto-hébergement exige que les poids du modèle et le processus d’inférence s’exécutent dans une infrastructure que vous contrôlez.
Pourquoi le modèle nécessite-t-il autant de mémoire si seulement 104B paramètres sont actifs ?
Des tokens différents sélectionnent des experts différents. Les paramètres actifs décrivent la participation au calcul ; le déploiement doit néanmoins stocker et accéder à l’ensemble complet des poids.
Puis-je activer immédiatement le contexte d’un million de jetons ?
Augmentez la longueur de contexte progressivement et mesurez l’usage de mémoire GPU à votre concurrence cible. Le modèle prend en charge 1 048 576 jetons, mais la capacité utilisable en service dépend de votre cache et de vos réglages de parallélisme.
Le déploiement local reproduira-t-il les scores de benchmark publiés ?
Pas automatiquement. La quantification, les budgets de raisonnement, les outils, les prompts et les frameworks d’évaluation peuvent tous influencer les résultats. Validez la configuration sur vos propres tâches.
Dois-je tester via une API avant d’acheter du matériel ?
Si vous n’avez pas établi que le modèle répond à vos exigences de qualité, les tests via API fournissent une base initiale avec moins de travail d’infrastructure. Les équipes disposant du matériel adapté et d’exigences claires en matière de résidence des données peuvent passer directement à une évaluation d’auto-hébergement contrôlée.