Aller au contenu
English

Traitement des entrées

  • Leçon 5
  • 50 min
  • Module 2 : Préparer et extraire le contenu

Où nous en sommes

Dans le module 1, nous avons examiné chaque fichier, choisi le chemin de chaque page et écrit le contrat que chaque lecteur doit remplir. Mais certains fichiers ne devraient jamais atteindre un lecteur : un PDF endommagé, un fichier verrouillé, un fichier trop volumineux ou le même reçu deux fois. Dans cette leçon, nous vérifions chaque fichier à l'entrée, comme une salle du courrier, et arrêtons chaque mauvais fichier avec une raison compréhensible.

Ce que vous saurez faire

Vérifiez chaque fichier avant qu’un programme le lise. Un fichier endommagé, verrouillé, trop volumineux ou répété s’arrête ainsi à l’entrée, avec une raison compréhensible. Il ne fait pas planter le lecteur et ne parvient pas deux fois à un agent.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 50 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre projet ~/projects/doc-extract à la fin du module 1 : avec l’environnement virtuel actif, python -m pytest -q affiche 40 passed (40 tests réussis). Si votre projet ne fonctionne plus, copiez l’instantané end-of-m01 comme l’indique le README des instantanés.
  • Les documents du cours dans data/documents/ : python -m doc_extract.generate --check affiche All 65 files match the course's checksums. (les 65 fichiers correspondent aux sommes de contrôle du cours).
  • Le dépôt des exercices dans ~/projects/nextia-learning-labs, obtenu dans la leçon de préparation. Récupérez ses fichiers les plus récents avec git -C ~/projects/nextia-learning-labs pull.

Le générateur du cours crée tous les documents de ce cours. Ils ne contiennent aucun vrai client, reçu de magasin ou numéro de carte. Tests effectués avec Python 3.12.13, pypdf 6.20.0, pypdfium2 5.14.0 et Pillow 12.3.0 sur macOS (Apple silicon). Les commandes Windows et Linux n’ont pas été testées.

Les trois leçons de ce module utilisent des fichiers qui fonctionnent ensemble : les vérifications de cette leçon, trois façons de lire une page et la préparation des images. Vous les copiez donc une seule fois, maintenant, à partir de l’instantané end-of-m02. Chaque leçon ouvre ensuite son propre fichier.

  1. Allez dans le dossier des projets :

    Fenêtre de terminal
    cd ~/projects
  2. Copiez les fichiers de l’instantané dans votre projet. Vos dossiers data/, out/ et .venv restent en place. La copie remplace README.md et .env.example par leurs versions du module 2.

    Fenêtre de terminal
    cp -R nextia-learning-labs/C13/snapshots/end-of-m02/. doc-extract/
  3. Entrez dans le projet et activez l’environnement virtuel (source .venv/bin/activate sur macOS et Linux, .venv\Scripts\Activate.ps1 sur Windows).

  4. Lancez les tests. Ils créent leur propre copie des documents et exécutent l’OCR sur quelques pages. Ils prennent donc environ 30 secondes :

    Fenêtre de terminal
    python -m pytest -q

    La dernière ligne est 63 passed (63 tests réussis). Vous n’installez rien de nouveau : requirements.txt contenait déjà tous les paquets du cours.

Pensez au service du courrier d’un grand bureau. Avant qu’une lettre monte à un bureau, un commis examine chaque enveloppe. Un colis trop gros va à un autre comptoir. Une enveloppe vide est retournée. Une enveloppe déchirée qui a perdu son contenu ne peut pas être lue. Une boîte verrouillée nécessite une clé que le commis n’a pas. Et si la même lettre arrive deux fois, la deuxième copie ne monte pas, sinon deux personnes y répondraient.

Le commis ne lit pas les lettres. Les vérifications sont rapides et se font une seule fois, à l’entrée. Grâce à elles, personne aux étages ne perd de temps avec un colis impossible à ouvrir. Et quand le commis retourne quelque chose, la note explique pourquoi : « trop volumineux », « endommagé », « verrouillé ».

