你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

文档智能自定义分类模型

项目
10/17/2024

重要

使用文档智能选公共预览版，可以提前使用目前正处于开发状态的功能。在正式发布 (GA) 之前，根据用户反馈，功能、方法和流程可能会发生更改。
文档智能客户端库的公共预览版默认使用 REST API 版本 2024-07-31-preview。
公共预览版 2024-07-31-preview 目前仅在以下 Azure 区域中可用。请注意，AI Studio 中的自定义生成式（文档字段提取）模型仅适用于美国中北部区域：
- 美国东部
- 美国西部 2
- “西欧”
- 美国中北部

此内容适用于：v4.0（预览版） | 先前版本：v3.1 (GA)

此内容适用于：v3.1 (GA) | 最新版本：v4.0（预览版）

重要

默认情况下，2024-07-31-preview API（自定义分类模型）在分析过程中不会拆分文档。
需要显式设置属性 splitMode，以便自动保存以前版本中的行为。 splitMode 的默认值是 none。
如果输入文件包含多个文档，则需要通过将 splitMode 设置为 auto 来启用拆分。

Azure AI 文档智能是一项基于云的 Azure AI 服务，支持构建智能文档处理解决方案。文档智能 API 可分析图像、PDF 和其他文档文件，以提取和检测各种内容、布局、样式和语义元素。

自定义分类模型是深度学习模型类型，结合了布局和语言特征，可准确检测和识别在应用程序中处理的文档。自定义分类模型每次执行一页输入文件的分类，以识别其中的文档，还可以识别输入文件中的多个文档或单个文档的多个实例。

模型功能

注意

从 2024-02-29-preview API 开始，自定义分类模型支持增量训练。可以向现有类添加新样本，或通过引用现有分类器来添加新类。

自定义分类模型可以分析单文件或多文件文档，以识别输入文件中是否包含任何经过训练的文档类型。以下是当前支持的情况：

包含一种文档类型的单个文件，例如贷款申请表单。
包含多种文档类型的单个文件。例如，贷款申请包中包含了贷款申请表单、工资单和银行对帐单。
单个文件中包含了同一文档的多个实例。例如，一组经过扫描的发票。

✔️ 训练自定义分类器需要至少 two 个不同的类，每个类至少需要 five 个文档示例。模型响应包含已识别的每个文档类的页面范围。

✔️ 允许的最大类数为 500。每个类允许的最大文档示例数为 100。

除非另行指定，否则模型将输入文档的每一页分类为标记数据集中的一个类。还可以指定要在输入文档中分析的页码。若要为应用程序设置阈值，请使用响应中的置信度评分。

增量训练

对于自定义模型，需要保持访问训练数据集，以便使用现有类的新样本更新分类器，或添加新类。分类器模型现在支持增量训练，在这种训练中，可以引用现有分类器并为现有类追加新样本，或者使用样本添加新类。如果数据保留是一个难题，并且需要更新分类器以适应不断变化的业务需求，则可以使用增量训练。使用 API 版本 2024-02-29-preview 及更高版本训练的模型支持增量训练。

重要

只有使用相同 API 版本训练的模型才支持增量训练。如果你正在尝试扩展某个模型，请使用训练原始模型时所用的 API 版本来扩展该模型。仅 API 版本 2024-07-31-preview 或更高版本才支持增量训练。

增量训练要求你提供原始模型 ID 作为 baseClassifierId。请参阅增量训练来详细了解如何使用增量训练。

Office 文档类型支持

现在，你可以训练分类器来识别各种格式的文档类型，包括 PDF、图像、Word、PowerPoint 和 Excel。汇编训练数据集时，可以添加任何受支持类型的文档。分类器不要求你显式标记特定类型。作为最佳做法，请确保训练数据集至少包含每种格式的一个样本，以提高模型的整体准确度。

比较自定义分类和组合模型

在某些方案中，自定义分类模型可以替换组合模型，但有一些区别需要注意：

功能	自定义分类器进程	组合模型进程
分析未知类型的单个文档，属于为提取模型处理而训练的其中一个类型。	● 需要多次调用。 ● 基于文档类调用分类模型。此步骤允许在调用提取模型分析之前进行基于置信度的检查。 ● 调用提取模型。	● 需要单一调用组合模型（其中包含了与输入文档类型对应的模型）。
分析未知类型的单个文件，属于为提取模型处理而训练的多个类型。	● 需要多次调用。 ● 调用分类器，忽略与提取的指定类型不匹配的文档。 ● 调用提取模型。	• 需要单一调用组合模型。该服务在组合模型中选择匹配度最高的自定义模型。 ● 组合模型不能忽略文档。
分析包含已知或未知类型的多个文档的文件，属于为提取模型处理而训练的其中一个类型。	● 需要多次调用。 ● 为输入文件中每个已识别的文档调用提取模型。 ● 调用提取模型。	• 需要单一调用组合模型。 ● 组合模型在文档的第一个实例上调用组件模型一次。 ● 忽略剩余文档。

