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

安装和运行读取容器Install and run Read containers

容器使你能够在自己的环境中运行计算机视觉 Api。Containers enable you to run the Computer Vision APIs in your own environment. 容器非常适合于特定的安全和数据管理要求。Containers are great for specific security and data governance requirements. 本文介绍如何下载、安装和运行计算机视觉容器。In this article you'll learn how to download, install, and run a Computer Vision container.

"读取" 的单个 Docker 容器可用于计算机视觉。A single Docker container, Read, is available for Computer Vision. 利用 "读取容器",您可以通过不同的图面和背景(如收据、海报和名片)来检测和提取不同对象图像中的打印文本The Read container 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. 此外,读取容器还会检测图像中的手写文本,并提供 PDF、TIFF 和多页文件支持。Additionally, the Read container detects handwritten text in images and provides PDF, TIFF, and multi-page file support. 有关详细信息,请参阅读取 API文档。For more information, see the Read API documentation.

如果还没有 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 the 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.
计算机视觉资源Computer Vision resource 若要使用容器,必须具有:In order to use the container, you must have:

Azure计算机视觉资源和关联的 API 密钥。An Azure Computer Vision resource and the associated API key the endpoint URI. 这两个值都可以在资源的“概述”和“密钥”页上找到,并且是启动容器所必需的。Both values are available on the Overview and Keys pages for the resource and are required to start the container.

{API_KEY} : "密钥" 页上有两个可用的资源键之一{API_KEY}: One of the two available resource keys on the Keys page

{ENDPOINT_URI} : "概述" 页中提供的终结点{ENDPOINT_URI}: The endpoint as provided on the Overview page

正在收集所需参数Gathering required parameters

所有认知服务容器都需要三个主要参数。There are three primary parameters for all Cognitive Services' containers that are required. 最终用户许可协议(EULA)的值必须为 acceptThe end-user license agreement (EULA) must be present with a value of accept. 此外,需要终结点 URL 和 API 密钥。Additionally, both an Endpoint URL and API Key are needed.

终结点 URI {ENDPOINT_URI}Endpoint URI {ENDPOINT_URI}

"终结点URI" 值在相应认知服务资源的 "Azure 门户概述" 页上可用。The Endpoint URI value is available on the Azure portal Overview page of the corresponding Cognitive Service resource. 导航到 "概述" 页,将鼠标悬停在终结点上 ,将显示一个 Copy to clipboard 图标。Navigate to the Overview page, hover over the Endpoint, and a Copy to clipboard icon will appear. 复制并在需要时使用。Copy and use where needed.

收集终结点 uri 供以后使用

密钥 {API_KEY}Keys {API_KEY}

此密钥用于启动容器,并在相应认知服务资源的 Azure 门户 "密钥" 页上可用。This key is used to start the container, and is available on the Azure portal's Keys page of the corresponding Cognitive Service resource. 导航到 "密钥" 页,然后单击 "Copy to clipboard " 图标。Navigate to the Keys page, and click on the Copy to clipboard icon.

获取两个密钥之一供以后使用

重要

这些订阅密钥用于访问认知服务 API。These subscription keys are used to access your Cognitive Service API. 不要共享你的密钥。Do not share your keys. 安全地存储它们,例如,使用 Azure Key Vault。Store them securely, for example, using Azure Key Vault. 我们还建议定期重新生成这些密钥。We also recommend regenerating these keys regularly. 只需一个密钥就能进行 API 调用。Only one key is necessary to make an API call. 重新生成第一个密钥时,可以使用第二个密钥来继续访问该服务。When regenerating the first key, you can use the second key for continued access to the service.

主计算机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

备注

要求和建议基于每秒单个请求的基准,使用 8 MB 的扫描业务信函图像,其中包含29行,总共803个字符。The requirements and recommendations are based on benchmarks with a single request per second, using an 8-MB image of a scanned business letter that contains 29 lines and a total of 803 characters.

下表描述了每个读取容器的最小和建议的资源分配。The following table describes the minimum and recommended allocation of resources for each Read container.