Le problème : le premier lecteur qui rencontre un mauvais fichier

Section intitulée « Le problème : le premier lecteur qui rencontre un mauvais fichier »

Les billets de soutien de Larkfield contiennent les fichiers joints par les clients, et les clients joignent de tout. Le jeu du cours contient volontairement sept fichiers problématiques, D059 à D065, du genre que reçoit le service de soutien. Sans vérification à l’entrée, le premier programme qui lit un fichier rencontre le problème et l’explique mal.

Voici deux exemples réels tirés des fichiers du cours. D064 s’appelle receipt-scan.pdf, mais c’est une photo au format JPEG qui porte le mauvais nom. Donnez-le à PDFium, la bibliothèque qui dessine les pages PDF sous forme d’images, et le programme s’arrête :

pypdfium2._helpers.misc.PdfiumError: Failed to load document (PDFium: Data format error).

D061 est un PDF dont le téléchargement s’est arrêté à mi-chemin. pypdf, la bibliothèque qui lit la structure d’un PDF, s’arrête avec ce message :

pypdf.errors.PdfReadError: EOF marker not found

Aucun des deux messages ne dit aux agents de Grace quoi faire. Pire encore, une erreur au milieu d’un lot peut aussi bloquer les fichiers suivants. Et certains problèmes ne produisent aucune erreur. D059 est une copie exacte de D001 : le client a joint le même reçu deux fois. Les deux copies se lisent parfaitement et parviennent donc toutes deux à un agent. Le même remboursement peut alors être vérifié deux fois.

Le premier exemple était un vrai bogue. Pendant le développement du cours, un JPEG nommé .pdf a fait planter le moteur de rendu des pages du projet. La correction repose sur la règle de cette leçon : déterminez le format à partir du contenu, jamais du nom. files.is_pdf lit maintenant les premiers octets du fichier partout.

Le traitement des entrées (ou réception) regroupe les vérifications que chaque fichier passe avant qu’un lecteur l’ouvre réellement. Comme le commis, il ne lit pas le contenu. Il pose quelques questions courtes, dans un ordre fixe. Le premier problème bloque le fichier avec un statut, un mot court que le code peut compter. Il fournit aussi une raison, une phrase qu’une personne peut lire. Les vérifications vont de la moins coûteuse à la plus coûteuse. Ainsi, un mauvais fichier coûte le moins possible.

doc_extract/intake.py pose ces questions :

  1. Taille. Le fichier dépasse-t-il la limite, fixée à 8 Mo par défaut (MAX_FILE_MB)? Un énorme fichier ralentit toutes les étapes suivantes, et un appel au modèle coûterait plus cher. Statut too_large (trop volumineux).
  2. Vide. Le fichier contient-il 0 octet? Statut empty (vide).
  3. Format. Les premiers octets indiquent-ils PDF, JPEG, PNG, TIFF ou XLSX? Chaque format commence par sa propre signature courte, son nombre magique : %PDF- pour un PDF, les octets ff d8 ff pour un JPEG. Le nom du fichier n’est pas utilisé. Statut unsupported (non pris en charge).
  4. Ouverture. La bonne bibliothèque peut-elle l’ouvrir? pypdf ouvre un PDF, et PDFium dessine sa première page en très petit. Pillow décode une image; l’archive zip de la feuille de calcul est testée. Statut corrupt (corrompu), ou password (mot de passe) pour un PDF qui nécessite un mot de passe.
  5. Doublon exact. Les octets sont-ils identiques à ceux d’un fichier arrivé plus tôt? Statut duplicate (doublon), avec le nom de la première copie.
  6. Nom. L’extension correspond-elle au contenu? Sinon, le statut est wrong_extension (mauvaise extension), mais le fichier est accepté et lu selon son vrai format.

La dernière vérification est la seule qui ne bloque pas le fichier. Un mauvais nom ne justifie pas le refus d’un bon reçu. Il justifie de faire confiance au contenu et de noter ce qui ne correspondait pas.

