文件智慧服務 v3.1 移轉
此內容適用於:v4.0 (預覽)
v3.1 (GA)
v3.0 (GA)
v2.1 (GA)
重要
文件智慧服務 REST API v3.1 引進 REST API 要求中的中斷性變更,並分析回應 JSON。
從 v3.1 預覽 API 版本移轉
預覽 API 會定期淘汰。 如果您使用預覽 API 版本,請更新應用程式,以 GA API 版本為目標。 若要使用 SDK 從 2023-02-28-preview API 版本移轉至 2023-07-31
(GA) API 版本,請更新至語言特定 SDK 的目前版本。
2023-07-31
(GA) API 有一些來自預覽 API 版本的更新和變更:
- 根據預設,啟用的功能僅限於特定模型所需的功能,其優點是降低延遲和回應大小。 可以透過
features
參數中的列舉值來啟用新增的功能。 - 除了 prebuilt-{document,invoice} 之外,已不再支援來自 prebuilt-read 和 keyValuePairs 的配置功能。
- 依預設停用 prebuilt-read 和 prebuilt-layout 的條碼、prebuilt-read 的語言以及 prebuilt-invoice 的 keyValuePairs。
- 已移除註釋擷取。
- 系統會移除查詢欄位和索引鍵值組的一般名稱。
- 在 prebuilt-read 模型中支援 Office/HTML 檔案,不需要週框方塊即可擷取字詞和段落。 不再支援內嵌影像。 如果 Office/HTML 檔案要求附加元件功能,則會傳回空陣列,而不會發生錯誤。
分析功能
模型識別碼 | 文字擷取 | 段落 | 段落角色 | 選取標記 | 資料表 | 索引鍵/值組 | 語言 | 條碼 | 文件分析 | 公式* | StyleFont* | OCR 高解析度* |
---|---|---|---|---|---|---|---|---|---|---|---|---|
prebuilt-read | ✓ | ✓ | O | O | O | O | O | |||||
prebuilt-layout | ✓ | ✓ | ✓ | ✓ | ✓ | O | O | O | O | O | ||
prebuilt-document | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | O | O | O | O | O | |
prebuilt-businessCard | ✓ | ✓ | ||||||||||
prebuilt-idDocument | ✓ | O | O | ✓ | O | O | O | |||||
prebuilt-invoice | ✓ | ✓ | ✓ | O | O | O | ✓ | O | O | O | ||
prebuilt-receipt | ✓ | 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 | ||||
預先建置合約 | ✓ | ✓ | ✓ | ✓ | O | O | ✓ | O | O | O | ||
{ customModelName } | ✓ | ✓ | ✓ | ✓ | ✓ | O | O | ✓ | O | O | O |
✓ - 已啟用 O - 選擇性公式/StyleFont/OCR 高解析度* - 進階功能會產生額外的成本
從 v3.0 移轉
與 v3.0 相較之外,文件智慧服務 v3.1 推出了數項新特性與功能:
- 條碼擷取。
- 附加元件功能,包括高解析度、公式和字型屬性擷取。
- 文件分割和分類的自訂分類模型。
- 發票和收據模型中的語言擴充和新欄位支援。
- 識別碼文件模型中的新檔案類型支援。
- 新增預建健保卡模型。
- 在 prebuilt-read 模型中支援 Office/HTML 檔案,不需要週框方塊即可擷取字詞和段落。 不再支援內嵌影像。 如果 Office/HTML 檔案要求附加元件功能,則會傳回空陣列,而不會發生錯誤。
- 自訂擷取和分類模型的模型到期 - 我們的新自訂模型是以大型基底模型為基礎,我們會定期更新以改進行品質。 所有自訂模型都會引進到期日,以啟用對應基底模型的淘汰。 自訂模型到期後,您必須使用最新的 API 版本重新定型模型 (基底模型)。
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": { ... }
}
- 自訂神經模型建置配額 - 每個訂用帳戶每個月在每個區域可以建置的神經模型數目有限。 我們會擴展結果 JSON 以包含配額和已使用的資訊,以協助您了解目前使用量,作為 GET /info 所傳回之資源資訊的一部分。
{
"customDocumentModels": { ... },
"customNeuralDocumentModelBuilds": {
"used": 1,
"quota": 10,
"quotaResetDateTime": "2023-03-01T00:00:00Z"
}
}
- 分析作業的選擇性
features
查詢參數可以選擇啟用特定功能。 某些進階功能會產生額外的計費。 如需詳細資訊,請參閱分析功能清單。 - 擴充擷取的貨幣欄位物件,以盡可能輸出標準化的貨幣代碼欄位。 目前,貨幣欄位可能會傳回金額(例如 123.45) 和貨幣符號 (例如 $)。 此功能會將貨幣符號對應至標準 ISO 4217 代碼 (例如USD)。 模型可以選擇性地利用全域文件內容來釐清或推斷貨幣代碼。
{
"fields": {
"Total": {
"type": "currency",
"content": "$123.45",
"valueCurrency": {
"amount": 123.45,
"currencySymbol": "$",
"currencyCode": "USD"
},
...
}
}
}
除了模型品質改進之外,強烈建議您更新應用程式以使用 v3.1 來受益於這些新功能。
從 v2.1 或 v2.0 移轉
文件智慧服務 v3.1 是最新的 GA 版本,具有最豐富的功能、涵蓋大部分的語言和文件類型以及改善的模型品質。 如需 v3.1 中可用的特性和功能相關資訊,請參閱模型概觀。
從 v3.0 開始,文件智慧服務 REST API 已經過重新設計,以提升可用性。 在本章節中,了解文件智慧服務 v2.0、v2.1 和 v3.1 之間的差異,以及如何移至較新版本的 API。
警告
- REST API 2023-07-31 版本包含 REST API 分析回應 JSON 中的中斷性變更。
boundingBox
屬性會在每個執行個體中重新命名為polygon
。
REST API 端點的變更
v3.1 REST API 會將配置分析、預建模型和自訂模型的分析作業結合成單一配對的作業,方法是將 documentModels
和 modelId
指派給配置分析 (預建配置) 和預建模型。
POST 要求
https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31
GET 要求
https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31
分析作業
- 要求承載和呼叫模式保持不變。
- 分析作業會指定輸入文件和內容特定的設定,其會透過回應中的 Operation-Location 標頭傳回分析結果 URL。
- 透過 GET 要求來輪詢此分析結果 URL,以檢查分析作業的狀態 (要求之間的最小建議間隔為 1 秒)。
- 成功時,狀態會設定為成功,並在回應本文中傳回 analyzeResult。 如果遇到錯誤,狀態會設定為
failed
,並傳回錯誤。
模型 | v2.0 | v2.1 | v3.1 |
---|---|---|---|
要求 URL 首碼 | https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 | https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 | https://{your-form-recognizer-endpoint}/formrecognizer |
一般文件 | N/A | N/A | /documentModels/prebuilt-document:analyze |
版面配置 | /layout/analyze | /layout/analyze | /documentModels/prebuilt-layout:analyze |
自訂 | /custom/models/{modelId}/analyze | /custom/{modelId}/analyze | /documentModels/{modelId}:analyze |
發票 | N/A | /prebuilt/invoice/analyze | /documentModels/prebuilt-invoice:analyze |
收據 | /prebuilt/receipt/analyze | /prebuilt/receipt/analyze | /documentModels/prebuilt-receipt:analyze |
身分證明文件 | N/A | /prebuilt/idDocument/analyze | /documentModels/prebuilt-idDocument:analyze |
名片 | N/A | /prebuilt/businessCard/analyze | /documentModels/prebuilt-businessCard:analyze |
W-2 | N/A | N/A | /documentModels/prebuilt-tax.us.w2:analyze |
健保卡 | N/A | N/A | /documentModels/prebuilt-healthInsuranceCard.us:analyze |
合約 | N/A | N/A | /documentModels/prebuilt-contract:analyze |
分析要求本文
要分析的內容是透過要求本文提供。 URL 或 base64 編碼的資料可以是使用者來建構要求。
若要指定可公開存取的 Web URL,請將 Content-Type 設定為 application/json,並傳送下列 JSON 本文:
{
"urlSource": "{urlPath}"
}
文件智慧服務 v3.0也支援 Base 64 編碼:
{
"base64Source": "{base64EncodedContent}"
}
其他支援的參數
繼續提供支援的參數:
pages
:僅分析文件中的特定頁面子集。 從要分析的數字1
編製索引的頁碼清單。 例如 "1-3,5,7-9"locale
:文字辨識和文件分析的地區設定提示。 值只能包含語言代碼 (例如en
、fr
) 或 BCP 47 語言標記 (例如 "en-US")。
不再支援的參數:
- includeTextDetails
新的回應格式比較精簡,且一律會傳回完整輸出。
分析結果的變更
分析回應已重構為下列最上層結果,以支援多頁元素。
pages
tables
keyValuePairs
entities
styles
documents
注意
analyzeResult 回應變更包含許多變更,例如從頁面的屬性向上移動至 analyzeResult 內頂端的 lever 屬性。
{
// 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
}, ...
}
}, ...
]
}
建置或定型模型
模型物件在新的 API 中有三個更新
modelId
現在是可在人類可閱讀名稱模型上設定的屬性。modelName
已重新命名為description
buildMode
是新的屬性,其值在自訂表單模型時為template
,或在自訂神經模型時為neural
。
系統會 build
叫用作業來定型模型。 要求承載和呼叫模式保持不變。 建置作業會指定模型和訓練資料集,其會透過回應中的 Operation-Location 標頭傳回結果。 透過 GET 要求來輪詢此模型作業 URL,以檢查建置作業的狀態 (要求之間的最小建議間隔為 1 秒)。 不同於 v2.1,此 URL 不是模型的資源位置。 相反地,模型 URL 可以從指定的 modelId 建構,也可以從回應中的 resourceLocation 屬性擷取。 成功時,狀態會設定為 succeeded
,且結果包含自訂模型資訊。 如果遇到錯誤,狀態會設定為 failed
,並傳回錯誤。
下列程式碼是使用 SAS 權杖的範例組建要求。 請注意設定首碼或資料夾路徑時的尾端斜線。
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/}"
}
}
撰寫模型的變更
模型撰寫現在僅限於單一層級的巢狀。 撰寫的模型現在與具有新增 modelId
和 description
屬性的自訂模型一致。
POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
"modelId": "{composedModelId}",
"description": "{composedModelDescription}",
"componentModels": [
{ "modelId": "{modelId1}" },
{ "modelId": "{modelId2}" },
]
}
複製模型的變更
複製模型的呼叫模式保持不變:
- 使用呼叫
authorizeCopy
的目標資源授權複製作業。 現在是 POST 要求。 - 將授權提交至來源資源以複製模型呼叫
copyTo
- 輪詢傳回的作業,以驗證作業成功完成
複製模型函式的唯一變更如下:
authorizeCopy
上的 HTTP 動作現在是 POST 要求。- 授權承載包含提交複製要求所需的所有資訊。
授權複本
POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
"modelId": "{targetModelId}",
"description": "{targetModelDescription}",
}
使用授權動作中的回應本文來建構複本的要求。
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"
}
列出模型的變更
列出模型已擴充為現在會傳回預建和自訂模型。 所有預先建置的模型名稱都是以 prebuilt-
開頭。 只會傳回狀態為成功的模型。 若要列出失敗或進行中的模型,請參閱列出作業。
範例列出模型要求
GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31
取得模型的變更
隨著取得模型現在包含預先建置的模型,取得作業會傳回 docTypes
字典。 每個文件類型描述,包含名稱、選填描述、欄位結構描述和選用欄位信賴度。 欄位結構描述會描述可能以文件類型傳回的欄位清單。
GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31
新增取得資訊作業
服務上的 info
作業會傳回自訂模型計數和自訂模型限制。
GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31
範例回覆
{
"customDocumentModels": {
"count": 5,
"limit": 100
}
}