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

注意

  • 感情分析と言語検出のためのコンテナーが、一般提供されるようになりました。 キー フレーズ抽出のコンテナーは、制限なしのパブリック プレビューとして使用できます。
  • 現時点では、エンティティのリンクと NER をコンテナーとして使用することはできません。
  • コンテナー イメージの場所が最近変更された可能性があります。 このコンテナーの更新された場所については、この記事をご覧ください。

コンテナーを使用すると、独自の環境で Text Analytic API を実行でき、セキュリティとデータ ガバナンスの固有の要件に対応できます。 Text Analytics コンテナーは、未加工のテキストに対して高度な自然言語処理を提供し、主要な機能として、感情分析、キー フレーズ抽出、言語検出の 3 つを備えています。

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

重要

無料アカウントは 1 か月あたり 5,000 トランザクションまでに制限されており、FreeStandard 価格レベル のみがコンテナーに対して有効です。 トランザクションの要求レートの詳細については、「データ制限」を参照してください。

前提条件

Text Analytics コンテナーのいずれかを実行するには、ホスト コンピューターおよびコンテナー環境が必要です。

準備

Text Analytics コンテナーを使用する前に、次の前提条件を満たす必要があります。

必須 目的
Docker エンジン ホスト コンピューターに Docker エンジンをインストールしておく必要があります。 Docker には、macOSWindowsLinux 上で Docker 環境の構成を行うパッケージが用意されています。 Docker やコンテナーの基礎に関する入門情報については、「Docker overview」(Docker の概要) を参照してください。

コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。

Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。

Docker に関する知識 レジストリ、リポジトリ、コンテナー、コンテナー イメージなど、Docker の概念の基本的な理解に加えて、基本的な docker コマンドの知識が必要です。
Text Analytics リソース コンテナーを使用するためには、以下が必要です。

Free (F0) または Standard (S) 価格レベルの Azure Text Analytics リソース。 Azure portal でリソースの [Key and endpoint](キーとエンドポイント) ページに移動して、関連付けられている API キーとエンドポイント URI を取得する必要があります。

{API_KEY} : 利用可能な 2 つのリソース キーのどちらか。

{ENDPOINT_URI} : リソースのエンドポイント。

必須パラメーターの収集

すべての Cognitive Services のコンテナーに対して必須である、3 つの主要なパラメーターがあります。 エンドユーザー使用許諾契約書 (EULA) は、accept の値と共に提示される必要があります。 さらに、エンドポイント URL と API キーの両方が必要です。

エンドポイント URL {ENDPOINT_URI}

エンドポイント URI の値は、Azure portal で、対応する Cognitive Service リソースの [概要] ページで入手できます。 [概要] ページに移動して、エンドポイントの上にマウス ポインターを移動すると、Copy to clipboard アイコンが表示されます。 必要に応じてコピーして使用します。

後で使用するためにエンドポイント URI を収集する

キー {API_KEY}

このキーはコンテナーを起動するために使用され、Azure portal で、対応する Cognitive Service リソースの [キー] ページで入手できます。 [キー] ページに移動し、Copy to clipboard アイコンをクリックします。

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

重要

これらのサブスクリプション キーは、Cognitive Service API にアクセスするために使用されます。 キーを共有しないでください。 Azure Key Vault を使用するなどして、安全に保管してください。 これらのキーを定期的に再生成することもお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。

Text Analytics for Health コンテナーを使用している場合は、責任ある AI (RAI) 確認も accept の値で存在する必要があります。

ホスト コンピューター

ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。 お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内の Docker ホスティング サービスを使用することもできます。

コンテナーの要件と推奨事項

次の表に、Text Analytics コンテナーの最小仕様と推奨仕様を説明します。 少なくとも 2 ギガバイト (GB) のメモリが必要であり、各 CPU コアは 2.6 ギガヘルツ (GHz) 以上である必要があります。 秒あたりの許可されるトランザクション数 (TPS) も示されます。

