| --- |
| license: other |
| language: |
| - wo |
| base_model: McGill-NLP/AfriqueQwen3.5-4B-50Langs |
| library_name: transformers |
| pipeline_tag: text-generation |
| tags: |
| - wolof |
| - lora |
| - rslora |
| - qwen3.5 |
| - math |
| --- |
| |
| # Xalaat-R1-4B |
|
|
| Modèle de **raisonnement mathématique en wolof**, obtenu par continued pretraining |
| (CPT) puis instruction tuning (SFT) rsLoRA sur |
| [McGill-NLP/AfriqueQwen3.5-4B-50Langs](https://huggingface.co/McGill-NLP/AfriqueQwen3.5-4B-50Langs). |
| Le modèle à la racine du dépôt est la version **fusionnée CPT+SFT**, chargeable |
| directement, sans PEFT. |
|
|
| Ce qu'il sait faire : résoudre un problème arithmétique posé en wolof, en |
| détaillant les étapes, et terminer par `#### <réponse>`. Le SFT est intégralement |
| du GSM8K traduit en wolof, avec un seul prompt système. **Rien n'établit sa |
| capacité en conversation wolof générale**, et les mesures ci-dessous montrent |
| qu'elle n'y est pas. |
|
|
| ## Trois prérequis d'inférence |
|
|
| Sans ces trois conditions, le modèle est hors distribution et dégénère. Ce ne sont |
| pas des recommandations. |
|
|
| 1. **Le prompt système du SFT**, reproduit dans l'exemple ci-dessous. Les 7273 |
| exemples d'entraînement le partagent tous, et 100 % de leurs réponses |
| se terminent par `#### <réponse><|im_end|>`. Sans lui, le modèle produit de la |
| prose, n'atteint jamais le marqueur `####`, et n'émet donc jamais sa fin de |
| tour. |
| 2. **`enable_thinking=False`** dans `apply_chat_template`. Le corpus SFT a un bloc |
| `<think></think>` vide ; le gabarit ne l'écrit que si on passe ce paramètre. |
| Par défaut il ouvre `<think>` et le modèle part en boucle. |
| 3. **`transformers >= 5.5`**, la version qui introduit l'architecture `qwen3_5`. |
| Testé avec 5.15.1 et `torch` 2.13.0. |
| |
| ## Arrêt de génération : corrigé |
| |
| L'ancien `generation_config.json` déclarait `eos_token_id: [248044, 248044]`, soit |
| `<|endoftext|>`, hérité du modèle de base via `_from_model_config: true`. Or ce |
| modèle est entraîné en ChatML et termine ses tours sur `<|im_end|>` (**248046**), |
| que rien n'écoutait. C'est la cause des boucles de répétition, un défaut de |
| configuration et non d'entraînement : aucun réentraînement n'a été nécessaire. |
| |
| `generation_config.json` déclare maintenant `eos_token_id: [248046, 248044]` et |
| `tokenizer_config.json` a `eos_token: "<|im_end|>"`. Un appel qui fixe lui-même |
| `eos_token_id` reste la garantie la plus sûre. |
| |
| ## Usage |
| |
| ```python |
| import torch |
| from transformers import AutoModelForCausalLM, AutoTokenizer |
| |
| REPO = "Fallovski/Xalaat-R1-4B" |
| SYSTEM = ( |
| "Yow, danga am xam-xam bu rëy ci matématik ak ci Wolof. Sa liggéey mooy " |
| "jàppale ma ci ay laaj matématik. Su ma la laajee ab laaj, wone ma ni nga " |
| "ko defee (tegtal bi) ci ay xàjj yu toppante (step-by-step), ba noppi, ci " |
| "tontu bu mujj bi, nga teg ci kanam '####'." |
| ) |
| |
| # device explicite plutôt que device_map="auto", qui exige `accelerate`. |
| device = "cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu" |
| tokenizer = AutoTokenizer.from_pretrained(REPO) |
| model = AutoModelForCausalLM.from_pretrained(REPO, dtype=torch.bfloat16).to(device).eval() |
| |
| messages = [ |
| {"role": "system", "content": SYSTEM}, |
| {"role": "user", "content": "Am naa ñaari mango, may naa benn, ñaata mango la dess?"}, |
| ] |
| inputs = tokenizer.apply_chat_template( |
| messages, |
| add_generation_prompt=True, |
| enable_thinking=False, |
| return_tensors="pt", |
| return_dict=True, |
| ).to(device) |
| |
| out = model.generate( |
| **inputs, |
| max_new_tokens=512, |
| do_sample=False, |
| eos_token_id=[tokenizer.convert_tokens_to_ids("<|im_end|>"), tokenizer.eos_token_id], |
| pad_token_id=tokenizer.pad_token_id, |
| ) |
| print(tokenizer.decode(out[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True)) |
| # Am naa ñaari mango, may naa benn, kon am naa 2-1=1 mango bu des. |
| # #### 1 |
| ``` |
| |
| ## Playground |
| |
| `playground.py`, à la racine du dépôt, est un seul fichier qui ne demande que |
| `torch` et `transformers >= 5.5`. Il applique les trois prérequis ci-dessus par |
| défaut, donc il n'y a rien à configurer pour essayer le modèle. |
| |
| ```bash |
| python playground.py # conversation |
| python playground.py --prompt "Ñaata mango la dess?" # une seule question |
| python playground.py --prompt "…" --temperatures 0 0.7 # la même, plusieurs tirages |
| ``` |
| |
| La réponse s'affiche en flux, et sous elle le nombre extrait du `####` — ou un |
| avertissement quand la sortie sort du format. `/sweep` rejoue la dernière |
| question à plusieurs températures et donne l'accord entre tirages : quatre |
| tirages d'accord signalent un raisonnement tenu, quatre réponses différentes une |
| réponse tirée au sort. `/aide` liste les commandes. |
| |
| ## Évaluation |
| |
| `lm_eval` 0.4.12, `transformers` 5.15.1, `torch` 2.13.0, Apple M4 Max en MPS, |
| bfloat16, batch 1. Gabarit ChatML appliqué, exemples few-shot présentés comme de |
| vrais tours de conversation, `eos_token_id=248046` imposé. Le prompt système du |
| SFT est utilisé sur AfriMGSM uniquement : il est spécifique aux mathématiques, et |
| l'appliquer aux trois autres tâches les biaiserait. |
| |
| ### AfriMGSM wolof — le CPT+SFT est validé |
| |
| `afrimgsm_cot_wol_prompt_1` (IrokoBench, Adelani et al. NAACL 2025), 250 exemples, |
| soit tout le split `test`. Métrique `flexible-extract`. |
| |
| | Condition | Xalaat-R1-4B | Base AfriqueQwen | Rapport | |
| |---|---|---|---| |
| | 0-shot | **0,260** ± 0,028 | 0,052 ± 0,014 | ×5,0 | |
| | 3-shot | **0,308** ± 0,029 | 0,060 ± 0,015 | ×5,1 | |
|
|
| L'écart vaut plus de sept erreurs-types dans les deux conditions. C'est la mesure |
| qui justifie le CPT et le SFT. |
|
|
| `strict-match` vaut 0,00 pour les deux modèles et ne départage rien : son filtre |
| cherche `"The answer is (N)"`, une formule anglaise, quand ce modèle est entraîné |
| à écrire `#### N`. Ne pas lire ce 0 comme une incompétence. |
|
|
| Le format explique une partie de l'écart. Sur les mêmes 250 sorties 0-shot : |
|
|
| | | Contient `####` | `####` suivi d'un nombre | Longueur médiane | |
| |---|---|---|---| |
| | Xalaat-R1-4B | 79,2 % | **78,8 %** | 299 car. | |
| | Base AfriqueQwen | 34,4 % | **1,2 %** | 618 car. | |
|
|
| La base imite le marqueur sans s'en servir comme emplacement de réponse : elle |
| l'écrit une fois sur trois, mais y met un nombre une fois sur cent. Ses sorties |
| sont deux fois plus longues, signe qu'elle ne sait pas terminer son tour. Chez |
| Xalaat, 0,8 % des sorties gardent une répétition résiduelle. |
|
|
| ### Tâches à choix multiples — aucun gain démontré |
|
|
| 300 exemples, 3-shot, sans prompt système. |
|
|
| | Tâche | Xalaat-R1-4B | Base AfriqueQwen | |
| |---|---|---| |
| | `afrixnli_native_direct_wol` (inférence) | 0,380 ± 0,028 | 0,363 ± 0,028 | |
| | `belebele_wol_Latn` (compréhension) | 0,273 ± 0,026 | 0,203 ± 0,023 | |
| | `sib_wol_prompt_1` (classification de sujet) | 0,353 ± 0,034 | 0,324 ± 0,033 | |
|
|
| Les écarts d'`afrixnli` et de `sib` tiennent dans les marges d'erreur. Celui de |
| `belebele` les dépasse à peine, mais 0,273 sur quatre choix reste le niveau du |
| hasard : les deux modèles échouent, l'un un peu moins mal que l'autre. |
|
|
| Le gain du fine-tuning est donc **spécifique à la tâche entraînée**. C'est |
| cohérent avec un SFT entièrement constitué de GSM8K traduit. |
|
|
| ## Limitations |
|
|
| - **Domaine restreint.** GSM8K traduit et un prompt système de mathématiques : |
| hors de ce cadre, rien n'est mesuré. |
| - **Numéraux wolof non standardisés mal lus.** En orthographe phonétique, `niet` |
| et `niee` (ñett, trois) sont interprétés comme 1. Les chiffres arabes, les |
| numéraux français (`quinze`, `trois`) et l'orthographe standardisée (`ñaari`, |
| `benn`) fonctionnent. Une normalisation en amont est nécessaire pour un usage |
| réel. |
| - **Artefacts d'entraînement.** 29,4 % du corpus SFT (2137 exemples) contient les |
| annotations calculatrices de GSM8K (`<<16-3-4=9>>`), que le modèle reproduit en |
| sortie. À nettoyer avant tout nouveau SFT. |
| - **Pollution translingue.** Des tokens d'autres langues apparaissent |
| occasionnellement dans des réponses par ailleurs correctes. |
| - **Wolof uniquement.** Le CPT et le SFT ne ciblaient que le wolof, et |
| l'évaluation ci-dessus ne couvre que lui. Les 47 autres langues du modèle de |
| base ne sont pas mesurées ici et un fine-tuning de cette ampleur les dégrade |
| généralement. |
| - **Corpus wolof d'entraînement modeste** au regard des standards du continued |
| pretraining. |
|
|
| ## Reproduction |
|
|
| Six runs : deux en 0-shot sur AfriMGSM, quatre dans la suite 3-shot. Le même jeu |
| de commandes sert pour ce dépôt et pour le modèle de base. |
|
|
| ```bash |
| MODEL=Fallovski/Xalaat-R1-4B # ou McGill-NLP/AfriqueQwen3.5-4B-50Langs |
| SYS="Yow, danga am xam-xam bu rëy ci matématik ak ci Wolof. Sa liggéey mooy jàppale ma ci ay laaj matématik. Su ma la laajee ab laaj, wone ma ni nga ko defee (tegtal bi) ci ay xàjj yu toppante (step-by-step), ba noppi, ci tontu bu mujj bi, nga teg ci kanam '####'." |
| COMMON="--model hf --model_args pretrained=$MODEL,dtype=bfloat16 --device mps |
| --batch_size 1 --apply_chat_template --gen_kwargs eos_token_id=248046 |
| --log_samples --output_path results/" |
| |
| # AfriMGSM 0-shot, tout le split test (250) |
| lm_eval $COMMON --tasks afrimgsm_cot_wol_prompt_1 --num_fewshot 0 \ |
| --system_instruction "$SYS" |
| |
| # AfriMGSM 3-shot, exemples en tours de conversation |
| lm_eval $COMMON --tasks afrimgsm_cot_wol_prompt_1 --num_fewshot 3 \ |
| --fewshot_as_multiturn --system_instruction "$SYS" |
| |
| # choix multiples 3-shot, 300 exemples, sans prompt système |
| lm_eval $COMMON --num_fewshot 3 --fewshot_as_multiturn --limit 300 \ |
| --tasks afrixnli_native_direct_wol,belebele_wol_Latn,sib_wol_prompt_1 |
| ``` |
|
|
| Deux écarts de protocole à connaître : le run 0-shot de la base n'a pas reçu |
| `eos_token_id=248046`, contrairement à celui de Xalaat (les deux runs 3-shot l'ont |
| reçu et donnent le même rapport, la conclusion n'en dépend pas) ; et Xalaat a été |
| évalué sur `4b62576` en 0-shot puis `5486cbe` ensuite, deux révisions qui ne |
| diffèrent que par la suppression de dossiers de sauvegarde, à poids identiques. |
|
|
| Compter environ 2 h 30 pour la suite 3-shot sur un M4 Max en MPS. |
|
|
