Tutoriel KTransformers : exécuter GLM-5.3-Flash en local

KTransformers est un framework d’inférence open source qui permet au CPU et au GPU d’exécuter activement des experts différents pendant l’inférence, afin d’exécuter des modèles Mixture-of-Experts (MoE) bien plus volumineux que la mémoire de votre GPU. Des frameworks comme vLLM peuvent également décharger des poids vers la mémoire CPU, mais KTransformers est conçu spécifiquement pour la structure clairsemée des modèles MoE.

Dans ce tutoriel, nous allons utiliser KTransformers et SGLang pour exécuter GLM-5.3-Flash, un modèle de 320 milliards de paramètres dont les poids ne tiennent pas dans 192 Go de VRAM. Nous surveillerons l’utilisation de la mémoire CPU et GPU, expérimenterons le placement des experts, testerons l’API compatible OpenAI et connecterons le modèle à Pi en agent de codage local.

L’idée principale est simple : au lieu d’utiliser la mémoire CPU comme un simple débordoir, KTransformers exploite à la fois le calcul CPU et le calcul GPU durant l’inférence.

En bref

• KTransformers exécute de grands modèles MoE en s’appuyant à la fois sur la VRAM du GPU et la RAM du système ; le CPU calcule les experts résidents en RAM.
• Les poids FP8 natifs de GLM-5.3-Flash occupent environ 306 GiB ; le guide officiel recommande au minimum 350 Go de mémoire système disponible.
• Nous avons exécuté le modèle complet sur 2× RTX PRO 6000 (192 Go de VRAM au total) avec une fenêtre de contexte de 32K, à environ 11 tokens par seconde.
• Le serveur expose une API compatible OpenAI, ce qui permet à des agents de codage comme Pi d’utiliser directement le modèle.

Qu’est-ce que KTransformers ?

KTransformers est un framework d’inférence open source pour exécuter des très grands modèles de langue en combinant la VRAM GPU et la RAM CPU. Habituellement, servir un grand modèle implique de charger la plupart de ses poids en mémoire GPU, ce qui devient vite coûteux pour un modèle de la taille de GLM-5.3-Flash.

KTransformers adopte une autre approche : il conserve de nombreux poids d’experts MoE en mémoire système et réserve la mémoire GPU aux parties de l’inférence qui bénéficient le plus de l’accélération GPU.

Cela fonctionne bien pour les modèles MoE, car chaque expert n’est pas utilisé à chaque token. GLM-5.3-Flash, par exemple, comporte 288 experts routés, mais son routeur n’en sélectionne que 8 (plus 1 expert partagé) par token. KTransformers peut donc répartir le calcul des experts entre le CPU et le GPU :

Comment KT-Kernel et SGLang fonctionnent ensemble

L’empilement actuel de KTransformers intègre KT-Kernel avec SGLang pour une inférence hétérogène CPU-GPU. Chaque composant assure un rôle différent :

• SGLang fournit le runtime de service : requêtes API, batching, ordonnancement, gestion du KV-cache et parallélisme GPU.
• KT-Kernel remplace le chemin d’exécution MoE standard par une exécution des experts optimisée CPU-GPU. Les experts sélectionnés tournent sur le GPU, tandis que les autres restent en RAM et sont calculés sur le CPU.

KTransformers prend également en charge l’ajustement du placement des experts selon les profils de charge, comme décrit dans son tutoriel sur l’ordonnancement des experts.

En d’autres termes, KTransformers considère la mémoire CPU et la mémoire GPU comme un système d’inférence partagé, au lieu d’exiger que tout le modèle tienne en VRAM. C’est ce qui permet d’exécuter de très grands modèles MoE sur du matériel disposant de bien moins de mémoire GPU que nécessaire habituellement.

Qu’est-ce que GLM-5.3-Flash ?

GLM-5.3-Flash est le modèle MoE à poids ouverts et nativement multimodal de Z.ai, publié sous licence MIT en août 2026. Malgré son nom « Flash », c’est un grand modèle : 320 milliards de paramètres au total, dont environ 18 milliards actifs par token.

Voici les caractéristiques qui comptent pour l’inférence locale :

• Experts : 288 experts routés avec routage top-8, plus 1 expert partagé
• Poids : environ 306 GiB pour le checkpoint FP8 officiel (zai-org/GLM-5.3-Flash)
• Fenêtre de contexte : jusqu’à 1 million de tokens
• Entrées : texte, images et vidéo, avec prise en charge du raisonnement et des appels d’outils

KTransformers lit directement les poids FP8 officiels, sans conversion ni étape supplémentaire de quantification. Pour les benchmarks et une présentation complète, consultez notre guide GLM-5.3-Flash.