最小ホスト仕様 推奨されるホスト仕様 最小 TPS 最大 TPS
言語検出、キー フレーズ抽出 1 コア、2 GB メモリ 1 コア、4 GB メモリ 15 30
感情分析 1 コア、2 GB メモリ 4 コア、8 GB メモリ 15 30
Text Analytics for Health - 1 ドキュメント/要求 4 コア、10 GB メモリ 6 コア、12 GB メモリ 15 30
Text Analytics for Health - 10 ドキュメント/要求 6 コア、16 GB メモリ 8 コア、20 GB メモリ 15 30

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

docker pull によるコンテナー イメージの取得

ヒント

docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。 たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Text Analytics のコンテナー イメージは Microsoft コンテナー レジストリで入手できます。

感情分析コンテナー v3 用の docker pull

複数の言語で、感情分析コンテナー v3 のコンテナーを使用できます。 英語のコンテナー用のコンテナーをダウンロードするには、次のコマンドを使用します。

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/sentiment:3.0-en

別の言語用のコンテナーをダウンロードするには、en を次のいずれかの言語コードに置き換えます。

Text Analytics コンテナー 言語コード
簡体中国語 zh-hans
繁体字中国語 zh-hant
オランダ語 nl
英語 en
フランス語 fr
ドイツ語 de
ヒンディー語 hi
イタリア語 it
日本語 ja
韓国語 ko
ノルウェー語 (ブークモール) no
ポルトガル語 (ブラジル) pt-BR
ポルトガル語 (ポルトガル) pt-PT
スペイン語 es
トルコ語 tr

Text Analytics コンテナーで使用可能なタグの詳しい説明については、Docker Hub に関する記事を参照してください。

コンテナーを使用する方法

コンテナーをホスト コンピューター上に用意できたら、次の手順を使用してコンテナーを操作します。

  1. 必要な課金設定を使用してコンテナーを実行します。
  2. コンテナーの予測エンドポイントに対するクエリを実行します

docker run によるコンテナーの実行

コンテナーを実行するには、docker run コマンドを使用します。 コンテナーは一度実行すると、お客様が停止するまで動作し続けます。

重要

  • 以降のセクションの Docker コマンドには、行連結文字としてバック スラッシュ (\) が使用されています。 お客様のホスト オペレーティング システムの要件に応じて、置換または削除してください。
  • コンテナーを実行するには、EulaBillingApiKey の各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。 詳細については、「課金」を参照してください。
  • 感情分析と言語検出のコンテナーは一般提供されています。 v2 の API が使用されているキー フレーズ抽出のコンテナーは、プレビュー段階です。

"感情分析 v3 " コンテナーを実行するには、次の docker run コマンドを実行します。 次のプレースホルダーを実際の値に置き換えてください。

プレースホルダー 形式または例
{API_KEY} 自分の Text Analytics リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI} Text Analytics API にアクセスするためのエンドポイント。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 https://<your-custom-subdomain>.cognitiveservices.azure.com
docker run --rm -it -p 5000:5000 --memory 8g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/textanalytics/sentiment \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

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

  • コンテナー イメージから 感情分析 コンテナーを実行します。
  • 1 つの CPU コアと 8 ギガバイト (GB) のメモリを割り当てます。
  • TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てます
  • コンテナーの終了後にそれを自動的に削除します。 ホスト コンピューター上のコンテナー イメージは引き続き利用できます。

同じホスト上で複数のコンテナーを実行する

公開されているポートを使って複数のコンテナーを実行する予定の場合、必ず各コンテナーを別の公開されているポートで実行してください。 たとえば、最初のコンテナーをポート 5000 上で、2 番目のコンテナーを 5001 上で実行します。

このコンテナーと、別の Azure Cognitive Services コンテナーを HOST 上で同時に実行することができます。 同じ Cognitive Services コンテナーの複数のコンテナーを実行することもできます。

コンテナーの予測エンドポイントに対するクエリの実行

コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。

コンテナーの API のホストとしては http://localhost:5000 を使用します。

コンテナーが実行されていることを検証する

