LUIS docker コンテナーのインストールと実行Install and run LUIS docker containers

Language Understanding (LUIS) コンテナーでは、お客様のトレーニング済みまたは発行済みの Language Understanding モデル (LUIS アプリ とも呼ばれます) を Docker コンテナーに読み込みこんで、コンテナーの API エンドポイントからクエリ予測を利用することができます。The Language Understanding (LUIS) container loads your trained or published Language Understanding model, also know as a LUIS app, into a docker container and provides access to the query predictions from the container's API endpoints. コンテナーからクエリ ログを収集し、それらを Language Understanding アプリに再度アップロードすることで、アプリの予測精度を高めることができます。You can collect query logs from the container and upload these back to the Language Understanding app to improve the app's prediction accuracy.

次のビデオでは、このコンテナーの使用に関するデモが行われています。The following video demonstrates using this container.

Cognitive Services のコンテナーのデモContainer demonstration for Cognitive Services

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

前提条件Prerequisites

LUIS コンテナーを実行するには、以下が必要です。In order to run the LUIS container, you must have the following:

必須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.
Azure Cognitive Services リソースおよび LUIS パッケージ アプリ ファイルAzure Cognitive Services resource and LUIS packaged app file コンテナーを使用するためには、以下が必要です。In order to use the container, you must have:

* Cognitive Services Azure リソースおよび関連する課金キー (課金エンドポイント URI)。* A Cognitive Services Azure resource and the associated billing key the billing endpoint URI. どちらの値も、対象リソースの概要ページとキー ページで使用でき、コンテナーを開始するために必要です。Both values are available on the Overview and Keys pages for the resource and are required to start the container. luis/v2.0 ルーティングをエンドポイント URI に追加する必要があります。次の BILLING_ENDPOINT_URI の例を参照してください。You need to add the luis/v2.0 routing to the endpoint URI as shown in the following BILLING_ENDPOINT_URI example.
* コンテナーへのマウント済み入力としてパッケージ化されたトレーニング済みまたは発行済みのアプリと、その関連アプリ ID。* A trained or published app packaged as a mounted input to the container with its associated App ID. パッケージ ファイルは、LUIS ポータルまたはオーサリング API から取得できます。You can get the packaged file from the LUIS portal or the Authoring APIs. オーサリング API から LUIS パッケージ アプリを入手している場合は、"オーサリング キー" も必要になります。If you are getting LUIS packaged app from the authoring APIs, you will also need your Authoring Key.

これらの要件は、以下の変数にコマンドライン引数を渡すために使用されます。These requirements are used to pass command-line arguments to the following variables:

{AUTHORING_KEY} : このキーは、パッケージ化されたアプリをクラウドの LUIS サービスから取得したり、クエリ ログをクラウドにアップロードしたりするために使用されます。{AUTHORING_KEY}: This key is used to get the packaged app from the LUIS service in the cloud and upload the query logs back to the cloud. 形式は xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx です。The format is xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

{APPLICATION_ID} : この ID は、アプリを選択するために使用されます。{APPLICATION_ID}: This ID is used to select the App. 形式は xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx です。The format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

{ENDPOINT_KEY} : このキーは、コンテナーを起動するために使用されます。{ENDPOINT_KEY}: This key is used to start the container. エンドポイント キーは 2 か所で確認できます。You can find the endpoint key in two places. 1 つ目は Azure portal です (Cognitive Services リソースのキーの一覧内)。The first is the Azure portal within the Cognitive Services resource's keys list. また、LUIS ポータルの [Keys and endpoints](キーとエンドポイント) の設定ページでもエンドポイント キーを確認できます。The endpoint key is also available in the LUIS portal on the Keys and Endpoint settings page. スターター キーは使用しないでください。Do not use the starter key.