Comment le programme sait-il que deux fichiers ont les mêmes octets, sans conserver tous les fichiers qu’il a vus? Il calcule une empreinte : un court résumé des octets, toujours de la même longueur. Le projet utilise SHA-256, qui transforme n’importe quel fichier en 64 caractères hexadécimaux. Les mêmes octets donnent toujours les mêmes 64 caractères. Changez un octet, et environ la moitié des caractères changent. Le programme conserve donc une empreinte par fichier. Un nouveau fichier dont l’empreinte est déjà connue est une copie.

Voici les vraies empreintes de trois fichiers du cours :

758bcf84593dc3430f0fddeaf02073530b1a3996ea3eab0458cb5c560456740e receipt-lk-986875.pdf
758bcf84593dc3430f0fddeaf02073530b1a3996ea3eab0458cb5c560456740e receipt-lk-986875 (1).pdf
bcee48048deb959a629771227ac8e465673456e69a6252051d16d7f71ae8db46 scan0002.jpg

Les deux premiers sont D001 et D059 : mêmes octets, même empreinte. Le nom (1) est ce qu’un ordinateur ajoute quand vous enregistrez un fichier deux fois. Le troisième fichier est différent, donc son empreinte n’a rien en commun avec les autres.

Avant de lancer les vérifications sur les 65 fichiers, suivez-en cinq à la main. Pour chaque fichier, le tableau montre sa taille, ses premiers octets et la décision.

Fichier Taille Premiers octets Premier problème Statut
receipt-lk-986875.pdf (D001) 2 366 octets %PDF- aucun accepted (accepté)
receipt-lk-986875 (1).pdf (D059) 2 366 octets %PDF- l’empreinte 758bcf84… est déjà connue duplicate
receipt-scan.pdf (D064) 289 721 octets ff d8 ff (JPEG) le nom indique PDF, le contenu indique JPEG wrong_extension, accepté
receipt-download.pdf (D061) 1 158 octets %PDF- il ne s’ouvre pas : un PDF se termine par %%EOF, et celui-ci s’arrête avant corrupt
notes.txt (D065) 41 octets Customer says the… (le client dit que…) ni PDF, ni image, ni feuille de calcul unsupported

Deux détails comptent. D061 commence comme un bon PDF : ses premiers octets sont corrects. Seule la quatrième vérification, « s’ouvre-t-il? », trouve donc le problème. Et l’ordre d’arrivée compte pour les doublons. D001 est arrivé en premier, donc D001 est accepté et D059 est le doublon. Si D059 était arrivé en premier, D001 serait la copie. Un des tests du projet vérifie exactement cela.

Un flux de haut en bas. 65 fichiers arrivent. Question : plus de 8 Mo? Oui mène à too_large, D063, 9,1 Mo. Non mène à : 0 octet? Oui mène à empty, aucun dans le jeu. Non mène à : premiers octets PDF, JPEG, PNG, TIFF ou XLSX? Non mène à unsupported, D065, un .txt. Oui mène à : s'ouvre-t-il? Non mène à corrupt D061 et password D062. Oui mène à : même SHA-256 qu'un fichier précédent? Oui mène à duplicate, D059 est identique à D001. Non mène à : le nom correspond-il au contenu? Oui mène à : 60 fichiers poursuivent leur chemin vers la lecture. Non mène à wrong_extension, D064, accepté, qui les rejoint.
Les vérifications à la réception, dans leur ordre. Le premier problème bloque le fichier; seul un mauvais nom le laisse passer. Les nombres proviennent des 65 fichiers du cours.
Description textuelle du diagramme