Exigences matérielles pour GLM-5.3-Flash

Pour GLM-5.3-Flash, la question matérielle porte surtout sur la RAM système. Le tutoriel officiel KTransformers pour GLM-5.3-Flash recommande de réserver au moins 350 Go de mémoire système disponible.

Configuration recommandée : 2× RTX PRO 6000

Pour ce tutoriel, nous utilisons une instance RunPod avec approximativement :

GPU:         2× RTX PRO 6000
VRAM:        96 GB each
Total VRAM:  192 GB

System RAM:  350 GB+
Storage:     500 GB+
Python:      3.11

Le checkpoint FP8 officiel de GLM-5.3-Flash fait environ 306 GiB (soit ~329 Go), tandis que nos deux GPU offrent 192 Go de VRAM au total. Le modèle complet ne peut donc pas simplement être chargé en mémoire GPU.

Au lieu de cela, KTransformers conserve une grande partie des poids MoE en RAM système et transfère les calculs les plus utiles vers les GPU. La recommandation des 350 Go laisse suffisamment d’espace pour les poids du modèle et les surcoûts à l’exécution.

Plus de mémoire GPU ne supprime pas le besoin de RAM dans cette configuration. La mémoire CPU fait partie intégrante de l’architecture d’inférence hétérogène de KTransformers : les poids des experts restent en RAM tandis que le GPU prend en charge les parties du modèle qui bénéficient le plus de l’accélération.

L’implémentation actuelle de GLM-5.3-Flash comporte également des prérequis CPU et GPU spécifiques :

• GPU : architectures NVIDIA SM89 ou SM120, couvrant les séries RTX 40, RTX 50 et les cartes station de travail Blackwell comme la RTX PRO 6000.
• CPU : prise en charge AVX-512, sur laquelle s’appuie le noyau expert FP8 côté CPU.

Pouvez-vous exécuter GLM-5.3-Flash sur un seul GPU ?

Oui, à condition de disposer de suffisamment de RAM système et d’un CPU compatible. Le tutoriel officiel inclut une configuration mono-GPU qui positionne --kt-num-gpu-experts 0, afin que les experts MoE soient gérés côté CPU.

Nous utilisons ici deux RTX PRO 6000, mais ce n’est pas une exigence minimale stricte. Le second GPU nous apporte plus de VRAM et de marge pour expérimenter une implémentation KTransformers relativement récente, plutôt que d’optimiser pour la configuration matérielle la plus réduite possible.

Étape 1 : installer KTransformers avec SGLang

Créez un environnement Python 3.11 propre et installez KTransformers avec la prise en charge de SGLang :

python3.11 -m venv /workspace/kt
source /workspace/kt/bin/activate

pip install --upgrade pip
pip install \"ktransformers[sglang]\"

Vérifiez que KTransformers, KT-Kernel, SGLang et CUDA sont correctement détectés :

kt version

Vous devriez obtenir une sortie similaire :

KTransformers CLI v0.7.0.post4

Python      3.11.13
Platform    Linux 6.8.0-136-generic
CUDA        13.0

Packages:
kt-kernel   0.7.0.post4
sglang-kt   0.7.0.post4

Cela confirme que le runtime KTransformers et son backend SGLang sont installés et prêts à l’emploi.

Étape 2 : télécharger GLM-5.3-Flash depuis Hugging Face

Avant de démarrer le serveur, téléchargez le checkpoint officiel GLM-5.3-Flash depuis Hugging Face :

hf download zai-org/GLM-5.3-Flash \
  --local-dir /workspace/GLM-5.3-Flash

Le checkpoint pèse environ 306 GiB ; le téléchargement peut donc prendre un certain temps selon votre bande passante.

Indiquez ensuite à KTransformers le chemin local du modèle :

export MODEL_PATH=/workspace/GLM-5.3-Flash

Étape 3 : lancer le serveur GLM-5.3-Flash avec SGLang

Lancez maintenant GLM-5.3-Flash avec un parallélisme tensoriel sur deux voies, en utilisant les deux RTX PRO 6000. Le modèle prend en charge jusqu’à 1 million de tokens de contexte, et les exemples officiels utilisent une configuration validée à 501 25 tokens. Nous démarrons avec une fenêtre de contexte de 32K pour garder une consommation mémoire prévisible durant les tests.

