Migrace Document Intelligence v3.1

Tento obsah se vztahuje na: v4.0 (Preview) v3.1 (GA) v3.0 (GA) v2.1 (GA)

Důležité

Rozhraní REST API document Intelligence verze 3.1 zavádí zásadní změny v požadavku rozhraní REST API a analyzuje JSON odpovědi.

Migrace z verze rozhraní API verze 3.1 Preview

Rozhraní API ve verzi Preview jsou pravidelně zastaralá. Pokud používáte verzi rozhraní API ve verzi Preview, aktualizujte aplikaci tak, aby cílila na verzi rozhraní GA API. Pokud chcete migrovat z verze rozhraní API verze 2023-02-28-Preview na 2023-07-31 verzi rozhraní API (GA) pomocí sady SDK, aktualizujte na aktuální verzi sady SDK pro konkrétní jazyk.

Rozhraní 2023-07-31 API (GA) má několik aktualizací a změn z verze Preview API:

• Funkce, které jsou ve výchozím nastavení povolené, jsou omezené na funkce nezbytné pro konkrétní model s výhodou snížené latence a velikosti odpovědi. Přidané funkce je možné povolit prostřednictvím hodnot výčtu v parametru features .
• Některé funkce rozložení z předem připravených hodnot read a keyValuePairs nad rámec předem připraveného dokumentu,faktura} se už nepodporují.
• Zakázání čárových kódů ve výchozím nastavení pro předem připravené rozložení a předem připravené rozložení, jazyky pro předem připravenou čtení a keyValuePairs pro předem připravenou fakturu
• Extrakce poznámek se odebere.
• Pole dotazu a běžné názvy párů klíč-hodnota se odeberou.
• Soubory Office/HTML jsou podporovány v předem vytvořeném modelu čtení, extrahování slov a odstavců bez ohraničování polí. Vložené image se už nepodporují. Pokud jsou pro soubory Office/HTML požadovány funkce doplňků, vrátí se prázdné pole bez chyb.

Funkce analýzy

ID modelu	Extrakce textu	Odstavce	Role odstavce	Značky výběru	Tabulky	Páry klíč-hodnota	Jazyky	Čárové kódy	Analýza dokumentů	Formule*	StyleFont*	Vysoké rozlišení OCR*
předem připravená čtení	✓	✓					O	O		O	O	O
předem připravené rozložení	✓	✓	✓	✓	✓		O	O		O	O	O
předem připravený dokument	✓	✓	✓	✓	✓	✓	O	O		O	O	O
předem připravená vizitka	✓								✓
prebuilt-idDocument	✓						O	O	✓	O	O	O
předem připravená faktura	✓			✓	✓	O	O	O	✓	O	O	O
předem připravená potvrzení	✓						O	O	✓	O	O	O
prebuilt-healthInsuranceCard.us	✓						O	O	✓	O	O	O
prebuilt-tax.us.w2	✓			✓			O	O	✓	O	O	O
předem připravená-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
předem připravená smlouva	✓	✓	✓	✓			O	O	✓	O	O	O
{ customModelName }	✓	✓	✓	✓	✓		O	O	✓	O	O	O

– Povolený O - Volitelné vzorce/StyleFont/OCR High Resolution* – Funkce Premium se účtují přidaných nákladů.

Migrace z verze 3.0

Ve srovnání s v3.0 přináší funkce Document Intelligence verze 3.1 několik nových funkcí a možností:

• Extrakce čárových kódů .
• Možnosti doplňků, včetně extrakce vlastností s vysokým rozlišením, vzorcem a písmem
• Vlastní klasifikační model pro rozdělení a klasifikaci dokumentu
• Rozšíření jazyka a nová pole podporují v modelu faktury a účtenky .
• Podpora nového typu dokumentu v modelu dokumentu ID
• Nový předem připravený model zdravotní pojištění.
• Soubory Office/HTML jsou podporovány v předem vytvořeném modelu čtení, extrahování slov a odstavců bez ohraničování polí. Vložené image se už nepodporují. Pokud jsou pro soubory Office/HTML požadovány funkce doplňků, vrátí se prázdné pole bez chyb.
• Vypršení platnosti modelu pro vlastní modely extrakce a klasifikace – naše nové vlastní modely vycházejí z velkého základního modelu, který pravidelně aktualizujeme pro zlepšení kvality. Ve všech vlastních modelech se zavádí datum vypršení platnosti, aby se umožnilo vyřazení odpovídajících základních modelů. Po vypršení platnosti vlastního modelu je potřeba model znovu natrénovat pomocí nejnovější verze rozhraní API (základní model).

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

