Build Hybrid Search in .NET with EF Core 10 and pgvector

{
  "sdk": {
    "version": "10.0.401",
    "rollForward": "latestPatch",
    "allowPrerelease": false
  }
}

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.12" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.12" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.12" />
    <PackageReference Include="Microsoft.Extensions.AI" Version="10.10.0" />
    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.10.1" />
    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.3" />
    <PackageReference Include="OllamaSharp" Version="5.5.0" />
    <PackageReference Include="Pgvector.EntityFrameworkCore" Version="0.3.0" />
  </ItemGroup>

</Project>

services:
  postgres:
    image: pgvector/pgvector:pg17
    container_name: dotnet-guide-hybrid-search-postgres
    environment:
      POSTGRES_DB: hybridsearch
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "54329:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d hybridsearch"]
      interval: 2s
      timeout: 3s
      retries: 30
    volumes:
      - hybridsearch-data:/var/lib/postgresql/data

volumes:
  hybridsearch-data:

docker compose up -d

public static async Task InitializeAsync(
    IServiceProvider services,
    string connectionString,
    CancellationToken cancellationToken = default)
{
    await using (NpgsqlConnection connection = new(connectionString))
    {
        await connection.OpenAsync(cancellationToken);
        await using NpgsqlCommand command = new(
            "CREATE EXTENSION IF NOT EXISTS vector;",
            connection);
        await command.ExecuteNonQueryAsync(cancellationToken);
    }

    using IServiceScope scope = services.CreateScope();
    SearchDbContext db =
        scope.ServiceProvider.GetRequiredService<SearchDbContext>();

    await db.Database.EnsureCreatedAsync(cancellationToken);
}

public sealed class DocumentChunk
{
    public Guid Id { get; init; }
    public string DocumentId { get; init; } = string.Empty;
    public int ChunkNumber { get; init; }
    public string Title { get; set; } = string.Empty;
    public string Text { get; set; } = string.Empty;
    public string EmbeddingModel { get; set; } = string.Empty;

    [Column(TypeName = "vector(768)")]
    public Vector? Embedding { get; set; }

    public NpgsqlTsVector SearchVector { get; private set; } = null!;
}

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.HasPostgresExtension("vector");

    modelBuilder.Entity<DocumentChunk>(entity =>
    {
        entity.HasKey(x => x.Id);

        entity.HasIndex(x => new { x.DocumentId, x.ChunkNumber })
            .IsUnique();

        entity.HasGeneratedTsVectorColumn(
                x => x.SearchVector,
                "english",
                x => new { x.Title, x.Text })
            .HasIndex(x => x.SearchVector)
            .HasMethod("GIN");

        entity.HasIndex(x => x.Embedding)
            .HasMethod("hnsw")
            .HasOperators("vector_cosine_ops")
            .HasStorageParameter("m", 16)
            .HasStorageParameter("ef_construction", 64);
    });
}

public sealed class EmbeddingOptions
{
    public const string SectionName = "Embedding";

    public string Provider { get; init; } = "Ollama";
    public string Endpoint { get; init; } = "http://localhost:11434";
    public string Model { get; init; } = "nomic-embed-text";
}

public static class EmbeddingDimensions
{
    public const int Value = 768;
}

public static class EmbeddingProviderFactory
{
    public static IEmbeddingGenerator<string, Embedding<float>> CreateOllama(
        string endpoint,
        string model) =>
        new OllamaApiClient(new Uri(endpoint), model);

    // Compile/construction verified only in this publication run.
    public static IEmbeddingGenerator<string, Embedding<float>> CreateOpenAI(
        string apiKey,
        string model) =>
        new EmbeddingClient(model, apiKey).AsIEmbeddingGenerator();

    // Compile/construction verified only in this publication run.
    public static IEmbeddingGenerator<string, Embedding<float>> CreateAzureOpenAI(
        string endpoint,
        string apiKey,
        string deployment)
    {
        AzureOpenAIClient client = new(
            new Uri(endpoint),
            new AzureKeyCredential(apiKey));

        return client
            .GetEmbeddingClient(deployment)
            .AsIEmbeddingGenerator();
    }
}

