---
title: "Fine-tune an ONNX model on the CPU in C#"
url: https://recursiveai.org/onemodel/cookbook/fine-tune-imported-onnx-model-on-cpu/
description: "Load a small ONNX graph, train its float32 weights locally on the CPU, and save the tuned model for inference with a runnable C# example."
version: "1.3.0"
---

# Fine-tune an ONNX model on the CPU in C#

**OneModel** is a free, open-source neural-network library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneModel.Training) · [GitHub](https://github.com/recursive-ai-oss/onemodel-csharp) · [Docs](https://recursiveai.org/onemodel/docs/) · [Download example (.zip)](https://recursiveai.org/onemodel/cookbook/fine-tune-imported-onnx-model-on-cpu/fine-tune-imported-onnx-model-on-cpu.zip)

Load an `.onnx` file, train its weights with an optimizer, and save the result. `OnnxModule` updates weights through [supported operators](https://recursiveai.org/onemodel/docs/training/#11-training-an-imported-graph-onnxmodule).

The result is `.onemodel`, not `.onnx`; this training path doesn’t support convolution, recurrent, pooling, or control-flow graphs.

```shell
dotnet add package RecursiveAI.OneModel.Training
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (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.

```csharp
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](https://recursiveai.org/onemodel/cookbook/fine-tune-imported-onnx-model-on-cpu/fine-tune-imported-onnx-model-on-cpu.zip), then `dotnet run`.

Takes one training step and writes the updated graph in OneModel format:

```text
Saved tuned.onemodel
```

## Full 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.

```csharp
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}");
```

```text
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.

```csharp
using var model = OnnxModule.Load("linear.onnx",
    new OnnxModuleOptions { IsTrainable = name => name == "W" });
```

## Related recipes

- [Train a neural network](https://recursiveai.org/onemodel/cookbook/train-a-model/)
- [Freeze model parameters during training](https://recursiveai.org/onemodel/cookbook/freeze-model-parameters-during-training/)
- [Run an ONNX model in C#](https://recursiveai.org/onemodel/cookbook/run-onnx-model/)

## 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](https://recursiveai.org/onemodel/docs/training/#11-training-an-imported-graph-onnxmodule) 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](https://recursiveai.org/onemodel/cookbook/resume-training-from-checkpoint/) rather than relying on the inference graph to store your optimizer state.
