Analyser la réponse de l’API de document

Dans cet article, nous examinerons les différents objets renvoyés dans le cadre de la réponse de AnalyzeDocument et de la façon dont vous pouvez utiliser la réponse d’analyse de document API dans vos applications.

Demande d’analyse de document

Les API Intelligence documentaire analysent les images, les PDF et d’autres fichiers de documents pour extraire et détecter divers éléments de contenu, de disposition, de style et de sémantique. L’opération Analyze une API asynchrone. L’envoi d’un document renvoie un en-tête Operation-Location qui contient l’URL à interroger pour l’achèvement. Lorsqu’une demande d’analyse se termine correctement, la réponse contient les éléments décrits dans l’extraction des données du modèle.

Éléments de réponse

• Les éléments de contenu sont les éléments de texte de base extraits du document.

• Les éléments de disposition regroupent les éléments de contenu en unités structurelles.

• Les éléments de style décrivent la police et la langue des éléments de contenu.

• Les éléments sémantiques attribuent une signification aux éléments de contenu spécifiés.

Tous les éléments de contenu sont regroupés par pages, spécifiées par le numéro de page (1 indexé). Ils sont également triés par ordre de lecture qui classe ensemble les éléments sémantiquement contigus, même s’ils traversent les limites des lignes ou des colonnes. Lorsque l’ordre de lecture entre les paragraphes et autres éléments de disposition est ambigu, le service renvoie généralement le contenu dans un ordre de gauche à droite et de haut en bas.

Remarque

Actuellement, Intelligence documentaire ne prend pas en charge l’ordre de lecture au-delà des limites de page. Les marques de sélection ne sont pas positionnées à l’intérieur des mots qui les entourent.

La propriété de contenu de niveau supérieur contient une concaténation de tous les éléments de contenu dans l’ordre de lecture. Tous les éléments précisent leur position dans l’ordre de lecture par le biais d’intervalles dans cette chaîne de contenu. Le contenu de certains éléments n’est pas toujours contigu.

Réponse d’analyse

La réponse Analyze pour chaque API renvoie des objets différents. Les réponses de l’API contiennent des éléments des modèles de composants, le cas échéant.

Contenu de la réponse	Description	API
pages	Mots, lignes et intervalles reconnus à partir de chaque page du document d’entrée.	Modèles de lecture, de disposition, de document général, préétablis et personnalisés
paragraphes	Contenu reconnu en tant que paragraphes.	Modèles de lecture, de disposition, de document général, préétablis et personnalisés
styles	Propriétés d’élément de texte identifiées.	Modèles de lecture, de disposition, de document général, préétablis et personnalisés
langues	Langue identifiée associée à chaque intervalle du texte extrait	Lire
tables	Contenu tabulaire identifié et extrait du document. Les tableaux sont liés aux tableaux identifiés par le modèle de disposition pré-entraîné. Le contenu étiqueté en tant que tableaux est extrait en tant que champs structurés dans l’objet documents.	Modèles de disposition, de document général, de facture et personnalisés
figures	Figures (graphiques, images) identifiées et extraites du document, fournissant des représentations visuelles qui facilitent la compréhension des informations complexes.	Le modèle de disposition
sections	Structure de document hiérarchique identifiée et extraite du document. Section ou sous-section avec les éléments correspondants (paragraphe, tableau, figure) qui lui sont attachés.	Le modèle de disposition
keyValuePairs	Paires clé-valeur reconnues par un modèle pré-entraîné. La clé est un intervalle de texte du document avec la valeur associée.	Modèles de document général et de facture
documents	Les champs reconnus sont renvoyés dans le dictionnaire fields dans la liste des documents	Modèles prédéfinis, modèles personnalisés.

Pour plus d’informations sur les objets renvoyés par chaque API, consultez Extraction de données de modèle.

Propriétés de l’élément

Étendues

Les intervalles précisent la position logique de chaque élément dans l’ordre de lecture global, chaque intervalle spécifiant un décalage et une longueur de caractère dans la propriété de chaîne de contenu de niveau supérieur. Par défaut, les décalages et longueurs de caractères sont renvoyés en unités de caractères perçus par l’utilisateur (également appelés grapheme clusters ou éléments de texte). Pour prendre en charge différents environnements de développement qui utilisent différentes unités de caractères, l’utilisateur peut également spécifier le paramètre de requête stringIndexIndex pour renvoyer des décalages et des longueurs d’intervalle dans des points de code Unicode (Python 3) ou des unités de code UTF16 (Java, JavaScript, .NET). Pour plus d’informations, consultez Prise en charge multilingue/emojis.

