2026/9/10 21:49:43
FEATURED · 精选文章 
Semantic Kernel 示例代码仓库重构方案解析从 ADR-0042 到samples目录的落地实践【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本篇技术指南以 Semantic Kernel 仓库中的架构决策记录 docs/decisions/0042-samples-restructure.mdADR-00422024-04-18 通过为骨架系统梳理该仓库如何将杂乱无章的示例代码重构为「按类型分层、按特性分组、跨语言一致」的样本结构。你将掌握五种示例类型的划分标准、根目录结构三种候选方案的取舍逻辑、KernelSyntaxExamples四种分解策略的对比以及最终决策在 .NET 与 Python 仓库中的实际落地形态从而能够在向仓库贡献新示例时快速判断“该放哪个目录、叫什么名字、遵循什么约定”。一、重构背景旧结构为什么难用ADR-0042 开篇即点出了旧示例结构的四个核心痛点信息量低、难以被发现示例的存放方式缺乏可预测性使用者无法凭直觉找到目标示例编号失去意义KernelSyntaxExamples中超过 70 个带编号的示例平铺并列数字编号既不表示学习进度也无法传达示例内容命名无法传递意图项目名称无法让人一眼看出“这到底是什么”冗余后缀文件夹和解决方案带有Examples后缀而samples目录下的一切本质上都是示例后缀纯属多余。二、示例类型学五种样本的明确定义决策文档首先建立了一套统一的“示例类型学”这是后续所有目录决策的基础类型描述GettingStarted单一的分步上手教程step-by-step tutorial to get startedConcepts按特性组织的聚焦代码片段concept by feature specific code snippetsLearnResources与在线文档Microsoft Learn、DevBlogs 等对应的代码片段Tutorials更深入的分步教程Demos演示一个或多个特性组合的完整应用程序这套分类同时成为跨语言一致性的基准所有受支持的 SK 语言版本.NET、Python 等都遵循相近的样本结构。三、决策驱动原则与旧目录迁移策略3.1 四条决策原则原则含义Easy to Search易于搜索结构组织良好便于找到不同类型的样本Lean namings精简命名文件夹、解决方案和示例名称尽可能清晰、简短Sends a Clear Message传达清晰信息避免使用 Semantic Kernel 特有的术语或行话Cross Language跨语言所有受支持的 SK 语言采用相似的样本结构3.2 旧目录的具体迁移方案原文件夹迁移方案KernelSyntaxExamples/Getting_Started移入GettingStartedKernelSyntaxExamples/Examples??_*拆解到Concepts下的多个概念子文件夹AgentSyntaxExamples拆解到Concepts下的Agents子文件夹DocumentationExamples移入LearnResources子文件夹并重命名为MicrosoftLearnCreateChatGptPlugin移入Demo子文件夹HomeAutomation移入Demo子文件夹TelemetryExample移入Demo子文件夹并重命名为TelemetryWithAppInsightsHuggingFaceImageTextExample移入Demo子文件夹并重命名为HuggingFaceImageToText四、根目录结构三个候选方案对比Option 1 - Ultra Narrow Root Categorization超窄根部分类将samples根目录压缩到极简的少数几个分类samples/ ├── Tutorials/ │ └── Getting Started/ ├── Concepts/ │ ├── Kernel Syntax** │ └── Agents Syntax** ├── Resources/ └── Demos/优点结构更简单、更少冗长“少即是多”新手能看到并排的其他教程按需选择不强制从 Getting Started 开始。缺点需要额外认知负担才能明白 “Getting Started” 属于 tutorial 的一种。Option 2 - Getting Started Root CategorizationGetting Started 根级分类✅ 最终采纳与 Option 1 相比将Getting Started提升到samples根目录的独立一级samples/ ├── Getting Started/ ├── Tutorials/ ├── Concepts/ │ ├── Kernel Syntax Decomposition** │ └── Agents Syntax Decomposition** ├── Resources/ └── Demos/优点Getting Started 是客户最先看到的内容。缺点若 Getting Started 示例对该客户不适用需要返回其他文件夹寻找内容。Option 3 - Conservative Use Cases Based Root Categorization保守 用例分类保留 Syntax Examples 项目为根级选项同时新增 Use Cases、Modalities、Kernel Content 等文件夹samples/ |── QuickStart/ |── Tutorials/ ├── KernelSyntaxExamples/ ├── AgentSyntaxExamples/ ├── UseCases/ OR Demos/ ├── KernelContent/ OR Modalities/ ├── Documentation/ OR Resources/优点更保守保留KernelSyntaxExamples和AgentSyntaxExamples根级目录不会破坏已有的互联网链接。缺点更冗长的结构增加寻找样本的摩擦KernelContent/Modalities是内部术语客户难以理解Documentation容易被误认为纯文档目录Use Cases暗示真实业务场景而实际只是 SK 特性的简单演示。五、KernelSyntaxExamples分解四个候选方案KernelSyntaxExamples内含 70 个编号示例平铺排列是本次重构的攻坚点。决策文档先识别出按 Kernel 组件划分的概念清单其范围覆盖KernelBuilder、Functions、Plugins、AI Services、Hooks、Filters、Templates、AI ServicesChat/Text 生成、Text to/from Image、Audio、Custom、Memory Services、Telemetry、Logging、Dependency Injection、HttpClient、Planners、Authentication、Function Calling、Filtering、RAG、Agents、Flow Orchestrator 等。Option 1 - Concept by Components按组件分概念将概念按 Kernel 组件与特性组织为嵌套目录树。Large每文件夹文件较少完整树形结构节选核心分支Concepts/ ├── Kernel/ │ ├── Builder/ │ ├── Functions/ │ │ ├── Arguments/ │ │ ├── MethodFunctions/ │ │ ├── PromptFunctions/ │ │ ├── Types/ │ │ ├── Results/ │ │ │ ├── Serialization/ │ │ │ ├── Metadata/ │ │ │ └── Strongly typed/ │ │ └── InlineFunctions/ │ ├── Plugins/ │ │ ├── Describe Plugins/ │ │ ├── OpenAI Plugins/ │ │ ├── OpenAPI Plugins/ │ │ │ └── API Manifest/ │ │ ├── gRPC Plugins/ │ │ └── Mutable Plugins/ │ ├── AI Services (Examples using Services thru Kernel Invocation)/ │ │ ├── Chat Completion/ │ │ ├── Text Generation/ │ │ └── Service Selector/ │ ├── Hooks/ │ ├── Filters/ │ │ ├── Function Filtering/ │ │ ├── Template Rendering Filtering/ │ │ └── Function Call Filtering (When available)/ │ └── Templates/ ├── AI Services (Examples using Services directly ...)/ │ ├── ExecutionSettings/ │ ├── Chat Completion/ │ │ ├── LocalModels/ │ │ │ ├── LMStudio/ │ │ │ ├── LocalAI/ │ │ │ ├── Ollama/ │ │ │ └── HuggingFace/ │ │ ├── Gemini/ │ │ ├── OpenAI/ │ │ ├── AzureOpenAI/ │ │ └── HuggingFace/ │ ├── Text Generation/ ...OpenAI / AzureOpenAI / HuggingFace / LocalModels │ ├── Text to Image/OpenAI / AzureOpenAI │ ├── Image to Text/HuggingFace │ ├── Text to Audio/OpenAI │ ├── Audio to Text/OpenAI │ └── Custom/DYI / OpenAI / OpenAI File ├── Memory Services/ │ ├── Search/Semantic Memory / Text Memory / Azure AI Search │ └── Text Embeddings/OpenAI / HuggingFace ├── Telemetry/ ├── Logging/ ├── Dependency Injection/ ├── HttpClient/Resiliency / Usage ├── Planners/Handlebars ├── Authentication/Azure AD ├── Function Calling/Auto / Manual ├── Filtering/Kernel Hooks / Service Selector ├── Templates/ ├── Resilience/ ├── Memory/Semantic Memory / Text Memory Plugin / Search ├── RAG/Inline / Function Calling ├── Agents/Delegation / Charts / Collaboration / Authoring / Tools / Chat Completion Agent——Agent Syntax Examples 在此无编号存放 └── Flow Orchestrator/Compact每文件夹文件较多将上述深层嵌套压平为每特性一层Concepts/ ├── Kernel/Builder / Functions / Plugins / AI Services / Hooks / Filters / Templates ├── AI Services/Chat Completion / Text Generation / Text to Image / Image to Text / Text to Audio / Audio to Text / Custom ├── Memory Services/Search / Text Embeddings ├── Telemetry/ ├── Logging/ ├── Dependency Injection/ ├── HttpClient/Resiliency / Usage ├── Planners/Handlebars ├── Authentication/Azure AD ├── Function Calling/Auto / Manual ├── Filtering/Kernel Hooks / Service Selector ├── Templates/ ├── Resilience/ ├── RAG/ ├── Agents/ └── Flow Orchestrator/优点容易理解组件间关系易于演进到更高级概念清楚知道某个特性的新示例该放哪里。缺点结构过深对开发者导航不友好即使清晰仍显冗长。Option 2 - Concept by Components Flattened Version组件扁平化用单层文件夹 点号命名避免深层嵌套Concepts/ ├── KernelBuilder ├── Kernel.Functions.Arguments ├── Kernel.Functions.MethodFunctions ├── Kernel.Functions.PromptFunctions ├── Kernel.Functions.Results.Serialization ├── Kernel.Functions.Results.Metadata ├── Kernel.Functions.Results.StronglyTyped ├── Kernel.Plugins.DescribePlugins ├── Kernel.Plugins.OpenAIPlugins ├── Kernel.Plugins.OpenAPIPlugins.APIManifest ├── Kernel.Plugins.gRPCPlugins ├── Kernel.Plugins.MutablePlugins ├── Kernel.AIServices.ChatCompletion ├── Kernel.AIServices.TextGeneration ├── Kernel.AIServices.ServiceSelector ├── Kernel.Hooks ├── Kernel.Filters.FunctionFiltering ├── Kernel.Filters.TemplateRenderingFiltering ├── Kernel.Filters.FunctionCallFiltering ├── Kernel.Templates ├── AIServices.ExecutionSettings ├── AIServices.ChatCompletion.Gemini / .OpenAI / .AzureOpenAI / .HuggingFace ├── AIServices.TextGeneration.OpenAI / .AzureOpenAI / .HuggingFace ├── AIServices.TextToImage.OpenAI / .AzureOpenAI ├── AIServices.ImageToText.HuggingFace ├── AIServices.TextToAudio.OpenAI ├── AIServices.AudioToText.OpenAI ├── AIServices.Custom.DIY / .OpenAI.OpenAIFile ├── MemoryServices.Search.SemanticMemory / .TextMemory / .AzureAISearch ├── MemoryServices.TextEmbeddings.OpenAI / .HuggingFace ├── Telemetry / Logging / DependencyInjection ├── HttpClient.Resiliency / HttpClient.Usage ├── Planners.Handlebars ├── Authentication.AzureAD ├── FunctionCalling.AutoFunctionCalling / .ManualFunctionCalling ├── Filtering.KernelHooks / .ServiceSelector ├── Templates / Resilience ├── RAG.Inline / RAG.FunctionCalling ├── Agents.Delegation / .Charts / .Collaboration / .Authoring / .Tools / .ChatCompletionAgent └── FlowOrchestrator同样提供Compact 版Kernel.Functions、Kernel.Plugins、Kernel.AIServices、AIServices.ChatCompletion、AIServices.TextGeneration、MemoryServices.Search、MemoryServices.TextEmbeddings、FunctionCalling、Filtering、RAG、Agents等合并成约 29 个一级目录。优点扁平结构避免深嵌套在 IDE 和 GitHub UI 中更易导航保留组件关系清晰的优点。缺点目录名仍然冗长。Option 3 - Concept by Feature Grouping按特性分组✅ 最终采纳将大而相关的特性归组形成约 20 个高层目录Concepts/ ├── Functions/ ├── Chat Completion/ ├── Text Generation/ ├── Text to Image/ ├── Image to Text/ ├── Text to Audio/ ├── Audio to Text/ ├── Telemetry ├── Logging ├── Dependency Injection ├── Plugins ├── Auto Function Calling ├── Filtering ├── Memory ├── Search ├── Agents ├── Templates ├── RAG ├── Prompts └── LocalModels/优点结构更小、更易导航新示例放哪里依然一目了然。缺点无法直观看出组件间的关系高层结构下每个文件需要承载更多示例多个示例共享同一文件夹找特定示例更难这正是旧KernelSyntaxExamples的主要痛点更难演进为更高级的概念。Option 4 - Concept by Difficulty Level按难度分级按 200-Basic → 500-Expert 分级组织Concepts/ ├── 200-BasicFunctions / Chat Completion / Text Generation / … ├── 300-IntermediateFunctions / Chat Completion / … ├── 400-AdvancedManual Function Calling / … └── 500-ExpertFunctions / Manual Function Calling / …优点新手直接被引导到合适难度示例按复杂度组织。缺点项目没有 basic/intermediate/advanced/expert 的明确定义每个难度层级可能都需要更多示例无法体现组件关系创作者难以判定示例难度且一个示例可能同时适配多个难度层级。六、最终决策[x] Root Structure Decision: Option 2 - Getting Started Root Categorization [x] KernelSyntaxExamples Decomposition: Option 3 - Concept by Feature Grouping即Getting Started提升为根级目录KernelSyntaxExamples按特性分组拆解为Concepts。Agent 示例不再编号全部归入Concepts/Agents。七、落地验证重构结果在当前仓库中的实际形态7.1 .NET 侧dotnet/samples对比 dotnet/samples/README.md 中的类型表ADR-0042 的决策已完整落地且在此基础上演进出更多 Getting Started 变体类型描述GettingStarted上手教程引入关键概念Step1_Create_Kernel.cs至Step9_OpenAPI_Plugins.cs共 9 步GettingStartedWithAgentsAgents 上手教程GettingStartedWithProcessesProcesses 上手教程GettingStartedWithVectorStoresVector Stores 上手教程AgentFrameworkMigrationAgent Framework 迁移对照示例Concepts聚焦示例覆盖全部概念Demos多特性组合演示应用LearnResources对应在线文档的代码片段Concepts目录实际按特性拆分为 20 个一级子目录Agents、AudioToText、Caching、ChatCompletion55 个文件、DependencyInjection、Filtering、FunctionCalling、Functions、ImageToText、KernelBuildingKernel.cs、ConfigureExecutionSettings.cs、CustomAIServiceSelector.cs、Memory、Optimization、Plugins、PromptTemplates、RAG、Search、TextGeneration、TextToAudio、TextToImage——与 Option 3 的Functions / Chat Completion / Text Generation / ... / Agents / Templates特性分组一一对应也吸收了 Option 1 的部分细分如Functions下的 Arguments、MethodFunctions、PromptFunctions、Types、Results。Demos目录验证了旧目录迁移表CreateChatGptPlugin现为 BookingRestaurant 等场景、HomeAutomation、TelemetryWithAppInsights、HuggingFaceImageToText、CodeInterpreterPlugin、ModelContextProtocolClientServer均在 dotnet/samples/Demos/README.md 中列出名称与决策一致。LearnResources下存在MicrosoftLearn子目录正是迁移表中「DocumentationExamples → LearnResources/MicrosoftLearn」的落地。7.2 Python 侧跨语言一致性的验证python/samples/README.md 展示了同样的结构骨架getting_started、getting_started_with_agents、getting_started_with_processes、concepts、demos、learn_resources。其中 python/samples/concepts 同样按特性分组agents96 个 .py 文件、chat_completion、functions、plugins、memory、rag、filtering、prompt_templates、auto_function_calling、local_models、mcp、realtime等——证明「Cross Language」原则并非空谈。八、重构之后贡献者与使用者的实操指引8.1 新增示例该放哪里按 ADR-0042 的类型学做三问判断是完整上手引导→GettingStarted或 Agents / Processes / VectorStores 变体是单个特性的聚焦片段→Concepts/Feature下特性名参考 Option 3 的 20 个分组文件名用Provider_Feature.cs风格如OpenAI_ChatCompletion.cs、HuggingFace_ImageToText.cs是多特性组合的完整应用→Demos/AppName名称去掉Example后缀、直白表达用途如TelemetryWithAppInsights、HuggingFaceImageToText。8.2 运行 Concepts 示例Concepts 项目以 xUnit 测试形式承载示例可用命令行按全限定名过滤运行参见 dotnet/samples/Concepts/README.mddotnet test -l console;verbositydetailed --filter FullyQualifiedNameNameSpace.TestClass.TestMethod针对ChatCompletion/OpenAI_ChatCompletion.cs中的ChatPromptAsync测试dotnet test -l console;verbositydetailed --filter FullyQualifiedNameChatCompletion.OpenAI_ChatCompletion.ChatPromptAsync8.3 配置访问密钥大多数示例需要 OpenAI、Azure OpenAI、Bing 等凭据仓库建议使用 .NET Secret Manager 避免密钥泄漏进仓库cd dotnet/samples/Concepts dotnet user-secrets init dotnet user-secrets set OpenAI:ServiceId gpt-3.5-turbo-instruct dotnet user-secrets set OpenAI:ModelId gpt-3.5-turbo-instruct dotnet user-secrets set OpenAI:ChatModelId gpt-4 dotnet user-secrets set OpenAI:ApiKey ...也可以使用环境变量双下划线__分隔父子属性export OpenAI__ApiKeysk-.... export AzureOpenAI__DeploymentNamegpt-35-turbo-instruct export AzureOpenAI__ChatDeploymentNamegpt-4 export AzureOpenAI__Endpointhttps://contoso.openai.azure.com/ export HuggingFace__ApiKey.... export Bing__ApiKey....或在Concepts.csproj旁创建被 git 忽略的appsettings.Development.json配置文件{ OpenAI: { ServiceId: gpt-3.5-turbo-instruct, ModelId: gpt-3.5-turbo-instruct, ChatModelId: gpt-4, ApiKey: sk-.... }, AzureOpenAI: { ServiceId: azure-gpt-35-turbo-instruct, DeploymentName: gpt-35-turbo-instruct, ChatDeploymentName: gpt-4, Endpoint: https://contoso.openai.azure.com/, ApiKey: .... } }九、总结ADR-0042 是一次典型的「以搜索体验为中心的工程治理」先用明确的类型学划分样本身份再用「Getting Started 根级 特性分组」的组合决策消除编号噪音与语义模糊的命名最后以跨语言一致的结构保证 .NET 与 Python 的贡献者遵循同一套心智模型。对照当前仓库如 dotnet/samples、python/samples可以看到该决策不仅被完整执行还在其骨架上自然生长出 Processes、VectorStores、Agent Framework Migration 等新的上手教程变体——这正是优秀 ADR 的价值决策记录成为项目长期演进中可追溯、可扩展的结构契约。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Semantic Kernel 示例代码仓库重构方案解析：从 ADR-0042 到 `samples` 目录的落地实践
Semantic Kernel 示例代码仓库重构方案解析从 ADR-0042 到samples目录的落地实践【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本篇技术指南以 Semantic Kernel 仓库中的架构决策记录 docs/decisions/0042-samples-restructure.mdADR-00422024-04-18 通过为骨架系统梳理该仓库如何将杂乱无章的示例代码重构为「按类型分层、按特性分组、跨语言一致」的样本结构。你将掌握五种示例类型的划分标准、根目录结构三种候选方案的取舍逻辑、KernelSyntaxExamples四种分解策略的对比以及最终决策在 .NET 与 Python 仓库中的实际落地形态从而能够在向仓库贡献新示例时快速判断“该放哪个目录、叫什么名字、遵循什么约定”。一、重构背景旧结构为什么难用ADR-0042 开篇即点出了旧示例结构的四个核心痛点信息量低、难以被发现示例的存放方式缺乏可预测性使用者无法凭直觉找到目标示例编号失去意义KernelSyntaxExamples中超过 70 个带编号的示例平铺并列数字编号既不表示学习进度也无法传达示例内容命名无法传递意图项目名称无法让人一眼看出“这到底是什么”冗余后缀文件夹和解决方案带有Examples后缀而samples目录下的一切本质上都是示例后缀纯属多余。二、示例类型学五种样本的明确定义决策文档首先建立了一套统一的“示例类型学”这是后续所有目录决策的基础类型描述GettingStarted单一的分步上手教程step-by-step tutorial to get startedConcepts按特性组织的聚焦代码片段concept by feature specific code snippetsLearnResources与在线文档Microsoft Learn、DevBlogs 等对应的代码片段Tutorials更深入的分步教程Demos演示一个或多个特性组合的完整应用程序这套分类同时成为跨语言一致性的基准所有受支持的 SK 语言版本.NET、Python 等都遵循相近的样本结构。三、决策驱动原则与旧目录迁移策略3.1 四条决策原则原则含义Easy to Search易于搜索结构组织良好便于找到不同类型的样本Lean namings精简命名文件夹、解决方案和示例名称尽可能清晰、简短Sends a Clear Message传达清晰信息避免使用 Semantic Kernel 特有的术语或行话Cross Language跨语言所有受支持的 SK 语言采用相似的样本结构3.2 旧目录的具体迁移方案原文件夹迁移方案KernelSyntaxExamples/Getting_Started移入GettingStartedKernelSyntaxExamples/Examples??_*拆解到Concepts下的多个概念子文件夹AgentSyntaxExamples拆解到Concepts下的Agents子文件夹DocumentationExamples移入LearnResources子文件夹并重命名为MicrosoftLearnCreateChatGptPlugin移入Demo子文件夹HomeAutomation移入Demo子文件夹TelemetryExample移入Demo子文件夹并重命名为TelemetryWithAppInsightsHuggingFaceImageTextExample移入Demo子文件夹并重命名为HuggingFaceImageToText四、根目录结构三个候选方案对比Option 1 - Ultra Narrow Root Categorization超窄根部分类将samples根目录压缩到极简的少数几个分类samples/ ├── Tutorials/ │ └── Getting Started/ ├── Concepts/ │ ├── Kernel Syntax** │ └── Agents Syntax** ├── Resources/ └── Demos/优点结构更简单、更少冗长“少即是多”新手能看到并排的其他教程按需选择不强制从 Getting Started 开始。缺点需要额外认知负担才能明白 “Getting Started” 属于 tutorial 的一种。Option 2 - Getting Started Root CategorizationGetting Started 根级分类✅ 最终采纳与 Option 1 相比将Getting Started提升到samples根目录的独立一级samples/ ├── Getting Started/ ├── Tutorials/ ├── Concepts/ │ ├── Kernel Syntax Decomposition** │ └── Agents Syntax Decomposition** ├── Resources/ └── Demos/优点Getting Started 是客户最先看到的内容。缺点若 Getting Started 示例对该客户不适用需要返回其他文件夹寻找内容。Option 3 - Conservative Use Cases Based Root Categorization保守 用例分类保留 Syntax Examples 项目为根级选项同时新增 Use Cases、Modalities、Kernel Content 等文件夹samples/ |── QuickStart/ |── Tutorials/ ├── KernelSyntaxExamples/ ├── AgentSyntaxExamples/ ├── UseCases/ OR Demos/ ├── KernelContent/ OR Modalities/ ├── Documentation/ OR Resources/优点更保守保留KernelSyntaxExamples和AgentSyntaxExamples根级目录不会破坏已有的互联网链接。缺点更冗长的结构增加寻找样本的摩擦KernelContent/Modalities是内部术语客户难以理解Documentation容易被误认为纯文档目录Use Cases暗示真实业务场景而实际只是 SK 特性的简单演示。五、KernelSyntaxExamples分解四个候选方案KernelSyntaxExamples内含 70 个编号示例平铺排列是本次重构的攻坚点。决策文档先识别出按 Kernel 组件划分的概念清单其范围覆盖KernelBuilder、Functions、Plugins、AI Services、Hooks、Filters、Templates、AI ServicesChat/Text 生成、Text to/from Image、Audio、Custom、Memory Services、Telemetry、Logging、Dependency Injection、HttpClient、Planners、Authentication、Function Calling、Filtering、RAG、Agents、Flow Orchestrator 等。Option 1 - Concept by Components按组件分概念将概念按 Kernel 组件与特性组织为嵌套目录树。Large每文件夹文件较少完整树形结构节选核心分支Concepts/ ├── Kernel/ │ ├── Builder/ │ ├── Functions/ │ │ ├── Arguments/ │ │ ├── MethodFunctions/ │ │ ├── PromptFunctions/ │ │ ├── Types/ │ │ ├── Results/ │ │ │ ├── Serialization/ │ │ │ ├── Metadata/ │ │ │ └── Strongly typed/ │ │ └── InlineFunctions/ │ ├── Plugins/ │ │ ├── Describe Plugins/ │ │ ├── OpenAI Plugins/ │ │ ├── OpenAPI Plugins/ │ │ │ └── API Manifest/ │ │ ├── gRPC Plugins/ │ │ └── Mutable Plugins/ │ ├── AI Services (Examples using Services thru Kernel Invocation)/ │ │ ├── Chat Completion/ │ │ ├── Text Generation/ │ │ └── Service Selector/ │ ├── Hooks/ │ ├── Filters/ │ │ ├── Function Filtering/ │ │ ├── Template Rendering Filtering/ │ │ └── Function Call Filtering (When available)/ │ └── Templates/ ├── AI Services (Examples using Services directly ...)/ │ ├── ExecutionSettings/ │ ├── Chat Completion/ │ │ ├── LocalModels/ │ │ │ ├── LMStudio/ │ │ │ ├── LocalAI/ │ │ │ ├── Ollama/ │ │ │ └── HuggingFace/ │ │ ├── Gemini/ │ │ ├── OpenAI/ │ │ ├── AzureOpenAI/ │ │ └── HuggingFace/ │ ├── Text Generation/ ...OpenAI / AzureOpenAI / HuggingFace / LocalModels │ ├── Text to Image/OpenAI / AzureOpenAI │ ├── Image to Text/HuggingFace │ ├── Text to Audio/OpenAI │ ├── Audio to Text/OpenAI │ └── Custom/DYI / OpenAI / OpenAI File ├── Memory Services/ │ ├── Search/Semantic Memory / Text Memory / Azure AI Search │ └── Text Embeddings/OpenAI / HuggingFace ├── Telemetry/ ├── Logging/ ├── Dependency Injection/ ├── HttpClient/Resiliency / Usage ├── Planners/Handlebars ├── Authentication/Azure AD ├── Function Calling/Auto / Manual ├── Filtering/Kernel Hooks / Service Selector ├── Templates/ ├── Resilience/ ├── Memory/Semantic Memory / Text Memory Plugin / Search ├── RAG/Inline / Function Calling ├── Agents/Delegation / Charts / Collaboration / Authoring / Tools / Chat Completion Agent——Agent Syntax Examples 在此无编号存放 └── Flow Orchestrator/Compact每文件夹文件较多将上述深层嵌套压平为每特性一层Concepts/ ├── Kernel/Builder / Functions / Plugins / AI Services / Hooks / Filters / Templates ├── AI Services/Chat Completion / Text Generation / Text to Image / Image to Text / Text to Audio / Audio to Text / Custom ├── Memory Services/Search / Text Embeddings ├── Telemetry/ ├── Logging/ ├── Dependency Injection/ ├── HttpClient/Resiliency / Usage ├── Planners/Handlebars ├── Authentication/Azure AD ├── Function Calling/Auto / Manual ├── Filtering/Kernel Hooks / Service Selector ├── Templates/ ├── Resilience/ ├── RAG/ ├── Agents/ └── Flow Orchestrator/优点容易理解组件间关系易于演进到更高级概念清楚知道某个特性的新示例该放哪里。缺点结构过深对开发者导航不友好即使清晰仍显冗长。Option 2 - Concept by Components Flattened Version组件扁平化用单层文件夹 点号命名避免深层嵌套Concepts/ ├── KernelBuilder ├── Kernel.Functions.Arguments ├── Kernel.Functions.MethodFunctions ├── Kernel.Functions.PromptFunctions ├── Kernel.Functions.Results.Serialization ├── Kernel.Functions.Results.Metadata ├── Kernel.Functions.Results.StronglyTyped ├── Kernel.Plugins.DescribePlugins ├── Kernel.Plugins.OpenAIPlugins ├── Kernel.Plugins.OpenAPIPlugins.APIManifest ├── Kernel.Plugins.gRPCPlugins ├── Kernel.Plugins.MutablePlugins ├── Kernel.AIServices.ChatCompletion ├── Kernel.AIServices.TextGeneration ├── Kernel.AIServices.ServiceSelector ├── Kernel.Hooks ├── Kernel.Filters.FunctionFiltering ├── Kernel.Filters.TemplateRenderingFiltering ├── Kernel.Filters.FunctionCallFiltering ├── Kernel.Templates ├── AIServices.ExecutionSettings ├── AIServices.ChatCompletion.Gemini / .OpenAI / .AzureOpenAI / .HuggingFace ├── AIServices.TextGeneration.OpenAI / .AzureOpenAI / .HuggingFace ├── AIServices.TextToImage.OpenAI / .AzureOpenAI ├── AIServices.ImageToText.HuggingFace ├── AIServices.TextToAudio.OpenAI ├── AIServices.AudioToText.OpenAI ├── AIServices.Custom.DIY / .OpenAI.OpenAIFile ├── MemoryServices.Search.SemanticMemory / .TextMemory / .AzureAISearch ├── MemoryServices.TextEmbeddings.OpenAI / .HuggingFace ├── Telemetry / Logging / DependencyInjection ├── HttpClient.Resiliency / HttpClient.Usage ├── Planners.Handlebars ├── Authentication.AzureAD ├── FunctionCalling.AutoFunctionCalling / .ManualFunctionCalling ├── Filtering.KernelHooks / .ServiceSelector ├── Templates / Resilience ├── RAG.Inline / RAG.FunctionCalling ├── Agents.Delegation / .Charts / .Collaboration / .Authoring / .Tools / .ChatCompletionAgent └── FlowOrchestrator同样提供Compact 版Kernel.Functions、Kernel.Plugins、Kernel.AIServices、AIServices.ChatCompletion、AIServices.TextGeneration、MemoryServices.Search、MemoryServices.TextEmbeddings、FunctionCalling、Filtering、RAG、Agents等合并成约 29 个一级目录。优点扁平结构避免深嵌套在 IDE 和 GitHub UI 中更易导航保留组件关系清晰的优点。缺点目录名仍然冗长。Option 3 - Concept by Feature Grouping按特性分组✅ 最终采纳将大而相关的特性归组形成约 20 个高层目录Concepts/ ├── Functions/ ├── Chat Completion/ ├── Text Generation/ ├── Text to Image/ ├── Image to Text/ ├── Text to Audio/ ├── Audio to Text/ ├── Telemetry ├── Logging ├── Dependency Injection ├── Plugins ├── Auto Function Calling ├── Filtering ├── Memory ├── Search ├── Agents ├── Templates ├── RAG ├── Prompts └── LocalModels/优点结构更小、更易导航新示例放哪里依然一目了然。缺点无法直观看出组件间的关系高层结构下每个文件需要承载更多示例多个示例共享同一文件夹找特定示例更难这正是旧KernelSyntaxExamples的主要痛点更难演进为更高级的概念。Option 4 - Concept by Difficulty Level按难度分级按 200-Basic → 500-Expert 分级组织Concepts/ ├── 200-BasicFunctions / Chat Completion / Text Generation / … ├── 300-IntermediateFunctions / Chat Completion / … ├── 400-AdvancedManual Function Calling / … └── 500-ExpertFunctions / Manual Function Calling / …优点新手直接被引导到合适难度示例按复杂度组织。缺点项目没有 basic/intermediate/advanced/expert 的明确定义每个难度层级可能都需要更多示例无法体现组件关系创作者难以判定示例难度且一个示例可能同时适配多个难度层级。六、最终决策[x] Root Structure Decision: Option 2 - Getting Started Root Categorization [x] KernelSyntaxExamples Decomposition: Option 3 - Concept by Feature Grouping即Getting Started提升为根级目录KernelSyntaxExamples按特性分组拆解为Concepts。Agent 示例不再编号全部归入Concepts/Agents。七、落地验证重构结果在当前仓库中的实际形态7.1 .NET 侧dotnet/samples对比 dotnet/samples/README.md 中的类型表ADR-0042 的决策已完整落地且在此基础上演进出更多 Getting Started 变体类型描述GettingStarted上手教程引入关键概念Step1_Create_Kernel.cs至Step9_OpenAPI_Plugins.cs共 9 步GettingStartedWithAgentsAgents 上手教程GettingStartedWithProcessesProcesses 上手教程GettingStartedWithVectorStoresVector Stores 上手教程AgentFrameworkMigrationAgent Framework 迁移对照示例Concepts聚焦示例覆盖全部概念Demos多特性组合演示应用LearnResources对应在线文档的代码片段Concepts目录实际按特性拆分为 20 个一级子目录Agents、AudioToText、Caching、ChatCompletion55 个文件、DependencyInjection、Filtering、FunctionCalling、Functions、ImageToText、KernelBuildingKernel.cs、ConfigureExecutionSettings.cs、CustomAIServiceSelector.cs、Memory、Optimization、Plugins、PromptTemplates、RAG、Search、TextGeneration、TextToAudio、TextToImage——与 Option 3 的Functions / Chat Completion / Text Generation / ... / Agents / Templates特性分组一一对应也吸收了 Option 1 的部分细分如Functions下的 Arguments、MethodFunctions、PromptFunctions、Types、Results。Demos目录验证了旧目录迁移表CreateChatGptPlugin现为 BookingRestaurant 等场景、HomeAutomation、TelemetryWithAppInsights、HuggingFaceImageToText、CodeInterpreterPlugin、ModelContextProtocolClientServer均在 dotnet/samples/Demos/README.md 中列出名称与决策一致。LearnResources下存在MicrosoftLearn子目录正是迁移表中「DocumentationExamples → LearnResources/MicrosoftLearn」的落地。7.2 Python 侧跨语言一致性的验证python/samples/README.md 展示了同样的结构骨架getting_started、getting_started_with_agents、getting_started_with_processes、concepts、demos、learn_resources。其中 python/samples/concepts 同样按特性分组agents96 个 .py 文件、chat_completion、functions、plugins、memory、rag、filtering、prompt_templates、auto_function_calling、local_models、mcp、realtime等——证明「Cross Language」原则并非空谈。八、重构之后贡献者与使用者的实操指引8.1 新增示例该放哪里按 ADR-0042 的类型学做三问判断是完整上手引导→GettingStarted或 Agents / Processes / VectorStores 变体是单个特性的聚焦片段→Concepts/Feature下特性名参考 Option 3 的 20 个分组文件名用Provider_Feature.cs风格如OpenAI_ChatCompletion.cs、HuggingFace_ImageToText.cs是多特性组合的完整应用→Demos/AppName名称去掉Example后缀、直白表达用途如TelemetryWithAppInsights、HuggingFaceImageToText。8.2 运行 Concepts 示例Concepts 项目以 xUnit 测试形式承载示例可用命令行按全限定名过滤运行参见 dotnet/samples/Concepts/README.mddotnet test -l console;verbositydetailed --filter FullyQualifiedNameNameSpace.TestClass.TestMethod针对ChatCompletion/OpenAI_ChatCompletion.cs中的ChatPromptAsync测试dotnet test -l console;verbositydetailed --filter FullyQualifiedNameChatCompletion.OpenAI_ChatCompletion.ChatPromptAsync8.3 配置访问密钥大多数示例需要 OpenAI、Azure OpenAI、Bing 等凭据仓库建议使用 .NET Secret Manager 避免密钥泄漏进仓库cd dotnet/samples/Concepts dotnet user-secrets init dotnet user-secrets set OpenAI:ServiceId gpt-3.5-turbo-instruct dotnet user-secrets set OpenAI:ModelId gpt-3.5-turbo-instruct dotnet user-secrets set OpenAI:ChatModelId gpt-4 dotnet user-secrets set OpenAI:ApiKey ...也可以使用环境变量双下划线__分隔父子属性export OpenAI__ApiKeysk-.... export AzureOpenAI__DeploymentNamegpt-35-turbo-instruct export AzureOpenAI__ChatDeploymentNamegpt-4 export AzureOpenAI__Endpointhttps://contoso.openai.azure.com/ export HuggingFace__ApiKey.... export Bing__ApiKey....或在Concepts.csproj旁创建被 git 忽略的appsettings.Development.json配置文件{ OpenAI: { ServiceId: gpt-3.5-turbo-instruct, ModelId: gpt-3.5-turbo-instruct, ChatModelId: gpt-4, ApiKey: sk-.... }, AzureOpenAI: { ServiceId: azure-gpt-35-turbo-instruct, DeploymentName: gpt-35-turbo-instruct, ChatDeploymentName: gpt-4, Endpoint: https://contoso.openai.azure.com/, ApiKey: .... } }九、总结ADR-0042 是一次典型的「以搜索体验为中心的工程治理」先用明确的类型学划分样本身份再用「Getting Started 根级 特性分组」的组合决策消除编号噪音与语义模糊的命名最后以跨语言一致的结构保证 .NET 与 Python 的贡献者遵循同一套心智模型。对照当前仓库如 dotnet/samples、python/samples可以看到该决策不仅被完整执行还在其骨架上自然生长出 Processes、VectorStores、Agent Framework Migration 等新的上手教程变体——这正是优秀 ADR 的价值决策记录成为项目长期演进中可追溯、可扩展的结构契约。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
 的排序)