语言支持

分类模型目前仅支持英语文档。

现在，可以训练分类模型处理包含不同语言的文档。有关完整列表，请参阅支持的语言。

输入要求

支持的文件格式：

型号	PDF	映像： `jpeg/jpg`、`png`、`bmp`、`tiff`、`heif`	Microsoft Office： Word (docx)、Excel (xlxs)、PowerPoint (pptx)
读取	✔	✔	✔
布局	✔	✔	✔（2024-02-29-preview、2023-10-31-preview 及更高版本）
常规文档	✔	✔
预生成	✔	✔
自定义提取	✔	✔
自定义分类	✔	✔	✔

为获得最佳结果，请针对每个文档类型提供五张清晰的照片或高质量的扫描件。
对于 PDF 和 TIFF，最多可处理 2,000 页（对于免费层订阅，仅处理前两页）。
用于分析文档的文件大小对于付费 (S0) 层为 500 MB，对于免费 (F0) 层为 4 MB。
图像尺寸必须介于 50 x 50 像素与 10,000 x 10,000 像素之间。
如果 PDF 是密码锁定的文件，则必须先删除锁，然后才能提交它们。
对于 1024 x 768 像素的图像，要提取的文本的最小高度为 12 像素。此尺寸对应于 150 点每英寸 (DPI) 的大约 8 号字文本。
对于自定义模型训练，自定义模板模型的训练数据最大页数为 500，自定义神经模型的训练数据最大页数为 50,000。
对于自定义提取模型训练，模板模型的训练数据总大小为 50 MB，神经模型的训练数据总大小为为 1G-MB。
对于自定义分类模型训练，训练数据的总大小为 1 GB，上限为 10,000 页。

文档拆分

当一个文件中有多个文档时，分类器可以识别输入文件里包含的不同文档类型。分类器响应包含识别到的包含在某个文件中的每种文档类型的页范围。此响应可以包含同一文档类型的多个实例。

analyze 操作现在包含 splitMode 属性，让你能够精细控制拆分行为。

若要将整个输入文件视为一个文档来进行分类，请将 splitMode 设置为 none。执行此操作后，服务为整个输入文件只返回一个分类。
若要对输入文件的每一页都进行分类，请将 splitMode 设置为 perPage。服务会尝试将每一页作为单个文档来进行分类。
将 splitMode 设置为 auto 后，服务会识别文档及关联的页范围。

最佳实践

自定义分类模型需要每个类至少五个样本来训练。如果类相似，则添加额外的训练示例可以提高模型的准确性。

分类器会尝试将每个文档分配到其中一类，如果希望模型看到文档类型不在隶属于训练数据集的类中，则应计划对分类分数设置一个阈值，或向 "other" 类添加几个具有代表性的文档类型示例。添加 "other" 类可确保不需要的文档不会影响分类器质量。

训练模型

v4.0: 2024-02-29-preview、2024-07-31-preview 和 v3.1: 2023-07-31 (GA) API 支持自定义分类模型。文档智能 Studio 具有无代码用户界面，以交互方式训练自定义分类器。请按照操作指南开始执行操作。

使用 REST API 时，如果已按文件夹整理了文档，则可以使用请求的 azureBlobSource 属性来训练分类模型。


https://{endpoint}/documentintelligence/documentClassifiers:build?api-version=2024-02-29-preview

{
  "classifierId": "demo2.1",
  "description": "",
  "docTypes": {
    "car-maint": {
        "azureBlobSource": {
            "containerUrl": "SAS URL to container",
            "prefix": "sample1/car-maint/"
            }
    },
    "cc-auth": {
        "azureBlobSource": {
            "containerUrl": "SAS URL to container",
            "prefix": "sample1/cc-auth/"
            }
    },
    "deed-of-trust": {
        "azureBlobSource": {
            "containerUrl": "SAS URL to container",
            "prefix": "sample1/deed-of-trust/"
            }
    }
  }
}

https://{endpoint}/formrecognizer/documentClassifiers:build?api-version=2023-07-31

{
  "classifierId": "demo2.1",
  "description": "",
  "docTypes": {
    "car-maint": {
        "azureBlobSource": {
            "containerUrl": "SAS URL to container",
            "prefix": "{path to dataset root}/car-maint/"
            }
    },
    "cc-auth": {
        "azureBlobSource": {
            "containerUrl": "SAS URL to container",
            "prefix": "{path to dataset root}/cc-auth/"
            }
    },
    "deed-of-trust": {
        "azureBlobSource": {
            "containerUrl": "SAS URL to container",
            "prefix": "{path to dataset root}/deed-of-trust/"
            }
    }
  }
}

或者，如果有一个扁平式文件列表，或只计划使用每个文件夹中的几个选定文件来训练模型，则可以使用 azureBlobFileListSource 属性来训练模型。此步骤需要 file list 为 JSON 行格式。对于每个类，添加其中包含了要提交以供训练的文件列表的新文件。

