OnnxEmbeddingModel class

ONNX Runtime-backed embedding model for dense text retrieval.

Implements EmbeddingModel using a model from ModelCatalog via the betto_onnxrt OnnxRuntime and OnnxSession API. Produces L2-normalised float32 embeddings suitable for cosine similarity search.

Model identity

modelId returns the stable ModelSpec.id of the loaded model (e.g. bge-small-en-v1.5). This should be persisted alongside the vector index so that a model change can be detected and the index rebuilt.

Loading with download-on-demand (preferred)

Supply a cacheDir (and optionally a ModelSpec via spec) to fetch the model on first use via ModelDownloader. If the model files are already cached and their SHA-256 checksums match, they are used immediately. Otherwise ModelDownloader fetches the files before opening the ORT session:

final spec = ModelCatalog.lookup('bge-small-en-v1.5');
final model = await OnnxEmbeddingModel.load(
  spec: spec,
  cacheDir: '/path/to/cache',
  onProgress: (received, total) {
    stderr.writeln('Downloading: $received / $total bytes');
  },
);

Loading from an explicit path

The modelPath parameter loads a model from a specific filesystem path, bypassing the catalog and downloader. Specifying modelPath without spec uses ModelCatalog.defaultModelId for the identity.

final model = await OnnxEmbeddingModel.load(
  modelPath: '/path/to/bge_small.onnx',
);

Important: Either modelPath or cacheDir must be supplied. Calling load without either throws ArgumentError synchronously — there is no bundled model asset path. See ModelCatalog and ModelDownloader.

Lifecycle

load opens the native ORT session via OnnxRuntime.load. embed runs synchronously on the calling isolate — do not call from the UI thread in Flutter without isolate offloading. dispose releases native resources; always call it (use try/finally).

Thread safety

ORT sessions are thread-affine. All embed and dispose calls must come from the same isolate that called load.