Text Analytics コンテナーをインストールして実行するInstall and run Text Analytics containers

Text Analytics コンテナーは、未加工のテキストに対して高度な自然言語処理を提供し、主要な機能として、感情分析、キー フレーズ抽出、言語検出の 3 つを備えています。The Text Analytics containers provide advanced natural language processing over raw text, and includes three main functions: sentiment analysis, key phrase extraction, and language detection. エンティティ リンク設定は現在コンテナーでサポートされていません。Entity linking is not currently supported in a container.

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。If you don't have an Azure subscription, create a free account before you begin.

前提条件Prerequisites

Text Analytics コンテナーのいずれかを実行するには、ホスト コンピューターおよびコンテナー環境が必要です。In order to run any of the Text Analytics containers, you must have the host computer and container environments.

準備Preparation

Text Analytics コンテナーを使用する前に、次の前提条件を満たす必要があります。You must meet the following prerequisites before using Text Analytics 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 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 must also be configured to support Linux containers.

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

関連付けられている課金キーと課金エンドポイント URI を取得するための Cognitive Services Azure リソース。A Cognitive Services Azure resource to get the associated billing key and billing endpoint URI. どちらの値も、Azure portal の [Cognitive Services Overview](Cognitive Services の概要) ページと [キー] ページで使用でき、コンテナーを開始するために必要です。Both values are available on the Azure portal's Cognitive Services Overview and Keys pages and are required to start the container. text/analytics/v2.0 ルーティングをエンドポイント URI に追加する必要があります。次の BILLING_ENDPOINT_URI の例を参照してください。You need to add the text/analytics/v2.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/text/analytics/v2.1{BILLING_ENDPOINT_URI}: endpoint URI example is: https://westus.api.cognitive.microsoft.com/text/analytics/v2.1

ホスト コンピューター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 including:

コンテナーの要件と推奨事項Container requirements and recommendations

次の表に、各 Text Analytics コンテナーに割り当てる CPU コア (2.6 GHz (ギガヘルツ) 以上) とメモリ (GB 単位) の最小値と推奨値を示します。The following table describes the minimum and recommended CPU cores, at least 2.6 gigahertz (GHz) or faster, and memory, in gigabytes (GB), to allocate for each Text Analytics container.

コンテナーContainer 最小値Minimum 推奨Recommended TPSTPS
(最小、最大)(Minimum, Maximum)
キー フレーズ抽出Key Phrase Extraction 1 コア、2 GB メモリ1 core, 2 GB memory 1 コア、4 GB メモリ1 core, 4 GB memory 15、3015, 30
言語検出Language Detection 1 コア、2 GB メモリ1 core, 2 GB memory 1 コア、4 GB メモリ1 core, 4 GB memory 15、3015, 30
感情分析Sentiment Analysis 1 コア、2 GB メモリ1 core, 2 GB memory 1 コア、4 GB メモリ1 core, 4 GB memory 15、3015, 30
  • 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。Each core must be at least 2.6 gigahertz (GHz) or faster.
  • TPS - 1 秒あたりのトランザクション数TPS - transactions per second

コアとメモリは、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

Text Analytics のコンテナー イメージは Microsoft コンテナー レジストリから入手できます。Container images for Text Analytics are available from Microsoft Container Registry.

コンテナーContainer リポジトリRepository
キー フレーズ抽出Key Phrase Extraction mcr.microsoft.com/azure-cognitive-services/keyphrase
言語検出Language Detection mcr.microsoft.com/azure-cognitive-services/language
感情分析Sentiment Analysis mcr.microsoft.com/azure-cognitive-services/sentiment

docker pull コマンドを使用して Microsoft Container Registry からコンテナー イメージをダウンロードします。Use the docker pull command to download a container image from Microsoft Container Registry.

Text Analytics コンテナーで使用可能なタグの詳しい説明については、Docker Hub の次のコンテナーを参照してください。For a full description of available tags for the Text Analytics containers, see the following containers on the Docker Hub:

docker pull コマンドを使用して、コンテナー イメージをダウンロードします。Use the docker pull command to download a container image.

キー フレーズ抽出コンテナー用の docker pullDocker pull for the Key phrase extraction container

docker pull mcr.microsoft.com/azure-cognitive-services/keyphrase:latest

言語検出コンテナー用の docker pullDocker pull for the language detection container

docker pull mcr.microsoft.com/azure-cognitive-services/language:latest

感情コンテナー用の docker pullDocker pull for the sentiment container

docker pull mcr.microsoft.com/azure-cognitive-services/sentiment: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

コンテナーを使用する方法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 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 portal の Cognitive Services の [キー] ページで確認できます。This key is used to start the container, and is available on the Azure portal's 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.

例:Example:
Billing=https://westus.api.cognitive.microsoft.com/text/analytics/v2.0

text/analytics/v2.0 ルーティングをエンドポイント URI に追加する必要があります。前の BILLING_ENDPOINT_URI の例を参照してください。You need to add the text/analytics/v2.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 example docker run command.

docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/keyphrase \
Eula=accept \
Billing={BILLING_ENDPOINT_URI} \
ApiKey={BILLING_KEY}