{
  "classifierId": "demo2",
  "description": "",
  "docTypes": {
    "car-maint": {
      "azureBlobFileListSource": {
        "containerUrl": "SAS URL to container",
        "fileList": "{path to dataset root}/car-maint.jsonl"
      }
    },
    "cc-auth": {
      "azureBlobFileListSource": {
        "containerUrl": "SAS URL to container",
        "fileList": "{path to dataset root}/cc-auth.jsonl"
      }
    },
    "deed-of-trust": {
      "azureBlobFileListSource": {
        "containerUrl": "SAS URL to container",
        "fileList": "{path to dataset root}/deed-of-trust.jsonl"
      }
    }
  }
}

作为示例，文件列表 car-maint.jsonl 包含以下文件。

{"file":"classifier/car-maint/Commercial Motor Vehicle - Adatum.pdf"}
{"file":"classifier/car-maint/Commercial Motor Vehicle - Fincher.pdf"}
{"file":"classifier/car-maint/Commercial Motor Vehicle - Lamna.pdf"}
{"file":"classifier/car-maint/Commercial Motor Vehicle - Liberty.pdf"}
{"file":"classifier/car-maint/Commercial Motor Vehicle - Trey.pdf"}

覆盖模型

注意

从 2024-07-31-preview API 开始，自定义分类模型支持就地覆盖模型。

现在可以就地更新自定义分类。在决定替换现有模型之前，直接覆盖模型将无法比较模型质量。在请求正文中显式指定 allowOverwrite 属性时，允许覆盖模型。一旦执行此操作，便无法恢复已覆盖的原始模型。



{
  "classifierId": "existingClassifierName",
  "allowOverwrite": true,  // Default=false
  ...
}

复制模型

注意

从 2024-07-31-preview API 开始，自定义分类模型支持将模型复制到以下任一区域以及从中复制模型：

美国东部
美国西部 2
“西欧”

使用 REST API 或文档智能工作室将模型复制到另一个区域。

生成复制授权请求

以下 HTTP 请求从目标资源获取复制授权。需要输入目标资源的终结点和密钥作为头。

POST https://myendpoint.cognitiveservices.azure.com/documentintelligence/documentClassifiers:authorizeCopy?api-version=2024-07-31-preview
Ocp-Apim-Subscription-Key: {<your-key>}

请求正文

{
  "classifierId": "targetClassifier",
  "description": "Target classifier description"
}

收到带有响应正文的 200 响应代码，其中包含启动复制所需的 JSON 有效负载。

{
  "targetResourceId": "/subscriptions/targetSub/resourceGroups/targetRG/providers/Microsoft.CognitiveServices/accounts/targetService",
  "targetResourceRegion": "targetResourceRegion",
  "targetClassifierId": "targetClassifier",
  "targetClassifierLocation": "https://targetEndpoint.cognitiveservices.azure.com/documentintelligence/documentClassifiers/targetClassifier",
  "accessToken": "accessToken",
  "expirationDateTime": "timestamp"
}

启动复制操作

以下 HTTP 请求对源资源启动复制操作。需要输入源资源的终结点和密钥作为 URL 和标头。请注意，请求 URL 包含所要复制的源分类器的分类器 ID。

POST {endpoint}/documentintelligence/documentClassifiers/{classifierId}:copyTo?api-version=2024-07-31-preview
Ocp-Apim-Subscription-Key: {<your-key>}

请求的正文是上一步的响应。

{
  "targetResourceId": "/subscriptions/targetSub/resourceGroups/targetRG/providers/Microsoft.CognitiveServices/accounts/targetService",
  "targetResourceRegion": "targetResourceRegion",
  "targetClassifierId": "targetClassifier",
  "targetClassifierLocation": "https://targetEndpoint.cognitiveservices.azure.com/documentintelligence/documentClassifiers/targetClassifier",
  "accessToken": "accessToken",
  "expirationDateTime": "timestamp"
}

模型回复

使用文档分类模型分析输入文件。

https://{endpoint}/documentintelligence/documentClassifiers/{classifier}:analyze?api-version=2024-02-29-preview

从 2024-07-31-preview API 开始，可以在请求中使用 pages 查询参数来指定输入文档中要分析的页数。

https://{service-endpoint}/formrecognizer/documentClassifiers/{classifier}:analyze?api-version=2023-07-31

响应包含已识别的文档，这些文档具有响应的文档部分中的关联页面范围。

{
  ...

    "documents": [
      {
        "docType": "formA",
        "boundingRegions": [
          { "pageNumber": 1, "polygon": [...] },
          { "pageNumber": 2, "polygon": [...] }
        ],
        "confidence": 0.97,
        "spans": []
      },
      {
        "docType": "formB",
        "boundingRegions": [
          { "pageNumber": 3, "polygon": [...] }
        ],
        "confidence": 0.97,
        "spans": []
      }, ...
    ]
  }

后续步骤

了解如何创建自定义分类模型：

构建自定义分类模型自定义模型概述

通过