Semantic Kernel .NET 架构学习指南 🚀

嗨,欢迎来到 Semantic Kernel 的世界!我是你的技术教练,接下来我会带你深入这个由微软打造的 AI 编排框架。别担心,我们会从零开始,一步步揭开它的神秘面纱。准备好了吗?让我们开始这段激动人心的旅程吧! 😊

第一部分:项目架构深度解析 🔍

1. 项目架构概览

用通俗的类比理解 Semantic Kernel 💡

想象一下,你在组织一场大型音乐会。Semantic Kernel 就像是这场音乐会的总指挥和协调中心:

Kernel(内核) 是你的指挥台 🎭 - 协调所有资源和服务
Plugins(插件) 是你的乐手们 🎸 - 每个人都有专长(搜索、计算、数据处理等)
AI Connectors(AI连接器) 是你的音响设备 🔊 - 连接各种AI服务(OpenAI、Azure OpenAI、Google Gemini等)
Functions(函数) 是你的乐谱 🎼 - 定义了具体要执行的动作
Agents(代理) 是你的舞台剧演员 🎭 - 可以有状态、记忆和复杂行为的智能实体

整个框架的设计哲学就是:让开发者能够像编排一场演出一样,优雅地组合AI能力、业务逻辑和外部服务,创造出强大的AI应用。

核心设计特征 ⭐

Semantic Kernel 采用了插件化的微内核架构,具有以下突出特点:

高度可扩展的连接器生态 🔌
- 支持 10+ 种主流 AI 服务商(OpenAI、Azure OpenAI、Google、Amazon Bedrock、Ollama、Mistral AI等)
- 统一的抽象接口,切换AI提供商只需修改配置
- 内置向量存储支持(15+ 数据库: Qdrant、Pinecone、Redis、PostgreSQL、MongoDB等)
函数式编程范式 🎯
- 将业务逻辑封装为函数(Function)
- 支持原生C#方法函数和Prompt模板函数
- 函数可以被AI自动调用(Function Calling)
依赖注入友好 💉
- 深度集成 Microsoft.Extensions.DependencyInjection
- 支持标准ASP.NET Core服务生命周期管理
- 便于单元测试和模块化开发
多层过滤器机制 🛡️
- Prompt渲染过滤器:在提示词发送前拦截和修改
- 函数调用过滤器:控制函数执行流程
- 自动函数调用过滤器:拦截AI的function calling行为
- 可实现日志、性能监控、权限控制、内容安全等横切关注点
实验性Agent框架 🤖
- 支持OpenAI Assistants API
- 多Agent协同编排
- 内置对话管理和状态保持

特性	Semantic Kernel	LangChain	AutoGen
语言支持	C#、Python、Java	Python、JavaScript	Python
设计理念	企业级、类型安全	快速原型、链式调用	多Agent对话
依赖注入	✅ 原生支持	⚠️ 有限支持	❌ 不支持
函数调用	✅ 深度集成	✅ 支持	✅ 支持
向量存储	✅ 15+ 连接器	✅ 丰富	⚠️ 基础
企业级特性	✅ 完善	⚠️ 社区驱动	⚠️ 研究导向
适用场景	.NET生态、企业应用	Python快速开发	Agent研究、自动化工作流

技术栈分析 🔧

核心框架层 (SemanticKernel.Abstractions + SemanticKernel.Core)

Target Frameworks: net8.0, netstandard2.0 // 兼容性极佳 核心依赖: - Microsoft.Extensions.DependencyInjection (8.0+) // DI容器 - Microsoft.Extensions.AI (9.9.0) // 微软AI抽象层 - System.Numerics.Tensors (9.0+) // 向量运算

AI连接器层 (15+ Connectors)

OpenAI生态: ├─ Connectors.OpenAI → OpenAI官方API ├─ Connectors.AzureOpenAI → Azure OpenAI服务 └─ Connectors.AzureAIInference → Azure AI推理端点 开源/本地模型: ├─ Connectors.Ollama → 本地LLM运行 ├─ Connectors.Onnx → ONNX Runtime推理 └─ Connectors.HuggingFace → HuggingFace模型 云服务商: ├─ Connectors.Amazon → AWS Bedrock ├─ Connectors.Google → Google Gemini └─ Connectors.MistralAI → Mistral AI

数据持久化层 (VectorData)

向量数据库: ├─ AzureAISearch, Qdrant, Pinecone, Milvus, Weaviate, Chroma ├─ Redis, PostgreSQL(PgVector), MongoDB └─ SqlServer, Sqlite, CosmosDB 特点: ✅ 统一的IVectorStore接口 ✅ 支持向量相似度搜索 ✅ 支持混合搜索(向量+文本)

函数扩展层 (Functions)

- Functions.OpenApi → REST API转函数 - Functions.Grpc → gRPC服务转函数 - Functions.Yaml → YAML定义函数 - Functions.Prompty → Prompty格式(Azure AI Studio)

插件生态 (Plugins)

- Plugins.Core → 内置核心插件 - Plugins.Web → 网页搜索、爬虫 - Plugins.MsGraph → Microsoft 365集成 - Plugins.Document → 文档处理

架构流程描述 🌊

让我们跟随一个典型的AI问答请求,看看数据是如何在系统中流转的:

┌─────────────────────────────────────────────────────────────────┐ │ 1️⃣ 用户输入 "帮我查询今天的天气并生成一份天气报告" │ └────────────────┬────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ 2️⃣ Kernel.InvokePromptAsync(prompt) │ │ ↓ 触发 IPromptRenderFilter (Prompt渲染过滤器) │ │ ↓ 模板引擎解析变量、条件逻辑 │ │ ↓ 渲染成最终Prompt │ └────────────────┬────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ 3️⃣ 路由到 IChatCompletionService (如OpenAI) │ │ ↓ HttpClient发送请求到 https://api.openai.com │ │ ↓ 携带已注册的Functions元数据(function calling schema) │ └────────────────┬────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ 4️⃣ AI模型分析后决定调用 GetWeatherPlugin.GetCurrentWeather() │ │ ← 返回 FunctionCallContent: {name: "GetWeather", args: {...}}│ └────────────────┬────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ 5️⃣ 触发 IFunctionInvocationFilter (函数调用过滤器) │ │ ↓ 可在此进行权限检查、参数验证、日志记录 │ │ ↓ 实际调用 Plugin 中的 C# 方法 │ │ ↓ 方法内部调用天气API,获取数据 │ │ ← 返回 FunctionResult: {result: "北京,晴,25°C"} │ └────────────────┬────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ 6️⃣ 将函数执行结果重新提交给AI │ │ → AI基于实际数据生成最终回答 │ │ ← 返回 "今天北京天气晴朗,气温25°C,适宜外出活动..." │ └────────────────┬────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ 7️⃣ 返回给用户 (支持流式输出 StreamingChatMessageContent) │ └─────────────────────────────────────────────────────────────────┘

关键交互点:

Kernel 是整个流程的协调者,管理所有服务的生命周期
Filters 提供了多个拦截点,实现横切关注点
Function Calling 是核心能力,让AI能主动调用工具
Plugin 是能力的封装单元,可热插拔

2. 目录结构与核心流程 📁

目录组织逻辑

项目采用按功能模块划分的组织方式,清晰易懂:

dotnet/ ├─ src/ # 核心源代码 │ ├─ SemanticKernel.Abstractions/ ⭐ 抽象接口层 │ │ ├─ AI/ # AI服务接口 │ │ │ ├─ ChatCompletion/ # 对话完成 │ │ │ ├─ Embeddings/ # 文本嵌入 │ │ │ ├─ TextToImage/ # 文本生成图像 │ │ │ └─ AudioToText/ # 语音转文本 │ │ ├─ Functions/ # 函数系统 │ │ │ ├─ KernelFunction.cs # 函数抽象 │ │ │ ├─ KernelPlugin.cs # 插件抽象 │ │ │ └─ KernelArguments.cs # 参数传递 │ │ ├─ Kernel.cs # 🔥 核心Kernel类 │ │ ├─ Events/ # 事件系统 │ │ └─ Filters/ # 过滤器接口 │ │ │ ├─ SemanticKernel.Core/ ⭐ 核心实现层 │ │ ├─ Functions/ # 函数工厂 │ │ │ ├─ KernelFunctionFromMethod.cs │ │ │ └─ KernelFunctionFromPrompt.cs │ │ ├─ PromptTemplate/ # 模板引擎 │ │ ├─ TemplateEngine/ # Liquid模板 │ │ └─ Memory/ # 记忆系统 │ │ │ ├─ Connectors/ # 🔌 AI服务连接器 │ │ ├─ Connectors.OpenAI/ │ │ ├─ Connectors.AzureOpenAI/ │ │ ├─ Connectors.Google/ │ │ ├─ Connectors.Ollama/ │ │ └─ ... (15+ connectors) │ │ │ ├─ VectorData/ # 💾 向量数据层 │ │ ├─ VectorData.Abstractions/ # 统一接口 │ │ ├─ Qdrant/ # Qdrant实现 │ │ ├─ Pinecone/ # Pinecone实现 │ │ ├─ Redis/ # Redis实现 │ │ └─ ... (15+ vector stores) │ │ │ ├─ Agents/ # 🤖 Agent框架 │ │ ├─ Abstractions/ # Agent接口 │ │ ├─ Core/ # 核心Agent实现 │ │ ├─ OpenAI/ # OpenAI Assistants │ │ └─ Orchestration/ # Agent编排 │ │ │ ├─ Plugins/ # 🧩 插件库 │ │ ├─ Plugins.Core/ # 核心插件 │ │ ├─ Plugins.Web/ # 网页插件 │ │ └─ Plugins.MsGraph/ # Microsoft 365 │ │ │ ├─ Functions/ # 🔧 函数扩展 │ │ ├─ Functions.OpenApi/ # OpenAPI → Function │ │ ├─ Functions.Grpc/ # gRPC → Function │ │ └─ Functions.Yaml/ # YAML定义 │ │ │ └─ Experimental/ # 🧪 实验性功能 │ ├─ Process.Abstractions/ # 流程框架抽象 │ └─ Orchestration.Flow/ # 流程编排 │ ├─ samples/ # 📚 示例代码 │ ├─ GettingStarted/ # ⭐ 入门教程(从这里开始!) │ ├─ Concepts/ # 概念示例(按功能分类) │ ├─ Demos/ # 综合演示项目 │ │ ├─ VectorStoreRAG/ # RAG实现 │ │ ├─ AgentFrameworkWithAspire/ # Agent + Aspire │ │ └─ ProcessWithDapr/ # 分布式Process │ └─ GettingStartedWithAgents/ # Agent专题教程 │ ├─ test/ # 🧪 测试 │ └─ VectorData/ # 向量存储一致性测试 │ └─ notebooks/ # 📒 Jupyter笔记本 └─ 00-getting-started.ipynb # 交互式入门

关键文件定位 🎯

第一个应阅读的文件 (构建心智模型):

src/SemanticKernel.Abstractions/Kernel.cs (核心入口)

// 这是整个框架的"心脏",理解它就理解了60%的设计 public sealed class Kernel {  public IServiceProvider Services {  get; } // DI容器 public KernelPluginCollection Plugins {  get; } // 插件集合 public Task<FunctionResult> InvokeAsync(...); // 调用入口 }

src/SemanticKernel.Abstractions/Functions/KernelFunction.cs

// 理解"函数"是什么,它如何被调用 public abstract class KernelFunction {  public KernelFunctionMetadata Metadata {  get; } public Task<FunctionResult> InvokeAsync(...); }

samples/GettingStarted/Step1_Create_Kernel.cs (最小示例)

// 5分钟就能运行的第一个程序! Kernel kernel = Kernel.CreateBuilder() .AddOpenAIChatCompletion("gpt-4", apiKey) .Build(); Console.WriteLine(await kernel.InvokePromptAsync("讲个笑话"));

核心业务逻辑所在 (深入理解):

函数调用链路: SemanticKernel.Core/Functions/KernelFunctionFromMethod.cs
Prompt渲染: SemanticKernel.Core/PromptTemplate/KernelPromptTemplate.cs
OpenAI集成: Connectors/Connectors.OpenAI/
向量搜索: VectorData/VectorData.Abstractions/VectorStoreRecordCollection.cs

模块依赖关系 📊

graph TB A[应用层: samples/] -->|依赖| B[API层: SemanticKernel.Core] B -->|依赖| C[抽象层: SemanticKernel.Abstractions] C -->|依赖| D[向量抽象: VectorData.Abstractions] B -->|实现| E[Connectors.*] E -->|依赖| C B -->|实现| F[Plugins.*] F -->|依赖| C B -->|实现| G[Functions.*] G -->|依赖| C H[Agents.*] -->|依赖| C H -->|依赖| B I[VectorData实现] -->|依赖| D style C fill:#ff6b6b style B fill:#4ecdc4 style A fill:#95e1d3

依赖流向特点:
✅ 单向依赖: 所有模块都依赖Abstractions,不存在循环依赖
✅ 接口隔离: 连接器之间完全独立,互不影响
✅ 可替换性: 实现层可以随时替换而不影响上层

典型业务流程:智能客服机器人 🤖

场景:用户询问订单状态,AI自动查询数据库并回答

sequenceDiagram participant U as 用户 participant K as Kernel participant A as OpenAIChatCompletion participant P as OrderPlugin participant DB as 数据库 U->>K: "我的订单#12345现在什么状态?" K->>K: PromptRenderFilter拦截 K->>A: 发送Prompt + 注册的Functions A->>A: AI理解意图,决定调用GetOrderStatus A-->>K: 返回FunctionCallContent K->>K: FunctionInvocationFilter拦截 K->>P: 调用 GetOrderStatus("12345") P->>DB: SQL查询 DB-->>P: 返回{status: "已发货", eta: "明天"} P-->>K: FunctionResult K->>A: 提交函数执行结果 A->>A: 生成自然语言回答 A-->>K: "您的订单已发货,预计明天送达" K-->>U: 返回结果

实现文件索引:

入口: samples/Concepts/FunctionCalling/FunctionCalling.cs
Plugin定义: 自定义类,使用[KernelFunction]特性标记
Kernel构建: KernelBuilder.AddOpenAIChatCompletion(...).AddPlugin<OrderPlugin>().Build()
过滤器注入: builder.Services.AddSingleton<IFunctionInvocationFilter, LoggingFilter>()

