LocalEmbedder 0.3.1

LocalEmbedder

A simple, high-performance .NET library for local text embeddings with automatic model downloading from HuggingFace.

await using var model = await LocalEmbedder.LoadAsync("all-MiniLM-L6-v2");
var embedding = await model.EmbedAsync("Hello, world!");

Features

• Zero Configuration - Just specify a model name, auto-downloads from HuggingFace
• High Performance - SIMD-optimized operations with TensorPrimitives
• Minimal Dependencies - Only ONNX Runtime and System.Numerics.Tensors
• GPU Acceleration - CUDA, DirectML, CoreML support
• Pre-configured Models - Popular embedding models ready to use
• Resume Downloads - Automatically resumes interrupted downloads

Installation

dotnet add package LocalEmbedder

Quick Start

using LocalEmbedder;

// Load a model (auto-downloads if not cached)
await using var model = await LocalEmbedder.LoadAsync("all-MiniLM-L6-v2");

// Generate embedding
float[] embedding = await model.EmbedAsync("Your text here");

// Batch processing
float[][] embeddings = await model.EmbedAsync([
    "First sentence",
    "Second sentence",
    "Third sentence"
]);

Note: Both await using (recommended) and using patterns are supported for resource disposal.

Available Models

// List all available models
foreach (var modelId in LocalEmbedder.GetAvailableModels())
{
    Console.WriteLine(modelId);
}

Configuration

var model = await LocalEmbedder.LoadAsync("all-MiniLM-L6-v2", new EmbedderOptions
{
    CacheDirectory = "./models",           // Model cache location
    MaxSequenceLength = 512,               // Max tokens
    NormalizeEmbeddings = true,            // L2 normalization
    Provider = ExecutionProvider.Auto      // Auto-select best (default)
});

Execution Providers

ExecutionProvider.Auto      // Default - automatically selects best available
ExecutionProvider.Cpu       // CPU only
ExecutionProvider.Cuda      // NVIDIA GPU
ExecutionProvider.DirectML  // Windows GPU (AMD, Intel, NVIDIA)
ExecutionProvider.CoreML    // Apple Silicon

The default Auto provider automatically selects:

1. CUDA if NVIDIA GPU is available (highest performance)
2. DirectML on Windows or CoreML on macOS if supported
3. CPU as fallback (always available)

Advanced Usage

Custom HuggingFace Model

// Load any ONNX model from HuggingFace
var model = await LocalEmbedder.LoadAsync("intfloat/multilingual-e5-large");

Local Model File

// Load from local path
var model = await LocalEmbedder.LoadAsync("/path/to/model.onnx");

Dependency Injection

// Register as singleton
services.AddSingleton<IEmbeddingModel>(sp =>
    LocalEmbedder.LoadAsync("all-MiniLM-L6-v2").GetAwaiter().GetResult());

// Or use factory
services.AddSingleton<IEmbedderFactory, EmbedderFactory>();

Similarity Search

using var model = await LocalEmbedder.LoadAsync("all-MiniLM-L6-v2");

var query = await model.EmbedAsync("What is machine learning?");
var documents = await model.EmbedAsync([
    "Machine learning is a subset of AI",
    "The weather is nice today",
    "Deep learning uses neural networks"
]);

// Find most similar
var similarities = documents.Select(doc => 
    LocalEmbedder.CosineSimilarity(query, doc));

API Reference

IEmbeddingModel

public interface IEmbeddingModel : IDisposable
{
    string ModelId { get; }
    int Dimensions { get; }
    
    ValueTask<float[]> EmbedAsync(string text, CancellationToken ct = default);
    ValueTask<float[][]> EmbedAsync(IReadOnlyList<string> texts, CancellationToken ct = default);
}

Utility Methods

// Cosine similarity between two vectors
float similarity = LocalEmbedder.CosineSimilarity(vec1, vec2);

// Euclidean distance
float distance = LocalEmbedder.EuclideanDistance(vec1, vec2);

// Dot product
float dot = LocalEmbedder.DotProduct(vec1, vec2);

Performance Tips

1. Reuse model instances - Loading is expensive, embed calls are cheap
2. Batch your requests - EmbedAsync(string[]) is more efficient than multiple single calls
3. Use GPU - Significant speedup for large batches
4. Choose the right model - Smaller models (MiniLM) are much faster than large ones (E5-large)

Requirements

• .NET 10.0 or later
• ONNX Runtime native libraries (included via NuGet)

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.