Load an .onnx file, train its weights with an optimizer, and save the result. OnnxModule updates weights through supported operators.
The result is .onemodel, not .onnx; this training path doesn’t support convolution, recurrent, pooling, or control-flow graphs.
dotnet add package RecursiveAI.OneModel.TrainingRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
linear.onnx comes in the example zip. It computes MatMul(x, W) with float32 W = [[1], [1]]; the sample trains on input [1, 2] with target [5]. For your own model, replace the path and use inputs and targets that match its shapes and types.
using RecursiveAI.OneModel.Tensors; using RecursiveAI.OneModel.Training; using var model = OnnxModule.Load("linear.onnx"); using var x = Tensor.FromSpan<float>([1, 2], 1, 2); using var y = Tensor.FromSpan<float>([5], 1, 1); using var sgd = new Sgd(model.Parameters(), 0.0625f); using var scope = new ActivationScope(); Losses.Mse(model.Forward(x), y).Backward(); sgd.Step(); model.Save("tuned.onemodel"); Console.WriteLine("Saved tuned.onemodel");
Unzip the example, then dotnet run.
Takes one training step and writes the updated graph in OneModel format:
Saved tuned.onemodelFull program
The program repeats the update eight times, then reloads the saved graph to predict on the same input. The printed prediction is for the training example, not a measure of how the model does on new data.
using System.Globalization; using RecursiveAI.OneModel; using RecursiveAI.OneModel.Tensors; using RecursiveAI.OneModel.Training; CultureInfo.CurrentCulture = CultureInfo.InvariantCulture; using var model = OnnxModule.Load("linear.onnx"); using var input = Tensor.FromSpan<float>([1, 2], 1, 2); using var target = Tensor.FromSpan<float>([5], 1, 1); using var optimizer = new Sgd(model.Parameters(), 0.0625f); Console.WriteLine("Trainable: " + string.Join(", ", model.NamedParameters().Select(item => item.Name))); for (int step = 0; step < 8; step++) { using var scope = new ActivationScope(); optimizer.ZeroGrad(); var prediction = model.Forward(input); if (step == 0) Console.WriteLine($"Before training: {prediction.Item<float>():F3}"); Losses.Mse(prediction, target).Backward(); optimizer.Step(); } const string path = "tuned.onemodel"; model.Save(path); using var tuned = Model.Load(path); Console.WriteLine($"After reload: {tuned.Run([1f, 2f])[0]:F3}"); Console.WriteLine($"Saved {path}");
Trainable: W Before training: 3.000 After reload: 4.999 Saved tuned.onemodel
If a node needs a gradient but has no supported training operator, OnnxModule.Load throws SessionException with kind UnsupportedOperator and lists the unsupported operators.
Variations
Train only a named weight. Replace the Load line to make only the initializer named W trainable; other float32 initializers stay frozen. The sample has only one weight tensor, so the output is unchanged.
using var model = OnnxModule.Load("linear.onnx", new OnnxModuleOptions { IsTrainable = name => name == "W" });
Related recipes
The short answer
Load the file with OnnxModule.Load, pass its trainable parameters to an optimizer, and compute a loss from Forward and your target. Call Backward and then Step to update the imported weights. Use an ActivationScope around the forward and backward pass, and zero the old gradients before each step when you train in a loop. Call Save to write the tuned graph for inference; the result is a .onemodel file, not a new .onnx file.
Can you fine-tune any ONNX model?
No. Being able to run an ONNX graph for inference doesn’t mean you can differentiate it. A node on a path from a trainable parameter needs backward support unless it’s an operation that never carries a gradient, such as Shape. The training reference lists which operators can carry gradients, including MatMul, Gemm, and Relu. It rules out convolution, recurrent, and pooling graphs for this imported-graph path. Control-flow operators such as If and Loop aren’t supported here. Imported Dropout runs as the identity, even when the module is in training mode.
An initializer is a tensor stored in the graph, often a weight. Eligible float32 initializers with more than one element become parameters by default. Single-element float32 initializers and frequency tables feeding Sin or Cos are examples of values the library keeps frozen. Half-precision and quantized weights are graph constants, not trainable parameters. Look at NamedParameters() to see what the optimizer can actually update, and keep the tensor shapes and element types declared by the model when preparing your inputs.
How do you save a fine-tuned ONNX model for inference?
OnnxModule.Save writes the current trained parameter values back into the graph and saves that graph in OneModel format. Model.Load can then open it for prediction, as the program does above. The original linear.onnx stays unchanged. If you need a new ONNX artifact for a consumer that only reads .onnx, this save method doesn’t produce one.
For inference in the same process, CreateSession uses the current weights without writing a file. That session has its own copy: if you train the module further, create a fresh session to use the newer values. To continue the same optimizer run later, keep a training checkpoint rather than relying on the inference graph to store your optimizer state.