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

安装并运行人脸容器Install and run Face containers

Azure 认知服务人脸检测的人脸在图像中的 docker 提供标准化的 Linux 容器。Azure Cognitive Services Face provides a standardized Linux container for Docker that detects human faces in images. 它还标识属性,其中包括如鼻子下面和眼睛、 性别、 年龄和其他机器预测面部识别功能的人脸特征点。It also identifies attributes, which include face landmarks such as noses and eyes, gender, age, and other machine-predicted facial features. 除了检测,人脸可以检查在相同的映像或不同的映像中的两张脸是否相同使用置信度得分。In addition to detection, Face can check if two faces in the same image or different images are the same by using a confidence score. 人脸还可以比较针对一个数据库以查看是否已存在的相似或相同的人脸的人脸。Face also can compare faces against a database to see if a similar-looking or identical face already exists. 它还可以将相似的人脸分组使用共享的视觉特征。It also can organize similar faces into groups by using shared visual traits.

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

必备组件Prerequisites

在使用人脸 API 容器之前,必须满足以下先决条件。You must meet the following prerequisites before you use the Face API containers.

需要Required 目的Purpose
Docker 引擎Docker Engine 必须在上安装 Docker 引擎主机计算机The Docker Engine must be 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 also must be configured to support Linux containers.

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

Azure 认知服务资源和关联的帐单密钥和计费的终结点 URI。An Azure Cognitive Services resource and the associated billing key and the billing endpoint URI. 这两个值位于概述密钥资源页。Both values are available on the Overview and Keys pages for the resource. 它们需要启动该容器。They're required to start the container. 添加face/v1.0路由到终结点 URI,如下面的 BILLING_ENDPOINT_URI 示例中所示:Add the face/v1.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/face/v1.0{BILLING_ENDPOINT_URI}: endpoint URI example is https://westus.api.cognitive.microsoft.com/face/v1.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

下表显示了为每个人脸 API 容器分配的最小和建议的 CPU 核心数和内存。The following table describes the minimum and recommended CPU cores and memory to allocate for each Face API container.

容器Container 最小值Minimum 建议Recommended 每秒事务数Transactions per second
(最低配置,最大)(Minimum, maximum)
人脸Face 单核,2 GB 内存1 core, 2-GB memory 单核,4 GB 内存1 core, 4-GB memory 10, 2010, 20
  • 每个核心必须是至少 2.6 GHz 或速度更快。Each core must be at least 2.6 GHz or faster.
  • 每秒事务数 (TPS)。Transactions per second (TPS).

核心和内存对应于 --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 拉取容器映像Get the container image with docker pull

提供了有关人脸 API 的容器映像。Container images for the Face API are available.

容器Container 存储库Repository
人脸Face containerpreview.azurecr.io/microsoft/cognitive-services-face: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

适用于人脸容器的 Docker 拉取Docker pull for the Face container

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

使用容器Use the container

在容器上后主机计算机,使用以下过程来使用该容器。After 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 the container with docker run

使用 docker run 命令运行三个容器中的任意一个。Use the docker run command to run any of the three containers. 该命令使用以下参数。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 值是可在 Azure 上Cognitive Services概述页。The billing endpoint URI value is available on the Azure Cognitive Services Overview page. 例如 https://westus.api.cognitive.microsoft.com/face/v1.0An example is https://westus.api.cognitive.microsoft.com/face/v1.0.

添加face/v1.0路由到终结点 URI,如前面的 BILLING_ENDPOINT_URI 示例中所示。Add the face/v1.0 routing to the endpoint URI, as shown in the preceding BILLING_ENDPOINT_URI example.

这些参数替换为你自己的值在下面的示例docker run命令示例:Replace these parameters with your own values in the following docker run command example:

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

此命令:This command:

  • 从容器映像中运行的人脸容器。Runs a face container from the container image.
  • 分配一个 CPU 核心和 4 GB 的内存。Allocates one CPU core and 4 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 run 命令的多个示例More examples of the docker run command are available.

重要

EulaBilling,和ApiKey选项必须指定要运行该容器或容器不会启动。The Eula, Billing, and ApiKey options must be specified to run the container or 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.

验证容器是否正在运行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 is enabled, the container generates log files that are helpful to troubleshoot issues that happen while you start or run the container.

计费Billing

人脸 API 容器在你的 Azure 帐户使用人脸 API 资源将计费信息发送到 Azure。The Face API containers send billing information to Azure by using a Face API 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

在本文中,你学习概念以及如何下载、 安装并运行人脸 API 容器的工作流。In this article, you learned concepts and workflow for how to download, install, and run Face API containers. 综上所述:In summary:

  • 人脸 API 为 Docker 提供关键短语提取、 语言检测和情绪分析提供了三个 Linux 容器。The Face API provides three Linux containers for Docker that provide key phrase extraction, language detection, and sentiment analysis.
  • 从 Azure 容器注册表下载容器映像。Container images are downloaded from the Azure Container Registry.
  • 容器映像在 Docker 中运行。Container images run in Docker.
  • 可以使用 REST API 或 SDK 调用人脸 API 容器中的操作通过指定主机的容器的 URI。You can use either the REST API or the SDK to call operations in Face API containers by specifying the host URI of the container.
  • 实例化一个容器时,必须指定计费信息。You must specify billing information when you instantiate a container.

重要

认知服务容器未获得许可,无需连接到 Azure 计数的运行。Cognitive Services containers aren't licensed to run without being connected to Azure for metering. 客户必须使容器能够通信与计量服务在所有时间的计费信息。Customers must enable the containers to communicate billing information with the metering service at all times. 认知服务容器不会将客户数据(例如,正在分析的图像或文本)发送给 Microsoft。Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

后续步骤Next steps