Aller au contenu
English

Gérer l'incertitude visuelle

  • Leçon 13
  • 50 min
  • Module 4 : Utiliser les modèles multimodaux de façon réfléchie

Où nous en sommes

Dans la dernière leçon, nous avons combiné les règles et le modèle, et 53 reçus sur 54 sont sortis complets. Mais certaines images ne peuvent être entièrement lues par personne : floues, coupées, trop petites, ou avec des pages qui se contredisent. L'opinion du modèle sur lui-même ne nous dit pas quand cela arrive. Dans cette leçon, nous mesurons ce qu'une image ne nous permet pas de savoir, et nous signalons explicitement chaque lacune, comme un bon témoin.

Ce que vous saurez faire

Déterminez ce qu’une image ne permet pas au pipeline de savoir, avec des mesures indépendantes de l’opinion du modèle sur lui-même. Puis signalez explicitement chaque valeur indisponible : absente, avec la raison, jamais une supposition plausible.

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 à la fin de la leçon précédente : python -m pytest -q affiche 81 passed (81 tests réussis).
  • Le dépôt des exercices dans ~/projects/nextia-learning-labs, à jour.

Testé avec Python 3.12.13, RapidOCR 3.10.0 et Pillow 12.3.0 sur macOS (Apple silicon). Les commandes Windows et Linux ne sont pas testées. Le générateur du cours produit volontairement les photos endommagées et les images réduites.

  1. Dans le dossier du projet, copiez le module et son test depuis l’instantané :

    Fenêtre de terminal
    S=../nextia-learning-labs/C13/snapshots/end-of-m04
    cp $S/doc_extract/uncertainty.py doc_extract/
    cp $S/tests/test_uncertainty.py tests/
  2. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q

    La dernière ligne est 84 passed (84 tests réussis). C’est le nombre de tests de l’instantané end-of-m04.

Imaginez un témoin d’un accident de voiture la nuit. Un bon témoin dit : « La voiture était bleue. Je n’ai pas pu lire la plaque : elle était trop loin. » Un mauvais témoin donne un numéro de plaque plausible, parce que l’agent de police en veut un. Les deux semblent sûrs d’eux. Un seul est utile.

Un agent prudent ne demande pas seulement au témoin à quel point il est sûr. Il vérifie aussi les conditions : il faisait noir, le témoin se trouvait à 50 mètres. Ces faits ne dépendent pas de l’opinion du témoin sur lui-même. Et l’agent écrit « plaque : non vue, trop loin » dans le rapport. Il ne laisse pas la case vide et ne la remplit pas avec une supposition.

Une image de reçu a aussi ses conditions : flou, bord coupé, petite taille. Cette leçon les mesure et inscrit « non vu, avec la raison » dans l’enregistrement.

Le problème : des images qui donnent une fausse impression

Section intitulée « Le problème : des images qui donnent une fausse impression »

Quatre images du jeu du cours ne peuvent pas être lues entièrement. L’image ci-dessous les montre, avec les mesures de l’OCR et les réponses du modèle :

Quatre cartes. D046, photo floue : un reçu sombre et très flou; l'OCR a trouvé 0 caractère, score 0,00; le modèle : tous les champs illisibles. D047, haut coupé : le bord supérieur de la photo coupe le nom du magasin. Seule la partie du reçu à partir de la ligne de commande apparaît; l'OCR a trouvé 255 caractères, score 0,99; le modèle : fournisseur et date not_printed (non imprimés), confiance 0,99, en rouge. D045, bas coupé : la photo s'arrête à la ligne de taxe; l'OCR a trouvé 266 caractères, score 0,99; le modèle : total et paiement cut_off (coupés). D022 au quart de sa taille, 212 x 275 pixels : la partie du reçu, agrandie six fois, montre des rangées de taches grises sans lettre lisible; l'OCR a trouvé 32 caractères, score 0,60; le modèle : la page est illisible.
Quatre images que le pipeline ne peut pas lire entièrement, avec les mesures OCR et la réponse du modèle. Une seule réponse se trompe sur ses propres limites : le haut de D047 est coupé, mais le modèle dit que le magasin et la date ne sont pas imprimés.
Description textuelle du diagramme

La première carte est D046, une photo sombre et très floue. L’OCR n’a trouvé aucun caractère, et le modèle a déclaré tous les champs illisibles. La deuxième est D047, une photo dont le bord supérieur coupe le nom du magasin. L’OCR a lu 255 caractères avec un score moyen de 0,99. Le modèle a déclaré le fournisseur et la date non imprimés, avec une confiance de 0,99. La troisième est D045, dont le bas s’arrête à la ligne de taxe. L’OCR a lu 266 caractères avec un score de 0,99. Le modèle a déclaré le total et le paiement coupés. La quatrième est le document numérisé D022, réduit au quart de sa taille : 212 par 275 pixels. La partie du reçu est agrandie pour que vous puissiez voir ses pixels. L’OCR a lu 32 caractères avec un score moyen de 0,60, et le modèle a déclaré la page illisible.

Lisez les mots du modèle pour les trois photos endommagées, à côté des champs réellement coupés par le générateur. Lancez python dans le dossier du projet et saisissez :

from doc_extract import documents, vision
for doc in ("D045", "D046", "D047"):
d = documents.get(doc)
ex = vision.read(d.file)
gone = [f"{n} {f.reason} ({f.confidence})" for n, f in ex.fields.items() if f.value is None and n != "shipping"]
print(doc, "| cut off:", d.truth.get("printed_but_cut_off", "-"), "| model absent:", ", ".join(gone))
D045 | cut off: ['total', 'payment_method'] | model absent: tax cut_off (0.96), total cut_off (0.99), payment_method cut_off (0.98)
D046 | cut off: - | model absent: vendor unreadable (1.0), order_number unreadable (1.0), date unreadable (1.0), currency unreadable (1.0), subtotal unreadable (1.0), tax unreadable (1.0), total unreadable (1.0), payment_method unreadable (1.0)
D047 | cut off: ['vendor', 'date'] | model absent: vendor not_printed (0.99), date not_printed (0.99)

