.NET AI从0开始入门 SemanticKernel 从基础到实践

引言

本教程将带你全面了解SemanticKernel，一款强大的AI开发工具包。以下内容基于实际代码示例，帮助你快速掌握使用技巧。

资源链接：

• 教程代码仓库：https://github.com/AIDotNet/SemanticKernel.Samples
• QQ交流群：961090189
• 微信交流群（加微）：wk28u9123456789
• 飞书交流群：点击加入
• 原文地址：https://ycnv7u8vf1o3.feishu.cn/docx/WezYdjrckoqhU3xNXbEcL3Ubn2b?from=from_copylink

一、SemanticKernel简介

SemanticKernel是一种轻型开源开发工具包，可用于轻松生成AI代理并将最新的AI模型集成到C#、Python或Java代码库中。它充当一个高效的中间件，可实现企业级解决方案的快速交付。

作为连接AI模型与传统编程的桥梁，SemanticKernel让你可以：

• 无缝集成OpenAI、Azure OpenAI和Hugging Face等LLM服务
• 将AI能力与传统编程逻辑和外部服务结合
• 构建复杂的AI工作流，解决实际业务问题

SemanticKernel的核心理念

SemanticKernel建立在几个关键概念之上：

1. 插件（Plugins）架构

SemanticKernel的插件系统是其最强大的特性之一。这些插件有两种主要类型：

• 语义函数（Semantic Functions）：使用自然语言指令（提示词）定义的函数，由AI模型执行
• 原生函数（Native Functions）：使用传统编程语言（如C#、Python、Java等）编写的函数

这种双重架构允许开发者创建混合解决方案，在需要精确控制的地方使用传统代码，在需要创造性和灵活性的地方使用AI能力。

2. Memory与Planner

SemanticKernel提供了先进的Memory和Planner组件：

• SemanticKernelMemory：使应用能够存储和检索信息，实现类似长期记忆的功能
• Planner：可以自动将复杂任务分解为更小的步骤，并安排它们的执行顺序

3. 可组合性

SemanticKernel的设计鼓励组件重用和组合，使开发者能够：

• 将简单功能组合成更复杂的工作流
• 创建可复用的插件库
• 构建模块化且可扩展的AI应用架构

实际应用案例

SemanticKernel在各种场景中展现出强大的实用价值：

• 内容创作助手：自动生成、总结和修改文本内容
• 个人知识管理：智能组织和检索文档与知识
• 客户服务自动化：构建能理解客户需求并提供个性化帮助的智能系统
• 数据分析辅助：将自然语言查询转换为数据查询，并生成见解报告
• 流程自动化：创建能理解非结构化数据并执行复杂任务的智能工作流

技术优势

SemanticKernel相比其他AI开发框架具有几个独特优势：

1. 语言灵活性：支持C#、Python、Java
2. 开放生态：与多种LLM提供商兼容，避免供应商锁定
3. 企业级支持：作为微软项目，具备企业级质量和支持
4. 社区活跃：拥有活跃的开发者社区，持续改进和扩展
5. 低入门门槛：允许开发者渐进式采用AI功能，无需一步到位

入门指南

如果你想开始使用SemanticKernel，可以按照以下步骤：

1. 安装SDK：根据你选择的编程语言安装相应的SemanticKernel SDK
2. 配置AI模型：连接到OpenAI、Azure OpenAI等LLM服务
3. 创建插件：定义语义函数和原生函数
4. 构建工作流：将函数组合成解决特定问题的工作流
5. 集成到应用：将SemanticKernel集成到你的应用程序中

二、SemanticKernel入门篇

1. 快速开始第一个示例

获取OpenAI在线API

由于在国内的限制，我们并没有办法直接访问OpenAI，所以下面的教程我们会推荐使用 https://api.token-ai.cn，然后您需要在这个网站中注册一个账号，并且创建一个令牌（最好是设置无限额度和无过期时间），创建好的令牌我们保存好，下面的基础教程入门会用到，这个令牌是用于代替OpenAI的原有的令牌。

