Microsoft.Extensions.AI.Evaluation 库

Microsoft。Extensions.AI.Evaluation 库简化了在 .NET 智能应用中评估 AI 模型生成的响应的质量和安全性的过程。 各种质量指标衡量响应的相关性、真实性、一致性和完整性等方面。 安全指标衡量仇恨和不公平、暴力和性内容等方面。 评估在测试中至关重要，因为它们有助于确保 AI 模型按预期执行，并提供可靠且准确的结果。

基于 Microsoft.Extensions.AI 抽象生成的评估库由以下 NuGet 包组成：

测试集成

这些库与现有.NET应用顺利集成，使你能够使用现有的测试基础结构和熟悉的语法来评估智能应用。 可以使用任何测试框架（例如 MSTest、 xUnit 或 NUnit）和测试工作流（例如 测试资源管理器、 dotnet 测试或 CI/CD 管道）。 该库还提供简单的方法，通过向遥测和监视仪表板发布评估分数来对应用程序进行联机评估。

综合评估指标

评估库是与来自Microsoft和GitHub的数据科学研究人员合作构建的，并在流行的Microsoft Copilot体验上进行了测试。 以下部分显示了内置的 质量、 NLP和安全评估 程序及其度量指标。

若要添加自己的评估，请实现 IEvaluator 接口。

质量评估器

质量评估人员测量响应质量。 它们使用 LLM 来执行评估。

评估器类型 指标 Description
RelevanceEvaluator Relevance 评估响应与查询的相关性
CompletenessEvaluator Completeness 评估响应的综合性和准确程度
RetrievalEvaluator Retrieval 评估在检索附加上下文信息时的性能
FluencyEvaluator Fluency 评估语法准确性、词汇范围、句子复杂性和整体可读性
CoherenceEvaluator Coherence 对思想的逻辑性和有序性的呈现进行评估
EquivalenceEvaluator Equivalence 评估生成的文本与其真实数据在查询方面的相似性
GroundednessEvaluator Groundedness 评估生成的响应与给定上下文的对齐程度
RelevanceTruthAndCompletenessEvaluator† Relevance (RTC)、Truth (RTC) 和 Completeness (RTC) 评估响应的相关、真实和完成程度
IntentResolutionEvaluator Intent Resolution 评估 AI 系统在识别和解决用户意向时的有效性（以代理为中心的）
TaskAdherenceEvaluator Task Adherence 评估 AI 系统在遵守分配给 AI 系统的任务时的有效性（以代理为重点）
ToolCallAccuracyEvaluator Tool Call Accuracy 评估 AI 系统使用提供给它的工具的有效性（以代理为中心的）

此评估器标记为实验性。

NLP评估者

NLP 计算器通过使用自然语言处理 （NLP） 技术将其与引用响应进行比较来评估 LLM 响应的质量。 这些评估器不是 LLM 或基于 AI 的;而是使用较旧的 NLP 技术来执行文本比较。

评估器类型 指标 Description
BLEUEvaluator BLEU 通过使用双语评估 (BLEU) 算法将其与一个或多个引用响应进行比较来评估响应。 此算法通常用于评估机器翻译或文本生成任务的质量。
GLEUEvaluator GLEU 使用 Google BLEU （GLEU） 算法测量生成的响应与一个或多个引用响应之间的相似性，该算法是针对句子级评估优化的BLEU算法的变体。
F1Evaluator F1 通过使用 F1 评分算法将其与引用响应进行比较来评估响应（生成的响应与引用响应之间的共享单词数的比率）。

安全评估者

安全评估程序检查响应中是否存在有害、不当或不安全的内容。 它们依赖于 Foundry 评估服务，该服务使用经过微调的模型来执行评估。

评估器类型 指标 Description
GroundednessProEvaluator Groundedness Pro 使用 Foundry 评估服务后面托管的微调模型来评估生成的响应与给定上下文的一致程度
ProtectedMaterialEvaluator Protected Material 评估对受保护材料的存在性的响应
UngroundedAttributesEvaluator Ungrounded Attributes 评估响应中是否存在指示人类属性的不合理推断的内容
HateAndUnfairnessEvaluator Hate And Unfairness 评估响应中是否存在仇恨或偏袒的内容
SelfHarmEvaluator Self Harm 评估响应中是否存在表明自我伤害的内容
ViolenceEvaluator Violence 评估一个响应中是否存在暴力内容
SexualEvaluator Sexual 评估对色情内容的存在性的响应
CodeVulnerabilityEvaluator Code Vulnerability 评估响应中是否存在易受攻击的代码
IndirectAttackEvaluator Indirect Attack 评估响应中是否存在间接攻击，例如被篡改的内容、入侵和信息收集。