容器Container 最小值Minimum 建议Recommended TPSTPS
(最小值, 最大值)(Minimum, Maximum)
读取Read 1个内核,8 GB 内存,0.24 TPS1 cores, 8-GB memory, 0.24 TPS 8核,16 GB 内存,1.17 TPS8 cores, 16-GB memory, 1.17 TPS 0.24、1.170.24, 1.17
  • 每个核心至少必须为 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 Read are available.

容器Container 容器注册表/存储库/映像名称Container Registry / Repository / Image Name
读取Read containerpreview.azurecr.io/microsoft/cognitive-services-read:latest

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

读取容器的 Docker 请求Docker pull for the Read container

docker pull containerpreview.azurecr.io/microsoft/cognitive-services-read: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
<image-id>       <repository-path/name>    <tag-name>

如何使用容器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 runMore 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. 有关如何获取 {ENDPOINT_URI}{API_KEY} 值的详细信息,请参阅收集必需的参数Refer to gathering required parameters for details on how to get the {ENDPOINT_URI} and {API_KEY} values.

命令的示例docker run可用。Examples of the docker run command are available.

docker run --rm -it -p 5000:5000 --memory 16g --cpus 8 \
containerpreview.azurecr.io/microsoft/cognitive-services-read \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

此命令:This command:

  • 从容器映像中运行读取容器。Runs the Read container from the container image.
  • 分配8个 CPU 内核和16千兆字节(GB)的内存。Allocates 8 CPU core and 16 gigabytes (GB) of memory.
  • 公开 TCP 端口 5000,并为容器分配伪 TTY。Exposes 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 runMore 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.

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

有几种方法可用于验证容器是否正在运行。There are several ways to validate that the container is running. 找到相关容器的外部 IP地址和公开端口, 并打开你喜欢的 web 浏览器。Locate the External IP address and exposed port of the container in question, and open your favorite web browser. 使用以下各种请求 Url 来验证容器是否正在运行。Use the various request URLs below to validate the container is running. 下面列出的示例请求 url 为http://localhost:5000, 但特定容器可能会有所不同。The example request URLs listed below are http://localhost:5000, but your specific container may vary. 请记住, 你要依赖容器的外部 IP地址和公开的端口。Keep in mind that you're to rely on your container's External IP address and exposed port.

请求 URLRequest URL 用途Purpose
http://localhost:5000/ 容器提供主页。The container provides a home page.
http://localhost:5000/status 使用 HTTP GET 请求, 用于验证容器是否正在运行而不会导致终结点查询。Requested with an HTTP 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 该容器提供了一套完整的端点文档和一项试用功能。The container provides a full set of documentation for the endpoints and a Try it out 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.

容器的主页

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

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

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

异步读取Asynchronous read

您可以使用 POST /vision/v2.0/read/core/asyncBatchAnalyzeGET /vision/v2.0/read/operations/{operationId} 操作来以异步方式读取图像,这与计算机视觉服务如何使用相应的 REST 操作类似。You can use the POST /vision/v2.0/read/core/asyncBatchAnalyze and GET /vision/v2.0/read/operations/{operationId} operations in concert to asynchronously read an image, similar to how the Computer Vision service uses those corresponding REST operations. 异步 POST 方法将返回用作 HTTP GET 请求标识符的 operationIdThe asynchronous POST method will return an operationId that is used as the identifer to the HTTP GET request.

在 swagger UI 中,选择要在浏览器中展开的 asyncBatchAnalyzeFrom the swagger UI, select the asyncBatchAnalyze to expand it in the browser. 然后选择 "试用" > 选择 "文件"。Then select Try it out > Choose file. 在此示例中,我们将使用下图:In this example, we'll use the following image:

选项卡和空格

异步 POST 成功运行后,它将返回HTTP 202状态代码。When the asynchronous POST has run successfully, it returns an HTTP 202 status code. 作为响应的一部分,有一个 operation-location 标头,其中包含请求的结果终结点。As part of the response, there is an operation-location header that holds the result endpoint for the request.

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

