Comment faire tourner Kimi K3 en local et ses limites

Moonshot AI a publié les poids ouverts de Kimi K3 le 27 juillet, et le compteur de téléchargements sur Hugging Face approche déjà les 100 000. L’intérêt est clair : un modèle de 2,8 billions de paramètres qui a battu Claude Opus 4.8 sur tous les benchmarks publiés par Moonshot, que vous pouvez désormais auto-héberger.

Essayez Apidog dès aujourd’hui

Le coût matériel est tout aussi clair. L’inférence en pleine précision demande 1,57 To d’espace disque, tandis que les poids MXFP4 publiés représentent déjà 594 Go. Vous pouvez posséder le modèle, mais à cette échelle, « local » ne signifie pas « sur un ordinateur portable » comme pour un Llama 8B.

Ce guide explique comment choisir une configuration réaliste, démarrer K3 avec vLLM ou llama.cpp, puis tester son endpoint compatible OpenAI avec Apidog.

Ce que vous téléchargez

Pour le contexte complet, consultez Qu’est-ce que Kimi K3 ?. Voici les caractéristiques à connaître avant de provisionner votre matériel :

• 2,8 T de paramètres au total, 104 milliards activés par jeton. K3 est un modèle Mixture-of-Experts (MoE) avec 896 experts. Chaque jeton active 16 experts sélectionnés, plus 2 experts partagés : le calcul par jeton reste donc inférieur au nombre total de paramètres.
• 93 couches. Le modèle combine 69 couches d’attention Kimi Delta (KDA) et 24 couches MLA gated. Cette architecture rend exploitable sa fenêtre de contexte d’un million de jetons.
• Vision native. L’encodeur MoonViT-V2 compte 401 millions de paramètres. Les poids publiés acceptent du texte, des images et de la vidéo.
• Poids MXFP4 et activations MXFP8. Moonshot a utilisé un entraînement conscient de la quantification : le format 4 bits est le format de service prévu, pas une conversion secondaire. La marge pour réduire encore la précision est donc limitée.
• Mode réflexion uniquement. K3 raisonne avant de répondre, avec des niveaux d’effort faible, élevé et maximal. Il n’existe pas de mode instantané.

Les poids sont soumis à la licence Kimi K3 sur le dépôt Hugging Face. Acceptez la licence, puis téléchargez-les avec huggingface-cli.

huggingface-cli download moonshotai/Kimi-K3 \
  --local-dir ./Kimi-K3

Sur une connexion à 1 Gbps, prévoyez environ 80 à 90 minutes pour télécharger les 594 Go.

Option 1 : servir K3 sur un nœud multi-GPU avec vLLM ou SGLang

Moonshot recommande vLLM, SGLang et TokenSpeed. La prise en charge du cache de préremplissage KDA a été intégrée à vLLM avec les poids ; vLLM est donc le chemin le plus direct.

Démarrez avec un parallélisme de tenseurs sur 8 GPU et une fenêtre de contexte réduite :

vllm serve moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --max-model-len 131072

Points de configuration

• Matériel : Moonshot a évalué K3 sur des clusters H20. En pratique, prévoyez au minimum un nœud de 8 GPU avec parallélisme de tenseurs. Sur du matériel de classe B200, un débit supérieur à 100 jetons/s est réalisable.
• Contexte : K3 prend en charge jusqu’à 1 048 576 jetons, mais le cache KV à contexte complet représente environ 27 Go à lui seul. Commencez avec --max-model-len 131072, puis augmentez uniquement si votre workload le nécessite.
• Échantillonnage : les valeurs par défaut de Moonshot sont temperature=1.0 et top_p=0.95. Pour les workloads agissants, gardez temperature=1.0 et définissez top_p=1.0.

Exemple de requête vers le serveur vLLM :

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/Kimi-K3",
    "messages": [
      {
        "role": "user",
        "content": "Résume ce document en trois points."
      }
    ],
    "temperature": 1.0,
    "top_p": 0.95
  }'

Cette approche est « locale » du point de vue de la souveraineté des données : l’infrastructure, les journaux et les contrôles de conformité restent chez vous. Elle ne l’est pas au sens « ordinateur portable », et la quantification ne change pas ce point pour un usage interactif.

Option 2 : utiliser une quantification GGUF sur une grande station de travail

Unsloth a publié des conversions GGUF pour llama.cpp. Ses quantifications dynamiques constituent la seule voie réaliste pour réduire K3 sous le format MXFP4 officiel.

Quantification	Taille	Signification
UD-IQ1_M	~345 Go	Minimum absolu. Quantification dynamique agressive sur 1 bit.
UD-IQ1_S	~650 Go	Point d’équilibre recommandé par Unsloth.
UD-Q4_K_XL	~1,55 To	Précision quasi totale.
UD-Q8_K_XL	~1,6 To	Effectivement sans perte.

Appliquez cette règle simple : RAM + VRAM doit être approximativement égale à la taille de la quantification.

llama.cpp peut fonctionner avec de l’offloading si la mémoire disponible est insuffisante, mais chaque gigaoctet absent se traduit par une perte de vitesse. Un Mac Studio doté de 128 Go de mémoire unifiée ou une DGX Station se situe à la limite basse pratique.

Exemple minimal avec le projecteur de vision :

./llama.cpp/llama-cli \
  --model unsloth/Kimi-K3-GGUF/UD-IQ1_S/Kimi-K3-UD-IQ1_M-00001-of-00015.gguf \
  --mmproj unsloth/Kimi-K3-GGUF/mmproj-F16.gguf \
  --temp 1.0 \
  --top-p 0.95

