Merge pull request #46589 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

docs/ai/quickstarts/build-vector-search-app.md

@@ -10,44 +10,44 @@ zone_pivot_groups: openai-library
 
 # Build a .NET AI vector search app
 
-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 <xref:Microsoft.Extensions.AI> and [Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/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.
+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.
 
-:::zone target="docs" pivot="openai"
+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.
 
-[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]
+## About the libraries
 
-:::zone-end
+The app uses the <xref:Microsoft.Extensions.AI> and <xref:Microsoft.Extensions.VectorData> 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.
 
-:::zone target="docs" pivot="azure-openai"
+[📦 Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/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:
 
-[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]
+- Perform create-read-update-delete (CRUD) operations on vector stores.
+- Use vector and text search on vector stores.
 
-:::zone-end
+> [!NOTE]
+> The [Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions/) library is currently in preview.
 
-## Interact with your data using vector stores
+<!--Prerequisites section-->
 
-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.
+:::zone target="docs" pivot="openai"
 
-### Explore Microsoft.Extensions.VectorData.Abstractions
+[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]
 
-[Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/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.
+:::zone-end
 
-The abstractions in `Microsoft.Extensions.VectorData.Abstractions` provide library authors and developers with the following functionality:
+:::zone target="docs" pivot="azure-openai"
 
-- Perform Create-Read-Update-Delete (CRUD) operations on vector stores
-- Use vector and text search on vector stores
+[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]
 
-> [!NOTE]
-> The [Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions/) library is currently in preview.
+:::zone-end
 
 ## 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
+- 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:
 
@@ -80,8 +80,8 @@ Complete the following steps to create a .NET console app that can:
 
     - [`Azure.Identity`](https://www.nuget.org/packages/Azure.Identity) provides [`Microsoft Entra ID`](/entra/fundamentals/whatis) token authentication support across the Azure SDK using classes such as `DefaultAzureCredential`.
     - [`Azure.AI.OpenAI`](https://www.nuget.org/packages/Azure.AI.OpenAI) is the official package for using OpenAI's .NET library with the Azure OpenAI Service.
-    - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
     - [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.AI) enables Create-Read-Update-Delete (CRUD) and search operations on vector stores.
+    - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
     - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides an implementation of key-value pair&mdash;based configuration.
     - [`Microsoft.Extensions.Configuration.UserSecrets`](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets) is a user secrets configuration provider implementation for `Microsoft.Extensions.Configuration`.
 
@@ -101,8 +101,8 @@ Complete the following steps to create a .NET console app that can:
     The following list describes each package in the `VectorDataAI` app:
 
     - [`Microsoft.Extensions.AI.OpenAI`](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) provides AI abstractions for OpenAI-compatible models or endpoints. This library also includes the official [`OpenAI`](https://www.nuget.org/packages/OpenAI) library for the OpenAI service API as a dependency.
-    - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
     - [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.AI) enables Create-Read-Update-Delete (CRUD) and search operations on vector stores.
+    - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
     - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides an implementation of key-value pair&mdash;based configuration.
     - [`Microsoft.Extensions.Configuration.UserSecrets`](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets) is a user secrets configuration provider implementation for `Microsoft.Extensions.Configuration`.
 
@@ -134,21 +134,18 @@ Complete the following steps to create a .NET console app that can:
     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.
-
 :::zone-end
 
+> [!NOTE]
+> For the model name, you need to specify a 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. For more information about embedding models, see [Embeddings](/azure/ai-services/openai/concepts/models#embeddings).
+
 ## Add the app code
 
 1. Add a new class named `CloudService` to your project with the following properties:
 
    :::code language="csharp" source="snippets/chat-with-data/azure-openai/CloudService.cs" :::
 
-    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.
+    The <xref:Microsoft.Extensions.VectorData> attributes, such as <xref:Microsoft.Extensions.VectorData.VectorStoreKeyAttribute>, 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 `Description` value for vector searches.
 
 1. In the `Program.cs` file, add the following code to create a data set that describes a collection of cloud services:
 
@@ -158,10 +155,10 @@ Complete the following steps to create a .NET console app that can:
 
     :::zone target="docs" pivot="azure-openai"
 
-    :::code language="csharp" source="snippets/chat-with-data/azure-openai/program.cs" id="EmbeddingGen":::
+    :::code language="csharp" source="snippets/chat-with-data/azure-openai/program.cs" id="EmbeddingGenerator":::
 
     > [!NOTE]
-    > <xref:Azure.Identity.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](../azure-ai-services-authentication.md).
+    > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your local tooling. 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](../azure-ai-services-authentication.md).
 
     :::zone-end
 
@@ -193,7 +190,7 @@ Complete the following steps to create a .NET console app that can:
 
 ## Clean up resources
 
-If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.
+If you no longer need them, delete the Azure OpenAI resource and model deployment.
 
 1. In the [Azure Portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
 1. Select the Azure OpenAI resource, and then select **Delete**.

docs/ai/quickstarts/includes/prerequisites-openai.md

@@ -7,4 +7,4 @@ ms.topic: include
 ## Prerequisites
 
 - .NET 8.0 SDK or higher - [Install the .NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0).
-- An [API key from OpenAI](https://platform.openai.com/docs/quickstart/account-setup) so you can run this sample.
+- An [API key from OpenAI](https://platform.openai.com/docs/libraries#create-and-export-an-api-key) so you can run this sample.

docs/ai/quickstarts/snippets/chat-with-data/azure-openai/CloudService.cs

@@ -13,6 +13,8 @@ internal class CloudService
     [VectorStoreData]
     public string Description { get; set; }
 
-    [VectorStoreVector(Dimensions: 384, DistanceFunction = DistanceFunction.CosineSimilarity)]
+    [VectorStoreVector(
+        Dimensions: 384,
+        DistanceFunction = DistanceFunction.CosineSimilarity)]
     public ReadOnlyMemory<float> Vector { get; set; }
 }

docs/ai/quickstarts/snippets/chat-with-data/azure-openai/Program.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.VectorData;
 using Microsoft.SemanticKernel.Connectors.InMemory;
+using System.Linq;
 using VectorDataAI;
 
 // <SnippetDataSet>
@@ -42,21 +43,21 @@
 ];
 // </SnippetDataSet>
 
-// <SnippetEmbeddingGen>
-// Load the configuration values
+// <SnippetEmbeddingGenerator>
+// Load the configuration values.
 IConfigurationRoot config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
 string endpoint = config["AZURE_OPENAI_ENDPOINT"];
 string model = config["AZURE_OPENAI_GPT_NAME"];
 
-// Create the embedding generator
+// Create the embedding generator.
 IEmbeddingGenerator<string, Embedding<float>> generator =
     new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
         .GetEmbeddingClient(deploymentName: model)
         .AsIEmbeddingGenerator();
-// </SnippetEmbeddingGen>
+// </SnippetEmbeddingGenerator>
 
 // <SnippetVectorStore>
-// Create and populate the vector store
+// Create and populate the vector store.
 var vectorStore = new InMemoryVectorStore();
 VectorStoreCollection<int, CloudService> cloudServicesStore =
     vectorStore.GetCollection<int, CloudService>("cloudServices");
@@ -70,14 +71,15 @@
 // </SnippetVectorStore>
 
 // <SnippetSearch>
-// Convert a search query to a vector and search 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.GenerateVectorAsync(query);
 
-List<VectorSearchResult<CloudService>> results =
-    await cloudServicesStore.SearchAsync(queryEmbedding, top: 1).ToListAsync();
+IAsyncEnumerable<VectorSearchResult<CloudService>> results =
+    cloudServicesStore.SearchAsync(queryEmbedding, top: 1);
 
-foreach (VectorSearchResult<CloudService> result in results)
+await foreach (VectorSearchResult<CloudService> result in results)
 {
     Console.WriteLine($"Name: {result.Record.Name}");
     Console.WriteLine($"Description: {result.Record.Description}");

docs/ai/quickstarts/snippets/chat-with-data/azure-openai/VectorDataAI.csproj

@@ -5,18 +5,17 @@
     <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <UserSecretsId>5981f38c-e59c-46cc-80bb-463f8c3f1691</UserSecretsId>
+    <UserSecretsId>8565c67c-c4b8-4824-a3e7-7f6e352adb33</UserSecretsId>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.Identity" Version="1.14.0" />
     <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
+    <PackageReference Include="Azure.Identity" Version="1.14.0" />
     <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.5.0-preview.1.25265.7" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="9.0.5" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="9.0.5" />
     <PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.5.0" />
-    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.53.1-preview" />
-    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.0-preview.4.25258.110" />
-    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0-preview.4.25258.110" />
-    <PackageReference Include="System.Linq.AsyncEnumerable" Version="10.0.0-preview.4.25258.110" />
+    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.55.0-preview" />
   </ItemGroup>
 
 </Project>

docs/ai/quickstarts/snippets/chat-with-data/openai/CloudService.cs

@@ -1,19 +1,20 @@
 using Microsoft.Extensions.VectorData;
 
-namespace VectorDataAI
+namespace VectorDataAI;
+
+internal class CloudService
 {
-    internal class CloudService
-    {
-        [VectorStoreRecordKey]
-        public int Key { get; set; }
+    [VectorStoreKey]
+    public int Key { get; set; }
 
-        [VectorStoreRecordData]
-        public string Name { get; set; }
+    [VectorStoreData]
+    public string Name { get; set; }
 
-        [VectorStoreRecordData]
-        public string Description { get; set; }
+    [VectorStoreData]
+    public string Description { get; set; }
 
-        [VectorStoreRecordVector(Dimensions: 384, DistanceFunction = DistanceFunction.CosineSimilarity)]
-        public ReadOnlyMemory<float> Vector { get; set; }
-    }
+    [VectorStoreVector(
+        Dimensions: 384,
+        DistanceFunction = DistanceFunction.CosineSimilarity)]
+    public ReadOnlyMemory<float> Vector { get; set; }
 }