CUDA_VISIBLE_DEVICES=0,1 \
python -m sglang.launch_server \
  --model-path \"$MODEL_PATH\" \
  --kt-weight-path \"$MODEL_PATH\" \
  --served-model-name GLM-5.3-flash \
  --host 0.0.0.0 \
  --port 30000 \
  --tp-size 2 \
  --context-length 32768 \
  --max-total-tokens 32768 \
  --mem-fraction-static 0.85 \
  --chunked-prefill-size 2048 \
  --kt-method FP8 \
  --kt-cpuinfer 64 \
  --kt-threadpool-count 2 \
  --kt-num-gpu-experts 14 \
  --kt-gpu-prefill-token-threshold 2048 \
  --kt-expert-placement-strategy uniform \
  --cuda-graph-bs 1 2 4 \
  --enable-p2p-check \
  --tool-call-parser glm47 \
  --reasoning-parser glm45

Cette configuration expose le modèle via un serveur SGLang compatible OpenAI sur le port 30000. Les deux GPU sont utilisés avec --tp-size 2, tandis que KTransformers maintient une partie de la charge MoE sur le CPU et place des experts sélectionnés sur les GPU.

Ces réglages sont volontairement prudents pour un premier démarrage : contexte 32K, 85 % de mémoire GPU statique, 14 experts GPU et 64 threads d’inférence CPU. Une fois le serveur stable, vous pourrez expérimenter une fenêtre de contexte plus grande, davantage d’experts GPU ou des paramètres mémoire différents pour améliorer le débit.

Principaux indicateurs de lancement KTransformers

La plupart des options ci-dessus sont propres à SGLang. Voici celles qui contrôlent la façon dont KTransformers partage le travail entre CPU et GPU :

Étape 4 : tester le déchargement CPU-GPU et le placement des experts

Maintenant que le serveur tourne, vérifions comment KTransformers utilise la VRAM GPU et la RAM système, puis modifions le nombre d’experts résidents sur GPU pour observer l’évolution de l’usage des ressources et des performances.

Sur RunPod, free -h peut induire en erreur car un conteneur peut voir la RAM totale de l’hôte plutôt que la mémoire réellement disponible pour le pod. Il est préférable de surveiller la mémoire GPU et la mémoire du conteneur séparément.

Surveiller l’usage de la VRAM GPU

Ouvrez un nouveau terminal et surveillez l’utilisation du GPU :

watch -n 1 nvidia-smi

Avec notre configuration actuelle, le modèle chargé utilise environ 48 Go par GPU, laissant une large part de VRAM inemployée. Cela suggère qu’il est possible de placer davantage d’experts sur les GPU, ou de tester une configuration à un seul GPU avec suffisamment de RAM système.

Surveiller la RAM du conteneur sur RunPod

Pour la RAM du conteneur, lisez directement les compteurs mémoire cgroup :

watch -n 1 'echo -n \"Used: \"; awk \"{printf \\\"%.1f GiB\\n\\", \\$1/1024/1024/1024}\" /sys/fs/cgroup/memory.current; echo -n \"Limit: \"; awk \"{printf \\\"%.1f GiB\\n\\", \\$1/1024/1024/1024}\" /sys/fs/cgroup/memory.max'

Vous devriez constater qu’une grande partie de la RAM disponible est occupée par les poids du modèle et les experts côté CPU. C’est attendu : KTransformers maintient volontairement de nombreux experts MoE en RAM plutôt que d’exiger qu’ils résident tous en VRAM.

Ajuster --kt-num-gpu-experts

Redémarrez ensuite le serveur avec différentes valeurs de --kt-num-gpu-experts. Par exemple, comparez :

0
10
20

--kt-num-gpu-experts contrôle le nombre d’experts par couche MoE placés sur le GPU. Avec 0, le calcul des experts reste côté CPU ; augmenter la valeur déplace davantage d’experts en mémoire GPU.

Pour chaque configuration, comparez l’usage de VRAM GPU, la RAM du conteneur, les tokens par seconde et le temps jusqu’au premier token. En général, plus d’experts GPU consomment davantage de VRAM mais réduisent l’exécution côté CPU, ce qui peut améliorer les performances d’inférence si la VRAM est suffisante.

Un point d’attention issu du tutoriel officiel : lorsque le « Layerwise Prefill » est activé pour GLM-5.3-Flash, l’implémentation actuelle normalise le nombre d’experts résidents sur GPU à zéro. Si l’usage de VRAM varie très peu entre les exécutions, c’est probablement la raison.

Cette expérience illustre l’atout clé de KTransformers : la RAM CPU et la VRAM GPU deviennent des leviers ajustables d’un même système d’inférence, ce qui permet d’arbitrer entre placement mémoire et vitesse, au lieu d’imposer que le modèle MoE entier tienne sur les GPU.

Étape 5 : tester l’API compatible OpenAI

