[Agent的评估-03]利用LocalEvaluator自定义逻辑评估MAF Agent

JaydenAI

270人浏览 · 2026-07-30 08:20:23

JaydenAI · 2026-07-30 08:20:23 发布

MAF的Agent评估体系以IAgentEvaluator为核心，作为该接口的三个原生实现之一，LocalEvaluator运行我们在本地定义符合签名的委托来对AIAgent实施评估。原则上我们可利用这种方式实现任意评估逻辑。我们就来看看LocalEvaluator背后是如何驱动我们自定义的委托来评估指定的Agent。

1. EvalCheck委托

上述的用于评估Agent的委托类型为具有如下定义的EvalCheck。它的输入类型EvalItem是构成MAF Agent评估体系的三大核心元素之一，实施评估所需的所有信息都包括其中，在Agent的评估-02:MAF Agent评估系统三个核心要素中，我们已经对这个类型进行了深入介绍，这里就不再赘言了。

public delegate EvalCheckResult EvalCheck(EvalItem item);
public sealed record EvalCheckResult(bool Passed, string Reason, string CheckName);

利用EvalCheck实施评估的结果体现再返回的EvalCheckResult对象上，这个记录类型包含如下三个属性：

Passed：评估是否通过；
Reason：评估通过与否的原因；
CheckName：当前评估的名称，一般用于简单描述进行哪方面的评估。

2. EvalCheckResult向EvaluationMetric的转换

通过Agent的评估-02:MAF Agent评估系统三个核心要素的介绍，我们知道MAF的Agent评估体系利用AgentEvaluationResults来表示评估的结果，具体针对某项指标的评估结果通过EvaluationMetric类型表示。作为EvalCheck委托评估结果的EvalCheckResult最终需要转换成EvaluationMetric对象，并添加到EvaluationResult的Metrics字典中。

static EvaluationMetric Convert(EvalCheckResult evalCheckResult)
=> new BooleanMetric(evalCheckResult.CheckName, evalCheckResult.Passed, evalCheckResult.Reason)
    {
        Interpretation = new EvaluationMetricInterpretation
        {
            Rating = (evalCheckResult.Passed ? EvaluationRating.Good : EvaluationRating.Unacceptable),
            Failed = !evalCheckResult.Passed
        }
    };

上面定义的这个Convert方法基本上体现了EvalCheckResult向EvaluationMetric的转换规则。由于EvalCheckResult只能体现是否通过评估，所有最终转换生成的是一个评估指标值类型为布尔类型的BooleanMetric对象，EvalCheckResult对象的CheckName、Passed和Reason分别对应BooleanMetric的Name、Value和Reason属性。与此同时，还会为BooleanMetric对象的Interpretation属性设置一个EvaluationMetricInterpretation对象对评估结果作进一步解释，具体来说后者的两个属性会按照如下的规则进行设置：

Rating：如果EvalCheckResult的Passed属性为true，返回EvaluationRating.Good，否则返回EvaluationRating.Unacceptable；
Failed：EvalCheckResult的Passed属性取反；

3. LocalEvaluator的评估流程

如下所示的是LocalEvaluator类型的完整定义。可以看出它是对一组EvalCheck对象的封装，Name属性固定返回LocalEvaluator，实现的EvaluateAsync会将evalName参数默认设置为Local Eval

public sealed class LocalEvaluator : IAgentEvaluator
{
	private readonly EvalCheck[] _checks;
	public string Name => "LocalEvaluator";

	public LocalEvaluator(params EvalCheck[] checks)
	    =>_checks = checks;
	public Task<AgentEvaluationResults> EvaluateAsync(
        IReadOnlyList<EvalItem> items, 
        string evalName = "Local Eval", 
        CancellationToken cancellationToken = default(CancellationToken))
	{
		List<EvaluationResult> list = new List<EvaluationResult>(items.Count);
		foreach (EvalItem item in items)
		{
			cancellationToken.ThrowIfCancellationRequested();
			EvaluationResult evaluationResult = new EvaluationResult();
			EvalCheck[] checks = _checks;
			foreach (EvalCheck evalCheck in checks)
			{
				EvalCheckResult evalCheckResult = evalCheck(item);
				evaluationResult.Metrics[evalCheckResult.CheckName] = new BooleanMetric(
                    evalCheckResult.CheckName, 
                    evalCheckResult.Passed, 
                    evalCheckResult.Reason)
				{
					Interpretation = new EvaluationMetricInterpretation
					{
						Rating = (evalCheckResult.Passed ? EvaluationRating.Good : EvaluationRating.Unacceptable),
						Failed = !evalCheckResult.Passed
					}
				};
			}
			list.Add(evaluationResult);
		}
		return Task.FromResult(new AgentEvaluationResults(Name, list, items));
	}
}

