https://github.com/elbruno/elbruno.localembeddings
.NET library for local embedding generation using ONNX and Microsoft.Extensions.AI
https://github.com/elbruno/elbruno.localembeddings
cosine-similarity csharp dependency-injection dotnet embeddings huggingface kernel-memory local-ai machine-learning microsoft-extensions-ai nuget onnx onnx-runtime rag semantic-search text-embeddings vector-embeddings
Last synced: 25 days ago
JSON representation
.NET library for local embedding generation using ONNX and Microsoft.Extensions.AI
- Host: GitHub
- URL: https://github.com/elbruno/elbruno.localembeddings
- Owner: elbruno
- License: mit
- Created: 2026-02-12T20:46:25.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-04T14:18:54.000Z (about 2 months ago)
- Last Synced: 2026-04-04T17:06:56.874Z (about 2 months ago)
- Topics: cosine-similarity, csharp, dependency-injection, dotnet, embeddings, huggingface, kernel-memory, local-ai, machine-learning, microsoft-extensions-ai, nuget, onnx, onnx-runtime, rag, semantic-search, text-embeddings, vector-embeddings
- Language: C#
- Size: 58.8 MB
- Stars: 23
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- License: LICENSE
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# LocalEmbeddings
[](https://www.nuget.org/packages/ElBruno.LocalEmbeddings)
[](https://www.nuget.org/packages/ElBruno.LocalEmbeddings)
[](https://github.com/elbruno/elbruno.localembeddings/actions/workflows/publish.yml)
[](LICENSE)
[](https://github.com/elbruno/elbruno.localembeddings)
[](https://twitter.com/elbruno)
A .NET library for generating text embeddings locally using ONNX Runtime and Microsoft.Extensions.AI abstractions โ no external API calls required.
## ๐ฅ Quick Overview
New to local embeddings? Watch this **[5-minute video](https://www.youtube.com/watch?v=0rRgSQWlVm8)** explaining the main goal of the library.
Want to build RAG applications? Read this **[blog post about 3 RAG approaches in .NET](https://elbruno.com/2026/02/14/%f0%9f%a4%96-building-rag-in-net-with-local-embeddings-3-approaches-zero-cloud-calls/)** with local embeddings and zero cloud calls.
Interested in **image embeddings**? Check out the **[YouTube video](https://www.youtube.com/watch?v=nVTropZJC88)** and **[blog post](https://elbruno.com/2026/02/16/%f0%9f%96%bc%ef%b8%8f-local-image-embeddings-in-net-clip-onnx/)** about local image embeddings with CLIP and ONNX.
## Features
- **Local Embedding Generation** โ Run inference entirely on your machine using ONNX Runtime
- **Microsoft.Extensions.AI Integration** โ Implements `IEmbeddingGenerator>`
- **๐ฆ
Harrier model support** โ Microsoft Harrier-OSS-v1 (270M, 640-dim, 94+ languages, instruction-tuned) via `ElBruno.LocalEmbeddings.Harrier`
- **Kernel Memory Integration** โ Companion package `ElBruno.LocalEmbeddings.KernelMemory` provides a native `ITextEmbeddingGenerator` adapter for [Microsoft Kernel Memory](https://github.com/microsoft/kernel-memory)
- **VectorData Integration** โ Companion package `ElBruno.LocalEmbeddings.VectorData` adds DI helpers for `Microsoft.Extensions.VectorData` (`VectorStore` and typed collections)
- **Built-in In-Memory Vector Store** โ `ElBruno.LocalEmbeddings.VectorData` includes `InMemoryVectorStore` (no Semantic Kernel connector dependency required)
- **HuggingFace Model Support** โ Use popular sentence transformer models from HuggingFace Hub
- **Automatic Model Caching** โ Models are downloaded once and cached locally
- **Dependency Injection Support** โ First-class `IServiceCollection` integration
- **Single-String Convenience API** โ `GenerateAsync("text")` and `GenerateEmbeddingAsync("text")` โ no array wrapping needed
- **Similarity Helpers** โ Cosine similarity, all-pairs `Similarity(...)` matrix, and one-line `FindClosestAsync(...)` semantic search
- **Thread-Safe & Batched** โ Concurrent generation and efficient multi-text processing
## ๐ฆ NuGet Packages
| Package | Version | Downloads | Description |
|---------|---------|-----------|-------------|
| [ElBruno.LocalEmbeddings](https://www.nuget.org/packages/ElBruno.LocalEmbeddings) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings) | Core library โ ONNX Runtime + Microsoft.Extensions.AI |
| [ElBruno.LocalEmbeddings.Harrier](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Harrier) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Harrier) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Harrier) | Microsoft Harrier-OSS-v1 (270M, 640-dim, 94+ languages) |
| [ElBruno.LocalEmbeddings.ImageEmbeddings](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.ImageEmbeddings) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.ImageEmbeddings) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.ImageEmbeddings) | CLIP-based image embeddings for multimodal search |
| [ElBruno.LocalEmbeddings.ImageEmbeddings.Downloader](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.ImageEmbeddings.Downloader) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.ImageEmbeddings.Downloader) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.ImageEmbeddings.Downloader) | Model downloader for image embeddings |
| [ElBruno.LocalEmbeddings.KernelMemory](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.KernelMemory) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.KernelMemory) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.KernelMemory) | Microsoft Kernel Memory adapter |
| [ElBruno.LocalEmbeddings.VectorData](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.VectorData) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.VectorData) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.VectorData) | Microsoft.Extensions.VectorData + InMemoryVectorStore |
| [ElBruno.LocalEmbeddings.Npu](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu) | NPU-accelerated embeddings via DirectML |
| [ElBruno.LocalEmbeddings.Npu.Intel](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu.Intel) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu.Intel) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu.Intel) | Intel Core Ultra NPU via OpenVINO |
| [ElBruno.LocalEmbeddings.Npu.Qualcomm](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu.Qualcomm) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu.Qualcomm) | [](https://www.nuget.org/packages/ElBruno.LocalEmbeddings.Npu.Qualcomm) | Qualcomm Snapdragon X NPU via QNN |
## Installation
```bash
dotnet add package ElBruno.LocalEmbeddings
```
For **Harrier model support**, install the companion package:
```bash
dotnet add package ElBruno.LocalEmbeddings.Harrier
```
For **Kernel Memory** integration, also install:
```bash
dotnet add package ElBruno.LocalEmbeddings.KernelMemory
```
For **VectorData** integration, install:
```bash
dotnet add package ElBruno.LocalEmbeddings.VectorData
```
## Quick Start
### 1) Generate one embedding
```csharp
using ElBruno.LocalEmbeddings;
await using var generator = await LocalEmbeddingGenerator.CreateAsync();
var embedding = await generator.GenerateEmbeddingAsync("Hello, world!");
Console.WriteLine(embedding.Vector.Length); // 384
```
### 2) Generate embeddings for multiple texts
```csharp
var inputs = new[] { "first text", "second text", "third text" };
var embeddings = await generator.GenerateAsync(inputs);
Console.WriteLine(embeddings.Count); // 3
```
### 3) Compare two texts with cosine similarity
```csharp
using ElBruno.LocalEmbeddings.Extensions;
var pair = await generator.GenerateAsync(["I love coding", "I enjoy programming"]);
var score = pair[0].CosineSimilarity(pair[1]);
Console.WriteLine(score);
```
### 4) Semantic search in one line
```csharp
var corpus = new[]
{
"Python for data science",
"JavaScript for web apps",
"Swift for iOS development"
};
var corpusEmbeddings = await generator.GenerateAsync(corpus);
var results = await generator.FindClosestAsync(
"best language for websites",
corpus,
corpusEmbeddings,
topK: 2,
minScore: 0.2f);
foreach (var result in results)
Console.WriteLine($"{result.Score:F3} - {result.Text}");
```
### 5) Using Harrier model (higher quality, multilingual)
```csharp
using ElBruno.LocalEmbeddings.Harrier;
var generator = await HarrierEmbeddingGenerator.CreateAsync();
var embedding = await generator.GenerateEmbeddingAsync("Hello, world!");
Console.WriteLine($"Dimensions: {embedding.Vector.Length}"); // 640
```
For custom models and runtime behavior, use the options-based constructor:
`new LocalEmbeddingGenerator(new LocalEmbeddingsOptions { ... })`.
> **Note:** The synchronous constructor remains available for backward compatibility, but performs blocking initialization when downloads are needed.
Want to go further? Read the [Getting Started guide](docs/getting-started.md) and the other docs in this repo for DI, configuration, VectorData, Kernel Memory, and full RAG examples.
Prefer a containerized dev environment? See the Dev Container section in the [Contributing guide](docs/contributing.md#dev-container-vs-code).
## Samples
All sample applications are located in `src/Samples/`. See the [samples README](src/Samples/README.md) for prerequisites and run instructions.
| Sample | What It Shows |
| ------ | ------------- |
| [HelloWorldAltModel](src/Samples/HelloWorldAltModel) | Minimal hello world with `sentence-transformers/all-MiniLM-L12-v2` |
| [ConsoleApp](src/Samples/ConsoleApp) | All the basics: single/batch embeddings, similarity, semantic search, DI |
| [HarrierConsoleApp](src/Samples/HarrierConsoleApp) | Harrier embedding model usage and similarity search |
| [RagChat](src/Samples/RagChat) | Embedding-only semantic search Q&A using shared VectorData `InMemoryVectorStore` (no LLM needed) |
| [RagOllama](src/Samples/RagOllama) | Full RAG with Ollama + phi4-mini + Kernel Memory |
| [RagFoundryLocal](src/Samples/RagFoundryLocal) | Full RAG with Foundry Local + phi4-mini |
| [ImageRagSimple](src/Samples/ImageRagSimple) | Minimal image RAG: index images โ search by text |
| [ImageRagChat](src/Samples/ImageRagChat) | Interactive image RAG chat with text and image-to-image search |
## Configuration
```csharp
var options = new LocalEmbeddingsOptions
{
ModelName = "sentence-transformers/all-MiniLM-L6-v2", // HuggingFace model
MaxSequenceLength = 512, // Max tokens
CacheDirectory = null, // Auto-detect per platform
EnsureModelDownloaded = true, // Download if missing
NormalizeEmbeddings = false // L2 normalize vectors
};
```
See [Configuration docs](docs/configuration.md) for supported models, local model paths, and cache locations.
### Common model options (with model cards)
Estimated download sizes below are approximate and can vary by ONNX variant (fp32/int8) and tokenizer assets.
- [`sentence-transformers/all-MiniLM-L6-v2` (default, ~90โ100 MB)](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
- [`sentence-transformers/all-MiniLM-L12-v2` (~130โ140 MB)](https://huggingface.co/sentence-transformers/all-MiniLM-L12-v2)
- [`sentence-transformers/paraphrase-MiniLM-L6-v2` (~90โ100 MB)](https://huggingface.co/sentence-transformers/paraphrase-MiniLM-L6-v2)
- [`BAAI/bge-large-en-v1.5` (large, ~1.3 GB)](https://huggingface.co/BAAI/bge-large-en-v1.5)
- [`intfloat/e5-large-v2` (large, ~1.3 GB)](https://huggingface.co/intfloat/e5-large-v2)
## Documentation
| Topic | Description |
| ----- | ----------- |
| [Getting Started](docs/getting-started.md) | Step-by-step guide from hello world to RAG |
| [API Reference](docs/api-reference.md) | Classes, methods, and extension methods |
| [Configuration](docs/configuration.md) | Options, supported models, cache locations |
| [Alternative Models](docs/alternative-models.md) | Non-default free models, local download workflow, and license notes |
| [Dependency Injection](docs/dependency-injection.md) | All DI overloads and `IConfiguration` binding |
| [Harrier Integration](docs/harrier-integration.md) | Microsoft Harrier-OSS-v1 local embedding model |
| [Kernel Memory Integration](docs/kernel-memory-integration.md) | Using local embeddings with Microsoft Kernel Memory |
| [VectorData Integration](docs/vector-data-integration.md) | Using local embeddings with Microsoft.Extensions.VectorData abstractions |
| [Contributing](docs/contributing.md) | Build from source, repo structure, guidelines |
| [Roadmap](docs/plans/roadmap_260213_0803.md) | Planned and completed features/samples with priorities |
| [Publishing](docs/publishing.md) | NuGet publishing with GitHub Actions + Trusted Publishing |
| [Changelog](docs/changelog.md) | Versioned summary of notable changes |
Have an idea for a new feature or sample? Please open an issue and share your suggestion.
## Building from Source
```bash
git clone https://github.com/elbruno/elbruno.localembeddings.git
cd elbruno.localembeddings
dotnet build
dotnet test
```
## Requirements
- .NET 10.0 SDK or later
- ONNX Runtime compatible platform (Windows, Linux, macOS)
## ๐ About the Author
Hi! I'm **ElBruno** ๐งก, a passionate developer and content creator exploring AI, .NET, and modern development practices.
**Made with โค๏ธ by [ElBruno](https://github.com/elbruno)**
If you like this project, consider following my work across platforms:
- ๐ป **Podcast**: [No Tienen Nombre](https://notienenombre.com) โ Spanish-language episodes on AI, development, and tech culture
- ๐ป **Blog**: [ElBruno.com](https://elbruno.com) โ Deep dives on embeddings, RAG, .NET, and local AI
- ๐บ **YouTube**: [youtube.com/elbruno](https://www.youtube.com/elbruno) โ Demos, tutorials, and live coding
- ๐ **LinkedIn**: [@elbruno](https://www.linkedin.com/in/elbruno/) โ Professional updates and insights
- ๐ **Twitter**: [@elbruno](https://www.x.com/in/elbruno/) โ Quick tips, releases, and tech news
## License
This project is licensed under the MIT License โ see the [LICENSE](LICENSE) file for details.