Région limite

Les régions limites décrivent la position visuelle de chaque élément dans le fichier. Lorsque les éléments ne sont pas visuellement contigus ou croisés (tables), les positions de la plupart des éléments sont décrites via un tableau de régions englobantes. Chaque région spécifie le numéro de page (1 indexé) et le polygone limite. Le polygone limite est décrit comme une séquence de points, dans le sens des aiguilles d’une montre à partir de la gauche par rapport à l’orientation naturelle de l’élément. Pour les quadrilatères, les points de tracé sont les coins haut-gauche, haut-droit, bas-droit et bas-gauche. Chaque point représente ses coordonnées x, y dans l’unité de page spécifiée par la propriété unité. En général, l’unité de mesure des images est le pixel, tandis que les fichiers PDF utilisent le pouce.

Remarque

Actuellement, Intelligence documentaire retourne uniquement des quadrilatères à 4 sommets en tant que polygones englobants. Les versions ultérieures pourront renvoyer un nombre différent de points pour décrire des formes plus complexes, comme des lignes courbes ou des images non rectangulaires. Les régions limites s’appliquent uniquement aux fichiers affichés. Si le fichier n’est pas rendu, les régions limites ne sont pas renvoyées. Actuellement, les fichiers au format docx/xlsx/pptx/html ne sont pas affichés.

Éléments de contenu

Word

Un mot est un élément de contenu composé d’une séquence de caractères. Dans Intelligence documentaire, un mot est défini comme séquence de caractères adjacents, où des espaces blancs séparent les mots les uns des autres. Pour les langues qui n’utilisent pas de séparateurs d’espace entre les mots, chaque caractère est renvoyé comme un mot distinct, même s’il ne représente pas une unité de mot sémantique.

Marques de sélection

Une marque de sélection est un élément de contenu qui représente un glyphe visuel indiquant l’état d’une sélection. La case à cocher est une forme courante de marques de sélection. Toutefois, elles sont également représentées via des cases d’option ou une cellule boxed sous forme visuelle. L’état d’une marque de sélection peut être sélectionné ou non sélectionné, avec une représentation visuelle différente pour indiquer l’état.

Éléments de disposition

Courbes

Une ligne est une séquence ordonnée d’éléments de contenu consécutifs séparés par un espace visuel, ou d’éléments immédiatement adjacents pour les langues ne comportant pas de délimiteurs d’espace entre les mots. Les éléments de contenu situés dans le même plan horizontal (rangée) mais séparés par plus d’un espace visuel seront généralement divisés en plusieurs lignes. Si cette fonctionnalité permet parfois de diviser un contenu sémantiquement contigu en lignes distinctes, elle permet aussi de représenter un contenu textuel divisé en plusieurs colonnes ou cellules. Les lignes en écriture verticale sont détectées dans le sens vertical.

Paragraph

Un paragraphe est une séquence ordonnée de lignes qui forment une unité logique. En général, les lignes partagent un alignement commun et un espacement entre les lignes. Les paragraphes sont souvent délimités par une mise en retrait, un espacement supplémentaire ou des puces/numérotations. Un contenu ne peut être affecté qu’à un seul paragraphe. Vous pouvez également associer des paragraphes à un rôle fonctionnel dans le document. Les rôles actuellement pris en charge sont l’en-tête de page, le pied de page, le numéro de page, le titre, le titre de section et la note de bas de page.

Page

Une page est un regroupement de contenu qui correspond généralement à un côté d’une feuille de papier. Une page affichée est caractérisée par la largeur et la hauteur dans l’unité spécifiée. En général, les images utilisent le pixel tandis que les fichiers PDF utilisent le pouce. La propriété d’angle décrit l’angle de texte global en degrés pour les pages qui peuvent être pivotées.

Remarque

Pour les feuilles de calcul comme Excel, chaque feuille est mappée à une page. Pour les présentations, comme PowerPoint, chaque diapositive est mappée à une page. Pour les formats de fichiers sans concept natif de pages sans rendu comme les documents HTML ou Word, le contenu principal du fichier est considéré comme une seule page.

