キー フレーズ抽出コンテナーをインストールして実行する
コンテナーを使うと、独自のインフラストラクチャで Key Phrase Extraction API をホストすることができます。 キー フレーズ抽出をリモートで呼び出すことでは満たすことができないセキュリティまたはデータ ガバナンスの要件がある場合は、コンテナーが適している可能性があります。
Note
- 無料アカウントは 1 か月あたり 5,000 テキスト レコードに制限されており、Free および Standard 価格レベルだけがコンテナーに対して有効です。 トランザクションの要求レートの詳細については、「データとサービスの制限」を参照してください。
コンテナーを使用すると、独自の環境で Key Phrase Extraction API を実行でき、セキュリティとデータ ガバナンスの固有の要件に対応できます。 キー フレーズ抽出コンテナーでは、未加工のテキストに対する高度な自然言語処理が提供され、主要な機能として、感情分析、キー フレーズ抽出、言語検出の 3 つが含まれます。
前提条件
- Azure サブスクリプションをお持ちでない場合は、無料アカウントを作成してください。
- ホスト コンピューターに Docker がインストールされていること。 コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。
- Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。
- Docker の概念に関する基本的な知識が必要です。
- Free (F0) または Standard (S) 価格レベルの言語リソース。
必須パラメーターの収集
すべての Azure AI コンテナーに対して 3 つの主要なパラメーターが必須です。 Microsoft ソフトウェア ライセンス条項について、値 accept が示される必要があります。 エンドポイント URI と API キーも必要です。
エンドポイント URL
{ENDPOINT_URI} の値は、Azure portal の対応する Azure AI サービス リソースの [概要] ページで入手できます。 [概要] ページに移動し、エンドポイントの上にマウス ポインターを合わせると、[クリップボードにコピー] アイコンが表示されます。 必要に応じて、エンドポイントをコピーして使用します。
キー
{API_KEY} の値はコンテナーを起動するために使用され、Azure portal で、対応する Azure AI サービス リソースの [キー] ページで入手できます。 [キー] ページに移動し、[クリップボードにコピー] アイコンを選択します。
重要
これらのサブスクリプション キーは、Azure AI サービス API にアクセスするために使用されます。 キーを共有しないでください。 安全に保管してください。 たとえば、Azure Key Vault を使用します。 また、これらのキーを定期的に再生成することをお勧めします。 API 呼び出しを行うために必要なキーは 1 つだけです。 最初のキーを再生成するときに、2 番目のキーを使用してサービスに継続的にアクセスすることができます。
ホスト コンピューターの要件と推奨事項
ホストとは、Docker コンテナーを実行する x64 ベースのコンピューターのことです。 お客様のオンプレミス上のコンピューターを使用できるほか、次のような Azure 内の Docker ホスティング サービスを使用することもできます。
- Azure Kubernetes Service。
- Azure Container Instances。
- Azure Stack にデプロイされた Kubernetes クラスター。 詳しくは、「Kubernetes を Azure Stack にデプロイする」をご覧ください。
次の表では、使用可能なキー フレーズ抽出コンテナーの最小仕様と推奨される仕様について説明します。 各 CPU コアは、少なくとも 2.6 ギガヘルツ (GHz) 以上である必要があります。 許容される 1 秒あたりのトランザクション数 (TPS) も示されています。
| 最小ホスト仕様 | 推奨されるホスト仕様 | 最小 TPS | 最大 TPS | |
|---|---|---|---|---|
| キー フレーズ抽出 | 1 コア、2 GB メモリ | 1 コア、4 GB メモリ | 15 | 30 |
CPU コアとメモリは、docker run コマンドの一部として使用される --cpus と --memory の設定に対応します。
docker pull によるコンテナー イメージの取得
キー フレーズ抽出コンテナー イメージは、mcr.microsoft.com コンテナー イメージ シンジケートにあります。 azure-cognitive-services/textanalytics/ リポジトリ内にあり、keyphrase という名前が付いています。 完全修飾コンテナー イメージ名は mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase です。
最新バージョンのコンテナーを使用するには、latest タグを使用できます。 また、MCR でタグの完全な一覧を確認することもできます。
docker pull コマンドを使用して Microsoft Container Registry からコンテナー イメージをダウンロードします。
docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase:latest
ヒント
docker images コマンドを使用して、ダウンロードしたコンテナー イメージを一覧表示できます。 たとえば、次のコマンドは、ダウンロードした各コンテナー イメージの ID、リポジトリ、およびタグが表として書式設定されて表示されます。
docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
<image-id> <repository-path/name> <tag-name>
docker run によるコンテナーの実行
コンテナーをホスト コンピューター上に準備できたら、docker run コマンドを使用してコンテナーを実行します。 コンテナーは一度実行すると、お客様が停止するまで動作し続けます。
重要
- 以降のセクションの Docker コマンドには、行連結文字としてバック スラッシュ (
\) が使用されています。 お客様のホスト オペレーティング システムの要件に応じて、置換または削除してください。 - コンテナーを実行するには、
Eula、Billing、ApiKeyの各オプションを指定する必要があります。そうしないと、コンテナーが起動しません。 詳細については、「課金」を参照してください。 - 感情分析コンテナーと言語検出コンテナーは API の v3 を使用し、一般公開されています。 v2 の API が使用されているキー フレーズ抽出のコンテナーは、プレビュー段階です。
"キー フレーズ抽出" コンテナーを実行するには、次の docker run コマンドを実行します。 次のプレースホルダーを実際の値に置き換えてください。
| プレースホルダー | 値 | 形式または例 |
|---|---|---|
| {API_KEY} | キー フレーズ抽出リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| {ENDPOINT_URI} | Key Phrase Extraction API にアクセスするためのエンドポイント。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
docker run --rm -it -p 5000:5000 --memory 4g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/textanalytics/keyphrase \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}
このコマンドは、次の操作を行います。
- コンテナー イメージからキー フレーズ抽出コンテナーを実行します
- 1 つの CPU コアと 4 ギガバイト (GB) のメモリを割り当てます
- TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てます
- コンテナーの終了後にそれを自動的に削除します。 ホスト コンピューター上のコンテナー イメージは引き続き利用できます。
同じホスト上で複数のコンテナーを実行する
公開されているポートを使って複数のコンテナーを実行する予定の場合、必ず各コンテナーを別の公開されているポートで実行してください。 たとえば、最初のコンテナーをポート 5000 上で、2 番目のコンテナーを 5001 上で実行します。
このコンテナーと、別の Azure AI サービス コンテナーを HOST 上で同時に実行することができます。 同じ Azure AI サービス コンテナーの複数のコンテナーを実行することもできます。
コンテナーの予測エンドポイントに対するクエリの実行
コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。
コンテナー API には、ホストの http://localhost:5000 を使用します。
コンテナーが実行されていることを検証する
コンテナーが実行されていることを検証する方法は複数あります。 問題になっているコンテナーの "外部 IP" アドレスと公開ポートを特定し、任意の Web ブラウザーを開きます。 次の各種の要求 URL を使用して、コンテナーが実行中であることを確認します。 ここに示す要求例の URL は http://localhost:5000 ですが、実際のコンテナーは異なる可能性があります。 使用するコンテナーの外部 IP アドレスと公開ポートを基にしてください。
| 要求 URL | 目的 |
|---|---|
http://localhost:5000/ |
コンテナーには、ホーム ページが用意されています。 |
http://localhost:5000/ready |
GET で要求することで、この URL により、コンテナーがモデルに対するクエリを受け取る準備ができていることを確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/status |
これも GET で要求することで、この URL により、コンテナーを起動するために使用された API キーが有効であるかどうかを、エンドポイント クエリを発生させずに確認できます。 この要求は Kubernetes の liveness probe と readiness probe に対して使用できます。 |
http://localhost:5000/swagger |
コンテナーには、エンドポイントの完全なドキュメント一式と、 [Try it out](試してみる) の機能が用意されています。 この機能を使用すると、コードを一切記述することなく、お客様の設定を Web ベースの HTML フォームに入力したりクエリを実行したりできます。 クエリから戻った後、HTTP ヘッダーと HTTP 本文の必要な形式を示すサンプル CURL コマンドが得られます。 |
インターネットから切断されたコンテナーを実行する
インターネットから切断されたこのコンテナーを使用するには、まずアプリケーションに入力し、コミットメント プランを購入してアクセスを要求する必要があります。 詳細については、「切断された環境での Docker コンテナーの使用」を参照してください。
インターネットから切断されたコンテナーの実行が承認されている場合は、次の例に使用する docker run コマンドの形式と、プレースホルダーの値を示しています。 これらのプレースホルダーの値は、実際の値に置き換えます。
docker run コマンドで DownloadLicense=True パラメーターを使用して、インターネットに接続されていないときに Docker コンテナーを実行できるようにするライセンス ファイルをダウンロードします。 有効期限も含まれており、それを過ぎると、そのライセンス ファイルを使用してコンテナーを実行できなくなります。 ライセンス ファイルは、お客様が承認されている対象の適切なコンテナーでのみ使用できます。 たとえば、音声テキスト変換コンテナーのライセンス ファイルを Document Intelligence コンテナーで使用することはできません。
| プレースホルダー | 値 | 形式または例 |
|---|---|---|
{IMAGE} |
使用するコンテナー イメージ。 | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{LICENSE_MOUNT} |
ライセンスがダウンロードされ、マウントされるパス。 | /host/license:/path/to/license/directory |
{ENDPOINT_URI} |
サービス要求を認証するためのエンドポイント。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{API_KEY} |
自分の Text Analytics リソースのキー。 それは、Azure portal で、お使いのリソースの [キーとエンドポイント] ページで見つけることができます。 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
{CONTAINER_LICENSE_DIRECTORY} |
コンテナーのローカル ファイル システム上のライセンス フォルダーの場所。 | /path/to/license/directory |
docker run --rm -it -p 5000:5000 \
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
ライセンス ファイルがダウンロードされたら、切断された環境でコンテナーを実行できます。 次の例では、使用する docker run コマンドの形式と、プレースホルダーの値を示します。 これらのプレースホルダーの値は、実際の値に置き換えます。
コンテナーを実行する場所では必ず、ライセンス ファイルをコンテナーにマウントする必要があり、コンテナーのローカル ファイルシステム上のライセンス フォルダーの場所を Mounts:License= で指定する必要があります。 課金用の使用状況レコードを書き込むことができるように、出力マウントも指定する必要があります。
| プレースホルダー | 値 | 形式または例 |
|---|---|---|
{IMAGE} |
使用するコンテナー イメージ。 | mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice |
{MEMORY_SIZE} |
コンテナーに割り当てるメモリの適切なサイズ。 | 4g |
{NUMBER_CPUS} |
コンテナーに割り当てる CPU の適切な数。 | 4 |
{LICENSE_MOUNT} |
ライセンスが配置され、マウントされるパス。 | /host/license:/path/to/license/directory |
{OUTPUT_PATH} |
使用状況レコードを記録するための出力パス。 | /host/output:/path/to/output/directory |
{CONTAINER_LICENSE_DIRECTORY} |
コンテナーのローカル ファイル システム上のライセンス フォルダーの場所。 | /path/to/license/directory |
{CONTAINER_OUTPUT_DIRECTORY} |
コンテナーのローカル ファイル システム上の出力フォルダーの場所。 | /path/to/output/directory |
docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \
-v {LICENSE_MOUNT} \
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}
コンテナーの停止
コンテナーをシャットダウンするには、コンテナーが実行されているコマンドライン環境で、Ctrl + C キーを押します。
トラブルシューティング
出力マウントとログを有効にした状態でコンテナーを実行すると、コンテナーによってログ ファイルが生成されます。これらはコンテナーの起動時または実行時に発生した問題のトラブルシューティングに役立ちます。
ヒント
トラブルシューティング情報とガイダンスの詳細については、Azure AI コンテナーについてよくあるご質問 (FAQ) に関するページを参照してください。
請求
キー フレーズ抽出コンテナーにより、Azure アカウントの "キー フレーズ抽出" リソースを使って、課金情報が Azure に送信されます。
コンテナーへのクエリは、 ApiKeyパラメーターに使用される Azure リソースの価格レベルで課金 されます。
Azure AI サービス コンテナーは、計測または課金エンドポイントに接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。 Azure AI サービス コンテナーによって、お客様のデータ (解析対象の画像やテキストなど) が Microsoft に送信されることはありません。
Azure に接続する
コンテナーには、実行する課金引数の値が必要です。 これらの値により、コンテナーは課金エンドポイントに接続することができます。 コンテナーは、約 10 から 15 分ごとに使用状況を報告します。 許可された時間枠内でコンテナーが Azure に接続しなかった場合、コンテナーは引き続き実行されますが、課金エンドポイントが復元されるまでクエリには対応しません。 接続は、10 ～15 分の同じ時間間隔で、10 回試行されます。 10 回以内に課金エンドポイントに接続できなかった場合、コンテナーによる要求の処理は停止されます。 課金のために Microsoft に送信される情報の例については、Azure AI サービス コンテナーについてよく寄せられる質問を参照してください。
課金引数
docker run コマンドは、次の 3 つのオプションのすべてに有効な値が指定された場合にコンテナーを起動します。
| オプション | 説明 |
|---|---|
ApiKey |
課金情報を追跡するために使用される Azure AI サービス リソースの API キー。 このオプションの値には、 Billing に指定されたプロビジョニング済みのリソースの API キーが設定されている必要があります。 |
Billing |
課金情報を追跡するために使用される Azure AI サービス リソースのエンドポイント。 このオプションの値には、プロビジョニング済みの Azure リソースのエンドポイント URI が設定されている必要があります。 |
Eula |
お客様がコンテナーのライセンスに同意したことを示します。 このオプションの値は accept に設定する必要があります。 |
\
まとめ
この記事では、キー フレーズ抽出コンテナーの概念とそのダウンロード、インストール、実行のワークフローについて説明しました。 要約すると:
- キー フレーズ抽出により、Docker 用の Linux コンテナーが提供されます。
- コンテナー イメージは Microsoft Container Registry (MCR) からダウンロードされます。
- コンテナー イメージを Docker で実行します。
- REST API または SDK を使って、コンテナーのホスト URI を指定することにより、キー フレーズ抽出コンテナーの操作を呼び出すことができます。
- コンテナーをインスタンス化するときは、課金情報を指定する必要があります。
重要
Azure AI コンテナーは、計測のために Azure に接続していないと、実行のライセンスが許可されません。 お客様は、コンテナーが常に計測サービスに課金情報を伝えられるようにする必要があります。 お客様のデータ (解析対象のテキストなど) が Azure AI コンテナーによって Microsoft に送信されることはありません。
次のステップ
- 構成設定については、コンテナーの構成に関するページを参照してください。