文档智能 v3.1 迁移

此内容适用于:选中标记 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 文件请求附加功能,则会返回空数组,不会出现错误。

分析功能

模型 ID 文本提取 段落 段落角色 选择标记 键值对 语言 条形码 文档分析 公式* StyleFont* OCR 高分辨率*
prebuilt-read O O O O O
预生成布局 O O O O O
预生成文档 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
prebuilt-contract O O O O O
{ customModelName } O O O O O

✓ - 已启用 O - 可选公式/StyleFont/OCR 高分辨率* - 高级功能会产生额外成本

从 v3.0 迁移

相较于 v3.0,文档智能 v3.1 引入了几个新特性和功能:

  • 条形码提取。
  • 附加功能,包括高分辨率、公式和字体属性提取。
  • 用于文档拆分和分类的自定义分类模型
  • 发票收据模型中的语言扩展和新字段支持。
  • ID 文档模型中的新文档类型支持。
  • 新的预生成医疗保险卡模型。
  • 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 通过向布局分析 (prebuilt-layout) 和预生成模型分配 documentModelsmodelId,将布局分析、预生成模型和自定义模型的分析操作合并为一对操作。

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
常规文档 空值 空值 /documentModels/prebuilt-document:analyze
布局 /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
自定义 /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
发票 不可用 /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
回执 /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
ID 文档 不可用 /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
名片 不可用 /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 空值 空值 /documentModels/prebuilt-tax.us.w2:analyze
医疗保险卡 空值 空值 /documentModels/prebuilt-healthInsuranceCard.us:analyze
合约 空值 空值 /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:文本识别和文档分析的区域设置提示。 值只能包含语言代码(例如 enfr)或 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 是一个新属性,对于自定义表单模型,其值为 template,对于自定义神经模型,其值为 neural

调用 build 操作以训练模型。 请求有效负载和调用模式保持不变。 生成操作指定模型和训练数据集,它通过响应中的 Operation-Location 标头返回结果。 通过 GET 请求轮询此模型操作 URL,检查生成操作的状态(请求之间的最小建议间隔为 1 秒)。 与 v2.1 不同,此 URL 不是模型的资源位置。 相反,可从给定的 modelId 构造模型 URL,还可从响应中的 resourceLocation 属性中检索模型 URL。 成功后,状态设置为 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.chinacloudapi.cn/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

对组合模型的更改

模型组合现在仅限于单级嵌套。 组合的模型现在与添加 modelIddescription 属性的自定义模型一致。

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

后续步骤