Training C & C++ APIs

Training C and C++ APIs are an extension of the onnxruntime core C and C++ APIs and should be used in conjunction with them.

In order to train a model with onnxruntime, the following training artifacts must be generated:

• The training onnx model
• The checkpoint file
• The optimizer onnx model
• The eval onnx model model (optional)

These training artifacts can be generated as part of an offline step using the python utilities made available in the onnxruntime-training python package.

After these artifacts have been generated, the C and C++ utilities listed in this documentation can be leveraged to perform training.

If any problem is encountered, please create an issue with your scenario and requirements, and we will be sure to respond and follow up on the request.

Training C API

OrtTrainingApi - Training C API functions.

This C structure contains functions that enable users to perform training with onnxruntime.

Sample Code:

#include <onnxruntime_training_api.h>
 
OrtApi* g_ort_api = OrtGetApiBase()->GetApi(ORT_API_VERSION);
OrtTrainingApi* g_ort_training_api = g_ort_api->GetTrainingApi(ORT_API_VERSION);
 
OrtEnv* env = NULL;
g_ort_api->CreateEnv(logging_level, logid, &env);
OrtSessionOptions* session_options = NULL;
g_ort_api->CreateSessionOptions(&session_options);
 
OrtCheckpointState* state = NULL;
g_ort_training_api->LoadCheckpoint(path_to_checkpoint, &state);
 
OrtTrainingSession* training_session = NULL;
g_ort_training_api->CreateTrainingSession(env, session_options, training_model_path,
                                          state, eval_model_path, optimizer_model_path,
                                          &training_session);
// Training loop
{
    g_ort_training_api->TrainStep(...);
    g_ort_training_api->OptimizerStep(...);
    g_ort_training_api->LazyResetGrad(...);
}
 
g_ort_training_api->ExportModelForInferencing(training_session, inference_model_path, ...);
g_ort_training_api->SaveCheckpoint(state, path_to_checkpoint, false);
 
g_ort_training_api->ReleaseTrainingSession(training_session);
g_ort_training_api->ReleaseCheckpointState(state);

‍Note The OrtCheckpointState contains the entire training state that the OrtTrainingSession uses. As a result, the training session must always have access to the state. That is to say, the OrtCheckpointState instance must outlive the lifetime of the OrtTrainingSession instance.

Training C++ API

Ort Training C++ API - Training C++ API classes and functions.

These C++ classes and functions enable users to perform training with onnxruntime.

Sample Code:

#include <onnxruntime_training_cxx_api.h>
 
Ort::Env env;
Ort::SessionOptions session_options;
 
auto state = Ort::CheckpointState::LoadCheckpoint(path_to_checkpoint);
auto training_session = Ort::TrainingSession(env, session_options, state, training_model_path,
                                             eval_model_path, optimizer_model_path);
 
// Training Loop
{
    training_session.TrainStep(...);
    training_session.OptimizerStep(...);
    training_session.LazyResetGrad(...);
}
 
training_session->ExportModelForInferencing(inference_model_path, ...);
Ort::CheckpointState::SaveCheckpoint(state, path_to_checkpoint, false);

‍Note The Ort::CheckpointState contains the entire training state that the Ort::TrainingSession uses. As a result, the training session must always have access to the state. That is to say, the Ort::CheckpointState instance must outlive the lifetime of the Ort::TrainingSession instance.