Dokumentinformation v3.1-migrering

Artikel
10/16/2024

Det här innehållet gäller för: v4.0 (förhandsversion) v3.1 (GA) v3.0 (GA) v2.1 (GA)

Viktigt!

Document Intelligence REST API v3.1 introducerar icke-bakåtkompatibla ändringar i REST API-begäran och analyserar svars-JSON.

Migrera från förhandsversionen av API:et v3.1

Förhandsversions-API:er är regelbundet inaktuella. Om du använder en förhandsversion av API:et uppdaterar du programmet så att det riktar in sig på GA API-versionen. Om du vill migrera från API-versionen 2023-02-28-preview till 2023-07-31 (GA) API-versionen med hjälp av SDK uppdaterar du till den aktuella versionen av språkspecifik SDK.

API:et 2023-07-31 (GA) har några uppdateringar och ändringar från förhandsversionen av API:et:

De funktioner som är aktiverade som standard är begränsade till de som är nödvändiga för den specifika modellen med fördelen med minskad svarstid och svarsstorlek. Tillagda funktioner kan aktiveras via uppräkningsvärden i features parametern.
Vissa layoutfunktioner från fördefinierade läsfunktioner och keyValuePairs utöver fördefinierade{dokument,faktura} stöds inte längre.
Inaktivera streckkoder som standard för fördefinierad och fördefinierad layout, språk för fördefinierad läsning och keyValuePairs för fördefinierad faktura.
Extrahering av anteckningar tas bort.
Frågefält och vanliga namn på nyckel/värde-par tas bort.
Office-/HTML-filer stöds i en fördefinierad läsmodell och extraherar ord och stycken utan avgränsningsrutor. Inbäddade avbildningar stöds inte längre. Om tilläggsfunktioner begärs för Office-/HTML-filer returneras en tom matris utan fel.

Analysfunktioner

Model ID	Extrahering av text	Punkterna	Styckeroller	Markeringsmarkeringar	Tabeller	Nyckel/värde-par	Språk	Streckkoder	Dokumentanalys	Formler*	StyleFont*	HÖG UPPLÖSNING FÖR OCR*
prebuilt-read	✓	✓					O	O		O	O	O
fördefinierad layout	✓	✓	✓	✓	✓		O	O		O	O	O
prebuilt-document	✓	✓	✓	✓	✓	✓	O	O		O	O	O
prebuilt-businessCard	✓								✓
prebuilt-idDocument	✓						O	O	✓	O	O	O
fördefinierad faktura	✓			✓	✓	O	O	O	✓	O	O	O
fördefinierad kvitto	✓						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

√ - Aktiverad O – Valfria formler/StyleFont/OCR High Resolution* – Premium-funktioner medför extra kostnader

Migrera från v3.0

Jämfört med v3.0 introducerar Document Intelligence v3.1 flera nya funktioner:

Extrahering av streckkod .
Tilläggsfunktioner som extrahering av hög upplösning, formel och teckensnitt.
Anpassad klassificeringsmodell för dokumentdelning och klassificering.
Språkexpansion och nya fält stöds i faktura- och kvittomodellen .
Stöd för ny dokumenttyp i ID-dokumentmodell .
Ny fördefinierad modell för sjukförsäkringskort .
Office-/HTML-filer stöds i en fördefinierad läsmodell och extraherar ord och stycken utan avgränsningsrutor. Inbäddade avbildningar stöds inte längre. Om tilläggsfunktioner begärs för Office-/HTML-filer returneras en tom matris utan fel.
Modellförfallodatum för anpassade extraherings- och klassificeringsmodeller – Våra nya anpassade modeller bygger på en stor basmodell som vi uppdaterar regelbundet för kvalitetsförbättringar. Ett förfallodatum introduceras för alla anpassade modeller för att möjliggöra tillbakadragande av motsvarande basmodeller. När en anpassad modell upphör att gälla måste du träna om modellen med den senaste API-versionen (basmodell).

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

Versionskvot för anpassad neural modell – Antalet neurala modeller som varje prenumeration kan skapa per region varje månad är begränsat. Vi expanderar JSON-resultatet för att inkludera kvoten och använd information som hjälper dig att förstå den aktuella användningen som en del av resursinformationen som returneras av GET /info.

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