{BILLING_ENDPOINT} : (例: https://westus.api.cognitive.microsoft.com/luis/v2.0)。{BILLING_ENDPOINT}: An example is: https://westus.api.cognitive.microsoft.com/luis/v2.0.

オーサリング キーとエンドポイント キーには、異なる目的があります。The authoring key and endpoint key have different purposes. これらは区別して使用してください。Do not use them interchangeably.

パッケージ ファイルのオーサリング APIAuthoring APIs for package file

パッケージ ファイルのオーサリング API は、次のとおりです。Authoring APIs for packaged apps:

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

このコンテナーでは、以下の設定に関して最小値と推奨値がサポートされます。This container supports minimum and recommended values for the settings:

コンテナーContainer 最小値Minimum 推奨Recommended TPSTPS
(最大、最小)(Minimum, Maximum)
LUISLUIS 1 コア、2 GB メモリ1 core, 2 GB memory 1 コア、4 GB メモリ1 core, 4 GB memory 20、4020,40
  • 各コアは少なくとも 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

docker pull コマンドを使用して mcr.microsoft.com/azure-cognitive-services/luis リポジトリからコンテナー イメージをダウンロードします。Use the docker pull command to download a container image from the mcr.microsoft.com/azure-cognitive-services/luis repository:

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

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

上記のコマンドで使用されている latest など、利用可能なタグの詳細な説明については、Docker Hub の LUIS に関するページを参照してください。For a full description of available tags, such as latest used in the preceding command, see LUIS on Docker Hub.

ヒント

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>

コンテナーを使用する方法How to use the container

コンテナーをホスト コンピューター上に用意できたら、次の手順を使用してコンテナーを操作します。Once the container is on the host computer, use the following process to work with the container.

Language Understanding (LUIS) コンテナーを使用する手順

  1. LUIS ポータルまたは LUIS API からコンテナーのパッケージをエクスポートします。Export package for container from LUIS portal or LUIS APIs.
  2. ホスト コンピューター上の必要な input ディレクトリにパッケージ ファイルを移動します。Move package file into the required input directory on the host computer. LUIS パッケージ ファイルの名前変更、改変、上書き、または展開は行わないでください。Do not rename, alter, overwrite, or decompress LUIS package file.
  3. 必要な "入力マウント" と課金設定でコンテナーを実行します。Run the container, with the required input mount and billing settings. docker run コマンドの他のもご覧いただけます。More examples of the docker run command are available.
  4. コンテナーの予測エンドポイントに対してクエリを実行しますQuerying the container's prediction endpoint.
  5. コンテナーの操作が完了したら、LUIS ポータルで出力マウントからエンドポイント ログをインポートし、コンテナーを停止します。When you are done with the container, import the endpoint logs from the output mount in the LUIS portal and stop the container.
  6. LUIS ポータルの [Review endpoint utterances](エンドポイントの発話の確認) ページでアクティブ ラーニングを使用して、アプリを強化します。Use LUIS portal's active learning on the Review endpoint utterances page to improve the app.

コンテナーで実行中のアプリに変更を加えることはできません。The app running in the container can't be altered. コンテナー内のアプリに変更を加えるには、LUIS ポータルを使用して LUIS サービスでアプリに変更を加えるか、または LUIS のオーサリング API を使用する必要があります。In order the change the app in the container, you need to change the app in the LUIS service using the LUIS portal or use the LUIS authoring APIs. そのうえで、アプリをトレーニングまたは発行し、新しいパッケージをダウンロードして、もう一度コンテナーを実行します。Then train and/or publish, then download a new package and run the container again.

コンテナー内の LUIS アプリを再度 LUIS サービスにエクスポートすることはできません。The LUIS app inside the container can't be exported back to the LUIS service. アップロードできるのは、クエリ ログだけです。Only the query logs can be uploaded.

パッケージ化されたアプリの LUIS からのエクスポートExport packaged app from LUIS

ユーザーの発話の予測クエリに回答するには、トレーニング済みまたは発行済みの LUIS アプリが LUIS コンテナーに必要です。The LUIS container requires a trained or published LUIS app to answer prediction queries of user utterances. LUIS アプリを取得するためには、トレーニング済みまたは発行済みのパッケージ API を使用します。In order to get the LUIS app, use either the trained or published package API.

その既定の場所は、お客様が docker run コマンドを実行する場所を起点とした input サブディレクトリです。The default location is the input subdirectory in relation to where you run the docker run command.

パッケージ ファイルを任意のディレクトリに配置してください。Docker コンテナーを実行する際には、そのディレクトリを入力マウントとして参照します。Place the package file in a directory and reference this directory as the input mount when you run the docker container.

パッケージの種類Package types

入力マウント ディレクトリには、運用ステージングトレーニング済みの各バージョンのアプリを同時に格納することができます。The input mount directory can contain the Production, Staging, and Trained versions of the app simultaneously. すべてのパッケージがマウントされます。All the packages are mounted.

パッケージの種類Package Type クエリ エンドポイント APIQuery Endpoint API クエリの利用可能性Query availability パッケージのファイル名の形式Package filename format
トレーニング済みTrained Get、PostGet, Post コンテナーのみContainer only {APPLICATION_ID}_v{APPLICATION_VERSION}.gz
ステージングStaging Get、PostGet, Post Azure とコンテナーAzure and container {APPLICATION_ID}_STAGING.gz
ProductionProduction Get、PostGet, Post Azure とコンテナーAzure and container {APPLICATION_ID}_PRODUCTION.gz

重要

LUIS パッケージ ファイルの名前変更、改変、上書き、または展開は行わないでください。Do not rename, alter, overwrite, or decompress the LUIS package files.

パッケージの前提条件Packaging prerequisites

LUIS アプリケーションをパッケージ化する前に、以下を用意する必要があります。Before packaging a LUIS application, you must have the following:

パッケージ化の要件Packaging Requirements 詳細Details
Azure Cognitive Services リソース インスタンスAzure Cognitive Services resource instance サポートされているリージョンは次のとおりですSupported regions include

米国西部 (westus)West US (westus)
西ヨーロッパ (westeurope)West Europe (westeurope)
オーストラリア東部 (australiaeast)Australia East (australiaeast)
トレーニング済みまたは発行済みの LUIS アプリTrained or published LUIS app サポートされていない依存関係を含んでいないこと。With no unsupported dependencies.
ホスト コンピューターのファイル システムへのアクセスAccess to the host computer's file system ホスト コンピューターで入力マウントが許可されている必要があります。The host computer must allow an input mount.

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

LUIS ポータルには、トレーニング済みアプリまたは発行済みアプリのパッケージをエクスポートする機能が備わっています。The LUIS portal provides the ability to export the trained or published app's package.

LUIS ポータルから発行済みアプリのパッケージをエクスポートするExport published app's package from LUIS portal

発行済みアプリのパッケージは、 [マイ アプリ] 一覧ページから入手できます。The published app's package is available from the My Apps list page.

  1. LUIS ポータルにサインオンします。Sign on to the LUIS portal.
  2. 一覧でアプリ名の左側にあるチェック ボックスをオンにします。Select the checkbox to the left of the app name in the list.
  3. 一覧の上にあるコンテキスト ツール バーから [エクスポート] 項目を選択します。Select the Export item from the contextual toolbar above the list.
  4. [Export for container (GZIP)](コンテナー用にエクスポート (GZIP)) を選択します。Select Export for container (GZIP).
  5. [運用スロット] または [ステージング スロット] の環境を選択します。Select the environment of Production slot or Staging slot.
  6. ブラウザーからパッケージがダウンロードされます。The package is downloaded from the browser.

アプリ ページの [エクスポート] メニューからコンテナー用の発行済みパッケージをエクスポートする

LUIS ポータルからトレーニング済みアプリのパッケージをエクスポートするExport trained app's package from LUIS portal

トレーニング済みアプリのパッケージは、 [バージョン] 一覧ページから入手できます。The trained app's package is available from the Versions list page.

  1. LUIS ポータルにサインオンします。Sign on to the LUIS portal.
  2. 一覧でアプリを選択します。Select the app in the list.
  3. アプリのナビゲーション バーで [管理] を選択します。Select Manage in the app's navigation bar.
  4. 左側のナビゲーション バーで [バージョン] を選択します。Select Versions in the left navigation bar.
  5. 一覧でバージョン名の左側にあるチェック ボックスをオンにします。Select the checkbox to the left of the version name in the list.
  6. 一覧の上にあるコンテキスト ツール バーから [エクスポート] 項目を選択します。Select the Export item from the contextual toolbar above the list.
  7. [Export for container (GZIP)](コンテナー用にエクスポート (GZIP)) を選択します。Select Export for container (GZIP).
  8. ブラウザーからパッケージがダウンロードされます。The package is downloaded from the browser.

[バージョン] ページの [エクスポート] メニューからコンテナーのトレーニング済みパッケージをエクスポートする

API から発行済みアプリのパッケージをエクスポートするExport published app's package from API

お客様が既に発行した LUIS アプリをパッケージ化するには、以下の REST API メソッドを使用します。Use the following REST API method, to package a LUIS app that you've already published. API 呼び出しのプレースホルダーは、HTTP 仕様の下の表を使用して、お客様独自の適切な値に置き換えてください。Substituting your own appropriate values for the placeholders in the API call, using the table below the HTTP specification.

GET /luis/api/v2.0/package/{APPLICATION_ID}/slot/{APPLICATION_ENVIRONMENT}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}
プレースホルダーPlaceholder Value
{APPLICATION_ID}{APPLICATION_ID} 発行済み LUIS アプリのアプリケーション ID。The application ID of the published LUIS app.
{APPLICATION_ENVIRONMENT}{APPLICATION_ENVIRONMENT} 発行済み LUIS アプリの環境。The environment of the published LUIS app. 次のいずれかの値を使用します。Use one of the following values:
PRODUCTION
STAGING
{AUTHORING_KEY}{AUTHORING_KEY} 発行済み LUIS アプリに使用する LUIS アカウントのオーサリング キー。The authoring key of the LUIS account for the published LUIS app.
LUIS ポータルの [ユーザー設定] ページからオーサリング キーを取得できます。You can get your authoring key from the User Settings page on the LUIS portal.
{AZURE_REGION}{AZURE_REGION} 適切な Azure リージョン:The appropriate Azure region:

westus - 米国西部westus - West US
westeurope - 西ヨーロッパwesteurope - West Europe
australiaeast - オーストラリア東部australiaeast - Australia East

発行済みパッケージをダウンロードするには、次の CURL コマンドを使用します。プレースホルダーは、お客様独自の値に置き換えてください。Use the following CURL command to download the published package, substituting your own values:

curl -X GET \
https://{AZURE_REGION}.api.cognitive.microsoft.com/luis/api/v2.0/package/{APPLICATION_ID}/slot/{APPLICATION_ENVIRONMENT}/gzip  \
 -H "Ocp-Apim-Subscription-Key: {AUTHORING_KEY}" \
 -o {APPLICATION_ID}_{APPLICATION_ENVIRONMENT}.gz

成功した場合、LUIS パッケージ ファイルが返されます。If successful, the response is a LUIS package file. コンテナーの入力マウントに指定した保存場所にファイルを保存してください。Save the file in the storage location specified for the input mount of the container.

API からトレーニング済みアプリのパッケージをエクスポートするExport trained app's package from API

お客様が既にトレーニングした LUIS アプリケーションをパッケージ化するには、以下の REST API メソッドを使用します。Use the following REST API method, to package a LUIS application that you've already trained. API 呼び出しのプレースホルダーは、HTTP 仕様の下の表を使用して、お客様独自の適切な値に置き換えてください。Substituting your own appropriate values for the placeholders in the API call, using the table below the HTTP specification.

