Migration d’Intelligence documentaire v3.1

  • Article

Ce contenu s’applique à :checkmarkv4.0 (préversion)checkmarkv3.1 (GA)checkmarkv3.0 (GA)checkmarkv2.1 (GA)

Important

La version 3.1 de l’API REST d’Intelligence documentaire introduit des changements cassants qui affectent la requête de l’API REST et l’analyse de la réponse JSON.

Migration à partir de la version 3.1 de l’API (préversion)

Les API en préversion sont régulièrement abandonnées. Si vous utilisez une version d’API en préversion, mettez à jour votre application pour cibler la version de l’API en disponibilité générale. Pour migrer de la version d’API 2023-02-28-preview vers la version d’API 2023-07-31 (disponibilité générale) à l’aide du SDK, mettez à jour vers la version actuelle du SDK spécifique au langage.

L’API 2023-07-31 (disponibilité générale) comporte quelques mises à jour et modifications par rapport à la version d’API en préversion :

  • Les fonctionnalités activées par défaut sont limitées à celles qui sont essentielles au modèle particulier, avec l’avantage d’une latence et d’une taille de réponse réduites. Des fonctionnalités supplémentaires peuvent être activées via des valeurs d’énumération dans le paramètre features.
  • Certaines fonctionnalités de disposition de prebuilt-read et de keyValuePairs au-delà de prebuilt-{document,invoice} ne sont plus prises en charge.
  • Désactivation des codes-barres par défaut pour prebuilt-read et prebuilt-layout, des langues pour prebuilt-read et de keyValuePairs pour prebuilt-invoice.
  • L’extraction d’annotation est supprimée.
  • Les champs de requête et les noms courants des paires clé-valeur sont supprimés.
  • Les fichiers Office/HTML sont pris en charge dans le modèle prebuilt-read, en extrayant des mots et des paragraphes sans cadre englobant. Les images incorporées ne sont plus prises en charge. Si des fonctionnalités de module complémentaire sont demandées pour les fichiers Office/HTML, un tableau vide est retourné sans erreur.

Fonctionnalités d’analyse

ID de modèle Extraction de texte Paragraphes Rôles de paragraphe Marques de sélection Tables Paires clé-valeur Langages Codes-barres Analyse de documents Formules* StyleFont* OCR haute résolution*
prebuilt-read ✓ ✓ O O O O O
prebuilt-layout ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
Facture prédéfinie ✓ ✓ ✓ O O O ✓ O O O
prebuilt-receipt ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098E ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098T ✓ ✓ O O ✓ O O O
prebuilt-contract ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - Activé - O - Facultatif Formules/StyleFont/OCR haute résolution* - Les fonctionnalités Premium entraînent des coûts supplémentaires

Migration à partir de v3.0

Par rapport à la version 3.0, Intelligence documentaire v3.1 introduit plusieurs nouvelles fonctionnalités :

  • Extraction de codes-barres.
  • Fonctionnalités de module complémentaire, notamment l’extraction de propriétés de police, de formule et de haute résolution.
  • Modèle de classification personnalisé pour le fractionnement et la classification des documents.
  • Extension de la langue et prise en charge de nouveaux champs dans les modèles Facture et Reçu.
  • Prise en charge d’un nouveau type de document dans le modèle Document d’identité.
  • Nouveau modèle Carte d’assurance maladie prédéfini.
  • Les fichiers Office/HTML sont pris en charge dans le modèle prebuilt-read, en extrayant des mots et des paragraphes sans cadre englobant. Les images incorporées ne sont plus prises en charge. Si des fonctionnalités de module complémentaire sont demandées pour les fichiers Office/HTML, un tableau vide est retourné sans erreur.
  • Expiration du modèle pour les modèles d’extraction et de classification personnalisés : nos nouveaux modèles personnalisés s’appuient sur un grand nombre de modèles de base que nous mettons à jour régulièrement pour améliorer la qualité. Une date d’expiration est introduite pour tous les modèles personnalisés pour permettre la mise hors service des modèles de base correspondants. Une fois qu’un modèle personnalisé expire, vous devez le réentraîner à l’aide de la dernière version de l’API (modèle de base).
GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}
  • Quota de génération de modèle neural personnalisé : le nombre de modèles neuraux que chaque abonnement peut générer par région chaque mois est limité. Nous développons le résultat JSON pour inclure le quota et les informations utilisées pour vous aider à comprendre l’utilisation actuelle dans le cadre des informations de ressource retournées par GET /info.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • Un paramètre de requête facultatif features pour les opérations Analyser peut éventuellement activer des fonctionnalités spécifiques. Certaines fonctionnalités Premium peuvent entraîner une facturation additionnelle. Pour plus d’informations, consultez Liste des fonctionnalités Analyser.
  • Étendez les objets de champ de devise extraits pour générer un champ de code de devise normalisé lorsque cela est possible. Actuellement, les champs courants peuvent retourner un montant (par exemple, 123,45) et currencySymbol (ex. $). Cette fonctionnalité mappe le symbole de devise à un code ISO 4217 canonique (par exemple, USD). Le modèle peut éventuellement utiliser le contenu global du document pour lever une ambiguïté ou déduire le code de devise.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Outre l’amélioration de la qualité du modèle, nous vous recommandons vivement de mettre à jour votre application pour utiliser la version 3.1 afin de tirer parti de ces nouvelles fonctionnalités.

Migration à partir des versions 2.1 ou 2.0

Intelligence documentaire v3.1 est la dernière version en disponibilité générale. Elle contient les fonctionnalités les plus riches et couvre la plupart des langues et types de documents, et dispose d’une qualité de modèle améliorée. Reportez-vous à la vue d’ensemble du modèle pour connaître les fonctionnalités disponibles dans la version 3.1.

À partir de la version 3.0, l’API REST Intelligence documentaire a été remaniée pour une meilleure convivialité. Dans cette section, découvrez les différences entre les versions 2.0, 2.1 et 3.1 de l’API Intelligence documentaire et comment passer à la version plus récente de l’API.

Attention

  • La version 2023-07-31 de l’API REST inclut un changement cassant dans le code JSON de la réponse d’analyse de l’API REST.
  • La propriété boundingBox est renommée polygon dans chaque instance.

Modifications apportées aux points de terminaison de l’API REST

L’API REST v3.1 combine les opérations d’analyse pour l’analyse de la disposition, les modèles prédéfinis et les modèles personnalisés au sein de deux opérations, en affectant documentModels et modelId à l’analyse de la disposition (prebuilt-layout) et aux modèles prédéfinis.

requête POST

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

Requête GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

Opération d’analyse

  • La charge utile de la demande et le modèle d’appel restent inchangés.
  • L’opération d’analyse spécifie le document d’entrée et les configurations spécifiques au contenu, et elle renvoie l’URL du résultat de l’analyse via l’en-tête Operation-Location de la réponse.
  • Interrogez cette URL de résultat d’analyse, via une requête GET, pour vérifier l’état de l’opération d’analyse (l’intervalle minimum recommandé entre les requêtes est d’une seconde).
  • En cas de réussite, l’état est défini sur « succeeded » et analyzeResult est renvoyé dans le corps de la réponse. Si des erreurs se produisent, l’état est défini sur failed et une erreur est renvoyée.
Modèle v2.0 v2.1 v3.1
Préfixe de l’URL de la demande https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Document général N/A N/A /documentModels/prebuilt-document:analyze
Disposition /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Personnalisée /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Facture N/A /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Réception /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Document d’identité N/A /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Carte de visite N/A /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 N/A N/A /documentModels/prebuilt-tax.us.w2:analyze
Carte d’assurance maladie N/A N/A /documentModels/prebuilt-healthInsuranceCard.us:analyze
Contrat N/A N/A /documentModels/prebuilt-contract:analyze

Corps de la demande d’analyse

Le contenu à analyser est fourni par le corps de la demande. L’URL ou les données codées en base64 peuvent être utilisées pour construire la requête.

Pour spécifier une URL web accessible publiquement, définissez Content-Type surapplication/json et envoyez le corps JSON suivant :

{
  "urlSource": "{urlPath}"
}

L’encodage en base 64 est également pris en charge dans Document Intelligence v3.0 :

{
  "base64Source": "{base64EncodedContent}"
}

Autres paramètres pris en charge

