安裝和執行臉部容器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.


使用臉部 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 連線,以及傳送帳單資料至 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.
臉部資源Face resource 若要使用容器,您必須具有:To use the container, you must have:

Azure臉部資源和相關聯的 API 金鑰和端點 URI。An Azure Face resource and the associated API key and the endpoint URI. 這兩個值都可在資源的 [總覽] 和 [金鑰] 頁面上取得。Both values are available on the Overview and Keys pages for the resource. 您必須啟動容器。They're 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.


這三個必要參數唯一的例外是當容器被視為「離線」容器時。The only exception to these three required parameters is when containers are considered "Offline" containers. 離線容器不會報告使用量、不會計量,而且遵循不同的計費方法。Offline containers do not report usage, are not metered and follow a different billing methodology.


[端點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.

要求私人容器登錄的存取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 CLI來使用命令列方法。We recommend that you use the command-line method by using the Docker CLI.

使用docker login命令 (如下列範例所示) 來登入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. < username> 取代為您的認證中提供的使用者名稱。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 1核心,2 GB 記憶體1 core, 2-GB memory 1核心,4 GB 記憶體1 core, 4-GB memory 10, 2010, 20
  • 每個核心必須至少有 2.6 GHz 或更快的速度。Each core must be at least 2.6 GHz or faster.
  • 每秒交易數(TP)。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 pull 的容器映射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. 例如,下列命令會列出每個已下載之容器映像的識別碼、存放庫和標籤,並將它格式化為表格: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>

臉部容器的 docker pullDocker 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 執行容器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 runExamples of the docker run command are available.

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

此命令: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.


您必須Billing指定ApiKey 、和選項來執行容器,否則容器將不會啟動。 EulaThe 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.

針對容器 API 請使用主機 http://localhost:5000Use the host, http://localhost:5000, for container APIs.

驗證容器正在執行Validate that a container is running

有數種方式可驗證容器正在執行。There are several ways to validate that the container is running. 找出有問題之容器的外部 IP位址和公開端口, 然後開啟您最愛的網頁瀏覽器。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.


停止容器Stop the container

若要關閉的容器,容器執行所在的命令列環境中選取Ctrl + CTo shut down the container, in the command-line environment where the container is running, select Ctrl+C.


如果您執行具有輸出裝載的容器,而且已啟用記錄,則容器會產生記錄檔,有助於疑難排解您啟動或執行容器時所發生的問題。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.


如需更多疑難排解資訊和指引,請參閱認知服務容器的常見問題(FAQ)For more troubleshooting information and guidance, see Cognitive Services containers frequently asked questions (FAQ).


臉部 API 容器會使用您 Azure 帳戶上的臉部 API 資源,將帳單資訊傳送至 Azure。The Face API containers send billing information to Azure by using a Face API resource on your Azure account.

至容器的查詢會使用於 Azure 資源的定價層計費<ApiKey>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.
此選項的值必須設定為 佈建的資源中指定的 API 金鑰BillingThe 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.
此選項的值必須設定為接受The 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


在本文中,您已瞭解如何下載、安裝及執行臉部 API 容器的概念和工作流程。In this article, you learned concepts and workflow for how to download, install, and run Face API containers. 摘要說明:In summary:

  • 容器映射會從 Azure Container Registry 下載。Container images are downloaded from the Azure Container Registry.
  • 容器映像是在 Docker 中執行。Container images run in Docker.
  • 您可以藉由指定容器的主機 URI,使用 REST API 或 SDK 來呼叫臉部 API 容器中的作業。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