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 are 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 in a specific syntax, e.g. cntk configFile=01_OneHidden.cntk in our example. Please see 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"

    # network definition   
    BrainScriptNetworkBuilder = (new ComputationNetwork
        networkDescription = "$ConfigDir$/01_OneHidden.ndl"
    )

    # learner configuration       
    SGD = [
        ...
    ]

    # reader configuration   
    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 will pick 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 for standard models or the BrainScript Network Builder for custom ones. Please refer to the corresponding Wiki pages for details.
• SGD - this block lets you parameterize the training algorithm (stochastic gradient descent). Configurable options include momentum, adaptive learning rate, adaptive minibatch size, 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's accuracy, you 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, you have to set command = MNISTtest and run cntk configFile=01_OneHidden.cntk to execute the testing. The result on the command line is:

Final Results: Minibatch[1-625]: err = 0.0239 * 10000    ce = 0.076812531 * 10000    Perplexity = 1.0798396
COMPLETED!

Using a trained model in your own code

A trained CNTK model can be used in your own code from C++ and C#. From C++, use the EvalDll (it has the same name under Windows and Linux), which is demonstrated in the example CPPEvalClient. From C#, use the EvalWrapper, cf. CSEvalClient. You can also wrap the EvalDll to call it from other languages.

The following example shows how to use the trained MNIST 01_OneHidden model to classify an image in C#. The following code snippet is taken from Program.cs in Source/Extensibility/CSEvalClient.

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

using (var model = new IEvaluateModelManagedF())
{
    // Create network based on a trained model (for CPU evaluation)
    string modelFilePath = Path.Combine(Environment.CurrentDirectory, @"..\Output\Models\01_OneHidden");
    string config = string.Format(modelPath=\"{0}\"", modelFilePath);
    model.CreateNetwork(config, deviceId: -1);

    // 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");

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

(Note: If this example fails with an exception Cannot move externally owned matrices to the preferred device. then please specify deviceId=-1 in the config file.)

TODO/REVIEW: Verify this comment. Is this still needed? Shouldn't we then also say that this restricts you to the CPU?

Next steps

• Examples
• Config file overview
• Command line parsing rules