Delen via

Document Intelligence v3.1-migratie

  • Artikel

Deze inhoud is van toepassing op:Vinkjev4.0 (preview)Vinkjev3.1 (GA)Vinkjev3.0 (GA)Vinkjev2.1 (GA)

Belangrijk

Document Intelligence REST API v3.1 introduceert belangrijke wijzigingen in de REST API-aanvraag en analyseer antwoord-JSON.

Migreren vanaf versie v3.1 preview-API

Preview-API's worden periodiek afgeschaft. Als u een preview-API-versie gebruikt, werkt u uw toepassing bij om de GA API-versie te targeten. Als u wilt migreren van de API-versie 2023-02-28-preview naar de 2023-07-31 API-versie (GA) met behulp van de SDK, werkt u bij naar de huidige versie van de taalspecifieke SDK.

De 2023-07-31 (GA) API heeft enkele updates en wijzigingen van de preview-API-versie:

  • De functies die standaard zijn ingeschakeld, zijn beperkt tot functies die essentieel zijn voor het specifieke model met het voordeel van verminderde latentie en responsgrootte. Toegevoegde functies kunnen worden ingeschakeld via enumwaarden in features parameter.
  • Sommige indelingsfuncties van vooraf gedefinieerde lees- en keyValuePairs buiten vooraf samengestelde-{document,factuur} worden niet meer ondersteund.
  • Streepjescodes standaard uitschakelen voor vooraf gedefinieerde en vooraf gedefinieerde indeling, talen voor vooraf gedefinieerde lees- en keyValuePairs voor vooraf samengestelde facturen.
  • Aantekeningextractie wordt verwijderd.
  • Queryvelden en algemene namen van sleutel-waardeparen worden verwijderd.
  • Office-/HTML-bestanden worden ondersteund in een vooraf samengesteld model, 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.

Analysefuncties

