[MAF预定义的AIContextProvider-01]TextSearchProvider——RAG在MAF中的实现

作为最核心的AIAgent，ChatClientAgent构建了一个管道与LLM交互。为了让管道的输出更符合我们的需求，有两个主要的途径：输入增强（Input Enhancement）和输出增强（Output Enhancement），前者通过通过改变输入让LLM返回更高质量的内容，后者则直接对LLM的输出进行加工处理。个注册的AIContextProvider组成的管道位于ChatClientAgent管道的中间件部分（前后分别是AIAgent中间件管道和ChatClient管道），是专门为输入和输出增强设计的。RAG（Retrieval-Augmented Generation）的本质是根据当前上下文检索相关内容来丰富LLM的输入，是典型的输入增强的典型应用场景，它通过TextSearchProvider这个预定义的AIContextProvider实现。

1. 利用TextSearchProvider实现RAG

在介绍TextSearchProvider的设计和实现原理之前，我们先通过一个简单的例子来演示一下在MAF中如何使用TextSearchProvider实现RAG。首先来如下一个没有RAG的例子：我们根据OpenAIClient创建了一个ChatClientAgent，并直接调用它来回答一个问题：2026年斯诺克世界赛冠军是谁？

csharp 复制代码

using Azure.AI.Projects;
using dotenv.net;
using Microsoft.Extensions.AI;
using OpenAI;
using OpenAI.Responses;
using System.ClientModel;

DotEnv.Load();

var model = Environment.GetEnvironmentVariable("MODEL")!;
var apiKey = Environment.GetEnvironmentVariable("API_KEY")!;
var endpoint = Environment.GetEnvironmentVariable("OPENAI_URL")!;

