LUIS 用の Docker コンテナーをインストールして実行する

コンテナーを使用すると、独自の環境で LUIS を使用できます。 コンテナーは、特定のセキュリティ要件とデータ ガバナンス要件に適しています。 この記事では、LUIS コンテナーをダウンロード、インストール、実行する方法について説明します。

Language Understanding (LUIS) コンテナーは、トレーニング済みまたは発行済みの Language Understanding モデルを読み込みます。 LUIS アプリのとして、Docker コンテナーは、コンテナーの API エンドポイントからクエリ予測にアクセスできます。 コンテナーからクエリ ログを収集し、Language Understanding アプリにアップロードし直して、アプリの予測精度を向上させることができます。

次のビデオでは、このコンテナーの使用方法を示します。

Azure AI サービスContainer demonstration for Azure AI servicesContainer demonstration for Azure AI servicesのコンテナーのデモンストレーション

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

前提条件

LUIS コンテナーを実行するには、次の前提条件に注意してください。

• ホスト コンピューターに Docker がインストールされていること。 コンテナーが Azure に接続して課金データを送信できるように、Docker を構成する必要があります。
  • Windows では、Linux コンテナーをサポートするように Docker を構成することも必要です。
  • Docker の概念に関する基本的な知識が必要です。
• 無料 (F0) または Standard (S) 価格レベルを持つ LUIS リソース。
• 関連付けられたアプリ ID を持つコンテナーへのマウントされた入力としてパッケージ化された、トレーニング済みまたは発行済みのアプリ。 パッケージ化されたファイルは、LUIS ポータルまたはオーサリング API から取得できます。 オーサリング APIから LUIS パッケージ アプリを取得する場合は、オーサリング キーも必要です。

必須パラメーターの収集

すべての Azure AI コンテナーに対して 3 つの主要なパラメーターが必須です。 Microsoft ソフトウェア ライセンス条項の値は accept でなければなりません。 エンドポイント URI と API キーも必要です。

エンドポイント URI

{ENDPOINT_URI} の値は、Azure portal の対応する Azure AI サービス リソースの [概要] ページで入手できます。 [概要] ページに移動し、エンドポイントの上にマウス ポインターを合わせると、[クリップボードにコピー] アイコンが表示されます。 必要に応じて、エンドポイントをコピーして使用します。

キー

{API_KEY} の値はコンテナーを起動するために使用され、Azure portal で、対応する Azure AI サービス リソースの [キー] ページで入手できます。 [キー] ページに移動し、[クリップボードにコピー] アイコンを選択します。

アプリ ID {APP_ID}

この ID は、アプリの選択に使用されます。 LUIS ポータルでアプリ ID を検索するには、アプリの画面上部にある [管理]、[設定] の順にクリックします。

オーサリング キー {AUTHORING_KEY}

このキーは、クラウド内の LUIS サービスからパッケージ 化されたアプリを取得し、クエリ ログをクラウドにアップロードするために使用されます。 この記事で後述する REST API を使用してアプリをエクスポート場合は、オーサリング キーが必要になります。

作成キーは、LUIS ポータル から取得できます。アプリの画面上部にある [管理] をクリックし、次に [Azure リソース ] をクリックします。

パッケージ ファイルの API の作成

パッケージ アプリの API の作成:

• 発行済みのパッケージ API
• 公開されていないトレーニング専用パッケージのAPI

ホスト コンピューター

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

• Azure Kubernetes Service。
• Azure Container Instances。
• Azure Stack にデプロイされた Kubernetes クラスター。 詳しくは、「Kubernetes を Azure Stack にデプロイする」をご覧ください。

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

次の表に、コンテナー ホストの最小値と推奨値を示します。 要件は、トラフィック量によって異なる場合があります。

• 各コアは少なくとも 2.6 ギガヘルツ (GHz) 以上にする必要があります。
• TPS - 1 秒あたりのトランザクション数

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

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

