Quantification post-entraînement ModelOpt

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

Étape 1 — Environnement

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

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

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

Vérifiez la table de support dans examples/llm_ptq/README.md pour les modèles HF vérifiés.

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

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

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

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

Motifs de dépendances connus :

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

• Launcher (4B) : définir 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

Étape 3 — Choisir le format de quantification

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

ls modelopt_recipes/models/ 2>/dev/null

Si une recette spécifique au modèle existe, utiliser --recipe <path> — elle peut contenir des paramètres ajustés.

S'il n'y a pas de recette spécifique au modèle, choisir un format en fonction du GPU (détails dans examples/llm_ptq/README.md) :

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

Utiliser --qformat <name> (par exemple, --qformat nvfp4). Définitions de format : modelopt/torch/quantization/config.py. Les recettes PTQ générales dans modelopt_recipes/general/ptq/ correspondent aux mêmes formats — --qformat est la façon plus simple de les utiliser.

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

Étape 4 — Exécuter PTQ

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

Pour modèles listés (4A/4B) : exécuter l'étalonnage complet directement (--calib_size 512). Pour modèles non listés (4C) : exécuter d'abord un test de fonctionnement (--calib_size 4), attendre 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 (sans SLURM) ? → MANUAL (4A)
                      │          GPU bare metal (local ou distant) ? → MANUAL (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/llm_ptq/requirements.txt

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

Exécutez --help pour toutes les options.

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

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

Écrire un fichier config YAML en utilisant common/hf_ptq/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), basculer au chemin 4A (exécution manuelle).

4C — Modèle non listé

Suivre references/unsupported-models.md. Il explique comment examiner le modèle, corriger ModelOpt si nécessaire, et exécuter hf_ptq.py. Exécuter manuellement (comme 4A) pour faciliter le suivi et le débogage.

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

Suivi

Après la soumission du job, enregistrer le job et configurer le suivi selon la skill de monitoring.

Étape 5 — Vérifier la sortie

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

Signaler le chemin et la taille à l'utilisateur.

Validation post-quantification

Valider que le motif de quantification du checkpoint exporté correspond à la recette. Les motifs de config de quantification peuvent manquer silencieusement des couches si le modèle utilise des conventions de nommage non standard (par exemple, experts.* de Gemma4 manqué par les motifs *mlp*) — cela ne se manifeste que plus tard sous forme d'échecs de déploiement. Lire references/checkpoint-validation.md pour le script de validation, les motifs attendus par recette et les lacunes de motifs courants.

Étapes suivantes : Si l'utilisateur souhaite déployer ou évaluer le checkpoint quantifié, utiliser la skill de déploiement ou la skill d'évaluation. Le workspace du checkpoint est conservé. Si le modèle a nécessité des correctifs lors du PTQ (par exemple, upgrade de transformers), les mêmes correctifs seront probablement nécessaires au moment du déploiement et de l'évaluation.

Règles clés de l'API

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

Pièges courants

• Dépendances spécifiques au modèle : Les modèles avec trust_remote_code peuvent importer des paquets non présents dans le conteneur (par exemple, mamba-ssm pour les modèles Mamba hybrides). Voir Étape 2.5. Utiliser la variable d'env EXTRA_PIP_DEPS avec le launcher, ou installer manuellement avant d'exécuter hf_ptq.py
• Version de transformers : Les nouveaux modèles peuvent nécessiter une version plus récente de transformers que celle installée. Vérifier config.json pour transformers_version. Dans les conteneurs, attention à PIP_CONSTRAINT qui bloque les mises à niveau — voir references/slurm-setup-ptq.md pour les solutions
• Datasets gérés : Certains datasets d'étalonnage nécessitent l'authentification HF. Assurer que HF_TOKEN est défini dans l'environnement du job, ou utiliser --dataset cnn_dailymail comme alternative non gérée
• NFS root_squash + Docker : Voir skills/common/slurm-setup.md section 5

Références