# Semantic Search in C#: Match Text by Meaning in Five Lines

> Add semantic search to your C# app in 5 lines. Match text by meaning, not keywords. One NuGet package with zero dependencies, running on CPU in your own process.

Source: https://kjarni.ai/blog/semanticsearch/ (published 2026-02-11)

Add semantic search to your C# app in 5 lines of code. One NuGet package, running on CPU inside your process.

Search for "how to change my login credentials" and semantic search returns "How do I reset my password?", because the meaning matches even though the words don't.

```bash
dotnet add package Kjarni
```
[NuGet](https://www.nuget.org/packages/Kjarni)
```C#
using Kjarni;

using var embedder = new Embedder("minilm-l6-v2");
Console.WriteLine(embedder.Similarity("doctor", "physician")); // 0.8598
Console.WriteLine(embedder.Similarity("doctor", "banana"));    // 0.3379
```

The model runs locally on CPU. No external services, no API costs, no data leaving your machine.

## How Semantic Search Works

The core idea: convert text into numbers that capture meaning.

A sentence embedding model reads text and outputs a vector, an array of
floating-point numbers, typically 384 or 768 dimensions. Texts with similar
meaning produce vectors that are close together. Texts with different meaning
produce vectors that are far apart.

```
"doctor"    -> [0.12, -0.34, 0.56, 0.78, ...]  (384 numbers)
"physician" -> [0.11, -0.33, 0.55, 0.79, ...]  (384 numbers)  <- close
"banana"    -> [-0.45, 0.23, -0.12, 0.01, ...]  (384 numbers)  <- far
```

You measure the distance between vectors using **cosine similarity**.
The score ranges from -1 (opposite) to 1 (identical).

## Encoding Text

```C#
using var embedder = new Embedder("minilm-l6-v2");
float[] vector = embedder.Encode("Hello world");
Console.WriteLine(vector.Length);                          // 384
Console.WriteLine(string.Join(", ", vector[..5]));
// -0.03447726, 0.031023178, 0.0067349467, 0.026109012, -0.039362032
```

The model downloads on first use (~90MB) and caches locally.
Every call to `Encode()` runs the full transformer: tokenization,
attention layers, mean pooling, normalization. The output is a
unit-length vector ready for cosine similarity.

These are the same vectors you'd get from Python's `sentence-transformers`:

```python
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2')
vector = model.encode("Hello world", normalize_embeddings=True)
# [-0.03447726  0.03102319  0.00673499  0.02610895 -0.03936201]
```

Same model, same weights, same output, without the 6.8GB Python dependency.

## Measuring Similarity

Cosine similarity tells you how close two vectors are:

```C#
using var embedder = new Embedder("minilm-l6-v2");

var pairs = new[] {
    ("doctor", "physician"),
    ("doctor", "hospital"),
    ("doctor", "banana"),
    ("cat", "dog"),
    ("cat", "car"),
    ("machine learning", "artificial intelligence"),
    ("machine learning", "potato soup"),
};

foreach (var (a, b) in pairs)
    Console.WriteLine($"  {embedder.Similarity(a, b):F4}  \"{a}\" / \"{b}\"");
```

```
  0.8598  "doctor" / "physician"
  0.5971  "doctor" / "hospital"
  0.3379  "doctor" / "banana"
  0.6606  "cat" / "dog"
  0.4633  "cat" / "car"
  0.7035  "machine learning" / "artificial intelligence"
  0.1848  "machine learning" / "potato soup"
```

The scores match intuition. "Doctor" and "physician" are near-synonyms (0.86).
"Cat" and "dog" are related but different (0.66). "Machine learning" and
"potato soup" have almost nothing in common (0.18).

Under the hood, `Similarity()` calls `Encode()` on both inputs and then
computes the dot product of the normalized vectors. If you're comparing
one query against many documents, it's more efficient to encode them
separately:

```C#
float similarity = Embedder.CosineSimilarity(vectorA, vectorB);
```

## Building a Search

Encode your documents once. Encode the query at search time.
Rank by cosine similarity.

```C#
using var embedder = new Embedder("minilm-l6-v2");

var docs = new[] {
    "How do I reset my password?",
    "What is your refund policy?",
    "Do you ship internationally?",
    "How do I update my billing address?",
    "Where can I track my order?",
};

// Encode all documents (do this once, store the vectors)
var vectors = embedder.EncodeBatch(docs);

// Search
var query = embedder.Encode("I need to change my login credentials");

var results = docs
    .Select((doc, i) => (doc, score: Embedder.CosineSimilarity(query, vectors[i])))
    .OrderByDescending(x => x.score);

foreach (var (doc, score) in results)
    Console.WriteLine($"  {score:F4}: {doc}");
```

```
  0.5981: How do I reset my password?
  0.4067: How do I update my billing address?
  0.0767: Where can I track my order?
 -0.0027: What is your refund policy?
 -0.0451: Do you ship internationally?
```

"Change my login credentials" matches "reset my password" at 0.60 despite
sharing zero keywords. That's the entire value of semantic search.

"Update my billing address" comes second. The model understands that
changing account information is related even though the specific fields differ.

## Batch Encoding

`EncodeBatch()` processes multiple texts in a single call. This is faster
than encoding them one by one because the model can process multiple inputs
in parallel:

```C#
var texts = new[] {
    "First document",
    "Second document",
    "Third document",
};

float[][] vectors = embedder.EncodeBatch(texts);
// vectors[0] = embedding for "First document"   (384 floats)
// vectors[1] = embedding for "Second document"   (384 floats)
// vectors[2] = embedding for "Third document"    (384 floats)
```

For a production FAQ system, you'd encode all your documents at startup,
store the vectors in memory (or serialize them to disk), and only
encode the user's query at request time.

## Choosing a Model

| Model | Dimensions | Input limit | Notes |
|-------|-----------|-------------|-------|
| `minilm-l6-v2` | 384 | 256 tokens | Default. Fast, good quality per byte |
| `mpnet-base-v2` | 768 | 384 tokens | Higher quality, slower |
| `nomic-embed-text` | 768 | 8192 tokens | Long documents, though trained at 2048 |
| `bge-m3` | 1024 | 8192 tokens | Large, multilingual |

Start with `minilm-l6-v2`. It's the most widely used embedding model in
production and handles most use cases well.

Pay attention to that input limit column, because it is the thing most people get
wrong. `minilm-l6-v2` reads **256 tokens**, not 512: roughly 180 words, or 900
characters. Anything past that is silently dropped, with no error and no warning,
and you get a vector for the first part of your text that looks perfectly valid.
If your documents are longer, either chunk them or use a model with a longer
window. This is measured in detail in
[Your MiniLM Embeddings Are Probably Truncating at 256 Tokens](/blog/embedding-truncation/).

## Cosine Similarity Explained

Two vectors are similar when they point in the same direction.
Cosine similarity measures the angle between them:

```
similarity = (A · B) / (|A| × |B|)
```

- **1.0**: identical direction (same meaning)
- **0.0**: perpendicular (unrelated)
- **-1.0**: opposite direction (opposite meaning, rare in practice)

Since Kjarni normalizes all vectors to unit length by default, cosine
similarity simplifies to the dot product:

```C#
// These are equivalent for normalized vectors:
float sim1 = Embedder.CosineSimilarity(a, b);
float sim2 = a.Zip(b, (x, y) => x * y).Sum();  // dot product
```

In practice, most semantic similarity scores fall between 0.0 and 0.8.
A score above 0.5 usually means strong relevance. A score above 0.7
means near-paraphrase. The exact threshold depends on your use case.

## Practical Patterns

### FAQ Matching

Route support tickets to the most relevant FAQ:

```C#
using var embedder = new Embedder("minilm-l6-v2");

var faqs = new[] {
    "How do I cancel my subscription?",
    "How do I get a refund?",
    "How do I change my email address?",
    "What payment methods do you accept?",
    "How do I contact support?",
};
var faqVectors = embedder.EncodeBatch(faqs);

string MatchFaq(string userQuestion)
{
    var queryVec = embedder.Encode(userQuestion);
    var best = faqs
        .Select((faq, i) => (faq, score: Embedder.CosineSimilarity(queryVec, faqVectors[i])))
        .OrderByDescending(x => x.score)
        .First();

    return best.score > 0.4 ? best.faq : "No matching FAQ found.";
}

Console.WriteLine(MatchFaq("I want to stop paying"));
// How do I cancel my subscription?

Console.WriteLine(MatchFaq("Can I pay with crypto?"));
// What payment methods do you accept?
```

### Deduplication

Find near-duplicate content in a dataset:

```C#
var texts = GetAllDocuments();
var vectors = embedder.EncodeBatch(texts);

var duplicates = new List<(string, string, float)>();

for (int i = 0; i < texts.Length; i++)
    for (int j = i + 1; j < texts.Length; j++)
    {
        var sim = Embedder.CosineSimilarity(vectors[i], vectors[j]);
        if (sim > 0.85)
            duplicates.Add((texts[i], texts[j], sim));
    }
```

A threshold of 0.85 catches rephrased content while ignoring
merely related documents.

### Combining with Sentiment

Find relevant reviews about a topic, then check their sentiment.
See [Sentiment Analysis in C#](/blog/sentimentanalysis) for more
on the classification side.

```C#
using var embedder = new Embedder("minilm-l6-v2");
using var classifier = new Classifier("roberta-sentiment");

var query = embedder.Encode("battery life");
var relevant = reviews
    .Select(r => (review: r, score: Embedder.CosineSimilarity(query, embedder.Encode(r))))
    .Where(x => x.score > 0.3)
    .OrderByDescending(x => x.score);

foreach (var (review, score) in relevant)
    Console.WriteLine($"{classifier.Classify(review)}  \"{review}\"");
```

## When to Use Semantic Search vs Keyword Search

Semantic search is not always better than keyword search.

**Semantic search works best when:**
- Users don't know the exact terminology
- You're matching intent, not words ("change login" → "reset password")
- Documents are short (FAQs, product descriptions, support tickets)

**Keyword search works best when:**
- Users search for exact terms (error codes, product IDs, proper nouns)
- You need exact phrase matching
- Documents are long and repetitive keywords matter

**The best approach is usually both.** See
[Build a Document Search Engine in C#](/blog/documentsearchengine)
for a hybrid search implementation that combines BM25 keyword search
with semantic vectors and reranking.

## How This Works Under the Hood

[Kjarni](https://github.com/olafurjohannsson/kjarni) loads HuggingFace
sentence-transformer models directly from safetensors. The inference engine
is written in Rust with SIMD-optimized kernels (AVX2/FMA on x86, NEON on ARM).
The C# package wraps a single native library that loads into your process, so there is nothing else to install and nothing to keep running:
no external dependencies.

The outputs match Python's `sentence-transformers` to four decimal places.

For the full story on why Kjarni exists and how it compares to Python and
ONNX Runtime, see [Why I Built a Native ML Inference Engine in Rust](/blog/nativeinference).

```
Install:  dotnet add package Kjarni
NuGet:    https://www.nuget.org/packages/Kjarni
GitHub:   https://github.com/olafurjohannsson/kjarni
```

## Next Steps

- [Sentiment Analysis in C#](/blog/sentimentanalysis): classify text as positive, negative, or neutral
- [Image Search in C#](/blog/imagesearch/): the same idea for photos, searched by description with CLIP
- [Build a Document Search Engine in C#](/blog/documentsearchengine): full hybrid search with indexing and reranking
- [Why I Built a Native ML Inference Engine in Rust](/blog/nativeinference): the technical story behind Kjarni
