Semantic Kernel 破坏性变更管理规范ADR 0045深度解析从钻石依赖到平滑迁移的工程实践【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本文基于 Semantic Kernel 仓库中的架构决策记录 docs/decisions/0045-breaking-changes-guidance.mdADR 0045系统解读该 .NET 开源项目如何管理与约束破坏性变更Breaking Changes。文中结合仓库内的版本化策略、实验性 API 标记机制、废弃Obsolete实践与真实迁移指南帮助读者理解为什么 Semantic Kernel 将避免破坏性变更视为硬性约束、在何种例外场景下允许变更、以及当变更不可避免时项目如何通过迁移指南与新旧 API 并存期保护下游用户。读完本文你将掌握一套可直接借鉴的开源 SDK 兼容性治理方法论并能据此评估、规划你自己的库或应用中 API 演进策略。一、为什么必须避免破坏性变更钻石依赖问题的本质ADR 0045 开篇即点明决策的核心动因——钻石依赖问题Diamond Dependency Issue。这是 .NET 生态中一个经典且棘手的依赖冲突场景假设你的应用同时引用了包 A 和包 B而 A 与 B 又各自依赖同一包 C 的不同版本如 C v1.0 与 C v2.0。依赖图呈现钻石形状此时 .NET 运行时只能加载其中一个版本的 C。如果 C v1.0 与 v2.0 之间存在破坏性 API 变更那么依赖旧版本的一方就会在运行时抛出MethodNotFound、TypeLoadException等异常且这类问题往往在编译期无法发现只有运行到具体调用路径时才爆发。对于 Semantic Kernel 这类被大量应用作为中间层基础设施引用的 SDK 而言破坏性变更的风险被进一步放大同一进程中不同业务模块可能经由不同版本的 Semantic Kernel 间接交互。因此 ADR 0045 的结论非常明确Chosen option: We must avoid breaking changes in .Net because of the well known diamond dependency issue.这条决策不仅约束 .NET 实现其精神也辐射到仓库中 Python、Java 等其他语言实现的发布节奏见 docs/decisions/0036-semantic-kernel-release-versioning.md。二、决策驱动破坏性变更仅允许在两种情形下发生ADR 0045 明确列出允许破坏性变更的全部例外情形除此之外一律禁止实验性功能的更新Updates to an experimental feature当项目从实验特性中学习到新认知、需要修改其设计时允许破坏性变更。这与 Semantic Kernel 的实验性 API 可随时变化的定位一致。依赖项引入无法避免的破坏性变更When one of our dependencies introduces an unavoidable breaking change当下游依赖如 OpenAI SDK升级导致必须跟进时允许变更。同时文档也列举了为了适应新需求而必须移动must move to accommodate的典型场景这些场景本身不是豁免许可而是需要通过废弃Obsolete 迁移路径来处理的特殊情况发现安全漏洞或严重缺陷如数据丢失依赖项引入重大破坏性变更如全新的 OpenAI SDK当前实现存在严重局限如 AI 服务引入新能力旧 API 无法承载。针对上述场景决策规定了标准处理流程计划废弃相关 APIobsolete the API(s)并提供文档化的迁移路径documented migration path指向新的推荐模式。ADR 0045 特别以切换到新的 OpenAI .NET SDK为例——在过渡期内新旧 API 将并存支持a period where the new and old APIs will be supported让客户有充足时间完成迁移。三、强制要求破坏性变更必须被清晰记录与公示即便在允许破坏性变更的例外情形下ADR 0045 也提出了两项不可妥协的记录义务在 PR 描述中详细描述破坏性变更以便该描述被自动纳入发布说明release notes。这是变更信息的源头也是下游用户最先接触到的变更入口。更新 Learn Site 迁移指南文档并确保迁移指南的发布时间与包含该破坏性变更的版本发布时间同步coincide避免版本已发布、迁移文档缺席的空窗期。这两条要求构成了 Semantic Kernel 变更治理的完整闭环PR 描述 → 发布说明 → 迁移指南任何一环缺失都视为不合规。四、源码落地实验性特性与废弃 API 的工程机制ADR 0045 描述的是决策层原则而仓库源码则展示了这些原则如何在代码层面强制执行。理解这些机制能帮助贡献者判断我的改动是否构成破坏性变更、应走哪条流程。4.1 实验性 APIExperimentalAttribute 与 SKEXP 诊断码仓库在 dotnet/src/InternalUtilities/src/Diagnostics/ExperimentalAttribute.cs 中内联了一份ExperimentalAttribute的实现该实现源自 .NET RuntimeSemantic Kernel 以 internal 形式复制以便在 .NET 8 之前的目标框架上使用。该特性接受一个diagnosticId参数编译器会据此对调用实验性 API 的调用方产生诊断警告或错误。其 XML 注释明确说明Indicates that an API is experimental and it may change in the future——这正是 ADR 0045 中实验性功能允许破坏性变更条款的代码级前置声明。配套的 dotnet/docs/EXPERIMENTS.md 维护着一张实验性功能诊断码对照表例如SKEXP 代码实验性功能类别SKEXP0001Semantic Kernel 核心功能Embedding、Image、Memory 连接器、Kernel filters、Audio 服务SKEXP0010OpenAI 与 Azure OpenAI 服务SKEXP0020Memory 连接器SKEXP0040函数类型GRPC / Markdown / OpenAPI / PromptySKEXP0050开箱即用的插件SKEXP0060PlannersSKEXP0080Process FrameworkSKEXP0110Agent Framework对于使用方可以在项目文件中通过NoWarn抑制特定实验性 API 的警告。例如 dotnet/docs/EXPERIMENTS.md 给出的配置PropertyGroup NoWarn$(NoWarn);SKEXP0001,SKEXP0010/NoWarn /PropertyGroup仓库示例代码中也有大量#pragma warning disable SKEXP0001的用法如 dotnet/samples/Demos/AIModelRouter/CustomRouter.cs说明这是社区普遍采用的按需抑制方式。4.2 正式 API 的废弃Obsolete 特性与替代指引对于已稳定但需要被替代的 API仓库使用 .NET 标准的[Obsolete]特性并且在废弃消息中明确指出替代方案。最典型的例子是 dotnet/src/SemanticKernel.Abstractions/Kernel.cs 中Kernel的四个事件——FunctionInvoking、FunctionInvoked、PromptRendering、PromptRendered[EditorBrowsable(EditorBrowsableState.Never)] [Obsolete(Events are deprecated in favor of filters. Example in dotnet/samples/GettingStarted/Step7_Observability.cs of Semantic Kernel repository.)] public event EventHandlerFunctionInvokingEventArgs? FunctionInvoking;这里体现了三个细节指明替代方向消息明确Events 已废弃改用 Filters并给出仓库内示例文件 dotnet/samples/GettingStarted/Step7_Observability.cs 作为迁移指引隐藏过时 API[EditorBrowsable(EditorBrowsableState.Never)]让过时成员在 IDE 智能提示中不再出现引导开发者主动迁移但并不删除保证既有代码仍可编译运行源码与决策的呼应这套废弃 引导迁移 保留兼容的流程正是 ADR 0045 中obsolete the API(s) and provide a documented migration path的落地形态。五、配套的版本化策略ADR 0036 如何配合变更治理破坏性变更治理与版本号策略密不可分。仓库中的 docs/decisions/0036-semantic-kernel-release-versioning.md 补充了 ADR 0045 的发布侧约束两者共同构成完整的兼容性契约不严格遵循语义化版本semver因为 NuGet 生态并不严格遵循 semverSemantic Kernel 选择务实策略低影响的不兼容 API 变更不提升 MAJOR 版本这类变更通常只影响 Semantic Kernel 内部实现或单元测试且项目预期 API 表面不会有重大调整实验性功能或 alpha 包的 API 变更不提升 MAJOR 版本与 ADR 0045实验性功能允许破坏性变更条款严格对应MINOR 版本在向后兼容地新增功能时递增PATCH 版本在仅含向后兼容的缺陷修复时递增版本后缀约定preview.NET/betaPython表示接近正式发布、接口已基本冻结alpha表示功能未完成、公共接口仍在开发中且预期会变化。对下游用户而言这套策略的含义是使用alpha后缀的包时必须预期 API 随时变化使用正式版本时项目承诺尽最大努力避免破坏性变更一旦发生破坏性变更必有发布说明与迁移指南。六、实战范例OpenAI Connector 迁移指南的完整剖析ADR 0045 中切换到新 OpenAI .NET SDK的示例在仓库中已有完整的实践产物——dotnet/docs/OPENAI-CONNECTOR-MIGRATION.md。这份文档是理解项目如何处理一次大规模破坏性变更的最佳教材它展示了 ADR 0045 要求的迁移路径文档应该包含哪些内容1. 包与命名空间迁移兼容性过渡- // Before - using Microsoft.SemanticKernel.Connectors.OpenAI; After using Microsoft.SemanticKernel.Connectors.AzureOpenAI;其中特别说明Microsoft.SemanticKernel.Connectors.AzureOpenAI包依赖Microsoft.SemanticKernel.Connectors.OpenAI包因此使用 OpenAI 相关类型时无需同时引用两个包。这正是 ADR 0045 所述新旧 API 并存期的包级实现。2. 被移除的能力与替代方案OpenAITextGenerationService/AzureOpenAITextGenerationService被移除新版 OpenAI SDK 不支持 text generation modality需改用OpenAIChatCompletionService/AzureOpenAIChatCompletionService同时注明 ChatCompletion 服务仍实现ITextGenerationService接口面向接口的代码可能无需改动ResultsPerPrompt多候选结果从OpenAIPromptExecutionSettings中移除OpenAIFileService被废弃推荐改用OpenAIClient.GetFileClient()。3. 行为变化清单Breaking glass scenarios文档第 9 节列出了一系列你可能需要更新代码的行为级变化例如元数据键名变化Created→CreatedAt、tool_calls→ToolCallsFinishReason 字符串值从stop变为StopToken 命名约定从Completion/Prompt改为Output/Input类型从CompletionsUsage改为ChatTokenUsage- var usage FunctionResult.Metadata?[Usage] as CompletionsUsage; - var completionTokesn usage?.CompletionTokens ?? 0; - var promptTokens usage?.PromptTokens ?? 0; var usage FunctionResult.Metadata?[Usage] as ChatTokenUsage; var promptTokens usage?.InputTokens ?? 0; var completionTokens usage?.OutputTokens ?? 0;传输管道配置从Azure.Core.Pipeline的HttpClientTransport改为新 OpenAI SDK基于System.ClientModel的HttpClientPipelineTransportvar clientOptions new OpenAIClientOptions { - // Before: From Azure.Core.Pipeline - Transport new HttpClientTransport(httpClient), // After: From OpenAI SDK - System.ClientModel Transport new HttpClientPipelineTransport(httpClient), };这份迁移指南完美印证了 ADR 0045 的治理闭环依赖OpenAI SDK引入不可避免的破坏性变更 → 项目跟进 → 用迁移指南完整记录每一项变更及其替代方案 → 与新版发布同步公示。七、给贡献者与下游开发者的实践清单综合 ADR 0045 与仓库源码可以提炼出对两类角色的可操作建议如果你是 Semantic Kernel 贡献者改动前先判断是否触及公共 API若涉及确认目标 API 是否为实验性是否带有SKEXPxxxx诊断码非实验性 API 的破坏性变更默认不被接受若确属依赖强制升级等例外必须在 PR 描述中详尽列出变更点使其进入发布说明采用先废弃、后移除的节奏用[Obsolete]标注并提供替代方案指引参考 Kernel.cs 的写法保留新旧并存过渡期同步编写迁移指南文档并保证其与发布同步上线。如果你使用 Semantic Kernel下游消费者优先使用preview/beta之前的正式版本或固定版本号并关注发布说明升级前先检索对应版本的迁移指南如 dotnet/docs/OPENAI-CONNECTOR-MIGRATION.md按代码替换清单逐项核对当引入实验性功能时记录其SKEXP诊断码并在项目文件中显式NoWarn或集中管理便于日后追踪实验性 API 的变更。八、总结ADR 0045 表面上看是一条简短的决策记录但它在 Semantic Kernel 仓库中串联起了一整套完整的兼容性工程体系以钻石依赖问题为约束原点以实验性功能 依赖强制升级为唯二例外以 PR 描述、发布说明、迁移指南三级文档为公示机制以 ExperimentalAttribute、Obsolete 特性、SKEXP 诊断码为代码落地手段以版本化策略ADR 0036与真实迁移指南为配套支撑。这种原则上零破坏、例外必记录、迁移必有文档的治理模式正是大型开源 SDK 在快速迭代与下游稳定性之间取得平衡的关键值得任何面向开发者的库或框架团队借鉴。延伸阅读仓库内决策记录原文docs/decisions/0045-breaking-changes-guidance.md版本化策略docs/decisions/0036-semantic-kernel-release-versioning.md实验性功能清单与 SKEXP 代码表dotnet/docs/EXPERIMENTS.md真实迁移指南范例dotnet/docs/OPENAI-CONNECTOR-MIGRATION.mdExperimentalAttribute 实现dotnet/src/InternalUtilities/src/Diagnostics/ExperimentalAttribute.csObsolete API 落地示例dotnet/src/SemanticKernel.Abstractions/Kernel.cs【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考