3. 代码结构观察 🔍

代码组织模式

Semantic Kernel 遵循了现代C#最佳实践,代码质量非常高:

✅ 清晰的领域模型

// 核心概念都有明确的类型表达 Kernel → 编排中心 KernelFunction → 可执行的函数 KernelPlugin → 函数的集合 KernelArguments → 参数传递容器 FunctionResult → 执行结果

✅ 接口与实现分离

IChatCompletionService (接口) ↑ 实现 ├─ OpenAIChatCompletionService ├─ AzureOpenAIChatCompletionService └─ GoogleGeminiChatCompletionService

切换AI提供商只需修改DI注册,代码无需改动!

✅ 异步优先设计

// 所有IO操作都是异步的,避免线程阻塞 Task<FunctionResult> InvokeAsync(...) IAsyncEnumerable<StreamingChatMessageContent> GetStreamingChatMessageContentsAsync(...)

✅ 泛型和约束

// 类型安全的服务获取 T GetRequiredService<T>() where T : IAIService IReadOnlyKernelPluginCollection Plugins {  get; }

设计模式识别 🎨

1. 建造者模式 (Builder Pattern) - 随处可见

var kernel = Kernel.CreateBuilder() .AddOpenAIChatCompletion(modelId, apiKey) .AddAzureOpenAIEmbedding(deploymentName, endpoint, apiKey) .Plugins.AddFromType<TimePlugin>() .Build();

2. 策略模式 (Strategy Pattern) - AI服务替换

// 通过接口IChatCompletionService抽象策略 // 运行时可动态选择不同实现 kernel.GetRequiredService<IChatCompletionService>();

3. 装饰器模式 (Decorator Pattern) - 过滤器链

// 每个Filter都可以包装原始行为 public class LoggingFilter : IFunctionInvocationFilter {  public async Task OnFunctionInvocationAsync( FunctionInvocationContext context, Func<FunctionInvocationContext, Task> next) {  _logger.LogInformation("调用前"); await next(context); // 调用下一个Filter或实际函数 _logger.LogInformation("调用后"); } }

4. 工厂模式 (Factory Pattern) - 函数创建

KernelFunctionFactory.CreateFromMethod(...) KernelFunctionFactory.CreateFromPrompt(...) KernelPluginFactory.CreateFromType<T>()

5. 依赖注入 (Dependency Injection) - 核心基础设施

// 所有服务都通过DI容器管理 public class MyPlugin {  public MyPlugin(ILogger<MyPlugin> logger, IHttpClientFactory factory) {  // 自动注入依赖 } }

6. 观察者模式 (Observer Pattern) - 事件系统

kernel.FunctionInvoking += (sender, e) => {  /* 订阅事件 */ }; kernel.FunctionInvoked += (sender, e) => {  /* 订阅事件 */ };

代码质量观察 ⭐

✅ 优秀之处:

完善的XML文档注释

/// <summary> /// Invokes the specified function with the specified arguments. /// </summary> /// <param name="function">The function to invoke.</param> /// <param name="arguments">The arguments to pass to the function.</param> /// <param name="cancellationToken">Cancellation token.</param> /// <returns>The result of the function invocation.</returns>

Nullable引用类型启用

#nullable enable public KernelFunction? GetFunction(string? pluginName, string functionName)

编译时就能发现潜在的空引用问题!

Source Generator应用

[JsonSerializable(typeof(ChatMessageContent))] internal sealed partial class AbstractionsJsonContext : JsonSerializerContext

AOT友好,性能优化

单元测试覆盖
- SemanticKernel.UnitTests/ 包含大量测试
- 使用 xUnit + Moq + FluentAssertions
- 测试覆盖率 > 80%
代码风格一致性
- 使用 .editorconfig 统一格式
- 启用 Roslyn Analyzers
- 强制code review流程

⚠️ 可以改进的地方 (学习机会):

部分方法较长
- 文件: Connectors.OpenAI/ChatCompletion/OpenAIChatCompletionService.cs
- GetChatMessageContentsAsync 方法超过100行
- 💡 学习点: 可以提炼为更小的私有方法,提高可读性
复杂的泛型约束
- 文件: VectorData.Abstractions/
- 泛型参数链过长,理解成本高
- 💡 学习点: 如何在类型安全和简洁性之间权衡
实验性功能标注
- 大量使用 [Experimental("SKEXP0XXX")] 特性
- 代码: src/Experimental/Process.Abstractions/
- 💡 学习点: 如何在开源项目中管理API稳定性

TODO和FIXME

# 在代码中搜索这些标记,可以发现待改进点 git grep -n "// TODO" git grep -n "// FIXME"

潜在改进点(学习机会) 🎓

🔍 值得探索的重构机会:

向量存储一致性测试套件
- 路径: test/VectorData/VectorData.ConformanceTests/
- 机会: 学习如何设计跨多个实现的一致性测试
- 思考: 如果增加新的向量存储,如何确保行为一致?
OpenAPI函数生成
- 路径: Functions/Functions.OpenApi/
- 机会: OpenAPI spec → C# function 的代码生成逻辑
- 思考: 如何处理复杂的API认证? 如何优化生成代码的性能?
Agent编排复杂度
- 路径: Agents/Orchestration/
- 机会: 多Agent协同的状态管理
- 思考: 如何避免Agent间的死循环? 如何实现超时和回退?
Prompt模板引擎
- 路径: SemanticKernel.Core/TemplateEngine/
- 机会: 支持更多模板语法(Handlebars、Liquid已支持)
- 思考: 如何在安全性和灵活性之间权衡? 如何防止模板注入攻击?

第二部分:技能需求清单 📚

1. 基础技能要求 (必备) ✅

C# 编程语言

必须掌握的语法特性:

.NET 8.0 新特性
- Primary Constructors (主构造函数)
- Collection expressions ([1, 2, 3])
- required 修饰符

异步编程 (Async/Await)

await foreach (var item in GetDataAsync()) {  } IAsyncEnumerable<T>

LINQ 和 Lambda表达式

plugins.Where(p => p.Name.StartsWith("Time")) .Select(p => p.Functions) .SelectMany(f => f);

泛型和约束

T GetRequiredService<T>() where T : class

特性 (Attributes)

[KernelFunction] [Description("Gets the current time")] public string GetTime() => DateTime.Now.ToString();

.NET框架核心

必须了解的组件:

依赖注入 (DI)

// 掌握三种生命周期 services.AddSingleton<IMyService, MyService>(); services.AddScoped<IMyService, MyService>(); services.AddTransient<IMyService, MyService>();

配置系统

IConfiguration configuration = new ConfigurationBuilder() .AddJsonFile("appsettings.json") .AddEnvironmentVariables() .AddUserSecrets<Program>() .Build();

日志系统 (ILogger)

_logger.LogInformation("Processing {Count} items", items.Count);

HttpClient & HttpClientFactory

var client = _httpClientFactory.CreateClient("OpenAI");

具体版本要求 📦

从 Directory.Packages.props 分析:

