wshobson/quantized-export

Exportation Quantifiée

La dernière étape après que checkpoint-promotion a remis un verdict PROMOTE : un checkpoint ayant passé le contrôle en quatre étapes n'est pas déployé tant qu'il n'est pas exporté dans le bon format pour son runtime cible et qu'il n'a pas été prouvé qu'il fonctionne toujours après l'exportation. Un verdict REJECT n'atteint jamais cette compétence — l'exportation commence uniquement à partir d'un checkpoint promu.

Entrée : un checkpoint promu (ou un adaptateur LoRA) plus la surface de déploiement cible — classe de GPU, pile de service, et si les charges de travail long-contexte/code/mathématiques sont concernées. Format de sortie : un artefact exporté dans le format choisi plus un rapport de diff de test de fumée comparant 3 à 5 sorties dorées avant l'exportation et après.

Carte des Formats

Choisissez le format en fonction du matériel et de la forme de déploiement, pas par habitude — un mauvais choix soit gaspille de la marge de débit, soit échoue silencieusement sur des charges de travail spécifiques (voir Surcharges de Charge de Travail).

• FP8 est la valeur par défaut sur les GPU de classe Hopper et plus récents. Il préserve une qualité proche du bf16 pour environ la moitié de la mémoire, et c'est le premier choix sûr chaque fois que le GPU cible le supporte et qu'aucune contrainte de périphérique de bord ne s'applique.
• AWQ INT4 cible les GPU plus anciens qui précèdent le support matériel FP8. GPTQ est remplacé pour les nouveaux déploiements — ne l'utilisez pas pour une nouvelle exportation ; AWQ offre une meilleure rétention de précision à la même largeur de bits et un support d'outillage plus large actuellement.
• GGUF avec quantification Q4_K_M, construit à partir d'un imatrix, est le format edge/llama.cpp. Utilisez-le pour un déploiement local ou proche du CPU, pas pour le débit de service GPU — il optimise l'empreinte, pas les tokens/s sur un GPU de centre de données.
• NVFP4 est destiné uniquement aux déploiements Blackwell à grande échelle — et explicitement PAS sur GB10. NVFP4 sur SM121 (GB10) est ~32 % plus lent que FP8 car le matériel manque d'un chemin cvt.e2m1x2 natif à moins que le noyau soit compilé sm_121a. Choisir NVFP4 sur une cible GB10 est une régression, pas une amélioration — choisissez FP8 à la place.
• Fusionné vs. LoRA uniquement est un axe séparé du format de quantification. Une exportation fusionnée intègre l'adaptateur dans les poids de base : artefact plus volumineux, aucune dépendance au modèle de base au moment du service. LoRA unique garde l'adaptateur séparé : artefact beaucoup plus petit, mais la pile de service doit charger exactement le même modèle de base en parallèle — une base mal assortie ou de mauvaise révision modifie silencieusement les sorties. Choisissez fusionné lorsque la portabilité de l'artefact est plus importante que le stockage ; choisissez LoRA unique lorsque l'empreinte disque ou le service multi-adaptateur est plus important.

Choix Appliqués

Le compromis principal de sélection de format, présenté comme une table de recherche pour les scénarios courants :

Cible	Charge de travail	Format
GPU de centre de données	chat générique	FP8
GPU de centre de données	long-contexte/code/mathématiques	FP8 ou W8A8 — jamais INT4
Génération de GPU plus ancienne	générique	AWQ INT4
Périphérique de bord / ordinateur portable	service llama.cpp	GGUF Q4_K_M + imatrix
GB10	toute charge de travail	FP8 via vLLM nightly, ou GGUF via llama.cpp localement — ignorez NVFP4

# extrait de décision rapide — voir le tableau ci-dessus pour la carte complète
hopper_ou_plus_recent: fp8
plus_ancien_gpu: awq-int4
bord_llama_cpp: gguf-q4_k_m+imatrix
gb10_toute_charge_de_travail: fp8-vllm-nightly   # jamais nvfp4 sur GB10

Surcharges de Charge de Travail

La carte des formats ci-dessus est une valeur par défaut, pas une règle qui survit à chaque charge de travail. Les charges de travail long-contexte, code, et mathématiques échouent en INT4 — l'erreur de quantification se cumule sur les longues séquences et le raisonnement précis au niveau des tokens de manière qui n'apparaît pas sur les prompts courts et génériques. Pour l'une de ces trois classes de charge de travail, restez en FP8 ou W8A8 même si le matériel cible justifierait autrement l'INT4 pour des raisons de coût.

