Semantic Kernel .NET 架构学习指南

本文涉及的产品
多模态交互后付费免费试用,全链路、全Agent
简介: 本指南系统解析微软Semantic Kernel .NET架构,涵盖核心组件、设计模式与源码结构,结合实战路径与调试技巧,助你从入门到贡献开源,掌握AI编排开发全栈技能。

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 采用了插件化的微内核架构,具有以下突出特点:

  1. 高度可扩展的连接器生态 🔌

    • 支持 10+ 种主流 AI 服务商(OpenAI、Azure OpenAI、Google、Amazon Bedrock、Ollama、Mistral AI等)
    • 统一的抽象接口,切换AI提供商只需修改配置
    • 内置向量存储支持(15+ 数据库: Qdrant、Pinecone、Redis、PostgreSQL、MongoDB等)
  2. 函数式编程范式 🎯

    • 将业务逻辑封装为函数(Function)
    • 支持原生C#方法函数和Prompt模板函数
    • 函数可以被AI自动调用(Function Calling)
  3. 依赖注入友好 💉

    • 深度集成 Microsoft.Extensions.DependencyInjection
    • 支持标准ASP.NET Core服务生命周期管理
    • 便于单元测试和模块化开发
  4. 多层过滤器机制 🛡️

    • Prompt渲染过滤器:在提示词发送前拦截和修改
    • 函数调用过滤器:控制函数执行流程
    • 自动函数调用过滤器:拦截AI的function calling行为
    • 可实现日志、性能监控、权限控制、内容安全等横切关注点
  5. 实验性Agent框架 🤖

    • 支持OpenAI Assistants API
    • 多Agent协同编排
    • 内置对话管理和状态保持

同类项目对比 📊

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

Semantic Kernel的独特优势:

  • 类型安全:强类型语言带来的编译时检查和IDE智能提示
  • 企业级成熟度:微软官方支持,遵循.NET最佳实践
  • Azure深度集成:与Azure OpenAI、Azure AI Search等无缝对接
  • 性能优化:支持Native AOT,启动快,内存占用小

技术栈分析 🔧

核心框架层 (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       # 交互式入门

关键文件定位 🎯

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

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

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

    // 理解"函数"是什么,它如何被调用
    public abstract class KernelFunction
    {
         
        public KernelFunctionMetadata Metadata {
          get; }
        public Task<FunctionResult> InvokeAsync(...);
    }
    
  3. samples/GettingStarted/Step1_Create_Kernel.cs (最小示例)

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

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

  1. 函数调用链路: SemanticKernel.Core/Functions/KernelFunctionFromMethod.cs
  2. Prompt渲染: SemanticKernel.Core/PromptTemplate/KernelPromptTemplate.cs
  3. OpenAI集成: Connectors/Connectors.OpenAI/
  4. 向量搜索: 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: 返回结果

实现文件索引:

  1. 入口: samples/Concepts/FunctionCalling/FunctionCalling.cs
  2. Plugin定义: 自定义类,使用[KernelFunction]特性标记
  3. Kernel构建: KernelBuilder.AddOpenAIChatCompletion(...).AddPlugin<OrderPlugin>().Build()
  4. 过滤器注入: 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) => {
    /* 订阅事件 */ };

代码质量观察 ⭐

✅ 优秀之处:

  1. 完善的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>
    
  2. Nullable引用类型启用

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

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

  3. Source Generator应用

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

    AOT友好,性能优化

  4. 单元测试覆盖

    • SemanticKernel.UnitTests/ 包含大量测试
    • 使用 xUnit + Moq + FluentAssertions
    • 测试覆盖率 > 80%
  5. 代码风格一致性

    • 使用 .editorconfig 统一格式
    • 启用 Roslyn Analyzers
    • 强制code review流程

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

  1. 部分方法较长

    • 文件: Connectors.OpenAI/ChatCompletion/OpenAIChatCompletionService.cs
    • GetChatMessageContentsAsync 方法超过100行
    • 💡 学习点: 可以提炼为更小的私有方法,提高可读性
  2. 复杂的泛型约束

    • 文件: VectorData.Abstractions/
    • 泛型参数链过长,理解成本高
    • 💡 学习点: 如何在类型安全和简洁性之间权衡
  3. 实验性功能标注

    • 大量使用 [Experimental("SKEXP0XXX")] 特性
    • 代码: src/Experimental/Process.Abstractions/
    • 💡 学习点: 如何在开源项目中管理API稳定性
  4. TODO和FIXME

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

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

🔍 值得探索的重构机会:

  1. 向量存储一致性测试套件

    • 路径: test/VectorData/VectorData.ConformanceTests/
    • 机会: 学习如何设计跨多个实现的一致性测试
    • 思考: 如果增加新的向量存储,如何确保行为一致?
  2. OpenAPI函数生成

    • 路径: Functions/Functions.OpenApi/
    • 机会: OpenAPI spec → C# function 的代码生成逻辑
    • 思考: 如何处理复杂的API认证? 如何优化生成代码的性能?
  3. Agent编排复杂度

    • 路径: Agents/Orchestration/
    • 机会: 多Agent协同的状态管理
    • 思考: 如何避免Agent间的死循环? 如何实现超时和回退?
  4. 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框架核心