创建项目

• 打开Visual Studio 2022，然后创建一个名称为TokenAI的控制台项目
  

• 右键新建的项目，然后点击管理 NuGet 程序包
  

• 搜索Semantic Kernel,并且选择包括预览版，然后选择安装Microsoft.SemanticKernel，
  

• 实现Stream式对话输出

打开Program.cs，输入以下代码：

using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0010

var kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("gpt-4.1-mini", new Uri("https://api.token-ai.cn/v1"),
        "您的密钥")
    .Build();

await foreach (var item in kernel.InvokePromptStreamingAsync("您好，我是TokenAI"))
{
    Console.Write(item.ToString());
};

执行效果：

我们使用Kernel的CreateBuilder创建了一个Kernel对象，并且在这个对象中存在InvokePromptStreamingAsync方法，这个方法提供了OpenAI的一个Stream的对话接口,并且我们添加了AddOpenAIChatCompletion添加了自定义的模型和我们的代理网站的key地址。

2. 使用聊天完成对话示例

首先给我们的控制台项目安装SK包

dotnet add package Microsoft.SemanticKernel

然后我们构建一个简单的Kernel，和ChatCompletion：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;

#pragma warning disable SKEXP0010

var kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("gpt-4o", new Uri("https://api.token-ai.cn/v1"),
        "您的密钥")
    .Build();

var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
ChatHistory history = [];

history.AddUserMessage("Hello, how are you?");

// 使用同步对话
var response = await chatCompletionService.GetChatMessageContentAsync(
    history,
    kernel: kernel
);

Console.WriteLine(response.Content);


// 使用异步对话
await foreach (var item in chatCompletionService.GetStreamingChatMessageContentsAsync(
                   history,
                   kernel: kernel
               ))
{
    Console.Write(item.Content);
}

效果如图，同步对话会一次性返回，异步对话会一点点返回，适合不同场景的对话，同步对话完整的响应会更快，但是复杂的业务可能等待很长时间导致请求超时，所以不同场景使用不同模式。

3. 开始使用Plugins

创建项目

首先给我们的控制台项目安装SK包

dotnet add package Microsoft.SemanticKernel

接下来，我们将：

1. 构建好我们的Kernel
2. 创建TimeInformation的一个Plugins并且提供了一个获取当前时间的Function
3. 构建俩个对话案例，用于区分使用了Function和没有使用function的区别

using System.ComponentModel;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

#pragma warning disable SKEXP0010

var kernelBuilder = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("gpt-4.1-mini", new Uri("https://api.token-ai.cn/v1"),
        "您的密钥");

kernelBuilder.Plugins.AddFromType<TimeInformation>();

var kernel = kernelBuilder.Build();

// 用提示符调用SK，要求AI提供它无法提供的信息，并可能产生幻觉
Console.WriteLine(await kernel.InvokePromptAsync("离圣诞节还有几天？"));

OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() };

// 用提示符调用内核，并允许AI自动调用函数
Console.WriteLine(await kernel.InvokePromptAsync("离圣诞节还有几天？解释你的想法", new(settings)));

class TimeInformation
{
    [KernelFunction]
    [Description("获取当前时间帮助用户解决时区不准确。")]
    public string GetCurrentUtcTime() => DateTime.UtcNow.ToString("R");
}

执行控制台得到如下效果：

今天是2024年4月27日，离圣诞节（12月25日）还有242天。
今天是2025年4月27日，距离圣诞节（12月25日）还有大约8个月，即大约242天左右。因此，现在离圣诞节还有很多天。

第一条内容是没有执行function得到的结果，完全不准确。

第二条内容是执行了function的结果，得到了当前时间得到了准确的结果。

结论

通过以上步骤，我们可以看到：

• 没有执行函数时，AI生成的回答不准确，无法提供实际的时间信息。
• 执行函数后，AI能够准确获取当前时间，并提供相应的计算结果。

4. 创建Yaml格式的提示词模板

这一篇的教程我们将讲解如何定义yaml格式的提示词模板并且使用，下面我们需要安装一下俩个包：

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Yaml

