AmeliorIA

tekio.org

Exemple de code : Extension de vocabulaire

Ce que le dossier 13-extension-vocabulaire/ fournit pour cette méthode. Principe et références : Extension de vocabulaire.

Ce que fait l'exemple

Le besoin : servir un modèle dans une langue ou un domaine que son tokenizer découpe mal. Chaque mot coûte alors plusieurs tokens : la génération est plus lente, le contexte se remplit plus vite et chaque appel coûte plus cher. Ici, le breton : 2,5 caractères par token avec le tokenizer de Qwen.

Résultats (Qwen2.5-0.5B, RTX 5070 Ti Laptop ; 600 articles jamais vus ; 3 graines, make graines EX=FORM13 N=3) :

Tokens des articles de test Caractères par token Bits par caractère
Avant 196 039 2,48 2,82
1 000 tokens ajoutés, initialisés par moyenne 165 133 (−15,8 %, ± 0,3) 2,94 2,59
après les deux phases d'entraînement 165 133 2,94 1,602
Témoin : même entraînement, tokenizer d'origine 196 039 2,48 1,572

Par graine, écart de bits par caractère entre le modèle étendu et le témoin : +0,025, +0,033, +0,031.

Ce qu'on en retient.

  • Le gain de la méthode est la compression : le même texte breton tient en 16 % de tokens en moins, sur les trois graines. La génération demande autant de passes en moins, et le contexte contient 19 % de texte en plus.
  • Il se paie d'une petite perte de qualité à entraînement égal : 0,03 bit par caractère de plus que le témoin (2 %), sur chaque graine. Les nouveaux embeddings partent d'une moyenne et n'ont qu'une époque pour se placer ; c'est le budget d'entraînement qui ferait disparaître cet écart.
  • L'entraînement explique la baisse de la perte, pas les nouveaux tokens : le témoin descend autant. Sans témoin, on attribuerait à tort à l'extension du vocabulaire le passage de 2,82 à 1,60 bit par caractère.
  • L'initialisation par moyenne fonctionne : juste après l'ajout, avant tout entraînement, la perte est déjà plus basse qu'avec l'ancien tokenizer (2,82 → 2,59).

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-0.5B<br/>Wikipédia en breton"]
  Cache[("cache disque<br/>~/.cache/huggingface")]
  subgraph Py["Processus Python"]
    Run["run.py<br/>charge les articles<br/>bits par caractère"]
    Tok["tokenizer<br/>add_tokens"]
    Tr["Trainer transformers<br/>phase 1, phase 2"]
  end
  GPU["GPU CUDA, 12 Go"]
  Out[("sorties/<br/>13-extension-vocabulaire/")]

  Hub -- "① HTTPS GET, 1re fois<br/>poids (1 Go), articles" --> Cache
  Cache -- "② lecture des poids" --> Run
  Run -- "③ ⑦ copie des poids<br/>en mémoire GPU" --> GPU
  Run -- "④ ⑥ appel Python<br/>découpage, ajout" --> Tok
  Run -- "⑤ ⑧ ⑪ ⑭ noyaux CUDA<br/>passes avant, mesure" --> GPU
  Run -- "⑨ ⑫ appel Python<br/>trainer.train()" --> Tr
  Tr -- "⑩ ⑬ noyaux CUDA<br/>forward, backward" --> GPU
  Tr -- "⑮ écriture<br/>modèle" --> Out
  Run -- "⑯ écriture<br/>resultats.json" --> Out

  GPU ~~~ Out
  class Hub externe
  class Run,Tok,Tr code
  class GPU gpu
  class Cache,Out disque

make run EX=FORM13 vérifie les prérequis (modules, GPU), puis lance run.py dans l'environnement .venv. Le script lit config.yaml (modèle, nombre de tokens à ajouter, initialisation, réglages des deux phases) et charge 3 000 articles de la Wikipédia en breton, une langue que le tokenizer de Qwen découpe mal (2,5 caractères par token, contre environ 4 en anglais). Un article sur cinq est mis de côté pour les mesures (600 articles, jamais vus à l'entraînement), les 2 400 autres servent à l'entraînement.

  • ① Téléchargement. Au premier lancement, le tokenizer et les poids de Qwen2.5-0.5B, modèle de base (environ 1 Go), et la Wikipédia en breton (wikimedia/wikipedia, 20231101.br) sont téléchargés depuis le Hugging Face Hub, par HTTPS.
  • ② Lecture. Tout est rangé dans le cache ~/.cache/huggingface ; les lancements suivants le relisent sur le disque, sans réseau.
  • ③ Copie sur le GPU. Les poids sont copiés en fp32 dans la mémoire du GPU.
  • ④ Choix des tokens. run.py compte les mots des articles d'entraînement présents au moins 5 fois, demande au tokenizer d'origine en combien de morceaux il découpe chacun, et garde les 1 000 mots qui font gagner le plus de tokens : mots courants (« gant », « eus », « hag », « evit ») et mots plus longs (« Ganedigezhioù », « Stadoù-Unanet »).
  • ⑤ Mesure avant. Deux mesures sur les 600 articles de test, comparables entre tokenizers : le nombre total de tokens, et les bits par caractère (la perte du modèle rapportée au nombre de caractères, pas de tokens). Chaque texte demande une passe avant.
  • ⑥ Ajout au tokenizer. Les 1 000 mots sont ajoutés avec add_tokens, chacun précédé de son espace, comme les mots du vocabulaire BPE d'origine.
  • ⑦ Agrandissement des embeddings. La matrice d'embeddings de Qwen2.5-0.5B, partagée entre l'entrée et la sortie, compte 151 936 lignes pour 151 665 tokens : 1 000 nouveaux tokens dépassent ses lignes de réserve, et resize_token_embeddings la porte à 152 665 lignes. Chaque nouveau token reçoit la moyenne des embeddings des sous-tokens qui le découpaient avec le tokenizer d'origine.
  • ⑧ Mesure après ajout, avant tout entraînement.
  • ⑨ Phase 1, embeddings seuls. Le reste du modèle est gelé. Les articles d'entraînement sont concaténés et découpés en blocs de 512 tokens (1 442 blocs), confiés au Trainer de transformers : 1 époque, lots de 2, accumulation 8, taux d'apprentissage 1e-3.
  • ⑩ Forward et backward sur le GPU, avec mise à jour de la seule matrice d'embeddings.
  • ⑪ Mesure après phase 1.
  • ⑫ Phase 2, modèle complet. Tous les poids sont dégelés : 1 époque, lots de 1, accumulation 16, taux 2e-5, gradient checkpointing.
  • ⑬ Forward et backward sur le GPU, avec mise à jour de tous les poids.
  • ⑭ Mesure après phase 2.
  • ⑮ Écriture du modèle et du tokenizer agrandi dans sorties/13-extension-vocabulaire/modele/.
  • ⑯ Écriture du rapport dans sorties/13-extension-vocabulaire/resultats.json, avec le même tableau affiché dans le terminal.

