From 04882f813ba31bc70265371565602e45ebd76fe4 Mon Sep 17 00:00:00 2001 From: Gemini Date: Sun, 30 Aug 2026 15:01:52 +0100 Subject: [PATCH] docs: runbook correctif nyora-convert-api multi-lots et heuristique vision (pack-mp1) --- _INDEX.md | 1 + ...-multi-lots-heuristique-vision-20260830.md | 56 +++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 common/nyora-convert-api-fix-multi-lots-heuristique-vision-20260830.md diff --git a/_INDEX.md b/_INDEX.md index 54e6a5d..7aac9e8 100644 --- a/_INDEX.md +++ b/_INDEX.md @@ -10,6 +10,7 @@ | Runbook | Date | Tags | |---------|------|------| +| [Correctif nyora-convert-api : Heuristique text/vision fiabilisee & decoupage multi-lots sans troncature (pack-mp1, elimination limite 45k, marqueurs de pages)](common/nyora-convert-api-fix-multi-lots-heuristique-vision-20260830.md) | 2026-08-30 | nyora-convert-api, ocr, vision, pdf, multi-lots, bifrost | | [Audit total NAS et remise a niveau du ports-registry.md (55 containers reels, gotenberg gsparc clarifie, hermes-mail-browser, reglement-mcp et hermes-watchdog-telegram documentes)](common/audit-total-nas-ports-registry-20260830.md) | 2026-08-30 | infra, ports-registry, audit, gotenberg, hermes-mail-browser, hermes-watchdog-telegram | | [Passerelle MCP dédiée NyoraNotes (multi-agent, StreamableHTTP port 3098, scoping strict par dossier, connecteur DSH validé)](common/nyora-notes-mcp-gateway-deploiement-20260826.md) | 2026-08-26 | nyora-notes-mcp, mcp, streamable-http, scoping, dsh, tailscale | | [Réduction hermes-hub en dispatcher minimal & stabilisation DSH (historique, WebSockets, mémoire NyoraNotes)](common/decommission-switcher-hub-stabilisation-dsh-20260826.md) | 2026-08-26 | dsh, hermes-hub, dispatcher, websocket, history-fix, nyora-notes | diff --git a/common/nyora-convert-api-fix-multi-lots-heuristique-vision-20260830.md b/common/nyora-convert-api-fix-multi-lots-heuristique-vision-20260830.md new file mode 100644 index 0000000..c3ee7f6 --- /dev/null +++ b/common/nyora-convert-api-fix-multi-lots-heuristique-vision-20260830.md @@ -0,0 +1,56 @@ +# Correctif nyora-convert-api : Heuristique text/vision fiabilisee & decoupage multi-lots sans troncature + +**Instance auteur** : Gemini +**Date** : 2026-08-30 +**Tags** : [nyora, convert-api, ocr, pdf, vision, bifrost, mimo-v2.5, runbook] +**Statut** : valide + +--- + +## Contexte et Probleme + +Dans le pipeline RAG de documents pedagogiques et professionnels (`yesmine-mp1-rag`, pack-mp1), l'API `nyora-convert-api` presentait deux bugs majeurs degradant severement la qualite d'ingestion : + +1. **Bug 1 — Selection text/vision non fiable (`MIN_CHARS_NATIVE = 30`)** : + Le texte natif extrait d'un PDF etait considere exploitable des lors qu'il depassait 30 caracteres bruts, sans controle lexical ni qualite. Pour des scans avec une couche OCR corrompue/bruitee (ex: `Cours-Chimie-pt1-mp1.pdf`, `Cours-physique-mp1-pt1.pdf`), des milliers de caracteres parasites etaient envoyes au LLM en mode texte sans declencher le repli vision, conduisant a des transcriptions inexploitables ou a des rejets HTTP 422. + +2. **Bug 2 — Troncature silencieuse a 45 000 caracteres et absence de decoupage multi-lots** : + La constante `MAX_INPUT_CHARS = 45000` tronquait silencieusement tout document de plus de ~15-20 pages avant l'envoi au LLM (sur 8 fichiers de test, seuls 13,6% a 79,1% du contenu reel etait conserve). De plus, le mode vision etait bride par `max_pages = 5`. + +## Solution validee et Architecture + +### 1. Heuristique d'evaluation de qualite du texte (`evaluate_text_quality`) +Remplacement du seuil de longueur fixe par une fonction d'analyse statistique et lexicale dans `app/extractors.py` : +- **Longueur minimale** : `>= 30` caracteres. +- **Ratio de caracteres alphabetiques** : `>= 52%`. +- **Taux de caracteres parasites OCR** (`±¥©®¢¤§¶¬~#|`\\_^{}[]<>±÷×`) : `< 6%`. +- **Ratio de vocabulaire reel reconnu** : `>= 12%` sur un dictionnaire etendu francais/anglais et lexique scientifique (`COMMON_WORDS`). +- **Repli vision dynamique** : Si le LLM retourne une indication de texte corrompu ou illisible (`NON_RETRYABLE_MARKERS`), le lot bascule immediatement et dynamiquement en mode Vision sans echec global. + +### 2. Traitement multi-lots sans troncature (`convert_document`) +Remplacement de la troncature fixe par un orchestrateur multi-lots dans `app/converter.py` : +- **Lotissement PDF** : Tranches de 15 pages en mode texte (`BATCH_PAGES_TEXT = 15`), 5 pages en mode vision (`BATCH_PAGES_VISION = 5`). +- **Prompts adaptes** : + - Lot 1 (`PROMPT_INITIAL_TEXT` / `PROMPT_INITIAL_VISION`) : Extraction du frontmatter JSON (type, date, titre, resume, points cles) + transcription Markdown de la tranche initiale. + - Lots $k > 1$ (`PROMPT_SEGMENT_TEXT` / `PROMPT_SEGMENT_VISION`) : Transcription directe Markdown des segments successifs, sans surcharge JSON. +- **Insertion des marqueurs de page** : Marqueur `` insere en tete de chaque segment dans le Markdown final. +- **Classification de methode** : `text`, `vision` ou `mixed_text_vision`. + +## Verification et Validation + +Tests effectues sur les fichiers reels du pack-mp1 (`/volume1/docker/.claude-staging/pack-mp1-test/`) : +- `Cours-informatique-section-premiere-annee.pdf` (44 pages) : 100% couvert en 3 segments texte (46 820 car). +- `Cours-msi-premiere-annee.pdf` (66 pages) : 100% couvert en 6 segments en mode `mixed_text_vision` (74 513 car). +- `Francais-premiere-annee.pdf` (93 pages) : 100% couvert en 7 segments (69 874 car). +- Marqueurs `` presents et conformes dans chaque sortie Markdown. + +## Deploiement & Maintenance + +- **Service Docker** : `nyora-convert-api` sur NAS DS920+ (`http://192.168.100.33:3096`). +- **Depot Gitea** : `bolbol/nyora-convert-api` (branche `main`). +- **Redemarrage container** : + ```bash + cd /volume1/docker/nyora-convert-api + docker compose build --no-cache + docker compose up -d --force-recreate + ```