Document Intelligence v3.1 migrálása

Cikk
11/21/2023

Ez a tartalom a következőre vonatkozik::v4.0 (előzetes verzió)v3.1 (GA)v3.0 (GA)v2.1 (GA)

Fontos

A Document Intelligence REST API 3.1-es verziójú kompatibilitástörő változásokat vezet be a REST API-kérésben, és elemzi a válasz JSON-t.

Migrálás a 3.1-es verziójú előzetes API-verzióról

Az előzetes verziójú API-k rendszeresen elavultak. Ha előzetes verziójú API-t használ, frissítse az alkalmazást a GA API-verzió megcélzásához. A 2023-02-28 előzetes verziójú API-verzióról a 2023-07-31 (GA) API-verzióra való migráláshoz az SDK használatával frissítsen a nyelvspecifikus SDK aktuális verziójára.

A 2023-07-31 (GA) API néhány frissítéssel és módosítással rendelkezik az előzetes verziójú API-ról:

Az alapértelmezés szerint engedélyezett funkciók az adott modellhez elengedhetetlen funkciókra korlátozódnak, a késés és a válaszméret csökkentése érdekében. A hozzáadott funkciók a paraméter enumerálási értékeivel features engedélyezhetők.
Az előre összeállított olvasási és keyValuePairs-elemek egyes elrendezési funkciói már nem támogatottak a(z) {document,invoice} előkészületen túl.
A vonalkódok alapértelmezés szerint letiltása az előre felépített és előre összeállított elrendezéshez, az előre felolvasott nyelvekhez és a keyValuePairshez az előre összeállított számlához.
A széljegyzetek kinyerése el lesz távolítva.
A rendszer eltávolítja a lekérdezésmezőket és a kulcs-érték párok közös nevét.
Az Office-/HTML-fájlok előre összeállított olvasott modellben támogatottak, és határolókeretek nélkül nyernek ki szavakat és bekezdéseket. A beágyazott képek már nem támogatottak. Ha office-/HTML-fájlok bővítményfunkcióira van szükség, a rendszer hiba nélkül visszaad egy üres tömböt.

Elemzési funkciók

Modellazonosító	Szöveg kinyerése	Bekezdések	Bekezdésszerepkörök	Kijelölési jelek	Táblák	Kulcs-érték párok	Nyelvek	Vonalkódok	Dokumentumelemzés	Képletek*	StyleFont*	OCR nagy felbontású*
előre összeállított olvasás	✓	✓					O	O		O	O	O
előre összeállított elrendezés	✓	✓	✓	✓	✓		O	O		O	O	O
előre összeállított dokumentum	✓	✓	✓	✓	✓	✓	O	O		O	O	O
előre összeállított-businessCard	✓								✓
előre összeállított-idDocument	✓						O	O	✓	O	O	O
előre összeállított számla	✓			✓	✓	O	O	O	✓	O	O	O
előre összeállított nyugta	✓						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
előre összeállított szerződés	✓	✓	✓	✓			O	O	✓	O	O	O
{ customModelName }	✓	✓	✓	✓	✓		O	O	✓	O	O	O

✓ – Engedélyezett O – Választható képletek/StyleFont/OCR Nagy felbontás* – A prémium funkciók többletköltséggel járnak

Migrálás a 3.0-s verzióról

A 3.0-s verzióval összehasonlítva a Document Intelligence 3.1-ben számos új funkció és képesség érhető el:

Vonalkód kinyerése.
A bővítmény képességei , beleértve a nagy felbontást, a képleteket és a betűtulajdonságokat.
Egyéni besorolási modell a dokumentumok felosztásához és besorolásához.
A nyelvbővítés és az új mezők támogatják a számla- és nyugtamodellt.
Új dokumentumtípus-támogatás az azonosító dokumentummodellben.
Új előre összeállított egészségbiztosítási kártyamodell .
Az Office-/HTML-fájlok előre összeállított olvasott modellben támogatottak, és határolókeretek nélkül nyernek ki szavakat és bekezdéseket. A beágyazott képek már nem támogatottak. Ha office-/HTML-fájlok bővítményfunkcióira van szükség, a rendszer hiba nélkül visszaad egy üres tömböt.
Modell lejárata egyéni kinyerési és besorolási modellekhez – Az új egyéni modellek egy nagy alapmodellre épülnek, amelyet rendszeresen frissítünk a minőség javítása érdekében. A lejárati dátum minden egyéni modellben megjelenik, hogy lehetővé tegye a megfelelő alapmodellek kivonását. Ha egy egyéni modell lejár, újra be kell tanítania a modellt a legújabb API-verzióval (alapmodell).

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

Egyéni neurális modell buildkvótája – Az előfizetésenként létrehozható neurális modellek száma régiónként korlátozott. Az eredmény JSON-ját kibővítjük, hogy tartalmazza a kvótát, és a get /info által visszaadott erőforrás-információk részeként az aktuális használat megértéséhez használt információkat használjuk fel.

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