<!-- 核心依赖 --> <PackageVersion Include="Microsoft.Extensions.AI" Version="9.9.0" /> <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="8.0.1" /> <PackageVersion Include="System.Text.Json" Version="8.0.6" /> <!-- AI SDK --> <PackageVersion Include="Azure.AI.OpenAI" Version="[2.3.0-beta.2]" /> <PackageVersion Include="OpenAI" Version="[2.4.0]" /> <!-- 测试框架 --> <PackageVersion Include="xunit" Version="2.9.3" /> <PackageVersion Include="Moq" Version="[4.18.4]" /> <PackageVersion Include="FluentAssertions" Version="8.2.0" />

⚠️ 版本兼容性重要提示:

Semantic Kernel 支持 .NET 8.0 和 .NET Standard 2.0
如果使用 Azure OpenAI,确保版本 >= 2.3.0-beta.2
OpenAI官方SDK必须使用 [2.4.0] (方括号表示精确版本)

基础工具和概念 🛠️

开发工具:

✅ Visual Studio 2022 / Rider / VS Code
✅ .NET CLI (dotnet build, dotnet test, dotnet run)
✅ Git (基本的 commit、branch、pull request)
✅ NuGet Package Manager

AI基础概念 (不需要深度数学,但要理解):

Embedding (向量嵌入): 文本 → 数字向量
Token: LLM的"单词"单位,影响成本
Temperature: 控制输出随机性 (0=确定, 1=创造性)
Function Calling: AI主动调用外部工具的能力
RAG (检索增强生成): 结合知识库的问答

2. 进阶技能要求 (深入掌握) 🚀

架构模式和设计原则

必须理解的模式:

插件架构 (Plugin Architecture)
- 如何设计可热插拔的模块?
- Semantic Kernel 的 KernelPlugin 实现
管道模式 (Pipeline Pattern)
- 过滤器链的实现原理
- 中间件的概念 (类似ASP.NET Core中间件)
SOLID原则实践
- SRP: 每个Plugin只做一件事
- OCP: 通过扩展Connector支持新AI,而非修改核心
- LSP: 所有 IChatCompletionService 可互换
- ISP: 接口细分 (IAudioToText, ITextToImage 等)
- DIP: 依赖抽象而非具体实现

依赖倒置实践

// 业务层依赖接口,而非具体的OpenAI public class MyService {  private readonly IChatCompletionService _chat; public MyService(IChatCompletionService chat) => _chat = chat; }

AI应用特有模式

Prompt Engineering:

如何编写清晰的System Message
如何使用Few-Shot Learning (提供示例)
如何处理上下文窗口限制

Function Calling最佳实践:

函数描述必须清晰明确
参数类型和枚举值要详细标注
使用 [Description] 特性引导AI理解

向量搜索优化:

Chunk Size (分块大小) 的选择
Top-K 和相似度阈值的调优
混合搜索 (Hybrid Search) 的应用

领域特定知识

如果开发特定领域的AI应用,需要了解:

企业应用开发:

Azure Active Directory 认证集成
API密钥安全管理 (Azure Key Vault)
成本控制和配额管理

对话式AI:

对话状态管理
多轮对话的上下文维护
意图识别和槽位填充

RAG系统构建:

文档解析 (PDF、Word、Markdown)
文本分块策略
向量数据库选型

3. 技能掌握程度建议 🎯

根据不同学习目标,我给你制定了三条路径:

初学者路径 (1-2周) 🌱

目标: 能运行示例,修改Prompt,调用基本功能

必学内容:

✅ C# 基础语法 (async/await, LINQ)
✅ 如何使用 Kernel.CreateBuilder() 创建Kernel
✅ 如何调用 InvokePromptAsync()
✅ 如何创建简单的Plugin (使用 [KernelFunction])
✅ 如何配置 OpenAI API Key

跳过内容 (暂时不需要):
❌ 向量数据库
❌ Agent编排
❌ 自定义Connector
❌ 过滤器高级用法

实践项目: 构建一个"智能助手"聊天机器人,能回答问题并查询天气

有经验的开发者路径 (2-4周) 🌳

目标: 能独立构建生产级AI应用,处理复杂场景

必学内容:

✅ 深入理解 Function Calling 机制
✅ 掌握多种AI服务的切换 (OpenAI ↔ Azure OpenAI ↔ Ollama)
✅ 向量数据库集成 (选一个: Qdrant / Redis / PostgreSQL)
✅ 过滤器系统 (实现日志、性能监控、内容审核)
✅ 依赖注入最佳实践
✅ 单元测试和集成测试

进阶内容:

RAG (检索增强生成) 实现
Streaming (流式输出) 处理
错误处理和重试策略
Token管理和成本优化

实践项目: 构建一个"企业知识库问答系统",支持文档上传、向量检索、多轮对话

意欲贡献代码的进阶者路径 (持续学习) 🌟

目标: 理解源码设计,能为开源社区贡献代码

必学内容:

✅ 阅读核心源码 (Kernel.cs, KernelFunction.cs)
✅ 理解所有设计模式的应用
✅ 掌握 Source Generator 和 Native AOT
✅ 了解性能优化技巧 (benchmarking, profiling)
✅ 熟悉开源协作流程 (GitHub PR, Code Review)

深度探索:

实现自定义Connector (如接入国产大模型)
扩展Prompt模板引擎
贡献向量存储适配器
优化Agent编排算法

参与方式:

在 GitHub 上认领 good first issue 标签的问题
改进文档和示例
提交 bug 报告和 feature 请求

第三部分:学习路径规划 🎯

1. 项目运行入口定位 (快速上手) 🚀

让我们先跑起来!我保证你在 30分钟内 就能看到第一个AI应用运行起来。

环境配置清单 ✅

步骤1: 安装.NET SDK

# Windows (使用 winget) winget install Microsoft.DotNet.SDK.9 # macOS (使用 Homebrew) brew install dotnet-sdk # 验证安装 dotnet --version # 应输出 9.0.xxx

步骤2: 克隆仓库

cd D:\Work\_projects\ git clone https://github.com/microsoft/semantic-kernel.git cd semantic-kernel/dotnet

步骤3: 配置API密钥

方式A: 使用 Secret Manager (推荐)

cd samples/GettingStarted dotnet user-secrets init dotnet user-secrets set "OpenAI:ApiKey" "sk-your-key-here" dotnet user-secrets set "OpenAI:ChatModelId" "gpt-4"

方式B: 使用环境变量

# PowerShell $env:OpenAI__ApiKey = "sk-your-key-here" $env:OpenAI__ChatModelId = "gpt-4"

步骤4: 运行第一个示例

cd samples/GettingStarted dotnet run --filter Step1_Create_Kernel

⚠️ 常见配置陷阱及解决方案

陷阱1: "OpenAI API key not configured"

# 原因: 密钥未正确配置 # 解决: 再次执行 dotnet user-secrets set "OpenAI:ApiKey" "your-key" # 验证: dotnet user-secrets list

陷阱2: "Target framework not supported"

# 原因: .NET SDK版本过低 # 解决: 确保安装了 .NET 8.0 或更高版本 # 检查: dotnet --list-sdks

陷阱3: "Rate limit exceeded"

// 原因: OpenAI免费额度耗尽或请求过快 // 解决: 添加重试策略 var kernel = Kernel.CreateBuilder() .AddOpenAIChatCompletion(modelId, apiKey) .Build(); // 或使用本地模型 (Ollama) var kernel = Kernel.CreateBuilder() .AddOllamaChatCompletion("llama3.2", new Uri("http://localhost:11434")) .Build();

