你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
调用 Azure AI 视觉 3.2 GA 读取 API
本指南展示了如何调用 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 读取。
输入要求
读取 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
}
]
}
]
}
]
}
}
文本行手写分类（仅限拉丁语）
响应中包括一个分类（指明每行文本是否为手写体），以及一个置信度得分。 此功能仅适用于拉丁语。 以下示例演示了图像中文本的手写分类。