Deux réponses sont honnêtes. Pour D045, le modèle indique cut_off (coupé) pour le total et le paiement. Il indique aussi cut_off pour la taxe, à moitié visible au bord; les règles la lisent. Pour D046, il indique unreadable (illisible) partout. Mais pour D047, il indique not_printed (non imprimé) pour le fournisseur et la date, avec une confiance de 0,99. C’est faux : chaque reçu Larkfield affiche son magasin et sa date. Ils étaient sur le papier, au-delà du bord de la photo. Un agent qui lit « non imprimé » pense que le reçu est étrange, pas que la photo est mauvaise. Il ne demande donc pas de nouvelle photo.

Les images réduites montrent un deuxième problème. Le cours a réduit six images de reçus à la moitié et au quart de leur taille. Il les a ensuite relues avec l’OCR et le modèle. Listez les réponses incorrectes du modèle au quart de la taille. Dans python :

from doc_extract import compare, documents, vision
for doc in ("D020", "D022", "D036", "D038", "D040", "D044"):
d = documents.get(doc)
ex = vision.read(d.file, variant="quarter")
for n, true in d.fields.items():
f = ex.fields[n]
if true is not None and not compare.correct(n, f.value, true):
print(f"{doc} {n:<13} model: {f.value} ({f.status} {f.reason}, confidence {f.confidence}) | true: {true}")
D020 date model: 2026-06-26 (found , confidence 0.96) | true: 2026-06-25
D022 vendor model: None (absent unreadable, confidence 0) | true: Larkfield
D022 order_number model: None (absent unreadable, confidence 0) | true: LK-850924
D022 date model: None (absent unreadable, confidence 0) | true: 2026-09-02
D022 currency model: None (absent unreadable, confidence 0) | true: CAD
D022 subtotal model: None (absent unreadable, confidence 0) | true: 162.00
D022 tax model: None (absent unreadable, confidence 0) | true: 21.06
D022 total model: None (absent unreadable, confidence 0) | true: 183.06
D022 payment_method model: None (absent unreadable, confidence 0) | true: Cash
D038 tax model: None (absent unreadable, confidence 0.85) | true: 8.44
D040 order_number model: LK-787043 (found , confidence 0.96) | true: LK-787943
D044 order_number model: None (absent unreadable, confidence 0.7) | true: LK-395245
D044 subtotal model: 352.95 (found , confidence 0.88) | true: 371.95
D044 shipping model: 19.00 (found , confidence 0.8) | true: 0.00
D044 tax model: 55.60 (found , confidence 0.8) | true: 55.70
D044 total model: 427.55 (found , confidence 0.95) | true: 427.65

Pour D022, le modèle indique unreadable pour chaque champ : la réponse honnête. Sur les autres images, il inscrit six valeurs fausses comme found (trouvées). La date de D020 est décalée d’un jour, et le numéro de commande de D040 contient un chiffre erroné. Sur D044, quatre montants sont faux, mais leur somme reste cohérente : 352,95 + 19,00 + 55,60 = 427,55. Une vérification de la somme réussirait. Le modèle ne sait pas toujours reconnaître qu’une image est trop petite pour lui.

L’idée : mesurer les conditions, signaler explicitement les manques

Section intitulée « L’idée : mesurer les conditions, signaler explicitement les manques »

Le jugement du modèle sur lui-même ne suffit pas. Il a indiqué « non imprimé » pour un haut coupé et marqué des lectures erronées comme trouvées. Le pipeline mesure donc lui-même les conditions de chaque page. Ce sont des signaux d’incertitude visuelle : des faits sur l’image et les réponses qui indiquent qu’une valeur pourrait être impossible à connaître. uncertainty.py les calcule à partir des lignes OCR que le pipeline possède déjà :

  • unreadable (illisible) : l’OCR a trouvé moins de 40 caractères sur la page, ou le score moyen des lignes est inférieur à 0,75.
  • low_resolution (faible résolution) : le texte est petit. La hauteur médiane des lignes OCR est inférieure à 14 pixels.
  • conflict (conflit) : deux pages du même fichier montrent des valeurs différentes pour le numéro de commande, la date ou le total.
  • unverified (non vérifié) : le modèle a donné une valeur introuvable sur la page (voir la leçon précédente).
  • absent, avec une raison : un champ est absent parce qu’il est cut_off ou unreadable. La raison vient du modèle, et combine.py la conserve.
  • une raison que le contrat n’autorise pas : un champ est absent pour une raison que le contrat interdit pour ce champ. Le fournisseur peut manquer seulement pour la raison unreadable; la date, seulement pour cut_off ou unreadable. Un reçu imprime toujours les deux.

La deuxième partie de l’idée concerne l’enregistrement. Une valeur indisponible reste explicite : value (valeur) vaut null, status (statut) vaut absent, et reason (raison) indique pourquoi. Une case vide cache la différence entre « absent du reçu » et « perdu dans la photo ». Une supposition cache le fait qu’il manque quelque chose.

Un petit exemple : quatre lignes d’une petite image

Section intitulée « Un petit exemple : quatre lignes d’une petite image »

Donnez à page_signals quatre lignes OCR, comme l’OCR pourrait lire le bas d’une petite image floue. Chaque valeur est visible : le texte, la boîte et le score. Dans python :