Az elemzési műveletek opcionális features lekérdezési paramétere opcionálisan engedélyezhet bizonyos funkciókat. Egyes prémium funkciókhoz hozzá lehet adni a számlázást. Részletekért tekintse meg az Elemzés funkciólistát .
Ha lehetséges, kiterjesztheti a kinyert pénznem mezőobjektumait egy normalizált pénznemkódmező kimenetére. Az aktuális mezők jelenleg az összeget (például 123,45) és a currencySymbol (pl. $) értéket adhatják vissza. Ez a funkció leképzi a pénznemszimbólumot egy canonical ISO 4217 kódra (pl. USD). A modell használhatja a globális dokumentum tartalmát a pénznemkód egyértelműsítésére vagy következtetésére.

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

A modellminőség javítása mellett erősen ajánlott frissítenie az alkalmazást, hogy a 3.1-et használja az új képességek előnyeinek kihasználásához.

Migrálás 2.1-ről vagy 2.0-s verzióról

A Document Intelligence 3.1-es verziója a legújabb GA-verzió, a leggazdagabb funkciókkal, a legtöbb nyelvvel és dokumentumtípussal, valamint a jobb modellminőséggel. Tekintse meg a modell áttekintését a 3.1-ben elérhető funkciókról és képességekről.

A 3.0-s verziótól kezdve a Document Intelligence REST API újra van tervezve a jobb használhatóság érdekében. Ebben a szakaszban megismerheti a Document Intelligence 2.0-s, 2.1-es és 3.1-es verziójának különbségeit, és megtudhatja, hogyan válthat az API újabb verziójára.

Figyelem

A REST API 2023-07-31 kiadás kompatibilitástörő változást tartalmaz a REST API analyze response JSON-ban.
A boundingBox tulajdonság minden példányban át lesz polygon nevezve.

A REST API-végpontok módosítása

A v3.1 REST API egyetlen műveletpárba egyesíti az elemzési műveleteket az elrendezéselemzéshez, az előre összeállított modellekhez és az egyéni modellekhez az elrendezéselemzés (előre összeállított elrendezés) és az előre összeállított modellek hozzárendelésével documentModelsmodelId .

POST kérés

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

GET kérés

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

Elemzési művelet

A kérelem hasznos adatai és hívási mintája változatlan marad.
Az Elemzés művelet megadja a bemeneti dokumentumot és a tartalomspecifikus konfigurációkat, az elemzés eredményének URL-címét a válasz Művelet helye fejlécén keresztül adja vissza.
Az elemzési eredmény URL-címének lekérdezése get kéréssel az elemzési művelet állapotának ellenőrzéséhez (a kérések közötti minimális ajánlott időköz 1 másodperc).
Sikeresség esetén az állapot sikeres lesz, és az analyzeResult a válasz törzsében lesz visszaadva. Ha hiba történik, az állapot a következőre failedvan adva, és a rendszer hibát ad vissza.

Modell	2.0-s verzió	2.1-s verzió	3.1-s verzió
URL-előtag kérése	https://{your-form-recognizer-endpoint}/formrecognizer/v2.0	https://{your-form-recognizer-endpoint}/formrecognizer/v2.1	https://{your-form-recognizer-endpoint}/formrecognizer
Általános dokumentum	N.A.	N.A.	`/documentModels/prebuilt-document:analyze`
Elrendezés	/layout/analyze	/layout/analyze	`/documentModels/prebuilt-layout:analyze`
Szokás	/custom/models/{modelId}/analyze	/custom/{modelId}/analyze	`/documentModels/{modelId}:analyze`
Számla	N/A	/előre összeállított/számla/elemzés	`/documentModels/prebuilt-invoice:analyze`
Beérkezési	/előre összeállított/nyugta/elemzés	/előre összeállított/nyugta/elemzés	`/documentModels/prebuilt-receipt:analyze`
Személyazonosító okmányok	N/A	/előre összeállított/idDocument/analyze	`/documentModels/prebuilt-idDocument:analyze`
Névjegykártya	N/A	/előre összeállított/businessCard/analyze	`/documentModels/prebuilt-businessCard:analyze`
W-2-nyomtatványok	N.A.	N.A.	`/documentModels/prebuilt-tax.us.w2:analyze`
Egészségbiztosítási kártya	N.A.	N.A.	`/documentModels/prebuilt-healthInsuranceCard.us:analyze`
Szerződés	N.A.	N.A.	`/documentModels/prebuilt-contract:analyze`

Kérelem törzsének elemzése

Az elemezni kívánt tartalom a kérelem törzsén keresztül érhető el. Az URL-cím vagy a base64 kódolású adatok lehetnek felhasználók a kérés létrehozásához.

