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

安装 Azure AI 视觉 3.2 GA 读取 OCR 容器

项目
09/04/2024

可通过容器在自己的环境中运行 Azure AI 视觉 API，并且容器有助于你满足特定的安全和数据管理要求。本文介绍如何下载、安装以及运行“Azure AI 视觉读取 (OCR)”容器。

通过“读取”容器，可从 JPEG、PNG、BMP、PDF 和 TIFF 文件格式的图像和文档中提取打印文本和手写文本。有关“读取”服务的详细信息，请参阅读取 API 操作指南。

新增功能

提供 Read 容器的 3.2-model-2022-04-30 GA 版本，支持 164 种语言和其他增强功能。如果你是现有客户，请按照下载说明开始操作。

Read 3.2 OCR 容器是最新 GA 模型，提供：

用于增强准确度的新模型。
对同一文档中的多种语言的支持。
对总共 164 种语言的支持。请参阅 OCR 支持的语言完整列表。
既适用于文档又适用于图像的单个操作。
对较大文档和图像的支持。
置信度分数。
对同时包含打印文本和手写文本的文档的支持。
仅从文档中的选定页面提取文本的功能。
用于将默认文本行输出顺序更改为更自然的语言阅读顺序（仅限拉丁语）的选择。
作为手写样式或并非仅适用于拉丁语的文本行分类。

如果目前使用的是读取 2.0 容器，请参阅迁移指南，了解新版本中的更改。

先决条件

使用容器前，必须满足以下先决条件：

必须	目的
Docker 引擎	需要在主计算机上安装 Docker 引擎。 Docker 提供用于在 macOS、Windows 和 Linux 上配置 Docker 环境的包。有关 Docker 和容器的基础知识，请参阅 Docker 概述。必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。在 Windows 上，还必须将 Docker 配置为支持 Linux 容器。
熟悉 Docker	应对 Docker 概念有基本的了解，例如注册表、存储库、容器和容器映像，以及基本的 `docker` 命令的知识。
计算机视觉资源	若要使用容器，必须具有：计算机视觉资源和关联的 API 密钥及终结点 URI。这两个值都可以在资源的“概述”和“密钥”页上找到，并且是启动容器所必需的。 {API_KEY} ：“密钥”页上提供的两个可用资源密钥中的一个 {ENDPOINT_URI} ：“概述”页上提供的终结点

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

收集必需的参数

所有 Azure AI 容器都需要三个主要参数。 Microsoft 软件许可条款的值必须为 accept。还需要终结点 URI 和 API 密钥。

终结点 URI

可在 Azure 门户中相应 Azure AI 服务资源的“概览”页上找到 {ENDPOINT_URI} 值。转到“概述”页，将鼠标悬停在终结点上就会显示一个“复制到剪贴板” 图标。在需要的地方复制并使用终结点。

屏幕截图显示如何收集终结点 URI 以供将来使用。

键

{API_KEY} 值用于启动容器，可在 Azure 门户中相应 Azure AI 服务资源的“密钥”页上找到。转到“密钥”页，选择“复制到剪贴板” 图标。

屏幕截图显示如何获取两个密钥之一以供将来使用。

重要

这些订阅密钥用于访问 Azure AI 服务 API。请勿共享密钥。安全地存储它们。例如，使用 Azure Key Vault。此外，建议定期重新生成这些密钥。发出 API 调用只需一个密钥。重新生成第一个密钥时，可以使用第二个密钥继续访问服务。

主机计算机要求

主机是运行 Docker 容器且基于 x64 的计算机。它可以是本地计算机或 Azure 中的 Docker 托管服务，例如：

Azure Kubernetes 服务。
Azure 容器实例。
部署到 Azure Stack 的 Kubernetes 群集。有关详细信息，请参阅将 Kubernetes 部署到 Azure Stack。

高级矢量扩展支持

主计算机是运行 docker 容器的计算机。主机必须支持高级矢量扩展 (AVX2)。可使用以下命令检查 Linux 主机是否提供 AVX2 支持：

grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected

警告

需要主计算机来支持 AVX2。如果没有 AVX2 支持，容器将无法正常运行。

容器要求和建议

注意

这些要求和建议基于这样的基准：每秒一个请求，使用包含 29 行和总共 803 个字符的经过扫描的业务信函的 523-KB 映像。与最低配置相比，建议配置使响应速度提高了大约 2 倍。

