BrainScript と Python: 読者の理解と拡張

[アーティクル]
07/31/2017

バージョン 1.5 以降、CNTK はモノリシックリーダー設計から、さまざまな形式の入力データを指定して作成できる、より構成可能なモデルに移行しています。

以前は、データ読み取りのさまざまな側面について、各閲覧者が責任を負っていましたが、これらに限定されません。

外部ストレージからメモリ内表現へのデータの逆シリアル化
コーパス全体のランダム化
入力シーケンス/サンプルのさまざまな変換 (画像のトリミングまたはスケーリングなど)
GPU で使用できるレイアウトを使用して、さまざまなモード (フレーム、シーケンス、または切り捨てられた BPTT) のミニバッチを作成する
ミニバッチと IO チャンクのレベルでプリフェッチする

バージョン 1.5 では、上記の機能の主要な部分が除外され、コア CNTK に移行され、異なるリーダー間で共有されるようになりました。このバージョンでは、新しいデータ形式をサポートするために拡張できる 2 つの主要な抽象化も導入されています。

デシリアライザー - 外部ストレージからインメモリシーケンスへの入力の逆シリアル化を行います
変換 - 入力シーケンスを出力シーケンスに変換します

次のセクションでは、これらの抽象化について詳しく説明します。

Python でのリーダー (ミニバッチソース) の構成

このセクションでは、複合リーダー (MinibatchSource) を Python で構成する方法の例をいくつか示します。

次の例は、AlexNet_ImageNet_Distributed.pyから適応したものです。Transforms セクションの AlexNet リーダーと同等の Python を示しています。

import cntk.io

mean_file = ...
map_file = ...

# model dimensions
image_height = 227
image_width  = 227
num_channels = 3  # RGB
num_classes  = 1000

transforms = [
     ImageDeserializer.crop(crop_type='randomside', 
                            side_ratio=0.88671875, 
                            jitter_type='uniratio'),
     ImageDeserializer.scale(width=image_width, 
                            height=image_height, 
                            channels=num_channels, 
                            interpolations='linear'),
     ImageDeserializer.mean(mean_file)
]

reader = MinibatchSource(
    ImageDeserializer(map_file, StreamDefs(
        # first column in map file is referred to as 'image'
        features = StreamDef(field='image', transforms=transforms),
        # and second as 'label' 
        labels   = StreamDef(field='label', shape=num_classes))))

次の例 (A2_RunCntk_py3.py から適応) は、複数のデシリアライザーを組み合わせる方法を示しています。

n_rois = 100
n_classes = 17
rois_dim = 4 * n_rois
label_dim = n_classes * n_rois

map_file = ...
roi_file = ...
label_file = ...

# read images
scale = ImageDeserializer.scale(width=1000, 
                                height=1000, 
                                channels=3,
                                scale_mode="pad", 
                                pad_value=114, 
                                interpolations='linear')
image_source = ImageDeserializer(map_file)
image_source.ignore_labels()
image_source.map_features('features', [scale])

# read rois and labels
roi_source = CTFDeserializer(roi_file)
roi_source.map_input('rois', dim=rois_dim, format="dense")
label_source = CTFDeserializer(label_file)
label_source.map_input('roiLabels', dim=label_dim, format="dense")

# define a composite reader
reader = MinibatchSource([image_source, roi_source, label_source])

...

# define mapping from reader streams to network inputs
input_map = {
    image_input: reader.streams.features,
    roi_input: reader.streams.rois,
    label_input: reader.streams.roiLabels
}

BrainScript

デシリアライザー

エンドツー エンドの LSTM/FullUtterance テストから HTKMLFReader の構成の次のフラグメントを見てみましょう (ここでは完全な構成 )。

...
# Old reader config. For illustration only.
reader = [
    readerType = "HTKMLFReader"
    readMethod = "blockRandomize"
    nbruttsineachrecurrentiter = 32
    randomize = "auto"
    verbosity = 0

    features = [
        dim = 363
        type = "real"
        scpFile = "$DataDir$/glob_0000.scp"
    ]

    labels = [
        mlfFile = "$DataDir$/glob_0000.mlf"
        labelMappingFile = "$DataDir$/state.list"

        labelDim = 132
        labelType = "category"
    ]
]

この構成のフラグメントは、"features" と "labels"の名前を持つ 2 つのデータストリームを生成するリーダーを宣言します。次の 2 種類のファイルを入力として受け取ります。

scp ファイル ("スクリプト" ファイル) として HTK parlance で知られている機能ファイルの一覧
mlf ファイルと呼ばれるラベルファイル ("マスターラベルファイル")

上記の構成フラグメントには、scp 形式または mlf 形式の逆シリアル化方法を定義する明示的なエンティティはありません。すべてが、HTKMLFReader 構成にカプセル化されます。したがって、とと共に異なるデータ形式の別の入力ストリームを公開する必要がある場合は、HTKMLFReader 変更し、そこにサポートを追加する必要があります。

コンポーザビリティを高め、再利用するために、同じ入力 新しい 構成によって、デシリアライザーと生成される入力ストリームが明示的に定義されます。

reader = [
    verbosity = 0
    randomize = true

    # A list of deserializers the reader uses.
    deserializers = (
        [
            # Type of deserializer, in this case the one that knows
            # how to deserialize HTK feature files.
            type = "HTKFeatureDeserializer"
            # Module (.dll or .so) where this deserializer is implemented
            module = "HTKDeserializers"

            # Description of input streams the deserializer provides,
            # can be one or many, depending on a particular
            # deserializer implementation
            # For HTKFeatureDeserializer, just one stream can be described.
            input = [
                # Description of input stream to feed the Input node named "features"
                features = [
                    dim = 363
                    scpFile = "$DataDir$/glob_0000.scp"
                ]
            ]
        ]:
        [
            # Type of deserializer, in this case the one
            # that knows how to deserialize mlf files.
            type = "HTKMLFDeserializer"
            module = "HTKDeserializers"
            # Description of input streams the deserializer provides,
            # For HTKMLFDeserializer, just one stream can be described.
            input = [
                # Description of input stream to feed the Input node named "labels"
                labels = [
                    dim = 132
                    mlfFile = "$DataDir$/glob_0000.mlf"
                    labelMappingFile = "$DataDir$/state.list"
                    # whether phone boundary information should be encoded
                    # set to true in CTC-type training
                    phoneBoundaries=false
                ]
            ]
        ]
    )
]

mlf および htk デシリアライザーによって生成されるシーケンスは、論理キー (音声発話を一意に識別し、scp ファイルと mlf ファイルの両方に存在する文字列) に基づいて結合されます。別の形式のストリームが必要な場合は、対応するデシリアライザーを構成に追加するだけです (HTK 機能と HTK MLF デシリアライザーでは、現在、複数の入力ストリームを公開することはできません)。

手記

現在、古いリーダー構成と新しいリーダー構成の両方がサポートされています。リーダー構成で "デシリアライザー" キーが使用されている場合、リーダー型は暗黙的に "CompositeDataReader" に設定されます。 CompositeDataReader モジュールを Windows に読み込むことができるようにするには、Cntk.Composite.dll を CNTK 実行可能ファイルと同じディレクトリに配置する必要があります。 Linux Cntk.Composite.so は、CNTK 実行可能ファイルを含む bin フォルダーに並んだ lib フォルダーに配置する必要があります。

現在、CNTK では次の逆シリアライザーがサポートされています。

デシリアライザーの種類	モジュール	形容
HTKFeatureDeserializer	HTKDeserializers	HTK 機能ファイルのデシリアライザー
HTKMLFDeserializer	HTKDeserializers	HTK MLF ファイルのデシリアライザー
ImageDeserializer	ImageReader	プレーンファイルまたは zip アーカイブでエンコードされたイメージのデシリアライザー。
Base64ImageDeserializer	ImageReader	マッピングファイルで base64 文字列としてエンコードされたイメージのデシリアライザー。
CNTKTextFormatDeserializer	CNTKTextFormatReader	CNTK テキストフォーマットファイルのデシリアライザー
CNTKBinaryFormatDeserializer	CNTKBinaryReader	CNTK バイナリ形式ファイルのデシリアライザー

構成パラメーターの完全な説明については、以下の表を参照してください。

変換

変換は、シーケンスを入力として受け取り、シーケンス内のサンプルのいくつかの変換を実行し、出力シーケンスを返す単純な抽象化です。変換の一般的な例として、トリミング、スケール、転置などの画像のさまざまな変換があります。変換は入力ごとに構成できます。

入力に変換を適用する方法を見てみましょう (構成は Tests/EndToEndTests/Image/AlexNet テストから取得されます)。

deserializers = ([
    type = "ImageDeserializer"
    module = "ImageReader"

    # Map file which maps images to labels
    file = "$ConfigDir$/train_map.txt"

    # Description of input streams
    input = [
            # Description of input stream to feed the Input node named "features"
            features = [
                transforms = (
                    [
                        type = "Crop"
                        # Possible values: Center, RandomSide, RandomArea, Multiview10. Default: Center
                        cropType = "RandomSide"
                        # Crop scale side ratio.
                        sideRatio = 0.875
                        # Crop scale ratio jitter type
                        jitterType = "UniRatio"
                    ]:[
                        type = "Scale"
                        width = 224
                        height = 224
                        channels = 3
                        # Interpolation to use when scaling image to width x height size.
                        interpolations = "linear"
                    ]:[
                        type = "Mean"
                        # Stores mean values for each pixel in OpenCV matrix XML format.
                        meanFile = "$ConfigDir$/ImageNet1K_mean.xml"
                    ]:[
                        # Changes the image layout from HWC to CHW
                        type = "Transpose"
                    ]
                )
            ]
            # Description of input stream to feed the Input node named "labels"
            labels = [
                labelDim = 1000
            ]
        ]
    ]
])

この構成では、入力ストリーム featuresに 4 つの変換が適用されます。最初に、イメージデータデシリアライザーは、HWC 表現の 1 つのイメージで構成されるシーケンスを生成します。その後、並べ替えられた変換の一覧が画像に適用されます。最初に、トリミング 変換、次に Scale と Meanが続きます。最後の変換は、イメージレイアウトを HWC から CHW に変更するの入れ替えです。

現在、次の変換が実装されています。詳細な説明については、ImageReaderを参照してください。

変換の種類	モジュール
実り	ImageReader
規模	ImageReader
色	ImageReader
意味する	ImageReader
転置	ImageReader

新しいリーダー構成の形式の説明

複数のデータ逆シリアライザーを構成するリーダー構成セクションは、次のようになります。

reader = [
    randomize = true|false
    verbosity = 0|1|2
    ...

    deserializers = (
        [<deserializerConfiguration1>]:
        [<deserializerConfiguration2>]:
        ...
        [<deserializerConfigurationN>]
    )
]

各デシリアライザー構成は次のように指定されます。

[
    module = "<readerModuleName>"   # Name of the external module (.dll or .so) where this particular deserializer is implemented
    type = "<deserializerType>"     # The type of the deserializer

    # There could be more deserializer-specific options in this section

    # Date deserializer input - describes a set of streams this deserializer produces.
    # It can be one (as in HTK) or many (as in CNTKTextFormat)
    input = [
        # Replace 'InputNameN' by the name of the corresponding input node in the network.
        InputName1 = [<inputConfiguration>]
        InputName2 = [<inputConfiguration>]
        ...
    ]
]

入力構成には、入力固有のオプションと、必要に応じて、入力に適用する必要がある変換の順序付きリストが含まれます。

[
    # Per-input data deserializer-specific options

    # Optionally a pipeline of transformations, to be implemented by data deserializer's reader module:
    transforms = (
       [<transformationConfiguration1>]:
       [<transformationConfiguration2>]:
       ...
       [<transformationConfigurationN>]
    )
]

変換構成では、変換の種類と変換固有のオプションを識別します。

[
    type = "<transformName>"
    # Transform-specific options
]

構成オプション

一般的な閲覧者の構成

パラメーター	形容
`verbosity`	詳細レベル (`0`、`1`、`2`)、さまざまなコンポーネント (Randomizer、Deserializer、Bundler など) の診断出力を制御オプションのでは、既定で `0`。
`randomize`	入力をランダム化するかどうかを指定します (`true`、`false`)。ランダム化メソッドは、HTKMLFReader の blockRandomize と同じです。省略可能なでは、既定値は `true`です。
`randomizationSeed`	初期ランダム化シード値 (入力データが再ランダム化されるときにスイープごとにインクリメントされます)。省略可能なでは、既定値は `0`です。
`randomizationWindow`	ランダム化ウィンドウのサイズ (正の整数) を指定します (つまり、ランダム化範囲)。このパラメーターは、一度にメモリに格納する必要があるデータセットの量に影響します。省略可能なでは、既定では、データセット全体のサイズ ( の値に応じて、サンプルまたはチャンク単位) に設定されます。ただし、デシリアライザーの 1 つがで、が明示的にに設定されていない場合、は既定で (約 4 GB のディスク領域分のチャンク) になります。 `randomize` が `false`されている場合、このパラメーターは無視されます。
`sampleBasedRandomizationWindow`	`true`場合、ランダム化ウィンドウのサイズは一定数のサンプルとして、それ以外の場合はチャンクの数として解釈されます。省略可能なでは、デシリアライザーの一覧に `CNTKTextFormatDeserializer` が存在しない場合は既定で `true` され、それ以外の場合は `false` されます。 `randomizationWindow`と同様に、`randomize` が `false`されている場合、このパラメーターは無視されます。
`truncationLength`	BPTT (正の整数) の切り捨ての長さをサンプル単位で指定します。必須は、`truncated` が `true`されている場合にのみ、それ以外の場合は無視されます。
`multiThreadedDeserialization`	デシリアライザー (`true`、`false`) からミニバッチのシーケンスを収集するときに、複数のスレッドを使用するかどうかを指定します。省略可能なです。
`frameMode`	フレームレベルまたはシーケンスレベルでデータをランダム化して返すかどうかを指定します。 `true`すると、入力シーケンスはフレームに分割されます。省略可能なです。 `frameMode` と `truncated` の両方を同時に `true` に設定することはできません。
`truncated`	`true`すると、時間 (BPTT) による逆反映の切り捨てが有効になります。省略可能なです。 `frameMode` と `truncated` の両方を同時に `true` に設定することはできません。
`useNumericSequenceKeys`	シーケンスキーは、異なるデシリアライザー間でシーケンスを関連付けるために使用されます。一部のデシリアライザー (HTK と MLF) の場合、シーケンスキーは任意の文字列です。それらを格納するには、大きなコーパスに多くのメモリが必要です。シーケンスキーが数値であることが確実な場合は、このパラメーターを true に設定してください。その場合、すべての文字列キーが整数に変換され、メモリ負荷が減少します。省略可能。既定の `false`です。
`hashSequenceKeys`	上記のメモリ上の理由から、このパラメーターを true に設定することで、文字列キーをハッシュすることもできます。文字列シーケンスキー (HTK、MLF) をサポートするデシリアライザーにのみ使用してください。省略可能。既定の `false`です。
`cacheIndex`	前処理段階で構築されたメタデータをディスクに書き込み、使用可能な場合はディスクから読み込むかどうかを指定します (`true`、`false`)。省略可能なでは、既定値は `false`です。詳細については、以下のセクションを参照してください。 CNTK バージョン 2.1 の新機能です。

インデックスキャッシュ

手記

CNTK バージョン 2.1 の新機能。

インデックスキャッシュを使用すると、特に大きな入力ファイルを操作する場合に、起動時間を大幅に短縮できます (2 ~ 3 倍)。 cacheIndex フラグを true に設定すると、キャッシュファイルが使用できない場合、または古い (入力ファイルより古い) 場合に、インデックス作成メタデータをディスク (入力ファイルと同じディレクトリ) に書き込むようリーダーに通知されます。この書き込みはベストエフォートであり、リーダーのパフォーマンスに影響を与えないように別のスレッドで実行されます。キャッシュファイルが存在し、up-to-date である場合、リーダーは入力ファイルをスキミングしてインデックスを作成しなくなります。代わりに、キャッシュファイルからインデックスが読み込まれます。特定のリーダー構成パラメーターはインデックス作成に直接影響することに注意してください (たとえば、frameMode の値が異なれば、インデックスのシーケンス数が異なる可能性があります)。そのため、キャッシュファイルは、キャッシュを生成した構成とは異なる構成のリーダーによって無視される可能性があります。キャッシュの利点を最大限に活用するには、以降の再実行時に構成を変更しないでください。

cacheIndex は、ImageDeserializer と CNTKBinaryFormatDeserializer には影響しません。前者では入力データのインデックスが作成されず、後でインデックス情報が形式自体に埋め込まれているので、

一般的なデシリアライザーの構成

パラメーター	形容
`module`	データデシリアライザーを実装するリーダーモジュール名を指定します。必須。
`type`	特定のリーダーモジュールによって公開されるデータデシリアライザー名を指定します。必須。

一般的な変換の構成

パラメーター	形容
`type`	データデシリアライザーを実装するリーダーモジュールによって公開される変換名を指定します。必須。

HTKFeatureDeserializer オプション

パラメーター	形容
`scpFile`	処理する SCP ファイルへのパスの一覧。ファイルは HTK 互換ファイルで、"アーカイブ" 形式で指定する必要があります。アーカイブの使用の詳細については、HTKMLF リーダーで説明されています。必須。
`dim`	目的のコンテキストウィンドウを持つ完全な特徴ベクトルディメンションを指定する整数。¹必須
`contextWindow`	正の整数のペアとして指定することも、単一の正の整数として指定することもできます (この場合、同じ数のペアとして 2 回繰り返されます)。サンプルのコンテキストウィンドウの左右のサイズ (ペアの 1 番目と 2 番目の整数) を指定します。省略可能なでは、既定値は `1`です。
`prefixPathInSCP`	SCP ファイル内で指定されたパスに適用するプレフィックス文字列。省略可能なです。

¹ たとえば、72 次元の特徴 (24 次元のフィルターバンク特徴とデルタおよび差分係数) があり、ネットワークが 11 フレームのコンテキストウィンドウを処理するように設計されている場合、指定されたディメンションは 792 である必要があります。

HTKMLFDeserializer オプション

パラメーター	形容
`mlfFile`	`scp` ファイルで指定されたすべての発話のラベルを含む HTK スタイルの `mlf` ファイルへのパス。 `mlfFileList` が指定されていない場合は、必須。
`mlfFileList`	`scp` ファイルで指定されたすべての発話のラベルを含む HTK スタイルの `mlf` ファイルへのパスの配列。 `mlfFile` が指定されていない場合は、必須。
`dim`	ラベルセットのカーディナリティの合計 (正の整数)。必須。
`labelMappingFile`	`mlf` ファイルに表示されるすべてのラベルを 1 行に 1 つずつ一覧表示するファイルへのパス。必須。

labelDim は、dim のシノニムとして使用できます。

CNTKTextFormatDeserializer オプション

CNTKTextFormatReader で使用できるのと同じオプション

ImageDeserializer オプション

file: 各行に、論理シーケンスキー、イメージファイル (e.g. JPEG、PNG など) と 0 ベースのラベルの間にタブ区切りのマッピングが含まれている単純なテキストファイル。

詳細については、ImageReaderを参照してください。

Base64ImageDeserializer オプション

このデシリアライザーは、ImageDeserializer で使用できるのと同じオプションをサポートしています。唯一の違いは、マッピングファイルの形式です。

file: 各行に、論理シーケンスキー (省略可能、省略可能)、0 から始まるカテゴリラベル、base 64 でエンコードされた画像ファイル (e.g. JPEG、PNG など) の間のタブ区切りのマッピングが含まれる単純なテキストファイル。

構成とテストの例

完全なネットワーク定義とそれに対応するデータ・セットの例は、CNTK リポジトリーにあります。逆シリアライザーを使用する単体テストとエンドツーエンドテストもあります。つまり、

次の方法で共有

BrainScript と Python: 読者の理解と拡張

Python でのリーダー (ミニバッチソース) の構成

BrainScript

デシリアライザー

変換

新しいリーダー構成の形式の説明

構成オプション

一般的な閲覧者の構成

インデックスキャッシュ

一般的なデシリアライザーの構成

一般的な変換の構成

HTKFeatureDeserializer オプション

HTKMLFDeserializer オプション

CNTKTextFormatDeserializer オプション

ImageDeserializer オプション

Base64ImageDeserializer オプション

構成とテストの例

その他のリソース

次の方法で共有

BrainScript と Python: 読者の理解と拡張

Python でのリーダー (ミニバッチ ソース) の構成

BrainScript

デシリアライザー

変換

新しいリーダー構成の形式の説明

構成オプション

一般的な閲覧者の構成

インデックスキャッシュ

一般的なデシリアライザーの構成

一般的な変換の構成

HTKFeatureDeserializer オプション

HTKMLFDeserializer オプション

CNTKTextFormatDeserializer オプション

ImageDeserializer オプション

Base64ImageDeserializer オプション

構成とテストの例

その他のリソース

Python でのリーダー (ミニバッチソース) の構成