GET /luis/api/v2.0/package/{APPLICATION_ID}/versions/{APPLICATION_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}
プレースホルダーPlaceholder Value
{APPLICATION_ID}{APPLICATION_ID} トレーニング済み LUIS アプリケーションのアプリケーション ID。The application ID of the trained LUIS application.
{APPLICATION_VERSION}{APPLICATION_VERSION} トレーニング済み LUIS アプリケーションのアプリケーション バージョン。The application version of the trained LUIS application.
{AUTHORING_KEY}{AUTHORING_KEY} 発行済み LUIS アプリに使用する LUIS アカウントのオーサリング キー。The authoring key of the LUIS account for the published LUIS app.
LUIS ポータルの [ユーザー設定] ページからオーサリング キーを取得できます。You can get your authoring key from the User Settings page on the LUIS portal.
{AZURE_REGION}{AZURE_REGION} 適切な Azure リージョン:The appropriate Azure region:

westus - 米国西部westus - West US
westeurope - 西ヨーロッパwesteurope - West Europe
australiaeast - オーストラリア東部australiaeast - Australia East

トレーニング済みパッケージをダウンロードするには、次の CURL コマンドを使用します。Use the following CURL command to download the trained package:

curl -X GET \
https://{AZURE_REGION}.api.cognitive.microsoft.com/luis/api/v2.0/package/{APPLICATION_ID}/versions/{APPLICATION_VERSION}/gzip  \
 -H "Ocp-Apim-Subscription-Key: {AUTHORING_KEY}" \
 -o {APPLICATION_ID}_v{APPLICATION_VERSION}.gz

