.NET+AI | MEAI | ChatOptions 详解（5）

一句话简介

ChatOptions 是 Microsoft.Extensions.AI 中传递给 IChatClient 的统一配置容器，用于在单次请求中精准控制生成策略、工具调用和扩展特性。

---

🎯 核心价值

• ✅ 统一配置接口：跨提供商的一致配置体验
• ✅ 细粒度控制：从对话上下文到采样策略，全方位调整
• ✅ 灵活扩展：通过 AdditionalProperties 和 RawRepresentationFactory 支持提供商特定功能

---

📝 核心属性概览

ChatOptions 的属性按能力维度可分为五大类：

1. 对话上下文

属性	说明	使用场景
ConversationId	绑定会话标识	无状态客户端的状态恢复
Instructions	附加系统提示词	补充场景限定或额外要求

2. 生成策略

属性	说明	典型值
ModelId	覆盖默认模型	"gpt-4o-mini"
ResponseFormat	强制输出格式	Text / Json / JSON Schema
Temperature	控制多样性	0.0-2.0（越高越随机）
TopP	核采样参数	0.0-1.0
TopK	Top-K 采样	整数值
MaxOutputTokens	最大生成长度	如 512
FrequencyPenalty	抑制重复词频	-2.0 到 2.0
PresencePenalty	抑制重复主题	-2.0 到 2.0
Seed	固定随机种子	用于结果复现
StopSequences	截断序列	如 ["[DONE]"]

3. 工具调用

属性	说明
ToolMode	工具调用策略（禁用/自动/必须）
Tools	当前请求可用的工具集合
AllowMultipleToolCalls	允许模型串联多个工具调用

4. 背景执行与恢复

属性	说明
AllowBackgroundResponses	支持后台长任务（实验性）
ContinuationToken	用于轮询或恢复流式响应

5. 扩展点

属性	说明
AdditionalProperties	透传自定义键值对
RawRepresentationFactory	返回提供商专属选项对象

---

💻 核心使用示例

示例 1：对话上下文配置

使用 ConversationId 和 Instructions 绑定会话并追加系统提示词：

	var contextMessages = new List<ChatMessage>

	{

	    new(ChatRole.System, "你是贴心的行程规划助手。"),

	    new(ChatRole.User, "帮我安排一个五一北京两日游的行程计划。")

	};

	 

	ChatOptions contextOptions = new()

	{

	    ConversationId = "planner-2024-05-01",

	    Instructions = "回答请保持中文，并按时间顺序给出活动安排。"

	};

	 

	var response = await chatClient.GetResponseAsync(contextMessages, contextOptions);

---

示例 2：生成策略调整

覆盖模型并微调采样参数，精准控制回答风格：

	ChatOptions generationOptions = new()

	{

	    ModelId = "gpt-4o-mini",

	    Temperature = 0.7f,

	    TopP = 0.9f,

	    MaxOutputTokens = 512,

	    StopSequences = new[] { "[DONE]" }

	};

	 

	var response = await chatClient.GetResponseAsync(messages, generationOptions);

---

示例 3：工具调用配置

结合 UseFunctionInvocation 中间件，动态控制工具列表：

	AITool weatherTool = AIFunctionFactory.Create(

	    (string city) => GetCurrentWeather(city),

	    name: "get_current_weather",

	    description: "查询指定城市的实时天气");

	 

	ChatOptions toolOptions = new()

	{

	    ToolMode = ChatToolMode.Auto,

	    AllowMultipleToolCalls = true,

	    Tools = new[] { weatherTool }

	};

	 

	var toolEnabledClient = chatClient.AsBuilder()

	    .UseFunctionInvocation()

	    .Build();

	 

	var response = await toolEnabledClient.GetResponseAsync(messages, toolOptions);

💡 提示：

• ChatOptions.Tools 适合单次请求的定制配置
• FunctionInvocationOptions.AdditionalTools 适合跨请求共享的工具

---

🔧 扩展点详解

1. AdditionalProperties：透传提供商特定参数

当标准 ChatOptions 属性无法覆盖提供商特殊功能时，使用 AdditionalProperties：

场景 1：传递 OpenAI 特定参数

	var options = new ChatOptions

	{

	    ResponseFormat = ChatResponseFormat.Json,

	    AdditionalProperties = new()

	    {

	        ["strictJsonSchema"] = true  // OpenAI 的严格 JSON Schema 模式

	    }

	};

场景 2：存储对话摘要

在 SummarizingChatReducer 中，通过 AdditionalProperties 存储和传递摘要内容：

	// 读取摘要

	if (message.AdditionalProperties?.TryGetValue<string>(SummaryKey, out var summaryValue) == true)

	{

	    summary = summaryValue;

	}

	 

	// 写入摘要

	var additionalProperties = lastSummarizedMessage.AdditionalProperties ??= [];

	additionalProperties[SummaryKey] = newSummary;

场景 3：Azure AI Inference 的额外属性

在 Microsoft.Extensions.AI.AzureAIInference 包中，AdditionalProperties 被转换为 BinaryData 类型：

	if (options.AdditionalProperties is { } props)

	{

	    foreach (var prop in props)

	    {

	        byte[] data = JsonSerializer.SerializeToUtf8Bytes(prop.Value);

	        result.AdditionalProperties[prop.Key] = new BinaryData(data);

	    }

	}

