Skill de Déploiement

Servez un checkpoint de modèle en tant que endpoint d'inférence compatible OpenAI. Supporte vLLM, SGLang et TRT-LLM (incluant AutoDeploy).

Démarrage rapide

Privilégiez scripts/deploy.sh pour les déploiements locaux standards — il gère la détection de quantification, les vérifications de santé et le cycle de vie du serveur. Utilisez les commandes du framework brut à l'Étape 4 si vous avez besoin de flags que le script ne supporte pas, ou pour un déploiement distant.

# Démarrer le serveur vLLM avec un checkpoint ModelOpt
scripts/deploy.sh start --model ./qwen3-0.6b-fp8

# Démarrer avec SGLang et parallélisme tensoriel
scripts/deploy.sh start --model ./llama-70b-nvfp4 --framework sglang --tp 4

# Démarrer depuis le hub HuggingFace
scripts/deploy.sh start --model nvidia/Llama-3.1-8B-Instruct-FP8

# Tester l'API
scripts/deploy.sh test

# Vérifier le statut
scripts/deploy.sh status

# Arrêter
scripts/deploy.sh stop

Le script gère : la détection GPU, la détection automatique du flag de quantification (FP8 vs FP4), le cycle de vie du serveur (start/stop/restart/status), le polling de vérification de santé et les tests d'API.

Flux de décision

0. Vérifier l'espace de travail (multi-utilisateur / bot Slack)

Si MODELOPT_WORKSPACE_ROOT est défini, lisez skills/common/workspace-management.md. Avant de créer un nouvel espace de travail, vérifiez la session actuelle pour les espaces de travail de modèles existants — surtout si vous déployez un checkpoint d'une exécution PTQ antérieure :

ls "$MODELOPT_WORKSPACE_ROOT/<session_id>/" 2>/dev/null

Si l'utilisateur dit « déployer le modèle que je viens de quantifier » ou référence un PTQ précédent, trouvez l'espace de travail correspondant et cd dedans. Le checkpoint devrait être dans le répertoire de sortie de cet espace de travail.

1. Identifier le checkpoint

Déterminez ce que l'utilisateur veut déployer :

• Checkpoint quantifié local (depuis la skill ptq ou export manuel) : cherchez hf_quant_config.json dans le répertoire. S'il provient d'une exécution PTQ antérieure dans le même espace de travail, vérifiez les emplacements de sortie courants : output/, outputs/, exported_model/, ou l'--export_path utilisé dans la commande PTQ.
• Hub de modèle HuggingFace (p. ex. nvidia/Llama-3.1-8B-Instruct-FP8) : utilisez directement
• Modèle non-quantifié : déployez tel quel (BF16) ou suggérez de quantifier d'abord avec la skill ptq

Remarque : Cette skill s'attend à des checkpoints au format HF (depuis PTQ avec --export_fmt hf). Les checkpoints au format TRT-LLM doivent être déployés directement avec TRT-LLM — voir references/trtllm.md.

Vérifiez le format de quantification le cas échéant :

cat <checkpoint_path>/hf_quant_config.json 2>/dev/null || echo "No hf_quant_config.json"

S'il n'est pas trouvé, vérifiez aussi config.json pour une section quantization_config avec quant_method: "modelopt". Si aucun n'existe, le checkpoint n'est pas quantifié.

2. Choisir le framework

Si l'utilisateur n'a pas spécifié de framework, recommandez en fonction de cette priorité :

Vérifiez la matrice de support dans references/support-matrix.md pour confirmer que la combinaison modèle + format + framework est supportée.

3. Vérifier l'environnement

Lisez skills/common/environment-setup.md pour la détection GPU, local vs distant, et la détection SLURM/Docker/bare metal. Après l'avoir complété, vous devriez savoir : modèle/nombre GPU, local ou distant, et environnement d'exécution.

Vérifiez ensuite que le framework de déploiement est installé :

python -c "import vllm; print(f'vLLM {vllm.__version__}')" 2>/dev/null || echo "vLLM not installed"
python -c "import sglang; print(f'SGLang {sglang.__version__}')" 2>/dev/null || echo "SGLang not installed"
python -c "import tensorrt_llm; print(f'TRT-LLM {tensorrt_llm.__version__}')" 2>/dev/null || echo "TRT-LLM not installed"

S'il n'est pas installé, consultez references/setup.md.

Estimation de la mémoire GPU (pour déterminer le parallélisme tensoriel) :

• BF16 : params × 2 bytes (8B ≈ 16 GB)
• FP8 : params × 1 byte (8B ≈ 8 GB)
• FP4 : params × 0,5 bytes (8B ≈ 4 GB)
• Ajoutez ~2-4 GB pour le cache KV et les frais généraux du framework

Si le modèle dépasse la mémoire d'une seule GPU, utilisez le parallélisme tensoriel (-tp <num_gpus>).

4. Déployer

Lisez la référence spécifique au framework pour les instructions détaillées :

Commandes de démarrage rapide (pour les cas courants) :

vLLM

# Servir en tant qu'endpoint compatible OpenAI
python -m vllm.entrypoints.openai.api_server \
    --model <checkpoint_path> \
    --quantization modelopt \
    --tensor-parallel-size <num_gpus> \
    --host 0.0.0.0 --port 8000

Pour les checkpoints NVFP4, utilisez --quantization modelopt_fp4.

NVFP4 sur Blackwell B300/GB300 (sm_103) : ajoutez -cu130 à la balise d'image (p. ex. vllm/vllm-openai:v0.19.1-cu130 — les balises de release sont multi-arch). La version par défaut cu12 n'a aucun kernel FP4 pour sm_103, donc vLLM charge le checkpoint puis meurt à l'initialisation du moteur avec CUDA error: no kernel image is available for execution on the device (affecte les backends NVFP4 flashinfer et cutlass ; marlin échoue séparément sur les dimensions de couche non-divisibles par 64). Vérifiez via recipes.vllm.ai/<org>/<model>?hardware=b300 (rendu JS — récupérez le markdown brut à github.com/vllm-project/recipes/blob/main/<org>/<model>.md). Pour les modèles multimodaux sur sm_103, passez aussi --mm-encoder-attn-backend TRITON_ATTN (le CuTe ViT flash-attn par défaut affirme « Only SM 10.x and 11.x »).

SGLang

python -m sglang.launch_server \
    --model-path <checkpoint_path> \
    --quantization modelopt \
    --tp <num_gpus> \
    --host 0.0.0.0 --port 8000

Pour les checkpoints NVFP4, utilisez --quantization modelopt_fp4.

Vérifiez les flags de lancement SGLang via le cookbook SGLang (l'équivalent SGLang de recipes.vllm.ai) : docs.sglang.io/cookbook/<category>/<org>/<model> (p. ex. .../autoregressive/DeepSeek/DeepSeek-V4) — faisant autorité sur le parallélisme, les backends MoE, les flags de stratégie, l'image Docker et la version minimale. Sélectionnez la variante via le fragment URL #hw=...&variant=...&quant=...&strategy=...&nodes=.... La page est rendue JS — récupérez le markdown brut à raw.githubusercontent.com/sgl-project/sglang/main/docs_new/cookbook/<category>/<org>/<model>.mdx. SM120 (RTX PRO 6000) a besoin du nightly lmsysorg/sglang:dev (:latest manque SM120). Voir references/sglang.md pour la matrice complète backend/flag.

TRT-LLM (direct)

from tensorrt_llm import LLM, SamplingParams
llm = LLM(model="<checkpoint_path>")
outputs = llm.generate(["Hello, my name is"], SamplingParams(temperature=0.8, top_p=0.95))

TRT-LLM AutoDeploy

Pour les checkpoints AutoQuant ou précision mixte, voir references/trtllm.md.

5. Vérifier le déploiement

Après le démarrage du serveur, vérifiez qu'il est sain :

# Vérification de santé
curl -s http://localhost:8000/health

# Lister les modèles
curl -s http://localhost:8000/v1/models | python -m json.tool

# Tester la génération
curl -s http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "<model_name>",
        "prompt": "The capital of France is",
        "max_tokens": 32
    }' | python -m json.tool