成功した場合、LUIS パッケージ ファイルが返されます。If successful, the response is a LUIS package file. コンテナーの入力マウントに指定した保存場所にファイルを保存してください。Save the file in the storage location specified for the input mount of the container.

docker run によるコンテナーの実行Run the container with docker run

コンテナーを実行するには、docker run コマンドを使用します。Use the docker run command to run the container. このコマンドには、次のパラメーターが使用されます。The command uses the following parameters:

プレースホルダーPlaceholder Value
{ENDPOINT_KEY}{ENDPOINT_KEY} このキーは、コンテナーを起動するために使用されます。This key is used to start the container. スターター キーは使用しないでください。Do not use the starter key.
{BILLING_ENDPOINT}{BILLING_ENDPOINT} 課金エンドポイントの値は、Azure portal の Cognitive Services の [概要] ページで確認できます。The billing endpoint value is available on the Azure portal's Cognitive Services Overview page. エンドポイント URI には、luis/v2.0 ルーティングを追加する必要があります (例: https://westus.api.cognitive.microsoft.com/luis/v2.0)。You need to add the luis/v2.0 routing to the endpoint URI as shown in the following example: https://westus.api.cognitive.microsoft.com/luis/v2.0.

次の例の docker run コマンドでは、これらのパラメーターをお客様独自の値に置き換えてください。Replace these parameters with your own values in the following example docker run command. Windows コンソールでコマンドを実行します。Run the command in the Windows console.

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/luis ^
Eula=accept ^
Billing={BILLING_ENDPOINT} ^
ApiKey={ENDPOINT_KEY}
  • この例では、Windows 上のアクセス許可の競合を防ぐために、c: ドライブのディレクトリを使用しています。This example uses the directory off the c: drive to avoid any permission conflicts on Windows. 特定のディレクトリを入力ディレクトリとして使用する必要がある場合は、Docker サービスのアクセス許可の付与が必要なことがあります。If you need to use a specific directory as the input directory, you may need to grant the docker service permission.
  • Docker コンテナーについて高度な知識がある場合を除き、引数の順序は変更しないでください。Do not change the order of the arguments unless you are very familiar with docker containers.
  • 別のオペレーティング システムを使用している場合は、正しいコンソール/ターミナル、マウント用のフォルダー構文、ご利用のシステムの行連結文字を使用します。If you are using a different operating system, use the correct console/terminal, folder syntax for mounts, and line continuation character for your system. これらの例では、行連結文字 ^ を使用した Windows コンソールを想定しています。These examples assume a Windows console with a line continuation character ^. コンテナーは Linux オペレーティング システムであるため、ターゲット マウントでは Linux スタイルのフォルダー構文を使用します。Because the container is a Linux operating system, the target mount uses a Linux-style folder syntax.

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

  • LUIS コンテナー イメージからコンテナーを実行しますRuns a container from the LUIS container image
  • コンテナー ホスト上の入力マウント (c:\input) から LUIS アプリを読み込みますLoads LUIS app from input mount at c:\input, located on container host
  • 2 つの CPU コアと 4 ギガバイト (GB) のメモリを割り当てますAllocates two CPU cores and 4 gigabytes (GB) of memory
  • TCP ポート 5000 を公開し、コンテナーに pseudo-TTY を割り当てますExposes TCP port 5000 and allocates a pseudo-TTY for the container
  • コンテナー ホスト上の出力マウント (c:\output) にコンテナーと LUIS のログを保存しますSaves container and LUIS logs to output mount at c:\output, located on container host
  • コンテナーの終了後にそれを自動的に削除します。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. ApiKey の値は、LUIS ポータルの [Keys and Endpoints](キーとエンドポイント) ページにある [キー] です。また、Azure Cognitive Services リソース キー ページで確認することもできます。The ApiKey value is the Key from the Keys and Endpoints page in the LUIS portal and is also available on the Azure Cognitive Services resource keys page.

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

