AmeliorIA

tekio.org

Exemple de code : Quantification

Ce que le dossier 15-quantification/ fournit pour cette méthode. Principe et références : Quantification.

Variantes

Variante GGUF : servir le modèle avec llama.cpp ou Ollama

Le besoin : faire tourner un modèle sur un poste, un serveur sans GPU ou en périphérie, avec les outils les plus répandus (llama.cpp, Ollama, LM Studio), et choisir le niveau de quantification en connaissant ce qu'il coûte.

variantes/gguf-llamacpp convertit Qwen2.5-1.5B-Instruct en GGUF 16 bits, calcule une matrice d'importance (imatrix) sur 400 textes de calibration, quantifie en Q8_0, Q5_K_M, Q4_K_M et IQ3_M, mesure la taille et la perplexité de chaque fichier avec llama-perplexity (100 textes), puis écrit un Modelfile Ollama. Il faut un clone compilé de llama.cpp (dossier_llamacpp, voir config.yaml).

Format Taille Perplexité
f16 2 950 Mo 13,91
Q8_0 1 570 Mo 13,93
Q5_K_M 1 073 Mo 14,16
Q4_K_M 940 Mo 14,47
IQ3_M 741 Mo 15,95

Q8_0 divise la taille par 2 sans perte mesurable ; Q4_K_M la divise par 3 pour +4 % de perplexité, le compromis habituel ; en dessous de 4 bits, la perte devient nette (+15 % en IQ3_M). Réserve : la perplexité résume mal certaines pertes (raisonnement, suivi de consignes) ; avant de déployer un format, mesurer aussi la tâche visée.

Composants de l'exemple

flowchart TD
  classDef externe fill:#fed7aa,stroke:#ea580c,color:#7c2d12
  classDef code fill:#ffffff,stroke:#6b7280,color:#1f2937
  classDef gpu fill:#fecaca,stroke:#dc2626,color:#7f1d1d
  classDef disque fill:#dcfce7,stroke:#16a34a,color:#14532d

  Hub["Hugging Face Hub<br/>Qwen2.5-1.5B-Instruct<br/>wikitext-2"]
  Cache[("cache disque<br/>~/.cache/huggingface")]
  subgraph Py["Processus Python"]
    Run["run.py<br/>génère les problèmes<br/>charge les modèles"]
    Ev["evaluation.py<br/>perplexité, exactitude"]
    BnB["bitsandbytes<br/>NF4, 4 bits"]
  end
  GPU["GPU CUDA, 12 Go"]
  Out[("sorties/<br/>15-quantification/")]

  Hub -- "① HTTPS GET, 1re fois<br/>poids (3 Go), textes" --> Cache
  Cache -- "② ⑥ lecture des poids" --> Run
  Run -- "③ copie des poids bf16<br/>en mémoire GPU" --> GPU
  Run -- "④ ⑨ appel Python<br/>mesure bf16, NF4" --> Ev
  Ev -- "⑤ ⑩ noyaux CUDA<br/>génération, forward" --> GPU
  Run -- "⑦ appel Python<br/>from_pretrained" --> BnB
  BnB -- "⑧ quantification<br/>à la volée" --> GPU
  Run -- "⑪ ⑫ écriture<br/>modèle, resultats.json" --> Out

  GPU ~~~ Out
  class Hub externe
  class Run,Ev,BnB code
  class GPU gpu
  class Cache,Out disque