var agent = new OpenAIClient(
    credential: new ApiKeyCredential(key: apiKey),
    options: new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
    .GetResponsesClient()
    .AsAIAgent(model: model);
var response = await agent.RunAsync(message:"2026年斯诺克世界赛冠军是谁？");
Console.WriteLine(response.Text);

输出：

markdown 复制代码

我目前**无法确定**2026年斯诺克世界锦标赛的冠军是谁。

原因是：
- 虽然按赛程来看，2026年世锦赛通常在**4月下旬至5月初**结束，但
- 我无法获取**实时或最新比赛结果**，而且不应在没有可靠数据的情况下猜测冠军。

你可以选择下面两种方式之一：
1. **如果你想要的是已产生的正式结果**：我可以告诉你去哪里快速核实（如世界斯诺克官网、BBC Sport、世界斯诺克巡回赛官方微博等）。
2. **如果你想要的是赛前或赛中的预测/分析**：我可以根据当时的世界排名、签表、球员状态，给你一个专业预测。

你是想问**"已经夺冠的是谁"**，还是**"你预测谁会夺冠"**？

由于知识固化的原因，LLM无法直接回答这个问题。解决这个问题有两种途径: 一种是通过工具（比如web-search）获取最新信息，另一种是通过RAG检索相关信息作为上下文来辅助LLM生成答案。下面我们通过TextSearchProvider来实现RAG：我们在调用AsAIAgent时，传入一个ChatClientAgentOptions对象，并将一个TextSearchProvider实例添加到AIContextProviders中。TextSearchProvider需要我们提供一个SearchAsync方法来实现具体的检索逻辑，我们让这个SearchAsync方法返回吴宜泽夺冠的一段新闻稿。

csharp 复制代码

using Azure.AI.Projects;
using dotenv.net;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;
using OpenAI.Responses;
using System.ClientModel;
using static Microsoft.Agents.AI.TextSearchProvider;

DotEnv.Load();

var model = Environment.GetEnvironmentVariable("MODEL")!;
var apiKey = Environment.GetEnvironmentVariable("API_KEY")!;
var endpoint = Environment.GetEnvironmentVariable("OPENAI_URL")!;

var textSearchProvider = new TextSearchProvider(searchAsync: SearchAsync);
var agent = new OpenAIClient(
    credential: new ApiKeyCredential(key: apiKey),
    options: new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
    .GetChatClient(model: model)
    .AsIChatClient()
    .AsAIAgent(options: new ChatClientAgentOptions { AIContextProviders = [textSearchProvider] });


var response = await agent.RunAsync(message: "2026年斯诺克世界赛冠军是谁？");
Console.WriteLine(response.Text);

static Task<IEnumerable<TextSearchResult>> SearchAsync(string query, CancellationToken cancellationToken)
{
    if (query.Contains("2026") && query.Contains("斯诺克") && query.Contains("世界赛"))
    {
        var news = """
北京时间2026年5月5日，英国谢菲尔德克鲁斯堡剧院，决胜局最后一颗黑球落袋后，00后中国球员吴宜泽挥拳庆祝。18:17，吴宜泽击败肖恩·墨菲，拿下2026年斯诺克世锦赛冠军。
社交平台上，"吴宜泽夺冠"迅速登上热搜，不少球迷将这场胜利形容为"中国斯诺克新的接力时刻"。这是继2025年赵心童夺冠之后，中国选手再次问鼎这项赛事最高荣誉。这也是在经历2023年前后相关禁赛与争议事件后，中国球员重新回到世界顶级竞争序列的重要节点。
相比十多年前，丁俊晖在斯诺克领域的单点突破，中国近几年开始稳定涌现世界级斯诺克选手。从个体突破到群体崛起，这项运动在中国已经进入新的发展阶段。
""";
        var result = new TextSearchResult
        {
            RawRepresentation = news,
            SourceLink = "https://baijiahao.baidu.com/s?id=1864605028122769594",
            SourceName = "每日经济新闻",
            Text = news
        };
        return Task.FromResult<IEnumerable<TextSearchResult>>([result]);
    }
    else
    {
        return Task.FromResult<IEnumerable<TextSearchResult>>([]);
    }
}

输出：

markdown 复制代码

2026年斯诺克世锦赛的冠军是**吴宜泽**。

他在北京时间 **2026年5月5日** 于英国谢菲尔德克鲁斯堡剧院举行的决赛中，击败了**肖恩·墨菲**，成功夺冠。这也是继2025年赵心童夺冠之后，中国选手连续第二年获得斯诺克世锦赛冠军。

2. 检索查询文本的状态存储

RAG应该根据当前上下文来检索相关内容，作为查询文本的不仅仅只考虑最近的用户消息，有时还应该考虑最近或者全部对话历史，也可以在此基础进行一些过滤。TextSearchProvider将作为检索的查询文本封装在TextSearchProviderState中，并存在在当前Session状态中。如下面的代码片段所示，TextSearchProviderState是定义在TextSearchProvider中的一个内嵌类性，RecentMessagesText属性存储的就是作为检索的查询文本。TextSearchProvider利用一个ProviderSessionState<TextSearchProviderState>对象来extSearchProviderState进行基于Session状态的读写，它在Session状态字典中的Key可以通过TextSearchProviderOptions进行配置，默认为TextSearchProvider的类名。

csharp 复制代码

public sealed class TextSearchProvider : MessageAIContextProvider
{
	public sealed class TextSearchProviderState
	{
		public List<string>? RecentMessagesText { get; set; }
	}

	private readonly ProviderSessionState<TextSearchProviderState> _sessionState;
	private IReadOnlyList<string>? _stateKeys;
    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
    public TextSearchProvider(
        Func<string, CancellationToken, Task<IEnumerable<TextSearchResult>>> searchAsync,
        TextSearchProviderOptions? options = null,
        ILoggerFactory? loggerFactory = null)
    : base(options?.SearchInputMessageFilter, options?.StorageInputRequestMessageFilter, options?.StorageInputResponseMessageFilter)
    {
        _sessionState = new ProviderSessionState<TextSearchProviderState>(
            _ => new TextSearchProviderState(),
            options?.StateKey ?? this.GetType().Name,
            AgentJsonUtilities.DefaultOptions);
        ...
    }
}

3. TextSearchProvider配置选项

TextSearchProvider相关的配置选项定义在TextSearchProviderOptions类中，前面已经提到过它的StateKey属性（存储查询文本的Session状态键），接下来我们看看它的其他配置选项。TextSearchProviderOptions最重要的配置选项莫过于SearchTime了，它不仅仅是决定了RAG检索的时机，更是决定了整个输入增强的实现方式。具体来说，如果SearchTime设置为BeforeAIInvoke，那么TextSearchProvider会在每次LLM调用之前自动进行文本检索，并将检索结果作为上下文提供给LLM；如果SearchTime设置为OnDemandFunctionCalling，那么TextSearchProvider会提供一个供LLM调用的工具来按需触发文本检索，LLM可以根据当前的查询条件来决定是否需要调用这个工具来获取相关信息。

csharp 复制代码

public sealed class TextSearchProviderOptions
{
	public enum TextSearchBehavior
	{
		BeforeAIInvoke,
		OnDemandFunctionCalling
	}

	public TextSearchBehavior SearchTime { get; set; } = TextSearchBehavior.BeforeAIInvoke;
	public string? FunctionToolName { get; set; }
	public string? FunctionToolDescription { get; set; }    
}

如果选择OnDemandFunctionCalling，那么我们需要通过FunctionToolName来指定这个工具的名称，通过FunctionToolDescription来描述这个工具的功能，以便LLM能够正确地调用它。默认的工具名称为Search，默认的工具描述为Allows searching for additional information to help answer the user question.。

如果对话历史太长，将整个对话内容作为检索的查询不但没有必要，还可能会导致检索效率低下。除此之外，过多的字符串拼接操作和过长的查询文本也可能会对LLM的性能产生负面影响。为了解决这个问题，TextSearchProviderOptions提供了RecentMessageMemoryLimit这个配置选项，来限制在进行文本检索时，应该考虑最近多少条消息。默认值为0，意味着只考虑最近输入的用户消息，不考虑任何历史消息。RecentMessageRolesIncluded可以从角色维度进一步细化应该考虑哪些消息，默认只考虑User角色的消息，因为RAG是为了解决LLM的知识局限性问题，无需考虑它的回答。当我们将LLM的响应作为RAG检索条件时，可能导致搜索结果过度向已知信息倾斜。

csharp 复制代码

public sealed class TextSearchProviderOptions
{
	public int RecentMessageMemoryLimit { get; set; }
    public List<ChatRole>? RecentMessageRolesIncluded { get; set; }

	public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? SearchInputMessageFilter { get; set; }
	public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? StorageInputRequestMessageFilter { get; set; }
	public Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? StorageInputResponseMessageFilter { get; set; }
}

TextSearchProviderOptions的三个Filter会提供给基类MessageAIContextProvider，在调用ProvideMessagesAsync方法之前，SearchInputMessageFilter会对请求消息进行过滤。StorageInputRequestMessageFilter和StorageInputResponseMessageFilter在调用StoreAIContextAsync方法之前会对待存储的请求和响应消息实施过滤。所以这三个Filter实际上是在对作为检索条件的消息进行过滤。

检索的结果作为上下文作为调用LLM提示词的一部分，我们可以利用TextSearchProviderOptions的ContextFormatter属性提供的委托自行完成针对这段文本的格式化。如果没有提供ContextFormatter委托，TextSearchProvider将会按照默认的格式来将检索结果转换成文本，这个文本会包含针对上下文提示词前缀和要求回答中携带引用的提示词，对应着ContextPrompt和CitationsPrompt这两个属性。ContextFormatter的输入是一个TextSearchResult的列表，而TextSearchResult作为检索的结果，不仅包含基本的文本内容（Text属性），还包含通过SourceName和SourceLink属性提供的元信息，前者可以用来描述这个文本内容的来源，后者则可以提供一个链接让用户能够访问到这个来源。RawRepresentation属性则可以用来存储一些原始的、未经格式化的表示，这些表示可能来自于数据源的底层对象模型。

csharp 复制代码

public sealed class TextSearchProviderOptions
{
	public string? ContextPrompt { get; set; }
	public string? CitationsPrompt { get; set; }
	public Func<IList<TextSearchProvider.TextSearchResult>, string>? ContextFormatter { get; set; }
}

public sealed class TextSearchProvider : MessageAIContextProvider
{
	public sealed class TextSearchResult
	{
		public string? SourceName { get; set; }
		public string? SourceLink { get; set; }
		public string Text { get; set; } = string.Empty;
		public object? RawRepresentation { get; set; }
	}
}

ContextPrompt和CitationsPrompt这两个属性的默认值分别为：

Consider the following information from source documents when responding to the user:
Include citations to the source document with document name and link if document name and link is available.。

由于RAG检索的内容主要来源于私域系统，这些内容可能包含敏感信息，因此在日志和遥测中需要对这些信息进行脱敏处理。TextSearchProviderOptions提供了EnableSensitiveTelemetryData和Redactor这两个配置选项来支持我们对敏感信息进行保护。EnableSensitiveTelemetryData是一个开关，用来控制是否允许在遥测数据中包含敏感信息；Redactor则是一个Redactor对象，它提供了对敏感信息进行脱敏处理的方法，在日志和遥测中会调用这个对象的方法来对敏感信息进行脱敏。

csharp 复制代码

public sealed class TextSearchProviderOptions
{
	
	public bool EnableSensitiveTelemetryData { get; set; }
	public Redactor? Redactor { get; set; }
}

public abstract class Redactor
{
	public unsafe string Redact(ReadOnlySpan<char> source);
	public abstract int Redact(ReadOnlySpan<char> source, Span<char> destination);
	public int Redact(string? source, Span<char> destination);
	public virtual string Redact(string? source);
	public unsafe string Redact<T>(T value, string? format = null, IFormatProvider? provider = null);
	public int Redact<T>(T value, Span<char> destination, string? format = null, IFormatProvider? provider = null);
	public bool TryRedact<T>(T value, Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider = null);
	public abstract int GetRedactedLength(ReadOnlySpan<char> input);
	public int GetRedactedLength(string? input);
}

4. TextSearchProvider的实现原理

TextSearchProvider针对RAG的实现其实很简单。在重写的ProvideAIContextAsync方法中，如果配置选项SearchTime为OnDemandFunctionCalling，它会创建一个用于检索的工具注册到返回的AIConext中。如果SearchTime为BeforeAIInvoke，它会调用ProvideMessagesAsync方法返回的消息作为AIContext的Messages属性。

csharp 复制代码

public sealed class TextSearchProvider : MessageAIContextProvider
{    
    public TextSearchProvider(
        Func<string, CancellationToken, Task<IEnumerable<TextSearchResult>>> searchAsync,
        TextSearchProviderOptions? options = null,
        ILoggerFactory? loggerFactory = null);
    protected override async ValueTask<AIContext> ProvideAIContextAsync(
        AIContextProvider.InvokingContext context, 
        CancellationToken cancellationToken = default);
    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideMessagesAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);
    protected override ValueTask StoreAIContextAsync(
        InvokedContext context, 
        CancellationToken cancellationToken = default);
}

重写的ProvideMessagesAsync会按照如下的逻辑执行：

从当前Session状态中提取TextSearchProviderState对象，并从中获取RecentMessagesText属性作为检索的查询文本列表，此列表会与当前请求的消息文本进行合并，生成最终的检索查询文本列表；
这个列表最终被拼接（采用回车作为分隔符）成一个字符串，作为构造函数指定的searchAsync委托的输入参数来实施检索，并得到一个TextSearchResult的列表作为检索结果；
如果配置选项ContextFormatter提供了委托，那么就调用这个委托来将TextSearchResult的列表转换成一个字符串；如果没有提供ContextFormatter委托，那么就采用默认的格式化方式来将TextSearchResult的列表转换成一个字符串，这个字符串会包含ContextPrompt和CitationsPrompt这两个提示词，以及检索结果的文本内容和来源信息；
格式化后的字符串会被封装在一个User角色的ChatMessage中，并作为一个单元素的列表返回，供ProvideAIContextAsync方法将其作为AIContext的一部分返回；

在重写的StoreAIContextAsync方法中，如果当前Session存在并且配置选项RecentMessageMemoryLimit大于0，它会按照如下的方式在Session状态中更新查询文本列表：

从当前Session状态中提取TextSearchProviderState对象，并从中获取RecentMessagesText属性作为当前的查询文本列表；
根据配置选项RecentMessageRolesIncluded来过滤当前请求的消息和LLM的响应消息，得到一个新的消息列表，并将消息文本提取出来；
原始的查询文本列表和新提取的消息文本列表进行合并，并根据配置选项RecentMessageMemoryLimit来限制对列表进行裁剪，得到一个新的查询文本列表；
将新的查询文本列表更新到当前Session状态的TextSearchProviderState对象的RecentMessagesText属性中，以供下一次检索使用。

5. 查看生成的工具

我们不妨看看基于RAG检索结果生成的ChatMessage具体包含什么内容，以及如果将SearchTime配置为OnDemandFunctionCalling，TextSearchProvider生成的工具又是什么样子的。为此，我们定义了如下这个AIContextTrackingProvider，它继承自AIContextProvider，并重写了InvokingCoreAsync方法，在这个方法中我们可以访问到当前调用的AIContext，从而查看其中包含的Messages和Tools等信息。

csharp 复制代码

class AIContextTrackingProvider: AIContextProvider
{
    protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
    {
        var index = 1;
        foreach(var message in context.AIContext?.Messages!)
        {
           Console.WriteLine($"""
               {new string('-', 20)} Message {index++} {new string('-', 20)}
               Role: {message.Role}
               Text:                
               {message.Text}
               """);
        }

        var function = context.AIContext?.Tools?.SingleOrDefault(tool => tool.Name == "Search") as AIFunction;
        if (function is not null)
        {
            Console.WriteLine($"""

                {new string('-', 20)} Tool {function.Name} {new string('-', 20)}
                Description: {function.Description}
                JsonSchema: {function.JsonSchema}
                """);
        }
        return base.InvokingCoreAsync(context, cancellationToken);
    }
}

我们将这个AIContextTrackingProvider和TextSearchProvider一起添加到ChatClientAgent的AIContextProviders中。由于我们希望查看的是由TextSearchProvider生成的工具或者消息，所以我们需要将AIContextTrackingProvider放在TextSearchProvider的后面。

csharp 复制代码

using Azure.AI.Projects;
using dotenv.net;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;
using OpenAI.Responses;
using System.ClientModel;
using static Microsoft.Agents.AI.TextSearchProvider;

DotEnv.Load();

var model = Environment.GetEnvironmentVariable("MODEL")!;
var apiKey = Environment.GetEnvironmentVariable("API_KEY")!;
var endpoint = Environment.GetEnvironmentVariable("OPENAI_URL")!;
var textSearchProvider = new TextSearchProvider(searchAsync: SearchAsync);
var trackingProvider = new AIContextTrackingProvider();
var agent = new OpenAIClient(
    credential: new ApiKeyCredential(key: apiKey),
    options: new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
    .GetChatClient(model: model)
    .AsIChatClient()
    .AsAIAgent(options: new ChatClientAgentOptions { AIContextProviders = [textSearchProvider, trackingProvider] });

await agent.RunAsync(message: "2026年斯诺克世界赛冠军是谁？");

static Task<IEnumerable<TextSearchResult>> SearchAsync(string query, CancellationToken cancellationToken)
{
    if (query.Contains("2026") && query.Contains("斯诺克") && query.Contains("世界赛"))
    {
        var news = """
北京时间2026年5月5日，英国谢菲尔德克鲁斯堡剧院，决胜局最后一颗黑球落袋后，00后中国球员吴宜泽挥拳庆祝。18:17，吴宜泽击败肖恩·墨菲，拿下2026年斯诺克世锦赛冠军。
社交平台上，"吴宜泽夺冠"迅速登上热搜，不少球迷将这场胜利形容为"中国斯诺克新的接力时刻"。这是继2025年赵心童夺冠之后，中国选手再次问鼎这项赛事最高荣誉。这也是在经历2023年前后相关禁赛与争议事件后，中国球员重新回到世界顶级竞争序列的重要节点。
相比十多年前，丁俊晖在斯诺克领域的单点突破，中国近几年开始稳定涌现世界级斯诺克选手。从个体突破到群体崛起，这项运动在中国已经进入新的发展阶段。
""";
        var result = new TextSearchResult
        {
            RawRepresentation = news,
            SourceLink = "https://baijiahao.baidu.com/s?id=1864605028122769594",
            SourceName = "每日经济新闻",
            Text = news
        };
        return Task.FromResult<IEnumerable<TextSearchResult>>([result]);
    }
    else
    {
        return Task.FromResult<IEnumerable<TextSearchResult>>([]);
    }
}

输出（第二条就是基于RAG检索结果生成的消息）：

markdown 复制代码

-------------------- Message 1 --------------------
Role: user
Text:


2026年斯诺克世界赛冠军是谁？

-------------------- Message 2 --------------------
Role: user
Text:

## Additional Context

Consider the following information from source documents when responding to the user:
SourceDocName: 每日经济新闻
SourceDocLink: https://baijiahao.baidu.com/s?id=1864605028122769594
Contents: 北京时间2026年5月5日，英国谢菲尔德克鲁斯堡剧院，决胜局最后一颗黑球落袋后，00后中国球员吴宜泽挥拳庆祝。18:17，吴宜泽击败肖恩·墨菲，拿下2026年斯诺克世锦赛冠军。
社交平台上，"吴宜泽夺冠"迅速登上热搜，不少球迷将这场胜利形容为"中国斯诺克新的接力时刻"。这是继2025年赵心童夺冠之后，中国选手再次问鼎这项赛事最高荣誉。这也是在经历2023年前后相关禁赛与争议事件后，中国球员重新回到世界顶级竞争序列的重要节点。
相比十多年前，丁俊晖在斯诺克领域的单点突破，中国近几年开始稳定涌现世界级斯诺克选手。从个体突破到群体崛起，这项运动在中国已经进入新的发展阶段。
----

Include citations to the source document with document name and link if document name and link is available.

为了查看AIContextTrackingProvider生成的用于上下文检索的工具，我们需要提供AIContextTrackingProviderOptions来创建AIContextTrackingProvider，并将SearchTime配置为OnDemandFunctionCalling。

csharp 复制代码

DotEnv.Load();

var model = Environment.GetEnvironmentVariable("MODEL")!;
var apiKey = Environment.GetEnvironmentVariable("API_KEY")!;
var endpoint = Environment.GetEnvironmentVariable("OPENAI_URL")!;
var options = new TextSearchProviderOptions { 
    SearchTime = TextSearchProviderOptions.TextSearchBehavior.OnDemandFunctionCalling };
var textSearchProvider = new TextSearchProvider(searchAsync: SearchAsync, options: options);
var trackingProvider = new AIContextTrackingProvider();
var agent = new OpenAIClient(
    credential: new ApiKeyCredential(key: apiKey),
    options: new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
    .GetChatClient(model: model)
    .AsIChatClient()
    .AsAIAgent(options: new ChatClientAgentOptions { AIContextProviders = [textSearchProvider, trackingProvider] });

await agent.RunAsync(message: "2026年斯诺克世界赛冠军是谁？");
...

输出：

markdown 复制代码

-------------------- Message 1 --------------------
Role: user
Text:
2026年斯诺克世界赛冠军是谁？

-------------------- Tool Search --------------------
Description: Allows searching for additional information to help answer the user question.
JsonSchema: {"type":"object","properties":{"userQuestion":{"type":"string"}},"required":["userQuestion"]}