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

摘要：使用ConversationId和绑定会话并追加系统提示词：var contextMessages = new List{new(ChatRole.System, "你是贴心的行程规划助手。"),new(ChatRole.User, "帮我安排一个五一北京两日

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

属性

说明

使用场景

ConversationId绑定会话标识无状态客户端的状态恢复 Instructions附加系统提示词补充场景限定或额外要求 2. 生成策略

属性

说明

典型值

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

属性

说明

ToolMode工具调用策略（禁用/自动/必须） Tools当前请求可用的工具集合 AllowMultipleToolCalls允许模型串联多个工具调用 4. 背景执行与恢复

属性

说明

AllowBackgroundResponses支持后台长任务（实验性） ContinuationToken用于轮询或恢复流式响应 5. 扩展点

属性

说明

使用ConversationId和绑定会话并追加系统提示词：var contextMessages = new List
{
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);
结合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适合跨请求共享的工具当标准ChatOptions属性无法覆盖提供商特殊功能时，使用场景 1：传递 OpenAI 特定参数var options = new ChatOptions
{
ResponseFormat = ChatResponseFormat.Json,
AdditionalProperties = new
{
["strictJsonSchema"] = true // OpenAI 的严格 JSON Schema 模式
}
};
在SummarizingChatReducer中，通过存储和传递摘要内容：// 读取摘要
if (message.AdditionalProperties?.TryGetValuestring>(SummaryKey, out var summaryValue) == true)
{
summary = summaryValue;
}

// 写入摘要
var additionalProperties = lastSummarizedMessage.AdditionalProperties ??= ;
additionalProperties[SummaryKey] = newSummary;
场景 3：Azure AI Inference 的额外属性在Microsoft.Extensions.AI.AzureAIInference包中，AdditionalProperties被转换为类型：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中添加专属属性

保持框架简洁性

提供最大灵活性

工作原理

类型签名：

public Func
输入：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 完全控制使用 RawRepresentationFactory2. 工具配置策略

场景

使用属性

单次请求的工具 ChatOptions.Tools跨请求共享的工具 FunctionInvocationOptions.AdditionalTools3. RawRepresentationFactory 使用建议 ✅ 仅在必要时使用：优先使用标准ChatOptions属性 ✅ 始终返回新实例：避免状态污染 ✅ 使用类型检查：根据客户端类型返回不同配置 ✅ 文档化特殊配置：添加注释说明使用原因总结 ✅ 统一配置容器：ChatOptions提供跨提供商的一致配置接口 ✅ 五大能力维度：对话上下文、生成策略、工具调用、背景执行、扩展点 ✅ 灵活扩展机制：AdditionalProperties透传自定义参数，RawRepresentationFactory提供底层控制 ✅ 清晰的优先级：Raw representation 中的非 null 值具有最高优先级 ✅ 最佳实践：标准功能用标准属性，特殊功能用扩展点，始终返回新实例

下一步：探索 Microsoft.Extensions.AI 的缓存机制，敬请期待。