Merge pull request 'perf(tech-steps): corrige la largeur du textcat — démarrage ~5× plus rapide' (#25) from perf/nlp-textcat-width into main

Reviewed-on: #25

.github/workflows/ci.yml

@@ -121,11 +121,14 @@ jobs:
           uv run uvicorn intent_service.main:app --host 0.0.0.0 --port 8000 &
           # `/health` only returns 200 once this service has finished
           # training itself from scratch (no model ever persisted to disk —
-          # see its own README) — measured at ~540s (fr) / ~390s (en),
-          # ~930s combined, against the current ~74-technique corpus (see
-          # docker-compose.yml's healthcheck for the same reasoning and why
-          # this grew slightly from the original ~670s).
-          timeout 1200 bash -c 'until curl -sf http://localhost:8000/health > /dev/null; do sleep 2; done'
+          # see its own README) — measured at ~3min combined (fr+en) against
+          # the current ~74-technique corpus, down from ~930s once
+          # `spacy.TextCatBOW.v3`'s `length` stopped being left at its
+          # 262144 default (see `_TEXTCAT_MODEL_LENGTH` in
+          # `locale_pipeline.py`, and docker-compose.yml's healthcheck for
+          # the same reasoning). The timeout stays well above that: it's a
+          # ceiling for a slow/contended runner, not a target.
+          timeout 600 bash -c 'until curl -sf http://localhost:8000/health > /dev/null; do sleep 2; done'
 
       - run: pnpm install --frozen-lockfile
       - run: pnpm --filter api exec prisma migrate deploy

docker-compose.yml

@@ -100,17 +100,19 @@ services:
       # This service trains itself from scratch on every start (no model
       # ever persisted to disk, see its own README) — `/health` only
       # returns 200 once that's done, not just once the base spaCy models
-      # are loaded. Measured at ~540s (fr) / ~390s (en), ~930s combined,
-      # against the current ~74-technique corpus — each technique now has
-      # the *same* number of `utterances` per locale as every other
-      # (equalized to the corpus's own pre-existing max, 7/5 — see
-      # `training_data.py`'s own doc comment for why a flat, larger target
-      # like 20 was tried and reverted) — `start_period` generous enough
-      # that failing checks during that whole window never count against
-      # `retries` (which would otherwise flip this container to
-      # "unhealthy" mid-training, blocking `app`'s own `depends_on:
-      # condition: service_healthy` indefinitely).
-      start_period: 1200s
+      # are loaded. Measured at ~3min combined (fr+en) against the current
+      # ~74-technique corpus, down from ~930s: the old figure was dominated
+      # by `spacy.TextCatBOW.v3`'s `length` parameter sitting at its 262144
+      # default, not by the corpus size (see `_TEXTCAT_MODEL_LENGTH` in
+      # `locale_pipeline.py` for the measurements).
+      #
+      # `start_period` stays deliberately far above that: it only governs
+      # how long failing checks are excused from counting against `retries`
+      # (which would otherwise flip this container to "unhealthy"
+      # mid-training and block `app`'s `depends_on: condition:
+      # service_healthy` indefinitely), so an over-generous value costs
+      # nothing while an under-tight one breaks startup on a slow runner.
+      start_period: 600s
 
   # Deliberately its own image, not built into `app`'s (see
   # services/tech-step-llm-worker/Dockerfile's own doc comment) — a

services/tech-step-intent-service/README.md

@@ -89,24 +89,28 @@ côté `apps/api`.
 
 ## Temps de démarrage
 
-**Ce service met plusieurs minutes à devenir `healthy`** — contrairement à
-node-nlp (entraînement quasi instantané), entraîner le `textcat` sur le
-corpus réel (~74 techniques, chaque technique entraînée sur ses `synonyms`
-en plus de ses `utterances` — voir `locale_pipeline.py`) prend de l'ordre
-de 540 secondes pour `fr` / 390 secondes pour `en` (mesuré localement,
-sans GPU), donc environ 930 secondes (~15-16 minutes) pour `fr`+`en`
-combinés à chaque démarrage du process — chaque technique a désormais le
-même nombre d'`utterances` par locale (voir `training_data.py`'s own doc
-comment), légèrement plus qu'avant ce rééquilibrage. `docker-compose.yml`
-et `.github/workflows/ci.yml` ont un `start_period`/timeout d'attente
-généreux pour ça (`1200s`) — voir leurs propres commentaires. C'est un
-compromis
-assumé, pas un défaut de configuration à corriger : moins d'itérations
-entraîne plus vite mais laisse des verdicts corrects sous
-`CONFIDENCE_THRESHOLD` (voir le commentaire de cette constante,
-`apps/api/src/lib/recipe-matching/tech-step-matcher.ts`, et celui de
-`_TRAINING_ITERATIONS`/`_TRAINING_BATCH_SIZE` dans `locale_pipeline.py`
-pour le détail du compromis).
+Ce service s'entraîne à chaque démarrage du process (voir plus bas pourquoi
+rien n'est persisté), ce qui prend de l'ordre de **~110 secondes pour `fr`**
+/ **~75 secondes pour `en`**, soit **~3 minutes** pour les deux locales
+combinées.
+
+Ça a longtemps été **~930 secondes (15-16 minutes)**, décrit ici comme « un
+compromis assumé, pas un défaut de configuration à corriger ». C'était un
+mauvais diagnostic : le coût ne venait ni des itérations ni de la taille du
+corpus, mais du paramètre `length` de `spacy.TextCatBOW.v3`, laissé à son
+défaut spaCy de `262144` alors que le corpus ne contient que ~920 tokens
+distincts — soit une couche de sortie de 19,4 millions de paramètres mise à
+jour à chaque pas de gradient, pour une table de hachage vide à 99,99 %. Le
+passer à `65536` (voir `_TEXTCAT_MODEL_LENGTH` dans `locale_pipeline.py` pour
+le balayage complet) rend l'entraînement **~5x plus rapide sans changement
+mesurable de comportement** — même accuracy dev, confiance identique au bit
+près, mêmes verdicts sur les probes difficiles. `2048` (30x) est atteignable
+mais décale mesurablement la distribution des scores ; c'est du travail pour
+la phase où le jeu d'évaluation aura été élargi.
+
+`docker-compose.yml` et `.github/workflows/ci.yml` gardent un
+`start_period`/timeout d'attente confortable — un plafond pour runner lent,
+pas une cible.
 
 ## Logs
 
