CNTK usage overview

To use CNTK you need to either download the executable binaries or download the source code and compile it on your machine ([details](Setup CNTK on your machine)). There are three main tasks (or actions) that are supported by CNTK:

• Train - Define a network and train it to produce a trained model using training data
• Evaluate - Test a trained model to assess its performance using test data
• Deploy - Use a trained model, e.g. in your own solution, to classify new instances

A brief overview for each of these tasks is given below and pointers to a more detailed description are provided. In addition there other tasks that CNTK supports such as edit existing models and write node outputs to a file. A description of these is provided in the Advanced Topics section on the Top-level commands page.

Training a model using CNTK

In the following we use the CNTK configuration and results from the MNIST example, in particular the configuration '01_OneHidden.cntk' (see Image/MNIST and 01_OneHidden.cntk for full details).

To train a model using CNTK you need to provide a configuration file as the first argument when calling the CNTK executable, cntk configFile=01_OneHidden.cntk our example (see also Config file overview for more details on config files). The following snippet provides an overview of the config file contents that are relevant for training.

ModelDir = "$OutputDir$/Models"
deviceId = 0
command = MNISTtrain

modelPath = "$ModelDir$/01_OneHidden"

MNISTtrain = [
    action = "train"

    NDLNetworkBuilder = [
        networkDescription = "$ConfigDir$/01_OneHidden.ndl"
    ]
    
    SGD = [
        ...
    ]

    reader = [
        readerType = "UCIFastReader"
        file = "$DataDir$/Train-28x28.txt"
        ...
    ]    
]

The above code snippet defines a command called MNISTtrain with action = "train". Other supported actions are for example test or write. The deviceId parameter specifies whether to use CPU or GPU. When set to auto CNTK picks the best available device. Set it to -1 to use the CPU or to a value >=0 to use a specific GPU. The modelPath defines where to store the intermediate and final trained models. In this example it uses the ModelDir variable defined at the beginning of the configuration file.

The three main configuration blocks for training define the network itself and the parameters for the training algorithm and the data reader.

• Network builder - here you define the topology and the details of the network such as the size and number of layers and the type of nodes. You can use the Simple Network Builder or the NDL Network Builder. Please refer to the corresponding Wiki pages for details.
• SGD - this block lets you parameterize the training algorithm (stochastic gradient descent). Options include using momentum, adaptive learning rate, adaptive minibatch size or parallel training. See SGD block for more details.
• reader - the reader block defines which reader to use and where the corresponding input files are. CNTK provides several data readers for different formats and tasks (see Reader block).

Finally, the line command = "MNISTtrain" specifies which of the defined tasks to execute. To execute several tasks consecutively, e.g. training and evaluation, simply add more tasks to the command separated by a colon: command = "MNISTtrain:MNISTtest".

Evaluating a trained model

To evaluate a trained model you can use the 'eval' or 'test' command (see also Train, Test, Eval for full details). The corresponding configuration in the MNIST 01_OneHidden.cntk example looks as follows.

MNISTtest = [
    action = "test"
    minibatchSize = 16

    reader = [
        readerType = "UCIFastReader"
        file = "$DataDir$/Test-28x28.txt"
        ...
    ]    
]

The 'MNISTtest' block uses 'action = "test"'. For the 'test' action you need to define a model that should be used for testing using the 'modelPath' parameter. In this example the 'modelPath' is not defined inside the 'MNISTtest' block but on the top level (see training part above) and is used by both the 'train' and 'test' actions. Inside the 'reader' block you specify the data file that should be used for testing, 'Test-28x28.txt' in the example. Finally, yu have to set 'command = MNISTtest' and run to execute the testing. The result on the command line is:

Final Results: Minibatch[1-625]: Samples Seen = 10000    err: ErrorPrediction/Sample = 0.0239    ce: CrossEntropyWithSoftmax/Sample = 0.076812531    Perplexity = 1.0798396
COMPLETED

Using a trained model in your own solution

To use a trained CNTK model in your own solution you can either use the EvalDll from C++ or wrap the EvalDll to call it from other languages. An example for a .NET wrapper and a C# client is provided in Source/Extensibility/CSEvalClient. The example shows how to use the trained MNIST '01_OneHidden' model to classify an image. The following code snippet is taken from 'Program.cs' in Source/Extensibility/CSEvalClient.

...
Dictionary<string, List<float>> outputs;

using (var model = new IEvaluateModelManagedF())
{
    // Initialize model evaluator
    string config = GetConfig();
    model.Init(config);

    // Load model
    string modelFilePath = Path.Combine(Environment.CurrentDirectory, @"..\Output\Models\01_OneHidden");
    model.LoadModel(modelFilePath);

    // Generate random input values in the appropriate structure and size
    var inputs = GetDictionary("features", 28*28, 255);
                
    // We can call the evaluate method and get back the results (single layer)...
    // List<float> outputList = model.Evaluate(inputs, "ol.z", 10);

    // ... or we can preallocate the structure and pass it in (multiple output layers)
    outputs = GetDictionary("ol.z", 10, 1);
    model.Evaluate(inputs, outputs);                    
}
...

See Program.cs for full details. If you get an exception 'Cannot move externally owned matrices to the preferred device.' please specify 'deviceId=-1' in the config file.

Next steps

• Examples
• Config file overview
• Command line parsing rules