|
| 1 | +--- |
| 2 | +title: The Microsoft.Extensions.AI.Evaluation libraries |
| 3 | +description: Learn about the Microsoft.Extensions.AI.Evaluation libraries, which simplify the process of evaluating the quality and accuracy of responses generated by AI models in .NET intelligent apps. |
| 4 | +ms.topic: concept-article |
| 5 | +ms.date: 02/19/2025 |
| 6 | +--- |
| 7 | +# The Microsoft.Extensions.AI.Evaluation libraries (Preview) |
| 8 | + |
| 9 | +The Microsoft.Extensions.AI.Evaluation libraries (currently in preview) simplify the process of evaluating the quality and accuracy of responses generated by AI models in .NET intelligent apps. Various metrics measure aspects like relevance, truthfulness, coherence, and completeness of the responses. Evaluations are crucial in testing, because they help ensure that the AI model performs as expected and provides reliable and accurate results. |
| 10 | + |
| 11 | +The evaluation libraries, which are built on top of the [Microsoft.Extensions.AI abstractions](../ai-extensions.md), are composed of the following NuGet packages: |
| 12 | + |
| 13 | +- [📦 Microsoft.Extensions.AI.Evaluation](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation) – Defines the core abstractions and types for supporting evaluation. |
| 14 | +- [📦 Microsoft.Extensions.AI.Evaluation.Quality](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Quality) – Contains evaluators that assess the quality of LLM responses in an app according to metrics such as relevance, fluency, coherence, and truthfulness. |
| 15 | +- [📦 Microsoft.Extensions.AI.Evaluation.Reporting](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Reporting) – Contains support for caching LLM responses, storing the results of evaluations, and generating reports from that data. |
| 16 | +- [📦 Microsoft.Extensions.AI.Evaluation.Reporting.Azure](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Reporting.Azure) - Supports the reporting library with an implementation for caching LLM responses and storing the evaluation results in an [Azure Storage](/azure/storage/common/storage-introduction) container. |
| 17 | +- [📦 Microsoft.Extensions.AI.Evaluation.Console](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Console) – A command-line tool for generating reports and managing evaluation data. |
| 18 | + |
| 19 | +## Test integration |
| 20 | + |
| 21 | +The libraries are designed to integrate smoothly with existing .NET apps, allowing you to leverage existing testing infrastructures and familiar syntax to evaluate intelligent apps. You can use any test framework (for example, [MSTest](../../core/testing/index.md#mstest), [xUnit](../../core/testing/index.md#xunit), or [NUnit](../../core/testing/index.md#nunit)) and testing workflow (for example, [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer), [dotnet test](../../core/tools/dotnet-test.md), or a CI/CD pipeline). The library also provides easy ways to do online evaluations of your application by publishing evaluation scores to telemetry and monitoring dashboards. |
| 22 | + |
| 23 | +## Comprehensive evaluation metrics |
| 24 | + |
| 25 | +The evaluation libraries were built in collaboration with data science researchers from Microsoft and GitHub, and were tested on popular Microsoft Copilot experiences. The following table shows the built-in evaluators. |
| 26 | + |
| 27 | +| Metric | Description | Evaluator type | |
| 28 | +|------------------------------------|----------------------------------------------|----------------| |
| 29 | +| Relevance, truth, and completeness | How effectively a response addresses a query | <xref:Microsoft.Extensions.AI.Evaluation.Quality.RelevanceTruthAndCompletenessEvaluator> | |
| 30 | +| Fluency | Grammatical accuracy, vocabulary range, sentence complexity, and overall readability| <xref:Microsoft.Extensions.AI.Evaluation.Quality.FluencyEvaluator> | |
| 31 | +| Coherence | The logical and orderly presentation of ideas | <xref:Microsoft.Extensions.AI.Evaluation.Quality.CoherenceEvaluator> | |
| 32 | +| Equivalence | The similarity between the generated text and its ground truth with respect to a query | <xref:Microsoft.Extensions.AI.Evaluation.Quality.EquivalenceEvaluator> | |
| 33 | +| Groundedness | How well a generated response aligns with the given context | <xref:Microsoft.Extensions.AI.Evaluation.Quality.GroundednessEvaluator> | |
| 34 | + |
| 35 | +You can also customize to add your own evaluations by implementing the <xref:Microsoft.Extensions.AI.Evaluation.IEvaluator> interface or extending the base classes such as <xref:Microsoft.Extensions.AI.Evaluation.Quality.ChatConversationEvaluator> and <xref:Microsoft.Extensions.AI.Evaluation.Quality.SingleNumericMetricEvaluator>. |
| 36 | + |
| 37 | +## Cached responses |
| 38 | + |
| 39 | +The library uses *response caching* functionality, which means responses from the AI model are persisted in a cache. In subsequent runs, if the request parameters (prompt and model) are unchanged, responses are then served from the cache to enable faster execution and lower cost. |
| 40 | + |
| 41 | +## Reporting |
| 42 | + |
| 43 | +The library contains support for storing evaluation results and generating reports. The following image shows an example report in an Azure DevOps pipeline: |
| 44 | + |
| 45 | +:::image type="content" source="../media/ai-extensions/pipeline-report.jpg" lightbox="../media/ai-extensions/pipeline-report.jpg" alt-text="Screenshot of an AI evaluation report in an Azure DevOps pipeline."::: |
| 46 | + |
| 47 | +The `dotnet aieval` tool, which ships as part of the `Microsoft.Extensions.AI.Evaluation.Console` package, also includes functionality for generating reports and managing the stored evaluation data and cached responses. |
| 48 | + |
| 49 | +## Configuration |
| 50 | + |
| 51 | +The libraries are designed to be flexible. You can pick the components that you need. For example, you can disable response caching or tailor reporting to work best in your environment. You can also customize and configure your evaluations, for example, by adding customized metrics and reporting options. |
| 52 | + |
| 53 | +## Samples |
| 54 | + |
| 55 | +For a more comprehensive tour of the functionality and APIs available in the Microsoft.Extensions.AI.Evaluation libraries, see the [API usage examples (dotnet/ai-samples repo)](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/). These examples are structured as a collection of unit tests. Each unit test showcases a specific concept or API and builds on the concepts and APIs showcased in previous unit tests. |
| 56 | + |
| 57 | +## See also |
| 58 | + |
| 59 | +- [Evaluation of generative AI apps (Azure AI Foundry)](/azure/ai-studio/concepts/evaluation-approach-gen-ai) |
0 commit comments