Semantic Kernel 内核内容类型毕业指南:从实验特性到稳定 API 的演进路线

原创2026-09-10 17:38:191,994 阅读
文章标签:人工智能AI AgentAgent 框架多智能体大模型工具调用Agent 编排MCP ClientsPrompt 模板插件系统RAG

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 状态,但存在明显的行为缺陷,维护者认为有必要通过破坏性变更将其修复并升级为稳定状态:

  1. 当前 ImageContent 不从 BinaryContent 派生;
  2. 存在不良行为:允许同一实例同时持有不同的 DataUri 与 Data;
  3. Uri 属性同时被用作 data uri 和引用 uri 两种用途;
  4. Uri 不支持大型语言模型的 data uri 格式(.NET Uri 类型存在 ushort 长度限制,见 dotnet/runtime#96544);
  5. 对 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 更为简陋:

  1. 不支持 Uri 引用位置;
  2. Uri 属性同时混用 data uri 与引用 uri;
  3. Uri 不支持大型 data uri 格式;
  4. 对开发者而言内容是否可读不明确。
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

九、对开发者的实践启示

  1. 使用 BinaryContent 时明确三种形态:外部引用用 Uri(拒绝 data scheme)、内联字节用 Data(配合 MimeType)、内联文本编码用 DataUri(支持 RFC 2397 参数并自动映射到 Metadata 的 data-uri-* 键)。读取前用 CanRead 判断内容是否可用。
  2. 善用 Data/DataUri 互斥覆盖语义:设置 Data 会使旧 DataUri 失效,设置 DataUri 会覆盖 MimeType 与字节数据,因此同一实例不会出现两套矛盾的二进制内容——这正是本次毕业修复的核心缺陷。
  3. 特化内容类型(ImageContent/AudioContent)可直接复用基类能力:当前两者的构造函数与 BinaryContent 完全同构,可像使用基类一样自由读写字节、data uri 与引用 uri,相关行为与校验由基类统一保证。
  4. 函数调用链路中,FunctionCallContent 与 FunctionResultContent 通过 CallId 关联:前者可用 InvokeAsync 直接执行,后者可用 ToChatMessage() 快速回填 Tool 角色消息,形成完整的"模型请求函数 → 执行 → 结果回传"闭环。
  5. 实验特性警示:BinaryContent/AudioContent(SKEXP0001)与 FileReferenceContent/AnnotationContent(SKEXP0110)仍带有 [Experimental] 标记,生产代码中启用它们需要显式抑制对应警告(如 #pragma warning disable SKEXP0001),并关注后续版本变更。

延伸阅读

登录后查看全文
semantic-kernel