Edit

Share via

Build a .NET AI vector search app

  • Article
Choose a host service for OpenAI

In this quickstart, you create a .NET console app to perform semantic search on a vector store to find relevant results for the user's query. You learn how to generate embeddings for user prompts and use those embeddings to query the vector data store. Vector search functionality is also a key component for Retrieval Augmented Generation (RAG) scenarios. The app uses the Microsoft.Extensions.AI and Microsoft.Extensions.VectorData.Abstractions libraries so you can write code using AI abstractions rather than a specific SDK. AI abstractions help create loosely coupled code that allows you to change the underlying AI model with minimal app changes.

Prerequisites

Prerequisites

Clone the sample repository

You can create your own app using the steps in the sections ahead, or you can clone the GitHub repository that contains the completed sample apps for all of the quickstarts. If you plan to use Azure OpenAI, the sample repo is also structured as an Azure Developer CLI template that can provision an Azure OpenAI resource for you.

git clone https://github.com/dotnet/ai-samples.git

Interact with your data using vector stores

Vector stores or vector databases are essential for tasks like semantic search, Retrieval Augmented Generation (RAG), and other scenarios that require grounding generative AI responses. While relational databases and document databases are optimized for structured and semi-structured data, vector databases are built to efficiently store, index, and manage data represented as embedding vectors. As a result, the indexing and search algorithms used by vector databases are optimized to efficiently retrieve data that can be used downstream in your applications.

Explore Microsoft.Extensions.VectorData.Abstractions

Microsoft.Extensions.VectorData.Abstractions is a .NET library developed in collaboration with Semantic Kernel and the broader .NET ecosystem to provide a unified layer of abstractions for interacting with vector stores.

The abstractions in Microsoft.Extensions.VectorData.Abstractions provide library authors and developers with the following functionality:

  • Perform Create-Read-Update-Delete (CRUD) operations on vector stores
  • Use vector and text search on vector stores

Note

The Microsoft.Extensions.VectorData.Abstractions library is currently in preview.

Create the app

Complete the following steps to create a .NET console app that can:

  • Create and populate a vector store by generating embeddings for a data set
  • Generate an embedding for the user prompt
  • Query the vector store using the user prompt embedding
  • Display the relevant results from the vector search

  1. In an empty directory on your computer, use the dotnet new command to create a new console app:

    dotnet new console -o VectorDataAI

  2. Change directory into the app folder:

    cd VectorDataAI

  3. Install the required packages:

    dotnet package add Azure.Identity
dotnet package add Azure.AI.OpenAI
dotnet package add Microsoft.Extensions.AI.OpenAI --prerelease
dotnet package add Microsoft.Extensions.VectorData.Abstractions --prerelease
dotnet package add Microsoft.SemanticKernel.Connectors.InMemory --prerelease
dotnet package add Microsoft.Extensions.Configuration
dotnet package add Microsoft.Extensions.Configuration.UserSecrets

    The following list describes what each package is used for in the VectorDataAI app:

    dotnet package add Microsoft.Extensions.AI.OpenAI --prerelease
dotnet package add Microsoft.Extensions.VectorData.Abstractions --prerelease
dotnet package add Microsoft.SemanticKernel.Connectors.InMemory --prerelease
dotnet package add Microsoft.Extensions.Configuration
dotnet package add Microsoft.Extensions.Configuration.UserSecrets

    The following list describes what each package is used for in the VectorDataAI app:

  4. Open the app in Visual Studio Code (or your editor of choice).

    code .

Create the AI service

The sample GitHub repository is structured as an Azure Developer CLI (azd) template, which azd can use to provision the Azure OpenAI service and model for you.

  1. From a terminal or command prompt, navigate to the src\quickstarts\azure-openai directory of the sample repo.

  2. Run the azd up command to provision the Azure OpenAI resources. It might take several minutes to create the Azure OpenAI service and deploy the model.

    azd up

    azd also configures the required user secrets for the sample app, such as the Azure OpenAI endpoint and model name.

Configure the app

  1. Navigate to the root of your .NET project from a terminal or command prompt.

  2. Run the following commands to configure your OpenAI API key as a secret for the sample app:

    dotnet user-secrets init
dotnet user-secrets set OpenAIKey <your-openai-key>
dotnet user-secrets set ModelName <your-openai-model-name>

    Note

    For the ModelName value, you need to specify an OpenAI text embedding model such as text-embedding-3-small or text-embedding-3-large to generate embeddings for vector search in the sections that follow.

Add the app code

  1. Add a new class named CloudService to your project with the following properties:

    using Microsoft.Extensions.VectorData;

namespace VectorDataAI
{
    internal class CloudService
    {
        [VectorStoreRecordKey]
        public int Key { get; set; }

        [VectorStoreRecordData]
        public string Name { get; set; }

        [VectorStoreRecordData]
        public string Description { get; set; }