Si votre matériel est inférieur à cette configuration, ne forcez pas. La liste des meilleurs LLM locaux de 2026 propose des modèles ouverts qui tiennent dans 24 à 128 Go et répondent en temps réel. K3 à 1 bit avec une RAM insuffisante ne le fera pas.

L’expérience M1 Max : possible, mais 16 secondes par jeton

Un fil de discussion Hacker News a documenté l’exécution de K3 sur un M1 Max avec 64 Go de mémoire, en diffusant les poids depuis un SSD de 2 To au lieu de les conserver en mémoire.

Pourquoi cela fonctionne :

• K3 contient environ 115 Go de paramètres denses sollicités à chaque jeton.
• Il faut également charger environ 25 Go de poids d’experts routés par jeton.
• La partie dense dépasse déjà les 64 Go de mémoire de la machine : le SSD se comporte alors comme une mémoire très lente.

Pourquoi ce n’est pas exploitable en pratique :

• Le résultat observé est d’environ 16 secondes par jeton.
• Certaines configurations ont dépassé une minute par jeton.
• Le débit du disque devient le goulot d’étranglement. Les SSD de l’ère M1 sont moins rapides que ceux des puces Apple récentes, et diffuser les experts sur le réseau est encore plus lent.

C’est une démonstration intéressante de ce que permettent les MoE et mmap, mais pas une configuration de production. Si vous voulez utiliser K3 depuis un MacBook, les niveaux gratuits ou l’API hébergée restent plus adaptés.

Intégrer votre K3 local dans un flux de travail API

Que vous utilisiez vLLM ou le mode serveur de llama.cpp, vous obtenez un endpoint HTTP compatible OpenAI, généralement disponible sur localhost.

Pour vLLM, l’URL par défaut est :

http://localhost:8000/v1

Vous pouvez ensuite appliquer le même workflow que pour tester des LLM locaux en tant qu’API.

1. Créez un environnement Apidog

Dans Apidog, créez un environnement avec une variable base_url :

base_url = http://localhost:8000/v1

Utilisez-la dans vos requêtes :

{{base_url}}/chat/completions

Vous pourrez ensuite remplacer cette variable par le endpoint hébergé de Moonshot sans modifier les requêtes, les tests ou les collections.

2. Testez la réponse de chat

Configurez une requête POST vers :

{{base_url}}/chat/completions

Avec ce corps JSON :

{
  "model": "moonshotai/Kimi-K3",
  "messages": [
    {
      "role": "user",
      "content": "Explique la différence entre le parallélisme de tenseurs et le parallélisme de pipeline."
    }
  ],
  "temperature": 1.0,
  "top_p": 0.95,
  "stream": true
}

3. Inspectez le flux de réflexion

K3 fonctionne en mode réflexion uniquement : les réponses incluent du contenu de raisonnement avant la réponse finale. La vue de débogage SSE d’Apidog permet d’inspecter le flux au fil de l’arrivée des événements.

Utilisez cette vue pour vérifier les effets des changements suivants :

• niveau d’effort de raisonnement ;
• paramètres d’échantillonnage ;
• moteur d’inférence ;
• quantification des poids.

4. Ajoutez des assertions automatisées

Ne vous contentez pas d’évaluer la sortie « à l’œil ». Ajoutez des tests sur :

• le schéma de réponse ;
• la présence des champs d’usage des jetons ;
• les budgets de latence ;
• le statut HTTP ;
• les contraintes fonctionnelles propres à votre application.

Par exemple, vérifiez qu’une réponse contient un choix et un message :

pm.test("La réponse contient un message", () => {
  const body = pm.response.json();
  pm.expect(body.choices).to.be.an("array").that.is.not.empty;
  pm.expect(body.choices[0].message).to.have.property("content");
});

Ainsi, une nouvelle quantification ou une mise à jour du moteur qui dégrade la sortie apparaît dans les tests plutôt que dans les retours utilisateurs.

5. Simulez l’API pendant le chargement des GPU

Un modèle de 594 Go peut prendre du temps à charger. Enregistrez quelques réponses réelles, puis configurez un serveur de simulation pour les rejouer pendant que l’infrastructure d’inférence est indisponible.

Cela permet au front-end et aux intégrations de progresser sans attendre le serveur GPU. Vous pouvez télécharger Apidog pour configurer gratuitement des tests et des simulations avec n’importe quel serveur compatible OpenAI.

Le format de requête est le même que dans le guide API de Kimi K3. Les tests écrits pour l’API hébergée peuvent donc être transférés directement vers votre déploiement local.

Alors, devriez-vous exécuter K3 localement ?

Votre situation	Recommandation
Nœud de 8 GPU ou plus, besoin de souveraineté des données ou de conformité	Oui. Utilisez vLLM avec parallélisme de tenseurs et les poids MXFP4.
Station de travail avec 350 Go ou plus de RAM/VRAM	Faisable. Utilisez un GGUF Unsloth à 1 bit, avec des attentes modérées sur les performances.
Mac ou PC avec 64 à 128 Go	Non. Vous obtiendrez des secondes par jeton, pas des jetons par seconde.
Vous voulez simplement intégrer K3 dans votre produit	Utilisez l’API hébergée, compatible OpenAI et Anthropic.

Les poids ouverts de K3 sont importants parce qu’ils permettent d’auditer, d’affiner et d’auto-héberger un modèle de pointe, pas parce que tout le monde devrait le faire sur sa machine.

Pour les équipes disposant du matériel adapté, la voie vLLM est exploitable aujourd’hui. Pour les autres, l’accès hébergé ou les fournisseurs tiers reste l’option pragmatique.

Dans tous les cas, traitez l’endpoint du modèle comme n’importe quelle API de production : validez les schémas, inspectez les flux SSE, mesurez la latence et utilisez des simulations pour maintenir le développement en mouvement pendant que le modèle réfléchit.