您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

安装和运行识别文本容器Install and run Recognize Text containers

计算机视觉的识别文本部分也可用作 Docker 容器。The Recognize Text portion of Computer Vision is also available as a Docker container. 使用它可以从具有不同表面和背景的各种对象的图像中检测和提取印刷文本,例如收据、海报和名片。It allows you to detect and extract printed text from images of various objects with different surfaces and backgrounds, such as receipts, posters, and business cards.

重要

识别文本容器目前仅适用于英语。The Recognize Text container currently works only with English.

如果没有 Azure 订阅,请在开始之前创建一个免费帐户If you don't have an Azure subscription, create a free account before you begin.

必备组件Prerequisites

使用“识别文本”容器前,必须先满足以下先决条件:You must meet the following prerequisites before using Recognize Text containers:

需要Required 目的Purpose
Docker 引擎Docker Engine 需要在主计算机上安装 Docker 引擎。You need the Docker Engine installed on a host computer. Docker 提供用于在 macOSWindowsLinux 上配置 Docker 环境的包。Docker provides packages that configure the Docker environment on macOS, Windows, and Linux. 有关 Docker 和容器的基础知识,请参阅 Docker 概述For a primer on Docker and container basics, see the Docker overview.

必须将 Docker 配置为允许容器连接 Azure 并向其发送账单数据。Docker must be configured to allow the containers to connect with and send billing data to Azure.

在 Windows 上,还必须将 Docker 配置为支持 Linux 容器。On Windows, Docker must also be configured to support Linux containers.

熟悉 DockerFamiliarity with Docker 应对 Docker 概念有基本的了解,例如注册表、存储库、容器和容器映像,以及基本的 docker 命令的知识。You should have a basic understanding of Docker concepts, like registries, repositories, containers, and container images, as well as knowledge of basic docker commands.
AzureCognitive Services资源Azure Cognitive Services resource 若要使用容器,必须具有:In order to use the container, you must have:

一个_认知服务_Azure 资源和关联的计费密钥计费终结点 URI。A Cognitive Services Azure resource and the associated billing key the billing endpoint URI. 这两个值的资源概述和密钥页上可用,并且要求来启动该容器。Both values are available on the Overview and Keys pages for the resource and are required to start the container. 需将 vision/v2.0 路由添加到终结点 URI,如以下 BILLING_ENDPOINT_URI 示例所示。You need to add the vision/v2.0 routing to the endpoint URI as shown in the following BILLING_ENDPOINT_URI example.

{BILLING_KEY} :资源密钥{BILLING_KEY}: resource key

{BILLING_ENDPOINT_URI} :终结点 URI 示例如下:https://westus.api.cognitive.microsoft.com/vision/v2.0{BILLING_ENDPOINT_URI}: endpoint URI example is: https://westus.api.cognitive.microsoft.com/vision/v2.0

请求访问专用容器注册表Request access to the private container registry

填写并提交认知服务影像容器请求窗体容器请求访问。Fill out and submit the Cognitive Services Vision Containers Request form to request access to the container. 通过该表单请求有关你、你的公司以及要使用该容器的用户方案的信息。The form requests information about you, your company, and the user scenario for which you'll use the container. 在提交表单后,Azure 认知服务团队会检查,以确保满足的条件访问专用容器注册表的权限。After you submit the form, the Azure Cognitive Services team reviews it to make sure that you meet the criteria for access to the private container registry.

重要

必须使用与 Microsoft 帐户 (MSA) 或窗体中的 Azure Active Directory (Azure AD) 帐户相关联的电子邮件地址。You must use an email address associated with either a Microsoft Account (MSA) or an Azure Active Directory (Azure AD) account in the form.

如果你的请求得到批准,您将收到一封电子邮件的说明介绍如何获取你的凭据和访问专用容器注册表的。If your request is approved, you receive an email with instructions that describe how to obtain your credentials and access the private container registry.

登录到专用容器注册表Log in to the private container registry

有几种方法使用认知服务容器的专用容器注册表进行身份验证。There are several ways to authenticate with the private container registry for Cognitive Services containers. 我们建议你通过使用命令行方法Docker CLIWe recommend that you use the command-line method by using the Docker CLI.

使用docker 登录名命令,如下面的示例中所示中登录到containerpreview.azurecr.io,这是专用容器注册表的认知服务容器。Use the docker login command, as shown in the following example, to log in to containerpreview.azurecr.io, which is the private container registry for Cognitive Services containers. 将 <username> 替换为用户名,将 <password> 替换为从 Azure 认知服务团队收到的凭据中提供的密码 。Replace <username> with the user name and <password> with the password provided in the credentials you received from the Azure Cognitive Services team.

