一句话简介
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），用于在统一抽象与底层实现之间建立桥梁。
核心设计理念
为什么需要这个属性？
抽象与实现的矛盾
ChatOptions 提供统一配置，但各提供商有特有选项
例如 OpenAI 的 IncludeUsage、Azure AI 的自定义配置
避免抽象层膨胀
不为每个提供商在 ChatOptions 中添加专属属性
保持框架简洁性
提供最大灵活性
高级用户可完全控制底层 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) => 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 =
{
["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 值具有最高优先级
✅ 最佳实践：标准功能用标准属性，特殊功能用扩展点，始终返回新实例
下一步：探索 Microsoft.Extensions.AI 的缓存机制，敬请期待。