Model-id Tekstextractie Leden Alinearollen Selectiemarkeringen Tabellen Sleutel-waardeparen Talen Barcodes Documentanalyse Formules* StyleFont* OCR Hoge resolutie*
vooraf gedefinieerde leesbewerking ✓ ✓ O O O O O
vooraf gedefinieerde indeling ✓ ✓ ✓ ✓ ✓ O O O O O
vooraf samengesteld document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
vooraf samengestelde businessCard ✓ ✓
vooraf samengesteld-idDocument ✓ O O ✓ O O O
vooraf samengestelde factuur ✓ ✓ ✓ O O O ✓ O O O
vooraf samengestelde ontvangstbevestiging ✓ 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
vooraf samengesteld contract ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - IngeschakeldE O - Optionele formules/StyleFont/OCR High Resolution* - Premium-functies maken extra kosten

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 samengesteld model, 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": { ... }
}
  • Aangepast quotum voor neurale modelbuild: het aantal neurale modellen dat elk abonnement elke maand per regio kan bouwen, is beperkt. 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 Premium-functies kunnen extra facturering in rekening worden gebracht. 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 huidige velden een bedrag retourneren (bijvoorbeeld 123,45) en currencySymbol (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.

Let op

  • REST API 2023-07-31-release bevat een belangrijke wijziging in de REST API-analyse van antwoord-JSON.
  • De naam van de boundingBox eigenschap wordt polygon gewijzigd in elk exemplaar.

Wijzigingen in de REST API-eindpunten

De REST API v3.1 combineert de analysebewerkingen voor indelingsanalyse, vooraf samengestelde modellen en aangepaste modellen in één paar bewerkingen door de indelingsanalyse (vooraf gedefinieerde indeling) en vooraf gemaakte modellen toe te wijzen en modelId aan de indelingsanalyse toe te wijzendocumentModels.

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 nettolading en het aanroeppatroon van de aanvraag blijven ongewijzigd.
  • Met de bewerking Analyseren worden het invoerdocument en de inhoudsspecifieke configuraties opgegeven. De resultaat-URL wordt geretourneerd via de header Operation-Location in het antwoord.
  • Peil deze analyseresultaten-URL via een GET-aanvraag om de status van de analysebewerking te controleren (minimaal aanbevolen interval tussen aanvragen is 1 seconde).
  • Wanneer de status is geslaagd, wordt de status ingesteld op geslaagd en wordt analyzeResult geretourneerd in de hoofdtekst van het antwoord. Als er fouten optreden, wordt de status ingesteld op faileden wordt er een fout geretourneerd.
Model v2.0 v2.1 v3.1
Aanvraag-URL-voorvoegsel https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Algemeen document N.v.t. N.v.t. /documentModels/prebuilt-document:analyze
Indeling /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Aangepast /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Factuur N.v.t. /vooraf samengesteld/factuur/analyseren /documentModels/prebuilt-invoice:analyze
Ontvangst /vooraf samengesteld/ontvangstbewijs/analyseren /vooraf samengesteld/ontvangstbewijs/analyseren /documentModels/prebuilt-receipt:analyze
Id-document N.v.t. /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Visitekaartje N.v.t. /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 N.v.t. N.v.t. /documentModels/prebuilt-tax.us.w2:analyze
Ziekteverzekeringskaart N.v.t. N.v.t. /documentModels/prebuilt-healthInsuranceCard.us:analyze
Contract N.v.t. N.v.t. /documentModels/prebuilt-contract:analyze

Hoofdtekst van aanvraag analyseren

De inhoud die moet worden geanalyseerd, wordt geleverd via de aanvraagbody. De URL- of base64-gecodeerde gegevens kunnen een gebruiker zijn om de aanvraag 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 . Bijvoorbeeld: "1-3,5,7-9"
  • locale : Hint voor landinstellingen voor tekstherkenning en documentanalyse. De waarde mag alleen de taalcode (bijvoorbeeld en, fr) of BCP 47-taaltag (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

Het antwoord analyseren wordt geherstructureerd naar de volgende resultaten op het hoogste niveau ter ondersteuning van elementen met meerdere pagina's.

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

Notitie

De wijzigingen in het antwoord analyzeResult bevatten een aantal wijzigingen, zoals het omhoog verplaatsen van een eigenschap van pagina's naar een eigenschap van de bovenste lever binnen 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
}, ...
}
}, ...
]
}

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 in 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 nettolading en het aanroeppatroon van de aanvraag blijven ongewijzigd. Met de buildbewerking wordt het model en de trainingsgegevensset opgegeven. Het resultaat wordt geretourneerd via de header Operation-Location 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. Wanneer de status is geslaagd, wordt de status ingesteld op succeeded en bevat het resultaat de gegevens van 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. Noteer de afsluitende 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 opstellen is nu beperkt tot één niveau van nesten. 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 kopiëren van model

Het aanroeppatroon voor het kopieermodel blijft ongewijzigd:

  • Autoriseren van de kopieerbewerking met de doelresource die wordt aangeroepen authorizeCopy. Nu een POST-aanvraag.
  • Verzend de autorisatie naar de bronresource om het model aanroepen te kopiëren copyTo
  • De geretourneerde bewerking controleren om te controleren of de bewerking is voltooid

De enige wijzigingen in de kopieermodelfunctie zijn:

  • HTTP-actie op de aanvraag authorizeCopy is nu een POST-aanvraag.
  • De nettolading van de autorisatie bevat alle informatie die nodig is om de kopieeraanvraag 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 vooraf gemaakte en aangepaste modellen te retourneren. Alle vooraf gedefinieerde modelnamen beginnen met prebuilt-. Alleen modellen met de status Geslaagd worden geretourneerd. Zie Lijstbewerkingen om modellen weer te geven die zijn mislukt of worden uitgevoerd.

Aanvraag voor voorbeeldlijstmodellen

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

Wijzigen om het model op te halen

Omdat het 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

Bewerking Gegevens ophalen nieuw

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

Voorbeeldrespons

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

Volgende stappen