from doc_extract import uncertainty
from doc_extract.pages import Line, Page
lines = [Line("TOTAL", (40, 300, 120, 312), 0.62), Line("4O5.6l", (300, 300, 380, 312), 0.48),
Line("Cash", (40, 330, 90, 342), 0.71), Line("Thank you", (40, 360, 160, 372), 0.80)]
s = uncertainty.page_signals([Page("small.jpg", 1, 300, 400, "px", "ocr", lines)])
print("characters", s.chars, "| mean score", s.mean_score, "| text height", s.text_px, "px")
print(s.flags)
characters 24 | mean score 0.652 | text height 12.0 px
['unreadable: 24 characters found, mean score 0.65']

Suivez le calcul à la main. Les caractères : 5 + 6 + 4 + 9 = 24, moins de 40. Le score moyen : (0,62 + 0,48 + 0,71 + 0,80) / 4 = 2,61 / 4 = 0,6525, moins de 0,75. Chaque boîte mesure 12 pixels de haut, donc le texte est petit aussi. La page reçoit le signal unreadable, le plus fort. Le projet rapporte un seul signal de page, pas les deux. Remarquez la ligne 4O5.6l : l’OCR a lu une lettre O et une lettre l. Les règles ne peuvent pas en extraire un montant, donc aucun total n’est inventé à partir de cette ligne.

  1. La photo floue :

    Fenêtre de terminal
    python -m doc_extract.uncertainty D046
    D046 IMG_4887.jpg: 0 characters, mean score 0.0, text about 0.0 px high
    unreadable: 0 characters found, mean score 0.00
    vendor: absent (unreadable)
    order_number: absent (unreadable)
    date: absent (unreadable)
    currency: absent (unreadable)
    subtotal: absent (unreadable)
    shipping: absent (unreadable)
    tax: absent (unreadable)
    total: absent (unreadable)
    payment_method: absent (unreadable)
    vendor (unreadable) absent
    order_number (unreadable) absent
    date (unreadable) absent
    currency (unreadable) absent
    subtotal (unreadable) absent
    shipping (unreadable) absent
    tax (unreadable) absent
    total (unreadable) absent
    payment_method (unreadable) absent

    La page est illisible : l’OCR n’a rien trouvé. Chaque champ est absent et conserve la raison du modèle, unreadable. Un agent sait immédiatement quoi faire : demander une nouvelle photo au client.

  2. La photo coupée en bas :

    Fenêtre de terminal
    python -m doc_extract.uncertainty D045
    D045 IMG_4880.jpg: 266 characters, mean score 0.99, text about 44.0 px high
    currency: unverified: the model's value cannot be found on the page
    total: absent (cut_off)
    payment_method: absent (cut_off)
    vendor Larkfield found
    order_number LK-754892 found
    date 2026-06-13 found
    currency CAD unverified
    subtotal 358.95 found
    shipping (not_printed) absent
    tax 46.66 found
    total (cut_off) absent
    payment_method (cut_off) absent

    La page se lit bien : 266 caractères, score 0,99, texte d’environ 44 pixels de haut. Les signaux concernent les champs. La devise n’est pas vérifiée, comme dans la leçon précédente. Le total et le paiement sont absents parce qu’ils sont coupés. Les frais de livraison sont absents avec la raison not_printed, ce qui est normal pour un reçu de caisse. Cela ne produit donc aucun signal.

  3. La photo coupée en haut :

    Fenêtre de terminal
    python -m doc_extract.uncertainty D047
    D047 IMG_4894.jpg: 255 characters, mean score 0.991, text about 47.5 px high
    vendor: absent (not_printed), but the contract allows only: unreadable
    date: absent (not_printed), but the contract allows only: cut_off, unreadable
    vendor (not_printed) absent
    order_number LK-192531 found
    date (not_printed) absent
    currency CAD found
    subtotal 187.00 found
    shipping (not_printed) absent
    tax 24.31 found
    total 211.31 found
    payment_method Visa found

    La page se lit bien aussi, et le modèle a indiqué « non imprimé ». Mais le contrat autorise seulement unreadable pour le fournisseur, et seulement cut_off ou unreadable pour la date. Le projet signale donc les deux. Le contrat détecte ce que la confiance du modèle cachait. La raison honnête pour les deux est cut_off. Pour le fournisseur, la règle du contrat est trop stricte quand le haut est coupé. Un meilleur contrat autoriserait aussi cut_off. C’est une amélioration que vous pouvez faire; le cours conserve la règle.

  4. Un document numérisé à faible résolution :

    Fenêtre de terminal
    python -m doc_extract.uncertainty D024
    D024 scan0006.jpg: 306 characters, mean score 0.961, text about 13.5 px high
    low_resolution: text is about 14 pixels high
    vendor Larkfield found
    order_number LK-103850 found
    date 2026-09-09 found
    currency CAD found
    subtotal 89.00 found
    shipping (not_found) absent
    tax 11.57 found
    total 100.57 found
    payment_method Debit found

    D024 est numérisé à 75 points par pouce. Son texte mesure environ 13,5 pixels de haut, juste sous la limite de 14; il est donc signalé. Pourtant, chaque valeur est correcte. (not_found (non trouvé) est la raison donnée par les règles lorsqu’aucune ligne ne correspond aux frais de livraison. Comme dans Représenter la provenance, le document numérisé n’affiche aucune ligne de livraison.) Un signal dit « regardez ici », pas « c’est faux ». Le prochain module décide de ce qui est envoyé à une personne.

Exécutez python -m doc_extract.uncertainty --all pour voir tous les reçus dans un seul tableau. Seulement quatre des 54 lignes ont un signal :

