调用 Azure AI 视觉 3.2 GA 读取 API
本指南展示了如何调用 v3.2 GA 读取 API 从图像中提取文本。 你将了解此 API 行为的不同配置方式以满足你的需求。 本指南假设已经创建视觉资源并获得了密钥和终结点 URL。 如果没有，请按照快速入门中的说明开始操作。
输入要求
读取 API 调用采用图像和文档作为输入。 这些输入需满足以下要求：
- 支持的文件格式：JPEG、PNG、BMP、PDF 和 TIFF
- 对于 PDF 和 TIFF 文件，最多处理 2,000 个页面（对于免费层，只处理前两个页面）。
- 图像的文件大小必须小于 500 MB（对于免费层，则为 4 MB），且尺寸介于 50 x 50 和 10,000 x 10,000 像素之间。 PDF 文件没有大小限制。
- 对于 1024 x 768 的图像，要提取的文本的最小高度为 12 像素。 这对应于大约 8 个字体点文本，即 150 DPI。
注意
无需裁剪文本行的图像。 将整个图像发送到读取 API，它将识别所有文本。
确定如何处理数据（可选）
指定 OCR 模型
默认情况下，此服务使用最新的正式发布 (GA) 模型来提取文本。 从 Read 3.2 开始，model-version 参数允许在给定 API 版本的 GA 和预览版模型之间选择。 指定的模型将用于使用读取操作提取文本。
使用读取操作时，请为可选 model-version 参数使用以下值。
| 值 | 使用的模型 |
|---|---|
| 未提供 | 最新 GA 模型 |
| 最新 | 最新 GA 模型 |
| 2022-04-30 | 最新 GA 模型。 适用于印制文本的 164 种语言，以及适用于手写文本的 9 种语言，还有多项有关质量和性能的增强功能 |
| 2022-01-30-preview | 预览模型添加了对印地语、阿拉伯语和相关语言的印制文本的支持。 对于手写文本，添加了对日语和朝鲜语的支持。 |
| 2021-09-30-preview | 预览模型添加了对俄语和其他西里尔语的印制文本的支持。 对于手写文本，添加了对简体中文、法语、德语、意大利语、葡萄牙语和西班牙语的支持。 |
| 2021-04-12 | 2021 GA 模型 |
输入语言
默认情况下，服务从图像或文档（包括混合语言）中提取所有文本。 读取操作包含可选语言请求参数。 如果希望强制将文档作为该特定语言处理，则仅提供语言代码。 否则，服务可能会返回不完整和不正确的文本。
自然读取顺序输出（仅限拉丁语）
默认情况下，服务按从左到右的顺序输出文本行。 （可选）使用 readingOrder 请求参数，为更易于阅读的读取顺序输出使用 natural，如下例所示。 此功能仅支持拉丁语。
选择要进行文本提取的页面或页面范围
默认情况下，服务从文档的所有页面提取文本。 （可选）使用 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/49a36324-fc4b-4387-aa06-090cfbf0064f |
注意
Billing
Azure AI 视觉定价页面包含了读取 API 的定价层。 分析的每个图像或页面均为一个事务。 如果对包含 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 次调用。 付费层允许的每秒请求数 (RPS) 为 30 个，此限制可通过请求提高。 注意你的 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
}
]
}
]
}
]
}
}
文本行手写分类（仅限拉丁语）
响应中包括一个分类（指明每行文本是否为手写体），以及一个置信度得分。 此功能仅适用于拉丁语。 以下示例演示了图像中文本的手写分类。