• Kvóta sestavení vlastního neurálního modelu – počet neurálních modelů, které může každé předplatné sestavit každý měsíc, je omezené. Rozšíříme kód JSON výsledku tak, aby zahrnoval kvótu a použité informace, které vám pomůžou porozumět aktuálnímu využití v rámci informací o prostředcích vrácených rutinou GET /info.

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

• Volitelný features parametr dotazu pro operace Analyzovat může volitelně povolit konkrétní funkce. Některé prémiové funkce můžou mít přidanou fakturaci. Podrobnosti najdete v seznamu funkcí Analyzovat.
• Pokud je to možné, rozšiřte extrahované objekty pole měny a vypíšete normalizované pole kódu měny. V současné době můžou aktuální pole vracet částku (např. 123,45) a měnuSymbol (např. $). Tato funkce mapuje symbol měny na kanonický kód ISO 4217 (např. USD). Model může volitelně využít globální obsah dokumentu k nejednoznačnosti nebo odvození kódu měny.

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

Kromě vylepšení kvality modelu důrazně doporučujeme aktualizovat aplikaci tak, aby používala verzi 3.1, aby tyto nové funkce využívala.

Migrace z verze 2.1 nebo v2.0

Document Intelligence v3.1 je nejnovější verze GA s nejbohatšími funkcemi, většinou jazyků a typů dokumentů a vylepšenou kvalitou modelu. Informace o funkcích a možnostech dostupných ve verzi 3.1 najdete v přehledu modelů.

Od verze 3.0 je rozhraní REST API document intelligence přepracované pro lepší použitelnost. V této části se seznámíte s rozdíly mezi funkcemi Document Intelligence v2.0, v2.1 a v3.1 a novými verzemi rozhraní API.

Upozornění

• Verze REST API 2023-07-31 obsahuje zásadní změnu v rozhraní REST API pro analýzu kódu JSON odpovědi.
• Vlastnost boundingBox se v každé instanci přejmenuje polygon .

Změny koncových bodů rozhraní REST API

Rozhraní REST API verze 3.1 kombinuje analytické operace pro analýzu rozložení, předem připravené modely a vlastní modely do jedné dvojice operací přiřazením documentModels a modelId předpřipravenými modely.

Požadavek POST

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

Požadavek GET

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

Analýza operace

• Datová část požadavku a vzor volání zůstávají beze změny.
• Operace Analyzovat určuje vstupní dokument a konfigurace specifické pro obsah, vrátí adresu URL výsledku analýzy prostřednictvím hlavičky Operation-Location v odpovědi.
• Dotazujte se na tuto adresu URL analýzy výsledků prostřednictvím požadavku GET a zkontrolujte stav operace analýzy (minimální doporučený interval mezi požadavky je 1 sekunda).
• Po úspěchu je stav nastavený na úspěch a funkce analyzeResult se vrátí v textu odpovědi. Pokud dojde k chybám, stav se nastaví na faileda vrátí se chyba.

Model	v2.0	v2.1	v3.1
Předpona adresy URL požadavku	https://{your-form-recognizer-endpoint}/formrecognizer/v2.0	https://{your-form-recognizer-endpoint}/formrecognizer/v2.1	https://{your-form-recognizer-endpoint}/formrecognizer
Obecný dokument	–	N/A	/documentModels/prebuilt-document:analyze
Rozložení	/layout/analyze	/layout/analyze	/documentModels/prebuilt-layout:analyze
Vlastní	/custom/models/{modelId}/analyze	/custom/{modelId}/analyze	/documentModels/{modelId}:analyze
Faktura	–	/předem připravená faktura/analýza	/documentModels/prebuilt-invoice:analyze
Paragon	/předem připravená/účtenka/analýza	/předem připravená/účtenka/analýza	/documentModels/prebuilt-receipt:analyze
Průkaz totožnosti	–	/prebuilt/idDocument/analyze	/documentModels/prebuilt-idDocument:analyze
Vizitka	–	/prebuilt/businessCard/analyze	/documentModels/prebuilt-businessCard:analyze
Daňové přiznání	–	N/A	/documentModels/prebuilt-tax.us.w2:analyze
Zdravotní pojištění	–	N/A	/documentModels/prebuilt-healthInsuranceCard.us:analyze
Smlouva	–	N/A	/documentModels/prebuilt-contract:analyze

Analýza textu požadavku

Obsah, který se má analyzovat, se poskytuje prostřednictvím textu požadavku. Kódovaná data adresy URL nebo base64 mohou být uživatelem k vytvoření požadavku.

