perf(embeddings): skip unused BERT suffixes with exact token guards

[cdeust]

Symptôme

W3-3 : le modèle tokenise des suffixes qu’il n’utilisera pas. Un simple cap de caractères perd des tokens sur les espaces, contrôles Unicode ou mots longs ; le précédent audit de cette PR avait réfuté ce cap sans livrer d’optimisation.

Cause racine

WordPiece traite les mots complets avant troncature. La limite de256tokens ne définit donc pas une limite universelle de caractères : a + 9998 espaces + b utilise toute la chaîne pour seulement deux tokens ordinaires.

Changement

Ajouter une garde au chemin scalaire du modèle BERT. Elle conserve l’entrée entière sauf si un préfixe terminé à une frontière de mot remplit déjà le budget réel du modèle. Normalizer, pre-tokenizer, WordPiece, template simple, troncature à droite et absence de prompt sont vérifiés au chargement ; les tokens ajoutés normalisés ou contenant des espaces excluent l’optimisation. Les erreurs du tokenizer restent visibles.

Le point de sondage1450 est tiré des observations versionnées ; il choisit où essayer, jamais une borne universelle de sûreté. La recherche de frontière utilise str.find ; la garde de coût évite une deuxième tokenisation des préfixes presque vides. Les textes stockés, clés du LRU, vecteurs normalisés et chemins batch restent complets. Les batches ont leur propre problème d’équivalence numérique et ne sont pas modifiés ici.

Preuve

Tête 1b5490898acbb7ccce2cc9941c8325242c0a829e. 16/16 vecteurs bit-à-bit identiques, avec IDs, masques et type IDs du vrai modèle également identiques. Python3.12.11, MiniLM CPU, snapshot 1110a243fdf4706b3f48f1d95db1a4f5529b4d41, tokenizer SHA256 be50c3628f2bf5bb5e3a7f17b1f74611b2561a3a27eeab05e5aa30f411572037. Mesure du vrai EmbeddingEngine.encode, garde désactivée puis activée sur le même modèle : cache vidé à chaque appel, modèle déjà chargé, quatre paires alternées et première paire exclue, sans tolérance numérique. Hash de l’entrée complète et normalisation inclus dans les temps.

Fixture 10 000 caractères	Caractères encodés	Wall avant → après (ms)	CPU avant → après (ms)	Vecteur exact
internal_spaces	10000	3.662 → 3.658	3.722 → 3.738	oui
leading_spaces	10000	3.565 → 3.469	3.611 → 3.529	oui
internal_tabs	10000	3.385 → 3.371	3.449 → 3.422	oui
internal_nbsp	10000	3.798 → 3.853	3.849 → 3.915	oui
null_controls	10000	2.813 → 2.798	2.873 → 2.852	oui
format_controls	10000	3.646 → 3.650	3.709 → 3.702	oui
replacement_chars	10000	3.693 → 3.604	3.759 → 3.672	oui
combining_marks	10000	3.631 → 3.616	3.680 → 3.663	oui
composed_accents	1451	12.099 → 10.309	20.865 → 18.238	oui
decomposed_accents	1454	11.771 → 10.195	20.573 → 18.098	oui
joined_emoji	1453	13.581 → 11.897	21.695 → 18.882	oui
long_word	10000	3.841 → 3.733	3.944 → 3.796	oui
word_limit_boundary	10000	3.513 → 3.442	3.571 → 3.499	oui
chinese_punctuation	1456	15.333 → 11.391	24.443 → 20.292	oui
added_special_tokens	1451	11.879 → 10.079	20.733 → 18.005	oui
ordinary_prose	1451	11.381 → 10.134	20.168 → 18.013	oui

Sur la prose, la médiane wall passe de11,381 à10,134ms et la médiane CPU de20,168 à18,013ms. Les six cas éligibles sont raccourcis ; les autres restent entiers. Le tableau publie aussi leurs fluctuations/surcoûts : aucun gain uniforme ni extrapolation à un mélange de production n’est revendiqué.

.venv/bin/python /private/tmp/cortex-green-w3-3-guarded-v4-validation.py

Le superviseur figé exécute d’abord /private/tmp/cortex-green-w3-3-guarded-runtime-model-v4.py sous l’environnement isolé, puis bash /private/tmp/cortex-green-local-gates.sh w3-3-guarded-v4 tests_py/infrastructure. Gates dans l’ordre : uv verrouillé, Ruff/format, craftsmanship, Pyright sans diagnostic, couche (767 passed, 97 skipped, 1 warning, 3 subtests passed in 30.00s), suite complète (7807 passed, 229 skipped, 3 warnings, 433 subtests passed in 163.47s (0:02:43)). L’audit explicite sur le tokenizer en cache passe aussi22tests. Aucun cache de modèle sous/tmp ; état Cortex isolé.

Preuves : /private/tmp/cortex-green-w3-3-guarded-v4-validation.json, /private/tmp/cortex-green-w3-3-guarded-runtime-model-v4.json (tous les échantillons, hash sources, uptime et df avant/après), /private/tmp/cortex-green-w3-3-guarded-v4-gates.log. Le point de sondage et les mesures de recherche de frontière sont versionnés dans docs/provenance/green-w3-3-prefix-observations.json ; justification dans docs/provenance/green-w3-3-guarded-prefix.md.

La reproduction qualité complète réunissant les corrections W3/W4 reste à produire ; ces tests et ces fixtures ne constituent pas un passage des floors. Les floors échouaient déjà dans la référence main mesurée séparément. Nouvelle CI distante à vérifier sur cette tête.

before
20:03  up 3 days, 22:29, 9 users, load averages: 2.99 3.26 3.30
Filesystem        Size    Used   Avail Capacity iused ifree %iused  Mounted on
/dev/disk3s1s1   460Gi    12Gi    37Gi    25%    459k  387M    0%   /

after
20:03  up 3 days, 22:29, 9 users, load averages: 2.76 3.20 3.28
Filesystem        Size    Used   Avail Capacity iused ifree %iused  Mounted on
/dev/disk3s1s1   460Gi    12Gi    37Gi    25%    459k  387M    0%   /

Conformité

Une branche et une PR W3-3, aucune fusion. Pas de cap brut arbitraire, pas de perte de texte, pas de nouveaux seuils de qualité, ni changement du modèle ou de normalisation. Le noyau scalaire reçoit les mêmes tenseurs. Module de garde sous300lignes, méthodes sous40 ; embedding_engine reste à300lignes, état de la garde détenu par le cycle de vie du modèle. Baseline craftsmanship non élargie. Un seul travail lourd local à la fois ; aucune base de production.

Les conditions de préfixe suivent les sources primaires BERT normalizer, BERT pre-tokenizer et WordPiece, vérifiées sur la version0.22.2 verrouillée.

Candidats issues

L’équivalence numérique des vrais batches W3-2/W3-4 et l’écart aux floors sous mélange de provenances restent des problèmes distincts. Aucun ticket créé automatiquement. Les mesures synthétiques ci-dessus ne définissent pas la fréquence des textes éligibles en production.

Runbook

Pas de migration ni de configuration de production. Les configurations de tokenizer non vérifiées continuent leur encodage complet ; aucune installation supplémentaire. Les tests avec modèle restent explicitement offline et utilisent le cache durable.