Semantic Kernel .NET 连接器底层 SDK 版本策略解析Azure OpenAI / OpenAI 的 GA 与 Preview 抉择【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文围绕 Semantic Kernel 仓库中的架构决策记录 0055-dotnet-azureopenai-stable-version-strategy.md 展开剖析 2024 年 10 月 OpenAI 与 Azure OpenAI 底层 SDK 发布首个稳定版GA之后.NET 版连接器Connectors应如何选择版本策略的完整决策过程。读完本文你将理解「Keep As-Is」「Preview GA 双轨」「仅依赖 GA」三种方案的取舍逻辑、SKEXP 实验特性标识机制以及 Semantic Kernel 连接器包与底层 SDK 版本之间的映射与分支策略并能在自己的项目中正确判断如何消费这些包。背景GA 发布带来的版本策略十字路口2024 年 10 月 1 日OpenAI 与 Azure OpenAI 同时发布了各自底层 SDK 的第一个稳定GA版本。然而Azure OpenAI 的 GA 包相比之前的 preview 包移除了一大批原本在 preview 阶段可用的功能。这迫使 Semantic Kernel 团队重新审视连接器后续版本的依赖策略。当时涉及的两个连接器及其对应关系如下名称SDK 命名空间Semantic Kernel 命名空间OpenAI (OAI)OpenAIMicrosoft.SemanticKernel.Connectors.OpenAIAzure OpenAI (AOAI)Azure.AI.OpenAIMicrosoft.SemanticKernel.Connectors.AzureOpenAI在仓库中两个连接器项目的物理位置与命名空间一一对应Connectors.OpenAI.csproj程序集名Microsoft.SemanticKernel.Connectors.OpenAI直接引用OpenAI与Microsoft.Extensions.AI.OpenAI包Connectors.AzureOpenAI.csproj程序集名Microsoft.SemanticKernel.Connectors.AzureOpenAI直接引用Azure.AI.OpenAI包并项目引用 OpenAI 连接器因为 AzureOpenAI 服务在实现上复用了大量 OpenAI 的公共类型与逻辑。决策驱动因素团队在权衡方案时明确列出了以下驱动因素最小化对现有客户的影响允许客户自主选择使用 GA 或 Beta 版本的 OpenAI / Azure.AI.OpenAI 包保持对外策略信息的清晰一致保持与历史版本的兼容性包版本号应能清楚表明其依赖的 OpenAI / Azure.AI.OpenAI 版本与 Semantic Kernel 既有版本策略见 0036-semantic-kernel-release-versioning.md相协调并兼容其他 SDK 的版本策略。值得一提的是Semantic Kernel 自身的版本策略并不严格遵循 semver低影响的破坏性 API 变更不会提升 MAJOR 版本多数常规更新向后兼容且所有包在同一发布中使用相同版本号。这一背景决定了连接器版本策略必须与主版本节奏保持一致。三个候选方案方案一Keep As-Is —— 仅依赖 preview 包该方案维持现状连接器继续只针对底层 SDK 的 preview 包发布对现有客户与发布管线影响最小。当时所有已在使用 Azure OpenAI 连接器的客户其流水线都是针对 preview 包配置的。优点策略不变对客户影响最小保持与历史版本和既有 GA 目标版本、管线的兼容与之前「瞄准 preview 包」的策略一致Azure 与 OpenAI SDK 始终与新的 GA 版本保持同步可继续用「preview 目标 最新 GA 补丁」的方式跟进。缺点不存在一个对应稳定 GA 包的 SK 连接器版本对「只允许 GA 依赖」的新客户不友好——这类客户无法使用 SK 连接器团队估计这部分客户数量很小因为过去 18 个月已有大量客户接受 Azure OpenAI SDK 的 preview 版本OpenAI / Azure.AI.OpenAI 的 beta 版本可能引入意外破坏性变更并经由依赖关系传导给 SK。方案二Preview GA 双轨版本化最终未选但作为未来备选该方案为连接器引入双轨版本GA 版连接器依赖底层 SDK 的GA 版本Pre-release 版连接器依赖底层 SDK 的pre-release 版本。对于底层 SDK 已移除的 preview-only 功能Semantic Kernel 连接器会使用SKEXP0011专用实验标识Experimental attribute进行标注向用户明确「从 GA 包迁移可能带来的影响」一旦这些功能在 SDK GA 版中正式支持标注即被移除。优点对外传递清晰信号什么是 Azure / OpenAI 官方认定的稳定能力SK 的 GA 版就只暴露这些稳定能力有「依赖也必须是 GA」硬性要求的客户可以正常使用 SK 连接器新特性可以在连接器的 preview 版本中先行落地不影响连接器 GA 版本。缺点改变了既有版本策略首批发布需要充分的说明与沟通以平滑过渡原来在 SK GA 包中使用 OpenAI / AzureOpenAI preview 特性的客户需要把流水线切换到未来的 SK pre-release 版本维护两套连接器版本带来少量额外开销。双轨策略下的版本与分支策略若采用该方案会为连接器目标 GA 版本创建专门的 release 分支并在其中记录所有为适配稳定版而做的修改/移除同时作为在 API 与示例中增删SKEXP0011豁免的重要准则。版本节奏在原有基础上为底层 SDK beta 版本增加beta前缀序号OpenAI 版本Azure OpenAI 版本Semantic Kernel 版本¹分支12.0.02.0.01.25.0releases/1.25.022.1.0-beta.12.1.0-beta.11.26.0-betamain32.1.0-beta.32.1.0-beta.21.27.0-betamain4无变更无变更1.27.1-beta²main52.1.02.1.01.28.0releases/1.28.062.2.0-beta.12.1.0-beta.11.29.0-betamain版本同时适用于连接器包与Semantic Kernel 元包meta package。SDK 无变更但 Semantic Kernel 代码库有其他次要变更需要升级版本。可选平滑过渡Optional Smoothing Transition为缓解客户冲击文档提出可设置一个「过渡期通知」期间仍维持Keep As-Is策略给客户足够时间迁移到未来的 preview / GA 双轨版本体系。方案三停止依赖 preview 包不推荐[!WARNING] 该选项虽被正式考虑但不推荐。该方案严格遵循 1.0 GA 策略不再让客户暴露于非 GA 的 SDK 特性。但当时包括 Azure Assistants 在内的重量级功能仍处于 preview 状态——Assistants、Audio Generation、Batch、Files、Fine-Tuning、Vector Stores 等均不在 GA surface 内只能通过 preview 库发布与对应的 Azure OpenAI Service api-version 标签使用——因此该方案将对瞄准 Agent 框架等 preview 能力的客户造成巨大冲击。优点连接器只发布 GA 版本SK GA 包绝不把 preview 特性当作 GA 特性暴露符合「负责任 GA」原则。缺点对正在使用 preview 特性的客户冲击巨大且没有 preview 版连接器可供回退会使 Semantic Kernel 与 Assistants 等 Azure preview 特性的组合在实践上不可用。最终决策Keep As-Is决策结论选择「Keep As-Is」。理由当前 AI SDK 领域变化极快既要能及时跟进更新又要尽可能不搅乱既有版本策略、把对客户的影响降到最低。团队决定现阶段维持Keep As-Is未来在「切换为 Preview GA 双轨」不会对客户群已依赖的重要功能造成重大缺失时再重新考虑该方案。从仓库现状验证该策略的落地情况ADR 是 2024-10 的决策我们可以从当前仓库的实际文件验证其落地形态1. 依赖仍然以 beta / GA 混合形式存在。在 Directory.Packages.props中央包版本管理中Azure.AI.OpenAI引用版本为2.9.0-beta.1仍为 betaOpenAI引用版本为2.10.0已为 GA。这正对应「Keep As-Is」策略的典型形态随着 SDK 迭代部分依赖已跟上 GA部分仍停留在 beta由连接器按需选择。2. 实验特性用 SKEXP 标识标注。ADR 中提到的SKEXP0011专属标识在后续演进中已并入SKEXP0010OpenAI 与 Azure OpenAI 服务类别。当前 EXPERIMENTS.md 明确列出SKEXP0010覆盖「Azure OpenAI with your data service」「OpenAI embedding service」「OpenAI image service」「OpenAI parameters」「OpenAI chat history extension」「OpenAI file service」等实验性能力并给出通过NoWarn抑制警告的示例PropertyGroup NoWarn$(NoWarn);SKEXP0001,SKEXP0010/NoWarn /PropertyGroup在连接器 csproj 中也能看到实验标识的集中处理例如 Connectors.OpenAI.csproj 与 Connectors.AzureOpenAI.csproj 均声明了SKEXP0001,SKEXP0010,OPENAI001的NoWarn其中OPENAI001来自底层 OpenAI SDK 自身的实验性警告。3. 代码层面对 preview-only 特性的处理方式与 ADR 一致。以 AzureOpenAIPromptExecutionSettings.cs 为例UserSecurityContext、SetNewMaxCompletionTokensEnabled、AzureChatDataSource三个属性均标记了[Experimental(SKEXP0010)]AzureChatDataSource依赖的AzureSearchChatDataSource类型来自底层 SDK 的评估用途类型代码中用#pragma warning disable AOAI001/#pragma warning restore AOAI001包裹并保留[JsonIgnore]以确保其不被常规 JSON 序列化路径意外暴露。这种「实验属性 编译器警告抑制 文档登记」的组合正是 ADR 0055 设想的「preview-only 能力在 GA 包中被明确标注、便于用户识别迁移影响」的工程落地形态。4. 连接器版本与 SK 主版本保持同步。nuget-package.props 中的中央VersionPrefix当前为1.80.0统一应用于所有 NuGet 包连接器包与元包共用一个版本号验证了 ADR 0055 中「连接器包与 Semantic Kernel 元包共享版本节奏」的约定。对使用者的启示结合 ADR 0055 的决策与仓库现状.NET 开发者在消费这些连接器时应注意确认依赖版本的性质引用Microsoft.SemanticKernel.Connectors.OpenAI/Microsoft.SemanticKernel.Connectors.AzureOpenAI时其传递依赖的底层 SDK 可能是 GA 也可能是 beta当前 Azure.AI.OpenAI 即为2.9.0-beta.1。对底层依赖有严格 GA 要求的项目需在升级 SK 前核对 Directory.Packages.props 中的实际版本。留意 SKEXP0010 实验 API凡是打上[Experimental(SKEXP0010)]的连接器 API如 AzureChatDataSource、SetNewMaxCompletionTokensEnabled 等都可能随底层 SDK 演进而变化生产代码应避免强依赖或做好升级预案如需快速评估可参考 EXPERIMENTS.md 中的实验特性清单。关注 release 分支与版本号节奏参考 ADR 0055 中的版本映射表SK 主版本如 1.25.0 → 1.28.0会随底层 SDK 的 GA/beta 迭代而推进连接器包与元包同号发布升级时尽量保持各 SK 包版本一致这也是 0036-semantic-kernel-release-versioning.md 的建议。总体而言ADR 0055 展示了一次典型的「受控妥协」在底层 SDK 快速演进的背景下优先保障存量用户的稳定体验Keep As-Is同时通过 SKEXP 实验标识与清晰的版本沟通机制为未来切换「Preview GA 双轨」预留了平滑路径。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Semantic Kernel .NET 连接器底层 SDK 版本策略解析：Azure OpenAI / OpenAI 的 GA 与 Preview 抉择
Semantic Kernel .NET 连接器底层 SDK 版本策略解析Azure OpenAI / OpenAI 的 GA 与 Preview 抉择【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文围绕 Semantic Kernel 仓库中的架构决策记录 0055-dotnet-azureopenai-stable-version-strategy.md 展开剖析 2024 年 10 月 OpenAI 与 Azure OpenAI 底层 SDK 发布首个稳定版GA之后.NET 版连接器Connectors应如何选择版本策略的完整决策过程。读完本文你将理解「Keep As-Is」「Preview GA 双轨」「仅依赖 GA」三种方案的取舍逻辑、SKEXP 实验特性标识机制以及 Semantic Kernel 连接器包与底层 SDK 版本之间的映射与分支策略并能在自己的项目中正确判断如何消费这些包。背景GA 发布带来的版本策略十字路口2024 年 10 月 1 日OpenAI 与 Azure OpenAI 同时发布了各自底层 SDK 的第一个稳定GA版本。然而Azure OpenAI 的 GA 包相比之前的 preview 包移除了一大批原本在 preview 阶段可用的功能。这迫使 Semantic Kernel 团队重新审视连接器后续版本的依赖策略。当时涉及的两个连接器及其对应关系如下名称SDK 命名空间Semantic Kernel 命名空间OpenAI (OAI)OpenAIMicrosoft.SemanticKernel.Connectors.OpenAIAzure OpenAI (AOAI)Azure.AI.OpenAIMicrosoft.SemanticKernel.Connectors.AzureOpenAI在仓库中两个连接器项目的物理位置与命名空间一一对应Connectors.OpenAI.csproj程序集名Microsoft.SemanticKernel.Connectors.OpenAI直接引用OpenAI与Microsoft.Extensions.AI.OpenAI包Connectors.AzureOpenAI.csproj程序集名Microsoft.SemanticKernel.Connectors.AzureOpenAI直接引用Azure.AI.OpenAI包并项目引用 OpenAI 连接器因为 AzureOpenAI 服务在实现上复用了大量 OpenAI 的公共类型与逻辑。决策驱动因素团队在权衡方案时明确列出了以下驱动因素最小化对现有客户的影响允许客户自主选择使用 GA 或 Beta 版本的 OpenAI / Azure.AI.OpenAI 包保持对外策略信息的清晰一致保持与历史版本的兼容性包版本号应能清楚表明其依赖的 OpenAI / Azure.AI.OpenAI 版本与 Semantic Kernel 既有版本策略见 0036-semantic-kernel-release-versioning.md相协调并兼容其他 SDK 的版本策略。值得一提的是Semantic Kernel 自身的版本策略并不严格遵循 semver低影响的破坏性 API 变更不会提升 MAJOR 版本多数常规更新向后兼容且所有包在同一发布中使用相同版本号。这一背景决定了连接器版本策略必须与主版本节奏保持一致。三个候选方案方案一Keep As-Is —— 仅依赖 preview 包该方案维持现状连接器继续只针对底层 SDK 的 preview 包发布对现有客户与发布管线影响最小。当时所有已在使用 Azure OpenAI 连接器的客户其流水线都是针对 preview 包配置的。优点策略不变对客户影响最小保持与历史版本和既有 GA 目标版本、管线的兼容与之前「瞄准 preview 包」的策略一致Azure 与 OpenAI SDK 始终与新的 GA 版本保持同步可继续用「preview 目标 最新 GA 补丁」的方式跟进。缺点不存在一个对应稳定 GA 包的 SK 连接器版本对「只允许 GA 依赖」的新客户不友好——这类客户无法使用 SK 连接器团队估计这部分客户数量很小因为过去 18 个月已有大量客户接受 Azure OpenAI SDK 的 preview 版本OpenAI / Azure.AI.OpenAI 的 beta 版本可能引入意外破坏性变更并经由依赖关系传导给 SK。方案二Preview GA 双轨版本化最终未选但作为未来备选该方案为连接器引入双轨版本GA 版连接器依赖底层 SDK 的GA 版本Pre-release 版连接器依赖底层 SDK 的pre-release 版本。对于底层 SDK 已移除的 preview-only 功能Semantic Kernel 连接器会使用SKEXP0011专用实验标识Experimental attribute进行标注向用户明确「从 GA 包迁移可能带来的影响」一旦这些功能在 SDK GA 版中正式支持标注即被移除。优点对外传递清晰信号什么是 Azure / OpenAI 官方认定的稳定能力SK 的 GA 版就只暴露这些稳定能力有「依赖也必须是 GA」硬性要求的客户可以正常使用 SK 连接器新特性可以在连接器的 preview 版本中先行落地不影响连接器 GA 版本。缺点改变了既有版本策略首批发布需要充分的说明与沟通以平滑过渡原来在 SK GA 包中使用 OpenAI / AzureOpenAI preview 特性的客户需要把流水线切换到未来的 SK pre-release 版本维护两套连接器版本带来少量额外开销。双轨策略下的版本与分支策略若采用该方案会为连接器目标 GA 版本创建专门的 release 分支并在其中记录所有为适配稳定版而做的修改/移除同时作为在 API 与示例中增删SKEXP0011豁免的重要准则。版本节奏在原有基础上为底层 SDK beta 版本增加beta前缀序号OpenAI 版本Azure OpenAI 版本Semantic Kernel 版本¹分支12.0.02.0.01.25.0releases/1.25.022.1.0-beta.12.1.0-beta.11.26.0-betamain32.1.0-beta.32.1.0-beta.21.27.0-betamain4无变更无变更1.27.1-beta²main52.1.02.1.01.28.0releases/1.28.062.2.0-beta.12.1.0-beta.11.29.0-betamain版本同时适用于连接器包与Semantic Kernel 元包meta package。SDK 无变更但 Semantic Kernel 代码库有其他次要变更需要升级版本。可选平滑过渡Optional Smoothing Transition为缓解客户冲击文档提出可设置一个「过渡期通知」期间仍维持Keep As-Is策略给客户足够时间迁移到未来的 preview / GA 双轨版本体系。方案三停止依赖 preview 包不推荐[!WARNING] 该选项虽被正式考虑但不推荐。该方案严格遵循 1.0 GA 策略不再让客户暴露于非 GA 的 SDK 特性。但当时包括 Azure Assistants 在内的重量级功能仍处于 preview 状态——Assistants、Audio Generation、Batch、Files、Fine-Tuning、Vector Stores 等均不在 GA surface 内只能通过 preview 库发布与对应的 Azure OpenAI Service api-version 标签使用——因此该方案将对瞄准 Agent 框架等 preview 能力的客户造成巨大冲击。优点连接器只发布 GA 版本SK GA 包绝不把 preview 特性当作 GA 特性暴露符合「负责任 GA」原则。缺点对正在使用 preview 特性的客户冲击巨大且没有 preview 版连接器可供回退会使 Semantic Kernel 与 Assistants 等 Azure preview 特性的组合在实践上不可用。最终决策Keep As-Is决策结论选择「Keep As-Is」。理由当前 AI SDK 领域变化极快既要能及时跟进更新又要尽可能不搅乱既有版本策略、把对客户的影响降到最低。团队决定现阶段维持Keep As-Is未来在「切换为 Preview GA 双轨」不会对客户群已依赖的重要功能造成重大缺失时再重新考虑该方案。从仓库现状验证该策略的落地情况ADR 是 2024-10 的决策我们可以从当前仓库的实际文件验证其落地形态1. 依赖仍然以 beta / GA 混合形式存在。在 Directory.Packages.props中央包版本管理中Azure.AI.OpenAI引用版本为2.9.0-beta.1仍为 betaOpenAI引用版本为2.10.0已为 GA。这正对应「Keep As-Is」策略的典型形态随着 SDK 迭代部分依赖已跟上 GA部分仍停留在 beta由连接器按需选择。2. 实验特性用 SKEXP 标识标注。ADR 中提到的SKEXP0011专属标识在后续演进中已并入SKEXP0010OpenAI 与 Azure OpenAI 服务类别。当前 EXPERIMENTS.md 明确列出SKEXP0010覆盖「Azure OpenAI with your data service」「OpenAI embedding service」「OpenAI image service」「OpenAI parameters」「OpenAI chat history extension」「OpenAI file service」等实验性能力并给出通过NoWarn抑制警告的示例PropertyGroup NoWarn$(NoWarn);SKEXP0001,SKEXP0010/NoWarn /PropertyGroup在连接器 csproj 中也能看到实验标识的集中处理例如 Connectors.OpenAI.csproj 与 Connectors.AzureOpenAI.csproj 均声明了SKEXP0001,SKEXP0010,OPENAI001的NoWarn其中OPENAI001来自底层 OpenAI SDK 自身的实验性警告。3. 代码层面对 preview-only 特性的处理方式与 ADR 一致。以 AzureOpenAIPromptExecutionSettings.cs 为例UserSecurityContext、SetNewMaxCompletionTokensEnabled、AzureChatDataSource三个属性均标记了[Experimental(SKEXP0010)]AzureChatDataSource依赖的AzureSearchChatDataSource类型来自底层 SDK 的评估用途类型代码中用#pragma warning disable AOAI001/#pragma warning restore AOAI001包裹并保留[JsonIgnore]以确保其不被常规 JSON 序列化路径意外暴露。这种「实验属性 编译器警告抑制 文档登记」的组合正是 ADR 0055 设想的「preview-only 能力在 GA 包中被明确标注、便于用户识别迁移影响」的工程落地形态。4. 连接器版本与 SK 主版本保持同步。nuget-package.props 中的中央VersionPrefix当前为1.80.0统一应用于所有 NuGet 包连接器包与元包共用一个版本号验证了 ADR 0055 中「连接器包与 Semantic Kernel 元包共享版本节奏」的约定。对使用者的启示结合 ADR 0055 的决策与仓库现状.NET 开发者在消费这些连接器时应注意确认依赖版本的性质引用Microsoft.SemanticKernel.Connectors.OpenAI/Microsoft.SemanticKernel.Connectors.AzureOpenAI时其传递依赖的底层 SDK 可能是 GA 也可能是 beta当前 Azure.AI.OpenAI 即为2.9.0-beta.1。对底层依赖有严格 GA 要求的项目需在升级 SK 前核对 Directory.Packages.props 中的实际版本。留意 SKEXP0010 实验 API凡是打上[Experimental(SKEXP0010)]的连接器 API如 AzureChatDataSource、SetNewMaxCompletionTokensEnabled 等都可能随底层 SDK 演进而变化生产代码应避免强依赖或做好升级预案如需快速评估可参考 EXPERIMENTS.md 中的实验特性清单。关注 release 分支与版本号节奏参考 ADR 0055 中的版本映射表SK 主版本如 1.25.0 → 1.28.0会随底层 SDK 的 GA/beta 迭代而推进连接器包与元包同号发布升级时尽量保持各 SK 包版本一致这也是 0036-semantic-kernel-release-versioning.md 的建议。总体而言ADR 0055 展示了一次典型的「受控妥协」在底层 SDK 快速演进的背景下优先保障存量用户的稳定体验Keep As-Is同时通过 SKEXP 实验标识与清晰的版本沟通机制为未来切换「Preview GA 双轨」预留了平滑路径。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考