Semantic Kernel 内核内容类型毕业指南:从实验特性到稳定 API 的演进路线
Semantic Kernel 内核内容类型毕业指南:从实验特性到稳定 API 的演进路线
导读
本文基于 Semantic Kernel 仓库中的架构决策记录 0046-kernel-content-graduation.md,系统讲解 KernelContent 系列内容类型(二进制内容、图片、音频、函数调用、函数结果、文件引用与注解)如何从 experimental 状态"毕业"为稳定 API 的完整决策过程与落地方案。你将理解 BinaryContent 统一抽象的设计动机、Data URI 参数化与序列化机制、破坏性变更的处理策略,以及最终决策结果在当前仓库源码中的实际落地形态。
一、背景:为什么需要"内容类型毕业"
1.1 问题背景
在 Semantic Kernel 早期版本中,大量内容类型(Content Types)处于实验(experimental)状态,包括 BinaryContent、ImageContent、AudioContent、FunctionCallContent、FunctionResultContent 等。这些类型是 Kernel 与 AI 模型之间传递图像、音频、文件、函数调用等非文本信息的基础载体。实验状态意味着 API 可能随时变动,不适合作为长期稳定的对外契约,因此需要一套方案将它们"毕业"为稳定状态。
该 ADR 由 rogerbarreto 于 2024-05-02 提出,deciders 包括 markwallace-microsoft、sergeymenkshi、dmytrostruk、westey-m、matthewbolanos 等核心维护者,consulted 为 stephentoub。
1.2 决策驱动因素
毕业方案的设计受到四个核心约束,这也是评估每个内容类型方案时反复使用的判断标准:
| 决策驱动 | 含义 |
|---|---|
| 无破坏性变更 | 尽量不破坏现有消费者代码 |
| 简单、最小复杂度 | 避免过度设计 |
| 允许可扩展性 | 为未来的内容类型保留扩展空间 |
| 简洁清晰 | API 语义明确、无歧义 |
二、BinaryContent 毕业方案:统一二进制内容的基石
2.1 现状与痛点
毕业前的 BinaryContent 采用**延迟加载(deferred / lazy loaded)**设计,通过 Func<Task<Stream>> 提供流式读取能力:
public class BinaryContent : KernelContent
{
public ReadOnlyMemory<byte>? Content { get; set; }
public async Task<Stream> GetStreamAsync()
public async Task<ReadOnlyMemory<byte>> GetContentAsync()
ctor(ReadOnlyMemory<byte>? content = null)
ctor(Func<Task<Stream>> streamProvider)
}
该设计存在一个关键问题:Content 属性语义含糊。当 BinaryContent 被特化为 PdfContent、PictureContent 等类型时,Content 属性会与子类型自身的语义产生冲突或误导——例如 PdfContent.Content 本意应描述文本信息,PictureContent.Content 应暴露 Picture 类型,但它们都被笼统的 Content 命名覆盖了。
2.2 提案设计
提案将 BinaryContent 重构为"自我包含"的内容模型,移除延迟加载:
public class BinaryContent : KernelContent
{
ReadOnlyMemory<byte>? Data { get; set; }
Uri? Uri { get; set; }
string DataUri { get; set; }
bool CanRead { get; } // 指示内容是否可以按字节或 data uri 读取
ctor(Uri? referencedUri)
ctor(string dataUri)
// MimeType 非必填但可为空,鼓励在可用时始终传入该信息
ctor(ReadOnlyMemory<byte> data, string? mimeType)
ctor() // 序列化场景的空构造函数
}
设计要点如下:
- 移除
Content属性:避免与特化类型的语义冲突和误导; - 移除延迟加载:API 更简单,内容类型职责单一;
- 移除
GetContentAsync:不再有异步解引用(dereferenced)API; - 新增
Data属性:字节数组内容的读写入口,设置该属性会覆盖DataUri的 base64 数据部分; - 新增
DataUri属性:data uri 内容的读写入口,设置该属性会依据载荷覆盖Data与MimeType; - 新增
Uri属性:用于引用型内容(referenced content),不接受 data scheme,仅支持非 data 协议; - 新增
CanRead属性:明确指示内容是否可通过Data或DataUri读取; - 提供专用构造函数:分别面向 Uri、DataUri、字节数组 + MimeType 三种创建场景。
该方案的优势在于:API 简单且职责单一、Data 与 DataUri 双格式可读写、Uri 引用属性契合特化场景、完全可序列化、支持 Data Uri 参数、内置 Data Uri 与 Base64 校验、CanRead 让读取能力一目了然。唯一的代价是:对实验期 BinaryContent 消费者构成破坏性变更。
2.3 数据 URI 参数支持(RFC 2397)
根据 RFC 2397,data uri scheme 支持参数。Data URI 中携带的每个参数都会以 data-uri-{参数名} 为 key 写入 Metadata 字典:
var content = new BinaryContent("data:application/json;parameter1=value1;parameter2=value2;base64,SGVsbG8gV29ybGQ=");
var parameter1 = content.Metadata["data-uri-parameter1"]; // value1
var parameter2 = content.Metadata["data-uri-parameter2"]; // value2
反序列化时参数同样被保留,读取 DataUri 属性即可还原完整的参数化 data uri:
var json = """
{
"metadata":
{
"data-uri-parameter1":"value1",
"data-uri-parameter2":"value2"
},
"mimeType":"application/json",
"data":"SGVsbG8gV29ybGQ="
}
""";
var content = JsonSerializer.Deserialize<BinaryContent>(json);
content.DataUri // "data:application/json;parameter1=value1;parameter2=value2;base64,SGVsbG8gV29ybGQ="
特化示例:ImageContent / AudioContent
以 ImageContent 为例,作为 BinaryContent 的特化类型,构造函数直接透传基类:
public class ImageContent : BinaryContent
{
ctor(Uri uri) : base(uri)
ctor(string dataUri) : base(dataUri)
ctor(ReadOnlyMemory<byte> data, string? mimeType) : base(data, mimeType)
ctor() // serialization scenarios
}
public class AudioContent : BinaryContent
{
ctor(Uri uri)
}
特化方案支持 data uri 大内容、允许 ImageContent 既可用 dataUrl scheme 创建也可被 Url 引用,并保留 Data Uri 校验能力。
2.4 源码落地印证
提案中的设计在当前仓库中已完整落地为正式实现,见 BinaryContent.cs:
- 类声明于 第 19-20 行,标注
[Experimental("SKEXP0001")],仍处于实验特性状态; - 旧的
Content属性保留为[JsonIgnore, Obsolete("Use Data instead")]兼容别名(第 29-30 行),读取时直接转发到Data; Uri属性的 setter(第 126-134 行)会对data:scheme 抛出InvalidOperationException,并提示 "For DataUri contents, use DataUri property"——正是 ADR 中"Uri 仅支持非 data scheme"的实现;DataUri的 setter(第 147-183 行)执行完整的格式校验:必须以data:开头(否则抛UriFormatException),通过DataUriParser解析并覆盖MimeType,同时将参数写入Metadata;SetData(第 239-244 行)在写入字节数据时会使旧的_dataUri失效,保证同一实例中Data与DataUri不会同时存在矛盾值;CanRead(第 66-69 行)实现为_data is not null || _dataUri is not null,与提案语义完全一致;GetDataUri(第 259-278 行)支持按需从字节数组生成带参数的 base64 data uri(通过GetDataUriParametersFromMetadata回读data-uri-*元数据),从而保证"序列化后参数不丢失"。
底层 Data URI 解析由内部工具类 DataUriParser.cs 承担,其文档注释明确基于 RFC 2397(第 13-16 行),并内置了严格的 base64 字符集与长度校验逻辑(第 32-72 行)。单元测试覆盖于 DataUriParserTests.cs 与 BinaryContentTests.cs。
三、ImageContent 毕业:修复"同一个实例两套数据"的缺陷
3.1 现状问题
⚠️ 毕业前的 ImageContent 并不在 experimental 状态,但存在明显的行为缺陷,维护者认为有必要通过破坏性变更将其修复并升级为稳定状态:
- 当前
ImageContent不从BinaryContent派生; - 存在不良行为:允许同一实例同时持有不同的
DataUri与Data; Uri属性同时被用作 data uri 和引用 uri 两种用途;Uri不支持大型语言模型的 data uri 格式(.NETUri类型存在 ushort 长度限制,见 dotnet/runtime#96544);- 对 sk 开发者而言,内容是否可读不明确。
毕业前的结构如下:
public class ImageContent : KernelContent
{
Uri? Uri { get; set; }
public ReadOnlyMemory<byte>? Data { get; set; }
ctor(ReadOnlyMemory<byte>? data)
ctor(Uri uri)
ctor()
}
3.2 毕业提案与破坏性变更清单
提案让 ImageContent 成为 BinaryContent 的特化类型,完整继承其全部能力:
public class ImageContent : BinaryContent
{
ctor(Uri uri) : base(uri)
ctor(string dataUri) : base(dataUri)
ctor(ReadOnlyMemory<byte> data, string? mimeType) : base(data, mimeType)
ctor() // serialization scenarios
}
其带来的破坏性变更被明确列为决策的一部分:
Uri属性专用于引用位置(非 data uri),尝试赋入 data uri 格式将抛出异常并建议改用DataUri属性;- 设置
DataUri将依据提供的信息覆盖Data与MimeType; - 尝试设置无效的
DataUri将抛出异常; - 设置
Data将覆盖DataUri的数据部分; - 尝试序列化一个
Uri属性中带 data uri 的ImageContent将抛出异常。
3.3 源码落地印证
当前实现 ImageContent.cs 完全遵循该提案:类声明(第 11 行)直接 : BinaryContent,并提供 Uri、DataUri、字节数组 + MimeType、空构造函数四组重载,分别透传基类。其相关行为(Uri 拒绝 data scheme、Data/DataUri 互斥覆盖等)均继承自 BinaryContent 的 setter 校验逻辑,测试见 ImageContentTests.cs。
四、AudioContent 毕业:补齐引用能力
4.1 现状问题
毕业前的 AudioContent 相比 ImageContent 更为简陋:
- 不支持
Uri引用位置; Uri属性同时混用 data uri 与引用 uri;Uri不支持大型 data uri 格式;- 对开发者而言内容是否可读不明确。
public class AudioContent : KernelContent
{
public ReadOnlyMemory<byte>? Data { get; set; }
ctor(ReadOnlyMemory<byte>? data)
ctor()
}
4.2 毕业提案
与 ImageContent 相同的处理路径——成为 BinaryContent 的特化类型:
public class AudioContent : BinaryContent
{
ctor(Uri uri) : base(uri)
ctor(string dataUri) : base(dataUri)
ctor(ReadOnlyMemory<byte> data, string? mimeType) : base(data, mimeType)
ctor() // serialization scenarios
}
收益与 ImageContent 一致(可作 BinaryContent 使用、双格式读写、专属引用 Uri、完全可序列化、参数与校验支持、CanRead 明确可读性),代价是实验期 AudioContent 消费者的破坏性变更。当前实现见 AudioContent.cs,其中类声明位于第 15 行(标注 [Experimental("SKEXP0001")]),四组构造函数与 ImageContent 完全同构,测试见 AudioContentTests.cs。
五、FunctionCallContent 毕业:原样转正
FunctionCallContent 被认为结构已经成熟,无需任何变更即可毕业。虽然曾考虑引入基类 FunctionContent,但维护者认为让 FunctionCallContent 与 FunctionResultContent 各自直接派生自 KernelContent 能提供更清晰的关注点分离。
public sealed class FunctionCallContent : KernelContent
{
public string? Id { get; }
public string? PluginName { get; }
public string FunctionName { get; }
public KernelArguments? Arguments { get; }
public Exception? Exception { get; init; }
ctor(string functionName, string? pluginName = null, string? id = null, KernelArguments? arguments = null)
public async Task<FunctionResultContent> InvokeAsync(Kernel kernel, CancellationToken cancellationToken = default)
public static IEnumerable<FunctionCallContent> GetFunctionCalls(ChatMessageContent messageContent)
}
当前源码 FunctionCallContent.cs 与该提案基本一致:InvokeAsync(第 70-87 行)通过 kernel.Plugins.TryGetFunction 解析插件与函数并执行,找不到时抛出 KeyNotFoundException;GetFunctionCalls(第 94-97 行)从 ChatMessageContent.Items 中按类型过滤出函数调用项。测试见 FunctionCallContentTests.cs 与 FunctionCallContentBuilderTests.cs。
六、FunctionResultContent 毕业:两个候选方案
FunctionResultContent 结构总体良好,但存在两处打磨点:
- 从语义纯度看,
Id属性容易引发歧义——它并非响应 ID,而是函数调用 ID; - 多个构造函数对同一类型使用了不一致的参数名(
functionCall与functionCallContent)。
毕业前的结构:
public sealed class FunctionResultContent : KernelContent
{
public string? Id { get; }
public string? PluginName { get; }
public string? FunctionName { get; }
public object? Result { get; }
ctor(string? functionName = null, string? pluginName = null, string? id = null, object? result = null)
ctor(FunctionCallContent functionCall, object? result = null)
ctor(FunctionCallContent functionCallContent, FunctionResult result)
}
6.1 方案一:重命名 Id 为 CallId
将 Id 重命名为 CallId 并统一构造函数参数名,改动最小、语义最清晰:
public sealed class FunctionResultContent : KernelContent
{
public string? CallId { get; }
public string? PluginName { get; }
public string? FunctionName { get; }
public object? Result { get; }
ctor(string? functionName = null, string? pluginName = null, string? callId = null, object? result = null)
ctor(FunctionCallContent functionCallContent, object? result = null)
ctor(FunctionCallContent functionCallContent, FunctionResult functionResult)
}
6.2 方案二:组合 CallContent
采用组合方式,在 FunctionResultContent 内持有一个完整的 FunctionCallContent:
public sealed class FunctionResultContent : KernelContent
{
public FunctionCallContent CallContent { get; }
public object? Result { get; }
ctor(FunctionCallContent functionCallContent, object? result = null)
ctor(FunctionCallContent functionCallContent, FunctionResult functionResult)
}
优点:CallContent 可从响应中再次调用函数,便于某些重放场景;结果来源与结果本身数据(根类)职责分明;能保留调用时的参数信息。缺点:获取 call 详情需要多一层跳转。
6.3 决策与源码落地
最终决策采纳方案一(Id → CallId)。当前 FunctionResultContent.cs 的实现印证了这一点:CallId 属性(第 17 行)替代了原 Id,构造函数统一使用 functionCall / functionCallContent 命名,并从 FunctionCallContent 复制 Id/PluginName/FunctionName(第 58-64 行),同时提供 ToChatMessage()(第 81-84 行)便捷地将结果包装为 Tool 角色的 ChatMessageContent。测试见 FunctionResultContentTests.cs。
七、FileReferenceContent 与 AnnotationContent:保持实验,移出核心抽象
7.1 问题
FileReferenceContent 与 AnnotationContent 因序列化便利被放进了 SemanticKernel.Abstractions,但它们高度特化于 OpenAI Assistant API,不应长期留在核心抽象层——否则会鼓励其他包含 KernelContent 特化类型的包也照此耦合。ADR 建议将它们迁移到 SemanticKernel.Agents.OpenAI 项目,并保持实验状态。
#pragma warning disable SKEXP0110
[JsonDerivedType(typeof(AnnotationContent), typeDiscriminator: nameof(AnnotationContent))]
[JsonDerivedType(typeof(FileReferenceContent), typeDiscriminator: nameof(FileReferenceContent))]
#pragma warning disable SKEXP0110
public abstract class KernelContent { ... }
7.2 解决方案:JsonConverter 注解
更稳妥的做法是创建独立的 JsonConverter(如 KernelContentConverter)放在 Agents.OpenAI 项目中,为两个内容类型分别注解 [JsonConverter(typeof(KernelContentConverter))],由转换器依据 TypeDiscriminator 字段分派反序列化目标类型:
public class KernelContentConverter : JsonConverter<KernelContent>
{
public override KernelContent Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
using (var jsonDoc = JsonDocument.ParseValue(ref reader))
{
var root = jsonDoc.RootElement;
var typeDiscriminator = root.GetProperty("TypeDiscriminator").GetString();
switch (typeDiscriminator)
{
case nameof(AnnotationContent):
return JsonSerializer.Deserialize<AnnotationContent>(root.GetRawText(), options);
case nameof(FileReferenceContent):
return JsonSerializer.Deserialize<FileReferenceContent>(root.GetRawText(), options);
default:
throw new NotSupportedException($"Type discriminator '{typeDiscriminator}' is not supported.");
}
}
}
public override void Write(Utf8JsonWriter writer, KernelContent value, JsonSerializerOptions options)
{
JsonSerializer.Serialize(writer, value, value.GetType(), options);
}
}
[JsonConverter(typeof(KernelContentConverter))]
public class FileReferenceContent : KernelContent
{
public string FileId { get; init; } = string.Empty;
ctor()
ctor(string fileId, ...)
}
[JsonConverter(typeof(KernelContentConverter))]
public class AnnotationContent : KernelContent
{
public string? FileId { get; init; }
public string? Quote { get; init; }
public int StartIndex { get; init; }
public int EndIndex { get; init; }
public ctor()
public ctor(...)
}
7.3 源码现状
从当前仓库看,这两个类型仍保持实验状态:FileReferenceContent(dotnet/src/SemanticKernel.Abstractions/Contents/FileReferenceContent.cs)与 AnnotationContent(dotnet/src/SemanticKernel.Abstractions/Contents/AnnotationContent.cs)均标注 [Experimental("SKEXP0110")](分别在各自文件的第 12 行与第 11 行),且 AnnotationContent 的命名空间已归属 Microsoft.SemanticKernel.Agents,其 FileId/Quote 旧属性也已标记 [Obsolete] 并转向 ReferenceId/Label——呼应了"向 Agents 语义靠拢、逐步与核心抽象解耦"的方向。两者均有对应测试 FileReferenceContentTests.cs 与 AnnotationContentTests.cs。
八、决策结果汇总
| 内容类型 | 决策 | 说明 |
|---|---|---|
BinaryContent |
接受 | 重构为 Data/DataUri/Uri + CanRead 模型 |
ImageContent |
接受(破坏性变更) | 成为 BinaryContent 特化,不做向后兼容 |
AudioContent |
接受(实验性破坏性变更) | 成为 BinaryContent 特化 |
FunctionCallContent |
原样毕业 | 结构已成熟,无需变更 |
FunctionResultContent |
接受(实验性破坏性变更) | 属性 Id 重命名为 CallId |
FileReferenceContent / AnnotationContent |
维持现状 | 继续作为实验特性,建议迁往 Agents.OpenAI |
九、对开发者的实践启示
- 使用
BinaryContent时明确三种形态:外部引用用Uri(拒绝 data scheme)、内联字节用Data(配合MimeType)、内联文本编码用DataUri(支持 RFC 2397 参数并自动映射到Metadata的data-uri-*键)。读取前用CanRead判断内容是否可用。 - 善用
Data/DataUri互斥覆盖语义:设置Data会使旧DataUri失效,设置DataUri会覆盖MimeType与字节数据,因此同一实例不会出现两套矛盾的二进制内容——这正是本次毕业修复的核心缺陷。 - 特化内容类型(
ImageContent/AudioContent)可直接复用基类能力:当前两者的构造函数与BinaryContent完全同构,可像使用基类一样自由读写字节、data uri 与引用 uri,相关行为与校验由基类统一保证。 - 函数调用链路中,
FunctionCallContent与FunctionResultContent通过CallId关联:前者可用InvokeAsync直接执行,后者可用ToChatMessage()快速回填 Tool 角色消息,形成完整的"模型请求函数 → 执行 → 结果回传"闭环。 - 实验特性警示:
BinaryContent/AudioContent(SKEXP0001)与FileReferenceContent/AnnotationContent(SKEXP0110)仍带有[Experimental]标记,生产代码中启用它们需要显式抑制对应警告(如#pragma warning disable SKEXP0001),并关注后续版本变更。