下表显示了每个 Read OCR 容器的最小和建议资源分配。

容器	最小值	建议
Read 3.2 2022-04-30	4 个内核，8 GB 内存	8 个内核，16 GB 内存
读取 3.2 2021-04-12	4 个内核，16 GB 内存	8 个内核，24 GB 内存

每个核心必须至少为 2.6 千兆赫 (GHz) 或更快。

核心和内存对应于 --cpus 和 --memory 设置，用作 docker run 命令的一部分。

获取容器映像

可在 mcr.microsoft.com 容器注册表联合项中找到 Azure AI 视觉读取 OCR 容器映像。该映像驻留在 azure-cognitive-services 存储库中，名为 read。完全限定的容器映像名称为 mcr.microsoft.com/azure-cognitive-services/vision/read。

要使用最新版本的容器，可以使用 latest 标记。还可以在 MCR 上找到标记的完整列表。

你可以获取以下可供读取的容器映像。

容器	容器注册表/存储库/映像名称	Tags
Read 3.2 GA	`mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30`	最新版，3.2，3.2-model-2022-04-30

使用 docker pull 命令下载容器映像。

docker pull mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

提示

可以使用 docker images 命令列出下载的容器映像。例如，以下命令以表格列出每个下载的容器映像的 ID、存储库和标记：

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

如何使用容器

一旦容器位于主计算机上，请通过以下过程使用容器。

使用所需的计费设置运行容器。提供 docker run 命令的多个示例。
查询容器的预测终结点。

运行容器

使用 docker run 命令运行容器。有关如何获取 {ENDPOINT_URI} 和 {API_KEY} 值的详细信息，请参阅收集必需的参数。

docker run 命令的示例可用。

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30 \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

上面的命令：

从容器映像运行 Read OCR 最新 GA 版容器。
分配 8 个 CPU 核心和 16 千兆字节 (GB) 内存。
公开 TCP 端口 5000，并为容器分配伪 TTY。
退出后自动删除容器。容器映像在主计算机上仍然可用。

你也可以使用环境变量运行容器：

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
--env Eula=accept \
--env Billing={ENDPOINT_URI} \
--env ApiKey={API_KEY} \
mcr.microsoft.com/azure-cognitive-services/vision/read:3.2-model-2022-04-30

提供 docker run 命令的多个示例。

重要

必须指定 Eula、Billing 和 ApiKey 选项运行容器；否则，该容器不会启动。有关详细信息，请参阅计费。

如果使用 Azure 存储来存储图像以进行处理，则可以创建在调用容器时要使用的连接字符串。

若要查找连接字符串，请执行以下操作：

导航到 Azure 门户上的“存储帐户”，然后找到你的帐户。
选择左侧导航列表中的“访问密钥”。
连接字符串将位于“连接字符串”下面

在同一主机上运行多个容器

若要使用公开端口运行多个容器，请确保在运行每个容器时使用不同的公开端口。例如，在端口 5000 上运行第一个容器，在端口 5001 上运行第二个容器。

可以让此容器和其他 Azure AI 服务容器一起在主机上运行。此外，还可以让同一 Azure AI 服务容器的多个容器一起运行。

验证容器是否正在运行

有几种方法可用于验证容器是否正在运行。找到相关容器的外部 IP 地址和公开端口，并打开你常用的 Web 浏览器。使用以下各种请求 URL 验证容器是否正在运行。此处列出的示例请求 URL 是 http://localhost:5000，但是你的特定容器可能会有所不同。请确保依赖容器的外部 IP 地址和公开端口。

请求 URL	用途
`http://localhost:5000/`	容器提供主页。
`http://localhost:5000/ready`	使用 GET 对此 URL 进行请求，可以验证容器是否已准备好接受针对模型的查询。此请求可用于 Kubernetes 运行情况和就绪情况探测。
`http://localhost:5000/status`	同样使用 GET 对此 URL 进行请求，可以验证用于启动容器的 api-key 是否有效，而不会导致终结点查询。此请求可用于 Kubernetes 运行情况和就绪情况探测。
`http://localhost:5000/swagger`	容器为终结点提供一组完整的文档以及“尝试”功能。使用此功能可以将设置输入到基于 Web 的 HTML 表单并进行查询，而无需编写任何代码。查询返回后，将提供示例 CURL 命令，用于演示所需的 HTTP 标头和正文格式。

容器的主页

查询容器的预测终结点

容器提供了基于 REST 的查询预测终结点 API。