创建目录Resources在目录下创建GenerateStory.yaml文件，然后打开文件：

name: GenerateStory
template: |
  将一个关于 {{$topic}} 的故事生成一个长度为 {{$length}} 的故事。
template_format: semantic-kernel
description: 生成关于某个主题的故事的函数。
input_variables:
  - name: topic
    description: 故事的主题。
    is_required: true
  - name: length
    description: 故事中的句子数。
    is_required: true
output_variable:
  description: 生成的故事。
execution_settings:
  default:
    temperature: 0.6

这个是一个生成故事的提示词模板，里面提供了topic和length俩个参数，并且使用{{$topic}}的格式插入到模板中。

然后我们还需要将GenerateStory.yaml文件设置成嵌入资源，将下面配置复制到项目当中：

<ItemGroup>
  <None Remove="Resources\GenerateStory.yaml" />
  <EmbeddedResource Include="Resources\GenerateStory.yaml" />
</ItemGroup>

然后还需要创建一个读取嵌入资源的方法，创建EmbeddedResource.cs，打开文件：

/// <summary>
/// 提供从程序集中读取嵌入资源的功能。
/// 此类设计用于访问嵌入在同一程序集中的基于文本的资源。
/// 它根据名称检索指定资源文件的内容，并将其作为字符串返回。
/// </summary>
public static class EmbeddedResource
{
    private static readonly string? s_namespace = typeof(EmbeddedResource).Namespace;

    internal static string Read(string fileName)
    {
        // Get the current assembly. Note: this class is in the same assembly where the embedded resources are stored.
        Assembly assembly =
            typeof(EmbeddedResource).GetTypeInfo().Assembly ??
            throw new InvalidOperationException($"[{s_namespace}] {fileName} assembly not found");

        // Resources are mapped like types, using the namespace and appending "." (dot) and the file name
        var resourceName = $"{s_namespace}." + fileName;
        using Stream resource =
            assembly.GetManifestResourceStream(resourceName) ??
            throw new InvalidOperationException($"{resourceName} resource not found");

        // Return the resource content, in text format.
        using var reader = new StreamReader(resource);

        return reader.ReadToEnd();
    }
}

现在可以打开我们的Program.cs：

using Microsoft.SemanticKernel;
using Samples4;

#pragma warning disable SKEXP0010

var kernelBuilder = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("gpt-4.1-mini", new Uri("https://api.token-ai.cn/v1"),
        "您的密钥");
        
var kernel = kernelBuilder.Build();


var generateStoryYaml = EmbeddedResource.Read("Resources.GenerateStory.yaml");
var function = kernel.CreateFunctionFromPromptYaml(generateStoryYaml);

// Invoke the prompt function and display the result
Console.WriteLine(await kernel.InvokeAsync(function, arguments: new()
{
    { "topic", "Dog" },
    { "length", "3" },
}));

实现步骤：

1. 构建Kernel
2. 通过EmbeddedResource.Read读取嵌入的yaml模板，通过CreateFunctionFromPromptYaml创建function
3. 使用InvokeAsync进行调用function，构建KernelArguments传递参数

执行项目得到结果：

从前，有一只聪明的小狗。  
它每天帮助主人找回丢失的东西。  
最终，它成了村里最受欢迎的狗狗。

结论

通过上面案例我们了解了如何定义yaml的提示词模板，并在SemanticKernel中使用它来创建和调用函数。这种方法使得提示词管理更加结构化和可维护。

总结

本教程介绍了SemanticKernel的基础知识和核心概念，并通过四个实际示例展示了如何在C#中使用SemanticKernel：

1. 快速入门示例 - 实现流式对话输出
2. 使用聊天完成功能 - 同步和异步对话模式
3. 使用Plugins扩展AI能力 - 通过函数调用增强准确性
4. 创建Yaml格式提示词模板 - 更结构化地管理提示词

通过这些示例，你应该已经掌握了SemanticKernel的基本用法，可以开始构建自己的AI增强应用程序。