docker login containerpreview.azurecr.io -u <username> -p <password>

如果你保护你的凭据在文本文件中,您可以连接到该文本文件的内容docker login命令。If you secured your credentials in a text file, you can concatenate the contents of that text file to the docker login command. 使用cat命令,如下面的示例中所示。Use the cat command, as shown in the following example. 替换 <passwordFile> 使用的路径和包含密码的文本文件的名称。Replace <passwordFile> with the path and name of the text file that contains the password. 替换 <用户名> 与你的凭据中提供的用户名称。Replace <username> with the user name provided in your credentials.

cat <passwordFile> | docker login containerpreview.azurecr.io -u <username> --password-stdin

主计算机The host computer

主机是运行 Docker 容器且基于 x64 的计算机。The host is a x64-based computer that runs the Docker container. 它可以是本地计算机或 Azure 中的 Docker 托管服务,例如:It can be a computer on your premises or a Docker hosting service in Azure, such as:

容器要求和建议Container requirements and recommendations

下表列出了为每个“识别文本”容器分配的最小和建议 CPU 核心数和内存。The following table describes the minimum and recommended CPU cores and memory to allocate for each Recognize Text container.

容器Container 最小值Minimum 建议Recommended TPSTPS
(最小值, 最大值)(Minimum, Maximum)
识别文本Recognize Text 单核,8GB 内存,0.5 TPS1 core, 8 GB memory, 0.5 TPS 双核,8GB 内存,1 TPS2 cores, 8 GB memory, 1 TPS 0.5, 10.5, 1
  • 每个核心必须至少为 2.6 千兆赫 (GHz) 或更快。Each core must be at least 2.6 gigahertz (GHz) or faster.
  • TPS - 每秒事务数TPS - transactions per second

核心和内存对应于 --cpus--memory 设置,用作 docker run 命令的一部分。Core and memory correspond to the --cpus and --memory settings, which are used as part of the docker run command.

使用 docker pull 获取容器映像Get the container image with docker pull

“识别文本”的容器映像可用。Container images for Recognize Text are available.

容器Container 存储库Repository
识别文本Recognize Text containerpreview.azurecr.io/microsoft/cognitive-services-recognize-text:latest

运行 docker pull 命令下载容器映像。Use the docker pull command to download a container image.

适用于“识别文本”容器的 Docker 拉取Docker pull for the Recognize Text container

docker pull containerpreview.azurecr.io/microsoft/cognitive-services-recognize-text:latest

提示

可以使用 docker images 命令列出下载的容器映像。You can use the docker images command to list your downloaded container images. 例如,以下命令以表格列出每个下载的容器映像的 ID、存储库和标记:For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

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

IMAGE ID            REPOSITORY              TAG
ebbee78a6baa       <container-name>         latest

如何使用容器How to use the container

一旦容器位于主计算机上,请通过以下过程使用容器。Once the container is on the host computer, use the following process to work with the container.

  1. 使用所需的计费设置运行容器Run the container, with the required billing settings. 提供 docker run 命令的多个示例More examples of the docker run command are available.
  2. 查询容器的预测终结点Query the container's prediction endpoint.

通过 docker run 运行容器Run the container with docker run

使用 docker run 命令运行容器。Use the docker run command to run the container. 该命令使用以下参数:The command uses the following parameters:

占位符Placeholder Value
{BILLING_KEY}{BILLING_KEY} 此密钥用于启动此容器,并可在 Azure 上Cognitive Services密钥页。This key is used to start the container, and is available on the Azure Cognitive Services Keys page.
{BILLING_ENDPOINT_URI}{BILLING_ENDPOINT_URI} 帐单终结点 URI 值。The billing endpoint URI value. 下面是示例: https://westus.api.cognitive.microsoft.com/vision/v2.0Example is: https://westus.api.cognitive.microsoft.com/vision/v2.0

需将 vision/v2.0 路由添加到终结点 URI,如以下 BILLING_ENDPOINT_URI 示例所示。You need to add the vision/v2.0 routing to the endpoint URI as shown in the following BILLING_ENDPOINT_URI example.

在以下示例 docker run 命令中,请将这些参数替换为自己的值。Replace these parameters with your own values in the following example docker run command.

docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
containerpreview.azurecr.io/microsoft/cognitive-services-recognize-text \
Eula=accept \
Billing={BILLING_ENDPOINT_URI} \
ApiKey={BILLING_KEY}

