|
Download README.md from finanfa-tech/fon-nlu: direct link, hf CLI and curl.
- Browser
- Download file 14 kB
-
https://huggingface.co/finanfa-tech/fon-nlu/resolve/main/README.md
- Command line
-
hf download hf://finanfa-tech/fon-nlu/README.md
-
curl -L -o README.md https://huggingface.co/finanfa-tech/fon-nlu/resolve/main/README.md
14 kB
| language: | |
| - fon | |
| - fr | |
| license: cc-by-nc-4.0 | |
| library_name: scikit-learn | |
| pipeline_tag: text-classification | |
| tags: | |
| - fon | |
| - fongbe | |
| - benin | |
| - low-resource | |
| - nlu | |
| - intent-classification | |
| - slot-filling | |
| - mobile-money | |
| - voice-assistant | |
| - code-switching | |
| - finanfa-tech | |
| # fon-nlu — compréhension de commandes Mobile Money en fon, français et mélange fon-français | |
| **Petit modèle de compréhension (NLU) pour un assistant vocal de paiement mobile** : à partir d'une phrase (la transcription de ce que dit l'utilisateur) en **fon, en français ou en mélange des deux**, il trouve **ce que veut faire l'utilisateur** (l'intention) et en extrait **les informations utiles** (montant, destinataire, numéro de compteur ou de police). | |
| **Auteur : AWADEME Ronaldo — [Finanfa Tech](https://huggingface.co/finanfa-tech)** | |
| > 🇬🇧 *English summary:* A lightweight intent classifier + rule-based slot extractor for Mobile Money voice commands in Fon (Fongbe), French and Fon–French code-switching (Benin). v1.1.0: 11 intents (money transfer, SBEE electricity and SONEB water bill payment, balance check, airtime purchase, meter/policy number, recipient, yes, no, help/FAQ, and an out-of-scope class), trained on 2,630 examples. Fon amount expressions (e.g. "caki wè" = 2,000 FCFA, "kpowun ko atɔ́ɔ́n" = 625 FCFA) were validated by a native speaker. **Accuracy on unseen phrase forms: 96.0 % for the classifier alone, 97.8 % with a hand-written rule that separates electricity from airtime ('credit' counts as electricity only if SBEE, meter, 'courant' or 'électricité' is said)** – optimistic, because most of the data is template-based (all of it reviewed by the native speaker). Research-grade; never execute a payment without reading back the amount and recipient and asking for confirmation. Non-commercial license (CC-BY-NC-4.0). | |
| ## ⚠️ À lire avant d'utiliser | |
| - **Ne déclenchez jamais un paiement sans relire à voix haute le montant et le destinataire, et sans confirmation explicite de l'utilisateur.** Le modèle se trompe, et une erreur sur un montant est une erreur financière. | |
| - **Précision sur formes inédites : 96,0 % pour le modèle seul (macro-F1 95,7 %), 97,8 % avec la règle de l'électricité** (macro-F1 96,8 %), mesurée en validation croisée où les phrases de même forme restent ensemble. **Ces chiffres sont optimistes** : 1 646 des 2 630 exemples ont été générés pour le projet (puis relus par le locuteur) à partir de gabarits ; les phrases ne sont que 737 formes différentes. Sur des phrases réellement dites par des utilisateurs, attendez-vous à moins. La validation croisée classique donnerait presque 100 %, ce qui serait **trompeur**. | |
| - **Règle de l'électricité (écrite à la main, dans `nlu_engine.py`)** : quand le modèle hésite entre `achat_credit` et `paiement_sbee`, la phrase est un **paiement d'électricité seulement si elle contient** SBEE, « compteur » (français ou fon : « kɔ́mtɛ́ɛ́ »…), un numéro de compteur à 11 chiffres, « courant », « électricité » ou « hlɔnhlɔn » ; sinon c'est un **achat de crédit de communication**. Une phrase d'électricité qui ne dit aucun de ces mots sera donc comprise comme du crédit mobile. | |
| - **Une classe `inconnu` existe maintenant** (hors sujet), mais elle n'est pas fiable à elle seule : **rejetez aussi en dessous de 0,6 de confiance** et ne traitez jamais `inconnu` comme un ordre. | |
| - **« Acheter du crédit de communication » est le point faible du modèle seul** : 65 % de rappel avant la règle (confusion avec l'électricité). La règle ci-dessus corrige cela (rappel 97 %), mais repose sur des mots-clés. Vérifiez toujours le type d'opération avec l'utilisateur avant de payer. | |
| - **Texte uniquement** : le modèle reçoit du texte. Il n'a pas été testé sur des transcriptions automatiques de parole, qui contiennent des erreurs. | |
| - **Les contacts fournis dans `contact_resolver.py` sont fictifs** (numéros factices). En production, passez toujours la vraie liste de contacts de l'utilisateur. | |
| - **Usage non commercial uniquement** (CC-BY-NC-4.0). Fichier `.joblib` : ne le chargez que depuis une source de confiance (format pickle). | |
| ## Ce que fait le modèle | |
| **11 intentions** (voir la règle de l'électricité plus haut pour `achat_credit` / `paiement_sbee`) : `transfert_argent`, `paiement_sbee` (électricité), `paiement_soneb` (eau), `consulter_solde`, `achat_credit` (crédit de communication), `fournir_compteur` (donner un compteur ou une police en réponse), `fournir_destinataire` (donner le destinataire en réponse), `confirmation_oui`, `annulation_non`, `demande_aide_faq` (aide, frais, limites) et `inconnu` (hors sujet). | |
| **Informations extraites** (par des règles, pas par le modèle) : `montant` (en FCFA), `destinataire_nom` (avec résolution des liens de parenté : « nɔ ce » = Maman, « tɔ́ ce » = Papa…), `destinataire_numero`, `numero_compteur` (11 chiffres), `numero_police` (8 chiffres), `compteur_nom` (« compteur maison »…). | |
| ### Les montants en fon (validés par le locuteur) | |
| Les expressions suivantes ont été relues et validées par AWADEME Ronaldo, locuteur natif du fon. Une même valeur peut s'écrire de plusieurs façons (fon, français, chiffres). | |
| | Expression | Valeur | Exemples dans les données | | |
| |---|---|---| | |
| | kpowun ko | 500 FCFA | 30 | | |
| | kpowun ko nukun ɛnɛ | 600 FCFA | 62 | | |
| | kpowun ko atɔ́ɔ́n | 625 FCFA | 13 | | |
| | caki ɖokpó | 1 000 FCFA | 25 | | |
| | mille francs | 1 000 FCFA | 20 | | |
| | caki wè | 2 000 FCFA | 27 | | |
| | deux mille | 2 000 FCFA | 4 | | |
| | deux mille francs | 2 000 FCFA | 2 | | |
| | caki atɔn | 3 000 FCFA | 23 | | |
| | trois mille francs | 3 000 FCFA | 31 | | |
| | caki ɛnɛ | 4 000 FCFA | 13 | | |
| | caki atɔ́ɔ́n | 5 000 FCFA | 25 | | |
| | cinq mille francs | 5 000 FCFA | 11 | | |
| | franc caki atɔ́ɔ́n | 5 000 FCFA | 25 | | |
| | caki ayizɛ́n | 6 000 FCFA | 26 | | |
| | caki tantɔn | 8 000 FCFA | 12 | | |
| | caki wǒ | 10 000 FCFA | 19 | | |
| | dix mille | 10 000 FCFA | 15 | | |
| | caki afɔtɔ́n | 15 000 FCFA | 23 | | |
| | quinze mille francs | 15 000 FCFA | 20 | | |
| | caki ko | 20 000 FCFA | 17 | | |
| | vingt mille francs | 20 000 FCFA | 23 | | |
| | caki kande-wǒ | 50 000 FCFA | 21 | | |
| | cinquante mille francs | 50 000 FCFA | 10 | | |
| | caki kanweko | 100 000 FCFA | 3 | | |
| | cent mille francs | 100 000 FCFA | 27 | | |
| | deux cent mille | 200 000 FCFA | 21 | | |
| Les chiffres (« 5000 », « 50 000 ») et le français (« cinq mille francs », « quatre vingt mille ») sont aussi compris. | |
| ## Utilisation | |
| ```bash | |
| pip install -r requirements.txt # scikit-learn 1.9.1, numpy, joblib | |
| hf download finanfa-tech/fon-nlu --local-dir fon-nlu | |
| cd fon-nlu | |
| ``` | |
| ```python | |
| from nlu_engine import VoiceMoMoNLU | |
| nlu = VoiceMoMoNLU() | |
| r = nlu.parse("Un jló na sɛ́ cinq mille francs dó Femi") | |
| print(r["intent"], r["confidence"], r["slots"]) | |
| # transfert_argent 0.98 {'montant': {'raw': 'cinq mille francs', 'normalized': 5000}, 'destinataire_nom': {...}} | |
| if r["confidence"] < 0.6: | |
| pass # phrase non comprise : redemander à l'utilisateur | |
| # sinon : relire « {montant} FCFA à {destinataire} » à voix haute et demander une confirmation avant tout paiement | |
| ``` | |
| Les scripts doivent rester dans le même dossier (le modèle utilise les fonctions `normalize` et `normalize_masked` de `fon_amount_parser.py`). | |
| ## Architecture | |
| - **Intentions** : caractéristiques TF-IDF sur les mots (1 à 3) et sur les caractères (2 à 5), après suppression des accents et des signes du fon, avec **masquage des nombres** (compteur à 11 chiffres, numéro à 8 chiffres, montant : le modèle apprend la forme, pas la valeur), puis SVM linéaire à probabilités calibrées (scikit-learn). | |
| - **Informations** : règles et expressions régulières, un analyseur de montants (fon, français, chiffres), un résolveur de contacts (liens de parenté, correspondance approchée). | |
| - Taille : 283 Ko pour le modèle ; environ 4 ms par phrase sur un processeur (mesuré sur un Mac, Python 3.13). | |
| ## Données d'entraînement | |
| **2 630 exemples** (1 022 en français, 766 en fon, 842 en mélange), **737 formes de phrase**. Tous les exemples ont été **relus par AWADEME Ronaldo, locuteur natif du fon** : | |
| - **Jeu 1 : 984 exemples**, gabarits écrits pour le projet, relus et corrigés par lui (au moins 117 exemples modifiés) ; audit des 29 expressions de montants validé par lui. Orthographe harmonisée : « caki » sans « franc », « Kɔ́mtɛ́ɛ́ » pour « compteur ». | |
| - **Lot 2 : 720 exemples**, générés pour le projet (le fon vient en partie d'une traduction automatique), puis relus et corrigés par lui (13 exemples modifiés lors de la dernière relecture, 4 supprimés). 116 exemples au fon douteux ont été écartés. | |
| - **Lot 3 : 823 exemples**, générés à partir des formes validées du jeu 1 et de dialogues validés (nouveaux montants, noms, numéros), relus par lui. | |
| - **Lot 4 : 103 exemples**, variantes des formes qu'il a corrigées dans le lot 2 (achat de crédit « credit caki … », numéros de police « minɛlo … »), avec des montants et numéros différents, relus par lui (7 corrections). Règle de l'auteur : une phrase d'achat de crédit qui commence par « Un ba » ne finit jamais par « nu mi ». | |
| - **52 exemples retirés** : ils contenaient « kpataki », un mot qui n'est pas du fon, venu d'un gabarit écrit par erreur. | |
| Les noms et numéros sont des valeurs de test. Un seul relecteur. Le jeu de données n'est pas public. Voir la carte du jeu : `finanfa-tech/fon-nlu-data` (privé). | |
| ## Évaluation | |
| Validation croisée en 5 plis où les phrases de même forme restent ensemble (aucune fuite entre entraînement et test). **Modèle seul, sans la règle de l'électricité** : | |
| | Intention | Précision | Rappel | F1 | Exemples | | |
| |---|---|---|---|---| | |
| | achat_credit | 0.86 | 0.98 | 0.91 | 310 | | |
| | annulation_non | 1.00 | 0.98 | 0.99 | 116 | | |
| | confirmation_oui | 1.00 | 0.99 | 1.00 | 116 | | |
| | consulter_solde | 0.99 | 0.97 | 0.98 | 157 | | |
| | demande_aide_faq | 0.93 | 0.94 | 0.94 | 55 | | |
| | fournir_compteur | 0.99 | 0.92 | 0.95 | 197 | | |
| | fournir_destinataire | 0.91 | 0.92 | 0.91 | 95 | | |
| | inconnu | 0.88 | 0.97 | 0.92 | 151 | | |
| | paiement_sbee | 0.99 | 0.89 | 0.94 | 424 | | |
| | paiement_soneb | 1.00 | 1.00 | 1.00 | 291 | | |
| | transfert_argent | 0.98 | 0.98 | 0.98 | 718 | | |
| **Modèle seul : précision 96,0 %, F1 macro 95,7 %. Avec la règle de l'électricité : précision 97,8 %, F1 macro 96,8 %** (`achat_credit` : précision 98 %, rappel 98 % ; `paiement_sbee` : précision 100 %, rappel 99,5 %). Sur le seul jeu 1, modèle seul : 96,1 %. | |
| **Comparaison avec la version 1.0.0** (8 intentions, jeu 1 seul, modèle seul) : sur 1 289 exemples nouveaux dont l'intention existait déjà, la 1.0.0 obtenait 89,4 % et la 1.1.0 (entraînée sans ces formes) 90,6 % avant retrait de « kpataki » et règle. **Le gain du modèle seul est modeste** ; l'essentiel du progrès vient des 3 nouvelles intentions, de la reconnaissance de l'eau (SONEB, en partie grâce à des exemples très gabarités) et de la règle. | |
| Extraction du montant : 1 617 sur 1 617 exacts sur le jeu de développement. Ce chiffre n'est **pas indépendant** (les règles ont été écrites en regardant ces exemples) ; il ne prouve pas que tout montant dit autrement sera bien lu. | |
| ## Limites connues | |
| - Seulement 737 formes de phrase, dont la plupart sont des variantes de gabarits : une manière de parler différente peut être mal comprise. Plus de phrases réelles, dites naturellement, améliorera surtout le modèle. | |
| - Un seul relecteur : des erreurs de fon restent possibles dans l'entraînement. | |
| - La confusion entre `achat_credit` et `paiement_sbee` est corrigée par la règle de l'électricité (mots-clés) ; une phrase d'électricité sans mot-clé sera lue comme du crédit mobile. | |
| - « Dó Maman » seul n'est pas reconnu avec certitude comme `fournir_destinataire` (confiance faible). | |
| - Orthographe et tons du fon variables : le modèle ignore les tons, ce qui fusionne des mots différents. | |
| - Un seul relecteur ; système de comptage traditionnel (kpowun, caki, kantaan) validé sur les 29 expressions listées seulement. | |
| ## Versions | |
| - **1.3.0 (2026-11-16)** : lot 4 (103 variantes des formes corrigées par l'auteur) ; 2 630 exemples ; « caki wǒ atɔn » = 13 000 et « caki ko atɔn » = 23 000 (dizaine + unité) ; **« wɛ » (démonstratif) n'est plus lu comme le chiffre « wè » (2)**. Précision 96,0 % (modèle seul) / 97,8 % (avec la règle de l'électricité). | |
| - **1.2.0 (2026-11-16)** : lots 2 et 3 relus par l'auteur ; entraînement de zéro sur 2 527 exemples (orthographe harmonisée : « caki » sans « franc », « Kɔ́mtɛ́ɛ́ »). Précision 93,5 % (modèle seul) / 97,7 % (avec la règle de l'électricité), légèrement plus basse que la 1.1.1 parce que les corrections de l'auteur ajoutent des formes de phrase nouvelles et plus difficiles. | |
| - **1.1.1 (2026-11-16)** : retrait de 52 exemples contenant « kpataki » (mot qui n'est pas du fon) ; règle de l'électricité (SBEE / compteur / courant / électricité / hlɔnhlɔn) ; textes corrigés par l'auteur. 2 529 exemples. | |
| - **1.1.0 (2026-11-16)** : 11 intentions (ajout de `fournir_destinataire`, `demande_aide_faq`, `inconnu`) ; 2 581 exemples (lots 2 et 3 ajoutés) ; masquage des nombres ; analyseur de montants corrigé (« quatre vingt mille », virgule après un montant fon, « kpowun ko atɔ́ɔ́n » = 625) ; « franc caki » devient « caki ». | |
| - **1.0.0 (2026-11-15)** : première version publique. Entraînée sur 991 exemples corrigés ; bug corrigé dans l'analyse des montants (le « un » du fon était compté comme un chiffre : « Un jló na sɛ́ cinq mille » donnait 6 000 au lieu de 5 000) ; « kpowun ko atɔ́ɔ́n » = 625 FCFA ajouté. | |
| ## Licence | |
| CC-BY-NC-4.0 (usage non commercial, attribution). | |
| ## Citation | |
| AWADEME Ronaldo, Finanfa Tech. *fon-nlu : compréhension de commandes Mobile Money en fon, français et mélange*, 2026. https://huggingface.co/finanfa-tech/fon-nlu | |