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

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

项目
10/18/2024

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

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

OCR（读取）版

重要

选择最适合你的要求的读取版本。

输入	示例	读取版本	好处
图像：常规的现实图像	标签、路标和海报	适用于图像的 OCR（版本 4.0）	通过性能增强的同步 API 对常规非文档图像进行优化，可更轻松地在用户体验方案中嵌入 OCR。
文档：数字文档和扫描文档，包括图像	书籍、文章和报表	文档智能读取模型	使用异步 API 对文本密集型扫描文档和数字文档进行优化，有助于大规模地自动执行智能文档处理。

关于 Azure AI 视觉 v3.2 GA Read

正在查找最新的 Azure AI 视觉 v3.2 GA Read？所有未来的读取 OCR 增强功能都是前面列出的两项服务的一部分。 Azure AI 视觉 v3.2 将不再更新。有关详细信息，请参阅调用 Azure AI 视觉 3.2 GA 读取 API 和快速入门：Azure AI 视觉 v3.2 GA 读取。

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

指定 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 手写分类示例的屏幕截图。

通过

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

OCR（读取）版