为容器 API 使用主机 http://localhost:5000。可以在以下位置查看 Swagger 路径：http://localhost:5000/swagger/。

异步读取

可以同时使用 POST /vision/v3.2/read/analyze 和 GET /vision/v3.2/read/operations/{operationId} 操作来异步读取图像，类似于 Azure AI 视觉服务使用相应 REST 操作的方式。异步 POST 方法将返回一个 operationId，它用作 HTTP GET 请求的标识符。

在 Swagger UI 中，选择 Analyze 以在浏览器中将其展开。然后选择“试用”>“选择文件”。在本示例中，我们将使用以下图像：

制表符与空格

异步 POST 成功运行后，它会返回 HTTP 202 状态代码。作为响应的一部分，有一个 operation-location 标头，其中包含请求的结果终结点。

 content-length: 0
 date: Fri, 04 Sep 2020 16:23:01 GMT
 operation-location: http://localhost:5000/vision/v3.2/read/operations/a527d445-8a74-4482-8cb3-c98a65ec7ef9
 server: Kestrel

operation-location 是完全限定的 URL，可通过 HTTP GET 访问。以下是从上图执行 operation-location URL 的 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.0",
    "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
              }
            ]
          },
          {
            "boundingBox": [
              286,
              171,
              415,
              165,
              417,
              197,
              287,
              201
            ],
            "text": "paces",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.746
              }
            },
            "words": [
              {
                "boundingBox": [
                  286,
                  179,
                  404,
                  166,
                  405,
                  198,
                  290,
                  201
                ],
                "text": "paces",
                "confidence": 0.938
              }
            ]
          }
        ]
      }
    ]
  }
}

重要

如果将多个 Read OCR 容器部署在负载均衡器之后（例如，在 Docker Compose 或 Kubernetes 下面），则必须有外部缓存。由于进行处理的容器和 GET 请求容器可能不是同一个容器，因此外部缓存会存储结果并在容器之间共享这些结果。有关缓存设置的详细信息，请参阅配置 Azure AI 视觉 Docker 容器。

同步读取

可以使用以下操作来同步读取图像。

POST /vision/v3.2/read/syncAnalyze

完整读取图像后，API 才会返回 JSON 响应。此行为的唯一例外是在发生错误时。发生错误时，将返回以下 JSON：

{
    "status": "Failed"
}

JSON 响应对象具有与异步版本相同的对象图。如果你是 JavaScript 用户并且需要类型安全性，则可以使用 TypeScript 强制转换 JSON 响应。

有关示例用例，请在此处查看 TypeScript 沙盒，然后选择运行以直观显示其易用性。

运行已与 Internet 断开连接的容器

要使用此与 Internet 断开连接的容器，必须首先通过填写申请并购买承诺计划来请求访问权限。有关详细信息，请参阅在断开连接的环境中使用 Docker 容器。

如果已获准运行与 Internet 断开连接的容器，请使用以下示例，其中显示了将会使用的 docker run 命令的格式和占位符值。将这些占位符值替换为你自己的值。

docker run 命令中的 DownloadLicense=True 参数将会下载一个许可证文件，该文件将支持 Docker 容器能够在未连接到 Internet 时运行。它还包含到期日期，在此日期之后，许可证文件将失效，无法运行容器。只能将许可证文件用于已获批准的相应容器。例如，不能将语音转文本容器的许可证文件用于文档智能容器。

