{"id":59608,"date":"2026-02-26T10:00:00","date_gmt":"2026-02-26T18:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=59608"},"modified":"2026-02-25T23:01:01","modified_gmt":"2026-02-26T07:01:01","slug":"vector-data-in-dotnet-building-blocks-for-ai-part-2","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/vector-data-in-dotnet-building-blocks-for-ai-part-2\/","title":{"rendered":"Vector Data in .NET – Building Blocks for AI Part 2"},"content":{"rendered":"

Welcome back to the building blocks for AI in .NET series! In part one<\/a>, we explored Microsoft Extensions for AI (MEAI) and how it provides a unified interface for working with large language models. Today, we’re diving into the second building block: Microsoft.Extensions.VectorData<\/strong>.<\/p>\n

In the first post, we learned how to ask questions and even share some content for context with an LLM. Most applications, however, require more than just a simple question or small markdown file for context. You may want the LLM to have access to all of your product manuals to help troubleshoot customer issues, or provide your employee handbook for an HR chatbot.<\/p>\n

Another feature that is common in intelligent apps is semantic search. A semantic search uses the meaning of a query, not just the words or letters, to conduct the search. It does this by converting text into embeddings<\/em> which are numerical representations of the semantic meaning of text, and vectors that provide insights into how they are related.<\/p>\n

Imagine you have a simple database with just three entries:<\/p>\n

    \n
  1. Hall pass<\/li>\n
  2. Mountain pass<\/li>\n
  3. Pass (verb)<\/li>\n<\/ol>\n

    A traditional approach to finding the answer to queries like “How do I get over the pass?” or “Where do I pick up a pass?” breaks the query down into parts to search for. The word “pass” appears in all three database items, so I receive all three entries back despite the different contexts of my queries. Here is a simplified visualization:<\/p>\n

    \"How do I get over the pass?\" \r\nHow | do | I | get | over | the | pass \r\nPass - matches all three entries \r\n\r\n\"Where do I pick up my pass?\"\r\nWhere | do | I | pick | up | my | pass \r\nPass - matches all three entries <\/code><\/pre>\n
    Now let’s assume I use an embedding to encode the semantic meaning of the word. The database has already been encoded, but I need to create embeddings from my query. This time, however, the embeddings provide me with a semantic result, not a text-based one. The semantic approach looks like this:<\/p>\n
    \"How do I get over the pass?\" \r\n0 | 5 | etc. | 2 \r\n2 - matches the 2nd entry, \"Mountain pass\" \r\n\r\n\"Where do I pick up my pass?\" \r\n6 | 9 | etc. | 1   \r\n1 - matches the 1st entry, \"Hall pass\" <\/code><\/pre>\n
    A special embeddings model is used to create the embeddings and is trained to understand the semantic meaning of words through context such as the related terms that appear before and after it. Instead of generating embeddings every time the application runs, it makes much more sense to store them in a database. This has the added bonus of being able to use the database’s ability to query and return results, rather than coding the logic yourself or doing it in a suboptimal way.<\/p>\n
    Vector databases<\/em> are designed specifically to store vectors and embeddings. Qdrant, Redis, SQL Server and Cosmos DB are examples of services and products that support storing vector data. Just like MEAI unified LLM access, the vector data extensions provide a common abstraction for working with vector stores.<\/p>\n
    Why vectors matter for AI applications<\/h2>\n
    Before we jump into the code, let’s look a little more closely at vectors. When you ask an LLM a question about your company’s documentation, the model doesn’t magically know your content. Instead, your application typically:<\/p>\n
      \n
    1. Converts your documents into embeddings<\/strong> – numerical representations that capture semantic meaning<\/li>\n
    2. Stores those embeddings in a vector database<\/strong> along with the original content<\/li>\n
    3. Converts the user’s query into an embedding<\/strong> using the same model<\/li>\n
    4. Performs a similarity search<\/strong> to find the most relevant documents<\/li>\n
    5. Passes the relevant context to the LLM<\/strong> along with the user’s query<\/li>\n<\/ol>\n
      \"rag<\/a><\/p>\n
      This pattern, known as RAG (Retrieval-Augmented Generation), allows models to provide accurate, grounded responses based on your specific data. The challenge? Every vector database has its own SDK, data structures, and query patterns. That’s where Microsoft.Extensions.VectorData comes in.<\/p>\n
      One interface, many vector stores<\/h2>\n
      The Microsoft Extensions for Vector Data library provides abstractions that work across different vector database providers. Here’s what that looks like in practice. First, let’s look at using an example vector database, Qdrant, directly and without the abstractions:<\/p>\n
      var qdrantClient = new QdrantClient(\"localhost\", 6334);\r\n\r\nvar collection = \"my_collection\";\r\nawait qdrantClient.CreateCollectionAsync(collection, new VectorParams\r\n{\r\n    Size = 1536,\r\n    Distance = Distance.Cosine\r\n});\r\n\r\nvar points = new List<PointStruct>\r\n{\r\n    new()\r\n    {\r\n        Id = new PointId { Uuid = Guid.NewGuid().ToString() },\r\n        Vectors = embedding,\r\n        Payload =\r\n        {\r\n            [\"text\"] = \"Sample document text\",\r\n            [\"category\"] = \"documentation\"\r\n        }\r\n    }\r\n};\r\n\r\nawait qdrantClient.UpsertAsync(collection, points);\r\n\r\nvar searchResults = await qdrantClient.SearchAsync(collection, queryEmbedding, limit: 5);<\/code><\/pre>\n
      Now let’s see the same thing using the universal abstractions:<\/p>\n
      \/\/ Configure embedding generation once on the vector store\r\nvar embeddingGenerator = new OpenAIClient(apiKey)\r\n    .GetEmbeddingClient(\"text-embedding-3-small\")\r\n    .AsIEmbeddingGenerator();\r\n\r\nvar vectorStore = new QdrantVectorStore(\r\n    new QdrantClient(\"localhost\"),\r\n    ownsClient: true,\r\n    new QdrantVectorStoreOptions { EmbeddingGenerator = embeddingGenerator });\r\n\r\nvar collection = vectorStore.GetCollection<string, DocumentRecord>(\"my_collection\");\r\nawait collection.EnsureCollectionExistsAsync();\r\n\r\nvar record = new DocumentRecord\r\n{\r\n    Key = Guid.NewGuid().ToString(),\r\n    Text = \"Sample document text\",\r\n    Category = \"documentation\"\r\n};\r\n\r\nawait collection.UpsertAsync(record);\r\n\r\nvar searchResults = collection.SearchAsync(\"find documents about sample topics\", top: 5);<\/code><\/pre>\n
      The second example works with any supported vector store by simply changing the VectorStore<\/code> implementation. Your business logic stays the same.<\/p>\n
      Defining your data model<\/h2>\n
      The vector data abstractions use attributes to map your C# classes to vector database schemas. Here’s a practical example for a document store:<\/p>\n
      public class DocumentRecord\r\n{\r\n    [VectorStoreKey]\r\n    public string Key { get; set; }\r\n\r\n    [VectorStoreData]\r\n    public string Text { get; set; }\r\n\r\n    [VectorStoreData(IsIndexed = true)]\r\n    public string Category { get; set; }\r\n\r\n    [VectorStoreData(IsIndexed = true)]\r\n    public DateTimeOffset Timestamp { get; set; }\r\n\r\n    \/\/ The vector is automatically generated from Text when an\r\n    \/\/ IEmbeddingGenerator is configured on the collection or vector store\r\n    [VectorStoreVector(1536, DistanceFunction.CosineSimilarity)]\r\n    public string Embedding => this.Text;\r\n}<\/code><\/pre>\n
      The attributes tell the library:<\/p>\n