コンテナーによってサポートされる エンドポイント APIEndpoint APIs supported by the container

コンテナーでは、API の V2 バージョンと V3 (プレビュー) バージョンの両方を利用できます。Both V2 and V3 (Preview) versions of the API are available with the container.

コンテナーの予測エンドポイントに対するクエリの実行Query the container's prediction endpoint

コンテナーには、REST ベースのクエリ予測エンドポイント API が用意されています。The container provides REST-based query prediction endpoint APIs. 発行済み (ステージングまたは運用) アプリのエンドポイントには、トレーニング済みアプリのエンドポイントとは "異なる" ルートがあります。Endpoints for published (staging or production) apps have a different route than endpoints for trained apps.

コンテナーの API のホストとしては https://localhost:5000 を使用します。Use the host, https://localhost:5000, for container APIs.

パッケージの種類Package type MethodMethod ルートRoute クエリ パラメーターQuery parameters
公開先Published GetPostGet, Post /luis/v2.0/apps/{appId}?/luis/v2.0/apps/{appId}? q={q}q={q}
&staging&staging
[&timezoneOffset][&timezoneOffset]
[&verbose][&verbose]
[&log][&log]
トレーニング済みTrained Get、PostGet, Post /luis/v2.0/apps/{appId}/versions/{versionId}?/luis/v2.0/apps/{appId}/versions/{versionId}? q={q}q={q}
[&timezoneOffset][&timezoneOffset]
[&verbose][&verbose]
[&log][&log]

クエリ パラメーターを使用すると、クエリの応答で何がどのように返されるかを構成できます。The query parameters configure how and what is returned in the query response:

Query parameter (クエリ パラメーター)Query parameter TypeType 目的Purpose
q stringstring ユーザーの発話。The user's utterance.
timezoneOffset numbernumber timezoneOffset を使用すると、事前構築済みのエンティティ datetimeV2 で使用されるタイムゾーンを変更できます。The timezoneOffset allows you to change the timezone used by the prebuilt entity datetimeV2.
verbose ブール値boolean true に設定すると、すべての意図とそのスコアが返されます。Returns all intents and their scores when set to true. 既定値は false で、この場合、最上位の意図だけが返されます。Default is false, which returns only the top intent.
staging ブール値boolean true に設定した場合、ステージング環境の結果からクエリが返されます。Returns query from staging environment results if set to true.
log ブール値boolean クエリをログします。これは後でアクティブ ラーニングに使用できます。Logs queries, which can be used later for active learning. 既定値は true です。Default is true.