このコマンドは、次の操作を行います。This command:

  • コンテナー イメージからキー フレーズ コンテナーを実行しますRuns a key phrase container from the container image
  • 1 つの CPU コアと 4 ギガバイト (GB) のメモリを割り当てますAllocates one CPU core and 4 gigabytes (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; otherwise, the container won't start. 詳細については、「課金」を参照してください。For more information, see Billing.

同じホスト上で複数のコンテナーを実行するRunning 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.

このコンテナーと別のコグニティブ サービス コンテナーをホスト上で一緒に実行したり、同じコグニティブ サービス コンテナーの複数のコンテナーを実行したりできます。You can have this container and a different Cognitive Service container running on the HOST together or you can have multiple containers of the same Cognitive Service 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 container is running

コンテナーが実行されていることを検証する方法は複数あります。There are several ways to validate the container is running:

RequestRequest 目的Purpose
http://localhost:5000/ コンテナーには、ホーム ページが用意されています。The container provides a homepage.
http://localhost:5000/status GET で要求され、エンドポイント クエリを発生させずにコンテナーが実行されていることを検証します。Requested with GET, to validate the container is running without causing an endpoint query. これは Kubernetes の liveness probe と readiness probe に対して使用できます。This 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 as well as a Try it now feature. この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりすることができます。This feature allows you to enter your settings into a web-based HTML form and make the query without having to write any code. クエリから戻ると、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。Once the query returns, an example CURL command is provided to demonstrate the HTTP headers and body format required.

コンテナーのホーム ページ

コンテナーの停止Stop the container

コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。To shut down the container, in the command-line environment where the container is running, press 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.

課金Billing

Text Analytics コンテナーは、Azure アカウントの Cognitive Services リソースを使用して、Azure に課金情報を送信します。The Text Analytics containers send billing information to Azure, using a Cognitive Services resource on your Azure account.

コンテナーへのクエリは、<ApiKey> に使用される Azure リソースの価格レベルで課金されます。Queries to the container are billed at the pricing tier of the Azure resource used for the <ApiKey>.

Cognitive Services コンテナーは、計測のために課金エンドポイントに接続していないと、実行のライセンスが許可されません。Cognitive Services containers are not licensed to run without being connected to the billing endpoint for metering. お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。Customers need to enable the containers to communicate billing information with billing endpoint at all times. Cognitive Services コンテナーが、顧客データ (解析対象の画像やテキストなど) を Microsoft に送信することはありません。Cognitive Services containers do not send customer data (for example, the image or text that is being analyzed) to Microsoft.

Azure への接続Connecting to Azure

コンテナーには、実行する課金引数の値が必要です。The container needs the billing argument values to run. これらの値により、コンテナーは課金エンドポイントに接続することができます。These values allow the container to connect to billing endpoint. コンテナーから、約 10 ~ 15 分ごとに使用状況が報告されます。The container reports usage about every 10 to 15 minutes. 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。If the container doesn't connect within the allowed time window to Azure, the container will continue to run but will not 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 will stop running.

課金引数Billing arguments

docker run コマンドでコンテナーを起動するには、次の 3 つのオプションすべてに有効な値を指定する必要があります。All three of the following options must be specified with valid values in order for the docker run command to start the container:

オプションOption 説明Description
ApiKey 課金情報を追跡するために使用される Cognitive Service リソースの API キー。The API key of the Cognitive Service resource used to track billing information.
このオプションの値には、Billing に指定されたプロビジョニング済みのリソースの API キーが設定されている必要があります。The value of this option must be set to an API key for the provisioned resource specified in Billing.
Billing 課金情報を追跡するために使用される Cognitive Service リソースのエンドポイント。The endpoint of the Cognitive Service resource 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've 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

この記事では、Text Analytics コンテナーの概念とそのダウンロード、インストール、および実行のワークフローについて説明しました。In this article, you learned concepts and workflow for downloading, installing, and running Text Analytics containers. 要約すると:In summary:

  • Text Analytics では、キー フレーズ抽出、言語検出、感情分析をカプセル化する、Docker 用の 3 つの Linux コンテナーが提供されます。Text Analytics provides three Linux containers for Docker, encapsulating key phrase extraction, language detection, and sentiment analysis.
  • コンテナー イメージは、Azure の Microsoft Container Registry (MCR) からダウンロードされます。Container images are downloaded from the Microsoft Container Registry (MCR) in Azure.
  • コンテナー イメージを Docker で実行します。Container images run in Docker.
  • REST API または SDK を使用して、コンテナーのホスト URI を指定することによって、Text Analytics コンテナーの操作を呼び出すことができます。You can use either the REST API or SDK to call operations in Text Analytics containers by specifying the host URI of the container.
  • コンテナーをインスタンス化するときは、課金情報を指定する必要があります。You must specify billing information when instantiating a container.

重要

Cognitive Services コンテナーは、計測のために 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. Cognitive Services コンテナーが、顧客データ (解析対象の画像やテキストなど) を Microsoft に送信することはありません。Cognitive Services containers do not send customer data (e.g., the image or text that is being analyzed) to Microsoft.

次の手順Next steps