Table de charge de travail

Un tableau organise le contenu en un groupe de cellules dans une disposition de grille. Les lignes et colonnes peuvent être séparées visuellement par des lignes de grille, une bande de couleurs ou un espacement supérieur. La position d’une cellule de tableau est spécifiée par ses indices de ligne et de colonne. Une cellule peut s’étendre sur plusieurs lignes et colonnes.

En fonction de sa position et de son style, une cellule peut être classée comme contenu général, en-tête de ligne, en-tête de colonne, en-tête de stub ou description :

• Une cellule d’en-tête de ligne est généralement la première cellule d’une ligne qui décrit les autres cellules de la ligne.

• Une cellule d’en-tête de colonne est généralement la première cellule d’une colonne qui décrit les autres cellules de la colonne.

• Une ligne ou une colonne peut contenir plusieurs cellules d’en-tête pour décrire le contenu hiérarchique.

• Une cellule de tête stub est généralement la cellule située dans la première rangée et la première colonne. Elle peut être vide ou décrire les valeurs dans les cellules d’en-tête dans la même ligne/colonne.

• Une cellule de description apparaît généralement dans la partie supérieure ou inférieure d’un tableau, décrivant le contenu global du tableau. Toutefois, elle peut parfois apparaître au milieu d’un tableau pour décomposer le tableau en sections. En général, les cellules de description s’étendent sur plusieurs cellules d’une même ligne.

• Une légende de tableau spécifie le contenu qui explique le tableau. Un tableau peut également avoir une légende associée et un ensemble de notes de bas de page. Contrairement à une cellule de description, une légende se trouve généralement en dehors de la disposition de la grille. Une note de bas de page de tableau annote le contenu à l’intérieur du tableau, souvent marqué avec un symbole de note de bas de page souvent trouvé sous la grille du tableau.

Les tableaux de disposition diffèrent des champs de document extraits des données tabulaires. Les tableaux de disposition sont extraits du contenu visuel tabulaire du document sans tenir compte de la sémantique du contenu. En fait, certains tableaux de disposition sont conçus uniquement pour la disposition visuelle et ne contiennent pas toujours de données structurées. La méthode d’extraction de données structurées à partir de documents dont la disposition visuelle varie, comme les détails d’un reçu, nécessite généralement un post-traitement important. Il est essentiel de mapper les en-têtes de ligne ou de colonne à des champs structurés avec des noms de champ normalisés. En fonction du type de document, utilisez des modèles préétablis ou formez un modèle personnalisé pour extraire ce contenu structuré. Les informations qui en résultent sont exposées sous forme de champs de document. Ces modèles entraînés peuvent également traiter des données tabulaires sans en-tête et des données structurées sous des formes non tabulaires, par exemple la section « expérience professionnelle » d'un CV.

Remarque

À compter de 2024-07-31-preview, les régions englobantes pour les figures et les tableaux couvrent uniquement le contenu principal et excluent les légendes et notes de bas de page associées.

Figures

Les figures (graphiques, images) dans les documents jouent un rôle crucial dans le complément et l’amélioration du contenu textuel, fournissant des représentations visuelles qui aident à comprendre les informations complexes. L'objet figures détecté par le modèle de mise en page possède des propriétés clés telles que boundingRegions (les emplacements spatiaux de la figure sur les pages du document, y compris le numéro de page et les coordonnées du polygone qui délimitent la limite de la figure), spans (détaille les étendues de texte liées à la figure, en spécifiant leurs décalages et longueurs dans le texte du document. Cette connexion permet d’associer la figure à son contexte textuel pertinent), elements (les identifiants des éléments de texte ou des paragraphes du document qui sont liés à ou décrivent la figure) et caption, s’il y en a.

Lorsque output=figures est spécifiée lors de l’opération Analyze initiale, le service génère des images rognées pour toutes les figures détectées accessibles via /analyeResults/{resultId}/figures/{figureId}. FigureId est inclus dans chaque objet figure, suivant une convention non documentée de {pageNumber}.{figureIndex} où figureIndex réinitialise à une par page.

