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

Training a neural network with CNTK involves three components that must be configured:

• network: the neural network, including its structure/formula, model parameters. Training criteria and evaluation metric are also included here.
• reader: how training data is read
• SGD: the hyper-parameters of the stochastic-gradient process

You need to provide this information through a configuration file as the first argument when calling the CNTK executable. The configuration file uses a specific syntax. Please see Config file overview for details on config files.

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

The CNTK command line for this example is cntk configFile=01_OneHidden_ndl_deprecated.cntk. 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
        include "$ConfigDir$/01_OneHidden.bs"
    )

    # learner configuration       
    SGD = [
        ...
    ]

    # reader configuration   
    reader = [
        readerType = "CNTKTextFormatReader"
        file = "$DataDir$/Train-28x28_cntk_text.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.

testNetwork = {
    action = "test"
    minibatchSize = 1024    # reduce this if you run out of memory

    reader = {
        readerType = "CNTKTextFormatReader"
        file = "$DataDir$/Test-28x28_cntk_text.txt"
        input = {
            features = { dim = 784 ; format = "dense" }
            labels =   { dim = 10  ; format = "dense" }
        }
    }
}

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_ndl_deprecated.cntk to execute the testing. The result on the command line is:

Final Results: Minibatch[1-625]: errs = 2.39% * 10000; ce = 0.076812531 * 10000; Perplexity = 1.0798396
COMPLETED!

Using a trained model in your own code

Below we provide a very brief overview of how to use a trained model from C#. The section Evaluating CNTK Models (see sidebar) has many details including evaluation using C++/C#/nugget, evaluating hidden layers and evaluating multiple models.

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/Examples/Evaluation/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, which restricts evaluation to the CPU.)

Next steps

• Model Evaluation Detailed
• Examples
• Config file overview
• Command line parsing rules