@@ -177,20 +181,34 @@ vraie instance de ce service tournant (voir `apps/api/.env.test`), conforme
 
 ## Limitations connues
 
-- **Démarrage lent** (~15-16 minutes) — voir "Temps de démarrage" ci-dessus.
-  Une optimisation possible non explorée : parallélisation de
-  l'entraînement `fr`/`en` (actuellement séquentiel,
-  `PipelineRegistry.initialize`).
+- **`TECH_STEP_EVAL_DATASET` ne couvre que 26 des 74 techniques** (41 cas,
+  33 `fr` / 8 `en`) — 48 techniques (65 %) n'ont *aucune* couverture
+  d'évaluation. Le F1 agrégé de `0.815` porte sur ~39 spans, ce qui ne
+  permet de mesurer ni le F1 par technique, ni les confusions entre
+  techniques voisines. **C'est la limitation la plus bloquante de la
+  liste** : tant qu'elle tient, aucun changement d'architecture ou de
+  corpus n'est mesurable autrement qu'à l'intuition.
 - **`CONFIDENCE_THRESHOLD` côté `apps/api` est un placeholder** depuis
   l'élargissement du corpus à ~74 techniques (calibré à la main, pas via
   une vraie repasse de `calibrate-tech-step-threshold.ts` contre
   `TECH_STEP_EVAL_DATASET` — voir le commentaire de cette constante).
