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. 进阶拓展方向 🚀

技术博客与专家观点

相关技术大会

社区与论坛

总结与寄语 🎓

通义大模型

热门文章

最新文章

相关电子书