Paramètres qui continuent d’être pris en charge :

  • pages : analysez uniquement un sous-ensemble spécifique de pages dans le document. Liste des numéros de page indexés à partir du nombre 1 à analyser. Ex. "1-3,5,7-9"
  • locale : indicateur de paramètres régionaux pour la reconnaissance de texte et l’analyse de document. La valeur peut contenir uniquement le code de langue (par exemple, en, fr) ou la balise de langue BCP 47 (par exemple, « en-US »).

Paramètres qui ne sont plus pris en charge :

  • includeTextDetails

Le nouveau format de réponse est plus compact et la sortie complète est toujours renvoyée.

Modifications du résultat d’analyse

L’analyse de la réponse est refactorisée vers les résultats de haut niveau suivants pour prendre en charge les éléments multipages.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

Remarque

Les modifications apportées à la réponse analyzeResult incluent un certain nombre de modifications, comme le fait de passer d’une propriété de pages à une propriété de levier supérieur dans analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

Créer un modèle ou effectuer l'apprentissage d’un modèle

L’objet de modèle fait l’objet de trois mises à jour dans la nouvelle API

  • modelId est désormais une propriété qui peut être définie sur un modèle pour un nom lisible par l’utilisateur.
  • modelName est renommé description
  • buildMode est une nouvelle propriété dont la valeur est template pour les modèles de formulaire personnalisés ou neural pour les modèles neuraux personnalisés.

L’opération build est appelée pour effectuer l’apprentissage d’un modèle. La charge utile de la demande et le modèle d’appel restent inchangés. L’opération de génération spécifie le modèle et le jeu de données de formation, et elle renvoie le résultat via l’en-tête Operation-Location dans la réponse. Interrogez cette URL d’opération de modèle, via une requête GET, pour vérifier l’état de l’opération de génération (l’intervalle minimum recommandé entre les requêtes est d’une seconde). Contrairement à la version 2.1, cette URL n’est pas l’emplacement de la ressource du modèle. Au lieu de cela, l’URL du modèle peut être construite à partir du modelId donné, également récupéré dans la propriété resourceLocation de la réponse. En cas de réussite, l’état est défini sur succeeded et le résultat contient les informations sur le modèle personnalisé. Si des erreurs se produisent, l’état est défini sur failed et l’erreur est renvoyée.

Le code suivant est un exemple de demande de génération utilisant un jeton SAP. Notez la barre oblique de fin lorsque vous définissez le préfixe ou le chemin du dossier.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

Modifications apportées au modèle de composition

Le modèle de composition est maintenant limité à un seul niveau d’imbrication. Les modèles composés sont désormais cohérents avec les modèles personnalisés grâce à l’ajout des propriétés modelId et description.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

Modifications apportées au modèle de copie

Le modèle d’appel pour le modèle de copie reste inchangé :

  • Autorisez l’opération de copie avec la ressource cible qui appelle authorizeCopy. Désormais une requête POST.
  • Envoyez l’autorisation à la ressource source pour copier le modèle appelant copyTo.
  • Interrogez l’opération renvoyée pour valider l’opération terminée avec succès.

Les seules modifications apportées à la fonction du modèle de copie sont les suivantes :

  • L’action HTTP sur authorizeCopy est désormais une requête POST.
  • La charge utile d’autorisation contient toutes les informations nécessaires pour envoyer la demande de copie.

Autoriser la copie

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Utilisez le corps de réponse de l’action d’autorisation pour construire la demande de copie.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

Modifications apportées aux modèles de liste

Les modèles de liste sont étendus et renvoient désormais des modèles prédéfinis et personnalisés. Tous les noms de modèles prédéfinis commencent par prebuilt-. Seuls les modèles dont l’état est réussi sont renvoyés. Pour répertorier les modèles qui ont échoué ou qui sont en cours d’utilisation, consultez la section Opérations de liste.

Exemple de demande de modèles de liste

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

Modifications apportées au modèle Get

Étant donné que le modèle Get comprend désormais des modèles prédéfinis, l’opération Get renvoie un dictionnaire docTypes. Chaque description de type de document inclus un nom, une description facultative, un schéma de champ et une confiance facultative dans le champ. Le schéma de champ décrit la liste des champs potentiellement renvoyés avec le type de document.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Nouvelle opération Get info

L’opération info sur le service renvoie le nombre de modèles personnalisés et la limite de modèles personnalisés.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

Exemple de réponse

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

Étapes suivantes