-- **Textcat bag-of-words** (`spacy.TextCatBOW.v3`) — suffisant pour le
-  corpus actuel une fois correctement entraîné, mais n'exploite pas les
-  vecteurs de mots des modèles `md` chargés. Migrable vers une architecture
-  tok2vec/similarité sans changer le contrat HTTP, si le F1 mesuré par
-  `apps/api/src/scripts/calibrate-tech-step-threshold.ts` le justifie un
-  jour.
+  Conséquence directe du point précédent.
+- **Textcat bag-of-words** (`spacy.TextCatBOW.v3`) — n'exploite pas les
+  vecteurs de mots des modèles `md` chargés. Une mesure ponctuelle donne
+  `spacy.TextCatReduce.v1` (tok2vec + vecteurs statiques) à 98,6 %
+  d'accuracy dev et 0,984 de confiance moyenne, contre 97,3 % / 0,919 pour
+  le BOW actuel. **Mais** les mêmes sondes montrent des erreurs *confiantes*
+  sur les classes voisines (`"enfourner la tarte"` → `blindBake` 0,711 avec
+  `bake` à 0,004 ; `"cuire les pâtes dans l'eau bouillante"` → `poach`
+  0,801) : une confiance plus haute ne veut pas dire plus juste, et
+  neutralise `CONFIDENCE_THRESHOLD` comme filet de sécurité. À ne trancher
+  qu'avec un F1 par classe, donc après le premier point de cette liste.
+- **Des techniques se recouvrent réellement** (`bake`/`blindBake`,
+  `boil`/`poach`/`blanch`/`cook`, `rest`/`proof`) — 74 classes mutuellement
+  exclusives à ~7 exemples chacune, aux frontières floues, est un cadrage
+  qui plafonne quelle que soit l'architecture. À instruire (fusion de
+  classes ? `textcat_multilabel` ?) seulement si une matrice de confusion le
+  confirme.
 - **Reconstruit tout le pipeline à chaque démarrage** (pas de persistance,
   pas de fusion incrémentale) — un choix délibéré (voir
   `LocalePipeline.train`), pas une limitation à lever : `training_data.py`

services/tech-step-intent-service/intent_service/locale_pipeline.py

