Recursive AI

Load ONNX external weights in C#

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

Load scale.onnx from the zip. OneModel finds data/scale.weights relative to the model file.

Terminal
dotnet add package RecursiveAI.OneModel

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneModel;
 
using var model = Model.Load("scale.onnx");
float[] input = [2];
float[] output = model.Run(input, [1]);
Console.WriteLine(output[0]);

Unzip the example, then dotnet run.

The sample multiplies the input by the stored weight 3:

Text
6

The full program

scale.onnx contains one Mul node: y = x * w. This is the weight reference in the model (decoded from ONNX’s binary format):

Text
w: float32[1], data_location = EXTERNAL
location = data/scale.weights
offset = 4
length = 4

data/scale.weights contains 00 00 00 00 00 00 40 40 in hex. The model skips the first four bytes and reads the second four as a little-endian float32, 3.

C#
using RecursiveAI.OneModel;
using RecursiveAI.OneModel.Onnx;
 
const string path = "scale.onnx";
using (var model = Model.Load(path))
    Console.WriteLine($"Path: {model.Run(new float[] { 2 }, [1])[0]}");
 
var options = new ModelLoadOptions
{
    ExternalDataDirectory = Path.GetDirectoryName(Path.GetFullPath(path))!
};
using (var stream = File.OpenRead(path))
using (var model = Model.Load(stream, loadOptions: options))
    Console.WriteLine($"Stream: {model.Run(new float[] { 2 }, [1])[0]}");
 
try
{
    using var stream = File.OpenRead(path);
    using var model = Model.Load(stream);
}
catch (OnnxImportException error)
{
    Console.WriteLine($"Stream without directory: {error.Kind}");
}
Text
Path: 6
Stream: 6
Stream without directory: ExternalData

If data/scale.weights is missing, the path load throws OnnxImportException with kind ExternalData and names the missing file.

Variations

Load model bytes from memory, with weights on disk. Use the model’s folder as the base directory. If you’re running from another folder, pass the path to scale.onnx after dotnet run --.

C#
using RecursiveAI.OneModel;
 
string path = Path.GetFullPath(
    args.Length == 0 ? "scale.onnx" : args[0]);
byte[] bytes = File.ReadAllBytes(path);
var options = new ModelLoadOptions
{
    ExternalDataDirectory = Path.GetDirectoryName(path)!
};
using var model = Model.Load(bytes, loadOptions: options);
float[] input = [2];
Console.WriteLine(model.Run(input, [1])[0]);
Text
6

The short answer

If you have a local .onnx file, pass its path to Model.Load and keep each weight file where the model expects it. If you pass a stream or bytes instead, supply ModelLoadOptions.ExternalDataDirectory. This is the base directory for the relative paths in the model, not the path to a particular weight file.

What is ONNX external data?

ONNX external data lets a tensor store its values outside the .onnx file. The tensor’s name, shape, and type are still part of the model, but location points to the file with its values. Several tensors can point to different byte ranges in the same file. offset starts at zero if omitted; in OneModel, an omitted length means the expected byte count for that tensor.

A single serialized ONNX protobuf has a size limit below 2 GiB. A separate weight file can exceed that limit: OneModel checks offsets and lengths in 64 bits and addresses each tensor separately. That’s a per-file distinction, not a promise that any individual tensor fits. See OneModel’s ONNX import guide.

How do you load an ONNX model with external data from a stream?

Pick the directory that contains the weight files in their original layout. For the example, that’s the folder containing scale.onnx, not its data subfolder: the relative reference already starts with data/. Pass that directory in loadOptions when opening the stream. OneModel doesn’t infer it even if you supply a FileStream that you opened from a local path. A stream containing only the model still needs its external weights on disk.

Why can’t the loader find an ONNX weight file?

Check the model’s location against what you deployed. Copying only the .onnx file isn’t enough. If location is data/scale.weights, placing the weights beside scale.onnx or renaming the file breaks the reference. Move both files together and preserve the subdirectory. For a stream or bytes, check ExternalDataDirectory first: without it there’s no base for the lookup.

OneModel also rejects absolute locations, .. path components, and links that resolve outside the base directory. If the file exists but loading still fails, check whether the byte range fits inside the file. If the model specifies a length, it must match the tensor’s expected size. A truncated weight file can fail even when its name is correct. See the external data rules.

All onemodel recipes