你当前正在访问 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
- “西欧”
- 美国中北部

通过批处理分析 API，可以使用一个异步请求批量处理多个文档。无需单独提交文档并跟踪多个请求 ID，而是可以同时分析一组发票、一系列贷款文档或一组自定义模型训练文档。

若要利用批处理分析，需要一个 Azure Blob 存储帐户，以及用于源文档和已处理的输出的特定容器。
完成后，批处理操作结果将列出所有已处理的单个文档及其状态，例如 succeeded、skipped 或 failed。
批处理 API 预览版可通过即用即付定价获得。

以下模型支持批处理分析：

读取。从表单和文档中提取文本行、字词、检测到的语言和手写样式。
布局。从表单和文档中提取文本、表、选择标记和结构信息。
自定义模板。训练模型，以便从结构化表单中提取键值对、选择标记、表、签名字段和区域。
自定义神经。训练模型，以便从结构化、半结构化和非结构化文档中提取指定的数据字段。
自定义生成式。训练模型，以便从复杂对象（如嵌套表、抽象/生成字段和真正非结构化格式）中提取指定数据。

批处理分析指导

每个批处理分析请求处理的最大文档数量（包括跳过的文档）为 10,000。
azureBlobFileListSource 参数可用于将较大的请求拆分为较小的请求。
操作结果在完成后保留 24 小时。文档和结果位于提供的存储帐户中，但操作状态在完成 24 小时后不再可用。

准备好开始了吗？

先决条件

需要一个活动 Azure 订阅。如果你没有 Azure 订阅，可以免费创建一个。
在 Azure 门户中拥有 Azure 订阅 A 文档智能实例后。可以使用免费定价层 (F0) 来试用该服务。
部署资源后，选择“转到资源”并检索密钥和终结点。
- 需要从资源获取密钥和终结点，以便将应用程序连接到文档智能服务。稍后需要在本快速入门中将密钥和终结点粘贴到代码中。可以在 Azure 门户的“密钥和终结点”页面上找到这些值。
一个 Azure Blob 存储帐户。你将在自己的 Azure Blob 存储帐户中为源文件和结果文件创建容器：
- 源容器。此容器用于上传文件以进行分析（必需）。
- 结果容器。此容器用于存储已处理的文件（可选）。

可以为源文档和已处理的文档指定相同的 Azure Blob 存储容器。但是，为了尽量减少意外覆盖数据的可能性，我们建议选择单独的容器。

存储容器授权

可以选择以下选项之一来授权访问文档资源。

✔️ 托管标识。托管标识是一个服务主体，用于为 Azure 托管资源创建 Microsoft Entra 标识和特定权限。托管标识使你无需在代码中嵌入凭据即可运行文档智能应用程序。托管标识是授予存储数据访问权限的一种更安全的方式，取代了在源和结果 URL 中包含共享访问签名令牌 (SAS) 的要求。

要了解详细信息，请参阅用于文档智能的托管标识。

托管标识流（基于角色的访问控制）的屏幕截图。

重要

使用托管标识时，请勿在 HTTP 请求中包含 SAS 令牌 URL - 请求将失败。使用托管标识替代了包含共享访问签名令牌 (SAS) 的要求。

✔️ 共享访问签名 (SAS)。共享访问签名是向文档智能服务授予指定时间段内受限访问权限的 URL。若要使用此方法，需要为源容器和结果容器创建共享访问签名 (SAS) 令牌。源容器和结果容器必须包含作为查询字符串追加的共享访问签名 (SAS) 令牌。可将该令牌分配到容器或特定的 Blob。

附加 SAS 令牌的存储 URI 的屏幕截图。

源容器或 Blob 必须指定读取、写入、列出和删除访问权限。
结果容器或 Blob 必须指定写入、列出和删除访问权限。

要了解详细信息，请参阅创建 SAS 令牌。

调用批处理分析 API

在 azureBlobSource 或 azureBlobFileListSource 对象中为源文档集指定 Azure Blob 存储容器 URL。
使用 resultContainerUrl 为批处理分析结果指定 Azure Blob 存储容器 URL。为了避免意外覆盖，建议对源文档和已处理文档使用单独的容器。
- 如果使用同一容器，请将 resultContainerUrl 和 resultPrefix 设置为与输入 azureBlobSource 匹配。
- 使用同一容器时，可以包含 overwriteExisting 字段，以确定是否使用分析结果文件覆盖任何文件。

生成并运行 POST 请求

运行 POST 请求之前，请将 {your-source-container-SAS-URL} 和 {your-result-container-SAS-URL} 替换为 Azure Blob 存储容器实例中的值。

仅允许一个 azureBlobSource 或 azureBlobFileListSource。

POST /documentModels/{modelId}:analyzeBatch

[
  {
    "azureBlobSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "prefix": "trainingDocs/"
    },
    "azureBlobFileListSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "fileList": "myFileList.jsonl"
    },
    "resultContainerUrl": "{your-result-container-SAS-URL}",
    "resultPrefix": "trainingDocsResult/",
    "overwriteExisting": false
  }
]

成功的响应

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

检索批处理分析 API 结果

执行批处理 API 操作后，可以使用 GET 操作检索批处理分析结果。此操作将提取操作状态信息、操作完成百分比以及操作创建和更新日期/时间。

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

解释状态消息

对于每个文档集，都会分配一个状态：succeeded、failed 或 skipped。对于每个文档，提供了两个 URL 来验证结果：sourceUrl（成功输入文档的源 Blob 存储容器）和 resultUrl（通过组合 resultContainerUrl 和 resultPrefix 构建，以创建源文件和 .ocr.json 的相对路径）。

状态 notStarted 或 running。批处理分析操作未启动或未完成。等待所有文档的操作完成。
状态 completed。批处理分析操作已完成。
状态 failed。批处理操作失败。如果请求存在整体问题，通常会出现此响应。即使所有文件都失败，批处理报告响应中也会返回单个文件的失败。例如，存储错误不会停止整个批处理操作，因此可以通过批处理报告响应访问部分结果。

只有具有 succeeded 状态的文件才会在响应中生成属性 resultUrl。这使模型训练能够检测以 .ocr.json 结尾的文件名，并将其标识为可用于训练的唯一文件。

succeeded 状态响应的示例：

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

failed 状态响应的示例：

仅当整个批处理请求中出现错误时，才会返回此错误。
启动批处理分析操作后，单个文档操作状态不会影响整个批处理作业的状态，即使所有文件都具有 failed 状态。

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

skipped 状态响应的示例：

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

批处理分析结果通过将 resultUrl 中的文件与 resultContainerUrl 中的输出文件进行比较，帮助你识别哪些文件已成功分析并验证分析结果。

注意

在完成整个文档集批处理分析后，才会返回单个文件的分析结果。若要跟踪 percentCompleted 以外的详细进度，可以监视 *.ocr.json 文件写入 resultContainerUrl。

后续步骤

在 GitHub 上查看代码示例。

通过