Avec le serveur en marche, vérifions que le modèle est disponible et envoyons une requête réelle via l’API compatible OpenAI de SGLang.

Commencez par vérifier que le modèle est bien enregistré :

curl http://localhost:30000/v1/models

Ensuite, envoyez une invite de test :

curl http://localhost:30000/v1/chat/completions \
  -H \"Content-Type: application/json\" \
  -d '{
    \"model\": \"GLM-5.3-flash\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"Create a FastAPI application with a health endpoint.\"
      }
    ],
    \"max_tokens\": 500
  }'

Si tout fonctionne, le serveur renvoie une réponse de chat standard contenant du code généré et des statistiques d’usage.

Étape 6 : utiliser GLM-5.3-Flash comme agent de codage local avec Pi

Pi est un agent de codage léger qui peut utiliser n’importe quel modèle compatible OpenAI comme backend, ce qui permet à GLM-5.3-Flash de travailler directement sur des tâches de développement plutôt que de se limiter aux invites.

Installer Pi

Installez Pi avec son script d’installation :

curl -fsSL https://pi.dev/install.sh | sh

Ajoutez ensuite Pi à votre PATH :

echo 'export PATH=\"/root/.local/share/pi-node/current/bin:$PATH\"' >> ~/.bashrc
source ~/.bashrc

Pointer Pi vers le serveur KTransformers

Créez une configuration de modèle qui oriente Pi vers le serveur KTransformers local :

mkdir -p ~/.pi/agent && cat > ~/.pi/agent/models.json <<'EOF'
{
  "providers": {
    "ktransformers": {
      "baseUrl": "http://localhost:30000/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "models": [
        {
          "id": "GLM-5.3-flash",
          "name": "GLM-5.3-Flash",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 32768,
          "maxTokens": 8192,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}
EOF

Démarrez Pi :

pi

Ouvrez ensuite le sélecteur de modèles :

/model

Exécuter une tâche de développement avec GLM-5.3-Flash

Sélectionnez GLM-5.3-Flash et lancez une vraie tâche de codage :

Build a FastAPI service with /health and /users endpoints.
Add pytest tests and run them.

En quelques secondes, Pi devrait commencer à créer des fichiers, écrire l’API, exécuter des tests et corriger les problèmes au fil de la tâche.

Vous pouvez aussi observer le premier terminal, où tourne le serveur SGLang. Lors de notre essai, la vitesse de génération était d’environ 11 tokens par seconde. C’est raisonnable pour un modèle de cette taille avec un déchargement CPU substantiel, et l’ensemble peut encore être optimisé en déplaçant davantage d’experts sur les GPU.

En quelques minutes, le modèle a créé les endpoints, écrit et exécuté les tests, réalisé un smoke test et généré un court résumé expliquant comment lancer le projet.

L’intéressant, c’est que le modèle complet tourne en local alors que ses poids sont bien plus volumineux que la VRAM GPU disponible. Pi orchestre la boucle d’agent de codage, tandis que SGLang et KTransformers gèrent l’inférence du modèle.

KTransformers vs vLLM vs llama.cpp

KTransformers n’est pas la seule façon d’exécuter un modèle plus grand que votre VRAM. vLLM et llama.cpp prennent tous deux en charge le déchargement CPU, mais répartissent le travail différemment :

SGLang et KTransformers ne sont pas en concurrence dans cette configuration. SGLang gère la couche de service, tandis que KTransformers gère l’exécution MoE hétérogène CPU-GPU.

Pour conclure

Ce que j’ai le plus apprécié dans cette configuration, c’est que KTransformers s’écarte un peu de la pile d’inférence habituelle. Plutôt que de raisonner uniquement en termes de couches, il place des experts individuels sur le GPU tout en en conservant d’autres en RAM système, et le CPU participe réellement au calcul des experts. Le CPU ne sert pas seulement de stockage tampon.

Dans ce tutoriel, nous avons exécuté en local le modèle GLM-5.3-Flash complet sur deux RTX PRO 6000, bien que ses poids dépassent largement la VRAM disponible.

Ce n’est pas la configuration la plus rapide. J’obtenais environ 11 tokens par seconde, et il reste une grande marge pour ajuster le nombre et le placement des experts GPU. Vous pourriez aussi tenter l’expérience avec un seul GPU si vous avez assez de RAM ; j’en ai utilisé deux ici pour disposer de plus de marge.

Pour moi, c’est la leçon principale de ce guide : KTransformers n’est pas spécial parce qu’il a inventé le déchargement CPU. Il l’est parce qu’il fait travailler la RAM CPU, le calcul CPU et le calcul GPU de concert autour de la structure clairsemée des modèles MoE.