LUIS コンテナー イメージは、mcr.microsoft.com コンテナー レジストリ シンジケートにあります。 azure-cognitive-services/language リポジトリ内にあり、luis という名前が付いています。 完全修飾コンテナー イメージ名は mcr.microsoft.com/azure-cognitive-services/language/luis です。

最新バージョンのコンテナーを使用するには、latest タグを使用できます。 また、MCR でタグの完全な一覧を確認することもできます。

docker pull コマンドを使用して、mcr.microsoft.com/azure-cognitive-services/language/luis リポジトリからコンテナー イメージをダウンロードします。

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

上記のコマンドで使用した latest など、使用可能なタグの詳細については、Docker Hub での LUIS 参照してください。

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

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

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

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

Language Understanding (LUIS) コンテナーProcess for using Language Understanding (LUIS) containerを使用するためのプロセス

1. LUIS ポータルまたは LUIS API からコンテナーのパッケージ をエクスポートします。
2. ホスト コンピューター上の必要な input ディレクトリにパッケージ ファイルを移動します。 LUIS パッケージ ファイルの名前変更、変更、上書き、または展開は行わないでください。
3. 必要な "入力マウント" と請求設定でコンテナーを実行します。 コマンドの他のdocker runもご覧いただけます。
4. コンテナーの予測エンドポイントのクエリを実行します。
5. コンテナーの操作が完了したら、LUIS ポータルの出力マウントから エンドポイント ログをインポート、コンテナー 停止。
6. LUIS ポータルの アクティブ ラーニング とレビュー エンドポイント発話 ページを使ってアプリを改善します。

コンテナーで実行されているアプリを変更することはできません。 コンテナー内のアプリを変更するには、LUIS ポータルを使用して LUIS サービス内のアプリを変更するか、LUIS オーサリング APIを使用する必要があります。 次に、トレーニングや発行を行い、新しいパッケージをダウンロードしてコンテナーをもう一度実行します。

コンテナー内の LUIS アプリを LUIS サービスにエクスポートし直すことはできません。 アップロードできるのはクエリ ログだけです。

LUIS からパッケージ アプリをエクスポートする

LUIS コンテナーには、ユーザー発話の予測クエリに応答するために、トレーニング済みまたは公開済みの LUIS アプリが必要です。 LUIS アプリを取得するには、トレーニング済みまたは発行済みのパッケージ API を使用します。

既定の場所は、input コマンドを実行する場所に関連する docker run サブディレクトリです。

docker コンテナーを実行するときに、パッケージ ファイルをディレクトリに配置し、このディレクトリを入力マウントとして参照します。

パッケージの種類

入力マウント ディレクトリには、アプリの Production、Staging、および Versioned モデルを同時に含めることができます。 すべてのパッケージがマウントされます。

パッケージ化の前提条件

LUIS アプリケーションをパッケージ化する前に、次のものが必要です。

LUIS ポータルからアプリ パッケージをエクスポートする

LUIS Azure portal は、トレーニング済みまたは発行済みのアプリのパッケージをエクスポートする機能を提供します。

LUIS ポータルから発行済みアプリのパッケージをエクスポートする

発行されたアプリのパッケージは、[マイ アプリ] リスト ページ から入手できます。

1. アジュールポータル で LUISにサインインします。
2. 一覧のアプリ名の左側にあるチェック ボックスをオンにします。
3. 一覧の上にあるコンテキストツールバーから エクスポート 項目を選択します。
4. [コンテナー用にエクスポート (GZIP)] を選択します。
5. 運用スロット またはステージング スロット の環境を選択します。
6. パッケージはブラウザーからダウンロードされます。

LUIS ポータルからバージョン管理されたアプリのパッケージをエクスポートする

バージョン管理されたアプリのパッケージは、バージョン リスト ページから入手できます。

