Document Intelligence v4.0-migratie

SDk-migratiehandleidingen

Zie de taalspecifieke SDK-migratiehandleidingen in onze GitHub opslagplaatsen voor hulp bij het bijwerken van uw toepassingscode om de v4.0 SDK-SDK's te gebruiken. Deze handleidingen bevatten instructies voor het bijwerken van uw code om de nieuwe API-methoden aan te roepen en de bijgewerkte antwoordindelingen te verwerken die zijn geïntroduceerd in v4.0:

• .NET/C# SDK

• Java SDK

• Python SDK

• JavaScript/TypeScript SDK*

Migreren van v3.1 naar v4.0

Preview API's worden periodiek verouderd verklaard. Als u een preview-API-versie gebruikt, werkt u uw toepassing bij om de GA API-versie te targeten. Als u wilt migreren van een preview-API-versie naar de 2024-11-30 (GA) API-versie met behulp van de SDK, werkt u bij naar de huidige versie van de taalspecifieke SDK.

Analysefuncties

✓ - Ingeschakeld O - Optionele formules/StyleFont/OCR hoge resolutie* - Aan premiumfuncties zijn extra kosten verbonden

Migreren vanaf v3.0

In vergelijking met v3.0 introduceert Document Intelligence v3.1 verschillende nieuwe functies en mogelijkheden:

• Streepjescode-extractie.
• Invoegtoepassingsmogelijkheden , waaronder extractie van hoge resolutie, formule en lettertype-eigenschappen.
• Aangepast classificatiemodel voor het splitsen en classificeren van documenten.
• Taaluitbreiding en ondersteuning voor nieuwe velden in het factuur - en ontvangstbewijsmodel .
• Ondersteuning voor nieuw documenttype in id-documentmodel .
• Nieuw vooraf samengesteld model voor de gezondheidsverzekering .
• Office-/HTML-bestanden worden ondersteund in een vooraf gebouwd inleesmodel, waarbij woorden en alinea's zonder begrenzingsvakken worden geëxtraheerd. Ingesloten afbeeldingen worden niet meer ondersteund. Als er invoegtoepassingsfuncties worden aangevraagd voor Office-/HTML-bestanden, wordt er zonder fouten een lege matrix geretourneerd.
• Modelverlooptijd voor aangepaste extractie- en classificatiemodellen: onze nieuwe aangepaste modellen zijn gebaseerd op een groot basismodel dat we periodiek bijwerken voor kwaliteitsverbetering. Er wordt een vervaldatum geïntroduceerd voor alle aangepaste modellen om de buitengebruikstelling van de bijbehorende basismodellen mogelijk te maken. Zodra een aangepast model is verlopen, moet u het model opnieuw trainen met behulp van de nieuwste API-versie (basismodel).

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": { ... }
}

• Aangepaste quotumlimiet voor het bouwen van neurale modellen: er is een limiet aan het aantal neurale modellen dat elk abonnement per regio per maand kan bouwen. We breiden het resultaat-JSON uit om het quotum en de gebruikte informatie op te nemen, zodat u inzicht krijgt in het huidige gebruik als onderdeel van de resourcegegevens die worden geretourneerd door GET /info.

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• Een optionele features queryparameter voor analysebewerkingen kan desgewenst specifieke functies inschakelen. Sommige premiumfuncties kunnen extra kosten veroorzaken. Raadpleeg de lijst met functies analyseren voor meer informatie.
• Breid geëxtraheerde valutaveldobjecten uit om waar mogelijk een genormaliseerd valutacodeveld uit te voeren. Op dit moment kunnen velden een bedrag retourneren (bijvoorbeeld 123,45) en een valutasymbool (bijvoorbeeld $). Met deze functie wordt het valutasymbool toegewezen aan een canonieke ISO 4217-code (bijvoorbeeld USD). Het model kan eventueel de inhoud van het globale document gebruiken om de valutacode ondubbelzinnig te maken of af te stellen.

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Naast kwaliteitsverbetering van het model wordt u ten zeerste aangeraden uw toepassing bij te werken om v3.1 te gebruiken om te profiteren van deze nieuwe mogelijkheden.

Migreren vanaf v2.1 of v2.0

Document Intelligence v3.1 is de nieuwste GA-versie met de meest uitgebreide functies, de meeste talen en documenttypen en verbeterde modelkwaliteit. Raadpleeg het modeloverzicht voor de functies en mogelijkheden die beschikbaar zijn in v3.1.

Vanaf v3.0 is de Document Intelligence REST API opnieuw ontworpen voor betere bruikbaarheid. In deze sectie leert u de verschillen tussen Document Intelligence v2.0, v2.1 en v3.1 en hoe u naar de nieuwere versie van de API gaat.

Wijzigingen in de REST API-eindpunten

De REST API van v3.1 combineert de analysebewerkingen voor indelingsanalyse, voorgebouwde modellen en aangepaste modellen in een enkel paar bewerkingen door documentModels toe te wijzen aan indelingsanalyse en modelId aan voorgebouwde modellen.

POST-aanvraag

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

GET-aanvraag

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

Bewerking analyseren

• De payload en het aanroeppatroon van de aanvraag blijven ongewijzigd.
• Met de Analyze bewerking worden het invoerdocument en de inhoudsspecifieke configuraties opgegeven, waarna de geanalyseerde resultaat-URL wordt geretourneerd via de Operation-Location header in het antwoord.
• Poll de Analyze Result URL via een GET-aanvraag om de status van de Analyze bewerking te controleren (minimaal aanbevolen interval tussen aanvragen is 1 seconde).
• Bij succes wordt de status op succes gezet en analyzeResult wordt geretourneerd in de hoofdtekst van het antwoord. Als er fouten optreden, wordt de status ingesteld op faileden wordt er een fout geretourneerd.

