mirror of
https://github.com/siop-spelev/siop2.git
synced 2026-08-08 12:41:54 +00:00
59ed6f3952
Écran Voix R5 (maquetté, jamais construit) implémenté sur décision du référent : open-source et local, pas d'API externe. - apps/ai : faster-whisper (CTranslate2, CPU, MIT) opt-in (AI_TRANSCRIPTION=off|locale|deterministe, défaut off) ; endpoint /internal/transcrire — l'audio ne survit JAMAIS à l'appel (fichier temporaire supprimé quoi qu'il arrive) ; indexer_bilans inclut désormais InterventionReport.note anonymisée (champ existant depuis R2, jamais eu d'écran jusqu'ici) ; 29 pytest. - Contrat (77 opérations) : POST /assistant/transcribe (multipart). - API : proxy multipart vers siop2-ai (WORK_ORDERS.edit — même droit que la saisie du bilan) ; 2 tests e2e (80 tests API au total). - Mobile : expo-audio + expo-file-system, bouton dicter/terminer sur l'écran de clôture, purge locale après transcription, « Joindre la description à l'OT » (corrige un bug latent : enfilerBilan ignorait silencieusement les mises à jour de note). - Docker : siop2-ai embarque le modèle Whisper au build (1,54→2,19 Go), construit et vérifié (transcription réelle en conteneur, non-root). - Vérifié réellement : transcription fidèle (voix de synthèse française) en direct, bout en bout via l'API, dans le conteneur Docker construit, et chaîne corpus complète (note → clôture → réindexation → recherche sémantique). - Base de dev locale réinitialisée avec accord explicite du référent (prisma migrate reset, bloqué par défaut pour un agent IA) après pollution par les tests manuels de la recette terrain précédente. Reste : test tactile sur iPhone physique (bouton dicter) — bloqué par une connexion USB qui ne s'est pas rétablie malgré câble/port/ redémarrage essayés à plusieurs reprises, reporté comme la recette Android. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
86 lines
6.5 KiB
Markdown
86 lines
6.5 KiB
Markdown
# ADR-004 — Modèles et topologie du service IA (R5)
|
|
|
|
- **Statut** : acceptée (R5.1, 17 juillet 2026)
|
|
- **Contexte** : les maquettes R5 et les décisions D1-D5 sont validées (l'IA propose/l'humain
|
|
valide, sourcé ou silencieux, corpus fermé, anonymisation 09-08, voix purgée). Reste à
|
|
trancher COMMENT : quels modèles, où tournent-ils, qui parle à qui. Contraintes : serveur
|
|
Dokploy du partenaire (CPU, pas de GPU garanti), corpus en français, données d'un client
|
|
marocain (loi 09-08), CI sans secret, démo qui marche sans dépendance externe.
|
|
|
|
## Décision
|
|
|
|
1. **Embeddings : locaux, sur CPU** — `fastembed` (ONNX, sans PyTorch) avec
|
|
`sentence-transformers/paraphrase-multilingual-mpnet-base-v2` (768 dimensions, multilingue,
|
|
~1 Go, registre fastembed). Les textes du client ne quittent JAMAIS le serveur pour
|
|
l'indexation ni pour la recherche. Le modèle est téléchargé au build de l'image (pas au
|
|
démarrage). En **tests/CI : embeddeur déterministe par hachage** (pas de téléchargement,
|
|
pas de flottement) derrière la même interface.
|
|
|
|
> **Amendé en recette R5 (17/07/2026)** : le choix initial, MiniLM-L12-v2 (384 d, ~220 Mo),
|
|
> a été invalidé par la mesure — sur un banc français question→passage, il classait la
|
|
> page contenant la réponse DERRIÈRE des passages sans rapport (0,24 contre 0,41) et ne
|
|
> laissait aucune marge pour le seuil de refus D2. `mpnet-base-v2` rétablit le classement
|
|
> et une marge signal/bruit exploitable (pertinent ≥ 0,46 ; hors-corpus ≤ 0,42) pour un
|
|
> coût CPU encore raisonnable. `multilingual-e5-large` (1024 d, 2,2 Go) classait aussi
|
|
> correctement mais ses scores compressés (0,73-0,90) et son poids l'écartent — à
|
|
> réévaluer au calibrage sur le corpus client si la marge de mpnet s'avère insuffisante.
|
|
> Migration `r5_embeddings_mpnet` : colonne pgvector 384 → 768, index vidé (re-dérivable
|
|
> par réindexation). Seuils par défaut recalés : pertinence 0,45, suggestion 0,40,
|
|
> confiance forte 0,55.
|
|
2. **Stockage vectoriel : pgvector** dans le PostgreSQL existant (extension déjà installée
|
|
depuis R0) — table `RagChunk` gérée par la **migration Prisma** (le schéma reste la
|
|
propriété d'`apps/api`, source unique). Pas de base vectorielle de plus à opérer.
|
|
3. **Génération (réponses rédigées de l'assistant) : opt-in par configuration.**
|
|
- Sans clé (`AI_GENERATION=off`, défaut) : l'assistant fonctionne en **mode extractif** —
|
|
il montre les meilleurs extraits sourcés et une synthèse templatée, sans LLM. La démo,
|
|
la CI et un déploiement sans budget API restent pleinement fonctionnels et honnêtes.
|
|
- Avec clé (`AI_GENERATION=api` + `AI_API_KEY`, modèle configurable par `AI_MODEL`,
|
|
défaut `claude-opus-4-8`) : rédaction par le SDK officiel Anthropic, sur textes DÉJÀ
|
|
anonymisés (D4), avec l'obligation de citer les extraits fournis — jamais au-delà.
|
|
La config est validée au boot (api sans clé = refus de démarrer) ; la clé n'apparaît
|
|
ni dans les journaux ni au `/healthz` (qui n'expose que le mode). Tout échec du LLM
|
|
(refus, quota, réseau) retombe silencieusement sur le mode extractif.
|
|
- La **suggestion de codes de bilan** n'utilise PAS de LLM : similarité sémantique
|
|
(embeddings locaux) entre la description et les libellés des référentiels + les bilans
|
|
historiques du parc. Déterministe, testable, explicable (« 9 bilans similaires »).
|
|
4. **Topologie** : `apps/ai` (FastAPI/uv, conteneur `siop2-ai`) n'est **jamais exposé** —
|
|
réseau interne Dokploy uniquement, comme MinIO. Les utilisateurs passent par l'API NestJS
|
|
(auth JWT + matrice de permissions réutilisées) qui proxifie vers `siop2-ai`
|
|
(`AI_SERVICE_URL` + secret partagé `AI_SERVICE_TOKEN`). `apps/ai` lit Postgres
|
|
(métadonnées, bilans, écriture des chunks) et MinIO (octets des PDF) en direct sur le
|
|
réseau privé — la règle d'or ESLint d'ADR-001 concerne le code TypeScript de l'API,
|
|
la topologie « MinIO jamais exposé » du runbook reste respectée.
|
|
|
|
5. **Transcription (dictée, R5 D5) : locale, opt-in, jamais de persistance de l'audio.**
|
|
Amendement du 22/07/2026 — le référent choisit `faster-whisper` (CTranslate2, CPU,
|
|
licence MIT) plutôt qu'une API externe, même philosophie que les embeddings : « open
|
|
source et local ». `AI_TRANSCRIPTION=off` par défaut (endpoint refuse proprement,
|
|
503) ; `locale` charge le modèle (taille configurable par `AI_TRANSCRIPTION_MODEL`,
|
|
défaut `small`) ; `deterministe` en tests/CI (aucune dépendance audio). Le flux :
|
|
l'audio ne transite qu'une fois vers `siop2-ai` (multipart, jamais écrit sur disque
|
|
par `siop2-api`), un fichier temporaire le temps de l'inférence côté `siop2-ai`,
|
|
**supprimé aussitôt quoi qu'il arrive** — succès ou erreur (loi 09-08, D5). Seul le
|
|
texte transcrit revient, à relire par l'humain (D1) avant tout usage : suggestion de
|
|
bilan immédiate, et/ou sauvegarde dans `InterventionReport.note` — qui, à la clôture
|
|
de l'OT, rejoint le corpus comme les libellés codés (même pipeline d'anonymisation,
|
|
D4). **Point de vigilance non calibré** (décision explicite du référent : pas de
|
|
prototype de mesure préalable, contrairement au choix du modèle d'embeddings) :
|
|
Whisper transcrit mal le darija, probable en mélange avec le français sur le
|
|
terrain — à mesurer sur des enregistrements réels si la qualité déçoit en recette.
|
|
|
|
## Conséquences
|
|
|
|
- L'anonymisation (D4) s'applique **à l'ingestion** — les index ne contiennent jamais
|
|
d'identités ; le mode génératif n'envoie donc que des textes déjà nettoyés.
|
|
- Le mode extractif est le contrat de base : toute recette R5 doit passer SANS clé API.
|
|
- Si le partenaire veut un jour une génération 100 % locale (llama.cpp…), seul le point 3
|
|
change — interface `Generateur` prévue pour ça.
|
|
- La dictée (point 5) est opt-in et sans mesure de qualité préalable : à recetter avec
|
|
attention avant toute promesse de qualité au client, en particulier en darija.
|
|
- Implémentée et vérifiée le 22/07/2026 : transcription réelle (français, voix de
|
|
synthèse) juste et rapide en local, bout en bout via l'API NestJS, et dans l'image
|
|
Docker de production construite pour l'occasion (modèle embarqué, aucun téléchargement
|
|
au démarrage). **Reste** : le test tactile sur iPhone physique (bouton dicter, permission
|
|
micro) n'a pas pu se jouer — blocage USB persistant malgré câble/port/redémarrage
|
|
multiples, reporté comme la recette Android (attend un accès matériel qui fonctionne).
|