Document Intelligence v3.1 migrálása
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
featuresengedé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
featuresleké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.
Figyelemfelhívás
- A REST API 2023-07-31 kiadás kompatibilitástörő változást tartalmaz a REST API analyze response JSON-ban.
- A
boundingBoxtulajdonság minden példányban át leszpolygonnevezve.
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 documentModels modelId .
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 |
| Nyugta | /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ól1indexelt oldalszámok listája. Pl. "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.
pagestableskeyValuePairsentitiesstylesdocuments
Feljegyzé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
modelIdmostantól egy olyan tulajdonság, amely beállítható egy modellen egy olvasható névhez.modelNamea átnevezvedescriptionbuildModeaz egyéni űrlapmodellek vagyneuralaz egyéni neurális modellek értékeittemplatetartalmazó ú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
authorizeCopymostantó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
}
}
Következő lépések
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: