==============================
系列ラベリング予測を実行する
==============================

.. Contents:: 目次
    :local:
    :depth: 1

.. highlight:: console



はじめに
=========

| 系列ラベリングは文書中の各単語を所定のカテゴリに分類する機能です。
| ここでは系列ラベリング学習と系列ラベリング予測を行います。
| 「テキスト分析 with Deep Learning」(TDL)を用いた分析の例として、小説中の各単語が属するカテゴリ名を予測します。



実行準備
===========


データを準備する
----------------

| 系列ラベリングを実行するためには文書中の各単語が属するべき正しいカテゴリ名を指定した正解ラベルとテキストデータをまとめた学習データであらかじめ学習する必要があります。


| テキストデータをTDLが読み込めるトークンCSV形式に加工します。
| 系列ラベリングでは文書中の各単語に対して学習と予測をする必要があるため文書を単語に分けたトークンCSV形式のテキストデータを作成する必要があります。
| テキストデータの加工に関してはテキストエディタなどを使用して実施することも可能ですが、TDLが提供するデータ整形コマンドを使用することができます。


| ここでは、事前に用意したデータを使用して以降の手順を進めます。

| 1. ユーザがアクセス可能なディレクトリに *tdl-getting_started.zip* を格納します。

| 2. 格納したファイルを解凍します。

::
	
	$ unzip tdl-getting_started.zip
	
| 3. ディレクトリを移動します。以降の操作は本ディレクトリ内で実施します。

::

	$ cd tdl-getting_started

| データは *./examples/sample_data/sequence_labeling/* にあります。
| 以下にデータ例として予測に用いるデータを示しています。予測に用いるデータには正解ラベルは必須ではありませんが、精度評価のために使用します。

============== =============== ============== 
index          text            label          
============== =============== ============== 
1              かつごう        O
2              たっ            O
...
54             ヨシ            人名           
55             ちゃん          人名           
56             の              O              
...
============== =============== ============== 

.. code-block :: none
	:caption: csv形式サンプルデータ(例)　text(トークン)　label(人名、数など)
	
	index,text,label
	1,かつごう,O
	2,たっ,O
	...
	,,
	...
	54,ヨシ,人名
	55,ちゃん,人名
	56,の,O
	...
	


事前学習
=========

| 整形済みのテキストデータを学習し、予測モデルに解析対象のテキストデータに含まれる単語の意味を学習させる作業です。
| TDLが提供するプリセットモデルは既に大量の日本語テキストデータを事前学習済みであるため、一般的な文書を解析する場合、本作業は不要です。
| 専門文書や社内文書など一般的でない単語が含まれるテキストデータを解析する場合は事前学習を実施したほうが、高精度な解析をすることが可能です。

| なお、ここでは本作業を省略します。実行する場合は :ref:`pre_train2` をご覧ください。

系列ラベリング学習の実行
=============================

| 学習データ(*examples/sample_data/sequence_labeling/train.csv*)を用いて、系列ラベリング学習を実行します。

設定ファイルを準備する
-----------------------------
| 系列ラベリング学習コマンドコンフィグファイルを準備します。
| ここでは事前に準備した *./examples/config/sequence_labeling_train.json* を使用します。

| 設定ファイル上でepoch数やロードするモデルのパス、出力先のパスなどを指定できます。
| 今回は、TDLが提供しているpresetモデルを読み込み、学習を行うよう設定されています。

.. code-block :: none
	:caption: sequence_labeling_train.json
	
	{
	  "data": {
	    "train": {
	      "text": {
	        "file": "./examples/sample_data/sequence_labeling/train.csv",
	        "index": "index",
	        "column": "text"
	      },
	      "label": {
	        "file": "./examples/sample_data/sequence_labeling/train.csv",
	        "index": "index",
	        "column": "label"
	      }
	    },
	    "valid": {
	      "text": {
	        "file": null,
	        "index": "index",
	        "column": "text"
	      },
	      "label": {
	        "file": null,
	        "index": "index",
	        "column": "label"
	      }
	    }
	  },
	  "model": {
	    "load": {
	      "dir": "cl-tohoku/bert-base-japanese-whole-word-masking"
	    },
	    "save": {
	      "dir": "./examples/sequence_labeling_train/"
	    },
	    "train": {
	      "num_epochs": 5,
	      "batch_size": 32,
	      "max_seq_length": 64,
	      "learning_rate": 5e-05
	    },
	    "earlystop": {
	      "patience": null,
	      "min_delta": 1e-03
	    }
	  },
	  "task": {
	    "sequence_labeling": {
	      "categories": null
	    }
	  }
	}



系列ラベリング学習コマンドを実行する
---------------------------------------

| 学習データを用いて系列ラベリング予測モデルを作成します。その際、実行スクリプトとして、*sequence_labeling_train.rpd* を指定します。

| jupyter notebookのセルから以下のコマンドを実行します。

::

	 ! pyrapid /opt/nec/pyrapid/template/DMA/sequence_labeling_train.rpd --config ./examples/config/sequence_labeling_train.json
	

| コマンド実行に成功すると標準出力に系列ラベリング学習の進捗状況が表示されます。

| コマンドが完了すると、 *examples/sequence_labeling_train/* に系列ラベリング用の予測モデルが出力されます。

| 以上で、予測モデル作成(系列ラベリング学習)は完了です。



予測の実行
=============================

| テストデータと予測モデルを用いて予測を実行します。

| 学習していない未知のテキストデータに系列ラベリング予測モデルを適用し、テキストデータ中の各単語に対する予測カテゴリを生成し、予測結果ファイルを出力する作業です。本作業は、学習が正常に完了していることが前提となります。

| 本手順では系列ラベリング用予測データ(*examples/sample_data/sequence_labeling/predict.csv*)を使って系列ラベリング予測を実施します。
| なお、系列ラベリング予測には正解ラベルは必須ではありませんが、正解ラベルを指定すると系列ラベリング精度を評価することが可能です。


設定ファイルを準備する
-----------------------------

| 系列ラベリング予測コマンドコンフィグファイルを準備します。
| ここでは事前に準備した *./examples/config/sequence_labeling_predict.json* を使用します。

.. code-block :: none
	:caption: sequence_labeling_predict.json

	{
	  "data": {
	    "predict": {
	      "text": {
	        "file": "./examples/sample_data/sequence_labeling/predict.csv",
	        "index": "index",
	        "column": "text"
	      },
	      "label": {
	        "file": "./examples/sample_data/sequence_labeling/predict.csv",
	        "index": "index",
	        "column": "label"
	      }
	    }
	  },
	  "model": {
	    "load": {
	      "dir": "./examples/sequence_labeling_train/"
	    },
	    "predict": {
	      "batch_size": 32,
	      "max_seq_length": 64
	    }
	  },
	  "result": {
	    "save": {
	      "dir": "./examples/sequence_labeling_predict/"
	    }
	  }
	}


系列ラベリング予測コマンドを実行する
---------------------------------------

| 系列ラベリング予測モデルを用いて予測を実行します。その際、実行スクリプトとして、*sequence_labeling_predict.rpd* を指定します。

| jupyter notebookのセルから以下のコマンドを実行します。

::

	! pyrapid /opt/nec/pyrapid/template/DMA/sequence_labeling_predict.rpd --config ./examples/config/sequence_labeling_predict.json

| コマンド実行に成功すると系列ラベリング予測の進捗状況が表示されます。

| コマンドが完了すると、 *./examples/sequence_labeling_predict/* に以下のファイルが出力されます。

* 分類結果ファイル
* 分類精度ファイル
* 分類混同行列ファイル
* ログファイル
* 系列ラベリングコンフィグファイル

| 各出力ファイルの詳細については *NEC Advanced Analytics –テキスト分析 with Deep Learning V1.1 コマンドリファレンスガイド* の「系列ラベリング予測コマンド」の節を参照してください。

| 例として予測結果の分類結果ファイルを以下に示します。
| 各indexに対しての予測結果がpredicted列に示されていることが確認できます。
| その他の列は各カテゴリの所属確率を示しています。

============== =============== ============== =============== ===============
index          predicted       O              人名            数
============== =============== ============== =============== ===============
1              O               0.99996...     2.2004...34e-05 1.2572...25e-05
2              O               0.99997...     1.6591...85e-05 1.2136...17e-05
...
54             人名            0.00604...     0.9924...       0.0015...
55             O               0.94034...     0.0576...       0.0019...
56             O               0.99994...     3.7759...09e-05 1.7675...89e-05
...
============== =============== ============== =============== ===============


| 以上で、予測は完了となります。

.. _pre_train2:

【参考】事前学習
==================

| 本作業では事前学習を省略しましたが、実行する場合は以下の手順に従います。


設定ファイルを準備する
----------------------------------

| 事前学習コマンドコンフィグファイルを準備します。
| 参考として *./examples/config/bert_pretrain.json* が用意されています。

.. code-block :: none
	:caption: bert_pretrain.json
	
	{
	  "data": {
	    "train": {
	      "text": {
	        "file": "./examples/sample_data/classification/train.csv",
	        "index": "index",
	        "column_a": "text",
	        "column_b": "text_b"
	      }
	    },
	    "valid": {
	      "text": {
	        "file": null,
	        "index": "index",
	        "column_a": "text_a",
	        "column_b": "text_b"
	      }
	    }
	  },
	  "model": {
	    "load": {
	      "dir": "cl-tohoku/bert-base-japanese-whole-word-masking"
	    },
	    "save": {
	      "dir": "./examples/bert_pretrain/"
	    },
	    "train": {
	      "num_epochs": 5,
	      "batch_size": 32,
	      "max_seq_length": 64,
	      "learning_rate": 5e-05
	    },
	    "early_stop": {
	      "patience": null,
	      "min_delta": 1e-03
	    }
	  },
	  "task": {
	    "method": "mlm"
	  }
	}


事前学習コマンドを実行する
--------------------------------------

jupyter notebookのセルから以下のコマンドを実行します。

::
	
	! pyrapid /opt/nec/pyrapid/template/DMA/bert_pretrain.rpd --config ./examples/config/bert_pretrain.json

| コマンド実行に成功すると事前学習の進捗状況が表示されます。
| コマンドが完了すると、*examples/bert_pretrain/* に以下のファイルが出力されます。

* 予測モデルファイル
* ログファイル
* BERT事前学習コンフィグファイル 

| 以上で、事前学習は完了です。
| 事前学習したモデルを利用するには *sequence_labeling_train.json* ファイルを編集し、作成したモデルのパスを指定する必要があります。
