この記事の続きです:
Watson API Explorer の使いかた
上記記事で Watson API Explorer サービスの紹介をしました。今回はより実践的に Watson API を使ってみます。
今回対象にする Watson API は上記記事でも紹介した Natural Language Classifier (以下 NLC)とします。前回は学習前の(空の)データを確認しただけですが、今回は実際にデータを学習させた上で、学習データに対して問い合わせをする、という一連の機能を Watson API Explorer で確認する、という手順を行います。
この手順を紹介する上で、あらかじめ NLC サービスインスタンスを Bluemix 上に作成し、認証情報(username と password)を取得しておく必要があります。その手順については上記前回の記事を参照してください。
加えて今回はデータを学習させる手順が含まれるので、サンプルの学習用データを用意しました。以下のリンクをクリックして、nlc_api_training.zip をダウンロード&展開してください:
http://dotnsf.blog.jp/nlc_api_training.zip
展開すると2つのファイルが出来上がります。いずれもテキストファイル(JSON ファイルと CSV ファイル)なので、興味のある人はテキストエディタで中身を確認してみてください:
では実際に Watson API Explorer で NLC を使ってみます。まずは NLC API のページに移動します:
https://watson-api-explorer.mybluemix.net/apis/natural-language-classifier-v1
そして取得済みの username と password を画面右上欄に入力します。これで準備完了:
最初にデータを学習させてみますが、その前にまだ何も学習されていないことを確認しておきましょう。現在の状態を確認する API はリストの一番上にある GET /v1/classifiers です。ここをクリックして展開します:
この API の説明やパラメータ、実行結果の意味などが表示されますが、この API はパラメータなしで実行するので、特に何も指定する項目はありません。そのまま "Try it out!" ボタンをクリックして実行します。するとこの API が実行され、その結果(Response Body)を見ると "classifiers" が空配列([])になっており、まだ何も学習されていないことがわかります:
なお、この上記画面内の "Request URL" を見ると、同じ処理を curl で実行する場合のコマンド内容を確認できます。また "Response Headers" には REST API 実行結果に含まれている HTTP ヘッダの内容を確認することもできます。
もしもこのコマンドの実行結果が空配列ではなく何か含まれていて、次の学習コマンドを実行する前に内容をリセットする場合は、API リストの下から2番目にある DELETE /v1/classifiers/{classifier_id} を実行して現在の学習内容を削除できます。その方法は最後に紹介しますが、ここでは現在は何も学習していない状態であるとして以下を紹介します。
では NLC に学習データを送信してみましょう。新しいデータを学習させる場合の API は上から2番目の POST /v1/classifiers を使います:
パラメータの説明を見ると、この API の実行には2つの情報を(POST データとして)与える必要があると書かれています。1つは training_meta_data という名前の JSON データで、もう1つは training_data という名前の CSV データです。実はこれらのサンプルが上記でサンプル zip ファイルを展開した中に含まれていた2つのファイルです。
training_meta_data のサンプルが demo_metadata.json です。サンプルファイルの中身は以下のようになっているはずです:
非常にシンプルな内容の JSON テキストです。"language" はこの後の学習データに使われている言語(日本語なので "ja" を指定)、また "name" はこの学習データに付ける名前(この例では "dotnsf_nlc_demo")です。"name" の内容は適当に変更しても構いません。
もう1つの training_data のサンプルが dwj.csv です。 これが学習データに相当するもので、こちらもテキストエディタで開くとわかりますが、以下の様な内容の CSV ファイルです:
CSV の1行は2つだけの列で構成されており、1つ目が本文、2つ目は本文のカテゴリーになっています。つまり「(カテゴリー)の例として(本文)がある」ということを学習データとして与えています。これを1つのカテゴリーについて充分な(この dwj.csv では1つのカテゴリーにつき約100個の)本文を与えて、それを元に学習させている、ということです。
もう少し細かく説明すると、与えた本文は(training_meta_data で指定した「日本語」のルールで)単語に区切られ、品詞に分類した上でその出現頻度や傾向などから「カテゴリ(例えば cloud)とは、こういう特徴を持ったものだ」ということを自分で判断・理解して学習させています。このような例をカテゴリごとに大量に用意して、(上記サンプルでは)cloud とはこういうもの、java とはこういうもの、linux とはこういうもの、・・・といった内容を学習させる、そのための学習元データになっています。
したがって、上記の dwj.csv ファイルはそのままでも動くサンプルですが、新しい情報を書き加えたり、新しいカテゴリのデータを加えて与えたりしても動きます(更新後の内容を学習します)。興味があれば自分なりにカスタマイズしてみてください。
改めて、この2つのサンプルファイルを使って NLC の学習 API を実行してみます。Watson API Explorer のリスト上から2番目の POST /v1/classifiers を展開し、training_meta_data に demo_metadata.json を、training_data に dwj.csv を指定して、"Try it out!" をクリックします:
すると指定した2つのファイルがアップロードされ、学習用の分類器(classifier)が新たに1つ生成されて学習が開始されます。"Response Body" にはこの新たに作成された分類器を識別するための ID("classifier_id"、以下の例では "2374f9x69-nlc-8772") が含まれているのでメモしておきましょう。また現時点では "status" が "Training" となっていることもわかります。これは「この分類器はまだ学習が終わっていない状態である(問い合わせできる状態にはなっていない)」ことを意味しています。なので学習が完了するまではしばらく待つ必要があります:
なお上記の curl コマンドを見ると、2つのファイルが multipart/form-data 形式でアップロードされていることがわかります。実際にこの部分を REST API で作る際には multipart/form-data で POST するように実装する必要がある、ということもわかります。またメタデータで指定した "name" ("dotnsf_nlc_demo")はこの API の実行結果に現れていることもわかりますね。
特定の分類器の学習が完了しているかどうかを確認するための API も用意されています。リストの1番下にある GET /v1/classifier/{classifier_id} という API です。この API を展開し、パラメータの classifier_id 欄に先程作成した分類器の classifier_id(この例では "2374f9x69-nlc-8772") を指定して "Try it out!" ボタンをクリックします:
実行結果の "Response Body" を確認します。下の結果ではまだ "status" が "Training" となっていて、学習が完了していないことがわかります:
しばらく(ケースバイケースですが、15~30分程度)待って、この API を実行し、"status" が "Available" となっていれば与えたデータの学習が完了したことになります。こうなると学習済みの分類器に対する問い合わせが可能になります:
なお、この状態で再度最初の GET /v1/classifiers API を実行すると、(最初に実行した時の結果は空配列でしたが)先程新たに生成した分類器が実行結果に含まれて返ってくることがわかるはずです:
さて、学習が完了したので、Watson NLC に問い合わせを実行してみましょう。リストの上から3番目の GET /v1/classifiers/{classifier_id}/classify か、または4番目の POST /v1/classifiers/{classifier_id}/classify を使って問い合わせを行います。この2つの違いは HTTP メソッド(GET か POST か)と、問い合わせテキストの送信方法(パラメータかリクエスト本文か)です。どちらでもいいのですが、今回は後者の POST /v1/classifiers/{classifier_id}/classify を使ってみましょう。
リスト内の POST /v1/classifiers/{classifier_id}/classify を選んで展開し、classifier_id に作成した分類器の classfier_id(この例では "2374f9x69-nlc-8772")を、body には Watson NLC に問い合わせさせたい日本語テキスト文書を、それぞれ入力します。
今回問い合わせるテキストは「RedHat だけでなく Ubuntu も勉強しないとね」というものにします(変更しても構いません)。この日本語の自然言語テキストを先程学習させた NLC に対して分類をリクエストし、学習時に与えたデータに基いて「学習データに使ったカテゴリでいえば、どのカテゴリに属するテキストであるか?そしてそれはどのくらいの確信度があるのか?」を問い合わせます。
なお body には JSON テキストを指定する必要があり、そのテンプレートが右側にあるので、その内容に沿って、以下のように body を用意する必要があることに注意してください:
そして最後に "Try it out!" をクリックします。正しく実行されると、以下の様な JSON テキストが "Response Body" に返ってくるはずです:
ちなみに "Response Body" の全文はこんな感じでした:
実行結果に相当するのは上記の赤字部分です。これを表形式でまとめると以下の様な結果だった、ということになります:
1位は約 53.45% という確信度を以っての "Linux" でした。7つのカテゴリからの選択で 50% 以上の確信があるということはかなり高いと言えます。また人間の普通の感覚としても「RedHat だけでなく Ubuntu も勉強しないとね」というテキストの分類結果が Linux というのは、自然な(正しい)結果であるように感じます。 改めて注目していただきたいのは、問い合わせ本文には一言も Linux という単語はなかったのに、Linux という分類結果が高い確信度と共に得られている、という点です。
最後に、滅多に使わないかもしれませんが、作成した分類器が不要になった場合に削除する方法も紹介しておきます。リストの下から2番目にある DELETE /v1/classifiers/{classifier_id} を展開し、classifier_id パラメータに自分の ID(この例では "2374f9x69-nlc-8772")を指定して "Try it out!" をクリックします:
実行が成功しました。が、成功した場合は特に "Response Body" には削除されたかどうかがわかる情報は含まれてない感じ:
本当に消えているかどうかは、一番最初のステータス確認 API を再度実行して、classifier_id が消えていることを確認する必要があります。↓こうなっていれば消えています:
以上、Watson API Explorer を使って NLC を体験してみました。NLC がどんなものか、なんとなく理解できましたかね。
まあ、個人的には「curl でやっちまった方が早いじゃん」とも思ってますが、コマンドラインに慣れない人もいるだろうし、こういう Watson API Explorer のようなウェブインターフェースが用意された背景にはそれなりの需要があったのではないかと考えています。加えて、ドキュメントと動作確認機能が統合されているのは確かに便利ですよね。
なお、NLC の API そのものの詳細については以下のリファレンスを参照ください:
http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/natural-language-classifier/api/v1/
Watson API Explorer の使いかた
上記記事で Watson API Explorer サービスの紹介をしました。今回はより実践的に Watson API を使ってみます。
今回対象にする Watson API は上記記事でも紹介した Natural Language Classifier (以下 NLC)とします。前回は学習前の(空の)データを確認しただけですが、今回は実際にデータを学習させた上で、学習データに対して問い合わせをする、という一連の機能を Watson API Explorer で確認する、という手順を行います。
この手順を紹介する上で、あらかじめ NLC サービスインスタンスを Bluemix 上に作成し、認証情報(username と password)を取得しておく必要があります。その手順については上記前回の記事を参照してください。
加えて今回はデータを学習させる手順が含まれるので、サンプルの学習用データを用意しました。以下のリンクをクリックして、nlc_api_training.zip をダウンロード&展開してください:
http://dotnsf.blog.jp/nlc_api_training.zip
展開すると2つのファイルが出来上がります。いずれもテキストファイル(JSON ファイルと CSV ファイル)なので、興味のある人はテキストエディタで中身を確認してみてください:
では実際に Watson API Explorer で NLC を使ってみます。まずは NLC API のページに移動します:
https://watson-api-explorer.mybluemix.net/apis/natural-language-classifier-v1
そして取得済みの username と password を画面右上欄に入力します。これで準備完了:
最初にデータを学習させてみますが、その前にまだ何も学習されていないことを確認しておきましょう。現在の状態を確認する API はリストの一番上にある GET /v1/classifiers です。ここをクリックして展開します:
この API の説明やパラメータ、実行結果の意味などが表示されますが、この API はパラメータなしで実行するので、特に何も指定する項目はありません。そのまま "Try it out!" ボタンをクリックして実行します。するとこの API が実行され、その結果(Response Body)を見ると "classifiers" が空配列([])になっており、まだ何も学習されていないことがわかります:
なお、この上記画面内の "Request URL" を見ると、同じ処理を curl で実行する場合のコマンド内容を確認できます。また "Response Headers" には REST API 実行結果に含まれている HTTP ヘッダの内容を確認することもできます。
もしもこのコマンドの実行結果が空配列ではなく何か含まれていて、次の学習コマンドを実行する前に内容をリセットする場合は、API リストの下から2番目にある DELETE /v1/classifiers/{classifier_id} を実行して現在の学習内容を削除できます。その方法は最後に紹介しますが、ここでは現在は何も学習していない状態であるとして以下を紹介します。
では NLC に学習データを送信してみましょう。新しいデータを学習させる場合の API は上から2番目の POST /v1/classifiers を使います:
パラメータの説明を見ると、この API の実行には2つの情報を(POST データとして)与える必要があると書かれています。1つは training_meta_data という名前の JSON データで、もう1つは training_data という名前の CSV データです。実はこれらのサンプルが上記でサンプル zip ファイルを展開した中に含まれていた2つのファイルです。
training_meta_data のサンプルが demo_metadata.json です。サンプルファイルの中身は以下のようになっているはずです:
{"language":"ja","name":"dotnsf_nlc_demo"}
非常にシンプルな内容の JSON テキストです。"language" はこの後の学習データに使われている言語(日本語なので "ja" を指定)、また "name" はこの学習データに付ける名前(この例では "dotnsf_nlc_demo")です。"name" の内容は適当に変更しても構いません。
もう1つの training_data のサンプルが dwj.csv です。 これが学習データに相当するもので、こちらもテキストエディタで開くとわかりますが、以下の様な内容の CSV ファイルです:
Bluemix の Auto-Scaling サービスは、ターゲット環境の・・・,cloud この記事では、IBM DevOps Services で使用されるスプリント・・・,cloud : : Java 8 には、より簡単にプログラムを作成できるように・・・,java : : ほとんどの Linux システムでは、仮想マシン (VM) を作成およびサポートするための・・・,linux : :
CSV の1行は2つだけの列で構成されており、1つ目が本文、2つ目は本文のカテゴリーになっています。つまり「(カテゴリー)の例として(本文)がある」ということを学習データとして与えています。これを1つのカテゴリーについて充分な(この dwj.csv では1つのカテゴリーにつき約100個の)本文を与えて、それを元に学習させている、ということです。
もう少し細かく説明すると、与えた本文は(training_meta_data で指定した「日本語」のルールで)単語に区切られ、品詞に分類した上でその出現頻度や傾向などから「カテゴリ(例えば cloud)とは、こういう特徴を持ったものだ」ということを自分で判断・理解して学習させています。このような例をカテゴリごとに大量に用意して、(上記サンプルでは)cloud とはこういうもの、java とはこういうもの、linux とはこういうもの、・・・といった内容を学習させる、そのための学習元データになっています。
したがって、上記の dwj.csv ファイルはそのままでも動くサンプルですが、新しい情報を書き加えたり、新しいカテゴリのデータを加えて与えたりしても動きます(更新後の内容を学習します)。興味があれば自分なりにカスタマイズしてみてください。
改めて、この2つのサンプルファイルを使って NLC の学習 API を実行してみます。Watson API Explorer のリスト上から2番目の POST /v1/classifiers を展開し、training_meta_data に demo_metadata.json を、training_data に dwj.csv を指定して、"Try it out!" をクリックします:
すると指定した2つのファイルがアップロードされ、学習用の分類器(classifier)が新たに1つ生成されて学習が開始されます。"Response Body" にはこの新たに作成された分類器を識別するための ID("classifier_id"、以下の例では "2374f9x69-nlc-8772") が含まれているのでメモしておきましょう。また現時点では "status" が "Training" となっていることもわかります。これは「この分類器はまだ学習が終わっていない状態である(問い合わせできる状態にはなっていない)」ことを意味しています。なので学習が完了するまではしばらく待つ必要があります:
なお上記の curl コマンドを見ると、2つのファイルが multipart/form-data 形式でアップロードされていることがわかります。実際にこの部分を REST API で作る際には multipart/form-data で POST するように実装する必要がある、ということもわかります。またメタデータで指定した "name" ("dotnsf_nlc_demo")はこの API の実行結果に現れていることもわかりますね。
特定の分類器の学習が完了しているかどうかを確認するための API も用意されています。リストの1番下にある GET /v1/classifier/{classifier_id} という API です。この API を展開し、パラメータの classifier_id 欄に先程作成した分類器の classifier_id(この例では "2374f9x69-nlc-8772") を指定して "Try it out!" ボタンをクリックします:
実行結果の "Response Body" を確認します。下の結果ではまだ "status" が "Training" となっていて、学習が完了していないことがわかります:
しばらく(ケースバイケースですが、15~30分程度)待って、この API を実行し、"status" が "Available" となっていれば与えたデータの学習が完了したことになります。こうなると学習済みの分類器に対する問い合わせが可能になります:
なお、この状態で再度最初の GET /v1/classifiers API を実行すると、(最初に実行した時の結果は空配列でしたが)先程新たに生成した分類器が実行結果に含まれて返ってくることがわかるはずです:
さて、学習が完了したので、Watson NLC に問い合わせを実行してみましょう。リストの上から3番目の GET /v1/classifiers/{classifier_id}/classify か、または4番目の POST /v1/classifiers/{classifier_id}/classify を使って問い合わせを行います。この2つの違いは HTTP メソッド(GET か POST か)と、問い合わせテキストの送信方法(パラメータかリクエスト本文か)です。どちらでもいいのですが、今回は後者の POST /v1/classifiers/{classifier_id}/classify を使ってみましょう。
リスト内の POST /v1/classifiers/{classifier_id}/classify を選んで展開し、classifier_id に作成した分類器の classfier_id(この例では "2374f9x69-nlc-8772")を、body には Watson NLC に問い合わせさせたい日本語テキスト文書を、それぞれ入力します。
今回問い合わせるテキストは「RedHat だけでなく Ubuntu も勉強しないとね」というものにします(変更しても構いません)。この日本語の自然言語テキストを先程学習させた NLC に対して分類をリクエストし、学習時に与えたデータに基いて「学習データに使ったカテゴリでいえば、どのカテゴリに属するテキストであるか?そしてそれはどのくらいの確信度があるのか?」を問い合わせます。
なお body には JSON テキストを指定する必要があり、そのテンプレートが右側にあるので、その内容に沿って、以下のように body を用意する必要があることに注意してください:
{ "text": "RedHat だけでなく Ubuntu も勉強しないとね" }
そして最後に "Try it out!" をクリックします。正しく実行されると、以下の様な JSON テキストが "Response Body" に返ってくるはずです:
ちなみに "Response Body" の全文はこんな感じでした:
{
"classifier_id": "2374f9x69-nlc-8772",
"url": "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/2374f9x69-nlc-8772",
"text": "RedHat だけでなく Ubuntu も勉強しないとね",
"top_class": "linux",
"classes": [
{
"class_name": "linux",
"confidence": 0.5345447969025622
},
{
"class_name": "xml",
"confidence": 0.17404873174100038
},
{
"class_name": "cloud",
"confidence": 0.09516428245259624
},
{
"class_name": "opensource",
"confidence": 0.07239515901217708
},
{
"class_name": "web",
"confidence": 0.0611971709641311
},
{
"class_name": "java",
"confidence": 0.04321802457711143
},
{
"class_name": "mobile",
"confidence": 0.019431834350421725
}
]
}
実行結果に相当するのは上記の赤字部分です。これを表形式でまとめると以下の様な結果だった、ということになります:
分類結果順位 | 分類結果 | 確信度(%) |
---|---|---|
1 | linux | 53.45447969025622 |
2 | xml | 17.404873174100038 |
3 | cloud | 9.516428245259624 |
4 | opensource | 7.239515901217708 |
5 | web | 6.11971709641311 |
6 | java | 4.321802457711143 |
7 | mobile | 1.9431834350421725 |
1位は約 53.45% という確信度を以っての "Linux" でした。7つのカテゴリからの選択で 50% 以上の確信があるということはかなり高いと言えます。また人間の普通の感覚としても「RedHat だけでなく Ubuntu も勉強しないとね」というテキストの分類結果が Linux というのは、自然な(正しい)結果であるように感じます。 改めて注目していただきたいのは、問い合わせ本文には一言も Linux という単語はなかったのに、Linux という分類結果が高い確信度と共に得られている、という点です。
最後に、滅多に使わないかもしれませんが、作成した分類器が不要になった場合に削除する方法も紹介しておきます。リストの下から2番目にある DELETE /v1/classifiers/{classifier_id} を展開し、classifier_id パラメータに自分の ID(この例では "2374f9x69-nlc-8772")を指定して "Try it out!" をクリックします:
実行が成功しました。が、成功した場合は特に "Response Body" には削除されたかどうかがわかる情報は含まれてない感じ:
本当に消えているかどうかは、一番最初のステータス確認 API を再度実行して、classifier_id が消えていることを確認する必要があります。↓こうなっていれば消えています:
以上、Watson API Explorer を使って NLC を体験してみました。NLC がどんなものか、なんとなく理解できましたかね。
まあ、個人的には「curl でやっちまった方が早いじゃん」とも思ってますが、コマンドラインに慣れない人もいるだろうし、こういう Watson API Explorer のようなウェブインターフェースが用意された背景にはそれなりの需要があったのではないかと考えています。加えて、ドキュメントと動作確認機能が統合されているのは確かに便利ですよね。
なお、NLC の API そのものの詳細については以下のリファレンスを参照ください:
http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/natural-language-classifier/api/v1/