Face コンテナーのインストールと実行Install and run Face containers

Azure Cognitive Services Face では、画像中の人の顔を検出する、標準化された 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. 検出に加えて、Face では、同じ画像または異なる画像中の 2 つの顏が同じかどうかを信頼スコアを使って確認できます。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 では顔をデータベースと照合して、似ている顏や同一の顔が既に存在するかどうかを調べることもできます。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

Face 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 overview」(Docker の概要) を参照してください。For a primer on Docker and container basics, see the Docker overview.

コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。Docker must be configured to allow the containers to connect with and send billing data to Azure.

Windows では、Linux コンテナーをサポートするように Docker を構成しておく必要もあります。On Windows, Docker also must be configured to support Linux containers.

Docker に関する知識Familiarity 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.
Azure Cognitive Services リソースAzure Cognitive Services resource コンテナーを使用するには、以下が必要です。To use the container, you must have:

Azure Cognitive Services リソースおよび関連する課金キーと課金エンドポイント 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. 次の BILLING_ENDPOINT_URI の例に示すように、face/v1.0 ルーティングをエンドポイント 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

Cognitive Services Vision Containers Request フォームに入力して送信し、コンテナーへのアクセスを要求する必要があります。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 Cognitive Services チームがそれをレビューして、プライベート コンテナー レジストリにアクセスするための条件を満たしていることを確認します。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

Cognitive Services コンテナーのプライベート コンテナー レジストリで認証を行うにはいくつかの方法があります。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 コマンドを使用して、Cognitive Services コンテナーのプライベート コンテナー レジストリである 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 Cognitive Services チームから受け取った資格情報に指定されているユーザー名とパスワードにそれぞれ置き換えます。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

次の表に、各 Face API コンテナーに割り当てる CPU コアとメモリの最小値と推奨値を示します。The following table describes the minimum and recommended CPU cores and memory to allocate for each Face API container.

コンテナーContainer 最小値Minimum 推奨Recommended 1 秒あたりのトランザクション数Transactions per second
(最小、最大)(Minimum, maximum)
FaceFace 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.
  • 1 秒あたりのトランザクション数 (TPS)。Transactions per second (TPS).

コアとメモリは、docker run コマンドの一部として使用される --cpus--memory の設定に対応します。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

Face API のコンテナー イメージを利用できます。Container images for the Face API are available.

コンテナーContainer リポジトリRepository
FaceFace 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
<image-id>       <repository-path/name>         <tag-name>

Face コンテナー用の 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

3 つのコンテナーのいずれかを実行するには、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.

前の BILLING_ENDPOINT_URI の例に示すように、face/v1.0 ルーティングをエンドポイント 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:

  • コンテナー イメージから Face コンテナーを実行します。Runs a face container from the container image.
  • 1 つの CPU コアと 4 GB のメモリを割り当てます。Allocates one CPU core and 4 GB of memory.
  • TCP ポート 5000 を公開し、コンテナーに pseudo-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.

重要

コンテナーを実行するには、EulaBillingApiKey の各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。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 上で、2 番目のコンテナーを 5001 上で実行します。For example, run the first container on port 5000 and the second container on port 5001.

このコンテナーと、別の Azure Cognitive Services コンテナーを HOST 上で同時に実行することができます。You can have this container and a different Azure Cognitive Services container running on the HOST together. 同じ Cognitive Services コンテナーの複数のコンテナーを実行することもできます。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 のホストとしては https://localhost:5000 を使用します。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.

RequestRequest 目的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 の liveness probe と readiness probe に対して使用できます。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. クエリから戻った後、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。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

Face API コンテナーにより、Azure アカウントの Face 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 Cognitive Services コンテナーは、計測のために課金エンドポイントに接続していないと、実行のライセンスが許可されません。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. Cognitive Services コンテナーが、お客様のデータ (解析対象の画像やテキストなど) を Microsoft に送信することはありません。Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

Azure への接続Connect 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 コマンドでコンテナーを起動するには、次の 3 つのオプションすべてに有効な値を指定する必要があります。For the docker run command to start the container, all three of the following options must be specified with valid values:

オプションOption 説明Description
ApiKey 課金情報を追跡するために使用される Cognitive Services リソースの 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 課金情報を追跡するために使用される Cognitive Services リソースのエンドポイント。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.
このオプションの値は accept に設定する必要があります。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 を使用して任意のマシンに Cognitive Services をデプロイする方法How to deploy Cognitive Services to any machine using Docker
  • Cognitive Services を AKS にデプロイする方法How to deploy Cognitive Services to AKS

まとめSummary

この記事では、Face API コンテナーをダウンロード、インストール、および実行する方法の概念とワークフローについて説明しました。In this article, you learned concepts and workflow for how to download, install, and run Face API containers. 要約すると:In summary:

  • Face API には、キー フレーズ抽出、言語検出、感情分析を提供する、Docker 用の 3 つの Linux コンテナーが用意されています。The Face API provides three Linux containers for Docker that provide key phrase extraction, language detection, and sentiment analysis.
  • コンテナー イメージは Azure Container Registry からダウンロードされます。Container images are downloaded from the Azure Container Registry.
  • コンテナー イメージを Docker で実行します。Container images run in Docker.
  • REST API または SDK のいずれかを使用して、コンテナーのホスト URI を指定することによって、Face 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.

重要

Cognitive Services コンテナーは、計測のために 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. Cognitive Services コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。Cognitive Services containers don't send customer data, such as the image or text that's being analyzed, to Microsoft.

次の手順Next steps

  • 構成設定については、コンテナーの構成に関するページをご覧ください。For configuration settings, see Configure containers.
  • 顔を検出して識別する方法の詳細については、Face の概要に関するページをご覧ください。To learn more about how to detect and identify faces, see Face overview.
  • コンテナーでサポートされるメソッドの詳細については、Face API に関するページをご覧ください。For information about the methods supported by the container, see the Face API.
  • その他の Cognitive Services コンテナーを使用するには、Cognitive Services コンテナーに関するぺージをご覧ください。To use more Cognitive Services containers, see Cognitive Services containers.