此外，ContentHarmEvaluator提供针对HateAndUnfairnessEvaluator、SelfHarmEvaluator、ViolenceEvaluator和SexualEvaluator支持的四个指标的单次评估。

缓存的响应

该库使用 响应缓存 功能在缓存中保留来自 AI 模型的响应。 在后续运行中，如果请求参数（提示和模型）保持不变，它将提供缓存的响应，以提高执行速度并降低成本。

报告

该库支持存储评估结果和生成报告。 下图显示了Azure DevOps管道中的示例报表：

Azure DevOps 管道中的 AI 评估报告截图

作为 dotnet aieval 包的一部分随附的 Microsoft.Extensions.AI.Evaluation.Console 工具包括生成报表和管理存储的评估数据和缓存响应的功能。 有关详细信息，请参阅 “生成报表”。

配置

库很灵活，你可以选取所需的组件。 例如，禁用响应缓存或定制报告，以便在环境中效果最佳。 还可以通过添加自定义指标和报告选项来自定义和配置评估。

用法示例

示例1： 快速入门：评估响应质量

这里将创建一个 MSTest 应用来评估 OpenAI 模型中聊天响应的质量。 测试应用使用 Microsoft.Extensions.AI.Evaluation 库。

  • 配置AI服务

    这里使用推理时代的coding-minimax-m3-free模型。

  • 创建测试应用

    完成以下步骤以创建连接到 AI 模型的 MSTest 项目。

    1. 在终端窗口中，导航到要在其中创建应用的目录，并使用 dotnet new 以下命令创建新的 MSTest 应用：

      1

      dotnet new mstest -o TestAI

    2. 导航到 TestAI 目录，并将必要的包添加到应用：

      1
2
3
4
5
6

      dotnet add package Microsoft.Extensions.AI.Abstractions
dotnet add package Microsoft.Extensions.AI.Evaluation
dotnet add package Microsoft.Extensions.AI.Evaluation.Quality
dotnet add package Microsoft.Extensions.AI.OpenAI
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

    3. 运行以下命令，为 OpenAI 终结点和租户 ID 添加 app secrets：

      1
2
3

      dotnet user-secrets init
dotnet user-secrets set OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
dotnet user-secrets set TENANT_ID <your-tenant-ID>

      （根据环境，可能不需要租户 ID。在这种情况下，请将其从实例化 DefaultAzureCredential 的代码中删除。）

    4. 在所选编辑器中打开新应用。

  • 添加测试应用代码

    1. 将 Test1.cs 文件重命名为 MyTests.cs，然后打开该文件并将类重命名为 MyTests。

    2. 将专用 ChatConfiguration 消息和聊天消息和响应成员添加到 MyTests 类。 该 s_messages 字段是一个包含两 ChatMessage 个对象的列表，一个对象指示聊天机器人的行为，另一个是用户的问题。

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

      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 ChatResponse s_response = new();

    3. 将 InitializeAsync 方法添加到 MyTests 类。

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

      [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 = GetAzureOpenAIChatConfiguration();

    var chatOptions =
        new ChatOptions
        {
            Temperature = 0.0f,
            ResponseFormat = ChatResponseFormat.Text
        };

    // Fetch the response to be evaluated
    // and store it in a static variable.
    s_response = await s_chatConfiguration.ChatClient.GetResponseAsync(s_messages, chatOptions);
}

      此方法完成以下任务：

    4. 添加GetAzureOpenAIChatConfiguration方法，该方法用于创建评估器与模型通信的IChatClient。

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

      private static ChatConfiguration GetAzureOpenAIChatConfiguration()
{
    IConfigurationRoot config = new ConfigurationBuilder().AddUserSecrets<MyTests>().Build();

    string endpoint = config["AZURE_OPENAI_ENDPOINT"];
    string tenantId = config["AZURE_TENANT_ID"];
    string model = "gpt-5";

    // Get a chat client for the Azure OpenAI endpoint.
    AzureOpenAIClient azureClient =
        new(
            new Uri(endpoint),
            new DefaultAzureCredential(new DefaultAzureCredentialOptions() { TenantId = tenantId }));
    IChatClient client = azureClient.GetChatClient(deploymentName: model).AsIChatClient();

    return new ChatConfiguration(client);
}

    5. 添加测试方法以评估模型的响应。

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

      [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());
}

      此方法执行以下操作：

      • 调用来评估响应的一致性。 该EvaluateAsync(IEnumerable, ChatResponse, ChatConfiguration, IEnumerable, CancellationToken)方法返回一个包含EvaluationResult的NumericMetric。 NumericMetric 包含一个数值，该值通常表示在明确范围内的数字分数。
      • 从 EvaluationResult 中检索一致性分数。
      • 验证返回的一致性指标 的默认解释 。 评估者可以为它们返回的指标提供默认解释。 还可以根据需要更改默认解释以满足特定要求。
      • 验证返回的一致性指标上不存在任何诊断。 评估者可以在返回的指标中包含诊断信息，以指示在评估期间遇到的错误、警告或其他异常情况。

      运行测试/评估

      使用首选测试工作流运行测试，例如，使用 CLI 命令 dotnet test 或通过 测试资源管理器运行测试。

