檔智慧 v3.1 移轉

  • 發行項

此內容適用於：checkmarkv4.0 （預覽）checkmarkv3.1 （GA）checkmarkv3.0 （GA）checkmarkv2.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 列舉值來啟用。
  • 已不再支持預建-讀取和 keyValuePairs 以外的某些版面配置功能。{document，invoice} 已不再支援。
  • 針對預先建置和預先建置的版面配置，預設停用條碼、預建讀取的語言，以及預先建置發票的 keyValuePairs。
  • 批注擷取已移除。
  • 會移除查詢欄位和索引鍵/值組的一般名稱。
  • 預先建置的讀取模型支援 Office/HTML 檔案，不需要周框方塊即可擷取文字和段落。 不再支援內嵌影像。 如果 Office/HTML 檔案要求附加元件功能，則會傳回空數位列，而不會發生錯誤。

分析功能

Model ID 文字擷 段落 段落角色 選取標記 資料表 索引鍵/值組 語言 條碼 檔分析 公式* 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
預建發票 ✓ ✓ ✓ 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，Document Intelligence v3.1 引進數個新的特性和功能：

  • 條形碼 擷取。
  • 附加元件功能 ，包括高解析度、公式和字型屬性擷取。
  • 用於檔案分割和分類的自定義分類模型 。
  • 發票和收據模型中的語言擴充和新欄位支援。
  • 標識碼檔模型中的新文件類型支援。
  • 新的預建 健康保險卡 模型。
  • 預先建置的讀取模型支援 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） 和 currencySymbol （例如 $）。 此功能會將貨幣符號對應至標準 ISO 4217 代碼（例如美元）。 模型可以選擇性地利用通用檔案內容來厘清或推斷貨幣碼。
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

除了模型品質改善之外，強烈建議您更新應用程式以使用 v3.1 來受益于這些新功能。

從 v2.1 或 v2.0 移轉

Document Intelligence v3.1 是最新的 GA 版本，具有最豐富的功能、大部分的語言和檔案類型涵蓋範圍，以及改善的模型品質。 如需 v3.1 中可用的特性和功能，請參閱模型概觀 。

從 v3.0 開始， 檔智慧 REST API 經過重新設計，以提升可用性。 在本節中，瞭解 Document Intelligence 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 ，並傳回錯誤。
Model 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}"
}

Document Intelligence 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 內的頂端杠杆屬性。


{
// 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是新屬性，具有自訂表單模型或 neural 自訂類神經網路模型的值 template 。

叫 build 用作業來定型模型。 要求承載和呼叫模式保持不變。 建置作業會指定模型和訓練資料集，它會透過回應中的 Operation-Location 標頭傳回結果。 透過 GET 要求輪詢此模型作業 URL，以檢查建置作業的狀態（要求之間的最小建議間隔為 1 秒）。 不同于 v2.1，此 URL 不是模型的資源位置。 相反地，可以從指定的 modelId 建構模型 URL，也可以從回應中的 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/}"
  }
}

撰寫模型的變更

模型撰寫現在僅限於單一巢狀層級。 撰寫的模型現在與新增 和 description 屬性的 modelId 自訂模型一致。

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

變更以取得模型

由於 get 模型現在包含預先建置的模型，取得作業會 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
  }
}

下一步