Skill de déploiement

Servir un checkpoint de modèle comme endpoint d'inférence compatible OpenAI. Supporte vLLM, SGLang et TRT-LLM (y compris AutoDeploy).

Démarrage rapide

Préférez scripts/deploy.sh pour les déploiements locaux standard — il gère la détection de quantification, les contrôles de santé et le cycle de vie du serveur. Utilisez les commandes brutes du framework à l'étape 4 quand vous avez besoin de flags que le script ne supporte pas, ou pour un déploiement distant.

# Démarrer un 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 auto des flags de quantification (FP8 vs FP4), le cycle de vie du serveur (start/stop/restart/status), le polling de contrôle de santé et le test 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 les espaces existants — notamment si vous déployez un checkpoint issu d'une exécution PTQ antérieure :

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

Si l'utilisateur dit « déployer le modèle que je viens de quantifier » ou fait référence à une PTQ antérieure, trouvez l'espace de travail correspondant et cd dedans. Le checkpoint doit se trouver 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 (issu de la skill ptq ou d'un export manuel) : cherchez hf_quant_config.json dans le répertoire. S'il vient 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 le --export_path utilisé dans la commande PTQ.
• Hub de modèles HuggingFace (ex : nvidia/Llama-3.1-8B-Instruct-FP8) : utilisez directement
• Modèle non quantifié : déployez tel quel (BF16) ou proposez de quantifier d'abord avec la skill ptq

Note : Cette skill attend des checkpoints au format HF (issus de 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 si applicable :

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 aucune 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 comme 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.

SGLang

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

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 en bon état :

# Contrôle 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

Tous les contrôles doivent réussir avant de signaler le succès à l'utilisateur.

6. Déploiement distant (SSH/SLURM)

Si une configuration de cluster existe (~/.config/modelopt/clusters.yaml ou .claude/clusters.yaml), ou l'utilisateur mentionne l'exécution 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 identifiants existent sur le cluster selon skills/common/slurm-setup.md section 6. Si les identifiants manquent pour le registre de l'image, demandez à l'utilisateur de corriger l'authentification ou de passer à une image sur un registre authentifié (ex : NGC). Ne soumettez pas avant confirmation de l'authentification.

1. Sourcer les utilitaires distants :

   source .claude/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 (ex : issu 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". Ne synchronisez que si le checkpoint est local :

   remote_sync_to <local_checkpoint_path> checkpoints/

3. Déployer selon l'environnement distant :

   • SLURM — voir skills/common/slurm-setup.md pour les modèles de script de job (setup du conteneur, découverte account/partition). La commande de serveur à l'intérieur du conteneur est la même qu'à l'étape 4 (ex : python -m vllm.entrypoints.openai.api_server --model <path> --quantization modelopt). Après soumission, enregistrez le job et mettez en place la surveillance selon la skill monitor. Récupérez le nom du nœud avec 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. Signaler l'endpoint — incluez le nom de nœud distant et le port pour que l'utilisateur puisse se connecter (ex : http://<node_hostname>:8000). Pour SLURM, notez que le port n'est accessible que depuis le réseau du cluster.

Pour un déploiement géré par NEL (évaluation avec auto-déploiement), utilisez la skill d'évaluation à la place — NEL gère le déploiement du conteneur SLURM, les contrôles 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 en raison de défauts de clés de poids, d'architectures manquantes, ou de 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 la source du framework → ré-exécuter. Pour les problèmes au niveau des kernels, escaladez vers l'équipe du framework plutôt que de tenter des corrections.

Critères de succès

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