Toutes les vérifications doivent réussir avant de signaler le succès à l'utilisateur.

5b. Benchmarker le débit/latence (optionnel)

Si l'utilisateur demande de benchmarker, mesurer le débit/latence ou comparer les précisions, utilisez AIPerf (client benchmark OpenAI-compatible, Apache-2.0). Voir references/benchmarking.md pour l'installation, la porte cohérence pré-benchmark, les flags aiperf profile (notamment --extra-inputs ignore_eos:true), les formes de tokens suggérées et comment lire profile_export_aiperf.json.

6. Déploiement distant (SSH/SLURM)

Si une config de cluster existe (~/.config/modelopt/clusters.yaml, .agents/clusters.yaml ou .claude/clusters.yaml), ou si l'utilisateur mentionne s'exécuter sur une machine distante :

0. Vérifier l'authentification du registre de conteneurs — avant de soumettre un job SLURM avec une image de conteneur, vérifiez que les credentials existent sur le cluster selon skills/common/slurm-setup.md section 6. Si les credentials manquent pour le registre de l'image, demandez à l'utilisateur de corriger l'authentification ou de passer à une image sur un registre authentifié (p. ex. NGC). Ne soumettez pas avant que l'authentification soit confirmée.

1. Sourcer les utilitaires distants :

   source .agents/skills/common/remote_exec.sh
   remote_load_cluster
   remote_check_ssh
   remote_detect_env

2. Synchroniser le checkpoint (uniquement s'il a été produit localement) :

   Si le chemin du checkpoint est un chemin distant/absolu (p. ex. d'une exécution PTQ antérieure sur le cluster), ignorez la synchronisation — il y est déjà. Vérifiez avec remote_run "ls <checkpoint_path>/config.json". Synchronisez uniquement si le checkpoint est local :

   remote_sync_to <local_checkpoint_path> <session_id>/<model>/checkpoints/

3. Déployer en fonction de l'environnement distant :

   • SLURM — voir skills/common/slurm-setup.md pour les modèles de script de job (configuration de conteneur, découverte de compte/partition). La commande du serveur à l'intérieur du conteneur est la même qu'à l'Étape 4 (p. ex. python -m vllm.entrypoints.openai.api_server --model <path> --quantization modelopt). Après soumission, enregistrez le job et configurez la surveillance selon la skill de monitoring. Obtenez le nom d'hôte du nœud depuis squeue -j $JOBID -o %N.

   • Bare metal / Docker — utilisez remote_run pour démarrer le serveur directement :

     remote_run "nohup python -m vllm.entrypoints.openai.api_server --model <path> --port 8000 > deploy.log 2>&1 &"

4. Vérifier à distance :

   remote_run "curl -s http://localhost:8000/health"
   remote_run "curl -s http://localhost:8000/v1/models"

5. Rapporter l'endpoint — incluez le nom d'hôte distant et le port pour que l'utilisateur puisse se connecter (p. ex. http://<node_hostname>:8000). Pour SLURM, notez que le port n'est accessible que depuis le réseau du cluster.

Pour le déploiement géré par NEL (évaluation avec auto-déploiement), utilisez la skill d'évaluation à la place — NEL gère la déploiement de conteneur SLURM, les vérifications de santé et le nettoyage automatiquement.

Gestion des erreurs

Modèles non supportés

Si le modèle ne figure pas dans la matrice de support validée (references/support-matrix.md), le déploiement peut échouer dû à des incompatibilités de clés de poids, des mappages d'architecture manquants ou une confusion entre couches quantifiées/non-quantifiées. Lisez references/unsupported-models.md pour la boucle de débogage itérative : exécuter → lire l'erreur → diagnostiquer → patcher le code source du framework → réexécuter. Pour les problèmes au niveau du kernel, escaladez vers l'équipe du framework plutôt que de tenter des corrections.

Critères de succès

1. Le processus serveur est en cours d'exécution et sain (/health retourne 200)
2. Le modèle est listé à /v1/models
3. La génération de test produit une sortie cohérente
4. L'URL et le port du serveur sont rapportés à l'utilisateur
5. Si un benchmark a été demandé, les nombres de débit/latence sont rapportés