elbruno.LocalEmbeddings 1.0.2

LocalEmbeddings

A .NET library for generating text embeddings locally using ONNX Runtime and Microsoft.Extensions.AI abstractions—no external API calls required.

Features

• Local Embedding Generation - Run inference entirely on your machine using ONNX Runtime
• Microsoft.Extensions.AI Integration - Implements IEmbeddingGenerator<string, Embedding<float>> for seamless ecosystem compatibility
• HuggingFace Model Support - Use popular sentence transformer models from HuggingFace Hub
• Automatic Model Caching - Models are downloaded once and cached locally for fast subsequent loads
• Dependency Injection Support - First-class integration with IServiceCollection and the Options pattern
• Thread-Safe - Concurrent embedding generation from multiple threads
• Batched Inference - Efficient processing of multiple texts in a single call

Installation

dotnet add package elbruno.LocalEmbeddings

Or via the NuGet Package Manager:

Install-Package elbruno.LocalEmbeddings

Quick Start

Direct Usage

using LocalEmbeddings;
using LocalEmbeddings.Options;

// Create the generator with default settings
var generator = new LocalEmbeddingGenerator(new LocalEmbeddingsOptions());

// Generate a single embedding
var result = await generator.GenerateAsync(["Hello, world!"]);
float[] embedding = result[0].Vector.ToArray();

// Generate multiple embeddings (batched)
var texts = new[] { "First document", "Second document", "Third document" };
var embeddings = await generator.GenerateAsync(texts);

// Don't forget to dispose when done
generator.Dispose();

With Custom Model

var options = new LocalEmbeddingsOptions
{
    ModelName = "sentence-transformers/all-MiniLM-L6-v2",
    MaxSequenceLength = 256
};

using var generator = new LocalEmbeddingGenerator(options);
var embeddings = await generator.GenerateAsync(["Your text here"]);

Configuration Options

The LocalEmbeddingsOptions class provides the following configuration:

var options = new LocalEmbeddingsOptions
{
    ModelName = "sentence-transformers/all-MiniLM-L6-v2",
    CacheDirectory = @"C:\models\cache",
    MaxSequenceLength = 256,
    EnsureModelDownloaded = true
};

Dependency Injection

LocalEmbeddings provides multiple overloads of AddLocalEmbeddings() for flexible DI registration:

Basic Registration

using LocalEmbeddings.Extensions;

services.AddLocalEmbeddings();

With Configuration Action

services.AddLocalEmbeddings(options =>
{
    options.ModelName = "sentence-transformers/all-MiniLM-L6-v2";
    options.MaxSequenceLength = 256;
});

With Model Name Only

services.AddLocalEmbeddings("sentence-transformers/all-MiniLM-L6-v2");

With Pre-configured Options

var options = new LocalEmbeddingsOptions
{
    ModelName = "sentence-transformers/all-MiniLM-L6-v2",
    MaxSequenceLength = 256
};
services.AddLocalEmbeddings(options);

From Configuration (appsettings.json)

{
  "LocalEmbeddings": {
    "ModelName": "sentence-transformers/all-MiniLM-L6-v2",
    "MaxSequenceLength": 256,
    "CacheDirectory": "/path/to/cache"
  }
}

services.AddLocalEmbeddings(configuration.GetSection("LocalEmbeddings"));

Injecting the Generator

public class MyService
{
    private readonly IEmbeddingGenerator<string, Embedding<float>> _embeddings;

    public MyService(IEmbeddingGenerator<string, Embedding<float>> embeddings)
    {
        _embeddings = embeddings;
    }

    public async Task<float[]> GetEmbeddingAsync(string text)
    {
        var result = await _embeddings.GenerateAsync([text]);
        return result[0].Vector.ToArray();
    }
}

Supported Models

Default Model

The default model is sentence-transformers/all-MiniLM-L6-v2, which produces 384-dimensional embeddings. It offers an excellent balance of quality and performance.

Custom ONNX Models

You can use any HuggingFace sentence transformer model that has ONNX exports:

// Use a different HuggingFace model
var options = new LocalEmbeddingsOptions
{
    ModelName = "sentence-transformers/paraphrase-MiniLM-L6-v2"
};

Local Model Path

For offline scenarios or custom models, specify a local directory:

var options = new LocalEmbeddingsOptions
{
    ModelPath = @"C:\models\my-custom-model",
    EnsureModelDownloaded = false
};

The model directory must contain:

• model.onnx - The ONNX model file
• tokenizer.json or vocab.txt - Tokenizer files

Cache Locations

Models are automatically cached in platform-specific locations:

Override with the CacheDirectory option:

var options = new LocalEmbeddingsOptions
{
    CacheDirectory = "/custom/cache/path"
};

API Reference

LocalEmbeddingGenerator

The main class for generating embeddings. Implements IEmbeddingGenerator<string, Embedding<float>>.

public sealed class LocalEmbeddingGenerator : IEmbeddingGenerator<string, Embedding<float>>
{
    // Constructor
    public LocalEmbeddingGenerator(LocalEmbeddingsOptions options);
    
    // Properties
    public EmbeddingGeneratorMetadata Metadata { get; }
    
    // Methods
    public Task<GeneratedEmbeddings<Embedding<float>>> GenerateAsync(
        IEnumerable<string> values,
        EmbeddingGenerationOptions? options = null,
        CancellationToken cancellationToken = default);
    
    public TService? GetService<TService>(object? key = null) where TService : class;
    
    public void Dispose();
}

LocalEmbeddingsOptions

Configuration options for the embedding generator.

public sealed class LocalEmbeddingsOptions
{
    public string ModelName { get; set; }
    public string? ModelPath { get; set; }
    public string? CacheDirectory { get; set; }
    public int MaxSequenceLength { get; set; }
    public bool EnsureModelDownloaded { get; set; }
}

ServiceCollectionExtensions

Extension methods for DI registration in LocalEmbeddings.Extensions namespace.

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddLocalEmbeddings(
        this IServiceCollection services,
        Action<LocalEmbeddingsOptions>? configure = null);
    
    public static IServiceCollection AddLocalEmbeddings(
        this IServiceCollection services,
        LocalEmbeddingsOptions options);
    
    public static IServiceCollection AddLocalEmbeddings(
        this IServiceCollection services,
        string modelName);
    
    public static IServiceCollection AddLocalEmbeddings(
        this IServiceCollection services,
        IConfiguration configuration);
}

Building from Source

Prerequisites

• .NET 10.0 SDK or later
• Git

Build

git clone https://github.com/elbruno/elbruno.localembeddings.git
cd elbruno.localembeddings
dotnet build

Run Tests

dotnet test

Requirements

• .NET 10.0 or later
• ONNX Runtime compatible platform (Windows, Linux, macOS)

License

This project is licensed under the MIT License - see the LICENSE file for details.