利用TextSearchProvider实现RAG在介绍TextSearchProvider的设计和实现原理之前我们先通过一个简单的例子来演示一下在MAF中如何使用TextSearchProvider实现RAG。首先来如下一个没有RAG的例子我们根据OpenAIClient创建了一个ChatClientAgent并直接调用它来回答一个问题2026年斯诺克世界赛冠军是谁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);输出我目前**无法确定**2026年斯诺克世界锦标赛的冠军是谁。 原因是 - 虽然按赛程来看2026年世锦赛通常在**4月下旬至5月初**结束但 - 我无法获取**实时或最新比赛结果**而且不应在没有可靠数据的情况下猜测冠军。 你可以选择下面两种方式之一 1. **如果你想要的是已产生的正式结果**我可以告诉你去哪里快速核实如世界斯诺克官网、BBC Sport、世界斯诺克巡回赛官方微博等。 2. **如果你想要的是赛前或赛中的预测/分析**我可以根据当时的世界排名、签表、球员状态给你一个专业预测。 你是想问**“已经夺冠的是谁”**还是**“你预测谁会夺冠”**由于知识固化的原因LLM无法直接回答这个问题。解决这个问题有两种途径: 一种是通过工具比如web-search获取最新信息另一种是通过RAG检索相关信息作为上下文来辅助LLM生成答案。下面我们通过TextSearchProvider来实现RAG我们在调用AsAIAgent时传入一个ChatClientAgentOptions对象并将一个TextSearchProvider实例添加到AIContextProviders中。TextSearchProvider需要我们提供一个SearchAsync方法来实现具体的检索逻辑我们让这个SearchAsync方法返回吴宜泽夺冠的一段新闻稿。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 TaskIEnumerableTextSearchResult 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?id1864605028122769594, SourceName 每日经济新闻, Text news }; return Task.FromResultIEnumerableTextSearchResult([result]); } else { return Task.FromResultIEnumerableTextSearchResult([]); } }输出2026年斯诺克世锦赛的冠军是**吴宜泽**。 他在北京时间 **2026年5月5日** 于英国谢菲尔德克鲁斯堡剧院举行的决赛中击败了**肖恩·墨菲**成功夺冠。这也是继2025年赵心童夺冠之后中国选手连续第二年获得斯诺克世锦赛冠军。2. 检索查询文本的状态存储RAG应该根据当前上下文来检索相关内容作为查询文本的不仅仅只考虑最近的用户消息有时还应该考虑最近或者全部对话历史也可以在此基础进行一些过滤。TextSearchProvider将作为检索的查询文本封装在TextSearchProviderState中并存在在当前Session状态中。如下面的代码片段所示TextSearchProviderState是定义在TextSearchProvider中的一个内嵌类性RecentMessagesText属性存储的就是作为检索的查询文本。TextSearchProvider利用一个ProviderSessionStateTextSearchProviderState对象来extSearchProviderState进行基于Session状态的读写它在Session状态字典中的Key可以通过TextSearchProviderOptions进行配置默认为TextSearchProvider的类名。public sealed class TextSearchProvider : MessageAIContextProvider { public sealed class TextSearchProviderState { public Liststring? RecentMessagesText { get; set; } } private readonly ProviderSessionStateTextSearchProviderState _sessionState; private IReadOnlyListstring? _stateKeys; public override IReadOnlyListstring StateKeys this._stateKeys ?? [this._sessionState.StateKey]; public TextSearchProvider( Funcstring, CancellationToken, TaskIEnumerableTextSearchResult searchAsync, TextSearchProviderOptions? options null, ILoggerFactory? loggerFactory null) : base(options?.SearchInputMessageFilter, options?.StorageInputRequestMessageFilter, options?.StorageInputResponseMessageFilter) { _sessionState new ProviderSessionStateTextSearchProviderState( _ 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可以根据当前的查询条件来决定是否需要调用这个工具来获取相关信息。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检索条件时可能导致搜索结果过度向已知信息倾斜。public sealed class TextSearchProviderOptions { public int RecentMessageMemoryLimit { get; set; } public ListChatRole? RecentMessageRolesIncluded { get; set; } public FuncIEnumerableChatMessage, IEnumerableChatMessage? SearchInputMessageFilter { get; set; } public FuncIEnumerableChatMessage, IEnumerableChatMessage? StorageInputRequestMessageFilter { get; set; } public FuncIEnumerableChatMessage, IEnumerableChatMessage? 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属性则可以用来存储一些原始的、未经格式化的表示这些表示可能来自于数据源的底层对象模型。public sealed class TextSearchProviderOptions { public string? ContextPrompt { get; set; } public string? CitationsPrompt { get; set; } public FuncIListTextSearchProvider.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对象它提供了对敏感信息进行脱敏处理的方法在日志和遥测中会调用这个对象的方法来对敏感信息进行脱敏。public sealed class TextSearchProviderOptions { public bool EnableSensitiveTelemetryData { get; set; } public Redactor? Redactor { get; set; } } public abstract class Redactor { public unsafe string Redact(ReadOnlySpanchar source); public abstract int Redact(ReadOnlySpanchar source, Spanchar destination); public int Redact(string? source, Spanchar destination); public virtual string Redact(string? source); public unsafe string RedactT(T value, string? format null, IFormatProvider? provider null); public int RedactT(T value, Spanchar destination, string? format null, IFormatProvider? provider null); public bool TryRedactT(T value, Spanchar destination, out int charsWritten, ReadOnlySpanchar format, IFormatProvider? provider null); public abstract int GetRedactedLength(ReadOnlySpanchar input); public int GetRedactedLength(string? input); }4. TextSearchProvider的实现原理TextSearchProvider针对RAG的实现其实很简单。在重写的ProvideAIContextAsync方法中如果配置选项SearchTime为OnDemandFunctionCalling它会创建一个用于检索的工具注册到返回的AIConext中。如果SearchTime为BeforeAIInvoke它会调用ProvideMessagesAsync方法返回的消息作为AIContext的Messages属性。public sealed class TextSearchProvider : MessageAIContextProvider { public TextSearchProvider( Funcstring, CancellationToken, TaskIEnumerableTextSearchResult searchAsync, TextSearchProviderOptions? options null, ILoggerFactory? loggerFactory null); protected override async ValueTaskAIContext ProvideAIContextAsync( AIContextProvider.InvokingContext context, CancellationToken cancellationToken default); protected override async ValueTaskIEnumerableChatMessage 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配置为OnDemandFunctionCallingTextSearchProvider生成的工具又是什么样子的。为此我们定义了如下这个AIContextTrackingProvider它继承自AIContextProvider并重写了InvokingCoreAsync方法在这个方法中我们可以访问到当前调用的AIContext从而查看其中包含的Messages和Tools等信息。class AIContextTrackingProvider: AIContextProvider { protected override ValueTaskAIContext 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的后面。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 TaskIEnumerableTextSearchResult 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?id1864605028122769594, SourceName 每日经济新闻, Text news }; return Task.FromResultIEnumerableTextSearchResult([result]); } else { return Task.FromResultIEnumerableTextSearchResult([]); } }输出第二条就是基于RAG检索结果生成的消息-------------------- 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?id1864605028122769594 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。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年斯诺克世界赛冠军是谁); ...输出-------------------- 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]}