@@ -54,6 +54,56 @@ _EXCLUDED_COMPONENTS = ["parser", "ner", "tagger", "morphologizer", "attribute_r
 
 _TEXTCAT_PIPE_NAME = "textcat"
 
+# Largeur du vecteur de features hachées de `spacy.TextCatBOW.v3`.
+#
+# **Ce paramètre était le goulot d'étranglement du démarrage de ce service.**
+# spaCy le laisse à `262144` (2^18) par défaut, et il n'était pas passé
+# explicitement ici. Avec `no_output_layer: False` et 74 techniques, la
+# couche de sortie fait alors `262144 x 74` = **19 398 730 paramètres**, que
+# l'optimiseur Adam met à jour à *chaque* pas de gradient. Or le corpus
+# (`training_data.py`) ne contient que ~920 tokens distincts : l'écrasante
+# majorité de cette table de hachage n'est jamais peuplée. On payait un
+# temps de calcul proportionnel à une table vide.
+#
+# Balayage mesuré contre le corpus réel (74 techniques, `fr`, 25 itérations,
+# `ngram_size=1`, jeu de dev = la dernière `utterance` de chaque technique
+# tenue hors entraînement). "collisions" = tokens distincts du corpus
+# partageant un bucket avec un autre (sur 920) :
+#
+#   length   | params    | accuracy dev | confiance moy. | collisions | train
+#   ---------|-----------|--------------|----------------|------------|------
+#   262144   | 19398730  | 97.3%        | 0.809          |   2/920    | 400 s
+#   65536    |  4849722  | 97.3%        | 0.809          |  10/920    | 106 s
+#   16384    |  1212490  | 97.3%        | 0.808          |  50/920    |  35 s
+#    2048    |   151626  | 97.3%        | 0.816          | 305/920    |  13 s
+#
+# `65536` a été retenu comme la valeur **conservatrice** : confiance moyenne
+# identique au bit près au défaut spaCy (0.809), 1 % de collisions, et
+# pourtant **~5x plus rapide** (et ~15x moins de paramètres). C'est un gain
+# de calcul, pas un compromis de qualité — le jeu de dev, les probes
+# difficiles (`bake`/`blindBake`, `boil`/`poach`…) et la confiance sont
+# inchangés.
+#
+# `2048` a d'abord été livré puis reculé : à cette largeur, 305 des 920
+# tokens du corpus entrent en collision (33 %), ce qui replie des mots
+# distincts ensemble, décale mesurablement la confiance (0.816) et pourrait
+# donc décaler le F1 par classe — impossible à vérifier hors de la CI (gate
+# `tech-step-eval.test.ts`, nécessite Postgres). Descendre en dessous de
+# `65536` reste possible, mais c'est du travail pour la phase où le jeu
+# d'évaluation aura été élargi et pourra le valider.
+_TEXTCAT_MODEL_LENGTH = 65536
+# Unigrammes. `ngram_size=2` a été essayé et **reculé** : les bigrammes
+# rendent le classifieur nettement plus confiant (confiance moyenne
+# `0.809 -> 0.919`) — ce qui, contre-intuitivement, dégrade la justesse
+# bout-en-bout. `_classifyClause` (`tech-step-matcher.ts`) ne retombe sur
+# l'ancre NER que lorsque le score du classifieur est *sous*
+# `CONFIDENCE_THRESHOLD` ; une classification bout-de-clause confiante mais
+# fausse sur une technique voisine (`blindBake` au lieu de `bake`, `poach`
+# au lieu de `boil`) passe alors ce seuil et écrase l'ancre correcte. Le F1
+# agrégé de `tech-step-eval.test.ts` est tombé de `0.815` à `0.753`, sous le
+# plancher de `0.8`, uniquement à cause de ce changement.
+_TEXTCAT_NGRAM_SIZE = 1
+
 # 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
@@ -61,33 +111,33 @@ _TEXTCAT_PIPE_NAME = "textcat"
 # mais avec une confiance dérisoire — bien en dessous de tout seuil
 # raisonnable pour `CONFIDENCE_THRESHOLD` (`tech-step-matcher.ts`).
 #
-# Trois passes de calibration successives, toutes mesurées contre le
-# corpus réel (74 techniques) :
+# Historique de calibration (toutes les mesures contre le corpus réel) :
 # 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.
+# 3. Les `synonyms` de chaque technique sont devenus eux 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.
+#    Gain confirmé depuis par ablation : retirer les synonymes des exemples
+#    fait retomber la confiance moyenne de `0.816` à `0.714` à configuration
+#    égale. `_TRAINING_ITERATIONS` a été descendu à `25` à cette occasion
+#    pour compenser le temps d'entraînement.
+# 4. **Correction du diagnostic** : les étapes 1-3 attribuaient le coût aux
+#    itérations et au nombre d'exemples. C'était faux — il venait presque
+#    entièrement de `_TEXTCAT_MODEL_LENGTH` (voir son propre commentaire).
+#    Une fois ce paramètre corrigé, 25 itérations coûtent ~106 s par locale
+#    au lieu de ~406 s. `25` est conservé tel quel : la valeur donne déjà
+#    97.3% d'accuracy dev, et la marge de temps désormais disponible n'a
+#    d'intérêt que si une vraie mesure (F1 par classe, voir
+#    `tech-step-evaluator.ts`) montre qu'il y a quelque chose à y gagner.
+#
+# Une vraie repasse de `calibrate-tech-step-threshold.ts` contre
+# `TECH_STEP_EVAL_DATASET` reste nécessaire (voir `CONFIDENCE_THRESHOLD`'s
+# propre commentaire, `tech-step-matcher.ts`) — les chiffres ci-dessus sont
+# des mesures ponctuelles, pas un remplacement de cette calibration.
 _TRAINING_ITERATIONS = 25
 _TRAINING_BATCH_SIZE = 16
 # Arrêt anticipé : `_TRAINING_ITERATIONS` reste le plafond (le pire cas ne
@@ -333,8 +383,12 @@ class LocalePipeline:
                     "model": {
                         "@architectures": "spacy.TextCatBOW.v3",
                         "exclusive_classes": True,
-                        "ngram_size": 1,
+                        "ngram_size": _TEXTCAT_NGRAM_SIZE,
                         "no_output_layer": False,
+                        # Explicite, jamais laissé au défaut spaCy — voir
+                        # `_TEXTCAT_MODEL_LENGTH` pour pourquoi ce seul
+                        # paramètre valait 30x le temps d'entraînement.
+                        "length": _TEXTCAT_MODEL_LENGTH,
                     },
                 },
             )