陷阱4: "Connector not found"

# 原因: 缺少NuGet包 # 解决: 手动添加连接器包 dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

验证成功标志 ✅

运行成功后,你应该能看到类似输出:

What color is the sky? The sky is typically blue during the day... What color is the sea? The sea can appear blue, green, or even gray...

如果看到以上输出,恭喜你! 🎉 你已经成功运行了第一个Semantic Kernel程序!

2. 循序渐进学习计划 (四阶段法) 📖

阶段一: 环境搭建和项目启动 (1-2天) 🌱

学习目标:

✅ 成功运行至少3个示例
✅ 理解 Kernel 的基本概念
✅ 会修改 Prompt 并观察输出变化

学习路径:

Day 1 上午: 运行Getting Started示例

cd samples/GettingStarted dotnet test --logger "console;verbosity=detailed" --filter "FullyQualifiedName~Step1" dotnet test --filter "FullyQualifiedName~Step2" dotnet test --filter "FullyQualifiedName~Step3"

在IDE中打开这些文件,逐行阅读代码和注释:

Step1_Create_Kernel.cs - 理解Kernel的创建
Step2_Add_Plugins.cs - 理解Plugin的概念
Step3_Yaml_Prompt.cs - 理解Prompt模板

Day 1 下午: 修改示例进行实验

挑战1: 修改 Step1,让AI回答你的自定义问题

Console.WriteLine(await kernel.InvokePromptAsync("用一句话介绍量子计算"));

挑战2: 创建你的第一个Plugin

public class CalculatorPlugin {  [KernelFunction] [Description("计算两个数的和")] public int Add(int a, int b) => a + b; } // 注册并使用 kernel.Plugins.AddFromType<CalculatorPlugin>(); await kernel.InvokeAsync("CalculatorPlugin", "Add", new() {  ["a"] = 5, ["b"] = 3 });

Day 2: 理解核心概念

阅读官方文档(边读边运行代码):

尝试使用Jupyter Notebook:

cd notebooks # 安装Jupyter: pip install jupyter jupyter notebook 00-getting-started.ipynb

阶段成果: 能独立创建一个Kernel,添加Plugin,执行基本的AI调用

阶段二: 核心流程理解 (3-5天) 🌳

学习目标:

✅ 深入理解 Function Calling 机制
✅ 掌握多种AI服务的使用
✅ 能追踪完整的请求流程并画出流程图

学习路径:

Day 3-4: Function Calling深度实践

精读示例:

cd samples/Concepts/FunctionCalling # 运行所有function calling相关示例 dotnet test --filter "FullyQualifiedName~FunctionCalling"

关键示例:

FunctionCalling.cs - 基础function calling
FunctionCalling_ReturnMetadata.cs - 理解执行结果
OpenAI_FunctionCalling.cs - OpenAI特定用法

实践任务: 构建一个多功能助手

// 需求: AI助手能查天气、翻译文本、计算数学表达式 public class WeatherPlugin {  [KernelFunction, Description("获取指定城市的天气")] public string GetWeather(string city) => $"{city}: 晴天, 25°C"; } public class TranslatorPlugin {  [KernelFunction, Description("将文本翻译成指定语言")] public async Task<string> Translate(string text, string targetLang) {  // 这里可以调用翻译API return $"[{targetLang}] {text}"; } } // 组合使用 var kernel = Kernel.CreateBuilder() .AddOpenAIChatCompletion("gpt-4", apiKey) .Plugins.AddFromType<WeatherPlugin>() .Plugins.AddFromType<TranslatorPlugin>() .Build(); var result = await kernel.InvokePromptAsync( "北京天气怎么样? 然后把结果翻译成英文" );

Day 5: 多AI服务切换实践

尝试所有连接器:

cd samples/Concepts/ChatCompletion # OpenAI dotnet test --filter "OpenAI_ChatCompletion" # Azure OpenAI  dotnet test --filter "AzureOpenAI_ChatCompletion" # Ollama (本地) dotnet test --filter "Ollama_ChatCompletion" # Google Gemini dotnet test --filter "Google_GeminiChatCompletion"

实践任务: 实现AI Provider降级

// 目标: OpenAI失败时自动切换到Ollama var openAI = kernel.Services.GetService<IChatCompletionService>("openai"); var ollama = kernel.Services.GetService<IChatCompletionService>("ollama"); try {  return await openAI.GetChatMessageContentsAsync(...); } catch (HttpRequestException) {  _logger.LogWarning("OpenAI失败,切换到Ollama"); return await ollama.GetChatMessageContentsAsync(...); }

阶段成果:

能画出完整的Function Calling流程图
理解不同AI服务的差异和选型依据
能调试Kernel的执行流程

阶段三: 模块深入和定制开发 (1-2周) 🚀

学习目标:

✅ 掌握向量数据库和RAG
✅ 实现自定义过滤器
✅ 能构建完整的AI应用

Week 1: 向量数据库和RAG

Day 1-2: 向量存储基础

cd samples/GettingStartedWithVectorStores dotnet run

关键概念:

Embedding: 文本 → 向量
向量相似度搜索
数据导入和检索

实践: 选择一个向量数据库深入学习

// 推荐新手使用 InMemory (无需额外服务) var vectorStore = new InMemoryVectorStore(); var collection = vectorStore.GetCollection<string, Hotel>("hotels"); // 导入数据 await collection.UpsertAsync(new Hotel {  Id = "h1", Name = "海景酒店", Description = "位于海边,视野开阔,环境优美" }); // 搜索 var results = await collection.SearchAsync("我想找海边的酒店", top: 3);

Day 3-4: 构建RAG系统

精读示例:

cd samples/Concepts/RAG dotnet test --filter "WithPlugins" cd samples/Demos/VectorStoreRAG dotnet run

实践项目: 个人知识库问答

功能需求: 1. 支持上传TXT/PDF/Markdown文档 2. 自动分块并存储到向量数据库 3. 用户提问时检索相关片段 4. AI基于检索结果回答问题 技术栈: - 向量存储: Qdrant / InMemory - 文本分块: TextChunker - Embedding: OpenAI text-embedding-3-small - LLM: GPT-4

Week 2: 过滤器和高级特性

Day 1-2: 实现自定义过滤器

cd samples/Concepts/Filtering dotnet test --filter "FunctionInvocationFiltering"

实践: 实现一个完整的监控过滤器

public class MonitoringFilter : IFunctionInvocationFilter {  private readonly ILogger _logger; private readonly Histogram<double> _durationHistogram; public async Task OnFunctionInvocationAsync( FunctionInvocationContext context, Func<FunctionInvocationContext, Task> next) {  var sw = Stopwatch.StartNew(); try {  await next(context); _logger.LogInformation( "Function {Name} succeeded in {Duration}ms", context.Function.Name, sw.ElapsedMilliseconds); } catch (Exception ex) {  _logger.LogError(ex, "Function {Name} failed", context.Function.Name); throw; } finally {  _durationHistogram.Record(sw.Elapsed.TotalMilliseconds); } } }

Day 3-5: 综合项目实战

选择一个Demo深入研究并改进:

