Implementation:Microsoft Onnxruntime CheckpointProperty
| Knowledge Sources | |
|---|---|
| Domains | Training, API, Checkpoint |
| Last Updated | 2026-02-10 04:00 GMT |
Overview
Defines the PropertyBag class for storing user-defined scalar properties (int64_t, float, or string) within training checkpoint states.
Description
The `CheckpointProperty` header provides the `PropertyBag` struct, a type-safe dictionary for user-defined training properties. It uses a `std::variant<int64_t, float, std::string>` as the value type (`PropertyDataType`) and stores entries in an `InlinedHashMap`. The class supports adding, retrieving (with type checking via `std::get_if`), querying existence, and iterating over properties. A template specialization of `GetProperty<PropertyDataType>` returns the raw variant without type extraction. This is used by `CheckpointState` to persist metadata like epoch number, best validation score, or custom training flags alongside model and optimizer states.
Usage
Use this header when you need to attach custom metadata to a training checkpoint, such as the current epoch, learning rate schedules, or any scalar training metric that should survive checkpoint save/load cycles.
Code Reference
Source Location
- Repository: Microsoft_Onnxruntime
- File: orttraining/orttraining/training_api/checkpoint_property.h
- Lines: 1-71
Signature
using PropertyDataType = std::variant<int64_t, float, std::string>;
struct PropertyBag {
PropertyBag() = default;
void AddProperty(const std::string& name, const PropertyDataType& val);
template <typename T>
T GetProperty(const std::string& name) const;
auto begin() const;
auto end() const;
size_t size() const;
bool HasProperty(const std::string& property_name) const;
};
template <>
inline PropertyDataType PropertyBag::GetProperty<PropertyDataType>(const std::string& name) const;
Import
#include "orttraining/training_api/checkpoint_property.h"
I/O Contract
| Method | Input | Output | Description |
|---|---|---|---|
| AddProperty | name (string), val (PropertyDataType) | void | Inserts or updates a named property |
| GetProperty<T> | name (string) | T | Retrieves a property value with type-safe extraction; throws on missing or type mismatch |
| HasProperty | property_name (string) | bool | Checks whether a property exists by name |
| size | (none) | size_t | Returns the number of stored properties |
| begin / end | (none) | iterator | Enables range-based iteration over the property map |
Usage Examples
#include "orttraining/training_api/checkpoint_property.h"
using namespace onnxruntime::training::api;
PropertyBag bag;
bag.AddProperty("epoch", PropertyDataType(int64_t(10)));
bag.AddProperty("best_score", PropertyDataType(0.95f));
bag.AddProperty("run_name", PropertyDataType(std::string("experiment_1")));
int64_t epoch = bag.GetProperty<int64_t>("epoch"); // 10
float score = bag.GetProperty<float>("best_score"); // 0.95
bool has_lr = bag.HasProperty("learning_rate"); // false