"""Pipeline spaCy pour UNE locale — l'équivalent Python de ce que `node-nlp`'s `NlpManager` faisait pour cette locale dans `TechStepClassifierService` (`apps/api/src/lib/recipe-matching/tech-step-matcher.ts`) : NER par entités enum (ici un `PhraseMatcher`) + classification d'intention (ici un `textcat`), les deux entraînés à partir du corpus possédé par ce service lui-même (`training_data.TECH_STEP_TRAINING_DATA` — plus poussé par `apps/api` via HTTP, voir `pipeline_registry.py`). Le modèle de base spaCy (tokenizer + vecteurs + le composant `diacritics_normalizer` défini plus bas) est chargé une seule fois (`preload()`, appelé au démarrage du process — voir `main.py` — pas paresseusement au premier `train()`, pour que `GET /health` ne devienne `200` qu'une fois ce coût payé) puis réutilisé à chaque `train()` : seul le `textcat` (retiré puis rajouté à neuf) et le `PhraseMatcher` (remplacé) sont reconstruits à chaque appel, jamais le tokenizer/les vecteurs. Rien n'est jamais persisté sur disque — `training_data.py` reste l'unique source de vérité, reconstruite en mémoire depuis zéro à chaque démarrage du process. """ from __future__ import annotations import logging import random from dataclasses import dataclass, field import spacy from spacy.language import Language from spacy.matcher import PhraseMatcher from spacy.tokens import Doc, Span from spacy.training import Example from spacy.util import filter_spans, fix_random_seed, minibatch from . import utensil_vocabulary from .text_normalization import normalize_text logger = logging.getLogger(__name__) # Modèle spaCy de base par locale — voir pyproject.toml pour la version # pinnée exacte. `md` (pas `sm`) : conserve les vecteurs de mots, inutilisés # par le pipeline v1 (textcat bag-of-words) mais retenus pour l'ambition # future de similarité sémantique (voir le README de ce service). SUPPORTED_LOCALES = { "fr": "fr_core_news_md", "en": "en_core_web_md", } # Composants du modèle de base non utilisés par ce pipeline (on ne s'appuie # ni sur le NER générique de spaCy, ni sur l'analyse syntaxique/morphologique # — seuls le tokenizer et les vecteurs de mots restent nécessaires) : les # exclure au chargement évite le coût mémoire/CPU de composants qui ne # tourneraient jamais. _EXCLUDED_COMPONENTS = ["parser", "ner", "tagger", "morphologizer", "attribute_ruler", "lemmatizer"] _TEXTCAT_PIPE_NAME = "textcat" # Nombre d'itérations d'entraînement du textcat et taille de minibatch — # calibrés empiriquement contre le corpus réel (`training_data.py`), pas # seulement contre les petits corpus jouets des tests de ce fichier. Trop # peu d'itérations laisse des clauses correctement classifiées (bon argmax) # mais avec une confiance dérisoire — bien en dessous de tout seuil # raisonnable pour `CONFIDENCE_THRESHOLD` (`tech-step-matcher.ts`). # # Quatre passes de calibration successives, toutes mesurées contre le # corpus réel (74 techniques) : # 1. `150` itérations (calibré pour le corpus original, ~26 techniques) ne # passe plus à l'échelle une fois élargi : `150` sur 74 classes # dépassait 17 minutes pour une seule locale, constaté en CI. # 2. `40` itérations, `examples` limité aux `utterances` (pas les # `synonyms`) : ~200s/locale, mais confiance faible sur les clauses # ancrées sans paraphrase entraînée (`simmer`/`cook`/`bake` ~0.25-0.34). # 3. **Configuration actuelle** : les `synonyms` de chaque technique sont # désormais aussi des exemples d'entraînement du textcat (voir plus bas # dans `train()`) — un signal "mot-clé isolé -> sa propre technique" # qui manquait complètement avant. À `_TRAINING_ITERATIONS` inchangé # (40), le nombre d'exemples par époque grimpe de ~286 à ~749 et le # temps d'entraînement suit (~535s/locale) ; réduire à `25` retrouve un # temps proche de l'étape 2 (~336s/locale, ~670s pour fr+en combinés) # tout en gardant l'essentiel du gain de confiance apporté par les # synonymes : melt ~0.89, preheat ~0.77, compote ~0.78, julienne ~0.76, # zest ~0.66, bake ~0.62, cook ~0.38, simmer ~0.31 — le plus faible # observé, mais désormais nettement au-dessus du seuil de confiance # (contre ~0.25, sous le seuil d'alors, à l'étape 2). Bruit # hors-vocabulaire toujours négligeable (anglais via le classifieur # français : `~0.02`). Une vraie repasse de # `calibrate-tech-step-threshold.ts` contre `TECH_STEP_EVAL_DATASET` # reste nécessaire pour confirmer/affiner ces valeurs (voir # `CONFIDENCE_THRESHOLD`'s propre commentaire, `tech-step-matcher.ts`) # — ce qui précède est une mesure manuelle ponctuelle, pas un # remplacement de cette calibration. # 4. Le corpus a ensuite été rééquilibré à 20 `utterances` minimum par # technique et par locale (contre 3-7 avant — chaque technique en a # désormais *le même nombre*, demande explicite pour que le textcat ne # voie pas certaines classes avec 3x moins de signal que d'autres). Les # exemples par époque grimpent d'environ 749 à ~2180/locale (+191%) — à # `_TRAINING_ITERATIONS` inchangé (25), ça aurait fait grimper le temps # d'entraînement dans les mêmes proportions (~336s -> ~980s/locale, # ~33 minutes pour fr+en). Réduit à `10` pour retrouver un temps par # époque comparable à l'étape 3 malgré ~3x plus d'exemples par époque — # un corpus plus large et mieux équilibré par classe a aussi besoin de # structurellement moins d'époques pour bien converger (chaque époque # voit déjà beaucoup plus de signal par classe), donc ce n'est pas un # simple compromis qualité/temps à somme nulle comme les étapes # précédentes. Mesuré à `10` : ~355s (fr, 1943 exemples) / ~332s (en, # 1835 exemples), ~687s pour fr+en combinés — quasi identique à l'étape # 3 malgré ~2.6x plus d'exemples par époque. Les scores bruts semblaient # bons sur un petit échantillon de phrases suivies à la main, **mais** # `test/recipe-matching/tech-step-eval.test.ts` (F1 agrégé contre # `TECH_STEP_EVAL_DATASET`, la vraie jauge de qualité de ce pipeline, pas # un spot-check manuel) a mesuré `0.7999...` — sous le seuil `0.8` — une # fois passé en CI avec une vraie base Postgres : `10` itérations ne # suffisaient pas à absorber ~2.6x plus d'exemples par époque, contre le # pari initial que "un corpus plus grand converge en moins d'époques # relatives" — faux à ce niveau de réduction. Remonté à `20` : ~699s # pour `fr` seule (mesuré), donc largement au-dessus des ~900s de budget # pour les deux locales combinées une fois `en` incluse — `start_period` # (`docker-compose.yml`) et le `timeout` d'attente `/health` # (`.github/workflows/ci.yml`) relevés à `1800s` en conséquence. # Techniques auparavant en échec (précision nulle sur le jeu d'éval) à # `10` — `sweat`, `julienne`, `caramelize` — retestées manuellement à # `20` avec une confiance nettement rétablie (`sweat` ~0.99, par # exemple). À confirmer/affiner par une vraie repasse de # `calibrate-tech-step-threshold.ts` comme aux étapes précédentes — ce # qui précède reste une mesure ponctuelle plus la gate F1 de CI, pas un # remplacement de cette calibration. _TRAINING_ITERATIONS = 20 _TRAINING_BATCH_SIZE = 16 # Arrêt anticipé : `_TRAINING_ITERATIONS` reste le plafond (le pire cas ne # change pas), un corpus/locale qui converge plus vite n'a pas à payer les # itérations restantes pour rien. Une époque compte comme "sans progrès" # quand sa perte totale ne descend pas d'au moins `_EARLY_STOPPING_MIN_DELTA` # sous la meilleure perte vue jusqu'ici ; `_EARLY_STOPPING_PATIENCE` époques # consécutives sans progrès arrêtent l'entraînement. # # Mesuré contre le corpus réel (74 techniques, budget de 40 itérations, # avant le passage à 25) : ne s'est jamais déclenché — la perte continuait # de baisser significativement sur toute la plage (cohérent avec la # confiance qui grimpait encore nettement entre 15 et 40 itérations, voir # le commentaire de `_TRAINING_ITERATIONS`). Ce n'est donc pas un gain de # temps aujourd'hui, mais un filet de sécurité peu coûteux pour la suite : si # `_TRAINING_ITERATIONS` est un jour augmenté pour une meilleure confiance, # ceci évite de payer des itérations supplémentaires une fois la # convergence réellement atteinte, sans qu'il faille retrouver le bon # plafond à la main à chaque changement du corpus. _EARLY_STOPPING_PATIENCE = 3 _EARLY_STOPPING_MIN_DELTA = 0.001 # Abaissé de `0.2` avec le reste de cette recalibration — `0.1` régularise # encore contre la petite taille du corpus par technique tout en laissant # plus de signal passer à chaque pas, ce qui a mesurablement aidé la # confiance finale sans signe de sur-ajustement (le bruit hors-vocabulaire # reste aussi bas qu'avant, voir ci-dessus). _TRAINING_DROPOUT = 0.1 # Seed fixe — un warm-up reproductible d'un redémarrage à l'autre (même # corpus en entrée) est préférable à un score qui varie légèrement à chaque # déploiement pour la même donnée, en particulier pendant la calibration du # seuil de confiance côté apps/api. _TRAINING_SEED = 0 class _DiacriticsNormalizer: """Composant de pipeline réécrivant `token.norm_` avec `normalize_text()` (le port Python de `normalizeText()` côté `apps/api`) pour chaque token. Point clé : ce composant tourne aussi bien sur les `Doc` construits pour les *patterns* du `PhraseMatcher` (voir `LocalePipeline.train`) que sur le *texte cible* passé à `process()` — les deux passent donc par exactement la même normalisation, ce qui garantit qu'un synonyme comme "mijoter" matche indifféremment "MIJOTER"/"mijoté"/"Mijotée" dans le texte, reproduisant le comportement `ner.threshold: 1` (exact après normalisation, sans tolérance floue Levenshtein) de l'ancien `NlpManager`. Indépendant des `entries` entraînées — ajouté une seule fois par `preload()`, jamais retiré/rajouté par `train()`. Opère token par token, sur du texte déjà tokenisé — `normalize_text()` ne fait que réécrire la forme d'un token existant (minuscule, sans diacritique), jamais fusionner/scinder des tokens : les patterns (`nlp.make_doc(synonym)` + ce composant appliqué à la main, voir `LocalePipeline.train`) et le texte cible (`nlp(text)`, pipeline complet) passent donc toujours par le *même* découpage en tokens que le tokenizer du modèle de base leur donne, avant que ce composant n'y touche — pas de risque de désalignement entre les deux. """ def __call__(self, doc: Doc) -> Doc: for token in doc: token.norm_ = normalize_text(token.text) return doc @Language.factory("diacritics_normalizer") def _create_diacritics_normalizer(nlp: Language, name: str) -> _DiacriticsNormalizer: return _DiacriticsNormalizer() @dataclass class TrainEntry: """Une technique à entraîner pour une locale — construit par `PipelineRegistry.initialize()` depuis `training_data.entries_for_locale`.""" uid: str synonyms: list[str] = field(default_factory=list) utterances: list[str] = field(default_factory=list) @dataclass class Entity: """Une mention candidate trouvée par un `PhraseMatcher` — offsets caractère `[start, end)`, miroir de `EntityPayload` (`schemas.py`). `kind` distingue de quel `PhraseMatcher` la mention vient (`"technique"` — `self._matcher`, entraîné depuis `training_data.py` — ou `"utensil"` — `self._utensil_matcher`, statique, voir `utensil_vocabulary.py`) : `apps/api`'s `tech-step-matcher.ts` a besoin de savoir laquelle des deux résoudre (`TechStep.key` vs `Utensil.key`).""" uid: str start: int end: int kind: str = "technique" @dataclass class ProcessResult: """Résultat complet d'un `process()` — miroir de `ProcessResponse` (`schemas.py`).""" entities: list[Entity] intent: str | None score: float class UnsupportedLocaleError(ValueError): """`locale` ne correspond à aucun modèle spaCy connu (voir `SUPPORTED_LOCALES`) — distinct d'une locale simplement "pas encore entraînée" (`LocalePipeline.is_trained is False`), qui n'est pas une erreur (voir `process()`).""" class LocalePipeline: """Pipeline spaCy (NER par phrases + textcat) pour une locale donnée. Un `PipelineRegistry` (voir `pipeline_registry.py`) en détient une instance par locale supportée. """ def __init__(self, locale: str) -> None: if locale not in SUPPORTED_LOCALES: raise UnsupportedLocaleError(f"Unsupported locale: {locale!r}") self._locale = locale self._model_name = SUPPORTED_LOCALES[locale] # `None` tant que `preload()` n'a pas tourné. self._base_nlp: Language | None = None # `None` tant qu'aucun `train()` n'a réussi — `process()` traite ça # comme "rien à trouver" plutôt qu'une erreur, exactement le # comportement testé côté `apps/api` pour "une locale jamais # entraînée". self._matcher: PhraseMatcher | None = None # Construit une seule fois par `preload()`, jamais par `train()` — # contrairement à `self._matcher`, ce vocabulaire est statique # (`utensil_vocabulary.py`), il n'a pas de contrepartie "corpus # poussé par un appelant" à reconstruire. self._utensil_matcher: PhraseMatcher | None = None self._trained = False @property def is_trained(self) -> bool: return self._trained def preload(self) -> None: """Charge le modèle spaCy de base (tokenizer + vecteurs), le composant `diacritics_normalizer`, et construit le `PhraseMatcher` d'ustensiles — idempotent, sans effet si déjà chargé. Appelé au démarrage du process pour les deux locales connues (voir `main.py`), pas paresseusement au premier `train()`. Le matcher d'ustensiles est construit ici, pas dans `train()` : contrairement au `PhraseMatcher` de techniques (reconstruit à chaque `train()` depuis les `entries` reçues), le vocabulaire d'ustensiles est statique (`utensil_vocabulary.py`) — rien ne le fait jamais varier d'un appel à l'autre, donc rien ne justifie de payer son coût de construction plus d'une fois par démarrage. """ if self._base_nlp is not None: return nlp = spacy.load(self._model_name, exclude=_EXCLUDED_COMPONENTS) nlp.add_pipe("diacritics_normalizer", first=True) self._base_nlp = nlp diacritics_normalizer = nlp.get_pipe("diacritics_normalizer") utensil_matcher = PhraseMatcher(nlp.vocab, attr="NORM") for uid, synonyms in utensil_vocabulary.synonyms_for_locale(self._locale).items(): if not synonyms: continue patterns = [diacritics_normalizer(nlp.make_doc(synonym)) for synonym in synonyms] utensil_matcher.add(uid, patterns) self._utensil_matcher = utensil_matcher def train(self, entries: list[TrainEntry]) -> tuple[int, int, int]: """Reconstruit le `textcat` et le `PhraseMatcher` de ce pipeline à partir de `entries` (le tokenizer/les vecteurs restent ceux chargés par `preload()`). Retourne `(label_count, example_count, synonym_count)` pour la journalisation (`pipeline_registry.py`) — `example_count` est le nombre réel d'exemples donnés au `textcat` (`utterances` *et* `synonyms` combinés, voir plus bas), pas seulement `entry.utterances`. `entries` vide retombe à `is_trained == False` plutôt que de lever — un appelant qui n'a rien à entraîner pour cette locale obtient le même comportement que "jamais entraîné", pas une erreur 500. """ self.preload() assert self._base_nlp is not None # garanti par preload() ci-dessus if _TEXTCAT_PIPE_NAME in self._base_nlp.pipe_names: self._base_nlp.remove_pipe(_TEXTCAT_PIPE_NAME) if not entries: self._matcher = None self._trained = False return (0, 0, 0) nlp = self._base_nlp # `nlp.make_doc()` ne fait tourner *que* le tokenizer, pas les # composants du pipeline — le `diacritics_normalizer` ajouté par # `preload()` ne tournerait donc jamais sur les `Doc` de patterns # s'ils n'étaient construits qu'avec `make_doc()`, alors que # `process()` appelle `nlp(text)` (le pipeline complet) sur le texte # cible. Sans ce correctif, un synonyme accentué comme "préchauffer" # n'aurait jamais matché "PRÉCHAUFFER"/"Préchauffer" : trouvé en # calibrant contre les cas exacts de `tech-step-matcher.test.ts` # (fr, la locale la plus concernée par les accents) — un synonyme # sans diacritique comme "faire fondre" masquait le bug en semblant # fonctionner par coïncidence. Appliquer explicitement le même # composant aux deux côtés garantit qu'ils passent par la même # normalisation. diacritics_normalizer = nlp.get_pipe("diacritics_normalizer") matcher = PhraseMatcher(nlp.vocab, attr="NORM") synonym_count = 0 for entry in entries: if not entry.synonyms: continue patterns = [diacritics_normalizer(nlp.make_doc(synonym)) for synonym in entry.synonyms] matcher.add(entry.uid, patterns) synonym_count += len(entry.synonyms) # `textcat` (exclusive_classes) exige au moins deux labels (voir # spaCy's error E867) — jamais un problème avec le vrai corpus # (`TECH_STEP_TRAINING_DATA` a ~74 techniques), mais un `entries` à # un seul élément resterait structurellement valide pour le NER # seul : ne pas planter, juste ne pas construire de textcat du tout # (`process()` retombe alors sur `intent: null` via son garde # `if not cats`, exactement comme "rien à classifier"). Journalisé # explicitement — sans ça, "pourquoi cette locale ne classifie # jamais rien" ne serait visible qu'en déduisant `labelCount < 2` # de la ligne "tech-step NLP pipeline trained" (`pipeline_registry.py`). examples: list[Example] = [] if len(entries) < 2: logger.warning( "tech-step NLP textcat skipped: fewer than 2 labels, intent classification disabled for this locale", extra={"locale": self._locale, "labelCount": len(entries)}, ) else: textcat = nlp.add_pipe( _TEXTCAT_PIPE_NAME, config={ "model": { "@architectures": "spacy.TextCatBOW.v3", "exclusive_classes": True, "ngram_size": 1, "no_output_layer": False, }, }, ) for entry in entries: textcat.add_label(entry.uid) for entry in entries: cats = {other.uid: 0.0 for other in entries} cats[entry.uid] = 1.0 # `synonyms` (déjà utilisés pour le `PhraseMatcher` ci-dessus) # sont aussi de bonnes phrases d'entraînement pour le # `textcat` — un texte réduit au mot-clé lui-même ("fondre", # "faire fondre") est le cas le plus net qui soit pour sa # propre technique, et n'était auparavant vu par le textcat # que noyé dans le contexte plus riche des `utterances`. for text in (*entry.synonyms, *entry.utterances): doc = nlp.make_doc(text) examples.append(Example.from_dict(doc, {"cats": cats})) # Graine le RNG Python *et* celui de numpy/thinc sous-jacent à # `nlp.update()` (initialisation des poids, masque de dropout) — # `random.Random(_TRAINING_SEED)` ci-dessous ne couvre que l'ordre # de mélange des exemples choisi par ce module, pas ce que spaCy # fait en interne à chaque pas de gradient. fix_random_seed(_TRAINING_SEED) rng = random.Random(_TRAINING_SEED) if examples: optimizer = nlp.initialize(lambda: examples) best_loss = float("inf") epochs_without_improvement = 0 for iteration in range(_TRAINING_ITERATIONS): rng.shuffle(examples) losses: dict[str, float] = {} for batch in minibatch(examples, size=_TRAINING_BATCH_SIZE): nlp.update(batch, sgd=optimizer, drop=_TRAINING_DROPOUT, losses=losses) epoch_loss = losses.get(_TEXTCAT_PIPE_NAME, 0.0) # Arrêt anticipé — voir `_EARLY_STOPPING_PATIENCE`'s propre # commentaire. `_TRAINING_ITERATIONS` reste le plafond # (pire cas inchangé), ceci ne fait que raccourcir les # cas qui convergent plus vite. if epoch_loss < best_loss - _EARLY_STOPPING_MIN_DELTA: best_loss = epoch_loss epochs_without_improvement = 0 else: epochs_without_improvement += 1 if epochs_without_improvement >= _EARLY_STOPPING_PATIENCE: logger.info( "tech-step NLP textcat training stopped early", extra={ "locale": self._locale, "iteration": iteration + 1, "maxIterations": _TRAINING_ITERATIONS, "finalLoss": epoch_loss, }, ) break else: # Des `entries` avec des `uid` mais aucune `utterance` nulle # part (corpus incomplet) : le textcat a des labels mais rien # pour apprendre à les distinguer — toujours initialisé pour # rester un pipeline valide ; `process()` renverra alors un # score ~uniforme entre labels. Ce n'est pas ce module qui doit # juger la qualité du corpus reçu (voir `tech-step-eval-runner.ts` # côté apps/api pour ce rôle). nlp.initialize() self._matcher = matcher self._trained = True return (len(entries), len(examples), synonym_count) def process(self, text: str) -> ProcessResult: """Reproduit la forme de `NlpManager.process(locale, text)` : les entités candidates (NER) et le verdict du classifieur d'intention sur `text` tel quel — que ce soit la description complète ou une clause déjà découpée côté `apps/api`, ce module ne le sait pas et ne s'en soucie pas, exactement comme l'ancien `NlpManager`. `intent` vaut `None` dans deux cas distincts, tous deux silencieux côté retour (voir le log d'avertissement de `train()` pour repérer le second en amont) : `text` vide/blanc, ou `doc.cats` vide parce que `train()` a reçu moins de deux labels pour cette locale (le textcat n'a alors jamais été construit — voir son propre commentaire). """ if not self._trained or self._base_nlp is None or self._matcher is None or not text.strip(): return ProcessResult(entities=[], intent=None, score=0.0) doc = self._base_nlp(text) # A technique's own synonym list can legitimately contain one phrase # nested inside another (`melt`'s "fondre" is a literal substring of # its own "faire fondre") — the `PhraseMatcher` reports *both* as # separate matches at overlapping positions, which without # resolution would hand `splitIntoClauses` (apps/api) two candidates # for what a human reads as one mention, producing the same # techStepId twice in the final result. `filter_spans` keeps only # the longest match at each position (so "faire fondre" wins over # the "fondre" it contains) — found by a real regression in # `tech-step-matcher.test.ts`'s "detects several distinct # techniques..." case once this service replaced node-nlp (which # apparently resolved this internally; nothing here recreates that # by choice, `filter_spans` is spaCy's own documented tool for # exactly this "one span per position" problem, e.g. as used for # NER-style outputs). matched_spans = [ Span(doc, start, end, label=match_id) for match_id, start, end in self._matcher(doc) ] technique_entities = [ Entity( uid=self._base_nlp.vocab.strings[span.label], start=span.start_char, end=span.end_char, kind="technique", ) for span in filter_spans(matched_spans) ] # Second, independent `PhraseMatcher` pass for ustensiles — run and # `filter_spans`-resolved *separately* from the technique pass # above: the two matchers' candidates never compete for the same # position (a longer utensil match must never swallow/be swallowed # by a technique match the way two overlapping technique synonyms # do), only overlaps *within* the same matcher are the known # problem `filter_spans` exists for (see the technique pass's own # comment above). utensil_entities: list[Entity] = [] if self._utensil_matcher is not None: utensil_spans = [ Span(doc, start, end, label=match_id) for match_id, start, end in self._utensil_matcher(doc) ] utensil_entities = [ Entity( uid=self._base_nlp.vocab.strings[span.label], start=span.start_char, end=span.end_char, kind="utensil", ) for span in filter_spans(utensil_spans) ] entities = sorted(technique_entities + utensil_entities, key=lambda entity: entity.start) cats = doc.cats if not cats: return ProcessResult(entities=entities, intent=None, score=0.0) intent = max(cats, key=cats.get) return ProcessResult(entities=entities, intent=intent, score=cats[intent])