此命令:This command:

  • 通过容器映像运行“识别文本”容器Runs a recognize container from the container image
  • 分配一个 CPU 核心和 4 GB 内存Allocates one CPU core and 4 gigabytes (GB) of memory
  • 公开 TCP 端口 5000,并为容器分配伪 TTYExposes TCP port 5000 and allocates a pseudo-TTY for the container
  • 退出后自动删除容器。Automatically removes the container after it exits. 容器映像在主计算机上仍然可用。The container image is still available on the host computer.

提供 docker run 命令的多个示例More examples of the docker run command are available.

重要

必须指定 EulaBillingApiKey 选项运行容器;否则,该容器不会启动。The Eula, Billing, and ApiKey options must be specified to run the container; otherwise, the container won't start. 有关详细信息,请参阅计费For more information, see Billing.

在同一主机上运行多个容器Run multiple containers on the same host

若要使用公开端口运行多个容器,请确保在运行每个容器时使用不同的公开端口。If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. 例如,在端口 5000 上运行第一个容器,在端口 5001 上运行第二个容器。For example, run the first container on port 5000 and the second container on port 5001.

可以让此容器和其他 Azure 认知服务容器一起运行在该主机上。You can have this container and a different Azure Cognitive Services container running on the HOST together. 此外,还可以让同一认知服务容器的多个容器一起运行。You also can have multiple containers of the same Cognitive Services container running.

查询容器的预测终结点Query the container's prediction endpoint

容器提供了基于 REST 的查询预测终结点 API。The container provides REST-based query prediction endpoint APIs.

使用主机 https://localhost:5000,以获得容器 API。Use the host, https://localhost:5000, for container APIs.

异步文本识别Asynchronous text recognition