Un fichier arrive; le cours en compte 65. La première question porte sur la taille : un fichier de plus de 8 Mo est bloqué avec le statut too_large. Dans le jeu du cours, c’est D063, un TIFF non compressé de 9,1 Mo. Deuxième question : le fichier contient-il 0 octet? Aucun ici. Troisième question : les premiers octets indiquent-ils PDF, JPEG, PNG, TIFF ou XLSX? D065, un fichier texte, est bloqué avec le statut unsupported. Quatrième question : le fichier s’ouvre-t-il? D061 est bloqué avec le statut corrupt et D062 avec password. Cinquième question : le fichier a-t-il la même empreinte SHA-256 qu’un fichier arrivé plus tôt? D059, une copie de D001, est bloqué avec le statut duplicate. Dernière question : le nom correspond-il au contenu? Pour 59 fichiers, oui : accepted. Pour D064, un JPEG nommé .pdf, non : wrong_extension, mais le fichier est accepté et lu comme un JPEG. Ainsi, 60 fichiers poursuivent leur chemin vers la lecture.

Lancer les vérifications sur les fichiers de Larkfield

Section intitulée « Lancer les vérifications sur les fichiers de Larkfield »

Lancez maintenant les vérifications sur tout le jeu, dans l’ordre d’arrivée des fichiers. intake affiche seulement les fichiers qui ne sont pas acceptés sans remarque, puis les totaux.

  1. Lancez les vérifications à la réception :

    Fenêtre de terminal
    python -m doc_extract.intake
    D059 receipt-lk-986875 (1).pdf duplicate the same bytes as receipt-lk-986875.pdf
    D061 receipt-download.pdf corrupt EOF marker not found
    D062 receipt-protected.pdf password the PDF needs a password to open
    D063 scan-raw.tif too_large 9.1 MB is over the limit of 8.0 MB
    D064 receipt-scan.pdf wrong_extension the name ends in .pdf, but the content is jpeg
    D065 notes.txt unsupported the content is not a PDF, image or spreadsheet (unknown)
    accepted 59, corrupt 1, duplicate 1, password 1, too_large 1, unsupported 1, wrong_extension 1

    Cinq fichiers sont bloqués et un poursuit son chemin avec une note. Les 65 fichiers ont pris environ 0,3 seconde au total.

  2. Ouvrez doc_extract/intake.py et trouvez check(). Lisez la fonction de haut en bas. Chaque return correspond à un statut de la liste ci-dessus, dans le même ordre.

  3. Essayez une limite beaucoup plus petite, 0,2 Mo, pour voir la vérification de taille en action :

    Fenêtre de terminal
    python -m doc_extract.intake --max-mb 0.2

    La dernière ligne montre que 17 fichiers sont maintenant trop volumineux :

    accepted 44, corrupt 1, duplicate 1, password 1, too_large 17, unsupported 1

    Ces 17 fichiers sont 14 numérisations, la demande de garantie (sa page 2 est numérisée), D063 et D064. Regardez une des lignes au-dessus des totaux : D020 scan0002.jpg too_large 0.2 MB is over the limit of 0.2 MB (D020, scan0002.jpg, trop volumineux : 0,2 Mo dépasse la limite de 0,2 Mo). Le fichier contient 224 481 octets, que le message arrondit à 0,2 Mo. La vérification compare les octets, donc elle est correcte; seul le message est court. Remarquez aussi que D064 est maintenant bloqué avec too_large, avant la vérification de son nom. Le premier problème l’emporte.

Sam demande : « Pourquoi un PDF corrompu est bloqué, mais pas un fichier avec un mauvais nom? » Mei répond : « Personne ne peut lire un fichier corrompu. On le retourne avec la raison, et l’agent demande au client d’envoyer le fichier à nouveau. Un fichier avec un mauvais nom peut se lire parfaitement, si on fait confiance à ses octets. Le refuser ne ferait qu’agacer le client. »

Amira pose la question suivante : que fait Larkfield d’un fichier bloqué? Dans ce cours, le statut et la raison sont retournés avec le billet, et le fichier n’entre pas dans le pipeline. Dans Intégration et maintenance, le pipeline complet conserve ces décisions avec les autres enregistrements du fichier.

Quasi-doublons : le même reçu, numérisé deux fois

Section intitulée « Quasi-doublons : le même reçu, numérisé deux fois »