D024 scan_image 0.961 low_resolution: text is about 14 pixels high
D045 photo 0.99 currency: unverified: the model's value cannot be found on the page; total: absent (cut_off); payment_method:
D046 photo 0.0 unreadable: 0 characters found, mean score 0.00; vendor: absent (unreadable); order_number: absent (unreadable
D047 photo 0.991 vendor: absent (not_printed), but the contract allows only: unreadable; date: absent (not_printed), but the co

Revenons aux six reçus à leur taille originale, à la moitié et au quart. Le script ci-dessous crée les copies réduites dans out/small/, comme le cours l’a fait. Puis il lit chaque image avec l’OCR, sans préparation et avec préparation. Il reprend aussi la réponse enregistrée du modèle pour cette taille. Enregistrez-le sous small_pictures.py dans le dossier du projet :

from pathlib import Path
from PIL import Image
from doc_extract import compare, documents, fields, ocr, uncertainty, vision
DOCS = ["D020", "D022", "D036", "D038", "D040", "D044"]
for size, scale in (("full", 1), ("half", 0.5), ("quarter", 0.25)):
right = {"raw": 0, "prepared": 0, "model": 0}
printed = 0
for doc in DOCS:
d = documents.get(doc)
path = d.path
if scale < 1: # a smaller copy, made as the course made it
path = Path("out/small") / size / d.file
path.parent.mkdir(parents=True, exist_ok=True)
with Image.open(d.path) as img:
small = img.convert("RGB").resize((round(img.width * scale), round(img.height * scale)), Image.LANCZOS)
small.save(path, "JPEG", quality=85)
want = {n: v for n, v in d.fields.items() if v is not None}
printed += len(want)
line = f"{size:<8}{doc}"
for kind in ("raw", "prepared"):
pages = ocr.read(path, prepare=(kind == "prepared"))
ex = fields.extract(pages, "ocr")
k = sum(compare.correct(n, ex.value(n), v) for n, v in want.items())
right[kind] += k
line += f" {kind} {k}/{len(want)}"
if kind == "raw":
s = uncertainty.page_signals(pages)
model = vision.read(d.file, 1, variant="" if scale == 1 else size)
k = sum(compare.correct(n, model.value(n), v) for n, v in want.items())
right["model"] += k
print(f"{line} model {k}/{len(want)} | text {s.text_px} px, score {s.mean_score} | {'; '.join(s.flags) or 'no signal'}")
print(f"{size:<8}all: raw {right['raw']}/{printed}, prepared {right['prepared']}/{printed}, model {right['model']}/{printed}")

Exécutez-le. La première exécution lit 30 images avec l’OCR; elle prend donc environ 20 secondes :

Fenêtre de terminal
python small_pictures.py
full D020 raw 9/9 prepared 9/9 model 9/9 | text 34.8 px, score 0.997 | no signal
full D022 raw 8/8 prepared 8/8 model 8/8 | text 21.0 px, score 0.989 | no signal
full D036 raw 8/8 prepared 8/8 model 8/8 | text 55.6 px, score 0.986 | no signal
full D038 raw 9/9 prepared 9/9 model 9/9 | text 31.2 px, score 0.995 | no signal
full D040 raw 8/8 prepared 8/8 model 8/8 | text 82.5 px, score 0.991 | no signal
full D044 raw 9/9 prepared 9/9 model 9/9 | text 33.7 px, score 0.989 | no signal
full all: raw 51/51, prepared 51/51, model 51/51
half D020 raw 9/9 prepared 9/9 model 9/9 | text 19.0 px, score 0.996 | no signal
half D022 raw 7/8 prepared 7/8 model 8/8 | text 11.0 px, score 0.928 | low_resolution: text is about 11 pixels high
half D036 raw 8/8 prepared 8/8 model 8/8 | text 29.0 px, score 0.99 | no signal
half D038 raw 9/9 prepared 9/9 model 9/9 | text 17.0 px, score 0.975 | no signal
half D040 raw 8/8 prepared 8/8 model 8/8 | text 43.0 px, score 0.992 | no signal
half D044 raw 9/9 prepared 8/9 model 9/9 | text 18.0 px, score 0.964 | no signal
half all: raw 50/51, prepared 49/51, model 51/51
quarter D020 raw 7/9 prepared 4/9 model 8/9 | text 9.0 px, score 0.949 | low_resolution: text is about 9 pixels high
quarter D022 raw 0/8 prepared 0/8 model 0/8 | text 6.0 px, score 0.595 | unreadable: 32 characters found, mean score 0.60
quarter D036 raw 8/8 prepared 7/8 model 8/8 | text 15.5 px, score 0.965 | no signal
quarter D038 raw 3/9 prepared 2/9 model 8/9 | text 9.0 px, score 0.716 | unreadable: 121 characters found, mean score 0.72
quarter D040 raw 8/8 prepared 8/8 model 7/8 | text 22.5 px, score 0.98 | no signal
quarter D044 raw 3/9 prepared 2/9 model 4/9 | text 9.0 px, score 0.665 | unreadable: 210 characters found, mean score 0.67
quarter all: raw 29/51, prepared 23/51, model 35/51
  • OCR sur l'image sans préparation
  • OCR sur l'image préparée
  • Le modèle, requête v2
Valeurs imprimées lues correctement sur six reçus à leur taille originale, à la moitié et au quart (51 valeurs). À la moitié, tout reste lisible; au quart, chaque méthode de lecture échoue, et la préparation dégrade l'OCR.
Description textuelle du graphique

Valeurs imprimées lues correctement, sur 51. Taille originale, par exemple 1 200 par 1 600 pixels : OCR sans préparation 100 %, OCR avec préparation 100 %, modèle 100 %. Moitié, 600 par 800 : OCR sans préparation 98 %, avec préparation 96 %, modèle 100 %. Quart, 300 par 400 : OCR sans préparation 57 %, avec préparation 45 %, modèle 69 %.

À la moitié, le texte mesure encore environ 11 à 43 pixels de haut, et presque chaque valeur est correcte. Au quart, chaque méthode de lecture échoue. La préparation dégrade l’OCR au lieu de l’améliorer. Agrandir une image minuscule ne peut pas ajouter les détails absents. Le modèle réussit le mieux, mais il inscrit six de ses erreurs comme found.

Lisez maintenant les signaux dans la sortie. Au quart, quatre des six images reçoivent le signal unreadable ou low_resolution. D044, l’image aux quatre montants faux dont la somme est cohérente, reçoit le signal unreadable (score 0,67). D040 n’est pas signalé : son texte mesure 22,5 pixels de haut et son score est de 0,98. Pourtant, le modèle a mal lu un chiffre de son numéro de commande, tandis que l’OCR a lu correctement les huit valeurs. Voilà pourquoi le pipeline lit d’abord avec les règles : ici, le modèle n’est pas appelé du tout.

Un fichier de deux pages peut dire deux choses différentes. La demande de garantie D058 contient un formulaire à la page 1 et le reçu à la page 2. Les deux affichent un numéro de commande. uncertainty.conflicts compare le numéro de commande, la date et le total entre les pages. Exécutez-le sur la vraie demande. Puis exécutez-le sur une copie où deux chiffres de la page 1 sont inversés. C’est un cas construit, comme si le client avait mal saisi le numéro de commande. Dans python :

import copy
from doc_extract import combine, documents, fields, uncertainty
pages = combine.read_pages(documents.get("D058"))
for p in pages:
print("page", p.page, p.path, "order", fields.extract([p], "rules").value("order_number"))
print("real:", uncertainty.conflicts(pages))
typo = copy.deepcopy(pages) # constructed: two digits swapped on the form
for ln in typo[0].lines:
ln.text = ln.text.replace("LK-921048", "LK-921084")
print("constructed:", uncertainty.conflicts(typo))
page 1 text order LK-921048
page 2 ocr order LK-921048
real: []
constructed: ['conflict: order_number differs between pages: page 1 LK-921084, page 2 LK-921048']

Sur la vraie demande, le formulaire et le reçu concordent. Sur la copie construite, le projet nomme le champ et les deux valeurs avec leurs pages. Il n’en choisit aucune. La caisse imprime le reçu, donc il est probablement correct, mais « probablement » relève de la décision d’une personne.

  • Calculez-les toujours. Ils ne coûtent presque rien : ils comptent les caractères, les scores et les hauteurs des lignes OCR déjà lues par le pipeline.
  • Lisez-les comme des raisons de vérifier, pas comme des verdicts. D024 est signalé et correct. D040 au quart n’est pas signalé, et le modèle l’a mal lu. Les seuils (40 caractères, score de 0,75, 14 pixels) ont été choisis sur les images de ce cours. Vérifiez-les sur vos propres documents.
  • Conservez la raison avec chaque valeur absente. cut_off demande une nouvelle photo. unreadable en demande une plus nette. not_printed ne demande rien. Le contrat indique les raisons permises pour chaque champ.
  • Ne vous fiez pas au jugement d’une méthode de lecture sur elle-même. Le modèle a déclaré un haut coupé « non imprimé » avec une confiance de 0,99. Il a inscrit des lectures erronées comme trouvées avec une confiance de 0,80 à 0,96. Confiance et acheminement vers la révision mesure cela sur toutes ses réponses.

Erreur courante

Un total qui semble correct

Symptôme : Un développeur voit que D045 n’a pas de total et ajoute une ligne de code : « si le total manque, utiliser sous-total + taxe ». D045 affiche maintenant total 405.61. L’enregistrement semble complet, et aucune révision n’est nécessaire.

Cause : Le total a été calculé, pas lu. 358,95 + 46,66 = 405,61, et rien sur la photo ne le montre. Le cours a affiché les lignes du reçu papier D045 à partir de la vérité du générateur. Les six dernières sont au-delà du bord de la photo :

LARKFIELD
Home & Garden
88 Queen St W
Toronto ON M5H 2M5
------------------------------------
Date: 2026-06-13 10:31
Order: LK-754892
Transaction: 0522-205
Till 03
------------------------------------
Watering can
1 x 19.95 19.95
Cushion covers (set of 4)
1 x 36.00 36.00
Wooden garden bench
1 x 249.00 249.00
Garden chair
1 x 54.00 54.00
------------------------------------
Subtotal 358.95
HST 13% 46.66
TOTAL CAD 405.61
------------------------------------
Cash 405.61
Thank you! Keep this receipt
for returns and warranty.
Made-up document for a course. Not a real receipt.

Cette fois, la valeur calculée correspond à celle imprimée : TOTAL CAD 405.61. Mais le pipeline ne pouvait pas le savoir. Au-delà du bord, il pourrait y avoir un rabais, une carte-cadeau, une deuxième ligne de taxe ou des frais de livraison. Un total calculé erroné aurait exactement la même apparence.

Diagnostic : Cherchez les valeurs sans preuve. Un total calculé n’a ni boîte ni texte seen (vu). Ce texte correspond à l’emplacement dans l’enregistrement des preuves de Représenter la provenance. Dans ce projet, chaque valeur trouvée a une ligne sur la page; un total sans ligne est une supposition.

Correction : Gardez le total absent, avec la raison cut_off, comme le fait combine.py. L’agent demande une nouvelle photo au client. Ou il saisit le total du reçu papier comme correction. Flux de correction enregistre cette correction à côté de l’original. Les vérifications comme « la somme correspond au total » relèvent de la validation, lorsque les deux valeurs sont imprimées : Validation selon les règles d’affaires.

Conséquence dans le travail en IA : une valeur plausible est pire qu’une valeur vide. Une valeur vide suscite une question; une valeur plausible empêche quiconque de la poser.

Changez une condition : au lieu d’utiliser les raisons du modèle, mesurez l’image. Une photo coupée contient du texte qui atteint le bord de l’image. Pour chaque photo et image numérisée, calculez la marge vide au-dessus de la ligne OCR la plus haute. Calculez aussi celle sous la ligne la plus basse. Exprimez chaque marge comme une proportion de la hauteur de l’image. Prédisez quels reçus ont une marge inférieure à 2 %. Puis vérifiez dans python :

from doc_extract import combine, documents
for d in documents.receipts():
if d.source not in ("photo", "scan_image"):
continue
page = combine.read_pages(d)[0]
if not page.lines:
print(d.doc_id, d.source, "no text")
continue
top = min(ln.box[1] for ln in page.lines) / page.height
bottom = 1 - max(ln.box[3] for ln in page.lines) / page.height
mark = " <- text at the edge" if min(top, bottom) < 0.02 else ""
print(f"{d.doc_id} {d.source:<10} top {top:5.1%} bottom {bottom:5.1%}{mark}")
Afficher la réponse
D020 scan_image top 2.4% bottom 6.0%
D022 scan_image top 23.0% bottom 43.5%
D024 scan_image top 39.2% bottom 25.7%
D026 scan_image top 5.5% bottom 3.3%
D028 scan_image top 35.2% bottom 32.7%
D030 scan_image top 15.1% bottom 49.9%
D032 scan_image top 3.3% bottom 4.7%
D033 scan_image top 45.6% bottom 32.3%
D034 scan_image top 30.0% bottom 48.0%
D035 photo top 14.1% bottom 14.5%
D036 photo top 10.3% bottom 9.7%
D037 photo top 11.5% bottom 10.4%
D038 photo top 12.5% bottom 15.2%
D039 photo top 11.9% bottom 12.3%
D040 photo top 10.5% bottom 8.5%
D041 photo top 11.1% bottom 16.3%
D042 photo top 16.6% bottom 15.1%
D043 photo top 13.3% bottom 13.2%
D044 photo top 13.0% bottom 13.3%
D045 photo top 33.2% bottom 0.1% <- text at the edge
D046 photo no text
D047 photo top 1.6% bottom 38.3% <- text at the edge
D048 photo top 15.1% bottom 28.0%
D049 photo top 18.7% bottom 30.4%
D051 scan_image top 30.8% bottom 31.0%

Deux images ont du texte au bord : D045 en bas (0,1 %) et D047 en haut (1,6 %). Ce sont exactement les deux photos dont le bord est coupé. Chaque autre photo a une marge d’au moins 8 % en haut et en bas. Certains documents numérisés s’en approchent : D020 a 2,4 % en haut, parce que le papier remplit la page numérisée. Cette mesure trouve donc le haut coupé de D047 sans la raison du modèle et sans le contrat. Elle nécessite un seuil que vous devez vérifier sur davantage de documents. Mais elle ne dépend pas de ce que le modèle dit sur lui-même. Le projet n’inclut pas cette vérification; vous pouvez l’ajouter comme septième signal.

Vérifiez votre compréhension

Expliquez comment le pipeline sait que le fournisseur de D047 n'est pas « non imprimé ». La page se lit pourtant bien et le modèle est sûr à 99 %.

Afficher la réponse

Ce ne sont pas les signaux de l’image : l’OCR a lu 255 caractères avec un score moyen de 0,99. Ce n’est pas non plus le modèle : il a répondu not_printed (non imprimé) avec une confiance de 0,99. Le pipeline le sait grâce au contrat d’extraction. Le contrat permet l’absence du fournisseur seulement avec unreadable (illisible), car chaque reçu indique son magasin. Le motif « fournisseur : absent, non imprimé » n’est donc pas permis par le contrat. field_signals le signale, et fait de même pour la date. Le motif honnête est cut_off (coupé) : le haut de la photo ne les montre plus. (Le contrat signalerait aussi cut_off pour le fournisseur, car il permet seulement unreadable. Cette règle est trop stricte pour un haut coupé. Un meilleur contrat permettrait cut_off : vous pouvez apporter cette amélioration, qui n’est pas faite dans le cours. Dans les deux cas, le reçu reçoit un signalement.) Une personne voit le signalement et demande une meilleure photo au client.

Vérifiez votre compréhension

Prédisez : D022 à la moitié de sa taille (425 x 550 pixels). Quel signal d'incertitude apparaîtra? L'OCR et le modèle liront-ils encore ses valeurs?

Afficher la réponse

À la moitié de sa taille, le texte de D022 mesure environ 11 pixels de haut, sous la limite de 14. La page reçoit donc le signal low_resolution (faible résolution). Son score moyen, 0,93, dépasse 0,75 : elle n’est donc pas illisible. L’OCR lit encore 7 de ses 8 valeurs, sur l’image brute comme sur l’image préparée. La réponse enregistrée du modèle à cette taille lit les 8 valeurs. Le signal est donc un avertissement qui précède l’échec. Au quart de la taille, l’OCR lit 0 valeur sur 8, et le modèle dit que la page est illisible.

Vérifiez votre compréhension

Vérification pratique : exécutez python -m doc_extract.uncertainty D045. Pour chaque signal et chaque champ absent, dites ce qu'un agent devrait faire.

Afficher la réponse

La sortie signale trois choses. currency: unverified (devise : non vérifiée) : le modèle a déduit CAD de l’adresse à Toronto, sans ligne qui l’indique. L’agent confirme la devise (un magasin à Toronto facture en dollars canadiens) ou pose la question. total: absent (cut_off) et payment_method: absent (cut_off) : le total et le mode de paiement existent sur papier, sous le bord de la photo. L’agent demande une nouvelle photo au client, ou saisit ces valeurs depuis le reçu papier comme correction. Les frais d’expédition sont absents avec not_printed : les reçus de caisse n’ont aucune ligne d’expédition, donc l’agent ne fait rien. Aucun agent ne devrait calculer le total à partir du sous-total et de la taxe.

Ce module a utilisé le modèle de vision de façon réfléchie. Dans Conception des entrées et des requêtes, vous avez choisi son entrée et écrit une requête précise. La page et une image recadrée quand le reçu est petit; un schéma strict où « absent » est une réponse normale. Les valeurs inventées sont passées de 11 à 0. Dans Combiner les méthodes, vous avez d’abord lu avec les règles, puis appelé le modèle pour 9 des 54 reçus. Vous avez ancré ses valeurs dans la page et conservé les désaccords pour une personne : 427 valeurs correctes sur 435, à 0,0018 $ US par document. Dans cette leçon, vous avez mesuré ce que les images ne permettent pas au pipeline de savoir. Vous avez aussi gardé chaque valeur indisponible explicite, avec son motif. Votre projet correspond à l’instantané end-of-m04 : python -m pytest -q affiche 84 passed (84 tests réussis). Seul README.md diffère : la version de l’instantané liste les commandes de ce module. Copiez-la depuis l’instantané si vous la voulez.

Exercice du module : comparer le pipeline avec vos propres étiquettes

Section intitulée « Exercice du module : comparer le pipeline avec vos propres étiquettes »

Extrayez les champs de reçus synthétiques, puis comparez-les à une vérité terrain que vous écrivez à la main. Une vérité terrain est l’ensemble des bonnes réponses auxquelles vous comparez le pipeline. Vous étiquetez ce que l’image montre, puis comparez chaque champ et comptez chaque résultat.

Exercice guidé : la photo D049 du magasin partenaire

Section intitulée « Exercice guidé : la photo D049 du magasin partenaire »
  1. Générez une image de la photo :

    Fenêtre de terminal
    python -m doc_extract.show D049
    D049 IMG_5101.jpg (168,957 bytes, photo)
    page 1: 1200 x 1600 pixels at 100 dpi -> out/show/D049-p1.png

    Ouvrez l’image dans out/show/.

  2. Écrivez vos étiquettes avant toute exécution, une par champ, selon le contrat. Voici l’étiquetage de D049 par l’auteur du cours, à partir de la photo :

    vendor Maple & Pine Hardware (MAPLE & PINE, a partner store of Larkfield)
    order_number absent, not_printed (INV# 0271480 is an invoice number)
    date 2026-09-23 (Sep 23 2026)
    currency CAD (inferred: a shop in Kingston ON; no currency printed)
    subtotal 27.45 (MERCH)
    shipping absent, not_printed
    tax 3.57 (Sales tax 13%)
    total 31.02 (AMOUNT DUE)
    payment_method Visa (TENDER VISA****4821)
  3. Exécutez le pipeline :

    Fenêtre de terminal
    python -m doc_extract.combine D049
    D049 IMG_5101.jpg: model used (required fields missing: subtotal, total; an unknown shop: the rules know only Larkfield's layouts)
    vendor MAPLE & PINE from both found ok
    order_number (not_printed) from none absent ok
    date 2026-09-23 from both found ok
    currency CAD from both inferred ok
    subtotal 27.45 from model found ok
    shipping (not_printed) from none absent ok
    tax 3.57 from both found ok
    total 31.02 from model found ok
    payment_method Visa from model found ok
  4. Comparez chaque champ. Attribuez à chaque champ l’un des cinq résultats :

    • correct : la même valeur, après normalisation;
    • absence correcte : absent des deux côtés;
    • manquant : vous avez une valeur, le pipeline n’en a aucune;
    • erroné : deux valeurs différentes;
    • inventé : le pipeline a une valeur, vous n’en avez aucune.

    Ici : 7 corrects et 2 absences correctes. Le fournisseur MAPLE & PINE devient Maple & Pine Hardware après normalisation.

  5. Comparez vos étiquettes à la vérité du générateur. Une étiquette manuelle peut aussi être erronée :

    Fenêtre de terminal
    python -m doc_extract.documents D049
    D049 IMG_5101.jpg
    kind receipt, source photo, language en, pages 1, 168,957 bytes
    how it was made: {"tilt": 0.05, "angle": 6.0}
    vendor Maple & Pine Hardware
    order_number (not on the document)
    date 2026-09-23
    currency CAD
    subtotal 27.45
    shipping (not on the document)
    tax 3.57
    total 31.02
    payment_method Visa
    item: 1 x Rake, steel @ 27.45 = 27.45

    Les étiquettes de l’auteur correspondent à la vérité. Voici comment la vérité du cours a été vérifiée : le générateur connaît chaque valeur par construction, et l’auteur a relu chaque reçu.

Exercice autonome : une numérisation et une photo coupée

Section intitulée « Exercice autonome : une numérisation et une photo coupée »

Faites de même pour la numérisation D033 du magasin partenaire et la photo D047, dont le haut est coupé. Étiquetez d’abord les deux à partir des images (show D033, show D047). Exécutez ensuite combine sur chacune, comparez et comptez les cinq résultats pour chaque reçu. Pour D047, décidez quoi écrire pour le fournisseur et la date. Est-ce ce que vous savez de Larkfield, ou ce que l’image montre?

Afficher une solution détaillée

D033, selon le pipeline :

D033 scan-partner-1.jpg: model used (required fields missing: subtotal, total; an unknown shop: the rules know only Larkfield's layouts)
vendor MAPLE & PINE from both found ok
order_number (not_printed) from none absent ok
date 2026-07-18 from both found ok
currency CAD from both inferred ok
subtotal 8.49 from model found ok
shipping (not_printed) from none absent ok
tax 1.10 from both found ok
total 9.59 from model found ok
payment_method Debit from model found ok

D047, selon le pipeline :

D047 IMG_4894.jpg: model used (required fields missing: vendor, date)
vendor (not_printed) from none absent ok
order_number LK-192531 from both found ok
date (not_printed) from none absent ok
currency CAD from both found ok
subtotal 187.00 from both found ok
shipping (not_printed) from none absent ok
tax 24.31 from both found ok
total 211.31 from both found ok
payment_method Visa from both found ok

La vérité de D047 :

D047 IMG_4894.jpg
kind receipt, source photo, language en, pages 1, 176,420 bytes
how it was made: {"tilt": 0.04, "angle": 2.0, "crop_top": 0.2864, "layout": "till"}
vendor (not on the document)
order_number LK-192531
date (not on the document)
currency CAD
subtotal 187.00
shipping (not on the document)
tax 24.31
total 211.31
payment_method Visa
item: 1 x Step ladder @ 79.00 = 79.00
item: 2 x Garden chair @ 54.00 = 108.00

D033 : 7 corrects, 2 absences correctes (le numéro de commande et les frais d’expédition). Le modèle a donné le sous-total, le total et le paiement, tous ancrés dans les lignes OCR de la numérisation.

D047 : 7 corrects et 2 absences correctes : le fournisseur et la date sont aussi absents dans la vérité. La vérité du générateur consigne ce que l’image montre, et le haut de cette photo est coupé. Si vous avez étiqueté le fournisseur « Larkfield » parce que vous connaissez la mise en page, l’image ne justifie pas votre étiquette. Votre comparaison compterait alors une valeur manquante qu’aucun lecteur ne pourrait trouver. Étiquetez l’image, pas vos connaissances. La vérité indique aussi printed_but_cut_off: vendor, date (imprimés, mais coupés : fournisseur, date) : c’est le motif. Le motif honnête pour les deux est donc cut_off. Le contrat permet cut_off pour la date, mais seulement unreadable pour le fournisseur, car il attend un nom de magasin lisible. Un haut coupé montre que cette règle est trop stricte : un meilleur contrat permettrait aussi cut_off pour le fournisseur. Vous pouvez apporter cette amélioration; le cours conserve la règle. Le pipeline indique que les deux sont absents, mais avec le mauvais motif du modèle, not_printed. La commande uncertainty D047 signale précisément ce problème.

Vérification de fin de leçon : garder les valeurs indisponibles explicites

Section intitulée « Vérification de fin de leçon : garder les valeurs indisponibles explicites »

Gardez les valeurs indisponibles explicites plutôt que d’inventer du texte plausible. Pour chaque cas, dites ce que le pipeline stocke, pourquoi, et quelle valeur plausible aurait pu être inventée :

  1. D045 : le total.
  2. D046 : le fournisseur.
  3. D047 : la date.
Afficher une solution détaillée

Ce que combine stocke pour les champs monétaires et le paiement de D045. Dans python :

from doc_extract import combine, documents
ex, dec = combine.combine(documents.get("D045"))
for n in ("subtotal", "tax", "total", "payment_method"):
f = ex.fields[n]
print(f"{n:<15} value={f.value!r:<9} status={f.status:<7} reason={f.reason!r:<12} from={dec.source[n]:<5} flags={dec.flags.get(n, [])}")
subtotal value='358.95' status=found reason='' from=both flags=[]
tax value='46.66' status=found reason='' from=rules flags=['the model says absent (cut_off)']
total value=None status=absent reason='cut_off' from=none flags=[]
payment_method value=None status=absent reason='cut_off' from=none flags=[]
  1. Total de D045 : value=None, status=absent, reason='cut_off'. La photo se termine sous la ligne de taxe, et le modèle l’a indiqué. La valeur inventée plausible est 405,61, le sous-total plus la taxe : correcte par hasard sur ce papier, sans aucune preuve. L’agent demande une nouvelle photo, ou ajoute le total comme correction.
  2. Fournisseur de D046 : absent, unreadable, comme tous les champs de cette photo. Le signal de la page indique unreadable: 0 characters found (illisible : 0 caractère trouvé). La valeur inventée plausible est « Larkfield », parce que la plupart des reçus viennent de là. C’est peut-être même vrai, mais aucun lecteur ne l’a vu. L’agent demande une photo plus nette.
  3. Date de D047 : absente, avec le motif du modèle not_printed, et le signalement « le contrat permet seulement : coupé, illisible ». La valeur inventée plausible est une date du billet de soutien, comme le jour où le client a écrit. Le motif honnête est cut_off. Le projet conserve le motif du modèle et ajoute le signalement, qui montre à une personne que le motif indiqué est erroné.

Dans les trois cas, le champ n’est ni vide ni deviné. Il indique « absent », avec un motif qui dit à l’agent quoi faire ensuite.

Récapitulatif

  • Les signaux d’incertitude visuelle sont mesurés, pas demandés. Ce sont : trop peu de caractères ou un faible score OCR moyen (unreadable), et du petit texte (low_resolution). Aussi, des pages en désaccord (conflict, conflit), des valeurs du modèle absentes de la page (unverified), et des valeurs absentes avec leur motif.
  • Ce que le modèle dit de lui-même ne suffit pas. Il a répondu not_printed avec une confiance de 0,99 pour le haut coupé de D047. Au quart de la taille, il a indiqué six lectures erronées comme found (trouvé). Les motifs permis par le contrat détectent le premier problème; les signaux de résolution et les règles appliquées d’abord protègent contre le second.
  • Au quart de leur taille, les petites images deviennent illisibles pour tous les lecteurs. À la moitié de leur taille, presque tout reste lisible, et le signal low_resolution avertit avant l’échec.
  • Gardez chaque valeur indisponible explicite : null, absent et un motif (not_printed, cut_off, unreadable). Ne calculez et ne complétez jamais une valeur que la page ne montre pas.

Ensuite, le module 5 vérifie les valeurs que le pipeline a trouvées : dates, totaux cohérents, devises et numéros de commande. Il décide aussi quels documents une personne doit réviser.

Leçon suivante : Validation selon les règles d'affaires