発行済みアプリに対してクエリを実行するQuery published app

発行済みアプリのコンテナーに対してクエリを実行するためのサンプル CURL コマンド:An example CURL command for querying the container for a published app is:

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

ステージング環境に対してクエリを実行する場合は、staging というクエリ文字列パラメーターの値を true に変更してください。To make queries to the Staging environment, change the staging query string parameter value to true:

staging=true

トレーニング済みアプリに対してクエリを実行するQuery trained app

トレーニング済みアプリのコンテナーに対してクエリを実行するためのサンプル CURL コマンド:An example CURL command for querying the container for a trained app is:

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

バージョン名は最大 10 文字で、URL に使用できる文字だけを含みます。The version name has a maximum of 10 characters and contains only characters allowed in a URL.

アクティブ ラーニングに使用するエンドポイント ログのインポートImport the endpoint logs for active learning

LUIS コンテナーの出力マウントが指定された場合、アプリのクエリ ログ ファイルは出力ディレクトリ ({INSTANCE_ID} はコンテナーの ID) に保存されます。If an output mount is specified for the LUIS container, app query log files are saved in the output directory, where {INSTANCE_ID} is the container ID. アプリのクエリ ログには、LUIS コンテナーに送信された予測クエリごとに、クエリ、応答、タイムスタンプが記録されます。The app query log contains the query, response, and timestamps for each prediction query submitted to the LUIS container.

次の場所は、コンテナーのログ ファイルに使用される入れ子になったディレクトリ構造を示しています。The following location shows the nested directory structure for the container's log files.

/output/luis/{INSTANCE_ID}/

LUIS ポータルから、お客様のアプリを選択し、 [Import endpoint logs](エンドポイント ログのインポート) を選択して、それらのログをアップロードします。From the LUIS portal, select your app, then select Import endpoint logs to upload these logs.

アクティブ ラーニングに使用するコンテナーのログ ファイルをインポートする

ログがアップロードされたら、LUIS ポータルでエンドポイント発話を確認します。After the log is uploaded, review the endpoint utterances in the LUIS portal.

コンテナーが実行されていることを検証するValidate that a container is running

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

RequestRequest 目的Purpose
http://localhost:5000/ コンテナーには、ホーム ページが用意されています。The container provides a home page.
http://localhost:5000/status GET で要求され、エンドポイント クエリを発生させずにコンテナーが実行されていることを検証します。Requested with GET, to validate that the container is running 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 now 機能が用意されています。The container provides a full set of documentation for the endpoints and a Try it now 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, 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

LUIS コンテナーでは、お客様の Azure アカウントの Cognitive Services リソースを使用して課金情報が Azure に送信されます。The LUIS container sends 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 that's used for the <ApiKey>.

Azure Cognitive Services コンテナーは、計測のために課金エンドポイントに接続していないと、実行のライセンスが許可されません。Azure Cognitive Services containers aren't licensed to run without being connected to the billing endpoint for metering. お客様は、コンテナーが常に課金エンドポイントに課金情報を伝えられるようにする必要があります。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 running.

課金引数Billing arguments

docker run コマンドでコンテナーを起動するには、次の 3 つのオプションすべてに有効な値を指定する必要があります。For the docker run command to start the container, all three of the following options must be specified 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.

latest コンテナーでサポートされる依存関係Supported dependencies for latest container

