Construire un pipeline fiable de réception de documents et d’OCR

Commencer par un contrat de réception

Un pipeline documentaire devient difficile à gérer lorsque la première étape accepte tout et que la dernière suppose que tout a été compris. Définissez le contrat de réception avant de choisir les Robots : quelles sources sont autorisées, ce que l’application considère comme un document, quelles métadonnées sont requises, quelle taille un téléversement peut atteindre et quelles sorties les systèmes en aval attendent. Appliquez une limite de nombre de pages dans l’application avant de créer l’Assembly ; l’exemple ci-dessous ne limite pas le nombre de pages. Les PDF volumineux ou comportant de nombreuses pages peuvent dépasser la fenêtre fixe d’interrogation du Robot pendant l’attente d’un traitement asynchrone chez le fournisseur, même si ce traitement se termine ultérieurement. Réessayer avec une entrée inchangée n’élargit pas cette fenêtre ; traitez les dépassements répétés du délai d’attente comme un échec et réduisez ou scindez l’entrée avant une nouvelle tentative.

Conservez l’original téléversé comme référence immuable. Un PDF normalisé, un fichier texte OCR et un enregistrement de recherche sont des dérivés dont les durées de vie et les modes de défaillance diffèrent. Attribuez-leur une identité commune dans l’application afin qu’un examinateur puisse remonter d’un résultat de recherche aux octets sources qui l’ont produit. La navigation vers une page précise nécessite une correspondance distincte entre les pages.

Diriger chaque entrée vers le bon Robot

L’extension d’un fichier ne vous indique pas si un PDF contient du texte sélectionnable ou uniquement des pixels issus d’une numérisation. Utilisez la valeur de ${file.mime} déterminée par Transloadit et la politique de l’application pour diriger les entrées. La détermination du type MIME combine les métadonnées intégrées, les informations tirées de l’extension et l’analyse du contenu ; l’extension peut prévaloir lorsque les métadonnées intégrées sont indisponibles. Ce filtrage ne prouve pas la nature du contenu du fichier. Si votre contrat de réception exige une validation stricte du contenu, validez les octets stockés dans votre application. /file/filter peut diriger les fichiers à l’aide de conditions accepts ou declines portant sur ${file.mime} ; utilisez error_on_decline lorsqu’une entrée non prise en charge doit faire échouer l’Assembly.

Les PDF peuvent être envoyés directement à /document/ocr. Utilisez /image/ocr pour les textes courts dans les photographies et les captures d’écran ; sa documentation avertit que la précision peut être moindre pour les images de documents denses. Pour les fichiers bureautiques d’entrée tels que DOCX, utilisez /document/convert EN (English) pour les convertir en PDF, après avoir vérifié en premier lieu les formats d’entrée indiqués dans sa documentation. Ce flux de travail utilise sa sortie PDF ; d’autres formats de sortie sont disponibles, mais le PDF n’est pas pris en charge en entrée. Un Robot peut ignorer les entrées qu’il n’accepte pas sans faire échouer l’Assembly ; ajoutez donc un filtre MIME explicite et vérifiez les sorties requises.

Préserver la provenance dans les sorties dérivées

Il est difficile de se fier à un texte sans en connaître la provenance. Stockez l’identifiant du document source, la version de sortie et l’horodatage de l’extraction avec le texte extrait. L’exemple AWS ci-dessous renvoie du JSON à l’échelle du document, sans rattacher les données aux pages. Pour obtenir des résultats de recherche par page, l’application doit scinder les PDF avant le téléversement et consigner les numéros des pages d’origine ; cette préparation sort du cadre du guide. L’exemple autorise une seule entrée par Assembly et utilise des noms d’objets fixes. Un pipeline par page nécessite une Assembly par page, avec des clés d’objets propres à chaque page et une correspondance avec le document parent. Réutiliser les mêmes valeurs document_id et output_version pour plusieurs pages écraserait leurs objets. Ne déduisez jamais cette correspondance de l’ordre du tableau OCR. Si la source est remplacée, créez une nouvelle version et laissez l’indexeur retirer l’ancien enregistrement uniquement après vérification de la nouvelle sortie.