1
2
3
4
5
6
7
8
9

PS D:\PROJECT\TestAI> dotnet test   
还原完成(0.4)
  TestAI net10.0 已成功 (0.3 秒) → bin\Debug\net10.0\TestAI.dll
已为 D:\PROJECT\TestAI\bin\Debug\net10.0\TestAI.dll 启用测试并行化(Workers: 16，Scope: MethodLevel)
  TestAI 测试 net10.0 已成功 (9.3 秒)

测试摘要: 总计: 1, 失败: 0, 成功: 1, 已跳过: 0, 持续时间: 9.3 秒
在 10.6 秒内生成 已成功
PS D:\PROJECT\TestAI>

示例2： 使用缓存和报告评估响应质量

这里主要相比上一个示例添加一个包。

1

dotnet add package Microsoft.Extensions.AI.Evaluation.Reporting

1
2

// The value of the TestContext property is populated by MSTest.
public TestContext? TestContext { get; set; }

  • 添加GetAzureOpenAIChatConfiguration方法，该方法用于创建评估器与模型通信的IChatClient。

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

    private static ChatConfiguration GetAzureOpenAIChatConfiguration()
{
    IConfigurationRoot config = new ConfigurationBuilder().AddUserSecrets<MyTests>().Build();

    string endpoint = config["AZURE_OPENAI_ENDPOINT"];
    string tenantId = config["AZURE_TENANT_ID"];
    string model = "gpt-5";

    // Get an instance of Microsoft.Extensions.AI's <see cref="IChatClient"/>
    // interface for the selected LLM endpoint.
    AzureOpenAIClient azureClient =
        new(
            new Uri(endpoint),
            new DefaultAzureCredential(new DefaultAzureCredentialOptions() { TenantId = tenantId }));
    IChatClient client = azureClient.GetChatClient(deploymentName: model).AsIChatClient();

    // Create an instance of <see cref="ChatConfiguration"/>
    // to communicate with the LLM.
    return new ChatConfiguration(client);
}

  • 设置报告功能

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

    private string ScenarioName => $"{TestContext!.FullyQualifiedTestClassName}.{TestContext.TestName}";

private static string ExecutionName => $"{DateTime.Now:yyyyMMddTHHmmss}";

private static readonly ReportingConfiguration s_defaultReportingConfiguration =
    DiskBasedReportingConfiguration.Create(
        storageRootPath: "C:\\TestReports",
        evaluators: GetEvaluators(),
        chatConfiguration: GetAzureOpenAIChatConfiguration(),
        enableResponseCaching: true,
        executionName: ExecutionName);

结果输出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

❌ FAILED: SampleAndEvaluateResponse (350ms)
   Assert.IsFalse failed. 'condition' expression: 'wordCount.Interpretation!.Failed'. This Words metric has a value of 116 because the evaluated model response contained 116 words.

========================================
Test Run Summary
========================================
Total Tests: 1
Passed: 0
Failed: 1
Skipped: 0
❌ Result: FAILED
Total Time (including build): 10.91s (10910ms)
========================================

示例3： 使用缓存和报告评估响应安全性

参考链接: https://learn.microsoft.com/zh-cn/dotnet/ai/evaluation/evaluate-safety