Les copies exactes sont faciles à repérer. Mais D060, scan-again.jpg, est une deuxième numérisation du même reçu papier que D020. Le client l’a numérisé de nouveau parce que la première numérisation semblait inclinée. Les deux images montrent le même reçu, mais presque chaque pixel est un peu différent. Les octets sont donc différents, les empreintes de hachage aussi, et le traitement des entrées accepte les deux :

bcee48048deb959a629771227ac8e465673456e69a6252051d16d7f71ae8db46 scan0002.jpg
18942a38df8196d71e47929c4fae68c753c8dcd4aefc1ff3c856d6926ad3cdfd scan-again.jpg

C’est un quasi-doublon : deux fichiers au même contenu, mais aux octets différents. Un programme peut-il voir que deux images se ressemblent?

Imaginez comment vous compareriez deux photos de la même pièce vues de loin. Vous ne compareriez pas chaque détail. Vous regarderiez les grandes formes : sombre ici, clair là. Une empreinte d’image fait la même chose. L’empreinte du projet, intake.fingerprint, est un hachage par différences. Elle recadre la page autour de son contenu et la réduit à une petite image grise de 17 × 16 pixels. Elle compare ensuite chaque pixel à son voisin de droite : un pixel plus clair donne le bit 1. Un pixel plus sombre ou égal donne 0. Seize rangées de 16 comparaisons donnent 256 bits. Pour comparer deux empreintes, on compte les bits différents : 0 signifie « même apparence ».

Voici un petit exemple avec une rangée de cinq pixels gris (0 est noir, 255 est blanc). Ces valeurs sont inventées pour montrer la règle :

Pixel 1 2 3 4 5 Bits (chaque pixel comparé au suivant)
Première numérisation 200 180 180 90 240 1 0 1 0
Deuxième numérisation, un peu plus sombre 190 172 171 85 230 1 1 1 0

La deuxième numérisation est plus sombre partout, mais la plupart des comparaisons restent les mêmes. Elles comparent des voisins, pas des valeurs absolues. Seuls les pixels 2 et 3, auparavant égaux, diffèrent maintenant de 1, et leur bit change. Un bit sur quatre diffère. C’est pourquoi une empreinte résiste à une numérisation plus sombre ou à une copie plus petite.

Ce que les empreintes montrent sur les fichiers de Larkfield

Section intitulée « Ce que les empreintes montrent sur les fichiers de Larkfield »

Voici maintenant le résultat réel. intake --fingerprints affiche les 12 paires de pages les plus proches dans l’ensemble :

Fenêtre de terminal
python -m doc_extract.intake --fingerprints
0 of 256 bits differ: receipt-lk-986875.pdf / receipt-lk-986875 (1).pdf
1 of 256 bits differ: receipt-lk-139958.pdf / order-us-lk-159455.pdf
1 of 256 bits differ: receipt-lk-848917.pdf / receipt-lk-139958.pdf
2 of 256 bits differ: order-us-lk-159455.pdf / order-us-lk-517444.pdf
2 of 256 bits differ: receipt-lk-237469.pdf / receipt-lk-139958.pdf
2 of 256 bits differ: receipt-lk-848917.pdf / order-us-lk-159455.pdf
2 of 256 bits differ: receipt-lk-848917.pdf / order-us-lk-517444.pdf
3 of 256 bits differ: receipt-lk-139958.pdf / order-us-lk-517444.pdf
3 of 256 bits differ: receipt-lk-237469.pdf / order-us-lk-159455.pdf
3 of 256 bits differ: receipt-lk-237469.pdf / order-us-lk-517444.pdf
3 of 256 bits differ: receipt-lk-237469.pdf / receipt-lk-848917.pdf
6 of 256 bits differ: receipt-lk-246283.pdf / receipt-lk-946210.pdf