Nyilvánosan elérhető webes URL-cím megadásához állítsa be a Content-Type értéket alkalmazásra/jsonra , és küldje el a következő JSON-törzset:

{
  "urlSource": "{urlPath}"
}

A 64-es alapkódolás a Document Intelligence 3.0-s verzióban is támogatott:

{
  "base64Source": "{base64EncodedContent}"
}

További támogatott paraméterek

A továbbra is támogatott paraméterek:

pages : A dokumentum lapjainak csak egy adott részhalmazát elemezheti. Az elemzendő számból 1 indexelt oldalszámok listája. Ex. "1-3,5,7-9"
locale : Területi tipp szövegfelismeréshez és dokumentumelemzéshez. Az érték csak a nyelvi kódot (pl. en, fr) vagy a BCP 47 nyelvi címkét (pl. "en-US") tartalmazhatja.

A paraméterek már nem támogatottak:

includeTextDetails

Az új válaszformátum kompaktabb, és a teljes kimenet mindig vissza lesz adva.

Az eredmény elemzésének módosításai

Az elemzési válasz újrabontása a következő felső szintű eredményekre történik a többoldalas elemek támogatásához.

pages
tables
keyValuePairs
entities
styles
documents

Megjegyzés:

Az analyzeResult válaszmódosítások számos módosítást tartalmaznak, például a lapok tulajdonságáról az analyzeResult felső kar tulajdonságára való áttérést.


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

Modell összeállítása vagy betanítása

A modellobjektum három frissítést kapott az új API-ban

modelId mostantól egy olyan tulajdonság, amely beállítható egy modellen egy olvasható névhez.
modelName a átnevezve description
buildModeaz egyéni űrlapmodellek vagy neural az egyéni neurális modellek értékeit template tartalmazó új tulajdonság.

A build rendszer meghívja a műveletet egy modell betanításához. A kérelem hasznos adatai és hívási mintája változatlan marad. A buildelési művelet meghatározza a modellt és a betanítási adatkészletet, az eredményt a válasz Művelet helye fejlécén keresztül adja vissza. A modellművelet URL-címének lekérdezése get kéréssel a buildelési művelet állapotának ellenőrzéséhez (a kérések közötti minimális ajánlott időköz 1 másodperc). A 2.1-s verziótól eltérően ez az URL-cím nem a modell erőforrás-helye. Ehelyett a modell URL-címe az adott modelId azonosítóból hozható létre, és a válasz resourceLocation tulajdonságából is lekérhető. Sikeresség esetén az állapot beállítása succeeded és az eredmény tartalmazza az egyéni modell adatait. Ha hiba történik, az állapot a következőre failedvan állítva, és a rendszer visszaadja a hibát.

Az alábbi kód egy SAS-jogkivonatot használó buildelési mintakérés. Figyelje meg a záró perjelet az előtag vagy mappa elérési útjának beállításakor.

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

A modell megírásának módosításai

A modell összeállítása mostantól egyetlen beágyazási szintre korlátozódik. A komponált modellek mostantól konzisztensek az egyéni modellekkel a hozzáadással modelId és description a tulajdonságokkal.

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

A modell másolásának módosításai

A másolási modell hívási mintája változatlan marad:

Engedélyezze a másolási műveletet a célerőforrás-hívással authorizeCopy. Most egy POST-kérés.
Az engedélyezés elküldése a forráserőforrásnak a modellhívás másolásához copyTo
A visszaadott művelet lekérdezése a művelet sikeres végrehajtásának ellenőrzéséhez

A másolási modell függvényének csak a következő módosításai módosulnak:

A HTTP-művelet authorizeCopy mostantól POST-kérés.
Az engedélyezési hasznos adatok tartalmazzák a másolási kérelem elküldéséhez szükséges összes információt.

A másolat engedélyezése

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

A másolatra vonatkozó kérés létrehozásához használja az engedélyezési művelet válasz törzsét.

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

A listamodellek módosítása

A listamodellek mostantól előre összeállított és egyéni modelleket is visszaadnak. Minden előre összeállított modellnév a .-val prebuilt-kezdődik. A rendszer csak a sikeres állapotú modelleket adja vissza. A sikertelen vagy folyamatban lévő modellek listáját a Listaműveletek című témakörben találja.

Mintalistamodellek kérése

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

Változás a modell lekéréséhez

Mivel a get modell már előre összeállított modelleket is tartalmaz, a lekérési művelet egy szótárt docTypes ad vissza. Minden dokumentumtípus leírása tartalmazza a nevet, az opcionális leírást, a mezősémát és az opcionális mező megbízhatóságát. A mezőséma a dokumentumtípussal esetleg visszaadott mezők listáját írja le.

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

Új get info művelet

A info szolgáltatáson végzett művelet az egyéni modellek számát és az egyéni modellkorlátot adja vissza.

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

Mintaválasz

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

Share via