---

2. RawRepresentationFactory：逃生舱机制

RawRepresentationFactory 是框架提供的逃生舱（Escape Hatch） ，用于在统一抽象与底层实现之间建立桥梁。

核心设计理念

为什么需要这个属性？

1. 抽象与实现的矛盾

   • ChatOptions 提供统一配置，但各提供商有特有选项
   • 例如 OpenAI 的 IncludeUsage、Azure AI 的自定义配置

2. 避免抽象层膨胀

   • 不为每个提供商在 ChatOptions 中添加专属属性
   • 保持框架简洁性

3. 提供最大灵活性

   • 高级用户可完全控制底层 SDK 配置

工作原理

类型签名：

	public Func<IChatClient, object?>? RawRepresentationFactory { get; set; }

• 输入：IChatClient - 当前客户端实例
• 输出：object? - 底层实现特定的选项对象

核心机制 - 空值合并优先级：

• RawRepresentationFactory 返回的非 null 属性具有最高优先级
• ChatOptions 的属性仅填充 raw representation 中的 null 属性

使用场景

场景 1：设置 OpenAI 特有配置

	var chatOptions = new ChatOptions

	{

	    Temperature = 0.7f,

	    MaxOutputTokens = 1000,

	    

	    RawRepresentationFactory = (client https://www.falvce.com/) => new ChatCompletionOptions

	    {

	        IncludeUsage = true,  // OpenAI 特有：在流式响应中包含使用统计

	        TopP = 0.95f          // 预设值，不会被 ChatOptions 覆盖

	    }

	};

	 

	// 最终结果：

	// - Temperature: 0.7 (来自 ChatOptions)

	// - MaxOutputTokens: 1000 (来自 ChatOptions)

	// - TopP: 0.95 (来自 RawRepresentationFactory，优先级更高)

	// - IncludeUsage: true (OpenAI 特有)

场景 2：动态适配不同提供商

	var options = new ChatOptions

	{

	    Temperature = 0.7f,

	    

	    RawRepresentationFactory = (client) => client switch

	    {

	        OpenAIChatClient => new ChatCompletionOptions

	        {

	            IncludeUsage = true,

	            Store = true  // OpenAI 持久化选项

	        },

	        

	        AzureAIInferenceChatClient => new ChatCompletionsOptions

	        {

	            AdditionalProperties = 

	            {https://www.falvce.com/

	                ["custom_azure_setting"] = new BinaryData("value")

	            }

	        },

	        

	        _ => null  // 其他客户端使用默认转换

	    }

	};

优先级总结

配置属性的最终值由以下优先级决定：

	高优先级 ←―――――――――――――――――――――――――――→ 低优先级

	 

	1. RawRepresentationFactory 中的非 null 值

	2. ChatOptions 中的值（仅填充 raw 中的 null 属性）

	3. 客户端的默认值

示例可视化：

	RawRepresentation: { Temperature = 0.8, MaxTokens = null, TopP = 0.9 }

	ChatOptions:       { Temperature = 0.5, MaxTokens = 100,  TopP = 0.7, Seed = 42 }

	 

	最终结果:          { Temperature = 0.8, MaxTokens = 100,  TopP = 0.9, Seed = 42 }

	                    ↑ 来自 Raw      ↑ 来自 ChatOptions ↑ 来自 Raw  ↑ 来自 ChatOptions

重要注意事项

注意点	说明
必须返回新实例	避免共享实例导致状态污染
类型必须匹配	返回错误类型会被忽略，框架创建默认实例
不会被序列化	委托不能序列化，序列化时会丢失此属性

	// ❌ 错误：返回共享实例

	private static ChatCompletionOptions _sharedOptions = new();

	RawRepresentationFactory = (c) => _sharedOptions;

	 

	// ✅ 正确：每次返回新实例

	RawRepresentationFactory = (c) => new ChatCompletionOptions { IncludeUsage = true };

---

🏢 最佳实践

1. 配置选择策略

场景	推荐方式
标准功能	使用 ChatOptions 标准属性
提供商特定参数	使用 AdditionalProperties
底层 SDK 完全控制	使用 RawRepresentationFactory

2. 工具配置策略

场景	使用属性
单次请求的工具	ChatOptions.Tools
跨请求共享的工具	FunctionInvocationOptions.AdditionalTools

3. RawRepresentationFactory 使用建议

• ✅ 仅在必要时使用：优先使用标准 ChatOptions 属性
• ✅ 始终返回新实例：避免状态污染
• ✅ 使用类型检查：根据客户端类型返回不同配置
• ✅ 文档化特殊配置：添加注释说明使用原因

---

🎯 总结

• ✅ 统一配置容器：ChatOptions 提供跨提供商的一致配置接口
• ✅ 五大能力维度：对话上下文、生成策略、工具调用、背景执行、扩展点
• ✅ 灵活扩展机制：AdditionalProperties 透传自定义参数，RawRepresentationFactory 提供底层控制
• ✅ 清晰的优先级：Raw representation 中的非 null 值具有最高优先级
• ✅ 最佳实践：标准功能用标准属性，特殊功能用扩展点，始终返回新实例