必须了解的组件:

  1. 依赖注入 (DI)

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

    IConfiguration configuration = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json")
        .AddEnvironmentVariables()
        .AddUserSecrets<Program>()
        .Build();
    
  3. 日志系统 (ILogger)

    _logger.LogInformation("Processing {Count} items", items.Count);
    
  4. 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. 进阶技能要求 (深入掌握) 🚀

架构模式和设计原则

必须理解的模式:

  1. 插件架构 (Plugin Architecture)

    • 如何设计可热插拔的模块?
    • Semantic Kernel 的 KernelPlugin 实现
  2. 管道模式 (Pipeline Pattern)

    • 过滤器链的实现原理
    • 中间件的概念 (类似ASP.NET Core中间件)
  3. SOLID原则实践

    • SRP: 每个Plugin只做一件事
    • OCP: 通过扩展Connector支持新AI,而非修改核心
    • LSP: 所有 IChatCompletionService 可互换
    • ISP: 接口细分 (IAudioToText, ITextToImage 等)
    • DIP: 依赖抽象而非具体实现
  4. 依赖倒置实践

    // 业务层依赖接口,而非具体的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,调用基本功能

必学内容:

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

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

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


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

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

必学内容:

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

进阶内容:

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

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


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

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

必学内容:

  1. ✅ 阅读核心源码 (Kernel.cs, KernelFunction.cs)
  2. ✅ 理解所有设计模式的应用
  3. ✅ 掌握 Source Generator 和 Native AOT
  4. ✅ 了解性能优化技巧 (benchmarking, profiling)
  5. ✅ 熟悉开源协作流程 (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中打开这些文件,逐行阅读代码和注释:

  1. Step1_Create_Kernel.cs - 理解Kernel的创建
  2. Step2_Add_Plugins.cs - 理解Plugin的概念
  3. 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: 理解核心概念

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

  1. Semantic Kernel概念
  2. 函数调用
  3. Prompt模板

尝试使用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"

关键示例:

  1. FunctionCalling.cs - 基础function calling
  2. FunctionCalling_ReturnMetadata.cs - 理解执行结果
  3. 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中打开,添加注释):

  1. Kernel.cs - 理解Kernel的初始化和生命周期
  2. KernelFunction.cs - 理解函数抽象
  3. KernelFunctionFromMethod.cs - 理解如何将C#方法转为Function
  4. 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: 开源贡献

  1. 阅读贡献指南

    # 查看项目根目录的CONTRIBUTING.md
    
  2. 认领Issue

  3. 提交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. 调试技巧和常见陷阱 🐛

推荐的调试方法

方法1: 启用详细日志

var builder = Kernel.CreateBuilder();
builder.Services.AddLogging(c => c
    .AddConsole()
    .SetMinimumLevel(LogLevel.Trace));  // 显示所有日志

var kernel = builder.Build();

方法2: 使用IFunctionInvocationFilter记录所有调用

public class DebugFilter : IFunctionInvocationFilter
{
   
    public async Task OnFunctionInvocationAsync(
        FunctionInvocationContext context, 
        Func<FunctionInvocationContext, Task> next)
    {
   
        Console.WriteLine($"[调用] {context.Function.Name}");
        Console.WriteLine($"[参数] {JsonSerializer.Serialize(context.Arguments)}");

        await next(context);

        Console.WriteLine($"[结果] {context.Result}");
    }
}

方法3: 使用Fiddler/Postman抓包

// 配置HTTP代理,查看实际的API请求
var handler = new HttpClientHandler
{
   
    Proxy = new WebProxy("http://localhost:8888")
};
builder.Services.AddHttpClient("OpenAI")
    .ConfigurePrimaryHttpMessageHandler(() => handler);

新人常见陷阱 (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核心文档

必读文档:

  1. 官方文档中心 ⭐⭐⭐⭐⭐

    • 链接: https://learn.microsoft.com/semantic-kernel/
    • 重点章节:
      • Overview → Concepts (理解核心概念)
      • Quickstart → Get Started (快速入门)
      • AI Services → Connectors (连接器选型)
      • Agents → Building Agents (Agent开发)
  2. GitHub Wiki ⭐⭐⭐⭐

  3. 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                  📊 遥测和监控

权威技术书籍

推荐书籍:

  1. 《Building LLM Apps: Create Intelligent Apps and Agents with Large Language Models》 ⭐⭐⭐⭐⭐

    • 作者: Valentina Alto
    • 内容: 使用Semantic Kernel构建LLM应用的完整指南
    • 适合: 有一定.NET基础的开发者
  2. 《Generative AI with LangChain》 ⭐⭐⭐⭐

    • 作者: Ben Auffarth
    • 内容: 虽然是LangChain,但AI应用架构思想通用
    • 适合: 理解AI编排框架的设计理念
  3. 《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周):

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

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

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

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

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

