Merge main into live

.openpublishing.redirection.ai.json

@@ -1,8 +1,8 @@
 {
     "redirections": [
         {
-            "source_path_from_root": "/docs/ai/quickstarts/get-started-azure-openai.md",
-            "redirect_url": "/dotnet/ai/quickstarts/get-started-openai"
+            "source_path_from_root": "/docs/ai/how-to/app-service-db-auth.md",
+            "redirect_url": "/dotnet/ai"
         },
         {
             "source_path_from_root": "/docs/ai/how-to/use-redis-for-memory.md",
@@ -13,8 +13,36 @@
             "redirect_url": "/dotnet/ai"
         },
         {
-            "source_path_from_root": "/docs/ai/how-to/app-service-db-auth.md",
-            "redirect_url": "/dotnet/ai"
+            "source_path_from_root": "/docs/ai/quickstarts/get-started-azure-openai.md",
+            "redirect_url": "/dotnet/ai/quickstarts/build-chat-app"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/get-started-openai.md",
+            "redirect_url": "/dotnet/ai/quickstarts/build-chat-app"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/quickstart-ai-chat-with-data.md",
+            "redirect_url": "/dotnet/ai/quickstarts/build-vector-search-app"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/quickstart-assistants.md",
+            "redirect_url": "/dotnet/ai/quickstarts/create-assistant"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/quickstart-azure-openai-tool.md",
+            "redirect_url": "/dotnet/ai/quickstarts/use-function-calling"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/quickstart-local-ai.md",
+            "redirect_url": "/dotnet/ai/quickstarts/chat-local-model"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/quickstart-openai-generate-images.md",
+            "redirect_url": "/dotnet/ai/quickstarts/generate-images"
+        },
+        {
+            "source_path_from_root": "/docs/ai/quickstarts/quickstart-openai-summarize-text.md",
+            "redirect_url": "/dotnet/ai/quickstarts/prompt-model"
         }
     ]
-}
+}

docs/ai/ai-extensions.md