operation-location 是完全限定的 URL,通过 HTTP GET 访问。The operation-location is the fully qualified URL and is accessed via an HTTP GET. 下面是从上一个映像执行 operation-location URL 的 JSON 响应:Here is the JSON response from executing the operation-location URL from the preceding image:

{
  "status": "Succeeded",
  "recognitionResults": [
    {
      "page": 1,
      "clockwiseOrientation": 2.42,
      "width": 502,
      "height": 252,
      "unit": "pixel",
      "lines": [
        {
          "boundingBox": [
            56,
            39,
            317,
            50,
            313,
            134,
            53,
            123
          ],
          "text": "Tabs VS",
          "words": [
            {
              "boundingBox": [
                90,
                43,
                243,
                53,
                243,
                123,
                94,
                125
              ],
              "text": "Tabs",
              "confidence": "Low"
            },
            {
              "boundingBox": [
                259,
                55,
                313,
                62,
                313,
                122,
                259,
                123
              ],
              "text": "VS"
            }
          ]
        },
        {
          "boundingBox": [
            221,
            148,
            417,
            146,
            417,
            206,
            227,
            218
          ],
          "text": "Spaces",
          "words": [
            {
              "boundingBox": [
                230,
                148,
                416,
                141,
                419,
                211,
                232,
                218
              ],
              "text": "Spaces"
            }
          ]
        }
      ]
    }
  ]
}

同步读取Synchronous read

您可以使用 POST /vision/v2.0/read/core/Analyze 操作同步读取图像。You can use the POST /vision/v2.0/read/core/Analyze operation to synchronously read an image. 如果图像是完整的,则 API 会返回 JSON 响应。When the image is read in its entirety, then and only then does the API return a JSON response. 唯一的例外情况是发生错误。The only exception to this is if an error occurs. 出现错误时,将返回以下 JSON:When an error occurs the following JSON is returned:

{
    status: "Failed"
}

JSON 响应对象与异步版本具有相同的对象关系图。The JSON response object has the same object graph as the asynchronous version. 如果你是 JavaScript 用户并且需要类型安全,则可以使用以下类型将 JSON 响应转换为 AnalyzeResult 对象。If you're a JavaScript user and want type safety, the following types could be used to cast the JSON response as an AnalyzeResult object.

export interface AnalyzeResult {
    status: Status;
    recognitionResults?: RecognitionResult[] | null;
}

export enum Status {
    NotStarted = 0,
    Running = 1,
    Failed = 2,
    Succeeded = 3
}

export enum Unit {
    Pixel = 0,
    Inch = 1
}

export interface RecognitionResult {
    page?: number | null;
    clockwiseOrientation?: number | null;
    width?: number | null;
    height?: number | null;
    unit?: Unit | null;
    lines?: Line[] | null;
}

export interface Line {
    boundingBox?: number[] | null;
    text: string;
    words?: Word[] | null;
}

export enum Confidence {
    High = 0,
    Low = 1
}

export interface Word {
  boundingBox?: number[] | null;
  text: string;
  confidence?: Confidence | null;
}

有关示例用例,请参阅此处的 TypeScript 沙箱,并选择 "运行" 以可视化其易用性。For an example use-case, see the TypeScript sandbox here and select Run to visualize its ease-of-use.

停止容器Stop the container

若要关闭的情况下该容器,其中容器正在运行,在命令行环境中选择Ctrl + CTo 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.

提示

有关疑难解答的详细信息和指南,请参阅认知服务容器常见问题(FAQ)For more troubleshooting information and guidance, see Cognitive Services containers frequently asked questions (FAQ).

计费Billing

认知服务容器使用 Azure 帐户中的相应资源将计费信息发送到 Azure。The Cognitive Services containers send billing information to Azure, using the corresponding 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:

OptionOption 描述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 Computer Vision containers. 综上所述:In summary:

  • 计算机视觉为 Docker 提供 Linux 容器,并封装读取。Computer Vision provides a Linux container for Docker, encapsulating Read.
  • 容器映像从 Azure 中的 "容器预览" 容器注册表下载。Container images are downloaded from the "Container Preview" container registry 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 Read 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