{
    "figures": [
      {
        "id": "{figureId}",
        "boundingRegions": [],
        "spans": [],
        "elements": [
          "/paragraphs/15",
          ...
        ],
        "caption": {
          "content": "Here is a figure with some text",
          "boundingRegions": [],
          "spans": [],
          "elements": [
            "/paragraphs/15"
          ]
        }
      }
    ]
}

Sections

L’analyse hiérarchique de la structure des documents est essentielle pour organiser, comprendre et traiter des documents étendus. Cette approche est essentielle pour segmenter sémantiquement des documents longs afin d’améliorer la compréhension, de faciliter la navigation et d’améliorer la récupération des informations. L’avènement de la génération augmentée de récupération (RAG) dans l’IA générative de document souligne l’importance de l’analyse hiérarchique de la structure de document. Le Modèle de disposition prend en charge les sections et sous-sections de la sortie, qui identifie la relation des sections et des objets dans chaque section. La structure hiérarchique est conservée dans elements de chaque section.

{
    "sections": [
      {
        "spans": [],
        "elements": [
          "/paragraphs/0",
          "/sections/1",
          "/sections/2",
          "/sections/5"
        ]
      },
...
}

Champ de formulaire (paire clé-valeur)

Un champ de formulaire se compose d’une étiquette de champ (clé) et d’une valeur. L’étiquette de champ est généralement une chaîne de texte descriptive qui décrit la signification du champ. Elle apparaît souvent à gauche de la valeur, mais elle peut aussi apparaître au-dessus ou en dessous de la valeur. La valeur du champ contient la valeur du contenu d’une instance de champ spécifique. La valeur peut se composer de mots, de marques de sélection et d’autres éléments de contenu. Il peut également être vide pour les champs de formulaire non remplis. Un type particulier de champ de formulaire comporte une valeur de marque de sélection avec l’étiquette du champ à sa droite. Le champ de document est un concept similaire mais distinct des champs de formulaire généraux. L’étiquette (clé) d’un champ de formulaire général doit apparaître dans le document. Ainsi, elle ne peut généralement pas saisir des informations telles que le nom du commerçant sur un reçu. Les champs de document sont étiquetés et n’extraient pas de clé. Les champs de document mappent uniquement une valeur extraite à une clé étiquetée. Pour plus d’informations, consultez Champs de document.

Éléments de style

Style

Un élément de style décrit le style de police à appliquer au contenu textuel. Le contenu est spécifié via des intervalles dans la propriété globale du contenu. Actuellement, le seul style de police détecté est l’écriture manuelle. Comme d’autres styles sont ajoutés, le texte peut être décrit via plusieurs objets de style non-conflictuel. Pour des raisons de compacité, tous les textes partageant un style de police particulier (avec la même confiance) sont décrits par un seul objet de style.

{
    "confidence": 1,
    "spans": [
        {
            "offset": 2402,
            "length": 7
        }
    ],
    "isHandwritten": true
}

Langage

Un élément de langue décrit la langue détectée pour le contenu spécifié via des intervalles dans la propriété de contenu global. La langue détectée est spécifiée via une balise de langue BCP-47 pour indiquer la langue principale, ainsi que les informations de script et de région facultatives. Par exemple, l’anglais et le chinois traditionnel sont reconnus comme « en » et zh-Hant, respectivement. Les différences d’orthographe régionales pour l’anglais britannique peuvent entraîner la détection de texte telle que En-GB. Les éléments linguistiques n’englobent pas les textes sans langue dominante (ex. : les chiffres).

Éléments sémantiques

Remarque

Les éléments sémantiques décrits ici s’appliquent aux modèles prédéfinis d’Intelligence documentaire. Vos modèles personnalisés peuvent retourner des représentations de données différentes. Par exemple, la date et l’heure retournées par un modèle personnalisé peuvent être représentées dans un modèle différent de la mise en forme ISO 8601 standard.

Document

Un document est une unité sémantiquement complète. Un fichier peut contenir plusieurs documents, tels que plusieurs formulaires fiscaux au sein d’un fichier PDF ou plusieurs reçus dans une seule page. Cependant, l’ordre des documents au sein du fichier n’affecte pas fondamentalement les informations qu’il transmet.

Remarque

Intelligence documentaire ne prend pas actuellement en charge plusieurs documents sur une seule page.

Le type de document décrit des documents partageant un ensemble commun de champs sémantiques, représentés par un schéma structuré, indépendamment de son modèle visuel ou de sa disposition. Par exemple, tous les documents de type « reçu » peuvent contenir le nom du marchand, la date de transaction et le total des transactions, bien que les reçus de restaurant et d’hôtel diffèrent souvent en apparence.

Un élément de document comprend la liste des champs reconnus parmi les champs spécifiés par le schéma sémantique du type de document détecté :

• Un champ de document peut être extrait ou déduit. Les champs extraits sont représentés par le contenu extrait et éventuellement sa valeur normalisée, si elle est interprétable.

• Un champ déduit ne contient aucune propriété de contenu et est représenté uniquement par sa valeur.

• Un champ de tableau ne contient aucune propriété de contenu. Le contenu peut être concaténé à partir du contenu des éléments du tableau.

• Un champ d’objet contient une propriété de contenu qui spécifie le contenu complet représentant l’objet pouvant être un sur-ensemble des sous-champs extraits.

Le schéma sémantique d’un type de document est décrit par le biais des champs qu’il contient. Chaque schéma de champ est spécifié par son nom canonique et son type de valeur. Les types de valeurs de champ comprennent les types de base (ex. : chaîne), composés (ex. : adresse) et structurés (ex. : tableau, objet). Le type de valeur du champ spécifie également la normalisation sémantique effectuée pour convertir le contenu détecté en une représentation de normalisation. La normalisation peut être dépendante des paramètres régionaux.

Types de base

Type de valeur de champ	Description	Représentation normalisée	Exemple (Contenu du champ -> Valeur)
string	Texte brut	Identique au contenu	MerchantName : « Contoso » → « Contoso »
date	Date	ISO 8601 - AAAA-MM-JJ	InvoiceDate : « 07/05/2022 » → « 2022-05-07 »
time	Temps	ISO 8601 - hh:mm:ss	TransactionTime : « 21:45 » → « 21:45:00 »
phoneNumber	Numéro de téléphone	E.164 - +{CountryCode}{SubscriberNumber}	WorkPhone : « (800) 555-7676 » → « +18005557676 »
countryRegion	Pays/région	ISO 3166-1 alpha-3	CountryRegion : « États-Unis » → « EUA »
selectionMark	Est sélectionné	« signé » ou « non signé »	AcceptEula : ☑ → « sélectionné »
signature	Est signé	Identique au contenu	LendeeSignature : {signature} → « signé »
nombre	Nombre à virgule flottante	Nombre à virgule flottante	Quantity : « 1.20 » → 1.2
entier	Nombre entier	Numéro signé 64 bits	Count : « 123 » → 123
boolean	Valeur booléenne	true/false	IsStatutoryEmployee : ☑ → vrai

Types composés

• Devise : montant monétaire avec unité monétaire facultative. Une valeur, par exemple : InvoiceTotal: $123.45

  {
      "amount": 123.45,
      "currencySymbol": "$"
  }
  

• Address : adresse analysée. Par exemple : ShipToAddress: 123 Main St., Redmond, WA 98052

  {
  "poBox": "PO Box 12",
  "houseNumber": "123",
  "streetName": "Main St.",
  "city": "Redmond",
  "state": "WA",
  "postalCode": "98052",
  "countryRegion": "USA",
  "streetAddress": "123 Main St."
  }
  

Types structurés

• Array : liste de champs du même type

  "Items": {
      "type": "array",
      "valueArray": [
  
      ]
  }
  

• Object : liste nommée de sous-champs de types potentiellement différents

  "InvoiceTotal": {
    "type": "currency",
    "valueCurrency": {
        "currencySymbol": "$",
        "amount": 110
    },
    "content": "$110.00",
    "boundingRegions": [
        {
            "pageNumber": 1,
            "polygon": [
                7.3842,
                7.465,
                7.9181,
                7.465,
                7.9181,
                7.6089,
                7.3842,
                7.6089
            ]
        }
    ],
    "confidence": 0.945,
    "spans": [
        {
            "offset": 806,
            "length": 7
        }
    ]
  }
  

Étapes suivantes

• Essayez de traiter vos propres formulaires et documents à l’aide du Studio Intelligence documentaire.

• Effectuez un démarrage rapide Intelligence Documentaire et commencez à créer une application de traitement de documents dans le langage de développement de votre choix.