builder.Services.AddDbContext<SearchDbContext>(options =>
    options.UseNpgsql(
        connectionString,
        npgsql => npgsql.UseVector()));

builder.Services.AddSingleton<
    IEmbeddingGenerator<string, Embedding<float>>>(services =>
{
    EmbeddingOptions options = services
        .GetRequiredService<IOptions<EmbeddingOptions>>()
        .Value;

    if (!options.Provider.Equals(
        "Ollama",
        StringComparison.OrdinalIgnoreCase))
    {
        throw new InvalidOperationException(
            "The live-verified runtime provider for this sample is Ollama. " +
            "See docs/provider-options.md for compile-verified cloud adapter examples.");
    }

    return EmbeddingProviderFactory.CreateOllama(
        options.Endpoint,
        options.Model);
});

public IReadOnlyList<string> Split(
    string text,
    int maxWords = 120,
    int overlapWords = 20)
{
    if (string.IsNullOrWhiteSpace(text)) return [];
    if (maxWords <= 0)
        throw new ArgumentOutOfRangeException(nameof(maxWords));
    if (overlapWords < 0 || overlapWords >= maxWords)
        throw new ArgumentOutOfRangeException(nameof(overlapWords));

    string[] words = text.Split(
        (char[]?)null,
        StringSplitOptions.RemoveEmptyEntries |
        StringSplitOptions.TrimEntries);

    var chunks = new List<string>();
    int start = 0;

    while (start < words.Length)
    {
        int end = Math.Min(start + maxWords, words.Length);
        chunks.Add(string.Join(" ", words[start..end]));

        if (end == words.Length) break;
        start = end - overlapWords;
    }

    return chunks;
}

public async Task<IngestDocumentResponse> IngestAsync(
    IngestDocumentRequest request,
    CancellationToken cancellationToken = default)
{
    if (string.IsNullOrWhiteSpace(request.DocumentId))
        throw new ArgumentException("DocumentId is required.", nameof(request));
    if (string.IsNullOrWhiteSpace(request.Title))
        throw new ArgumentException("Title is required.", nameof(request));
    if (string.IsNullOrWhiteSpace(request.Text))
        throw new ArgumentException("Text is required.", nameof(request));

    string documentId = request.DocumentId.Trim();
    string title = request.Title.Trim();

    IReadOnlyList<string> chunks = chunker.Split(request.Text);
    if (chunks.Count == 0)
        throw new ArgumentException(
            "The document did not produce any chunks.",
            nameof(request));

    var replacement = new List<DocumentChunk>(chunks.Count);

    for (int index = 0; index < chunks.Count; index++)
    {
        ReadOnlyMemory<float> vector =
            await embeddings.GenerateVectorAsync(chunks[index]);

        ValidateVector(vector);

        replacement.Add(new DocumentChunk
        {
            Id = Guid.NewGuid(),
            DocumentId = documentId,
            ChunkNumber = index + 1,
            Title = title,
            Text = chunks[index],
            EmbeddingModel = embeddingOptions.Value.Model,
            Embedding = new Vector(vector.ToArray())
        });
    }

    await using var transaction =
        await db.Database.BeginTransactionAsync(cancellationToken);

    await db.DocumentChunks
        .Where(x => x.DocumentId == documentId)
        .ExecuteDeleteAsync(cancellationToken);

    db.DocumentChunks.AddRange(replacement);
    await db.SaveChangesAsync(cancellationToken);
    await transaction.CommitAsync(cancellationToken);

    return new IngestDocumentResponse(
        documentId,
        chunks.Count,
        embeddingOptions.Value.Model,
        EmbeddingDimensions.Value);
}

