ModelOpt Post-Training Quantization

Générer un checkpoint quantifié à partir d'un modèle préentraîné. Lisez d'abord examples/hf_ptq/README.md — il contient la matrice de support, les flags CLI et les directives de précision.

Step 1 — Environnement

Lisez skills/common/environment-setup.md et skills/common/workspace-management.md. Après les avoir complétés, vous devez savoir :

• ModelOpt source est disponible
• Local ou distant (+ config cluster si distant)
• SLURM / Docker+GPU / GPU nu
• Launcher disponible ?
• Quel workspace utiliser

Step 2 — Le modèle est-il supporté ?

Consultez la table de support dans examples/hf_ptq/README.md pour les modèles HF vérifiés.

• Listé → supporté, utilisez hf_ptq.py (step 4A/4B)
• Non listé → lisez references/unsupported-models.md pour déterminer si hf_ptq.py peut fonctionner ou si un script personnalisé est nécessaire (step 4C)

Step 2.5 — Vérifier les dépendances spécifiques au modèle

Si le modèle utilise trust_remote_code (vérifiez config.json pour auto_map), inspectez ses fichiers Python personnalisés pour les imports non présents dans le container :

grep -h "^from \|^import " <model_path>/modeling_*.py | sort -u

Motifs de dépendance connus :

Si des dépendances supplémentaires sont nécessaires :

• Launcher (4B) : définissez EXTRA_PIP_DEPS dans la section environment de la tâche — ptq.sh les installe automatiquement
• Manuel (4A) : unset PIP_CONSTRAINT && pip install <deps> avant d'exécuter hf_ptq.py

Step 3 — Choisir le format de quantification

D'abord, vérifiez s'il existe une recette spécifique au modèle :

ls modelopt_recipes/models/ 2>/dev/null
ls modelopt_recipes/huggingface/<model_type>/ptq/ 2>/dev/null  # par-arch ; <model_type> depuis le config.json local (Hub ID : AutoConfig.from_pretrained)

Si une recette spécifique au modèle existe, préférez --recipe <path> — mais inspectez ses motifs include/exclude plutôt que de supposer (p. ex. pour les VLMs, confirmez que la tour de vision est réellement exclue).

Si aucune recette spécifique au modèle, choisissez un format basé sur le GPU (détails dans examples/hf_ptq/README.md) :

• Blackwell (B100/B200/GB200) : variantes nvfp4
• Hopper (H100/H200) ou plus ancien : fp8 ou int4_awq

Utilisez --qformat <name> (p. ex., --qformat nvfp4). Définitions des formats : modelopt/torch/quantization/config.py. Les recettes PTQ générales dans modelopt_recipes/general/ptq/ correspondent aux mêmes formats — --qformat est le moyen plus simple de les utiliser.

Avant d'exécuter PTQ, validez rapidement le qformat/recette sélectionné par rapport à la structure du modèle. Inspectez les motifs include/exclude de la recette et résumez quels groupes de couches seront quantifiés et approximativement combien de modules/couches correspondent (projections d'attention, projections MLP, experts, etc.). Si le nombre de correspondances est 0 ou beaucoup plus petit que prévu pour le modèle, arrêtez et corrigez la recette ou demandez à l'utilisateur avant de lancer l'étalonnage.

VLMs : les recettes génériques *mlp*/*experts* correspondent aussi à la tour de vision (model.visual.*) ; quantifier le ViT casse silencieusement les benchmarks d'image. Utilisez la recette huggingface/<model_type>/ptq/ ou ajoutez des exclusions *visual*/*vision_tower*, puis vérifiez à l'étape 5 — voir references/checkpoint-validation.md.

Si le checkpoint source est déjà quantifié et la recette/config demandée réduit la couverture de quantification, confirmez cette intention avec l'utilisateur avant d'exécuter. Par exemple, si un checkpoint FP8 est utilisé comme entrée et la recette exclut certaines couches pour qu'elles reviennent à BF16 au lieu de rester quantifiées, signalez les groupes de couches affectés et demandez si ce repli FP8-vers-BF16 est intentionnel.

NVFP4 peut être étalonné sur Hopper mais nécessite Blackwell pour l'inférence.

Step 4 — Exécuter PTQ

Objectif : checkpoint sur disque (.safetensors + config.json).

Pour modèles listés (4A/4B) : exécutez l'étalonnage complet directement (--calib_size 512). Pour modèles non listés (4C) : exécutez d'abord un test de fumée (--calib_size 4), attendez le succès, puis l'étalonnage complet.

Quel chemin ?

Dans la table README ? ─→ OUI ──→ SLURM (local ou distant) ? ──→ LAUNCHER (4B)
                  │          Docker local + GPU ? ────────→ LAUNCHER (4B)
                  │          Docker distant (pas SLURM) ? ──→ MANUEL (4A)
                  │          GPU nu (local ou distant) ? → MANUEL (4A)
                  │
                  └→ NON LISTÉ ──→ MODÈLE NON LISTÉ (4C)

4A — Direct : modèle supporté, exécution manuelle

pip install --no-build-isolation "nvidia-modelopt[hf]"
pip install -r examples/hf_ptq/requirements.txt