可以同时使用 POST /vision/v2.0/recognizeTextGET /vision/v2.0/textOperations/*{id}* 操作来异步识别图像中的印刷文本,其方式类似于计算机视觉服务使用相应的 REST 操作。You can use the POST /vision/v2.0/recognizeText and GET /vision/v2.0/textOperations/*{id}* operations in concert to asynchronously recognize printed text in an image, similar to how the Computer Vision service uses those corresponding REST operations. 此时,识别文本容器仅识别印刷文本而无法识别手写文本,因此识别文本容器将忽略通常为计算机视觉服务操作指定的 mode 参数。The Recognize Text container only recognizes printed text, not handwritten text, at this time, so the mode parameter normally specified for the Computer Vision service operation is ignored by the Recognize Text container.

同步文本识别Synchronous text recognition

可使用 POST /vision/v2.0/recognizeTextDirect 操作以同步方式识别图像中的印刷文本。You can use the POST /vision/v2.0/recognizeTextDirect operation to synchronously recognize printed text in an image. 由于此操作是同步的,因此此操作的请求正文与 POST /vision/v2.0/recognizeText 操作的请求正文相同,但此操作的响应正文与 GET /vision/v2.0/textOperations/*{id}* 操作返回的响应正文相同。Because this operation is synchronous, the request body for this operation is the same as that for the POST /vision/v2.0/recognizeText operation, but the response body for this operation is the same as that returned by the GET /vision/v2.0/textOperations/*{id}* operation.

验证容器是否正在运行Validate that a container is running

有几种方法可用于验证容器是否正在运行。There are several ways to validate that the container is running.

请求Request 目的Purpose
http://localhost:5000/ 容器提供主页。The container provides a home page.
http://localhost:5000/status 使用 GET 进行了请求,从而在不会导致终结点查询的情况下验证容器是否正在运行。Requested with GET, to validate that the container is running without causing an endpoint query. 此请求可用于 Kubernetes 运行情况和就绪情况探测This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/swagger 容器提供终结点以及 Try it now 功能的整套文档。The container provides a full set of documentation for the endpoints and a Try it now feature. 使用此功能可以将设置输入到基于 Web 的 HTML 表单并进行查询,而无需编写任何代码。With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. 查询返回后,将提供示例 CURL 命令,用于演示所需的 HTTP 标头和正文格式。After the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format that's required.

容器的主页

停止容器Stop the container

若要关闭容器,请在运行容器的命令行环境中选择 Ctrl+C。To shut down the container, in the command-line environment where the container is running, select Ctrl+C.

故障排除Troubleshooting

如果运行启用了输出装入点和日志记录的容器,该容器会生成有助于排查启动或运行容器时发生的问题的日志文件。If you run the container with an output mount and logging enabled, the container generates log files that are helpful to troubleshoot issues that happen while starting or running the container.

计费Billing

“识别文本”容器使用 Azure 帐户中的“识别文本” 资源向 Azure 发送帐单信息。The Recognize Text containers send billing information to Azure, using a Recognize Text resource on your Azure account.

对该容器的查询在用于 <ApiKey> 的 Azure 资源的定价层计费。Queries to the container are billed at the pricing tier of the Azure resource that's used for the <ApiKey>.

如果未连接到计费终结点进行计量,则 Azure 认知服务容器不会被许可运行。Azure Cognitive Services containers aren't licensed to run without being connected to the billing endpoint for metering. 必须始终让容器可以向计费终结点传送计费信息。You must enable the containers to communicate billing information with the billing endpoint at all times. 认知服务容器不会将客户数据(例如,正在分析的图像或文本)发送给 Microsoft。Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

连接到 AzureConnect to Azure

容器需要计费参数值才能运行。The container needs the billing argument values to run. 这些值使容器可以连接到计费终结点。These values allow the container to connect to the billing endpoint. 容器约每 10 到 15 分钟报告一次使用情况。The container reports usage about every 10 to 15 minutes. 如果容器未在允许的时间范围内连接到 Azure,容器将继续运行,但不会为查询提供服务,直到计费终结点恢复。If the container doesn't connect to Azure within the allowed time window, the container continues to run but doesn't serve queries until the billing endpoint is restored. 尝试连接按 10 到 15 分钟的相同时间间隔进行 10 次。The connection is attempted 10 times at the same time interval of 10 to 15 minutes. 如果无法在 10 次尝试内连接到计费终结点,容器将停止运行。If it can't connect to the billing endpoint within the 10 tries, the container stops running.

计费参数Billing arguments

必须使用有效值指定所有以下三个选项,才能使 docker run 命令启动容器:For the docker run command to start the container, all three of the following options must be specified with valid values:

选项Option 说明Description
ApiKey 用于跟踪计费信息的认知服务资源的 API 密钥。The API key of the Cognitive Services resource that's used to track billing information.
必须将此选项的值设置为 Billing 中指定的已预配资源的 API 密钥。The value of this option must be set to an API key for the provisioned resource that's specified in Billing.
Billing 用于跟踪计费信息的认知服务资源的终结点。The endpoint of the Cognitive Services resource that's used to track billing information.
必须将此选项的值设置为已预配的 Azure 资源的终结点 URI。The value of this option must be set to the endpoint URI of a provisioned Azure resource.
Eula 表示已接受容器的许可条款。Indicates that you accepted the license for the container.
此选项的值必须设置为 acceptThe value of this option must be set to accept.

有关这些选项的详细信息,请参阅配置容器For more information about these options, see Configure containers.

博客文章Blog posts

开发人员示例Developer samples

可在 GitHub 存储库中查看开发人员示例。Developer samples are available at our GitHub repository.

观看网络研讨会View webinar

加入网络研讨会了解:Join the webinar to learn about:

  • 如何将认知服务部署到任何使用 Docker 的计算机How to deploy Cognitive Services to any machine using Docker
  • 如何将认知服务部署到 AKSHow to deploy Cognitive Services to AKS

摘要Summary

本文介绍了与下载、安装和运行“识别文本”容器相关的概念和工作流。In this article, you learned concepts and workflow for downloading, installing, and running Recognize Text containers. 综上所述:In summary:

  • “识别文本”为 Docker 提供了Linux 容器,用于封装识别文本。Recognize Text provides a Linux container for Docker, encapsulating recognize text.
  • 从 Azure 中的 Microsoft 容器注册表 (MCR) 下载容器映像。Container images are downloaded from the Microsoft Container Registry (MCR) in Azure.
  • 容器映像在 Docker 中运行。Container images run in Docker.
  • 可使用 REST API 或 SDK 通过指定容器的主机 URI 来调用“识别文本”容器中的操作。You can use either the REST API or SDK to call operations in Recognize Text containers by specifying the host URI of the container.
  • 必须在实例化容器时指定账单信息。You must specify billing information when instantiating a container.

重要

如果未连接到 Azure 进行计量,则无法授权并运行认知服务容器。Cognitive Services containers are not licensed to run without being connected to Azure for metering. 客户需要始终让容器向计量服务传送账单信息。Customers need to enable the containers to communicate billing information with the metering service at all times. 认知服务容器不会将客户数据(例如,正在分析的图像或文本)发送给 Microsoft。Cognitive Services containers do not send customer data (for example, the image or text that is being analyzed) to Microsoft.

后续步骤Next steps