1. アジュールポータル で LUISにサインインします。
2. 一覧からアプリを選択します。
3. アプリのナビゲーションバーで を管理 を選択します。
4. 左側 の ウィンドウで [バージョン] を選択します。
5. 一覧のバージョン名の左側にあるチェック ボックスをオンにします。
6. 一覧の上にあるコンテキストツールバーから エクスポート 項目を選択します。
7. [コンテナー用にエクスポート (GZIP)] を選択します。
8. パッケージはブラウザーからダウンロードされます。

発行済みアプリのパッケージを API からエクスポートする

お客様が既に発行した LUIS アプリをパッケージ化するには、以下の REST API メソッドを使用します。 HTTP 仕様の下の表を使用して、API 呼び出しのプレースホルダーに対して独自の適切な値を置き換えます。

GET /luis/api/v2.0/package/{APP_ID}/slot/{SLOT_NAME}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

発行されたパッケージをダウンロードするには、のAPI ドキュメントを参照してください。 正常にダウンロードされた場合、応答は LUIS パッケージ ファイルです。 コンテナーの入力マウントに指定されたストレージの場所にファイルを保存します。

バージョン管理されたアプリのパッケージを API からエクスポートする

お客様が既にトレーニングした LUIS アプリケーションをパッケージ化するには、以下の REST API メソッドを使用します。 HTTP 仕様の下の表を使用して、API 呼び出しのプレースホルダーに対して独自の適切な値を置き換えます。

GET /luis/api/v2.0/package/{APP_ID}/versions/{APP_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

バージョン管理されたパッケージをダウンロードするには、こちらのにあるAPIドキュメントを参照してください。 正常にダウンロードされた場合、応答は LUIS パッケージ ファイルです。 コンテナーの入力マウントに指定されたストレージの場所にファイルを保存します。

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

コンテナーを実行するには、docker run コマンドを使用します。 と {ENDPOINT_URI} の値を取得する方法の詳細については、「{API_KEY}」を参照してください。

コマンドのdocker runを利用できます。

docker run --rm -it -p 5000:5000 ^
--memory 4g ^
--cpus 2 ^
--mount type=bind,src=c:\input,target=/input ^
--mount type=bind,src=c:\output\,target=/output ^
mcr.microsoft.com/azure-cognitive-services/language/luis ^
Eula=accept ^
Billing={ENDPOINT_URI} ^
ApiKey={API_KEY}

• この例では、windows でのアクセス許可の競合を回避するために、C: ドライブからディレクトリを使用します。 特定のディレクトリを入力ディレクトリとして使う必要がある場合は、Docker サービスのアクセス許可の付与が必要なことがあります。
• Docker コンテナーに慣れていない限り、引数の順序を変更しないでください。
• 別のオペレーティング システムを使用している場合は、正しいコンソール/ターミナル、マウント用のフォルダー構文、ご利用のシステムの行連結文字を使用します。 これらの例では、行連結文字 ^ を使用した Windows コンソールを想定しています。 コンテナーは Linux オペレーティング システムであるため、ターゲット マウントでは Linux スタイルのフォルダー構文を使用します。

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

• LUIS コンテナー イメージからコンテナーを実行する
• コンテナー ホストにある C:\inputの入力マウントから LUIS アプリを読み込みます
• 2 つの CPU コアと 4 ギガバイト (GB) のメモリを割り当てます
• TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てます
• コンテナー と LUIS のログを、コンテナー ホスト上 C:\outputの出力マウントに保存します
• コンテナーの終了後にそれを自動的に削除します。 ホスト コンピューター上のコンテナー イメージは引き続き利用できます。

コマンドの他のdocker runもご覧いただけます。

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

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

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

コンテナーでサポートされているエンドポイント API

コンテナーでは、V2 バージョンと V3 バージョンの API の両方を使用できます。

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

コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。 発行済み (ステージングまたは運用) アプリのエンドポイントには、バージョン付きのアプリのエンドポイントとは "異なる" ルートがあります。

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

クエリ パラメーターは、クエリ応答で返される方法と内容を構成します。

LUIS アプリのクエリを実行する

発行済みアプリのコンテナーに対してクエリを実行するための CURL コマンドの例を次に示します。

curl -G \
-d verbose=false \
-d log=true \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/production/predict"

curl -G \
-d verbose=false \
-d log=false \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/versions/{APP_VERSION}/predict"

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}?q=turn%20on%20the%20lights&staging=false&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}/versions/{APP_VERSION}?q=turn%20on%20the%20lights&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