En valfri frågeparameter features för att analysera åtgärder kan eventuellt aktivera specifika funktioner. Vissa premiumfunktioner kan medföra extra fakturering. Mer information finns i Analysera funktionslista.
Utöka extraherade valutafältobjekt för att mata ut ett normaliserat valutakodfält när det är möjligt. För närvarande kan aktuella fält returnera belopp (till exempel 123,45) och currencySymbol (till exempel $). Den här funktionen mappar valutasymbolen till en kanonisk ISO 4217-kod (till exempel USD). Modellen kan också använda det globala dokumentinnehållet för att skilja eller härleda valutakoden.

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

Förutom att förbättra modellens kvalitet rekommenderar vi starkt att du uppdaterar programmet så att det använder v3.1 för att dra nytta av dessa nya funktioner.

Migrera från v2.1 eller v2.0

Document Intelligence v3.1 är den senaste ga-versionen med de rikaste funktionerna, de flesta språk och dokumenttyper och förbättrad modellkvalitet. Se modellöversikten för de funktioner som är tillgängliga i v3.1.

Från och med v3.0 görs REST API för dokumentinformation om för bättre användbarhet. I det här avsnittet lär du dig skillnaderna mellan Document Intelligence v2.0, v2.1 och v3.1 och hur du flyttar till den nyare versionen av API:et.

Varning

REST API 2023-07-31-versionen innehåller en icke-bakåtkompatibel ändring i REST API-analyssvaret JSON.
Egenskapen boundingBox har bytt namn till polygon i varje instans.

Ändringar i REST API-slutpunkterna

REST API:et v3.1 kombinerar analysåtgärderna för layoutanalys, fördefinierade modeller och anpassade modeller till ett enda åtgärdspar genom att documentModels tilldela och modelId till layoutanalysen och fördefinierade modeller.

POST-begäran

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

GET-begäranden

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

Analysera åtgärd

Nyttolasten och anropsmönstret för begäran förblir oförändrade.
Åtgärden Analysera anger indatadokumentet och innehållsspecifika konfigurationer. Den returnerar url:en för analysresultatet via rubriken Operation-Location i svaret.
Avsök den här URL:en för att analysera resultat via en GET-begäran för att kontrollera analysåtgärdens status (minsta rekommenderade intervall mellan begäranden är 1 sekund).
När det har lyckats är statusen klar och analyzeResult returneras i svarstexten. Om fel påträffas anges statusen till failedoch ett fel returneras.

Modell	V2.0	v2.1	v3.1
Begärande-URL-prefix	https://{your-form-recognizer-endpoint}/formrecognizer/v2.0	https://{your-form-recognizer-endpoint}/formrecognizer/v2.1	https://{your-form-recognizer-endpoint}/formrecognizer
Allmänt dokument	Saknas	Saknas	`/documentModels/prebuilt-document:analyze`
Layout	/layout/analysera	/layout/analysera	`/documentModels/prebuilt-layout:analyze`
Egen	/custom/models/{modelId}/analyze	/custom/{modelId}/analyze	`/documentModels/{modelId}:analyze`
Faktura	Ej tillämpligt	/prebuilt/invoice/analyze	`/documentModels/prebuilt-invoice:analyze`
Kvitto	/prebuilt/receipt/analyze	/prebuilt/receipt/analyze	`/documentModels/prebuilt-receipt:analyze`
ID-dokument	Ej tillämpligt	/prebuilt/idDocument/analyze	`/documentModels/prebuilt-idDocument:analyze`
Visitkort	Ej tillämpligt	/prebuilt/businessCard/analyze	`/documentModels/prebuilt-businessCard:analyze`
W-2	Saknas	Saknas	`/documentModels/prebuilt-tax.us.w2:analyze`
Sjukförsäkringskort	Saknas	Saknas	`/documentModels/prebuilt-healthInsuranceCard.us:analyze`
Kontrakt	Saknas	Saknas	`/documentModels/prebuilt-contract:analyze`

Analysera begärandetext

Innehållet som ska analyseras tillhandahålls via begärandetexten. Antingen kan URL:en eller base64-kodade data vara användare för att skapa begäran.

Om du vill ange en offentligt tillgänglig webb-URL anger du Content-Type till application/json och skickar följande JSON-brödtext:

