共用方式為

文件智慧服務 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
  }
}

下一步