Pokud chcete zadat veřejně přístupnou webovou adresu URL, nastavte Content-Type na application/json a odešlete následující text JSON:

{
  "urlSource": "{urlPath}"
}

Kódování Base 64 je také podporováno v document Intelligence verze 3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Další podporované parametry

Parametry, které se nadále podporují:

• pages : Analyzujte pouze určitou podmnožinu stránek v dokumentu. Seznam čísel stránek indexovaných z čísla 1 k analýze Například "1-3,5,7-9"
• locale : Nápověda k národnímu prostředí pro rozpoznávání textu a analýzu dokumentů. Hodnota může obsahovat pouze kód jazyka (např. en, fr) nebo značku jazyka BCP 47 (např. en-US).

Parametry se už nepodporují:

• includeTextDetails

Nový formát odpovědi je kompaktnější a úplný výstup se vždy vrátí.

Změny analýzy výsledku

Analýza odpovědi je refaktorována na následující výsledky nejvyšší úrovně pro podporu vícestrákových prvků.

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

Poznámka:

Změny odpovědi analyzeResult zahrnují řadu změn, jako je přechod z vlastnosti stránek na vlastnost horní páky v rámci 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
}, ...
}
}, ...
]
}

Sestavení nebo trénování modelu

Objekt modelu má v novém rozhraní API tři aktualizace.

• modelId je teď vlastnost, která se dá nastavit v modelu pro čitelný název člověka.
• modelName přejmenová se na description
• buildMode je nová vlastnost s hodnotami template pro vlastní modely formulářů nebo neural pro vlastní neurální modely.

Operace build se vyvolá k trénování modelu. Datová část požadavku a vzor volání zůstávají beze změny. Operace sestavení určuje model a trénovací datovou sadu, vrátí výsledek prostřednictvím hlavičky Operation-Location v odpovědi. Dotazování této adresy URL operace modelu prostřednictvím požadavku GET za účelem kontroly stavu operace sestavení (minimální doporučený interval mezi požadavky je 1 sekunda). Na rozdíl od verze 2.1 tato adresa URL není umístěním prostředku modelu. Místo toho lze adresu URL modelu vytvořit z daného id modelu, také načtena z vlastnosti resourceLocation v odpovědi. Po úspěchu se stav nastaví na succeeded hodnotu a výsledek bude obsahovat informace o vlastním modelu. Pokud dojde k chybám, stav je nastaven na failedhodnotu a vrátí se chyba.

Následující kód je ukázkový požadavek na sestavení pomocí tokenu SAS. Při nastavování předpony nebo cesty ke složce si všimněte koncového lomítka.

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

Změny při vytváření modelu

Vytváření modelů je teď omezené na jednu úroveň vnoření. Složené modely jsou teď konzistentní s vlastními modely s přidáním modelId a description vlastnostmi.

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

Změny v modelu kopírování

Model volání pro model kopírování zůstává beze změny:

• Autorizovat operaci kopírování s voláním authorizeCopycílového prostředku . Teď je žádost POST.
• Odešlete autorizaci do zdrojového prostředku a zkopírujte volání modelu. copyTo
• Dotazování vrácené operace za účelem ověření úspěšné operace

Jedinými změnami funkce modelu kopírování jsou:

• Akce HTTP pro tuto authorizeCopy akci je nyní požadavkem POST.
• Datová část autorizace obsahuje všechny informace potřebné k odeslání žádosti o kopírování.

Autorizace kopie

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

Pomocí textu odpovědi z autorizované akce vytvořte požadavek na kopii.

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

Změny modelů seznamů

Modely seznamu se teď rozšiřují tak, aby vracely předem připravené a vlastní modely. Všechny předem vytvořené názvy modelů začínají na prebuilt-. Vrátí se pouze modely se stavem úspěchu. Pokud chcete zobrazit seznam modelů, které selhaly nebo probíhají, podívejte se na seznam operací.

Ukázka požadavku na modely seznamů

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

Změna pro získání modelu

Jak model get nyní obsahuje předem připravené modely, vrátí docTypes operace get slovník. Každý popis typu dokumentu zahrnuje název, volitelný popis, schéma pole a volitelnou spolehlivost polí. Schéma pole popisuje seznam polí, která mohou být vrácena typem dokumentu.

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

Nová operace získání informací

Operace info ve službě vrátí počet vlastních modelů a limit vlastního modelu.

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

Ukázková odpověď

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

Další kroky

• Kontrola nového rozhraní REST API
• Co je funkce Document Intelligence?
• Rychlý start k funkci Document Intelligence