La première paire est la copie exacte : 0 bit. Mais toutes les autres paires sont deux reçus différents. receipt-lk-139958.pdf (D016) et order-us-lk-159455.pdf (D052) diffèrent de 1 bit sur 256. Ce sont deux commandes en ligne avec des clients, des articles et des totaux différents, même dans des devises différentes. Et la vraie deuxième numérisation, D060 comparée à D020, ne figure pas du tout dans la liste. Pour voir sa distance, démarrez Python dans le dossier du projet avec python, puis saisissez :

from doc_extract import documents, intake
a, b = documents.get("D020"), documents.get("D060")
print(intake.distance(intake.fingerprint(a.path, "jpeg"), intake.fingerprint(b.path, "jpeg")))
10

La deuxième numérisation du même reçu diffère de 10 bits. Des reçus différents ne sont séparés que par 1 bit. Dans l’ensemble complet, 18 paires de reçus différents sont plus proches que le vrai quasi-doublon.

Deux rangées. Rangée du haut : D016 et D052, deux commandes en ligne différentes de Larkfield avec le même en-tête vert. Entre elles, leurs copies grises de 17 sur 16 pixels se ressemblent presque parfaitement. La grille de 256 bits contient un carré rouge : 1 bit sur 256 diffère. Rangée du bas : D020 et D060, la même confirmation de commande numérisée deux fois. Leurs copies grises se ressemblent aussi presque parfaitement. La grille contient 10 carrés rouges : 10 bits sur 256 diffèrent.
Ce que voit l'empreinte. En haut : deux reçus différents sur le même gabarit, séparés par 1 bit. En bas : un reçu numérisé deux fois, séparé par 10 bits. Les copies grises masquent toutes les valeurs; seul le gabarit reste.
Description textuelle du diagramme

L’image comporte deux rangées. Chaque rangée montre deux pages, leurs petites copies grises de 17 × 16 pixels et une grille entre elles. Cette grille contient 256 carrés, un par bit. Un carré rouge représente un bit différent. Dans la rangée du haut, D016 et D052 sont deux commandes en ligne différentes de Larkfield. Elles ont le même en-tête vert, les mêmes colonnes et des valeurs différentes. Leurs copies grises semblent presque identiques, et seulement 1 carré sur 256 est rouge. Dans la rangée du bas, D020 et D060 sont la même confirmation de commande, numérisée deux fois. Leurs copies grises se ressemblent aussi, et 10 carrés sont rouges. À 17 × 16 pixels, les nombres, les noms et les dates disparaissent. Il reste le gabarit : la barre d’en-tête, les colonnes, les espaces blancs. Les reçus créés à partir du même gabarit se ressemblent.

L’image montre pourquoi. À 17 × 16 pixels, aucun nombre, nom ou total ne reste. Seul le gabarit reste : la barre d’en-tête, le tableau, l’espace blanc au bas. Larkfield imprime chaque commande en ligne avec le même gabarit, donc des reçus différents se ressemblent. Une deuxième numérisation, légèrement inclinée et plus sombre, ressemble moins à la première que deux reçus différents entre eux.

Un seuil ne peut donc pas fonctionner. Fixez-le à 10 bits pour repérer D060, et 18 paires de reçus différents sont signalées comme doublons. Un agent refuserait alors des remboursements légitimes. Fixez-le plus bas, et D060 passe quand même.

La décision : comparer le contenu, après l’extraction

Section intitulée « La décision : comparer le contenu, après l’extraction »

Le cours sépare donc le travail. Le traitement des entrées bloque seulement les copies exactes grâce à leur empreinte SHA-256. Ce test coûte peu et ne se trompe jamais. Les quasi-doublons sont repérés plus tard, par leur contenu, une fois les valeurs lues. On cherche le même numéro de commande, ou le même magasin, la même date et le même total. Cette vérification se trouve dans Validation selon les règles d’affaires. Le pipeline complet y signale D060 comme doublon possible de D020, et une personne décide. L’empreinte reste dans le projet uniquement pour montrer ce résultat : --fingerprints est un outil d’observation, pas une règle.