占位符	Value	格式或示例
`{IMAGE}`	要使用的容器映像。	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice`
`{LICENSE_MOUNT}`	将下载和装载许可证的路径。	`/host/license:/path/to/license/directory`
`{ENDPOINT_URI}`	用于对服务请求进行身份验证的终结点。可以在 Azure 门户中资源的“密钥和终结点”页上找到此项。	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{API_KEY}`	文本分析资源的密钥。可以在 Azure 门户中资源的“密钥和终结点”页上找到此项。	`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
`{CONTAINER_LICENSE_DIRECTORY}`	容器本地文件系统上的许可证文件夹的位置。	`/path/to/license/directory`

docker run --rm -it -p 5000:5000 \ 
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}

下载许可证文件后，可以在断开连接的环境中运行容器。以下示例演示你将使用的 docker run 命令的格式设置以及占位符值。将这些占位符值替换为你自己的值。

无论容器在何处运行，都必须将许可证文件装载到容器，并且必须使用 Mounts:License= 指定容器本地文件系统上许可证文件夹的位置。还必须指定输出装载，以便可以写入计费使用情况记录。

占位符	Value	格式或示例
`{IMAGE}`	要使用的容器映像。	`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice`
`{MEMORY_SIZE}`	要分配给容器的适当内存大小。	`4g`
`{NUMBER_CPUS}`	要分配给容器的适当 CPU 数。	`4`
`{LICENSE_MOUNT}`	将放置和装载许可证的路径。	`/host/license:/path/to/license/directory`
`{OUTPUT_PATH}`	记录使用情况记录的输出路径。	`/host/output:/path/to/output/directory`
`{CONTAINER_LICENSE_DIRECTORY}`	容器本地文件系统上的许可证文件夹的位置。	`/path/to/license/directory`
`{CONTAINER_OUTPUT_DIRECTORY}`	容器本地文件系统上的输出文件夹的位置。	`/path/to/output/directory`

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \ 
-v {LICENSE_MOUNT} \ 
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

停止容器

若要关闭容器，请在运行容器的命令行环境中选择 Ctrl+C。

故障排除

如果运行启用了输出装入点和日志记录的容器，该容器会生成有助于排查启动或运行容器时发生的问题的日志文件。

提示

如需更多的故障排除信息和指南，请参阅 Azure AI 容器常见问题解答 (FAQ)。

如果在运行 Azure AI 服务容器时遇到问题，可以尝试使用 Microsoft 诊断容器。使用此容器可以诊断部署环境中可能阻止 Azure AI 容器按预期运行的常见错误。

若要获取容器，请使用以下 docker pull 命令：

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

然后运行容器。将 {ENDPOINT_URI} 替换为你的终结点，将 {API_KEY} 替换为你的资源的密钥：

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

容器会测试与计费终结点之间的网络连接性。

计费

Azure AI 容器使用 Azure 帐户中的相应资源向 Azure 发送计费信息。

对该容器的查询在用于 ApiKey 参数的 Azure 资源的定价层计费。

Azure AI 服务容器在未连接到计量或计费终结点的情况下无权运行。必须始终让容器可以向计费终结点传送计费信息。 Azure AI 服务容器不会将客户数据（例如，正在分析的图像或文本）发送给 Microsoft。

连接到 Azure

容器需要计费参数值才能运行。这些值使容器可以连接到计费终结点。容器约每 10 到 15 分钟报告一次使用情况。如果容器未在允许的时间范围内连接到 Azure，容器将继续运行，但不会为查询提供服务，直到计费终结点恢复。尝试连接按 10 到 15 分钟的相同时间间隔进行 10 次。如果无法在 10 次尝试内连接到计费终结点，容器会停止处理请求。有关发送给 Microsoft 进行计费的信息的示例，请参阅 Azure AI 服务容器常见问题解答。

计费参数

当以下三个选项都提供了有效值时，docker run 命令会启动容器：

选项	说明
`ApiKey`	用于跟踪账单信息的 Azure AI 服务资源的 API 密钥。必须将此选项的值设置为 `Billing` 中指定的已预配资源的 API 密钥。
`Billing`	用于跟踪账单信息的 Azure AI 服务资源的终结点。必须将此选项的值设置为已预配的 Azure 资源的终结点 URI。
`Eula`	表示已接受容器的许可条款。此选项的值必须设置为 accept。

有关这些选项的详细信息，请参阅配置容器。

总结

在本文中，你已学习相关概念，以及 Azure AI 视觉容器的下载、安装和运行工作流。综上所述：

Azure AI 视觉为 Docker 提供 Linux 容器，用于封装读取。
读取容器映像需要应用程序才能运行。
容器映像在 Docker 中运行。
可以使用 REST API 或 SDK 通过指定容器的主机 URI 来调用读取 OCR 容器中的操作。
必须在实例化容器时指定账单信息。

重要

如果未连接到 Azure 进行计量，则无法授权并运行 Azure AI 容器。客户需要始终让容器向计量服务传送账单信息。 Azure AI 容器不会将客户数据（例如，正在分析的图像或文本）发送给 Microsoft。

后续步骤

查看配置容器了解配置设置
查看 OCR 概述，了解有关识别印刷文本和手写文本的详细信息
如需详细了解该容器支持的方法，请参阅读取 API。
参阅常见问题解答 (FAQ)，以解决与 Azure AI 视觉功能相关的问题。
使用更多 Azure AI 容器

通过