private async Task<IReadOnlyList<RankedCandidate>> KeywordAsync(
    string query,
    int limit,
    CancellationToken cancellationToken)
{
    var rows = await db.DocumentChunks
        .AsNoTracking()
        .Where(x => x.SearchVector.Matches(
            EF.Functions.WebSearchToTsQuery("english", query)))
        .OrderByDescending(x => x.SearchVector.Rank(
            EF.Functions.WebSearchToTsQuery("english", query)))
        .Take(limit)
        .Select(x => new
        {
            x.Id,
            x.DocumentId,
            x.ChunkNumber,
            x.Title,
            x.Text,
            Score = x.SearchVector.Rank(
                EF.Functions.WebSearchToTsQuery("english", query))
        })
        .ToListAsync(cancellationToken);

    return rows.Select((x, index) => new RankedCandidate(
            x.Id,
            x.DocumentId,
            x.ChunkNumber,
            x.Title,
            x.Text,
            index + 1,
            x.Score))
        .ToList();
}

private async Task<IReadOnlyList<RankedCandidate>> VectorAsync(
    string query,
    int limit,
    CancellationToken cancellationToken)
{
    ReadOnlyMemory<float> embedding =
        await embeddings.GenerateVectorAsync(query);

    if (embedding.Length != EmbeddingDimensions.Value)
    {
        throw new InvalidOperationException(
            $"Embedding dimension mismatch. Expected {EmbeddingDimensions.Value}; " +
            $"received {embedding.Length}.");
    }

    Vector queryVector = new(embedding.ToArray());

    var rows = await db.DocumentChunks
        .AsNoTracking()
        .Where(x => x.Embedding != null)
        .OrderBy(x => x.Embedding!.CosineDistance(queryVector))
        .Take(limit)
        .Select(x => new
        {
            x.Id,
            x.DocumentId,
            x.ChunkNumber,
            x.Title,
            x.Text,
            Distance = x.Embedding!.CosineDistance(queryVector)
        })
        .ToListAsync(cancellationToken);

    return rows.Select((x, index) => new RankedCandidate(
            x.Id,
            x.DocumentId,
            x.ChunkNumber,
            x.Title,
            x.Text,
            index + 1,
            1.0 - x.Distance))
        .ToList();
}

public static IReadOnlyList<SearchHit> Fuse(
    IReadOnlyList<RankedCandidate> keyword,
    IReadOnlyList<RankedCandidate> vector,
    int top,
    int k = 60,
    double keywordWeight = 1.0,
    double vectorWeight = 1.0)
{
    if (top <= 0) throw new ArgumentOutOfRangeException(nameof(top));
    if (k < 0) throw new ArgumentOutOfRangeException(nameof(k));
    if (keywordWeight < 0)
        throw new ArgumentOutOfRangeException(nameof(keywordWeight));
    if (vectorWeight < 0)
        throw new ArgumentOutOfRangeException(nameof(vectorWeight));

    var accumulator = new Dictionary<Guid, MutableResult>();

    Add(keyword, keywordWeight, isKeyword: true);
    Add(vector, vectorWeight, isKeyword: false);

    return accumulator.Values
        .OrderByDescending(x => x.Score)
        .ThenBy(x => x.Id)
        .Take(top)
        .Select(x => new SearchHit(
            x.Id,
            x.DocumentId,
            x.ChunkNumber,
            x.Title,
            x.Text,
            x.Score,
            x.KeywordRank,
            x.VectorRank))
        .ToList();

    void Add(
        IReadOnlyList<RankedCandidate> source,
        double weight,
        bool isKeyword)
    {
        foreach (RankedCandidate candidate in source)
        {
            if (candidate.Rank <= 0)
                throw new ArgumentOutOfRangeException(
                    nameof(source),
                    "Ranks must start at 1.");

            if (!accumulator.TryGetValue(
                candidate.Id,
                out MutableResult? item))
            {
                item = new MutableResult(candidate);
                accumulator.Add(candidate.Id, item);
            }

            item.Score += weight / (k + candidate.Rank);

            if (isKeyword) item.KeywordRank = candidate.Rank;
            else item.VectorRank = candidate.Rank;
        }
    }
}