实现在EvaluateAsync方法中的评估逻辑很简单：遍历每个EvalItem，并为之创建一个EvaluationResult对象，后者Metrics属性填充的EvaluationMetric由对应的EvalCheckResult根据上述的规则转换而成。至于EvalCheckResult，自然就是每个EvalCheck针对EvalItem实施评估的结果。

4. 预定义EvalCheck

Microsoft.Agents.AI.EvalChecks类型利用定义的一系列静态方法创建了对应的EvalCheck委托，我们可以直接拿来用。

4.1 关键字验证

EvalChecks利用如下所示的两个重载的KeywordCheck方法返回的EvalCheck用来验证Agent的响应文本是否包含指定的关键字。如代码所示，我们可以利用caseSensitive参数控制字符串比较是否考虑大小写，默认为大小写不敏感。只有响应文本包含所有指定的关键字，才算是评估通过。

public static class EvalChecks
{
    public static EvalCheck KeywordCheck(params string[] keywords);    
    public static EvalCheck KeywordCheck(bool caseSensitive, params string[] keywords);
}

如果评估通过，返回EvalCheckResult的Reason属性会说明所有的执行的关键字（依次列出）均已找到，否则会列出缺失的关键字。EvalCheckResult的Name固定返回keyword_check。

4.2 工具调用验证

如果需要评估规则要求指定的工具集必须被调用，则可以利用如下两个ToolCalledCheck方法重载，mode参数表示的ToolCalledMode枚举提供了两个选项，表示是要求指定的工具全部被调用还是说只需要其中有一个被调用就行，默认为前者。具体验证的工具名称列表通过toolNames参数指定。

public static class EvalChecks
{
    public static EvalCheck ToolCalledCheck(params string[] toolNames);
    public static EvalCheck ToolCalledCheck(ToolCalledMode mode, params string[] toolNames);
}

public enum ToolCalledMode
{
    All,
    Any,
}

我们知道利用提供的对话历史提取调用过的工具，只需要从消息的Contents属性中提取FunctionCallContent类型的内容就可以了，所以ToolCalledCheck方法会采用这种方式提取调用过的工具名称列表。作为验证结果的EvalCheckResul以tool_called_check命名。

如果不要求调用具体某个工具，只要求有过工具调用就行。比如只注册了一个工具，或者注册的工具具有很大的差异，不太可能选错，此时只需要有工具被调用就可以。这种情况可以使用如下这个ToolCallsPresent方法生成的EvalCheck委托。作为验证结果的EvalCheckResul以tool_calls_present命名。

public static class EvalChecks
{
    public static EvalCheck ToolCallsPresent();
}

通过Agent的评估-02:MAF Agent评估系统三个核心要素对EvalItem类型的介绍，我们知道该类型定义了一个ExpectedToolCalls属性返回一组ExpectedToolCall对象，用来设置希望LLM生成的工具调用。ExpectedToolCall不仅定义了希望调用的工具名名称，还定义以希望传入的参数列表。如果需要进行这样的评估，可以使用ToolCallArgsMatch方法返回的EvalCheck委托。作为验证结果的EvalCheckResul以tool_call_args_match命名。

public sealed class EvalItem
{	
	public IReadOnlyList<ExpectedToolCall>? ExpectedToolCalls { get; set; }
}
public record ExpectedToolCall(string Name, IReadOnlyDictionary<string, object>? Arguments = null);

public static class EvalChecks
{
    public static EvalCheck ToolCallArgsMatch();
}

4.3 响应文本长度的验证

如果不希望响应文本为空或者过短，可以使用如下这个NonEmpty方法返回的EvalCheck委托，参数minLength表示响应文本允许的最短长度。作为验证结果的EvalCheckResul以non_empty命名。

public static class EvalChecks
{
    public static EvalCheck NonEmpty(int minLength = 1)
}

4.4 希望输出内容验证

除了表示希望工具调用的ExpectedToolCalls属性，EvalItem还定义了如下这个用来表示希望响应文本中包含的输出内容。如果希望完成对用的评估，可以使用如下这个ContainsExpected方法返回的EvalCheck委托，参数caseSensitive表示在进行字符串比较中是否考虑大小写，默认为大小写不敏感。作为验证结果的EvalCheckResul以contains_expected命名。

public sealed class EvalItem
{
	public string? ExpectedOutput { get; set; }
}

public static class EvalChecks
{
    public static EvalCheck ContainsExpected(bool caseSensitive = false)
}

4.4 多媒体内容验证

在一些针对图像处理的应用场景中，有时候要求对话历史中必须包含具有图片内容的消息，这是可以使用HasImageContent方法生成的EvalCheck。因为EvalItem的HasImageContent属性对此做出判断，所以评估是否通过完全取决于此属性的值。作为验证结果的EvalCheckResul以has_image_content命名。


