From c46ab3f6f4983c958d5450458e540425785a8fbe Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 7 Feb 2025 15:09:14 -0800 Subject: [PATCH 1/3] some docs fixes --- .../ChatCompletion/ChatMessage.cs | 6 +-- .../ChatCompletion/ChatOptions.cs | 38 +++++++++++++++++-- .../AnonymousDelegatingChatClient.cs | 4 +- .../ChatCompletion/CachingChatClient.cs | 6 +-- 4 files changed, 42 insertions(+), 12 deletions(-) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs index d52cc36cdbb..452886b6c6a 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs @@ -21,15 +21,15 @@ public ChatMessage() } /// Initializes a new instance of the class. - /// Role of the author of the message. - /// Content of the message. + /// The role of the author of the message. + /// The contents of the message. public ChatMessage(ChatRole role, string? content) : this(role, content is null ? [] : [new TextContent(content)]) { } /// Initializes a new instance of the class. - /// Role of the author of the message. + /// The role of the author of the message. /// The contents for this message. public ChatMessage( ChatRole role, diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs index f3d3621aa69..e51d71d51ff 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs @@ -10,21 +10,46 @@ namespace Microsoft.Extensions.AI; public class ChatOptions { /// Gets or sets the temperature for generating chat responses. + /// + /// This value controls the randomness of predictions made by the model. Use a lower value to decrease randomness in the response. + /// public float? Temperature { get; set; } /// Gets or sets the maximum number of tokens in the generated chat response. public int? MaxOutputTokens { get; set; } /// Gets or sets the "nucleus sampling" factor (or "top p") for generating chat responses. + /// + /// Nucleus sampling is an alternative to sampling with temperature where the model + /// considers the results of the tokens with probability mass. + /// For example, 0.1 means only the tokens comprising the top 10% probability mass are considered. + /// public float? TopP { get; set; } - /// Gets or sets a count indicating how many of the most probable tokens the model should consider when generating the next part of the text. + /// + /// Gets or sets the number of most probable tokens that the model considers when generating the next part of the text. + /// + /// + /// This property reduces the probability of generating nonsense. A higher value gives more diverse answers, while a lower value is more conservative. + /// public int? TopK { get; set; } - /// Gets or sets the frequency penalty for generating chat responses. + /// + /// Gets or sets the penalty for repeated tokens in chat responses proportional to how many times they've appeared. + /// + /// + /// You can modify this value to reduce the repetitiveness of generated tokens. The higher the value, the stronger a penalty + /// is applied to previously present tokens, proportional to how many times they've already appeared in the prompt or prior generation. + /// public float? FrequencyPenalty { get; set; } - /// Gets or sets the presence penalty for generating chat responses. + /// + /// Gets or sets a value that influences the probability of generated tokens appearing based on their existing presence in generated text. + /// + /// + /// You can modify this value to reduce repetitiveness of generated tokens. Similar to , + /// except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies. + /// public float? PresencePenalty { get; set; } /// Gets or sets a seed value used by a service to control the reproducibility of results. @@ -47,7 +72,12 @@ public class ChatOptions /// Gets or sets the model ID for the chat request. public string? ModelId { get; set; } - /// Gets or sets the stop sequences for generating chat responses. + /// + /// Gets or sets the list of stop sequences. + /// + /// + /// After a stop sequence is detected, the model stops generating further tokens for chat responses. + /// public IList? StopSequences { get; set; } /// Gets or sets the tool mode for the chat request. diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/AnonymousDelegatingChatClient.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/AnonymousDelegatingChatClient.cs index 35dc69fd75c..ebd5477f177 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/AnonymousDelegatingChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/AnonymousDelegatingChatClient.cs @@ -13,7 +13,7 @@ namespace Microsoft.Extensions.AI; -/// A delegating chat client that wraps an inner client with implementations provided by delegates. +/// Represents a delegating chat client that wraps an inner client with implementations provided by delegates. public sealed class AnonymousDelegatingChatClient : DelegatingChatClient { /// The delegate to use as the implementation of . @@ -40,7 +40,7 @@ public sealed class AnonymousDelegatingChatClient : DelegatingChatClient /// used to perform the operation on the inner client. It will handle both the non-streaming and streaming cases. /// /// - /// This overload may be used when the anonymous implementation needs to provide pre- and/or post-processing, but doesn't + /// This overload may be used when the anonymous implementation needs to provide pre-processing and/or post-processing, but doesn't /// need to interact with the results of the operation, which will come from the inner client. /// /// is . diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs index f2de7f92fc8..0f7d2e7ac74 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs @@ -13,7 +13,7 @@ namespace Microsoft.Extensions.AI; /// -/// A delegating chat client that caches the results of chat calls. +/// Represents a delegating chat client that caches the results of chat calls. /// public abstract class CachingChatClient : DelegatingChatClient { @@ -31,7 +31,7 @@ protected CachingChatClient(IChatClient innerClient) } /// Gets or sets a value indicating whether to coalesce streaming updates. - /// + /// /// /// When , the client will attempt to coalesce contiguous streaming updates /// into a single update, in order to reduce the number of individual items that are yielded on @@ -41,7 +41,7 @@ protected CachingChatClient(IChatClient innerClient) /// /// The default is . /// - /// + /// public bool CoalesceStreamingUpdates { get; set; } = true; /// From 6c33e03f971662489ced4c9f0d745423b0fd2583 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 7 Feb 2025 15:12:09 -0800 Subject: [PATCH 2/3] wording --- .../ChatCompletion/CachingChatClient.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs index 0f7d2e7ac74..698025e8901 100644 --- a/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs +++ b/src/Libraries/Microsoft.Extensions.AI/ChatCompletion/CachingChatClient.cs @@ -30,12 +30,12 @@ protected CachingChatClient(IChatClient innerClient) { } - /// Gets or sets a value indicating whether to coalesce streaming updates. + /// Gets or sets a value indicating whether streaming updates are coalesced. /// /// - /// When , the client will attempt to coalesce contiguous streaming updates - /// into a single update, in order to reduce the number of individual items that are yielded on - /// subsequent enumerations of the cached data. When , the updates are + /// if the client attempts to coalesce contiguous streaming updates + /// into a single update, to reduce the number of individual items that are yielded on + /// subsequent enumerations of the cached data; if the updates are /// kept unaltered. /// /// From c79c74455d8ea7c48de3bd3f89c9eb8d4235d71f Mon Sep 17 00:00:00 2001 From: Igor Velikorossov Date: Mon, 10 Feb 2025 08:13:23 +1100 Subject: [PATCH 3/3] Update src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs --- .../ChatCompletion/ChatOptions.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs index e51d71d51ff..ffeefc86aaf 100644 --- a/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs +++ b/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs @@ -31,7 +31,7 @@ public class ChatOptions /// /// /// This property reduces the probability of generating nonsense. A higher value gives more diverse answers, while a lower value is more conservative. - /// + /// public int? TopK { get; set; } ///