make run EX=FORM15 vérifie les prérequis (modules, GPU), puis lance run.py dans l'environnement .venv. Le script lit config.yaml (modèle, méthode de quantification, données, évaluation) : par défaut, Qwen2.5-1.5B-Instruct est mesuré en bf16, puis rechargé en NF4 4 bits par bitsandbytes (methode: bnb_nf4) et mesuré de nouveau. Les autres méthodes se choisissent avec SET="methode=..." ; gptq et awq tournent alors dans l'environnement séparé .venv-llmcompressor, que make choisit tout seul. Le schéma suit la méthode par défaut. Les 100 problèmes de test, de la forme (a op b) op c, sont générés en mémoire, sans téléchargement ; les 50 paragraphes de perplexité viennent du split test de wikitext-2, téléchargé depuis le Hugging Face Hub.

  • ① Téléchargement. Au premier lancement, transformers télécharge les poids de Qwen2.5-1.5B-Instruct (environ 3 Go, fichiers safetensors) et datasets télécharge wikitext-2, depuis le Hugging Face Hub, par HTTPS.
  • ② Lecture. Poids et textes sont rangés dans le cache ~/.cache/huggingface ; les lancements suivants les relisent sur le disque, sans réseau.
  • ③ Copie sur le GPU. Le modèle de référence est copié en bf16 dans la mémoire du GPU.
  • ④ Mesure de la référence. run.py relève la mémoire occupée par le modèle sur le GPU, puis le débit en génération : 64 tokens produits sur une consigne fixe, après un court préchauffage. Il appelle ensuite commun/evaluation.py pour la perplexité sur les 50 paragraphes et l'exactitude sur les 100 problèmes.
  • ⑤ Génération et forward sur le GPU. La perplexité demande une passe avant par lot de 4 paragraphes. L'exactitude fait répondre le modèle par lots de 16, token par token, jusqu'à 256 tokens, puis compare le nombre final de chaque réponse au résultat attendu.
  • ⑥ Relecture. Le modèle de référence est supprimé et la mémoire du GPU vidée ; les poids d'origine sont relus dans le cache.
  • ⑦ Chargement quantifié. run.py appelle from_pretrained avec une configuration bitsandbytes : NF4, double quantification des échelles, calcul en bf16.
  • ⑧ Quantification à la volée. Au moment de leur copie sur le GPU, les poids des couches linéaires sont arrondis par bitsandbytes sur 16 niveaux NF4, par blocs ayant chacun leur échelle. Les embeddings restent en bf16. Aucune donnée de calibration n'est utilisée.
  • ⑨ Mesure du modèle NF4. Mêmes mesures qu'en ④ : mémoire, débit, perplexité, exactitude.
  • ⑩ Génération et forward sur le GPU, avec le même décodage qu'en ⑤.
  • ⑪ Écriture du modèle quantifié et de son tokenizer dans sorties/15-quantification/modele-bnb_nf4/.
  • ⑫ Écriture du rapport dans sorties/15-quantification/resultats.json, avec le même tableau affiché dans le terminal.

Ce que fait le GPU. Le processus Python ne calcule presque rien lui-même : PyTorch envoie au GPU des « noyaux CUDA », de petits programmes qui font les multiplications de matrices et l'attention sur les poids et les activations déjà présents dans sa mémoire. En génération, il y a une passe avant par token produit, accélérée par un cache des clés et des valeurs déjà calculées. En NF4, les poids restent stockés sur 4 bits dans la mémoire du GPU : les noyaux de bitsandbytes les décompressent en bf16 au moment de chaque multiplication de matrices. C'est ce qui réduit la mémoire du modèle (2 945 Mo en bf16, 1 132 Mo en NF4) et ralentit ici la génération (126,4 contre 89,6 tokens par seconde). Les deux modèles ne coexistent jamais : la référence est libérée avant le chargement quantifié.

Ce qui est écrit.

Fichier Contenu
modele-bnb_nf4/model.safetensors Les poids quantifiés (1,1 Go) : couches linéaires en NF4 avec leurs échelles, embeddings en bf16
modele-bnb_nf4/config.json, generation_config.json L'architecture, la configuration de quantification (quant_method: bitsandbytes, bnb_4bit_quant_type: nf4, double quantification) et les réglages de génération, pour recharger le modèle directement en 4 bits
modele-bnb_nf4/tokenizer.json, tokenizer_config.json, chat_template.jinja Le tokenizer et le format de conversation, copiés pour que le dossier se suffise à lui-même
resultats.json Pour la référence bf16 et le modèle NF4 : mémoire du modèle sur le GPU, tokens par seconde, perplexité générale, exactitude sur les 100 problèmes avec la durée de l'évaluation et trois réponses d'exemple
config_effective.yaml La configuration réellement utilisée, surcharges SET comprises