🚀 高级概念 (长期):

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

实践项目推荐

新手项目:

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

进阶项目:

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

专家项目:

  1. 垂直领域Agent平台 - 金融/医疗/法律
  2. AI应用市场 - Plugin生态
  3. 低代码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. 进阶拓展方向 🚀

技术博客与专家观点

官方博客:

推荐博主:

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

中文资源:

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

相关技术大会

必看会议:

  1. Microsoft Build ⭐⭐⭐⭐⭐

  2. .NET Conf ⭐⭐⭐⭐

  3. AI Engineer Summit ⭐⭐⭐⭐

会议录像资源:

YouTube频道:
├─ Microsoft Developer (官方)
├─ dotNET (社区)
└─ GOTO Conferences (高质量技术分享)

社区与论坛

官方社区:

技术论坛:

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

国内社区:

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

总结与寄语 🎓

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

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

最后的建议 💡:

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

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

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

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

cd samples/GettingStarted
dotnet run

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

目录
相关文章
|
11天前
|
存储 关系型数据库 分布式数据库
PostgreSQL 18 发布,快来 PolarDB 尝鲜!
PostgreSQL 18 发布,PolarDB for PostgreSQL 全面兼容。新版本支持异步I/O、UUIDv7、虚拟生成列、逻辑复制增强及OAuth认证,显著提升性能与安全。PolarDB-PG 18 支持存算分离架构,融合海量弹性存储与极致计算性能,搭配丰富插件生态,为企业提供高效、稳定、灵活的云数据库解决方案,助力企业数字化转型如虎添翼!
|
9天前
|
存储 人工智能 搜索推荐
终身学习型智能体
当前人工智能前沿研究的一个重要方向:构建能够自主学习、调用工具、积累经验的小型智能体(Agent)。 我们可以称这种系统为“终身学习型智能体”或“自适应认知代理”。它的设计理念就是: 不靠庞大的内置知识取胜,而是依靠高效的推理能力 + 动态获取知识的能力 + 经验积累机制。
347 130
|
9天前
|
存储 人工智能 Java
AI 超级智能体全栈项目阶段二:Prompt 优化技巧与学术分析 AI 应用开发实现上下文联系多轮对话
本文讲解 Prompt 基本概念与 10 个优化技巧,结合学术分析 AI 应用的需求分析、设计方案,介绍 Spring AI 中 ChatClient 及 Advisors 的使用。
436 130
AI 超级智能体全栈项目阶段二:Prompt 优化技巧与学术分析 AI 应用开发实现上下文联系多轮对话
|
3天前
|
存储 安全 前端开发
如何将加密和解密函数应用到实际项目中?
如何将加密和解密函数应用到实际项目中?
201 138
|
10天前
|
人工智能 Java API
AI 超级智能体全栈项目阶段一:AI大模型概述、选型、项目初始化以及基于阿里云灵积模型 Qwen-Plus实现模型接入四种方式(SDK/HTTP/SpringAI/langchain4j)
本文介绍AI大模型的核心概念、分类及开发者学习路径,重点讲解如何选择与接入大模型。项目基于Spring Boot,使用阿里云灵积模型(Qwen-Plus),对比SDK、HTTP、Spring AI和LangChain4j四种接入方式,助力开发者高效构建AI应用。
390 122
AI 超级智能体全栈项目阶段一:AI大模型概述、选型、项目初始化以及基于阿里云灵积模型 Qwen-Plus实现模型接入四种方式(SDK/HTTP/SpringAI/langchain4j)
|
3天前
|
存储 JSON 安全
加密和解密函数的具体实现代码
加密和解密函数的具体实现代码
202 136
|
22天前
|
弹性计算 关系型数据库 微服务
基于 Docker 与 Kubernetes(K3s)的微服务:阿里云生产环境扩容实践
在微服务架构中,如何实现“稳定扩容”与“成本可控”是企业面临的核心挑战。本文结合 Python FastAPI 微服务实战,详解如何基于阿里云基础设施,利用 Docker 封装服务、K3s 实现容器编排,构建生产级微服务架构。内容涵盖容器构建、集群部署、自动扩缩容、可观测性等关键环节,适配阿里云资源特性与服务生态,助力企业打造低成本、高可靠、易扩展的微服务解决方案。
1361 8
|
8天前
|
监控 JavaScript Java
基于大模型技术的反欺诈知识问答系统
随着互联网与金融科技发展,网络欺诈频发,构建高效反欺诈平台成为迫切需求。本文基于Java、Vue.js、Spring Boot与MySQL技术,设计实现集欺诈识别、宣传教育、用户互动于一体的反欺诈系统,提升公众防范意识,助力企业合规与用户权益保护。