アクティブ ラーニング用のエンドポイント ログをインポートする

LUIS コンテナーに出力マウントが指定されている場合、アプリ クエリ ログ ファイルは出力ディレクトリに保存されます。{INSTANCE_ID} はコンテナー ID です。 アプリ クエリ ログには、LUIS コンテナーに送信された各予測クエリのクエリ、応答、タイムスタンプが含まれています。

次の場所は、コンテナーのログ ファイルの入れ子になったディレクトリ構造を示しています。

/output/luis/{INSTANCE_ID}/

LUIS ポータルからアプリを選択し、エンドポイント ログ インポートを選択してこれらのログをアップロードします。

用にコンテナーのログ ファイルをインポートする

ログがアップロードされたら、LUIS ポータルでエンドポイント発話を確認します。

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

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

インターネットから切断されたコンテナーを実行する

インターネットから切断されたこのコンテナーを使用するには、まずアプリケーションに入力し、コミットメント プランを購入してアクセスを要求する必要があります。 詳細については、「切断された環境での Docker コンテナーの使用」を参照してください。

インターネットから切断されたコンテナーの実行が承認されている場合、次の例は使用する docker run コマンドの形式とプレースホルダーの値を示しています。 自分の値でこれらのプレースホルダーの値を置き換えてください。

DownloadLicense=True コマンドで docker run パラメーターを使用して、インターネットに接続されていないときに Docker コンテナーを実行できるようにするライセンス ファイルをダウンロードします。 有効期限も含まれており、それを過ぎると、そのライセンス ファイルを使用してコンテナーを実行できなくなります。 ライセンス ファイルは、お客様が承認されている対象の適切なコンテナーでのみ使用できます。 たとえば、音声テキスト変換コンテナーのライセンス ファイルを Document Intelligence コンテナーで使用することはできません。

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= で指定する必要があります。 課金用の使用状況レコードを書き込むことができるように、出力マウントも指定する必要があります。

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 サービス コンテナーの実行で問題が発生している場合は、Microsoft 診断コンテナーを使用してみることができます。 このコンテナーを使用して、Azure AI コンテナーが想定どおりに機能しなくなる可能性がある、展開環境での一般的なエラーを診断します。

コンテナーを取得するには、次の docker pull コマンドを使用します。

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

その後で、コンテナーを実行します。 {ENDPOINT_URI} をエンドポイントに置き換え、{API_KEY} をリソースへのキーに置き換えます。

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

コンテナーは、課金エンドポイントへのネットワーク接続をテストします。

請求書

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

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

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

Azure に接続する

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

請求引数

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

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

概要

この記事では、Language Understanding (LUIS) コンテナーをダウンロード、インストール、実行するための概念とワークフローについて説明しました。 まとめ:

• Language Understanding (LUIS) には、発話のエンドポイント クエリ予測を提供する Docker 用の Linux コンテナーが 1 つ用意されています。
• コンテナー イメージは Microsoft Container Registry (MCR) からダウンロードされます。
• コンテナー イメージを Docker で実行します。
• REST API を使用して、コンテナーのホスト URI を指定することで、コンテナー エンドポイントに対してクエリを実行できます。
• コンテナーをインスタンス化するときは、課金情報を指定する必要があります。

次のステップ

• 構成設定について、コンテナーの構成を確認します。
• 既知の機能の制限については、LUIS コンテナーの制限を参照してください。
• トラブルシューティングに関するページを参照して、LUIS 機能に関連する問題を解決する。
• より多くの Azure AI コンテナーを使用する