public async Task<IReadOnlyList<SearchHit>> SearchAsync(
    SearchRequest request,
    CancellationToken cancellationToken = default)
{
    if (string.IsNullOrWhiteSpace(request.Query))
        throw new ArgumentException("Query is required.", nameof(request));

    if (request.Top is < 1 or > 20)
        throw new ArgumentOutOfRangeException(
            nameof(request),
            "Top must be between 1 and 20.");

    SearchMode mode = SearchModeParser.Parse(request.Mode);

    int candidateLimit =
        Math.Min(Math.Max(request.Top * 4, 20), 100);

    if (mode == SearchMode.Keyword)
    {
        IReadOnlyList<RankedCandidate> keyword =
            await KeywordAsync(
                request.Query.Trim(),
                candidateLimit,
                cancellationToken);

        return keyword.Take(request.Top)
            .Select(x => new SearchHit(
                x.Id, x.DocumentId, x.ChunkNumber,
                x.Title, x.Text,
                x.SourceScore, x.Rank, null))
            .ToList();
    }

    if (mode == SearchMode.Vector)
    {
        IReadOnlyList<RankedCandidate> vector =
            await VectorAsync(
                request.Query.Trim(),
                candidateLimit,
                cancellationToken);

        return vector.Take(request.Top)
            .Select(x => new SearchHit(
                x.Id, x.DocumentId, x.ChunkNumber,
                x.Title, x.Text,
                x.SourceScore, null, x.Rank))
            .ToList();
    }

    IReadOnlyList<RankedCandidate> keywordCandidates =
        await KeywordAsync(
            request.Query.Trim(),
            candidateLimit,
            cancellationToken);

    IReadOnlyList<RankedCandidate> vectorCandidates =
        await VectorAsync(
            request.Query.Trim(),
            candidateLimit,
            cancellationToken);

    return ReciprocalRankFusion.Fuse(
        keywordCandidates,
        vectorCandidates,
        request.Top);
}

public static SearchMode Parse(string? value) =>
    value?.Trim().ToLowerInvariant() switch
    {
        "keyword" => SearchMode.Keyword,
        "vector" => SearchMode.Vector,
        "hybrid" or null or "" => SearchMode.Hybrid,
        _ => throw new ArgumentException(
            "Search mode must be 'keyword', 'vector', or 'hybrid'.",
            nameof(value))
    };

# Start PostgreSQL + pgvector
docker compose up -d

# Install the verified embedding model once
ollama pull nomic-embed-text

# Start the API
dotnet run --project src/HybridSearch.Api

app.MapPost("/api/documents", async (
    IngestDocumentRequest request,
    DocumentIngestionService ingestion,
    CancellationToken cancellationToken) =>
{
    try
    {
        IngestDocumentResponse result =
            await ingestion.IngestAsync(request, cancellationToken);

        return Results.Ok(result);
    }
    catch (ArgumentException ex)
    {
        return Results.BadRequest(new { error = ex.Message });
    }
});

app.MapPost("/api/search", async (
    SearchRequest request,
    HybridSearchService search,
    CancellationToken cancellationToken) =>
{
    try
    {
        IReadOnlyList<SearchHit> result =
            await search.SearchAsync(request, cancellationToken);

        return Results.Ok(result);
    }
    catch (ArgumentException ex)
    {
        return Results.BadRequest(new { error = ex.Message });
    }
});

@HybridSearchApi = http://localhost:5087

POST {{HybridSearchApi}}/api/documents
Content-Type: application/json

{
  "documentId": "hosted-services",
  "title": "CancellationToken in hosted services",
  "text": "Use CancellationToken to request graceful shutdown of a background worker. Hosted services should observe cancellation and finish cleanup before the process exits."
}

###

POST {{HybridSearchApi}}/api/search
Content-Type: application/json

{
  "query": "CancellationToken shutdown",
  "mode": "hybrid",
  "top": 5
}

dotnet restore HybridSearch.slnx
dotnet build HybridSearch.slnx --configuration Release --no-restore
dotnet test HybridSearch.slnx --configuration Release --no-build

powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\scripts\verify.ps1"