        [VectorStoreRecordVector(384, DistanceFunction.CosineSimilarity)]
        public ReadOnlyMemory<float> Vector { get; set; }
    }
}

    In the preceding code:

    • The C# attributes provided by Microsoft.Extensions.VectorData influence how each property is handled when used in a vector store.
    • The Vector property stores a generated embedding that represents the semantic meaning of the Name and Description for vector searches.

  2. In the Program.cs file, add the following code to create a data set that describes a collection of cloud services:

    
var cloudServices = new List<CloudService>()
{
    new CloudService
        {
            Key=0,
            Name="Azure App Service",
            Description="Host .NET, Java, Node.js, and Python web applications and APIs in a fully managed Azure service. You only need to deploy your code to Azure. Azure takes care of all the infrastructure management like high availability, load balancing, and autoscaling."
        },
    new CloudService
        {
            Key=1,
            Name="Azure Service Bus",
            Description="A fully managed enterprise message broker supporting both point to point and publish-subscribe integrations. It's ideal for building decoupled applications, queue-based load leveling, or facilitating communication between microservices."
        },
    new CloudService
        {
            Key=2,
            Name="Azure Blob Storage",
            Description="Azure Blob Storage allows your applications to store and retrieve files in the cloud. Azure Storage is highly scalable to store massive amounts of data and data is stored redundantly to ensure high availability."
        },
    new CloudService
        {
            Key=3,
            Name="Microsoft Entra ID",
            Description="Manage user identities and control access to your apps, data, and resources.."
        },
    new CloudService
        {
            Key=4,
            Name="Azure Key Vault",
            Description="Store and access application secrets like connection strings and API keys in an encrypted vault with restricted access to make sure your secrets and your application aren't compromised."
        },
    new CloudService
        {
            Key=5,
            Name="Azure AI Search",
            Description="Information retrieval at scale for traditional and conversational search applications, with security and options for AI enrichment and vectorization."
        }

  3. Create and configure an IEmbeddingGenerator implementation to send requests to an embedding AI model:

    
// Load the configuration values
var config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
string endpoint = config["AZURE_OPENAI_ENDPOINT"];
string model = config["AZURE_OPENAI_GPT_NAME"];

// Create the embedding generator
IEmbeddingGenerator<string, Embedding<float>> generator =
    new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())

    Note

    DefaultAzureCredential searches for authentication credentials from your local tooling. If you aren't using the azd template to provision the Azure OpenAI resource, you'll need to assign the Azure AI Developer role to the account you used to sign in to Visual Studio or the Azure CLI. For more information, see Authenticate to Azure AI services with .NET.

    IEmbeddingGenerator<string, Embedding<float>> generator =
    new OpenAIClient(new ApiKeyCredential(key))
            .AsEmbeddingGenerator(modelId: model);

// Create and populate the vector store.
var vectorStore = new InMemoryVectorStore();
IVectorStoreRecordCollection<int, CloudService> cloudServicesStore = vectorStore.GetCollection<int, CloudService>("cloudServices");
await cloudServicesStore.CreateCollectionIfNotExistsAsync();

  4. Create and populate a vector store with the cloud service data. Use the IEmbeddingGenerator implementation to create and assign an embedding vector for each record in the cloud service data:

    // Create and populate the vector store
var vectorStore = new InMemoryVectorStore();
Microsoft.Extensions.VectorData.IVectorStoreRecordCollection<int, CloudService> cloudServicesStore = vectorStore.GetCollection<int, CloudService>("cloudServices");
await cloudServicesStore.CreateCollectionIfNotExistsAsync();

foreach (CloudService service in cloudServices)
{
    service.Vector = await generator.GenerateEmbeddingVectorAsync(service.Description);
    await cloudServicesStore.UpsertAsync(service);
}

    The embeddings are numerical representations of the semantic meaning for each data record, which makes them compatible with vector search features.

  5. Create an embedding for a search query and use it to perform a vector search on the vector store:

    // Convert a search query to a vector and search the vector store
string query = "Which Azure service should I use to store my Word documents?";
ReadOnlyMemory<float> queryEmbedding = await generator.GenerateEmbeddingVectorAsync(query);

VectorSearchResults<CloudService> results =
    await cloudServicesStore.VectorizedSearchAsync(queryEmbedding, new VectorSearchOptions<CloudService>()
{
    Top = 1
});

await foreach (VectorSearchResult<CloudService> result in results.Results)
{
    Console.WriteLine($"Name: {result.Record.Name}");
    Console.WriteLine($"Description: {result.Record.Description}");
    Console.WriteLine($"Vector match score: {result.Score}");
    Console.WriteLine();
}

  6. Use the dotnet run command to run the app:

    dotnet run

    The app prints out the top result of the vector search, which is the cloud service that is most relevant to the original query. You can modify the query to try different search scenarios.

Clean up resources

When you no longer need the sample application or resources, remove the corresponding deployment and all resources.

azd down

Next steps