Hoofdtekst van aanvraag analyseren

De inhoud die moet worden geanalyseerd, wordt geleverd via de aanvraagbody. Een URL of base64-gecodeerde gegevens kunnen worden gebruikt om het verzoek samen te stellen.

Als u een openbaar toegankelijke web-URL wilt opgeven, stelt u Content-Type in op toepassing/json en verzendt u de volgende JSON-hoofdtekst:

{
  "urlSource": "{urlPath}"
}

Base 64-codering wordt ook ondersteund in Document Intelligence v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Aanvullende ondersteunde parameters

Parameters die nog steeds worden ondersteund:

• pages : Analyseer alleen een specifieke subset van pagina's in het document. Lijst met paginanummers geïndexeerd van het te analyseren getal 1 . Ex. "1-3,5,7-9"
• locale : Hint voor landinstellingen voor tekstherkenning en documentanalyse. De waarde mag alleen de taalcode (bijvoorbeeld en of fr) of een BCP 47 taalcode-tag (bijvoorbeeld "en-US") bevatten.

Parameters worden niet meer ondersteund:

• includeTextDetails

De nieuwe antwoordindeling is compacter en de volledige uitvoer wordt altijd geretourneerd.

Wijzigingen om het resultaat te analyseren

De antwoordanalyse is geherstructureerd naar de volgende overzichtsniveau resultaten en ondersteunt elementen over meerdere pagina's.

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

{
// 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
}, ...
}
}, ...
]
}

Model bouwen of trainen

Het modelobject heeft drie updates in de nieuwe API

• modelId is nu een eigenschap die kan worden ingesteld op een model voor een voor mensen leesbare naam.
• modelName is hernoemd naar description
• buildMode is een nieuwe eigenschap met waarden voor template aangepaste formuliermodellen of neural voor aangepaste neurale modellen.

De build bewerking wordt aangeroepen om een model te trainen. De payload en het aanroeppatroon van de aanvraag blijven ongewijzigd. Met de buildbewerking wordt het model en de trainingsgegevensset opgegeven. Het resultaat wordt geretourneerd via de Operation-Location header in het antwoord. Peil deze modelbewerkings-URL via een GET-aanvraag om de status van de buildbewerking te controleren (minimaal aanbevolen interval tussen aanvragen is 1 seconde). In tegenstelling tot v2.1 is deze URL niet de resourcelocatie van het model. In plaats daarvan kan de model-URL worden samengesteld op basis van de opgegeven modelId, ook opgehaald uit de eigenschap resourceLocation in het antwoord. Als de operatie succesvol is, wordt de status ingesteld op succeeded en omvat het resultaat de informatie over het aangepaste model. Als er fouten optreden, wordt de status ingesteld op faileden wordt de fout geretourneerd.

De volgende code is een voorbeeld van een build-aanvraag met behulp van een SAS-token. Let op de sluitende slash bij het instellen van het voorvoegsel of mappad.

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/}"
  }
}

Wijzigingen in het opstellen van het model

Model samenstellen is nu beperkt tot één niveau van geneste structuren. Samengestelde modellen zijn nu consistent met aangepaste modellen met toevoeging van modelId en description eigenschappen.

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

Wijzigingen in het kopieermodel

Het aanroeppatroon voor het kopieermodel blijft ongewijzigd:

• Autoriseer de kopieerbewerking door de doelresource aan te roepen authorizeCopy. Nu een POST-aanvraag.
• Verzend de autorisatie aan de bronresource en kopieer de modelaanroep copyTo
• Controleer de status van de geretourneerde bewerking om te verifiëren of de bewerking succesvol is voltooid.

De enige wijzigingen in de kopieermodelfunctie zijn:

• HTTP-actie op de aanvraag authorizeCopy is nu een POST-aanvraag.
• De autorisatielading bevat alle informatie die nodig is om het kopieerverzoek in te dienen.

De kopie autoriseren

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

Gebruik de antwoordtekst van de autorisatieactie om de aanvraag voor de kopie samen te stellen.

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"
}

Wijzigingen in lijstmodellen

Lijstmodellen worden uitgebreid om nu zowel vooraf gebouwde als aangepaste modellen te retourneren. Alle vooraf gedefinieerde modelnamen beginnen met prebuilt-. Alleen modellen met de status Geslaagd worden geretourneerd. Zie List Operations om modellen weer te geven die zijn mislukt of in uitvoering zijn.

Aanvraag voor voorbeeldlijstmodellen

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

Wijzigen om modelbewerking te verkrijgen

Zoals Get Model nu vooraf gedefinieerde modellen bevat, retourneert de Get bewerking een docTypes woordenlijst. Elke beschrijving van het documenttype bevat naam, optionele beschrijving, veldschema en optionele veldvertrouwen. In het veldschema wordt de lijst met velden beschreven die mogelijk worden geretourneerd met het documenttype.

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

Nieuwe gegevens ophalen bewerking

De info bewerking op de service retourneert het aantal aangepaste modellen en de limiet van het aangepaste model.

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

Voorbeeldantwoord

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

Volgende stappen

• De nieuwe REST API controleren
• Wat is Document Intelligence?
• Quickstart voor Document Intelligence 0