349 lines
17 KiB
Markdown
349 lines
17 KiB
Markdown
# Valider la traduction ONNX — activation du moteur et mesure de la qualité
|
||
|
||
> **Objet** : traiter les deux suites de la traduction hors ligne mobile :
|
||
> (1) activer `OMIKA_ONNX_RUNTIME` et faire tourner une **vraie** paire FR⇄ES ;
|
||
> (2) lever le doute sur le **tokeniseur** SentencePiece.
|
||
>
|
||
> **Cible** : poste de développement (accès NuGet) + un appareil Android.
|
||
> **Prérequis** : `DEPLOIEMENT_API_LANGUES.md` (service serveur) et
|
||
> `TRADUCTION_HORS_LIGNE_MOBILE.md` (côté application) déjà lus.
|
||
|
||
---
|
||
|
||
## 1. Les deux problèmes ne se traitent pas de la même façon
|
||
|
||
| | Nature | Qui peut le faire | Coût |
|
||
|---|---|---|---|
|
||
| **Point 1** — activer le moteur | **Procédure d'exécution** : aucun code à écrire, 3 modifications de projet + une validation à exécuter | Toute machine avec accès NuGet | ~1 h |
|
||
| **Point 2** — tokeniseur | **Travail de code** déjà largement fait (§3.1), puis **mesure** : on ne corrige plus à l'aveugle, on compare à la référence | Développeur | 2 h pour mesurer, variable ensuite |
|
||
|
||
> **Règle directrice pour le point 2** : *ne jamais « améliorer » le tokeniseur
|
||
> sans mesure*. Une normalisation devinée est **pire** que pas de normalisation :
|
||
> elle produit un découpage différent de la référence de façon invisible. On
|
||
> mesure d'abord (§3.3), on corrige ensuite — et seulement ce qui diverge.
|
||
|
||
---
|
||
|
||
## 2. Point 1 — activer le moteur et faire tourner une vraie paire FR⇄ES
|
||
|
||
### 2.1 Prérequis
|
||
|
||
```powershell
|
||
# Vérifier que NuGet est joignable (c'est le seul prérequis bloquant)
|
||
dotnet nuget list source
|
||
# Un pack de langue de test (voir §2.3), et ~5 Go de disque libre
|
||
```
|
||
|
||
### 2.2 Étape A — activer le moteur (3 modifications, aucune ligne de code)
|
||
|
||
1. `Directory.Packages.props` :
|
||
```xml
|
||
<PackageVersion Include="Microsoft.ML.OnnxRuntime" Version="1.20.1" />
|
||
```
|
||
2. `src/Omika.App.Local/Omika.App.Local.csproj` :
|
||
```xml
|
||
<ItemGroup>
|
||
<PackageReference Include="Microsoft.ML.OnnxRuntime" />
|
||
</ItemGroup>
|
||
<PropertyGroup>
|
||
<DefineConstants>$(DefineConstants);OMIKA_ONNX_RUNTIME</DefineConstants>
|
||
</PropertyGroup>
|
||
```
|
||
3. `src/Omika.App/AppServices.cs` — une ligne :
|
||
```csharp
|
||
IOnnxInferenceSessionFactory onnxFactory = OnnxRuntimeInferenceSessionFactory.Instance;
|
||
```
|
||
|
||
**Vérification immédiate** — les deux commandes doivent passer :
|
||
|
||
```powershell
|
||
dotnet build src/Omika.App.Local/Omika.App.Local.csproj -c Debug
|
||
dotnet build tools/Omika.LanguesProbe/Omika.LanguesProbe.csproj -c Debug
|
||
```
|
||
|
||
> `OnnxRuntimeInferenceSessionFactory.cs` est le **seul** fichier dont la
|
||
> compilation dépend du paquet : c'est voulu. S'il ne compile pas, c'est une
|
||
> incompatibilité d'API avec la version du paquet — corrigez ce fichier
|
||
> uniquement, rien d'autre n'en dépend.
|
||
|
||
### 2.3 Étape B — obtenir une paire FR⇄ES réelle
|
||
|
||
Les modèles de traduction ne sont pas livrés avec Omika (poids + licences). Le
|
||
plus simple est un modèle **OPUS-MT** de Helsinki-NLP, exporté en ONNX.
|
||
|
||
```powershell
|
||
pip install "optimum[onnxruntime]" transformers sentencepiece
|
||
|
||
# fr -> es (sert le sens « depuisFrancais » du pack « es »)
|
||
optimum-cli export onnx --model Helsinki-NLP/opus-mt-fr-es .\export\fr-es
|
||
|
||
# es -> fr (sert le sens « versFrancais » du pack « es »)
|
||
optimum-cli export onnx --model Helsinki-NLP/opus-mt-es-fr .\export\es-fr
|
||
```
|
||
|
||
L'export produit notamment :
|
||
|
||
```
|
||
encoder_model.onnx
|
||
decoder_model.onnx
|
||
decoder_with_past_model.onnx <-- NE PAS LIVRER
|
||
source.spm
|
||
target.spm
|
||
```
|
||
|
||
> ⚠️ **`decoder_with_past_model.onnx` ne doit jamais être livré dans le pack.**
|
||
> C'est un décodeur à cache de clés/valeurs (`past_key_values`) destiné à la
|
||
> génération incrémentale : il attend des entrées que ce pipeline ne fournit pas.
|
||
> `OnnxTranslationService` l'exclut désormais explicitement (nom contenant
|
||
> `past`), mais autant ne pas le copier.
|
||
|
||
> ⚠️ **Un modèle Marian a DEUX vocabulaires** : `source.spm` (langue d'entrée) et
|
||
> `target.spm` (langue de sortie). Les livrer **tous les deux** est obligatoire —
|
||
> voir §2.4.
|
||
|
||
### 2.4 Étape C — construire le pack local
|
||
|
||
> Cette étape construit un pack **de test sur le poste**. Pour livrer un pack en
|
||
> **production** (dépôt sous `Langues__RootPath`, génération du manifeste,
|
||
> contrôles), la procédure dédiée est `LIVRAISON_MODELES_LANGUES.md` — l'
|
||
> arborescence et les règles de nommage y sont les mêmes.
|
||
|
||
Arborescence à créer, par exemple dans `C:\Omika\TestLangues\es` :
|
||
|
||
```
|
||
es/
|
||
├── versFrancais/ (es -> fr)
|
||
│ ├── encoder_model.onnx <- depuis .\export\es-fr\
|
||
│ ├── decoder_model.onnx <- depuis .\export\es-fr\
|
||
│ ├── source.spm <- depuis .\export\es-fr\source.spm (ESPAGNOL)
|
||
│ └── target.spm <- depuis .\export\es-fr\target.spm (FRANÇAIS)
|
||
└── depuisFrancais/ (fr -> es)
|
||
├── encoder_model.onnx <- depuis .\export\fr-es\
|
||
├── decoder_model.onnx <- depuis .\export\fr-es\
|
||
├── source.spm <- depuis .\export\fr-es\source.spm (FRANÇAIS)
|
||
└── target.spm <- depuis .\export\fr-es\target.spm (ESPAGNOL)
|
||
```
|
||
|
||
**Règles de nommage** (résolues automatiquement par le service, aucune
|
||
configuration nécessaire) :
|
||
|
||
| Fichier | Rôle | Repli si absent |
|
||
|---|---|---|
|
||
| `source.spm` | vocabulaire d'entrée | `vocab.spm`, puis premier `.spm` |
|
||
| `target.spm` | vocabulaire de sortie | `vocab.spm`, puis premier `.spm` |
|
||
| `vocab.spm` | vocabulaire **commun** aux deux langues (NLLB, mBART, M2M-100) | premier `.spm` |
|
||
| `encoder_model.onnx` / `encoder.onnx` / tout autre `.onnx` | modèle principal | — |
|
||
| `decoder_model.onnx` / `decoder.onnx` | décodeur séparé | mode « modèle unique » |
|
||
| `*_with_past*.onnx` | **ignoré** | — |
|
||
|
||
> **Modèle à vocabulaire partagé** (NLLB, mBART) : un seul `vocab.spm` suffit,
|
||
> il sert aux deux sens. **Modèle Marian/OPUS-MT** : `source.spm` + `target.spm`
|
||
> sont obligatoires. Les noms d'entrée du graphe (`input_ids` vs
|
||
> `decoder_input_ids`, `encoder_hidden_states` vs `memory`) sont eux aussi
|
||
> résolus automatiquement sur le modèle réellement chargé.
|
||
|
||
### 2.5 Étape D — valider sur le POSTE, sans téléphone
|
||
|
||
C'est le cœur du traitement du point 1 : **on ne débogue pas un modèle de 120 Mo
|
||
par déploiement d'APK.**
|
||
|
||
```powershell
|
||
# 1) Le vocabulaire est-il lisible, et le tokeniseur cohérent ?
|
||
dotnet run --project tools/Omika.LanguesProbe -- inspecter .\TestLangues\es\versFrancais\source.spm
|
||
|
||
# 2) Que produit exactement la tokenisation ? (à comparer à la référence, §3.3)
|
||
dotnet run --project tools/Omika.LanguesProbe -- encoder .\TestLangues\es\versFrancais\source.spm "Buenos días, ¿cómo está?"
|
||
|
||
# 3) La traduction complète, avec les temps de chargement et d'inférence
|
||
dotnet run --project tools/Omika.LanguesProbe -- traduire `
|
||
--dossier .\TestLangues\es\versFrancais --code es --sens versFrancais `
|
||
--texte "Sustitución de la pieza"
|
||
```
|
||
|
||
> **Pack familial** (modèle multilingue, §2.1.1 de
|
||
> `LIVRAISON_MODELES_LANGUES.md`) : pointer `--dossier` sur le dossier du
|
||
> **sens** (`langues/pt/versFrancais`). La commande lit les poids dans le
|
||
> `commun/` voisin et affiche la ligne `Jeton cible : >>fra<<` — si cette ligne
|
||
> manque, le pack produira la mauvaise langue sans aucune erreur.
|
||
|
||
**Ce qu'il faut regarder, dans cet ordre :**
|
||
|
||
1. `inspecter` — `ProfilNormalisation`, `RepliOctetDisponible`, et surtout les
|
||
**avertissements**. S'il annonce `precompiled_charsmap … NON appliquée`,
|
||
c'est attendu (§3.2) : notez-le, ne le corrigez pas encore.
|
||
2. `inspecter` — les **aller-retours** `texte → ids → texte`. Tous doivent être
|
||
`IDENTIQUE`. Un `DIFFERENT` sur du texte ordinaire est le symptôme d'un
|
||
découpage divergent : passez au §3.3 **avant** de chercher ailleurs.
|
||
3. `traduire` — la sortie doit être une phrase **française plausible**. Pas
|
||
parfaite : plausible. « Remplacement de la pièce » ✅. Une suite de mots
|
||
espagnols, du texte répété ou des caractères isolés ❌ → voir §3.4.
|
||
|
||
**Repères de performance à noter** (ils décideront de la faisabilité mobile) :
|
||
|
||
| Mesure | Attendu sur poste | Seuil d'alerte |
|
||
|---|---|---|
|
||
| Chargement du modèle | < 2 s | > 5 s |
|
||
| Inférence d'une phrase courte | < 1 s | > 3 s |
|
||
| Aller-retour tokeniseur seul | < 5 ms | > 50 ms |
|
||
|
||
### 2.6 Étape E — valider sur Android
|
||
|
||
```powershell
|
||
dotnet publish src/Omika.App.Android/Omika.App.Android.csproj -c Release -r android-arm64
|
||
```
|
||
|
||
1. Copier le dossier `es\` complet dans le stockage de l'appareil, sous
|
||
`<données app>/Omika/langues/es/` — ou, plus réaliste, publier le pack sur le
|
||
service Langues et le télécharger depuis **Paramètres → Langue secondaire**
|
||
(c'est aussi le test du §3 de `TRADUCTION_HORS_LIGNE_MOBILE.md`).
|
||
2. **Avant de tester la traduction**, vérifier le poids : un modèle Marian fait
|
||
~300 Mo pour les deux sens. C'est la décision de livrable la plus lourde de
|
||
tout le lot.
|
||
3. Dicter en espagnol dans une note interne → le champ doit recevoir du français.
|
||
4. Ouvrir le panneau de dictée → la bascule `⇄` doit redémarrer l'écoute en
|
||
espagnol.
|
||
5. Sur une note existante, appuyer sur « ⇄ Traduire » → affichage espagnol, et
|
||
**rien** ne doit apparaître dans l'Outbox (vérifier la page Synchronisation).
|
||
|
||
### 2.7 Critères go / no-go
|
||
|
||
Le moteur est **validé** si et seulement si :
|
||
|
||
- [ ] `inspecter` : aucun aller-retour `DIFFERENT` sur du texte ordinaire ;
|
||
- [ ] `traduire` : phrases françaises plausibles sur 10 phrases variées
|
||
(avec accents, chiffres, ponctuation, une phrase longue) ;
|
||
- [ ] inférence < 3 s par phrase sur l'appareil Android cible ;
|
||
- [ ] poids de l'APK mesuré et accepté ;
|
||
- [ ] la dictée traduite insère du français, et **aucune** donnée traduite
|
||
n'apparaît dans l'Outbox.
|
||
|
||
Sinon → §3.4.
|
||
|
||
### 2.8 Rollback
|
||
|
||
Retirer les 3 modifications du §2.2 (le symbole, le `PackageReference`, la
|
||
ligne d'`AppServices`). L'application repasse à
|
||
`UnavailableOnnxInferenceSessionFactory` : la traduction est annoncée
|
||
indisponible, **rien d'autre ne change**. Aucune migration de données, aucun
|
||
état à nettoyer — c'est précisément pourquoi le moteur est isolé derrière une
|
||
fabrique.
|
||
|
||
---
|
||
|
||
## 3. Point 2 — le tokeniseur
|
||
|
||
### 3.1 Ce qui a été corrigé (et pourquoi c'était faux)
|
||
|
||
Quatre défauts réels ont été corrigés. Aucun n'était visible sur les modèles les
|
||
plus courants, ce qui les rendait d'autant plus dangereux :
|
||
|
||
| Défaut | Conséquence avant correction | État |
|
||
|---|---|---|
|
||
| `normalizer_spec` ignoré : préfixe `▁` ajouté d'office | Un modèle formé avec `add_dummy_prefix=false` (fréquent sur les modèles récents) était découpé — donc traduit — **différemment** de la référence | ✅ lu et honoré |
|
||
| Espaces multiples / de bord jamais réduits | `« Bonjour le monde »` produisait des marqueurs `▁` parasites absents de la référence | ✅ `remove_extra_whitespaces` honoré (espace, tabulation, `\n`, `\r`, `\v`, `\f`) |
|
||
| `escape_whitespaces` supposé vrai | Un modèle à espaces littéraux était découpé de travers | ✅ honoré |
|
||
| **Repli octet absent** | Sur un modèle multilingue, un caractère hors vocabulaire devenait `<unk>` : les accents et les alphabets non latins étaient **purement perdus** | ✅ implémenté (encodage **et** décodage) |
|
||
| **Un seul vocabulaire par pack** | **Le défaut le plus grave** : un modèle Marian a un vocabulaire par langue. Décoder la sortie avec le vocabulaire d'entrée produit des identifiants interprétés dans le mauvais référentiel → du charabia | ✅ `source.spm` + `target.spm` |
|
||
|
||
Deux points qui **n'étaient pas** des défauts, vérifiés :
|
||
|
||
- la pénalité du jeton inconnu (`min_score − 10`) est bien celle de la référence
|
||
(`kUnkPenalty = 10.0`) ;
|
||
- un `<unk>` par **point de code** (et non par unité UTF-16) est correct : une
|
||
paire de substituts ne doit jamais être coupée en deux.
|
||
|
||
### 3.2 Ce qui reste approximé — et l'impact attendu
|
||
|
||
**`precompiled_charsmap` n'est pas appliqué.** C'est la table de normalisation
|
||
Unicode compilée du modèle (structure de trie à double tableau, format propre à
|
||
SentencePiece). La réimplémenter représenterait plusieurs centaines de lignes
|
||
pour un gain **nul sur la majorité des textes**.
|
||
|
||
Impact réel, à connaître :
|
||
|
||
- **Aucun** sur du texte déjà normalisé en NFC (ce que produit tout clavier
|
||
Android/iOS, et tout ce que l'API renvoie) ;
|
||
- **Quelques cas** sur les formes de compatibilité (`fi` ligature, chiffres
|
||
pleine largeur `１２３`, exposants `²`) et sur les langues dont l'écriture
|
||
demande un repli de casse ou une normalisation de présentation.
|
||
|
||
Le tokeniseur **le signale** désormais lui-même (`Avertissements`,
|
||
`ProfilNormalisation`). C'est visible dans `inspecter` et dans les diagnostics.
|
||
|
||
### 3.3 Mesurer la divergence (avant de corriger quoi que ce soit)
|
||
|
||
La référence est la bibliothèque Python `sentencepiece`, l'implémentation
|
||
d'origine de Google.
|
||
|
||
```powershell
|
||
pip install sentencepiece
|
||
|
||
# Génère une fixture de référence par modèle trouvé (récursif)
|
||
.\scripts\Generer-Fixtures-SentencePiece.ps1 -DossierModeles .\TestLangues
|
||
```
|
||
|
||
La fixture contient, pour chaque cas d'essai, les identifiants **de référence**
|
||
et le décodage **de référence**. Le test `SentencePieceFixturesTests` les
|
||
compare ensuite au tokeniseur Omika :
|
||
|
||
```powershell
|
||
dotnet test tests/Omika.Tests --filter SentencePieceFixtures
|
||
```
|
||
|
||
- **Dossier de fixtures absent → le test passe** (sinon toute compilation sans
|
||
modèle serait rouge). Les cas d'essai couvrent accents français, accents et
|
||
`¿¡` espagnols, espaces de bord et doubles, chaîne vide, espaces seuls,
|
||
chiffres et ponctuation, casse mixte, phrase longue, et un alphabet non latin.
|
||
- **Un échec nomme le cas fautif**, le premier index divergent, les deux
|
||
identifiants et le texte de la pièce : de quoi corriger sans deviner.
|
||
- Les `.spm` ne sont **pas versionnés** (poids + licences) — voir
|
||
`tests/fixtures/sentencepiece/LISEZMOI.md`.
|
||
|
||
### 3.4 Arbre de décision selon ce que révèle la mesure
|
||
|
||
| Symptôme mesuré | Cause la plus probable | Action |
|
||
|---|---|---|
|
||
| Aller-retour `DIFFERENT` sur du texte **ordinaire** (accents, ponctuation) | Divergence de découpage | Comparer avec `encoder` : si les identifiants diffèrent dès le **premier**, c'est la normalisation ; s'ils divergent plus loin, c'est le Viterbi |
|
||
| Divergence **uniquement** sur les cas de compatibilité (`fi`, `１２３`) | `precompiled_charsmap` non appliqué | **Accepter** et documenter : impact réel nul sur une dictée |
|
||
| Traduction = suite de mots de la langue source, ou texte répété | Vocabulaire cible faux (ou absent) | Vérifier que `target.spm` est bien livré dans le sens concerné (§2.4) |
|
||
| Traduction = `<unk>`, `▁`, ou caractères isolés | Mauvais vocabulaire, ou modèle non aligné sur le vocabulaire | Vérifier que `source.spm`/`target.spm` viennent bien du **même** modèle que les `.onnx` |
|
||
| Erreur « n'expose aucune des entrées attendues (…) » | Noms d'entrée atypiques | Le message énumère les entrées réelles du modèle : renseigner `OnnxTranslationOptions` en conséquence |
|
||
| Sortie entière ignorée / erreur de type | ONNX Runtime refuse un type inattendu | Corrigé : le type est testé **avant** `AsTensor<T>` (qui lève au lieu de retourner `null`) |
|
||
| Divergence **après** avoir tout vérifié | Vraie limite de l'implémentation | Ouvrir un ticket avec la fixture en échec **jointe** : elle contient tout ce qu'il faut pour reproduire |
|
||
|
||
> **Ce qu'il ne faut PAS faire** : assouplir la fixture attendue pour faire
|
||
> passer le test. Une fixture modifiée est une divergence rendue invisible.
|
||
|
||
---
|
||
|
||
## 4. Hors périmètre (à ne pas confondre)
|
||
|
||
- **Qualité de traduction** : ce document valide que le *pipeline* fonctionne,
|
||
pas que le modèle traduit bien. Un modèle médiocre restera médiocre — c'est un
|
||
choix de modèle, pas un défaut de code.
|
||
- **Poids du livrable mobile** : l'activation du moteur ONNX Runtime ajoute la
|
||
bibliothèque native par architecture, et les modèles pèsent 80 à 300 Mo par
|
||
langue. C'est une décision produit, pas technique.
|
||
- **Reprise/streaming** du téléchargement : non implémenté (le re-téléchargement
|
||
repart de zéro par fichier, mais les fichiers déjà conformes sont ignorés).
|
||
- **Beam search** : le décodage est glouton (compromis de latence assumé).
|
||
|
||
---
|
||
|
||
## 5. Récapitulatif
|
||
|
||
| # | Action | Qui | Où |
|
||
|---|---|---|---|
|
||
| 1 | Activer le symbole + le paquet + la fabrique (§2.2) | Dev (NuGet) | 3 fichiers |
|
||
| 2 | Exporter une paire FR⇄ES en ONNX (§2.3) | Dev | poste |
|
||
| 3 | Construire le pack `source.spm` + `target.spm` (§2.4) | Dev | disque |
|
||
| 4 | `inspecter` / `encoder` / `traduire` (§2.5) | Dev | poste — **pas de téléphone** |
|
||
| 5 | Générer les fixtures et lancer le test (§3.3) | Dev | `scripts\` + `dotnet test` |
|
||
| 6 | Trancher avec l'arbre de décision (§3.4) | Dev | — |
|
||
| 7 | Publier sur Android et mesurer poids + latence (§2.6) | Dev | appareil |
|
||
| 8 | Décider go / no-go (§2.7) | Produit + Dev | — |
|
||
|
||
**Si une seule chose doit être retenue** : les étapes 4 et 5 se font **sur le
|
||
poste, en quelques minutes**. Tout le reste — déploiement d'APK, téléchargement
|
||
de 300 Mo sur un téléphone, instrumentation à distance — est un détour.
|