Avec une autre méthode (SET="methode=..."), le dossier du modèle prend son nom (modele-bnb_int8/, modele-gptq/...), sauf qat qui n'en écrit pas ; pour gptq et awq, resultats.json ajoute la taille du modèle compressé sur le disque.

Essayer dans le dépôt

Exemple Statut Résultat mesuré Durée Commande
exemple principal démontré NF4 : 2 945 → 1 132 Mo ; perplexité 14,9 → 16,6 ; exactitude 0,99 → 0,96 test : 15 s
complet : 50 s
make test EX=FORM15
variante gguf-llamacpp démontré Q4_K_M : 940 Mo ; perplexité 13,9 → 14,5 test : 15 s
complet : 21 min
make test EX=FORM15 VAR=gguf-llamacpp
non testé version grosse infra jamais exécutée 15-quantification/infra/

Résultats et durées mesurés sur RTX 5070 Ti Laptop (12 Go, 11,5 Gio utilisables), 30 Go de RAM ; résultats de la configuration complète. make test lance un test rapide sur un petit modèle ; make run lance l'exemple complet ; make verifier contrôle d'abord les prérequis. Installation : Installer et lancer.

make install EXTRAS=1
make test EX=FORM15
make run EX=FORM15

Utilisation

python run.py --quick                                      # torchao int8 poids seuls (fonctionne sur CPU)
python run.py                                              # NF4 bitsandbytes, Qwen2.5-1.5B-Instruct
../.venv-llmcompressor/bin/python run.py --set methode=gptq   # llmcompressor, dans son propre venv
../.venv-llmcompressor/bin/python run.py --set methode=awq
python run.py --set methode=torchao_int4wo
python run.py --set methode=qat --set modele.nom=Qwen/Qwen2.5-0.5B-Instruct   # fine-tuning complet fp32 : 0,5B sur 12 Go
python variantes/gguf-llamacpp/run.py --quick              # nécessite llama.cpp compilé (voir config)

Dépendances selon la méthode : bitsandbytes (bnb), torchao (torchao, qat), llmcompressor (gptq, awq). llm-compressor impose sa propre version de torch et de transformers : il s'installe dans un venv séparé (python3 -m venv .venv-llmcompressor && .venv-llmcompressor/bin/pip install llmcompressor datasets pyyaml). Voir requirements-extras.txt.

Paramètres principaux

Clé Rôle
methode Voir le tableau
gptq.schema W4A16, W8A16 ou W8A8
calibration.n, longueur Données de calibration (GPTQ/AWQ) : représentatives de l'usage réel
qat.* Groupe de quantification et fine-tuning QAT

Grosse infra

  • Quantifier ne demande pas de cluster. llm-compressor calibre un 70B couche par couche sur 1 à 2 GPU (infra/gptq_70b_llmcompressor.py). GGUF tourne sur CPU.
  • Le multi-GPU sert à servir (vLLM --tensor-parallel-size) et à évaluer la dégradation sur des benchmarks (infra/lancer.sh : lm-eval du modèle bf16 et du modèle quantifié).
  • infra/config.yaml : run.py complet sur un 8B (GPTQ W4A16) sur 1 GPU 40 à 80 Go.
  • QAT sur gros modèles : torchtune / Axolotl (recettes QAT torchao), avec la même infra que le SFT (DATA02).
  • Cache KV quantifié (FP8) pour les longs contextes : vllm serve ... --kv-cache-dtype fp8.