Skip to content

Commit 1c9d90a

Browse files
authored
.Net: Adding a rag component for easily adding RAG to an agent. (#11774)
### Motivation and Context #10100 #10712 ### Description Adding a rag component for easily adding RAG to an agent. ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [ ] The code builds clean without any errors or warnings - [ ] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [ ] All unit tests pass, and I have added new tests where possible - [ ] I didn't break anyone 😄
1 parent 5e00d0c commit 1c9d90a

3 files changed

Lines changed: 501 additions & 0 deletions

File tree

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using System;
4+
using System.Collections.Generic;
5+
using System.Diagnostics.CodeAnalysis;
6+
using System.Linq;
7+
using System.Text;
8+
using System.Text.Json;
9+
using System.Text.Json.Serialization;
10+
using System.Threading;
11+
using System.Threading.Tasks;
12+
using Microsoft.Extensions.AI;
13+
using Microsoft.SemanticKernel.Data;
14+
15+
namespace Microsoft.SemanticKernel.Memory;
16+
17+
/// <summary>
18+
/// A component that does a search based on any messages that the AI model is invoked with and injects the results into the AI model invocation context.
19+
/// </summary>
20+
[Experimental("SKEXP0130")]
21+
public sealed class TextRagComponent : ConversationStatePart
22+
{
23+
private const string DefaultPluginSearchFunctionName = "Search";
24+
private const string DefaultPluginSearchFunctionDescription = "Allows searching for additional information to help answer the user question.";
25+
private const string DefaultContextPrompt = "Consider the following information when responding to the user:";
26+
private const string DefaultIncludeCitationsPrompt = "Include citations to the relevant information where it is referenced in the response.";
27+
28+
private readonly ITextSearch _textSearch;
29+
30+
private readonly AIFunction[] _aIFunctions;
31+
32+
/// <summary>
33+
/// Initializes a new instance of the <see cref="TextRagComponent"/> class.
34+
/// </summary>
35+
/// <param name="textSearch">The text search component to retrieve results from.</param>
36+
/// <param name="options">Options that configure the behavior of the component.</param>
37+
/// <exception cref="ArgumentNullException"></exception>
38+
public TextRagComponent(ITextSearch textSearch, TextRagComponentOptions? options = default)
39+
{
40+
Verify.NotNull(textSearch);
41+
42+
this._textSearch = textSearch;
43+
this.Options = options ?? new();
44+
45+
this._aIFunctions =
46+
[
47+
AIFunctionFactory.Create(
48+
this.SearchAsync,
49+
name: this.Options.PluginFunctionName ?? DefaultPluginSearchFunctionName,
50+
description: this.Options.PluginFunctionDescription ?? DefaultPluginSearchFunctionDescription)
51+
];
52+
}
53+
54+
/// <summary>
55+
/// Gets the options that have been configured for this component.
56+
/// </summary>
57+
public TextRagComponentOptions Options { get; }
58+
59+
/// <inheritdoc/>
60+
public override IReadOnlyCollection<AIFunction> AIFunctions
61+
{
62+
get
63+
{
64+
if (this.Options.SearchTime != TextRagComponentOptions.RagBehavior.ViaPlugin)
65+
{
66+
return Array.Empty<AIFunction>();
67+
}
68+
69+
return this._aIFunctions;
70+
}
71+
}
72+
73+
/// <inheritdoc/>
74+
public override async Task<string> OnModelInvokeAsync(ICollection<ChatMessage> newMessages, CancellationToken cancellationToken = default)
75+
{
76+
if (this.Options.SearchTime != TextRagComponentOptions.RagBehavior.BeforeAIInvoke)
77+
{
78+
return string.Empty;
79+
}
80+
81+
Verify.NotNull(newMessages);
82+
83+
string input = string.Join("\n", newMessages.Where(m => m is not null).Select(m => m.Text));
84+
85+
var searchResults = await this._textSearch.GetTextSearchResultsAsync(
86+
input,
87+
new() { Top = this.Options.Top },
88+
cancellationToken: cancellationToken).ConfigureAwait(false);
89+
90+
var results = await searchResults.Results.ToListAsync(cancellationToken).ConfigureAwait(false);
91+
92+
return this.FormatResults(results);
93+
}
94+
95+
/// <summary>
96+
/// Plugin method to search the database on demand.
97+
/// </summary>
98+
[KernelFunction]
99+
internal async Task<string> SearchAsync(string userQuestion, CancellationToken cancellationToken = default)
100+
{
101+
var searchResults = await this._textSearch.GetTextSearchResultsAsync(
102+
userQuestion,
103+
new() { Top = this.Options.Top },
104+
cancellationToken: cancellationToken).ConfigureAwait(false);
105+
106+
var results = await searchResults.Results.ToListAsync(cancellationToken).ConfigureAwait(false);
107+
108+
return this.FormatResults(results);
109+
}
110+
111+
/// <summary>
112+
/// Format the results showing the content with source link and name for each result.
113+
/// </summary>
114+
/// <param name="results">The results to format.</param>
115+
/// <returns>The formatted results.</returns>
116+
private string FormatResults(List<TextSearchResult> results)
117+
{
118+
if (this.Options.ContextFormatter is not null)
119+
{
120+
return this.Options.ContextFormatter(results);
121+
}
122+
123+
if (results.Count == 0)
124+
{
125+
return string.Empty;
126+
}
127+
128+
var sb = new StringBuilder();
129+
sb.AppendLine(this.Options.ContextPrompt ?? DefaultContextPrompt);
130+
for (int i = 0; i < results.Count; i++)
131+
{
132+
var result = results[i];
133+
sb.AppendLine($"Item {i + 1}:");
134+
sb.AppendLine($"Name: {result.Name}");
135+
sb.AppendLine($"Link: {result.Link}");
136+
sb.AppendLine($"Contents: {result.Value}");
137+
}
138+
sb.AppendLine(this.Options.IncludeCitationsPrompt ?? DefaultIncludeCitationsPrompt);
139+
sb.AppendLine();
140+
return sb.ToString();
141+
}
142+
}
143+
144+
[JsonSourceGenerationOptions(JsonSerializerDefaults.General,
145+
UseStringEnumConverter = false,
146+
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
147+
WriteIndented = false)]
148+
[JsonSerializable(typeof(List<TextSearchResult>))]
149+
internal partial class TextRagSourceGenerationContext : JsonSerializerContext
150+
{
151+
}
Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using System;
4+
using System.Collections.Generic;
5+
using System.Diagnostics.CodeAnalysis;
6+
using Microsoft.SemanticKernel.Data;
7+
8+
namespace Microsoft.SemanticKernel.Memory;
9+
10+
/// <summary>
11+
/// Contains options for the <see cref="TextRagComponent"/>.
12+
/// </summary>
13+
[Experimental("SKEXP0130")]
14+
public sealed class TextRagComponentOptions
15+
{
16+
private int _top = 3;
17+
18+
/// <summary>
19+
/// Maximum number of results to return from the similarity search.
20+
/// </summary>
21+
/// <remarks>The value must be greater than 0.</remarks>
22+
/// <value>The default value is 3 if not set.</value>
23+
public int Top
24+
{
25+
get => this._top;
26+
init
27+
{
28+
if (value < 1)
29+
{
30+
throw new ArgumentOutOfRangeException(nameof(value), "Top must be greater than 0.");
31+
}
32+
33+
this._top = value;
34+
}
35+
}
36+
37+
/// <summary>
38+
/// Gets or sets the time at which the text search is performed.
39+
/// </summary>
40+
public RagBehavior SearchTime { get; init; } = RagBehavior.BeforeAIInvoke;
41+
42+
/// <summary>
43+
/// Gets or sets the name of the plugin method that will be made available for searching
44+
/// if the <see cref="SearchTime"/> option is set to <see cref="RagBehavior.ViaPlugin"/>.
45+
/// </summary>
46+
/// <value>
47+
/// Defaults to &quot;Search&quot; if not set.
48+
/// </value>
49+
public string? PluginFunctionName { get; init; }
50+
51+
/// <summary>
52+
/// Gets or sets the description of the plugin method that will be made available for searching
53+
/// if the <see cref="SearchTime"/> option is set to <see cref="RagBehavior.ViaPlugin"/>.
54+
/// </summary>
55+
/// <value>
56+
/// Defaults to &quot;Allows searching for additional information to help answer the user question.&quot; if not set.
57+
/// </value>
58+
public string? PluginFunctionDescription { get; init; }
59+
60+
/// <summary>
61+
/// When providing the text chunks to the AI model on invocation, this string is prefixed
62+
/// to those chunks, in order to provide some context to the model.
63+
/// </summary>
64+
/// <value>
65+
/// Defaults to &quot;Consider the following information when responding to the user:&quot;
66+
/// </value>
67+
public string? ContextPrompt { get; init; }
68+
69+
/// <summary>
70+
/// When providing the text chunks to the AI model on invocation, this string is postfixed
71+
/// to those chunks, in order to instruct the model to include citations.
72+
/// </summary>
73+
/// <value>
74+
/// Defaults to &quot;Include citations to the relevant information where it is referenced in the response.:&quot;
75+
/// </value>
76+
public string? IncludeCitationsPrompt { get; init; }
77+
78+
/// <summary>
79+
/// Optional delegate to override the default context creation implementation.
80+
/// </summary>
81+
/// <remarks>
82+
/// <para>
83+
/// If provided, this delegate will be used to do the following:
84+
/// 1. Create the output context provided by the <see cref="TextRagComponent"/> when invoking the AI model.
85+
/// 2. Create the response text when invoking the component via a plugin.
86+
/// </para>
87+
/// <para>
88+
/// Note that the delegate should include the context prompt and the
89+
/// include citations prompt if they are required in the output.
90+
/// The <see cref="ContextPrompt"/> and <see cref="IncludeCitationsPrompt"/> settings
91+
/// will not be used if providing this delegate.
92+
/// </para>
93+
/// </remarks>
94+
public ContextFormatterType? ContextFormatter { get; init; }
95+
96+
/// <summary>
97+
/// Choices for controlling the behavior of the <see cref="TextRagComponent"/>.
98+
/// </summary>
99+
public enum RagBehavior
100+
{
101+
/// <summary>
102+
/// A search is performed each time that the model/agent is invoked just before invocation
103+
/// and the results are provided to the model/agent via the invocation context.
104+
/// </summary>
105+
BeforeAIInvoke,
106+
107+
/// <summary>
108+
/// A search may be performed by the model/agent on demand via function calling.
109+
/// </summary>
110+
ViaPlugin
111+
}
112+
113+
/// <summary>
114+
/// Delegate type for formatting the output context for the component.
115+
/// </summary>
116+
/// <param name="results">The results returned by the text search.</param>
117+
/// <returns>The formatted context.</returns>
118+
public delegate string ContextFormatterType(List<TextSearchResult> results);
119+
}

0 commit comments

Comments
 (0)