Témoin. Avant ⑯, le modèle étendu quitte le GPU et Qwen2.5-0.5B d'origine y est rechargé, avec son tokenizer inchangé. Il suit les deux mêmes phases (⑨ à ⑬), sur les mêmes articles et le même nombre d'époques (le même texte fait 1 724 blocs avec l'ancien tokenizer), puis il est mesuré comme en ⑭. L'écart avec apres_phase2 isole ce qu'apportent les nouveaux tokens, l'entraînement étant le même. temoin: false le désactive.

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. Les mesures (⑤, ⑧, ⑪, ⑭) ne font qu'une passe avant par texte, sans génération. L'agrandissement (⑦) alloue une nouvelle matrice d'embeddings sur le GPU et y recopie les anciennes lignes. En entraînement (⑩, ⑬), chaque pas fait une passe avant, une passe arrière qui calcule les gradients, puis la mise à jour par AdamW : en phase 1, gradients et état de l'optimiseur n'existent que pour la matrice d'embeddings ; en phase 2, pour tout le modèle. Les poids restent en fp32, les calculs d'entraînement se font en bf16.

Ce qui est écrit.

Fichier Contenu
modele/model.safetensors Le modèle complet après les deux phases, avec sa matrice d'embeddings de 152 665 lignes (2,0 Go, en fp32)
modele/tokenizer.json, tokenizer_config.json, chat_template.jinja Le tokenizer agrandi des 1 000 nouveaux tokens : il doit accompagner le modèle, l'ancien tokenizer ne correspond plus à ses embeddings
modele/config.json, generation_config.json L'architecture, avec vocab_size: 152665, et les réglages de génération
modele/training_args.bin Les réglages d'entraînement de la phase 2
phase1/, phase2/, temoin-phase1/, temoin-phase2/ Dossiers de travail du Trainer, vides : aucun point de contrôle n'est sauvegardé
resultats.json Pour avant, apres_init, apres_phase1, apres_phase2 et temoin : tokens_corpus_test, caracteres_par_token et bits_par_caractere ; la liste nouveaux_tokens des 1 000 mots ajoutés
config_effective.yaml La configuration réellement utilisée, surcharges SET comprises

Essayer dans le dépôt

Exemple Statut Résultat mesuré Durée Commande
exemple principal démontré tokens du texte breton −15,8 % (2,48 → 2,94 caractères par token, 3 graines) ; bits par caractère 1,602 contre 1,572 pour le témoin — à entraînement égal, qualité 2 % sous le témoin test : 23 s
complet : 13 min
make test EX=FORM13
non testé version grosse infra jamais exécutée 13-extension-vocabulaire/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=FORM13
make run EX=FORM13

Utilisation

python run.py --quick
python run.py                                                  # Qwen2.5-0.5B + 1 000 mots bretons, ~13 min
python run.py --set vocabulaire.init=aleatoire                 # comparer apres_init : bits par caractère bien plus hauts
python run.py --set "vocabulaire.liste=[Kavelmor, Zanlisia]"
python run.py --set donnees.config=20231101.oc                 # une autre langue : occitan
python run.py --set donnees.source=faits --set donnees.n_entites=80 --set vocabulaire.n_nouveaux=200 --set vocabulaire.min_freq=3   # noms inventés, sans téléchargement
make graines EX=FORM13 N=3                                     # trois graines : moyenne et écart type

Paramètres principaux

Clé Rôle
vocabulaire.n_nouveaux, min_freq, liste Choix des tokens
vocabulaire.init moyenne ou aleatoire
phase1.* / phase2.* Deux jeux d'hyperparamètres (lr élevé puis faible)

Grosse infra

  • infra/entrainer_tokenizer.py : BPE de la langue cible fusionné dans le tokenizer d'origine (sur CPU, quelques minutes).
  • infra/config.yaml : Llama-3.1-8B + 10 000 tokens coréens, phase 1 (2 000 pas) et phase 2 sur 500k articles, FSDP sur 8×H100. Le vrai coût est la phase 2 : plusieurs milliards de tokens, voir 01 infra.
  • Méthodes avancées d'initialisation : FOCUS, WECHSEL (alignement d'embeddings multilingues), ZeTT (hypernetwork).