@@ -99,5 +99,5 @@ For an end-to-end sample using `Microsoft.Extensions.AI`, see [eShopSupport](htt
 
 ## Next steps
 
-- [Build an AI chat app with .NET](./quickstarts/get-started-openai.md)
-- [Quickstart - Summarize text using Azure AI chat app with .NET](./quickstarts/quickstart-openai-summarize-text.md)
+- [Build an AI chat app with .NET](/dotnet/ai/quickstarts/build-chat-app)
+- [Quickstart - Summarize text using Azure AI chat app with .NET](/dotnet/ai/quickstarts/prompt-model)

docs/ai/dotnet-ai-ecosystem.md

@@ -63,7 +63,7 @@ Azure offers many other AI services to build specific application capabilities a
 
 .NET apps can also connect to local AI models for many different development scenarios. [Semantic Kernel](https://github.com/microsoft/semantic-kernel) is the recommended tool to connect to local models using .NET. Semantic Kernel can connect to many different models hosted across a variety of platforms and abstracts away lower-level implementation details.
 
-For example, you can use [Ollama](https://ollama.com/) to [connect to local AI models with .NET](quickstarts/quickstart-local-ai.md), including several small language models (SLMs) developed by Microsoft:
+For example, you can use [Ollama](https://ollama.com/) to [connect to local AI models with .NET](/dotnet/ai/quickstarts/chat-local-model), including several small language models (SLMs) developed by Microsoft:
 
 | Model               | Description                                               |
 |---------------------|-----------------------------------------------------------|
@@ -84,7 +84,7 @@ This article summarized the tools and SDKs in the .NET ecosystem, with a focus o
 ## Next steps
 
 - [What is Semantic Kernel?](/semantic-kernel/overview/)
-- [Quickstart - Summarize text using Azure AI chat app with .NET](./quickstarts/quickstart-openai-summarize-text.md)
+- [Quickstart - Summarize text using Azure AI chat app with .NET](/dotnet/ai/quickstarts/prompt-model)
 
 [phi3]: https://azure.microsoft.com/products/phi-3
 [orca]: https://www.microsoft.com/research/project/orca/

docs/ai/get-started/dotnet-ai-overview.md

@@ -36,16 +36,16 @@ We recommend the following sequence of tutorials and articles for an introductio
 
 | Scenario | Tutorial |
 |----------|----------|
-| Create a chat application | [Build an Azure AI chat app with .NET](../quickstarts/get-started-openai.md)|
-| Summarize text | [Summarize text using Azure AI chat app with .NET](../quickstarts/quickstart-openai-summarize-text.md) |
-| Chat with your data     | [Get insight about your data from an .NET Azure AI chat app](../quickstarts/quickstart-ai-chat-with-data.md) |
-| Call .NET functions with AI | [Extend Azure AI using tools and execute a local function with .NET](../quickstarts/quickstart-azure-openai-tool.md) |
-| Generate images | [Generate images using Azure AI with .NET](../quickstarts/quickstart-openai-generate-images.md) |
+| Create a chat application | [Build an Azure AI chat app with .NET](/dotnet/ai/quickstarts/build-chat-app)|
+| Summarize text | [Summarize text using Azure AI chat app with .NET](/dotnet/ai/quickstarts/prompt-model) |
+| Chat with your data     | [Get insight about your data from an .NET Azure AI chat app](/dotnet/ai/quickstarts/build-vector-search-app) |
+| Call .NET functions with AI | [Extend Azure AI using tools and execute a local function with .NET](/dotnet/ai/quickstarts/use-function-calling) |
+| Generate images | [Generate images using Azure AI with .NET](/dotnet/ai/quickstarts/generate-images) |
 | Train your own model |[ML.NET tutorial](https://dotnet.microsoft.com/learn/ml-dotnet/get-started-tutorial/intro) |
 
 Browse the table of contents to learn more about the core concepts, starting with [How generative AI and LLMs work](../conceptual/how-genai-and-llms-work.md).
 
 ## Next steps
 
-- [Quickstart: Build an Azure AI chat app with .NET](../quickstarts/get-started-openai.md)
+- [Quickstart: Build an Azure AI chat app with .NET](/dotnet/ai/quickstarts/build-chat-app)
 - [Video series: Machine Learning and AI with .NET](/shows/machine-learning-and-ai-with-dotnet-for-beginners)

docs/ai/how-to/content-filtering.md

@@ -49,4 +49,4 @@ The response was filtered due to the prompt triggering Azure OpenAI's content ma
 
 * [Create and assign a content filter](/azure/ai-services/openai/how-to/content-filters)
 * [Content Filtering concepts](/azure/ai-services/openai/concepts/content-filter)
-* [Create a chat app](../quickstarts/quickstart-openai-summarize-text.md)
+* [Create a chat app](/dotnet/ai/quickstarts/prompt-model)

docs/ai/index.yml

@@ -49,6 +49,8 @@ landingContent:
             url: conceptual/vector-databases.md
           - text: Prompt engineering
             url: conceptual/prompt-engineering-dotnet.md
+          - text: Evaluation libraries
+            url: conceptual/evaluation-libraries.md
 
   # Card (Optional; Remove if not applicable.)
   - title: Common tasks

docs/ai/quickstarts/get-started-openai.md → docs/ai/quickstarts/build-chat-app.md

@@ -153,5 +153,5 @@ azd down
 
 ## Next steps
 
-- [Quickstart - Chat with a local AI model](quickstart-local-ai.md)
-- [Generate images using AI with .NET](quickstart-openai-generate-images.md)
+- [Quickstart - Chat with a local AI model](/dotnet/ai/quickstarts/chat-local-model)
+- [Generate images using AI with .NET](/dotnet/ai/quickstarts/generate-images)

docs/ai/quickstarts/quickstart-ai-chat-with-data.md → docs/ai/quickstarts/build-vector-search-app.md

@@ -205,5 +205,5 @@ azd down
 
 ## Next steps
 
-- [Quickstart - Chat with a local AI model](quickstart-local-ai.md)
-- [Generate images using AI with .NET](quickstart-openai-generate-images.md)
+- [Quickstart - Chat with a local AI model](/dotnet/ai/quickstarts/chat-local-model)
+- [Generate images using AI with .NET](/dotnet/ai/quickstarts/generate-images)

docs/ai/quickstarts/quickstart-local-ai.md → docs/ai/quickstarts/chat-local-model.md

@@ -20,7 +20,7 @@ In this quickstart, you learn how to create a conversational .NET console chat a
 
 ## Run the local AI model
 
-Complete the following steps to configure and run a local AI Model on your device. Many different AI models are available to run locally and are trained for different tasks, such as generating code, analyzing images, generative chat, or creating embeddings. For this quickstart, you'll use the general purpose `phi3:mini` model, which is a small but capable generative AI created by Microsoft.
+Complete the following steps to configure and run a local AI model on your device. Many different AI models are available to run locally and are trained for different tasks, such as generating code, analyzing images, generative chat, or creating embeddings. For this quickstart, you'll use the general purpose `phi3:mini` model, which is a small but capable generative AI created by Microsoft.
 
 1. Open a terminal window and verify that Ollama is available on your device:
 
@@ -54,7 +54,7 @@ Complete the following steps to configure and run a local AI Model on your devic
 
 ## Create the .NET app
 
-Complete the following steps to create a .NET console app that will connect to your local `phi3:mini` AI model:
+Complete the following steps to create a .NET console app that connects to your local `phi3:mini` AI model.
 
 1. In a terminal window, navigate to an empty directory on your device and create a new app with the `dotnet new` command:
 

docs/ai/quickstarts/evaluate-ai-response.md

@@ -0,0 +1,116 @@
+---
+title: Quickstart - Evaluate a model's response
+description: Learn how to create an MSTest app to evaluate the AI chat response of a language model.
+ms.date: 02/25/2025
+ms.topic: quickstart
+ms.custom: devx-track-dotnet, devx-track-dotnet-ai
+---
+
+# Evaluate a model's response
+
+In this quickstart, you create an MSTest app to evaluate the chat response of a model. The test app uses the [Microsoft.Extensions.AI.Evaluation](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation) libraries.
+
+## Prerequisites
+
+- [Install .NET 8.0](https://dotnet.microsoft.com/download) or a later version
+- [Install Ollama](https://ollama.com/) locally on your machine
+- [Visual Studio Code](https://code.visualstudio.com/) (optional)
+
+## Run the local AI model
+
+Complete the following steps to configure and run a local AI model on your device. For this quickstart, you'll use the general purpose `phi3:mini` model, which is a small but capable generative AI created by Microsoft.
+
+1. Open a terminal window and verify that Ollama is available on your device:
+
+    ```bash
+    ollama
+    ```
+
+    If Ollama is available, it displays a list of available commands.
+
+1. Start Ollama:
+
+    ```bash
+    ollama serve
+    ```
+
+    If Ollama is running, it displays a list of available commands.
+
+1. Pull the `phi3:mini` model from the Ollama registry and wait for it to download:
+
+    ```bash
+    ollama pull phi3:mini
+    ```
+
+1. After the download completes, run the model:
+
+    ```bash
+    ollama run phi3:mini
+    ```
+
+    Ollama starts the `phi3:mini` model and provides a prompt for you to interact with it.
+
+## Create the test app
+
+Complete the following steps to create an MSTest project that connects to your local `phi3:mini` AI model.
+
+1. In a terminal window, navigate to the directory where you want to create your app, and create a new MSTest app with the `dotnet new` command:
+
+    ```dotnetcli
+    dotnet new mstest -o TestAI
+    ```
+
+1. Navigate to the `TestAI` directory, and add the necessary packages to your app:
+
+    ```dotnetcli
+    dotnet add package Microsoft.Extensions.AI.Ollama --prerelease
+    dotnet add package Microsoft.Extensions.AI.Abstractions --prerelease
+    dotnet add package Microsoft.Extensions.AI.Evaluation --prerelease
+    dotnet add package Microsoft.Extensions.AI.Evaluation.Quality --prerelease
+    ```
+
+1. Open the new app in your editor of choice, such as Visual Studio Code.
+
+    ```dotnetcli
+    code .
+    ```
+
+## Add the test app code
+
+1. Rename the file *Test1.cs* to *MyTests.cs*, and then open the file and rename the class to `MyTests`.
+1. Add the private <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration> and chat message and response members to the `MyTests` class. The `s_messages` field is a list that contains two <xref:Microsoft.Extensions.AI.ChatMessage> objects&mdash;one instructs the behavior of the chat bot, and the other is the question from the user.
+
+   :::code language="csharp" source="./snippets/evaluate-ai-responses/MyTests.cs" id="PrivateMembers":::
+
+1. Add the `InitializeAsync` method to the `MyTests` class.
+
+   :::code language="csharp" source="./snippets/evaluate-ai-responses/MyTests.cs" id="Initialize":::
+
+    This methods accomplishes the following tasks:
+
+   - Sets up the <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration>.
+   - Sets the <xref:Microsoft.Extensions.AI.ChatOptions>, including the <xref:Microsoft.Extensions.AI.ChatOptions.Temperature> and the <xref:Microsoft.Extensions.AI.ChatOptions.ResponseFormat>.
+   - Fetches the response to be evaluated by calling <xref:Microsoft.Extensions.AI.IChatClient.GetResponseAsync(System.Collections.Generic.IList{Microsoft.Extensions.AI.ChatMessage},Microsoft.Extensions.AI.ChatOptions,System.Threading.CancellationToken)>, and stores it in a static variable.
+
+1. Add the `GetOllamaChatConfiguration` method, which creates the <xref:Microsoft.Extensions.AI.IChatClient> that the evaluator uses to communicate with the model.
+
+   :::code language="csharp" source="./snippets/evaluate-ai-responses/MyTests.cs" id="GetChatConfig":::
+
+1. Add a test method to evaluate the model's response.
+
+   :::code language="csharp" source="./snippets/evaluate-ai-responses/MyTests.cs" id="TestCoherence":::
+
+   This method does the following:
+
+   - Invokes the <xref:Microsoft.Extensions.AI.Evaluation.Quality.CoherenceEvaluator> to evaluate the *coherence* of the response. The <xref:Microsoft.Extensions.AI.Evaluation.IEvaluator.EvaluateAsync(System.Collections.Generic.IEnumerable{Microsoft.Extensions.AI.ChatMessage},Microsoft.Extensions.AI.ChatMessage,Microsoft.Extensions.AI.Evaluation.ChatConfiguration,System.Collections.Generic.IEnumerable{Microsoft.Extensions.AI.Evaluation.EvaluationContext},System.Threading.CancellationToken)> method returns an <xref:Microsoft.Extensions.AI.Evaluation.EvaluationResult> that contains a <xref:Microsoft.Extensions.AI.Evaluation.NumericMetric>. A `NumericMetric` contains a numeric value that's typically used to represent numeric scores that fall within a well-defined range.
+   - Retrieves the coherence score from the <xref:Microsoft.Extensions.AI.Evaluation.EvaluationResult>.
+   - Validates the *default interpretation* for the returned coherence metric. Evaluators can include a default interpretation for the metrics they return. You can also change the default interpretation to suit your specific requirements, if needed.
+   - Validates that no diagnostics are present on the returned coherence metric. Evaluators can include diagnostics on the metrics they return to indicate errors, warnings, or other exceptional conditions encountered during evaluation.
+
+## Run the test/evaluation
+
+Run the test using your preferred test workflow, for example, by using the CLI command `dotnet test` or through [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer).
+
+## Next steps
+
+Next, try evaluating against different models to see if the results change. Then, check out the extensive examples in the [dotnet/ai-samples repo](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/) to see how to invoke multiple evaluators, add additional context, invoke a custom evaluator, attach diagnostics, or change the default interpretation of metrics.

docs/ai/quickstarts/quickstart-openai-generate-images.md → docs/ai/quickstarts/generate-images.md

@@ -144,5 +144,5 @@ azd down
 
 ## Next steps
 
-- [Quickstart - Build an AI chat app with .NET](get-started-openai.md)
+- [Quickstart - Build an AI chat app with .NET](/dotnet/ai/quickstarts/build-chat-app)
 - [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

docs/ai/quickstarts/includes/clone-sample-repo.md

@@ -7,7 +7,7 @@ ms.topic: include
 
 ## 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.
+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.
 
 ```bash
 git clone https://github.com/dotnet/ai-samples.git

docs/ai/quickstarts/quickstart-openai-summarize-text.md → docs/ai/quickstarts/prompt-model.md

@@ -153,5 +153,5 @@ azd down
 
 ## Next steps
 
-- [Quickstart - Build an AI chat app with .NET](get-started-openai.md)
+- [Quickstart - Build an AI chat app with .NET](/dotnet/ai/quickstarts/build-chat-app)
 - [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

docs/ai/quickstarts/snippets/evaluate-ai-responses/MyTests.cs

@@ -0,0 +1,85 @@
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Evaluation;
+using Microsoft.Extensions.AI.Evaluation.Quality;
+
+namespace TestAI;
+
+[TestClass]
+public sealed class MyTests
+{
+    // <SnippetPrivateMembers>
+    private static ChatConfiguration? s_chatConfiguration;
+    private static IList<ChatMessage> s_messages = [
+    new ChatMessage(
+            ChatRole.System,
+            """
+            You're an AI assistant that can answer questions related to astronomy.
+            Keep your responses concise and try to stay under 100 words.
+            Use the imperial measurement system for all measurements in your response.
+            """),
+        new ChatMessage(
+            ChatRole.User,
+            "How far is the planet Venus from Earth at its closest and furthest points?")];
+    private static ChatMessage s_response = new();
+    // </SnippetPrivateMembers>
+
+    // <SnippetInitialize>
+    [ClassInitialize]
+    public static async Task InitializeAsync(TestContext _)
+    {
+        /// Set up the <see cref="ChatConfiguration"/>,
+        // which includes the <see cref="IChatClient"/> that the
+        /// evaluator uses to communicate with the model.
+        s_chatConfiguration = GetOllamaChatConfiguration();
+
+        var chatOptions =
+            new ChatOptions
+            {
+                Temperature = 0.0f,
+                ResponseFormat = ChatResponseFormat.Text
+            };
+
+        /// Fetch the response to be evaluated
+        // and store it in a static variable.
+        ChatResponse response = await s_chatConfiguration.ChatClient.GetResponseAsync(s_messages, chatOptions);
+        s_response = response.Message;
+    }
+    // </SnippetInitialize>
+
+    // <SnippetGetChatConfig>
+    private static ChatConfiguration GetOllamaChatConfiguration()
+    {
+        /// Get a chat client for the Ollama endpoint.
+        IChatClient client =
+            new OllamaChatClient(
+                new Uri("http://localhost:11434"),
+                modelId: "phi3:mini");
+
+        return new ChatConfiguration(client);
+    }
+    // </SnippetGetChatConfig>
+
+    // <SnippetTestCoherence>
+    [TestMethod]
+    public async Task TestCoherence()
+    {
+        IEvaluator coherenceEvaluator = new CoherenceEvaluator();
+        EvaluationResult result = await coherenceEvaluator.EvaluateAsync(
+            s_messages,
+            s_response,
+            s_chatConfiguration);
+
+        /// Retrieve the score for coherence from the <see cref="EvaluationResult"/>.
+        NumericMetric coherence = result.Get<NumericMetric>(CoherenceEvaluator.CoherenceMetricName);
+
+        /// Validate the default interpretation
+        // for the returned coherence metric.
+        Assert.IsFalse(coherence.Interpretation!.Failed);
+        Assert.IsTrue(coherence.Interpretation.Rating is EvaluationRating.Good or EvaluationRating.Exceptional);
+
+        // Validate that no diagnostics are present
+        // on the returned coherence metric.
+        Assert.IsFalse(coherence.ContainsDiagnostics());
+    }
+    // </SnippetTestCoherence>
+}