python examples/hf_ptq/hf_ptq.py \
    --pyt_ckpt_path <model> \
    --qformat <format> \
    --calib_size 512 \
    --export_path <output>

Exécutez --help pour tous les options.

Pour distant : utilisez remote_run depuis remote_exec.sh (voir skills/common/remote-execution.md).

4B — Launcher : modèle supporté sur SLURM ou Docker local

Écrivez un config YAML en utilisant common/hf/ptq.sh. Voir references/launcher-guide.md pour le modèle complet.

cd tools/launcher
# SLURM (distant ou local) :
SLURM_HOST=<host> SLURM_ACCOUNT=<acct> uv run launch.py --yaml <config.yaml> user=<ssh_user> identity=<ssh_key> --yes
# Docker local :
uv run launch.py --yaml <config.yaml> hf_local=<hf_cache> --yes

Le launcher bloque et affiche les logs jusqu'à la fin du job. Si le launcher échoue (dépendances manquantes, erreurs de config), retournez au chemin 4A (exécution manuelle).

4C — Modèle non listé

Suivez references/unsupported-models.md. Il vous guide à travers l'investigation du modèle, les correctifs à ModelOpt si nécessaire, et l'exécution de hf_ptq.py. Exécutez manuellement (comme 4A) pour un suivi et débogage plus faciles.

Pour SLURM, voir skills/common/slurm-setup.md et references/slurm-setup-ptq.md.

Surveillance

Après la soumission du job, enregistrez le job et configurez la surveillance selon la monitor skill.

Step 5 — Vérifier la sortie

ls -lh <output_path>/
# Attendez : config.json, fichiers tokenizer, model-*.safetensors

Rapportez le chemin et la taille à l'utilisateur.

Validation post-quantification

C'est une porte obligatoire avant tout déploiement ou soumission d'évaluation. Ne soumettez pas d'eval, ne lancez pas de job de serveur ou ne transmettez pas le checkpoint comme prêt jusqu'à ce que cette porte soit franchie.

Lisez references/checkpoint-validation.md et effectuez les trois groupes de validation sur le chemin d'accès exact du checkpoint qui sera déployé/évalué :

1. Vérifiez la taille de sortie et les bits estimés par poids par rapport au checkpoint de base/source.
2. Vérifiez la couverture des poids quantifiés par rapport au qformat/recette/config demandé.
3. Vérifiez la cohérence des métadonnées par rapport au modèle de base/source.

Rapportez le résultat de la porte avant de continuer. Le rapport doit inclure la taille source, la taille de sortie, le ratio output/source, les comptages de précision des couches (p. ex. NVFP4, FP8, INT4, BF16/non quantifiés exclus, non quantifiés inattendus, divergences de déclaration) et les diffs de métadonnées. Si le ratio output/source est >= 1,0 pour une recette de compression, si un groupe de couches prévu manque de quantification, ou si les métadonnées ont changé inopinément, arrêtez et corrigez le checkpoint ou demandez à l'utilisateur avant de continuer.

Étapes suivantes : Si l'utilisateur souhaite déployer ou évaluer le checkpoint quantifié, utilisez la deployment ou evaluation skill. Le workspace du checkpoint se transfère. Si le modèle a nécessité des correctifs pendant PTQ (p. ex., mise à jour de transformers), les mêmes correctifs seront probablement nécessaires au déploiement et à l'évaluation.

Key API Rules

• Les classes mtq.register() doivent définir _setup() et l'appeler depuis __init__
• Appelez mto.enable_huggingface_checkpointing() avant la quantification
• Le wildcard *gate* correspond trop largement — utilisez *mlp.gate* ou *router*
• VLMs : hf_ptq.py extrait automatiquement le modèle de langage via extract_and_prepare_language_model_from_vl() — aucun traitement VLM manuel nécessaire dans la plupart des cas
• Checkpoints FP8 : préférez _QuantFP8Linear (dequant paresseux) à FineGrainedFP8Config(dequantize=True) qui gaspille ~2x la mémoire. Voir references/unsupported-models.md pour les détails
• Les noms de quantificateurs personnalisés doivent se terminer par _input_quantizer ou _weight_quantizer

Common Pitfalls

• Dépendances spécifiques au modèle : Les modèles avec trust_remote_code peuvent importer des packages non présents dans le container (p. ex., mamba-ssm pour les modèles Mamba hybrides). Voir Step 2.5. Utilisez la variable d'environnement EXTRA_PIP_DEPS avec le launcher, ou installez manuellement avant d'exécuter hf_ptq.py
• Version de transformers : Les nouveaux modèles peuvent avoir besoin d'une version plus récente de transformers que celle installée. Vérifiez config.json pour transformers_version. Dans les containers, attention à PIP_CONSTRAINT bloquant les mises à jour — voir references/slurm-setup-ptq.md pour les contournements
• Datasets gated : Certains datasets d'étalonnage nécessitent l'authentification HF. Assurez-vous que HF_TOKEN est défini dans l'environnement du job, ou utilisez --dataset cnn_dailymail comme alternative non gated
• NFS root_squash + Docker : Voir skills/common/slurm-setup.md section 5

References