Cognitive Services Containers を利用して ローカルの Docker コンテナーで LUIS (自然言語処理) を試す (1)LUIS 作成編

"人工知能パーツ" Web API として提供されている [Azure Cognitive Services](https://azure.microsoft.com/ja-jp/services/cognitive-services/) の一部機能を Docker コンテナーにダウンロード、構築して利用できる Azure Cognitive Services Containers が提供開始となっています。(2018年12月現在プレビュー)
ローカル環境の Docker に Cognitive Services の [Language Understanding (LUIS)](https://azure.microsoft.com/ja-jp/services/cognitive-services/language-understanding-intelligent-service/)  コンテナ―を作成、稼働させて利用する方法を紹介します。

### Cognitive Services Container を試すシリーズ
- Text Analytics : [Sentiment](21bb726e9bbc8db56e54)
- LUIS
    - (1) LUIS作成編 (※当記事)
    - [(2) Container設定編](https://qiita.com/annie/items/718884672ff1b6def80b)

## Language Understanding (LUIS) とは
Azure Cognitive Services の仲間で、自然言語分析モデルを簡易に作成＆利用できるサービスで、分析モデル (LUIS app と呼びます) を作成、管理、利用するための GUI や API が用意されています。
![LUIS Portal](https://qiita-image-store.s3.amazonaws.com/0/117583/1b8297c8-e832-933b-741e-c9fce528e97c.png)

# 手順
- [0. 準備](#0-%E6%BA%96%E5%82%99)
    - LUIS サービス(サブスクリプション)
    - LUIS App
    - Docker 環境
- 1. LUIS App の作成
    - [1.1 Azure Portal から LUIS サービスの作成](#11-azure-portal-%E3%81%8B%E3%82%89-luis-%E3%82%B5%E3%83%BC%E3%83%93%E3%82%B9%E3%81%AE%E4%BD%9C%E6%88%90)
    - [1.2 LUIS Portal で LUIS App の新規作成](#12-luis-portal-%E3%81%A7-luis-app-%E3%81%AE%E6%96%B0%E8%A6%8F%E4%BD%9C%E6%88%90)
    - [1.3 LUIS Portal で LUIS App の Export](#13-luis-portal-%E3%81%A7-luis-app-%E3%81%AE-export)
- 2. Docker 環境にコンテナ―を作成＆起動して利用 (※別ページに飛びます)
    - [2.1 Docker 環境にコンテナ―作成、起動](https://qiita.com/annie/items/718884672ff1b6def80b#21-docker-%E7%92%B0%E5%A2%83%E3%81%AB%E3%82%B3%E3%83%B3%E3%83%86%E3%83%8A%E4%BD%9C%E6%88%90%E8%B5%B7%E5%8B%95)
    - [2.2 Cognitive Services Containers (LUIS) のテスト](https://qiita.com/annie/items/718884672ff1b6def80b#22-cognitive-services-containers-luis-%E3%81%AE%E3%83%86%E3%82%B9%E3%83%88)
    - [2.3 Cognitive Services Containers (LUIS) のログ確認](https://qiita.com/annie/items/718884672ff1b6def80b#23-cognitive-services-containers-luis-%E3%81%AE%E3%83%AD%E3%82%B0%E7%A2%BA%E8%AA%8D)

# 0. 準備
必要なモノは以下の通りです。(以下の説明で分かる方は 1. の手順を読み飛ばして進んでください。)

### LUIS サービス(サブスクリプション)

LUIS は [LUIS Portal](https://www.luis.ai) で LUIS App を作成すると、Starter Key (試用キー) が割り当てられます。Container で利用する場合は Azure Portal から作成した LUIS サービス (のApiKey) を利用する必要があります。

### LUIS App

自然言語モデルである LUIS App を作成して Publish すると、Container 用に Export できるようになります。

> LUIS App の Container 用 Export 方法 → [1.3 LUIS Portal で LUIS App の Export](#13-luis-portal-%E3%81%A7-luis-app-%E3%81%AE-export) をご覧ください

### Docker 環境

今回は Windows 10 上に [Dockers for Windows](https://docs.docker.com/docker-for-windows/) をインストールして使用します。
Windows 版は Windows と Linux コンテナーを利用できますが、Cognitive Services Containers を利用するには Linux コンテナ―環境が必要です。(設定やインストール時のオプションで選択できます)

> **Cognitive Services Containers を利用できる Docker 環境**
Local on Windows*/macOS/Linux (*Windows OS では Linux コンテナ―で利用)
Azure Kubernetes Service
Azure Container Instances
Azure Stack (Kubernetes cluster)

# 1. LUIS App の作成

## 1.1 Azure Portal から LUIS サービスの作成
まずは Azure Portal から LUIS サービスを作成しておきます。
[Azure Portal](https://portal.azure.com) にアクセスし、Azure サブスクリプションが紐づいたアカウントでサインインします。

左バーの **[+新規作成]** をクリック、**LUIS** で検索する or **[AI + Machine Learning]**-**[Language Understanding]** の順にクリックして、 **Language Understanding** を表示してクリックします。 
![AzurePortal_LUIS01.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/23600d0a-e5f8-89ed-d3bd-bb68e45a1e59.png)

**Language Understanding** の新規作成ペインで以下の情報を入力します。

- **Name(名前)**: (識別しやすいお好みのものを)
- **Subscription(サブスクリプション)**: (自動入力)
- **Location(場所)**: LUIS App を作成するロケーション (米国西部、東アジアなど)
- **Price Level(価格レベル)**: F0(無償版) または S0(有償版)
- **Resource Group(リソースグループ)**: (識別しやすいお好みのものを)

[作成] をクリックして、LUIS サービスを作成します。

作成が完了したメッセージが表示されたら、クリックして LUIS サービスを開きます。
メニューの **[Overview(概要)]** をクリックして、endpoint を確認、コピーしてローカルに保存しておきます。
![AzurePortal_LUIS02.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/45bf37f4-cb70-0404-8578-b506e58353b4.png)

次に、メニューの **[Key(キー)]** をクリックして、表示される Key1 をコピーしてローカルに保存しておきます。
![AzurePortal_LUIS03.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/97d35a01-77a3-3770-79ab-4d271907cc08.png)


## 1.2 LUIS Portal で LUIS App の新規作成
[LUIS Portal](https://www.luis.ai) から LUIS App (自然言語モデル) を作成します。
ここでは Container で利用できる en-us (英語)版 の LUIS を作成します。

|Intent(文章の意図)|Utterance(例文)|Entity(エンティティ)|
|:----------|:---------------|:-------------|
|Greeting|Hello|--|
|Greeting|Good Morning|--|
|Greeting|Hi|--|
|Greeting|How are you|--|
|CreateTicket|I can't login|--|
|CreateTicket|My password is expired|--|
|CreateTicket|PC is broken|--|
|CreateTicket|I can't get emails|--|
|CreateTicket|My PC doesn't get wifi|--|
|BookMeetingRoom|I want book room at 10AM tomorrow|10AM, tomorrow|
|BookMeetingRoom|I need meeting room at 3PM today|3PM, today|
|BookMeetingRoom|Can I request room at 9:00 on Dec5?|9:00, Dec5|
|BookMeetingRoom|Do you have room tomorrow from 14:00|today, 14:00|
|BookMeetingRoom|Any room left day after tomorrow at 11:00|day after tomorrow, 11:00|

[LUIS Portal](https://www.luis.ai) にアクセスし、LUIS サービスを作成したアカウントでサインインします。
![LUIS Portal](https://qiita-image-store.s3.amazonaws.com/0/117583/1b8297c8-e832-933b-741e-c9fce528e97c.png)

**[+Create New App]** をクリックして LUIS App を新規作成します。
![LUISApp01.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/e762bd12-0d51-62a4-a2d3-258eda507914.png)

新規作成画面で

- **Name**: (識別しやすいお好みのものを)
- **Culture**: English

を入力＆選択し、**[Done]** をクリックして作成します。
![LUISApp02.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/3ddf364f-111b-6027-ba02-eef865b560cd.png)

### Intent の作成 (Greeting, CreateTicket)

LUIS App の BUILD 画面で **[+Create New Intent]** をクリックして、新規 Intent を作成します。
![LUISApp03.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/6e276102-83ec-90d7-de4b-aaad0d6d3add.png)

**Intent Name** に *Greeting* と入力して **[Done]** をクリックして作成します。
![LUISApp04.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/64f60f90-3c9a-0269-eac7-387a97198a48.png)

**Greeting** の真下にある欄に分析させたい Utterance(例文) を入力して Enter、を繰り返して例文の登録を行います。
![LUISApp05.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/92cfffe1-51f9-b1da-0065-73ca31a47423.png)

左列メニューの **Intent** をクリックし、*Greeting* が作成されていることを確認します。
再度 **[+Create New Intent]** をクリックして、**CreateTicket** という名前で Intent を追加作成します。
**CreateTicket** の真下にある欄に分析させたい Utterance(例文) を入力して Enter、を繰り返して例文の登録を行います。
![LUISApp06.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/fe3a9f81-6b56-f585-59f5-82f53f73f30c.png)


### Prebuilt Entity の利用 と Intent 追加 (BookMeetingRoom)
左列メニューの **Entity** をクリックします。 **[+Add prebuilt entity]** をクリックして汎用 Entity を追加します。
![LUISApp07.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/dbee8d55-11ae-5cf6-c071-6a599fed35fc.png)

日付や時刻を判別する **datetimeV2** にチェックをつけ、**[Done]** をクリックして追加します。
![LUISApp08.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/c92a5c50-f847-b187-8ca9-3faed5689b8e.png)

もう一度左列メニューの **Intent** をクリックし、**[+Create New Intent]** をクリックして、**BookMeetingRoom** という名前で Intent を追加作成します。
同様に Utterance を入力し、今度は日付や時刻の部分が datetimeV2 として取得されていれば OK です。
![LUISApp09.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/92751129-09bd-c661-662b-cdbe556b55b4.png)

>**Entities View** を OFF にすると、元の単語が表示されます。
![LUISApp10.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/c4931ab4-da44-895b-693f-29aa02f4d934.png)

### LUIS App の Train, Publish
LUIS App に設定した Intent, Entity, Utterance の学習 (Training) を行います。
画面右上の **[Train]** をクリックして、Training を実行します。
**Successfully Trained** とメッセージが表示され、Train の丸印が緑になれば完了です。
![LUISApp11.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/b98017dc-ec7b-36ef-7329-26e89a2c4c80.png)

画面右上の **[Test]** をクリックして、LUIS App のテストを行います。
分析したい文章を入力すると、推定された Intent が表示されます。
![LUISApp12.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/5c85978e-f05d-ad88-b8db-945f5a1df89f.png)

**Inspect** をクリックすると、詳細が表示され、推定された Entity なども確認できます。
![LUISApp13.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/91ca4ddc-14b0-edf1-b800-df082db935c2.png)

画面右上の **[Publish]** をクリックして、LUIS App の公開 (Publish) を行います。
**Production** (本番環境) または Staging (テスト環境) を選択し、[Publish] をクリックして公開に進みます。
![LUISApp14.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/e8ff1ea1-6447-99d5-0c24-ffd1f1b544c7.png)

**Publishing Complete** とメッセージが表示されたら Publish は完了です。
![LUISApp15.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/1bdc6ac9-539e-1093-ec17-e103ce2eabaf.png)

画面右上の **[MANAGE]** タブをクリックして、LUIS App 管理画面を表示します。
左側のメニュー の **Application Settings** にある **Keys and Endpoint settings** をクリックします。
![LUISApp16.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/73558787-9c9a-bbd7-54d9-df0e44b2cd22.png)

LUIS App に Web API で利用する場合の Endpoint (アクセス先)が確認できます。このような URL になっており、GET または POST で利用できます。(詳細)

```
https://westus.api.cognitive.microsoft.com/luis/v2.0/apps/{___LUIS_APP_ID___}?subscription-key={___LUIS_STARTER_KEY___}&timezoneOffset=-360&q=
```

URL末尾の *q=* の後に分析したい文章を入力すると、GET で推定結果を取得できます。日本時間(UTC+9:00)を設定するには、timezoneOffset=+540 にすればOKです。

```
https://westus.api.cognitive.microsoft.com/luis/v2.0/apps/{___LUIS_APP_ID___}?subscription-key={___LUIS_STARTER_KEY___}&timezoneOffset=+540&q=I need room now
```

*now* を現在の日本時間として取得しています。
![LUISApp17.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/9f04da74-04b3-2907-9aea-0476abe4a1ae.png)

LUIS Portal の画面に戻り、**Application Settings** にある **Application Information** をクリックします。画面に表示される **Application ID** をコピーしてローカルに保存しておきます。
![LUISApp18.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/62b30e54-2dbd-7266-9f7b-b87dc66d9b5a.png)

## 1.3 LUIS Portal で LUIS App の Export
### LUIS App の Export
作成、公開した LUIS App を Container 用に Export します。
画面左上メニューバーの **[My apps]** をクリックして、LUIS App 一覧を表示します。
作成した LUIS App にチェック☑をつけ、**[Export]**-**[Export for container]**-**[production Slot]** の順にクリックします。
![LUISApp19.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/b0d1f58d-6d70-8807-8fe2-9dbe7728b4cb.png)


ダウンロードした LUIS App は展開などせずそのまま利用します。

>ファイル名は *(LUIS_APP_ID)_PRODUCTION.gz* の形式になっています。

![LUISApp20.PNG](https://qiita-image-store.s3.amazonaws.com/0/117583/c2f9c86c-f920-e840-5145-a0bb8dde684e.png)