cd samples/Demos # 推荐项目: # 1. VectorStoreRAG - RAG完整实现 # 2. ContentSafety - 内容安全审核 # 3. AgentFrameworkWithAspire - Agent + 微服务

阶段成果:

能独立构建一个RAG应用
理解过滤器的最佳实践
掌握性能监控和日志记录

阶段四: 架构理解和贡献指南 (2周+) 🌟

学习目标:

✅ 理解源码设计和架构决策
✅ 能优化性能和处理边缘情况
✅ 具备贡献开源代码的能力

Week 1: 源码深度阅读

Day 1-3: 核心类源码分析

按顺序阅读以下文件(在IDE中打开,添加注释):

Kernel.cs - 理解Kernel的初始化和生命周期
KernelFunction.cs - 理解函数抽象
KernelFunctionFromMethod.cs - 理解如何将C#方法转为Function
KernelFunctionFromPrompt.cs - 理解Prompt如何被执行

阅读技巧:

使用 "Find All References" 查看调用关系
用调试器单步执行示例代码
画出类图和调用时序图

Day 4-5: Connector实现分析

深入一个Connector源码:

cd src/Connectors/Connectors.OpenAI # 重点阅读: - OpenAIChatCompletionService.cs - ClientCore.cs

学习重点:

HTTP请求是如何构建的
流式响应如何处理
错误重试机制
Token计算逻辑

Week 2: 实践与贡献

Day 1-3: 性能优化实践

使用BenchmarkDotNet进行性能测试:

[MemoryDiagnoser] public class KernelBenchmarks {  [Benchmark] public async Task InvokePrompt() {  await _kernel.InvokePromptAsync("Hello"); } }

优化方向:

减少不必要的对象分配
使用 ObjectPool 复用对象
优化字符串拼接
使用 Span<T> 避免数组复制

Day 4-7: 开源贡献

阅读贡献指南

# 查看项目根目录的CONTRIBUTING.md

认领Issue
- 访问 https://github.com/microsoft/semantic-kernel/issues
- 筛选 good first issue 标签
- 在Issue下评论表示愿意处理

提交PR

git checkout -b feature/my-improvement # 修改代码 dotnet test git commit -m "feat: add xxx support" git push origin feature/my-improvement # 在GitHub上创建Pull Request

阶段成果:

能阅读并理解核心源码
提交至少1个PR (即使是文档改进)
理解项目的架构演进方向

3. 学习路径流程图 🗺️

graph TD Start[开始学习] --> Env[阶段一: 环境搭建<br/>1-2天] Env --> Check1{能运行示例?} Check1 -->|否| Debug1[检查.NET版本<br/>检查API Key<br/>查看错误日志] Debug1 --> Env Check1 -->|是| Core[阶段二: 核心流程<br/>3-5天] Core --> Learn1[学习Function Calling] Core --> Learn2[学习多AI服务] Core --> Check2{能画流程图?} Check2 -->|否| Practice1[运行更多示例<br/>添加日志输出<br/>使用调试器] Practice1 --> Core Check2 -->|是| Advanced[阶段三: 模块深入<br/>1-2周] Advanced --> RAG[RAG实现] Advanced --> Vector[向量数据库] Advanced --> Filter[过滤器] Advanced --> Check3{完成项目?} Check3 -->|否| Practice2[选择更小的目标<br/>参考Demos<br/>寻求社区帮助] Practice2 --> Advanced Check3 -->|是| Expert[阶段四: 架构理解<br/>2周+] Expert --> Source[阅读源码] Expert --> Optimize[性能优化] Expert --> Contribute[开源贡献] Expert --> Check4{准备好贡献?} Check4 -->|否| Practice3[继续学习设计模式<br/>参与社区讨论<br/>改进个人项目] Practice3 --> Expert Check4 -->|是| End[🎉 成为SK专家!] style Start fill:#a8e6cf style End fill:#ffd3b6 style Env fill:#ffaaa5 style Core fill:#ff8b94 style Advanced fill:#a8e6cf style Expert fill:#dcedc1

第四部分:实践建议和进阶指导 💡

1. 调试技巧和常见陷阱 🐛

新人常见陷阱 (Top 5)

陷阱1: API密钥泄露到GitHub

❌ 错误做法: 直接写在代码里 var apiKey = "sk-proj-..."; ✅ 正确做法: 使用环境变量或Secret Manager var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY"); # 并确保 .gitignore 包含 appsettings.*.json

陷阱2: 忘记处理异常