Conservez le texte OCR séparément du document normalisé. Un examinateur peut avoir besoin de consulter côte à côte le scan d’origine, le PDF converti et le texte extrait. Ce lien est également utile lorsqu’un autre fournisseur d’OCR produit un meilleur résultat.

Rendre explicites l’examen et l’indexation

La valeur ok ASSEMBLY_COMPLETED de l’Assembly Status, observée par interrogation périodique ou via des notifications, signifie qu’aucune erreur non ignorée n’a interrompu l’Assembly et que les Jobs déclarés pour celle-ci, y compris les Jobs de stockage, sont terminés. Un Step peut ne pas traiter une entrée, et ignore_errors peut masquer l’échec d’un Step ; l’achèvement ne prouve donc pas à lui seul que les artefacts requis existent. Il ne signifie pas non plus que l’index de recherche de votre application a accepté le texte ou qu’une personne a approuvé un enregistrement sensible. Ne publiez un événement en aval qu’une fois que les sorties dont vous avez besoin existent et ont passé leurs contrôles.

/document/ocr ne fournit pas de scores de confiance ; ce Template ne peut donc pas orienter le traitement selon un seuil de confiance du fournisseur. Déclenchez un examen humain à l’aide de contrôles applicatifs automatisés portant par exemple sur des fichiers de sortie manquants, un texte extrait vide, une quantité de texte anormalement faible pour le nombre de pages indiqué, l’absence d’expressions attendues ou une catégorie de documents à fort enjeu. Pour les documents ordinaires, un parcours automatisé peut tout de même consigner les contrôles et conserver un moyen de retraiter la source.

Versionner les corrections sans perdre les éléments de preuve

Les corrections OCR et les remplacements de source doivent créer une nouvelle version dérivée. Conservez la source précédente, la sortie précédente et la décision issue de l’examen pendant la durée requise par votre politique de conservation, afin de pouvoir expliquer un résultat de l’index après une correction.

Utilisez l’identifiant du document et la version de sortie comme clé d’indexation. Ne réutilisez une version que pour relancer la même tentative de traitement ; attribuez une nouvelle version en cas de correction, de changement de fournisseur ou de retraitement délibéré. Sérialisez les écritures pour une même version afin que des tentatives simultanées ne puissent pas écraser un résultat accepté plus récent.

Commencer par un Template PDF au périmètre limité

L’exemple ci-dessous implémente uniquement la branche PDF : il autorise au plus un téléversement, rejette les types MIME autres que PDF, demande une sortie JSON OCR à AWS et exporte la source et le JSON vers des clés fixes distinctes, sous une seule version de document contrôlée par l’application. Enregistrez ce JSON comme contenu d’un Template stocké, et non comme paramètres complets d’une requête d’Assembly. Votre serveur fournit l’Auth Key et la signature lors de la création de l’Assembly. Testez des PDF représentatifs pour vérifier la structure de sortie, l’exploitabilité du texte et le comportement en cas d’échec avant d’étendre cette configuration d’exemple. Le paramètre auth.max_size limite le nombre total d’octets attendu pour le téléversement, y compris les données supplémentaires de la requête : 104857600 octets correspondent à 100 MiB, et non à une limite par fichier. Il ne garantit ni le rejet avant qu’un téléversement avec reprise ne transfère des octets, ni l’achèvement de l’OCR.