Vérifiez toujours chaque fichier à l’entrée. Les vérifications coûtent peu : environ 0,3 seconde pour les 65 fichiers sur l’ordinateur du cours. Seule la vérification d’ouverture effectue un travail important. Elle produit une image de la première page au dixième de sa taille. Le calcul des empreintes a pris environ 0,5 seconde.

Choisissez la limite de taille selon ce que les étapes suivantes peuvent traiter, pas au hasard. La limite du cours, 8 Mo, laisse passer toutes les numérisations et photos normales. Le plus gros fichier accepté fait 0,6 Mo. Seul D063, un TIFF non compressé de 9,1 Mo, est bloqué. Une limite de 0,2 Mo refuserait 15 reçus valides et la demande de garantie. Les agents demanderaient donc aux clients des fichiers déjà envoyés. Si vos fichiers diffèrent, modifiez la limite dans .env avec MAX_FILE_MB.

Ces vérifications ont certaines limites. Elles ne peuvent pas déterminer si une image est lisible : D046, une photo floue, s’ouvre sans erreur et passe. Les prochaines leçons se chargent de la lecture, et Gérer l’incertitude visuelle traite les pages illisibles. Elles ne peuvent pas repérer les quasi-doublons, comme vous l’avez vu. Et ici, le registre des empreintes reste en mémoire pour une seule exécution. Un vrai système conserve les empreintes dans sa base de données pour repérer une copie qui arrive la semaine suivante.

Erreur courante

Faire confiance au nom du fichier

Symptôme : Un lot de pièces jointes s’arrête à mi-chemin avec PdfiumError: Failed to load document (PDFium: Data format error). (échec du chargement du document : erreur de format des données). Le fichier s’appelle receipt-scan.pdf, donc le code l’a envoyé au moteur de rendu PDF.

Cause : Le nom était incorrect. Le fichier est un JPEG : ses premiers octets sont ff d8 ff, pas %PDF-. Les téléphones, les logiciels de courriel et les clients renomment les fichiers. Un nom n’est qu’une étiquette que n’importe qui peut changer. Le code qui décide selon l’extension envoie le fichier au mauvais lecteur.

Diagnostic : Regardez les premiers octets. python -m doc_extract.route D064 affiche le vrai format et indique ce que le nom prétend :

D064 receipt-scan.pdf: format jpeg <- the name says .pdf, 1 page(s), kind scan
page 1: route ocr (a scanned image (white page); pictures cover 100%)

Correction : Déterminez le format selon le contenu partout, pas seulement à l’entrée. Dans le projet, route.sniff lit le nombre magique. De son côté, files.is_pdf lit les cinq premiers octets avant de produire une image de la page. Un nom incorrect devient une note (wrong_extension, extension incorrecte), et le fichier est lu selon son vrai format.

Conséquence pour le travail en IA : un pipeline qui fait confiance aux noms échoue sur des fichiers réels. Il est difficile à déboguer, car l’erreur vient d’une bibliothèque interne, loin de la cause. Pire encore, un lecteur qui ne plante pas peut lire des données incohérentes et les transmettre comme du texte.

Changez une condition : l’ordre d’arrivée de deux fichiers. Supposons que le deuxième message du client, avec receipt-lk-986875 (1).pdf (D059), arrive chez Larkfield avant le premier (D001). Prédisez la décision du traitement des entrées pour chaque fichier. Vérifiez ensuite dans Python (démarrez python dans le dossier du projet) :

from doc_extract import documents, intake
registry = intake.Registry()
for doc_id in ("D059", "D001"):
r = intake.check(documents.get(doc_id).path, registry)
print(doc_id, r.status, r.reason)
Afficher la réponse
D059 accepted
D001 duplicate the same bytes as receipt-lk-986875 (1).pdf

La première copie arrivée est acceptée, quel que soit son nom, et la deuxième est le doublon. Les octets sont identiques, donc le programme ne peut pas savoir laquelle est « l’original ». Il n’en a pas besoin : les deux sont le même reçu. C’est pourquoi le registre garde le nom de la première copie (same_as, identique à). Un agent qui voit « doublon » peut retrouver le fichier conservé. Le test du projet test_the_first_copy_wins_the_order_matters vérifie ce cas.

