Face コンテナーのインストールと実行 (プレビュー)Install and run Face containers (Preview)

重要

Face コンテナーのユーザー制限に達しました。The limit for Face container users has been reached. 現在、Face コンテナーの新しいアプリケーションは受け付けていません。We are not currently accepting new applications for the Face container.

Azure Cognitive Services Face API には、画像内の人間の顔を検出して分析する Linux Docker コンテナーが用意されています。Azure Cognitive Services Face API provides a Linux Docker container that detects and analyzes 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 サービス コンテナーを使用する前に、次の前提条件を満たす必要があります。You must meet the following prerequisites before you use the Face service 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.
Face リソースFace resource コンテナーを使用するには、以下が必要です。To use the container, you must have:

Azure Face リソースとその関連する 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} : [キー] ページにある 2 つの利用可能なリソース キーのどちらか{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

すべての Cognitive Services のコンテナーに対して必須である、3 つの主要なパラメーターがあります。There are three primary parameters for all Cognitive Services' containers that are required. エンドユーザー使用許諾契約書 (EULA) は、accept の値と共に提示される必要があります。The 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.

エンドポイント URL {ENDPOINT_URI}Endpoint URI {ENDPOINT_URI}

エンドポイント URI の値は、Azure portal で、対応する Cognitive Service リソースの [概要] ページで入手できます。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 portal で、対応する Cognitive Service リソースの [キー] ページで入手できます。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.

後で使用するために 2 つのキーのどちらかを入手する

重要

これらのサブスクリプション キーは、Cognitive Service 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 呼び出しを行うために必要なキーは 1 つだけです。Only one key is necessary to make an API call. 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。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

次の表に、各 Face サービス コンテナーに割り当てる CPU コアとメモリの最小値と推奨値を示します。The following table describes the minimum and recommended CPU cores and memory to allocate for each Face service 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 サービスのコンテナー イメージを利用できます。Container images for the Face service 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

コンテナーを実行するには、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 4g --cpus 1 \
containerpreview.azurecr.io/microsoft/cognitive-services-face \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_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 のホストとしては http://localhost:5000 を使用します。Use 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" アドレスと公開ポートを特定し、任意の 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/ready GET で要求することで、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。Requested with GET, this provides a verification that the container is ready to accept a query against the model. この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。This request can be used for Kubernetes liveness and readiness probes.
http://localhost:5000/status これも GET で要求することで、コンテナーを起動するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。Also requested with GET, this verifies if the api-key used to start the container is valid 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 out](試してみる) の機能が用意されています。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. クエリから戻った後、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.

ヒント

トラブルシューティング情報とガイダンスの詳細については、「Cognitive Services コンテナーについてよくあるご質問 (FAQ)」を参照してください。For more troubleshooting information and guidance, see Cognitive Services containers frequently asked questions (FAQ).

課金Billing

Face サービス コンテナーにより、Azure アカウントの Face リソースが使用され、Azure に課金情報が送信されます。The Face service containers send billing information to Azure by using a Face 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 metering / billing endpoint. お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。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 serving requests.

課金引数Billing arguments

docker run コマンドは、次の 3 つのオプションのすべてに有効な値が指定された場合にコンテナーを起動します。The docker run command will start the container when all three of the following options are provided 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.

まとめSummary

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

  • コンテナー イメージは Azure Container Registry からダウンロードされます。Container images are downloaded from the Azure Container Registry.
  • コンテナー イメージを Docker で実行します。Container images run in Docker.
  • REST API または SDK のいずれかを使用して、コンテナーのホスト URI を指定することによって、Face サービス コンテナーの操作を呼び出すことができます。You can use either the REST API or the SDK to call operations in Face service 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.