❌ 裸调用,生产环境崩溃 await kernel.InvokePromptAsync(prompt); ✅ 捕获并处理 try {  return await kernel.InvokePromptAsync(prompt); } catch (HttpOperationException ex) when (ex.StatusCode == HttpStatusCode.TooManyRequests) {  _logger.LogWarning("Rate limited, retry after {Seconds}s", ex.RetryAfter); await Task.Delay(ex.RetryAfter); return await kernel.InvokePromptAsync(prompt); // 重试 }

陷阱3: Function描述不清晰导致AI调用失败

❌ 模糊的描述 [KernelFunction, Description("Get data")] public string GetData(string input) => "..."; ✅ 清晰的描述 [KernelFunction] [Description("根据城市名称获取实时天气信息,包括温度、湿度和天气状况")] public string GetWeather( [Description("城市名称,例如: 北京, 上海")] string cityName) => "...";

陷阱4: 上下文窗口溢出

❌ 无限制累积对话历史 history.AddUserMessage(input); var response = await chat.GetChatMessageContentAsync(history); history.AddAssistantMessage(response); // 几十轮对话后超出token限制! ✅ 使用ChatHistoryReducer var reducer = new ChatHistoryTruncationReducer(maxTokens: 4000); var reducedHistory = await reducer.ReduceAsync(history);

陷阱5: 忘记Dispose

❌ 资源泄漏 var kernel = Kernel.CreateBuilder()...Build(); // 使用后忘记释放 ✅ 使用using语句 (虽然Kernel不需要Dispose,但HttpClient等资源需要) await using var serviceProvider = services.BuildServiceProvider();

2. 扩展练习建议 (从易到难) 🎯

初级练习 (1-2天)

练习1: 修改Prompt模板

# 修改 samples/GettingStarted/Resources/GenerateStory.yaml template: | 写一个关于{ {$topic}}的{ {$style}}故事, 故事长度为{ {$length}}字。

练习2: 创建天气查询Plugin

public class WeatherPlugin {  private readonly HttpClient _http; [KernelFunction, Description("查询指定城市的天气")] public async Task<string> GetWeather(string city) {  // 调用真实的天气API (如 wttr.in) var response = await _http.GetStringAsync($"https://wttr.in/{city}?format=3"); return response; } }

中级练习 (3-5天)

练习3: 实现多轮对话机器人

// 需求: 维护对话历史,支持上下文理解 var history = new ChatHistory(); history.AddSystemMessage("你是一个友好的助手"); while (true) {  Console.Write("用户: "); var input = Console.ReadLine(); if (input == "exit") break; history.AddUserMessage(input); var response = await chat.GetChatMessageContentAsync(history, kernel: kernel); history.AddAssistantMessage(response); Console.WriteLine($"助手: {response}"); }

练习4: 构建PDF文档问答系统

步骤: 1. 使用PdfPig库解析PDF 2. 使用TextChunker分块 3. 生成Embedding并存储到向量数据库 4. 用户提问时检索Top 3相关块 5. 将检索结果注入Prompt,让AI回答

高级练习 (1-2周)

练习5: 实现Agent工作流

场景: 旅行规划助手 Agent1: 搜索目的地信息 Agent2: 查询酒店和机票价格 Agent3: 生成行程建议 Agent4: 整合所有信息生成最终方案 挑战: Agent间的消息传递,状态管理,错误恢复

练习6: 优化RAG性能

任务: 1. 实现混合搜索(BM25 + 向量搜索) 2. 添加重排序(Rerank) 3. 实现查询扩展 4. 测量检索准确率(Recall@10)

3. 参与贡献的途径 🤝

找到适合的Issue

步骤1: 浏览Issue列表

访问: https://github.com/microsoft/semantic-kernel/issues 筛选条件: ✅ is:open ✅ label:"good first issue" ✅ label:"help wanted"

推荐的Issue类型 (新手友好):

文档改进 (Documentation)
示例代码添加 (Samples)
单元测试补充 (Tests)
小的Bug修复 (Bugs)

步骤2: 评论表达意愿

Hi! I'd like to work on this issue. I'm familiar with C# and [相关技术]. Could you assign this to me?

代码规范要求

项目使用 .editorconfig 和 Roslyn Analyzers 强制代码风格:

必须遵守的规范:

// 1. Nullable reference types 必须正确标注 public string? GetOptionalValue() => null; // ✅ public string GetOptionalValue() => null; // ❌ 警告 // 2. 异步方法必须以Async结尾 public async Task<string> FetchDataAsync() {  } // ✅ public async Task<string> FetchData() {  } // ❌ // 3. 使用表达式主体 (简短方法) public int Add(int a, int b) => a + b; // ✅ // 4. 接口以I开头 public interface IChatService {  } // ✅ // 5. 使用 file-scoped namespace namespace Microsoft.SemanticKernel; // ✅

运行代码检查:

# 格式化代码 dotnet format # 运行所有测试 dotnet test # 检查编译警告 dotnet build /warnaserror

提交流程

步骤1: Fork仓库

# 在GitHub上点击Fork按钮 # 克隆你的Fork git clone https://github.com/YOUR_USERNAME/semantic-kernel.git cd semantic-kernel/dotnet

步骤2: 创建分支

git checkout -b feature/add-custom-connector

步骤3: 提交代码

git add . git commit -m "feat: add support for Anthropic Claude connector" # 提交信息格式: feat/fix/docs/test/refactor: description

步骤4: 推送并创建PR

git push origin feature/add-custom-connector # 访问GitHub,点击 "Create Pull Request"

PR描述模板:

## 变更说明 添加了对Anthropic Claude的支持 ## 变更类型 - [ ] Bug修复 - [x] 新功能 - [ ] 文档更新 - [ ] 测试改进 ## 测试 - [x] 添加了单元测试 - [x] 手动测试通过 ## 相关Issue Closes #1234

社区互动

推荐渠道:

💬 GitHub Discussions: 提问和讨论
🐦 Twitter: 关注 @MSSemanticKernel
📺 YouTube: Microsoft Semantic Kernel频道
📝 博客: https://devblogs.microsoft.com/

第五部分:技术栈学习指引 🌐

1. 官方文档定位 📚

Semantic Kernel核心文档

必读文档:

官方文档中心 ⭐⭐⭐⭐⭐
- 链接: https://learn.microsoft.com/semantic-kernel/
- 重点章节:
  - Overview → Concepts (理解核心概念)
  - Quickstart → Get Started (快速入门)
  - AI Services → Connectors (连接器选型)
  - Agents → Building Agents (Agent开发)
GitHub Wiki ⭐⭐⭐⭐
- 链接: https://github.com/microsoft/semantic-kernel/wiki
- 内容: 架构决策记录(ADR),设计文档
API文档 ⭐⭐⭐
- 链接: https://learn.microsoft.com/dotnet/api/microsoft.semantickernel
- 用途: 查询详细的API签名和用法

项目自身文档

项目包含丰富的README和示例:

必读文档索引: ├─ README.md (项目根目录) ⭐ 5分钟快速开始 ├─ dotnet/README.md ⭐ .NET SDK概览 ├─ dotnet/samples/README.md ⭐ 示例导航 ├─ dotnet/samples/GettingStarted/README.md ⭐ 入门教程 ├─ dotnet/samples/Concepts/README.md ⭐ 概念示例索引 ├─ dotnet/docs/EXPERIMENTS.md ⚠️ 实验性功能清单 └─ dotnet/docs/TELEMETRY.md 📊 遥测和监控

权威技术书籍

推荐书籍:

《Building LLM Apps: Create Intelligent Apps and Agents with Large Language Models》 ⭐⭐⭐⭐⭐
- 作者: Valentina Alto
- 内容: 使用Semantic Kernel构建LLM应用的完整指南
- 适合: 有一定.NET基础的开发者
《Generative AI with LangChain》 ⭐⭐⭐⭐
- 作者: Ben Auffarth
- 内容: 虽然是LangChain,但AI应用架构思想通用
- 适合: 理解AI编排框架的设计理念
《Designing Data-Intensive Applications》 ⭐⭐⭐⭐⭐
- 作者: Martin Kleppmann
- 内容: 向量数据库、分布式系统基础
- 适合: 构建生产级AI系统

2. 学习路径建议 🛤️

技能学习顺序

Phase 1: 基础夯实 (2-3周)

Week 1: C# + .NET 基础 ├─ async/await 深入理解 ├─ LINQ 和 Lambda ├─ 依赖注入原理 └─ 泛型和反射 Week 2: AI基础概念 ├─ LLM工作原理(不需要数学) ├─ Token和上下文窗口 ├─ Prompt Engineering └─ Function Calling原理 Week 3: Semantic Kernel入门 ├─ 运行所有GettingStarted示例 ├─ 阅读核心类源码 └─ 完成第一个完整项目

Phase 2: 进阶提升 (4-6周)

Week 4-5: 向量数据库和RAG ├─ Embedding原理 ├─ 向量相似度计算 ├─ RAG系统设计 └─ 至少掌握一个向量数据库 Week 6-7: Agent和编排 ├─ Agent架构模式 ├─ 多Agent协同 ├─ 状态管理 └─ 错误处理和重试 Week 8-9: 生产化 ├─ 监控和日志 ├─ 性能优化 ├─ 成本控制 └─ 安全和合规

Phase 3: 专家之路 (持续)

深度方向选择: ├─ 方向A: AI Infra (基础设施) │ ├─ 向量数据库内核 │ ├─ 模型推理优化 │ └─ 分布式训练 │ ├─ 方向B: AI Application (应用) │ ├─ 垂直领域AI助手 │ ├─ 多模态应用 │ └─ AI Agent产品化 │ └─ 方向C: AI Framework (框架) ├─ 参与Semantic Kernel开发 ├─ 设计新的编排模式 └─ 贡献核心功能

核心概念优先级

🔥 优先掌握 (前2周):

Kernel的生命周期
Function和Plugin的概念
Prompt模板语法
基本的依赖注入
如何调用OpenAI API

⭐ 重要概念 (第3-4周):

Function Calling机制
向量Embedding和相似度搜索
ChatHistory管理
流式输出处理
多AI服务切换

💡 进阶概念 (第5-8周):

Agent编排模式
过滤器链设计
自定义Connector开发
RAG系统优化
性能调优技巧

🚀 高级概念 (长期):

分布式Agent架构
Source Generator应用
Native AOT优化
大规模部署策略
AI系统可观测性

实践项目推荐

新手项目:

智能TODO列表 - 使用自然语言添加任务
天气查询机器人 - Function Calling入门
Markdown笔记助手 - 总结、提取关键词

进阶项目:

企业知识库问答 - RAG完整实现
Code Review助手 - 分析代码并提供建议
多语言客服系统 - 多AI服务 + 翻译

专家项目:

垂直领域Agent平台 - 金融/医疗/法律
AI应用市场 - Plugin生态
低代码AI编排平台 - 可视化Flow设计

3. 工具与环境配置指南 🔧

开发环境搭建

IDE推荐:

方案A: Visual Studio 2022 (Windows推荐)

下载: https://visualstudio.microsoft.com/ 版本: Community (免费) 必装扩展: ✅ ReSharper (可选,提升开发效率) ✅ GitHub Copilot (AI代码助手) ✅ Markdown Editor

方案B: JetBrains Rider (跨平台,性能最佳)

下载: https://www.jetbrains.com/rider/ 优势: 更快的索引,更好的重构工具 学生免费: 使用教育邮箱申请

方案C: Visual Studio Code (轻量级)

下载: https://code.visualstudio.com/ 必装扩展: ✅ C# Dev Kit ✅ .NET Install Tool ✅ REST Client (测试API)

常用工具使用

1. HTTP调试工具

Postman (测试AI API)

# 示例: 测试OpenAI API POST https://api.openai.com/v1/chat/completions Headers: Authorization: Bearer sk-... Content-Type: application/json Body: {  "model": "gpt-4", "messages": [{ "role": "user", "content": "Hello"}] }

2. 向量数据库工具

Qdrant Web UI

docker run -p 6333:6333 qdrant/qdrant # 访问 http://localhost:6333/dashboard

3. 日志查看器

Seq (结构化日志)

docker run -d -p 5341:80 datalust/seq # 在代码中配置 builder.Services.AddLogging(c => c.AddSeq("http://localhost:5341"));

4. 性能分析

dotnet-counters (实时监控)

dotnet tool install -g dotnet-counters dotnet-counters monitor --process-id <PID>

BenchmarkDotNet (性能测试)

[MemoryDiagnoser] public class MyBenchmarks {  [Benchmark] public async Task TestKernel() {  } }

4. 进阶拓展方向 🚀

技术博客与专家观点

官方博客:

Microsoft DevBlogs: https://devblogs.microsoft.com/semantic-kernel/
Azure AI Blog: https://techcommunity.microsoft.com/azure-ai

推荐博主:

Stephen Toub (微软性能专家,异步编程)
Scott Hanselman (.NET生态)
John Maeda (AI产品思考)

中文资源:

知乎专栏: 搜索 "Semantic Kernel"
B站视频: 微软Reactor系列讲座
博客园: .NET + AI 标签

社区与论坛

官方社区:

GitHub Discussions: https://github.com/microsoft/semantic-kernel/discussions
- 提问、分享项目、讨论新特性

技术论坛:

Stack Overflow: 标签 semantic-kernel
Reddit: r/dotnet, r/MachineLearning
Discord: Microsoft AI Community

国内社区:

掘金: .NET专栏
SegmentFault: AI技术标签
开源中国: Semantic Kernel镜像仓库

总结与寄语 🎓

亲爱的学习者,恭喜你读到这里! 🎉

你现在手上拥有的,是一份凝结了Semantic Kernel精华的完整学习地图。记住,学习AI开发不是百米冲刺,而是一场马拉松。这个框架背后蕴含的不仅是代码,更是微软在AI编排领域的深度思考和工程实践。

最后的建议 💡:

动手实践胜过千遍阅读 - 每学一个概念就写代码验证
不要畏惧源码 - 最好的文档就是代码本身
积极参与社区 - 在帮助别人的过程中你会学得更快
保持好奇心 - AI领域每天都在进化,保持学习的热情

如果在学习过程中遇到困难,记住:

所有的专家都是从新手走来的
GitHub Issues是你的朋友
社区永远欢迎你的问题

现在,关掉这份文档,打开IDE,开始你的第一行代码吧! 🚀

cd samples/GettingStarted dotnet run

愿你在AI开发的道路上越走越远,创造出改变世界的应用! ✨

Semantic Kernel .NET 架构学习指南

Semantic Kernel .NET 架构学习指南 🚀

第一部分:项目架构深度解析 🔍

1. 项目架构概览

用通俗的类比理解 Semantic Kernel 💡

核心设计特征 ⭐

同类项目对比 📊

技术栈分析 🔧

架构流程描述 🌊

2. 目录结构与核心流程 📁

目录组织逻辑

关键文件定位 🎯

模块依赖关系 📊

典型业务流程:智能客服机器人 🤖

3. 代码结构观察 🔍

代码组织模式

设计模式识别 🎨

代码质量观察 ⭐

潜在改进点(学习机会) 🎓

第二部分:技能需求清单 📚

1. 基础技能要求 (必备) ✅

C# 编程语言

.NET框架核心

具体版本要求 📦

基础工具和概念 🛠️

2. 进阶技能要求 (深入掌握) 🚀

架构模式和设计原则

AI应用特有模式

领域特定知识

3. 技能掌握程度建议 🎯

初学者路径 (1-2周) 🌱

有经验的开发者路径 (2-4周) 🌳

意欲贡献代码的进阶者路径 (持续学习) 🌟

第三部分:学习路径规划 🎯

1. 项目运行入口定位 (快速上手) 🚀

环境配置清单 ✅

⚠️ 常见配置陷阱及解决方案

验证成功标志 ✅

2. 循序渐进学习计划 (四阶段法) 📖

阶段一: 环境搭建和项目启动 (1-2天) 🌱

阶段二: 核心流程理解 (3-5天) 🌳

阶段三: 模块深入和定制开发 (1-2周) 🚀

阶段四: 架构理解和贡献指南 (2周+) 🌟

3. 学习路径流程图 🗺️

第四部分:实践建议和进阶指导 💡

1. 调试技巧和常见陷阱 🐛

推荐的调试方法

新人常见陷阱 (Top 5)

2. 扩展练习建议 (从易到难) 🎯

初级练习 (1-2天)

中级练习 (3-5天)

高级练习 (1-2周)

3. 参与贡献的途径 🤝

找到适合的Issue

代码规范要求

提交流程

社区互动

第五部分:技术栈学习指引 🌐

1. 官方文档定位 📚

Semantic Kernel核心文档

项目自身文档

权威技术书籍

2. 学习路径建议 🛤️

技能学习顺序

核心概念优先级

实践项目推荐

3. 工具与环境配置指南 🔧

开发环境搭建

常用工具使用

4. 进阶拓展方向 🚀

技术博客与专家观点

相关技术大会

社区与论坛

总结与寄语 🎓

通义大模型

热门文章

最新文章

相关课程

相关电子书