2019 //Build でリリースされる最新のコンテナーでは、次がサポートされます。The latest container, released at 2019 //Build, will support:

  • Bing Spell Check: &spellCheck=true&bing-spell-check-subscription-key={bingKey} クエリ文字列パラメーターでクエリ予測エンドポイントに対して要求します。Bing spell check: requests to the query prediction endpoint with the &spellCheck=true&bing-spell-check-subscription-key={bingKey} query string parameters. 詳細については、Bing Spell Check v7 チュートリアルを参照してください。Use the Bing Spell Check v7 tutorial to learn more. この機能を使用すると、コンテナーが Bing Spell Check V7 リソースに発話を送信します。If this feature is used, the container sends the utterance to your Bing Spell Check V7 resource.
  • 新しい事前構築済みドメイン: 企業向けのこれらのドメインには、エンティティ、発話の例、およびパターンが含まれます。New prebuilt domains: these enterprise-focused domains include entities, example utterances, and patterns. これらのドメインを独自の用途で拡張します。Extend these domains for your own use.

latest コンテナーでサポートされない依存関係Unsupported dependencies for latest container

LUIS アプリにサポートされていない依存関係がある場合、サポートされていない機能を削除するまで、コンテナー用にエクスポートできません。If your LUIS app has unsupported dependencies, you won't be able to export for container until you remove the unsupported features. コンテナー用にエクスポートしようとすると、LUIS ポータルで、削除する必要があるサポートされていない機能が報告されます。When you attempt to export for container, the LUIS portal reports the unsupported features you need to remove.

LUIS アプリケーションは、次の依存関係を一切含んでいない場合に使用できます。You can use a LUIS application if it doesn't include any of the following dependencies:

サポートされていないアプリ構成Unsupported app configurations 詳細Details
サポートされていないコンテナー カルチャUnsupported container cultures オランダ語 (nl-NL)Dutch (nl-NL)
日本語 (ja-JP)Japanese (ja-JP)
ドイツ語は、1.0.1 トークナイザー以降でのみサポートされています。German is only supported with the 1.0.1 tokenizer or later.
サポートされていないエンティティ (全カルチャ)Unsupported entities for all cultures KeyPhrase 事前構築済みエンティティ (全カルチャ)KeyPhrase prebuilt entity for all cultures
サポートされていないエンティティ (英語 (en-US) カルチャ)Unsupported entities for English (en-US) culture GeographyV2 事前構築済みエンティティGeographyV2 prebuilt entities
音声認識の準備Speech priming コンテナーでは、外部依存関係がサポートされません。External dependencies are not supported in the container.
センチメント分析Sentiment analysis コンテナーでは、外部依存関係がサポートされません。External dependencies are not supported in the container.

ブログ記事Blog posts

開発者向けサンプルDeveloper samples

開発者向けサンプルは、GitHub リポジトリから入手できます。Developer samples are available at our GitHub repository.

ウェビナーの閲覧View webinar

ウェビナーに参加して、以下について学習します。Join the webinar to learn about:

  • Docker を使用して任意のマシンに Cognitive Services をデプロイする方法How to deploy Cognitive Services to any machine using Docker
  • Cognitive Services を AKS にデプロイする方法How to deploy Cognitive Services to AKS

まとめSummary

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

  • Language Understanding (LUIS) からは、発話のエンドポイント クエリ予測を提供する Docker 用 Linux コンテナーが 1 つ提供されます。Language Understanding (LUIS) provides one Linux container for Docker providing endpoint query predictions of utterances.
  • コンテナー イメージは Microsoft Container Registry (MCR) からダウンロードされます。Container images are downloaded from the Microsoft Container Registry (MCR).
  • コンテナー イメージを Docker で実行します。Container images run in Docker.
  • REST API を使用して、コンテナーのホスト URI を指定することにより、コンテナーのエンドポイントに対してクエリを実行できます。You can use REST API to query the container endpoints 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 (for example, the image or text that is being analyzed) to Microsoft.

次の手順Next steps