调用 Azure AI 视觉 v3.2 GA 读取 API

项目
11/15/2024

本指南展示了如何调用 v3.2 GA 读取 API 从图像中提取文本。你将了解此 API 行为的不同配置方式以满足你的需求。

以下步骤假定你已创建计算机视觉资源并获取了密钥和终结点 URL。如果尚未完成这些操作，请参阅快速入门以开始使用。

确定如何处理数据（可选）

指定 OCR 模型

默认情况下，此服务使用最新的正式发布 (GA) 模型来提取文本。从 Read v3.2 开始，model-version 参数允许在给定 API 版本的 GA 和预览版模型之间选择。你指定的模型会用于通过读取操作提取文本。

使用读取操作时，请为可选 model-version 参数使用以下值。

值	使用的模型
未提供	最新 GA 模型
最新	最新 GA 模型
2022-04-30	最新 GA 模型。适用于印制文本的 164 种语言，以及适用于手写文本的 9 种语言，还有多项有关质量和性能的增强功能
2022-01-30	添加了对印地语、阿拉伯语和相关语言的印制文本的支持。对于手写文本，添加了对日语和朝鲜语的支持。
2021-09-30	添加了对俄语和其他西里尔语的印制文本的支持。对于手写文本，添加了对简体中文、法语、德语、意大利语、葡萄牙语和西班牙语的支持。
2021-04-12	2021 GA 模型

输入语言

默认情况下，服务从图像或文档（包括混合语言）中提取所有文本。读取操作包含可选语言请求参数。如果希望强制将文档作为该特定语言处理，则仅提供语言代码。否则，服务可能会返回不完整和不正确的文本。

自然读取顺序输出（仅限拉丁语）

默认情况下，服务按从左到右的顺序输出文本行。（可选）使用 readingOrder 请求参数，为更易于阅读的读取顺序输出使用 natural，如下例所示。此功能仅支持拉丁语。

OCR 阅读顺序示例的屏幕截图。

选择页面或页面范围以进行文本提取

默认情况下，服务从文档的所有页面提取文本。（可选）使用 pages 请求参数指定页码或页面范围，以便仅从这些页面提取文本。以下示例演示了一个 10 页的文档，在两种条件下提取文本：所有页面 (1-10) 和选定页面 (3-6)。

显示所有页面和选定页面的输出的屏幕截图。

提交服务数据

可向读取 API 提交本地映像或远程映像。就本地映像而言，请将二进制图像数据放在 HTTP 请求正文中。对于远程场景，请通过设置请求正文的格式来指定图像的 URL，如下所示。

{"url":"http://example.com/images/test.jpg"}

读取 API 的读取调用采用图像或 PDF 文档作为输入，以异步方式提取文本。

https://{endpoint}/vision/v3.2/read/analyze[?language][&pages][&readingOrder]

该调用返回时将包含一个名为 Operation-Location 的响应头字段。 Operation-Location 值是一个 URL，它包含要在下一步骤中使用的操作 ID。

响应标头	示例值
Operation-Location	`https://cognitiveservice/vision/v3.2/read/analyzeResults/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4`

注意

计费

Azure AI 视觉定价页面包含了读取操作的定价层。分析的每个图像或页面均为一个事务。如果对包含 100 个页面的 PDF 或 TIFF 文档调用该操作，则读取操作会将其计为 100 个事务，而你需要按 100 个事务付费。如果对该操作发出了 50 次调用，而每次调用提交了包含 100 个页面的文档，则你需要按照 50 X 100 = 5000 个事务付费。

获取服务结果

第二个步骤是调用获取读取结果操作。此操作采用读取操作创建的操作 ID 作为输入。

https://{endpoint}/vision/v3.2/read/analyzeResults/{operationId}

此操作返回一个 JSON 响应，其中包含具有以下可能值的 status 字段。

值	含义
`notStarted`	尚未启动操作。
`running`	正在处理操作。
`failed`	此操作失败。
`succeeded`	操作成功。

可以不断地以迭代方式调用此操作，直到它返回 succeeded 值为止。使用 1 到 2 秒的间隔可以避免超过每秒请求数 (RPS) 的速率限制。

注意

免费层将请求速率限制为每分钟 20 次调用。付费层允许 30 RPS，可通过请求增加。请记下你的 Azure 资源标识符和区域，然后开具 Azure 支持工单或联系你的帐户团队以请求更高的 RPS 速率。

当 status 字段的值为 succeeded 时，JSON 响应将包含从图像或文档提取的文本内容。 JSON 响应会维护已识别单词的原始分组。其中包括提取的文本行及其边界框坐标。每个文本行都包含所有提取的单词及其坐标和可信度分数。

注意

提交到“读取”操作的数据将暂时加密并静态存储较短的一段时间，然后被删除。这样，应用程序便可以检索提取的文本作为服务响应的一部分。

示例 JSON 输出

参阅下面的成功 JSON 响应示例：

{
  "status": "succeeded",
  "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
  "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
  "analyzeResult": {
    "version": "3.2",
    "readResults": [
      {
        "page": 1,
        "angle": 2.1243,
        "width": 502,
        "height": 252,
        "unit": "pixel",
        "lines": [
          {
            "boundingBox": [
              58,
              42,
              314,
              59,
              311,
              123,
              56,
              121
            ],
            "text": "Tabs vs",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.96
              }
            },
            "words": [
              {
                "boundingBox": [
                  68,
                  44,
                  225,
                  59,
                  224,
                  122,
                  66,
                  123
                ],
                "text": "Tabs",
                "confidence": 0.933
              },
              {
                "boundingBox": [
                  241,
                  61,
                  314,
                  72,
                  314,
                  123,
                  239,
                  122
                ],
                "text": "vs",
                "confidence": 0.977
              }
            ]
          }
        ]
      }
    ]
  }
}

文本行手写分类（仅限拉丁语）

响应中包括一个分类（指明每行文本是否为手写体），以及一个置信度得分。此功能仅适用于拉丁语。以下示例演示了图像中文本的手写分类。

显示 OCR 手写分类示例的屏幕截图。

通过