public sealed class EvalItem
{
	 public bool HasImageContent =>
     this.Conversation.Any(m =>
         m.Contents.Any(c =>
             (c is DataContent dc && dc.HasTopLevelMediaType("image"))
             || (c is UriContent uc && uc.HasTopLevelMediaType("image"))));
}

public static class EvalChecks
{
    public static EvalCheck HasImageContent()
}

5. 实例演示

下面的程序演示一个相对完整的例子。如代码所示，我们为创建的Agent注册了两个工具函数：

GetLocationCode：根据城市名车查询位置代码；
GetWeather：根据城市位置代码获取实时天气。

在调用Agent的EvaluateAsync扩展方法进行评估时，我们使用了LocalEvaluator作为唯一的评估器，并指定了通过调用ContainsExpected、ToolCallArgsMatch、ToolCalledCheck和KeywordCheck方法创建的四个EvalCheck委托，我们使用它们对工具调用和输出的内容进行评估。与ContainsExpected和ToolCallArgsMatch配套，我们还指定了expectedOutput和expectedToolCalls两个参数。

using Azure.AI.Projects;
using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.AI.Evaluation;
using OpenAI;
using System.ClientModel;
using System.ComponentModel;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.Json.Serialization;

Env.Load();
var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
var endpoint = Environment.GetEnvironmentVariable("OPENAI_BASE_URL")!;
List<AITool> tools = [
    AIFunctionFactory.Create(GetLocationCode, nameof(GetLocationCode)),
    AIFunctionFactory.Create(GetWeather, nameof(GetWeather))];
var agent = new OpenAIClient(new ApiKeyCredential(apiKey), new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
    .GetChatClient(model: "gpt-5.4-mini")
    .AsIChatClient()
    .AsAIAgent(tools:tools);

var results = await agent.EvaluateAsync(
    queries: ["目前苏州天气如何?"],
    evaluator: new LocalEvaluator(
        EvalChecks.ToolCallArgsMatch(),
        EvalChecks.ToolCalledCheck(nameof(GetLocationCode),nameof(GetWeather)),
        EvalChecks.KeywordCheck("晴","25")),
    expectedOutput: ["晴"],
    expectedToolCalls: [[
            new ExpectedToolCall(nameof(GetLocationCode), new Dictionary<string, object>{ { "city", "苏州" } }),
            new ExpectedToolCall(nameof(GetWeather), new Dictionary<string, object>{ { "locationCode", "123456" } })]]);

var serializerOptions = new JsonSerializerOptions
{
    WriteIndented = true,
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};
serializerOptions.Converters.Add(new JsonStringEnumConverter());
Console.WriteLine(JsonSerializer.Serialize(results.Items.Single().Metrics, serializerOptions));

[Description("获取所在城市的位置代码")] 
static string GetLocationCode([Description("城市名称")]string city) => "123456";

[Description("获取所在城市的实时天气")]
static string GetWeather([Description("城市位置代码")]string locationCode) => "晴，气温25摄氏度";

我只输出包含在验证结果中最核心的评估指标。从如下的输出内容可看出，与指定的四个EvalCheck委托对应的评估指标全部通过。

{
  "contains_expected": {
    "$type": "boolean",
    "Value": true,
    "Name": "contains_expected",
    "Reason": "Response contains expected output: \"晴\"",
    "Interpretation": {
      "Rating": "Good",
      "Failed": false,
      "Reason": null
    },
    "Context": null,
    "Diagnostics": null,
    "Metadata": null
  },
  "tool_call_args_match": {
    "$type": "boolean",
    "Value": true,
    "Name": "tool_call_args_match",
    "Reason": "Tool call args match: 2/2\n  GetLocationCode: args match\n  GetWeather: args match",
    "Interpretation": {
      "Rating": "Good",
      "Failed": false,
      "Reason": null
    },
    "Context": null,
    "Diagnostics": null,
    "Metadata": null
  },
  "tool_called_check": {
    "$type": "boolean",
    "Value": true,
    "Name": "tool_called_check",
    "Reason": "All tools called: GetLocationCode, GetWeather",
    "Interpretation": {
      "Rating": "Good",
      "Failed": false,
      "Reason": null
    },
    "Context": null,
    "Diagnostics": null,
    "Metadata": null
  },
  "keyword_check": {
    "$type": "boolean",
    "Value": true,
    "Name": "keyword_check",
    "Reason": "All keywords found: 晴, 25",
    "Interpretation": {
      "Rating": "Good",
      "Failed": false,
      "Reason": null
    },
    "Context": null,
    "Diagnostics": null,
    "Metadata": null
  }
}