• Ne validez pas cette surcharge avec MMLU ou d'autres benchmarks de connaissances larges — ils ne sollicitent pas le mode de défaillance. Mesurez avec les évaluations de tâches réelles — les dorés et les évaluateurs de eval-harness-first, exécutés sur l'artefact exporté — car la dégradation INT4 sur le long-contexte, le code ou les mathématiques se manifeste par des échecs spécifiques à la tâche (contexte perdu, syntaxe cassée, erreurs arithmétiques) bien avant qu'elle ne fasse bouger un benchmark de connaissances.
• Si une évaluation de tâche régresse après une exportation INT4 sur l'une de ces trois classes de charge de travail, la correction consiste à changer de format, pas à re-régler la recette de quantification — les variantes AWQ et GPTQ à la même largeur de bits partagent le même mode de défaillance d'erreur cumulative sur ces charges de travail.

Le Test de Fumée

Les bugs d'exportation sont silencieux au niveau du fichier — une exportation malformée produit toujours un artefact chargeable, donc les vérifications d'existence de fichier ne prouvent rien. Le test de fumée est obligatoire pour chaque exportation, sans exception pour un format qui « devrait juste marcher » :

1. Chargez l'artefact exporté dans son runtime cible réel — vLLM pour FP8/AWQ, llm.cpp pour GGUF, pas un chargement de vérification rapide dans un framework différent de celui qui le servira en production.
2. Exécutez 3 à 5 prompts dorés à travers lui — tirez-les du même eval/goldens.jsonl que eval-harness-first maintient, pas d'un ensemble ad hoc frais.
3. Comparez chaque sortie à la génération pré-exportation pour le même prompt, les mêmes paramètres d'échantillonnage déterministes — décodage glouton (température 0) et une graine fixe, persistée et réutilisée entre les exécutions pré- et post-exportation, pas seulement des configurations nominalement identiques. Pour une exportation sans perte, la correspondance exacte est la porte — tout diff est un bug. Pour une exportation avec perte (quantifiée), la correspondance exacte est censée échouer ; la porte est l'accord du verdict de l'évaluateur de tâche à la place — voir references/export-commands.md's Squelette de Script de Test de Fumée.

Exécutez ceci comme une porte, pas une vérification manuelle :

python smoke_test.py "$EXPORT_PATH" \
    eval/goldens.jsonl pre-export-outputs.jsonl
# code de sortie non nul pour toute discordance pré/post

Signatures de Défaillance

À quoi ressemblent réellement les bugs d'exportation, pas un simple drapeau de réussite/échec :

• Discordance de template se présente comme une sortie brouillée ou enchaînée — le template de chat intégré dans l'exportation ne correspond pas à celui sur lequel le checkpoint a été entraîné et évalué, donc les limites de tour ou les tokens spéciaux atterrissent au mauvais endroit.
• Mauvaise quantification appliquée à lm_head se présente comme une sortie hors template ou sémantiquement absurde qui semble toujours fluide — la tête de sortie a perdu la précision dont elle avait besoin alors que le reste du réseau s'est quantifié proprement.

Ne livrez jamais une exportation qui a sauté cette étape — un verdict PROMOTE d'un checkpoint dit que le checkpoint non exporté est bon ; il ne dit rien sur le pipeline d'exportation. Réexécutez après un changement de méthode de quantification ou de version du runtime, pas seulement après la première exportation. Des séquences de commandes exécutables pour chaque format plus le squelette de script de test de fumée : references/export-commands.md.

Compétences Connexes

• checkpoint-promotion — la seule source amont valide pour cette compétence. Un checkpoint sans verdict PROMOTE n'atteint pas l'exportation.
• eval-harness-first — possède le eval/goldens.jsonl dont le test de fumée de cette compétence tire ses 3 à 5 prompts, et les évaluations de tâche que la section Surcharges de Charge de Travail exige pour la validation long-contexte/code/mathématiques.
• finetuning-method-selection — son references/model-catalog.md est l'endroit pour vérifier les hypothèses de classe matérielle (quelles générations de GPU un modèle de base cible) avant de choisir un format sur la carte des formats ci-dessus.

Utilisateurs Spark : sur GB10, GGUF via llama.cpp fonctionne bien pour le service local, et le service FP8 via les builds nightly de vLLM est l'autre chemin éprouvé — NVFP4 est le seul format à éviter là-bas (voir l'exception de la carte des formats ci-dessus). Une fois que le plugin dgx-spark-ops est installé, déléguez les questions spécifiques de service et thermiques Spark à ses compétences plutôt que de les redériver ici.