Créez un compte Transloadit et enregistrez les Assembly Instructions dans un Template. Créez un ensemble d’informations d’identification de Template pour S3 nommé document-output, comprenant key, secret, bucket et bucket_region ; consultez les informations d’identification de Template pour la configuration. Pour cette configuration d’exemple, le serveur doit construire et soumettre l’intégralité de la requête d’Assembly, téléversement compris, plutôt que de transmettre le paramètre params signé à un navigateur. Il doit fournir et valider, dans les champs de la requête, des valeurs document_id et output_version non vides, autorisées et utilisables sans risque dans un chemin. Ces valeurs deviennent les variables ${fields.document_id} et ${fields.output_version} dans les chemins de stockage. Les champs multipart alimentent eux aussi les champs de l’Assembly et ne sont pas couverts par la signature du paramètre params ; la signature seule n’autorise donc pas un préfixe de stockage. Ne transmettez pas les champs fournis par le client. Avant l’indexation, vérifiez que les clés de stockage renvoyées correspondent au préfixe attendu par le serveur. Enregistrez allow_steps_override: false dans le Template stocké pour empêcher la redéfinition des Steps à l’exécution lorsque vous utilisez template_id. Gardez le bucket privé avec Block Public Access activé et vérifiez l’autorisation des lecteurs ; acl: bucket-default omet l’ACL de l’objet et s’appuie sur la politique d’accès du bucket.

Cet exemple fixe provider: aws pour rendre le choix du fournisseur explicite, sans garantir des réponses identiques. La valeur par défaut est auto. Prenez les limites actuelles d’AWS Textract⁠ comme référence pour les langues prises en charge par AWS. Vérifiez la prise en charge par le fournisseur avant de choisir AWS ou GCP ; leurs structures JSON diffèrent. Testez les langues et les mises en page de vos documents avec le fournisseur choisi et attendez-vous à ce que les réponses changent à mesure que ses modèles évoluent.

L’exemple utilise format: "json" avec granularity: "list" pour exporter un tableau de chaînes correspondant aux lignes reconnues, destiné à l’indexation et aux contrôles du volume de texte. Cela évite le mélange d’entrées de pages, de lignes et de mots dans l’artefact de granularité full produit par défaut, qui peut contenir du texte répété. format: "text" exporte plutôt du texte brut et impose la granularité list. Aucune sortie n’inclut le rattachement aux pages ni de score de confiance. Si vous choisissez la granularité full, les points facultatifs des polygones utilisent une seule largeur et une hauteur issues des métadonnées du PDF ; leurs coordonnées deviennent égales à zéro lorsque ces dimensions sont absentes. Validez ces points avant toute superposition et ne déduisez jamais l’identité d’une page des polygones ou de l’ordre du tableau.

Un Job d’OCR réussi peut tout de même omettre ou mal reconnaître du texte. Vérifiez les deux objets exportés ainsi que le volume de texte extrait par rapport au nombre de pages indiqué, et envoyez les résultats suspects pour examen humain. Ces contrôles automatisés signalent des problèmes, mais ne prouvent pas que la reconnaissance est complète ou exacte ; comparez les résultats à du texte connu dans des documents sources représentatifs avant publication.

Les clés d’objet fixes source.pdf et ocr.json font que les nouvelles tentatives ciblent les mêmes emplacements de stockage pour une version de document. Elles ne dédupliquent pas les Assemblies et ne rendent pas l’OCR déterministe ; l’application doit sérialiser les nouvelles tentatives et conserver la correspondance avec le résultat accepté. Comparez les frais des fournisseurs à l’aide des tarifs de Transloadit, en tenant compte du volume de pages et des autres traitements du flux de travail. Les frais d’OCR par page, propres à chaque fournisseur, sont calculés à partir de la valeur page_count indiquée pour l’entrée ; comparez les frais actuels avant d’estimer le coût du flux de travail complet.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 1,
    "max_size": 104857600
  },
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "pdf_only": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "==", "application/pdf"]],
      "error_on_decline": true,
      "error_msg": "Upload a PDF document"
    },
    "extracted_text": {
      "use": "pdf_only",
      "robot": "/document/ocr",
      "provider": "aws",
      "format": "json",
      "granularity": "list",
      "result": true
    },
    "stored_source": {
      "use": "pdf_only",
      "robot": "/s3/store",
      "credentials": "document-output",
      "path": "documents/${fields.document_id}/${fields.output_version}/source.pdf",
      "acl": "bucket-default",
      "result": true
    },
    "stored_text": {
      "use": "extracted_text",
      "robot": "/s3/store",
      "credentials": "document-output",
      "path": "documents/${fields.document_id}/${fields.output_version}/ocr.json",
      "acl": "bucket-default",
      "result": true
    }
  }
}