{
  "urlSource": "{urlPath}"
}

Base 64-kodning stöds också i Document Intelligence v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parametrar som dessutom stöds

Parametrar som fortfarande stöds:

pages : Analysera endast en specifik delmängd av sidor i dokumentet. Lista över sidnummer som indexerats från talet 1 som ska analyseras. T.ex. "1-3,5,7-9"
locale : Språktips för textigenkänning och dokumentanalys. Värdet får bara innehålla språkkoden (t.ex. en, fr) eller BCP 47-språktaggen (t.ex. "en-US").

Parametrar stöds inte längre:

includeTextDetails

Det nya svarsformatet är mer kompakt och de fullständiga utdata returneras alltid.

Ändringar för att analysera resultat

Analysera svar omstruktureras till följande resultat på den översta nivån för att stödja flersidiga element.

pages
tables
keyValuePairs
entities
styles
documents

Kommentar

AnalyzeResult-svarsändringarna innehåller ett antal ändringar som att flytta upp från en egenskap för sidor till en toppspakegenskap i 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
}, ...
}
}, ...
]
}

Skapa eller träna modell

Modellobjektet har tre uppdateringar i det nya API:et

modelId är nu en egenskap som kan anges på en modell för ett läsbart mänskligt namn.
modelName har bytt namn till description
buildMode är en ny egenskap med värden template för anpassade formulärmodeller eller neural anpassade neurala modeller.

Åtgärden build anropas för att träna en modell. Nyttolasten och anropsmönstret för begäran förblir oförändrade. Byggåtgärden anger modell- och träningsdatauppsättningen, den returnerar resultatet via rubriken Operation-Location i svaret. Avsök den här modellåtgärdens URL via en GET-begäran för att kontrollera status för byggåtgärden (minsta rekommenderade intervall mellan begäranden är 1 sekund). Till skillnad från v2.1 är den här URL:en inte modellens resursplats. I stället kan modell-URL:en konstrueras från det angivna modelId:et, som också hämtas från egenskapen resourceLocation i svaret. När det har lyckats anges statusen till succeeded och resultatet innehåller den anpassade modellinformationen. Om fel påträffas anges statusen till failedoch felet returneras.

Följande kod är en exempelversionsbegäran med hjälp av en SAS-token. Observera det avslutande snedstrecket när du ställer in prefixet eller mappsökvägen.

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

Ändringar för att skapa modell

Modellsammanfattning är nu begränsad till en enda kapslingsnivå. Sammansatta modeller är nu konsekventa med anpassade modeller med tillägg av modelId och description egenskaper.

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

Ändringar i kopieringsmodellen

Anropsmönstret för kopieringsmodellen förblir oförändrat:

Auktorisera kopieringsåtgärden med målresursen som anropar authorizeCopy. Nu en POST-begäran.
Skicka auktoriseringen till källresursen för att kopiera modellanropet copyTo
Avsök den returnerade åtgärden för att verifiera att åtgärden har slutförts

De enda ändringarna i kopieringsmodellfunktionen är:

HTTP-åtgärden på authorizeCopy är nu en POST-begäran.
Nyttolasten för auktorisering innehåller all information som behövs för att skicka kopieringsbegäran.

Auktorisera kopian

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

Använd svarstexten från åtgärden auktorisera för att skapa begäran för kopian.

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

Ändringar i listmodeller

Listmodeller utökas till att nu returnera fördefinierade och anpassade modeller. Alla fördefinierade modellnamn börjar med prebuilt-. Endast modeller med statusen lyckades returneras. Information om modeller som antingen misslyckades eller pågår finns i Liståtgärder.

Exempel på begäran om listmodeller

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

Ändra för att hämta modell

Eftersom get-modellen nu innehåller fördefinierade modeller returnerar get-åtgärden en docTypes ordlista. Varje beskrivning av dokumenttyp innehåller namn, valfri beskrivning, fältschema och valfritt fältförtroende. Fältschemat beskriver listan över fält som eventuellt returneras med dokumenttypen.

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

Ny get info-åtgärd

Åtgärden info på tjänsten returnerar antalet anpassade modeller och gränsen för anpassade modeller.

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

Exempelsvar

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

Dela via