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

文档智能批处理分析

项目
12/17/2024

通过批处理分析 API，可以使用一个异步请求批量处理多个文档。无需单独提交文档并跟踪多个请求 ID，而是可以同时分析一组文档如发票、一系列贷款文档或一组自定义模型训练文档。批处理 API 支持从 Azure Blob 存储读取文档并将结果写入 Blob 存储。

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

批处理分析指导

每个批处理分析请求处理的最大文档数量（包括跳过的文档）为 10,000。
操作结果在完成后保留 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。

指定输入文件

批处理 API 支持两个选项，用于指定要处理的文件。如果需要处理容器或文件夹中的所有文件，并且单个批处理请求的文件数小于 10000 限制，请使用 azureBlobSource 容器。

如果容器或文件夹中有要处理的特定文件，或者要处理的文件数超过单个批的最大限制，请使用 azureBlobFileListSource。将数据集拆分成多个批处理，并添加一个文件，其中包含要在容器根文件夹中以 JSONL 格式处理的文件列表。文件列表格式的示例为。

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

指定结果位置

使用 resultContainerUrl 为批处理分析结果指定 Azure Blob 存储容器 URL。为了避免意外覆盖，建议对源文档和已处理文档使用单独的容器。

如果不希望覆盖具有相同文件名的任何现有结果，请将 overwriteExisting 布尔属性设置为 false。此设置不会影响计费，并且只会阻止在处理输入文件后覆盖结果。

将 resultPrefix 设置为此批处理 API 运行的结果的命名空间。

如果计划对输入和输出使用相同的容器，请将 resultContainerUrl 和 resultPrefix 设置为与输入 azureBlobSource 匹配。
使用同一容器时，可以包含 overwriteExisting 字段，以确定是否使用分析结果文件覆盖任何文件。

生成并运行 POST 请求

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

以下示例演示如何将 azureBlobSource 属性添加到请求：

仅允许一个 azureBlobSource 或 azureBlobFileListSource。

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

以下示例演示如何将 azureBlobFileListSource 属性添加到请求：

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

成功的响应

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 上查看代码示例。

通过