コンテナーが実行されていることを検証する方法は複数あります。 問題になっているコンテナーの "外部 IP" アドレスと公開ポートを特定し、任意の Web ブラウザーを開きます。 以下に示した各種の要求 URL を使用して、コンテナーが実行中であることを確認します。 以下に示した例の要求 URL は http://localhost:5000 ですが、実際のコンテナーは異なる可能性があります。 ベースとなるのは実際のコンテナーの "外部 IP" アドレスと公開ポートであることに注意してください。

要求 URL 目的
http://localhost:5000/ コンテナーには、ホーム ページが用意されています。
http://localhost:5000/ready GET で要求することで、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。
http://localhost:5000/status これも GET で要求することで、コンテナーを起動するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。
http://localhost:5000/swagger コンテナーには、エンドポイントの完全なドキュメント一式と、 [Try it out](試してみる) の機能が用意されています。 この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりできます。 クエリから戻った後、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。

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

コンテナーの停止

コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。

トラブルシューティング

出力マウントとログを有効にした状態でコンテナーを実行すると、コンテナーによってログ ファイルが生成されます。これらはコンテナーの起動時または実行時に発生した問題のトラブルシューティングに役立ちます。

ヒント

トラブルシューティング情報とガイダンスの詳細については、「Cognitive Services コンテナーについてよくあるご質問 (FAQ)」を参照してください。

課金

Text Analytics コンテナーは、Azure アカウントの Text Analytics リソースを使用して、Azure に課金情報を送信します。

コンテナーへのクエリは、ApiKey に使用される Azure リソースの価格レベルで課金されます。

Azure Cognitive Services コンテナーは、計測または課金エンドポイントに接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。 Cognitive Services コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。

Azure に接続する

コンテナーには、実行する課金引数の値が必要です。 これらの値により、コンテナーは課金エンドポイントに接続することができます。 コンテナーから、約 10 ~ 15 分ごとに使用状況が報告されます。 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。 接続は、10 ~15 分の同じ時間間隔で、10 回試行されます。 10 回以内に課金エンドポイントに接続できなかった場合、コンテナーによる要求の処理は停止されます。 課金のために Microsoft に送信される情報の例については、Cognitive Services コンテナーについてよく寄せられる質問を参照してください。

課金引数

docker run コマンドは、次の 3 つのオプションのすべてに有効な値が指定された場合にコンテナーを起動します。

オプション 説明
ApiKey 課金情報を追跡するために使用される Cognitive Services リソースの API キー。
このオプションの値には、Billing に指定されたプロビジョニング済みのリソースの API キーが設定されている必要があります。
Billing 課金情報を追跡するために使用される Cognitive Services リソースのエンドポイント。
このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。
Eula お客様がコンテナーのライセンスに同意したことを示します。
このオプションの値は accept に設定する必要があります。

これらのオプションの詳細については、「コンテナーの構成」を参照してください。

まとめ

この記事では、Text Analytics コンテナーの概念とそのダウンロード、インストール、および実行のワークフローについて説明しました。 要約すると:

  • Text Analytics は、Docker 用に 3 つの Linux コンテナーを提供し、さまざまな機能をカプセル化します。
    • 感情分析
    • キー フレーズ抽出 (プレビュー)
    • 言語検出
    • Text Analytics for Health (プレビュー)
  • コンテナー イメージは、Microsoft Container Registry (MCR) またはプレビュー コンテナー リポジトリからダウンロードされます。
  • コンテナー イメージを Docker で実行します。
  • REST API または SDK を使用して、コンテナーのホスト URI を指定することによって、Text Analytics コンテナーの操作を呼び出すことができます。
  • コンテナーをインスタンス化するときは、課金情報を指定する必要があります。

重要

Cognitive Services コンテナーは、計測のために Azure に接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に計測サービスに課金情報を伝えられるようにする必要があります。 お客様のデータ (解析対象のテキストなど) が Cognitive Services コンテナーによって Microsoft に送信することはありません。

次のステップ