Vérifiez votre compréhension

Mettez les vérifications des entrées en ordre et expliquez pourquoi elles vont de la moins coûteuse à la plus coûteuse. Quelle vérification est la seule à laisser passer un fichier, et pourquoi?

Afficher la réponse

L’ordre est : taille, fichier vide, format selon les premiers octets, ouverture (corruption ou mot de passe), doublon exact par SHA-256, puis nom. Les premières vérifications lisent seulement la taille du fichier ou ses premiers octets. Un mauvais fichier est donc bloqué à un coût presque nul. L’ouverture du fichier est la vérification la plus coûteuse. Elle s’exécute donc seulement sur les fichiers qui ont réussi les autres. La vérification du nom est la seule à laisser passer le fichier. Un fichier avec wrong_extension a un contenu valide, donc le projet le lit selon son vrai format. Un nom incorrect est une note, pas une raison de refuser un reçu.

Vérifiez votre compréhension

Prédisez et expliquez : Tomás propose de bloquer les quasi-doublons à l'entrée avec l'empreinte d'image, à 10 bits ou moins. Que se passe-t-il avec les fichiers de Larkfield?

Afficher la réponse

D060, la deuxième numérisation de D020, est à 10 bits de distance, donc il serait bloqué. Mais 18 paires de reçus différents sont plus proches; D016 et D052 ne sont séparés que par 1 bit. À 17 × 16 pixels gris, les valeurs disparaissent et seul le gabarit reste. Larkfield imprime ses reçus à partir de quelques gabarits. La règle refuserait donc des reçus légitimes comme « doublons ». Le cours compare plutôt le contenu, après l’extraction : le même numéro de commande, ou le même magasin, date et total.

Vérifiez votre compréhension

Vérification pratique : exécutez les vérifications des entrées avec une limite de taille de 0,6 Mo. Quels fichiers sont trop gros, et lesquels ne voudriez-vous pas refuser?

Afficher la réponse

Exécutez python -m doc_extract.intake --max-mb 0.6. Deux fichiers sont trop gros : D063 (scan-raw.tif, 9,1 Mo) et D019 (scan0001.pdf, 639 633 octets). Le message arrondit la taille de D019 : « 0,6 Mo dépasse la limite de 0,6 Mo ». D063 est le TIFF non compressé que le cours bloque volontairement. D019 est un reçu numérisé normal : le refuser obligerait l’agent à recontacter le client sans raison. Une limite doit dépendre de ce que les étapes suivantes peuvent traiter, et elle doit laisser passer les fichiers normaux. La valeur par défaut, 8 Mo, le permet.

Récapitulatif

  • Traitement des entrées vérifie chaque fichier avant qu’un lecteur l’ouvre, de la vérification la moins coûteuse à la plus coûteuse. Les vérifications sont : taille, fichier vide, format selon les premiers octets, ouverture (corruption, mot de passe), doublon exact et nom. Le premier problème bloque le fichier avec un état et une raison qu’une personne peut lire.
  • Sur les 65 fichiers de Larkfield, 5 sont bloqués (D059 doublon, D061 corrompu, D062 mot de passe, D063 trop gros, D065 non pris en charge). D064, un JPEG nommé .pdf, est accepté et lu comme un JPEG. 60 fichiers poursuivent le traitement.
  • Déterminez le format selon le contenu, jamais selon le nom. Un nom incorrect a déjà fait planter le moteur de rendu du projet.
  • SHA-256 repère les copies exactes à un coût presque nul. Les quasi-doublons ont des octets différents. Une empreinte d’image place D060 à 10 bits de D020, mais 18 paires de reçus différents sont plus proches. Le cours repère donc les quasi-doublons par leur contenu, après l’extraction.

Ensuite, vous extrayez le texte des fichiers acceptés de trois façons, puis vous les comparez sur les mêmes pages.

Leçon suivante : Chemins texte et OCR