Semantic Kernel 实战系列（一） - 安装与快速入门

在上篇文章中，我介绍了Semantic Kernel（以下简称SK）的整体概念和它在.NET生态中的定位。作为一个专注.NET开发的博主，我特别强调了SK如何与我们熟悉的传统开发模式相结合，比如依赖注入和模块化设计。

今天，我们进入实际操作阶段，这篇是系列的第二篇，焦点是安装和快速入门。我会一步步带你从环境准备开始，到构建第一个简单示例，再到排查常见问题，最后通过一个实践练习让你上手。整个过程会紧密结合传统.NET开发实践，比如如何在Visual Studio中集成SK，或者如何像添加NuGet包一样轻松引入AI能力。

为什么这篇这么重要？因为安装和入门往往是开发者卡壳的地方，尤其是AI框架。传统开发中，我们习惯了稳定的SDK，但AI涉及API密钥和云服务，稍有不慎就报错。我会深入解释每个步骤的原理，让你不只是会用，还理解背后的机制。

❝在项目中，SK不是额外负担，而是像Entity Framework一样，提升效率的工具。实际价值在于落地，比如快速原型一个AI增强的Web API，帮你节省时间。走起！

1 环境准备

安装SK前，先确保你的开发环境就绪。这就像传统.NET项目起步时检查SDK版本一样，避免兼容性问题。SK是Microsoft开源的，所以它完美契合.NET生态，到2025年7月，最新版本已支持.NET 9，但如果你用.NET 8也完全没问题。

首先，安装.NET SDK。推荐至少.NET 8.0，因为SK依赖C#的现代特性如记录类型和异步流。如果你还没安装，去Microsoft官网下载安装器，运行后选“.NET SDK”。在运行原理上，SK用到了.NET的异步编程模型（Task-based），这与传统async/await一致，能无缝处理AI调用延迟。实际价值：用.NET 9，能享受到性能优化，比如更好的垃圾回收，在高负载AI场景下减少卡顿。

接下来，添加NuGet包。SK的核心包是Microsoft.SemanticKernel，当前稳定版是1.60.0。通过Visual Studio的NuGet包管理器搜索安装，或者命令行用dotnet add package Microsoft.SemanticKernel --version 1.60.0。如果你需要特定连接器，如Azure OpenAI，加Microsoft.SemanticKernel.Connectors.AzureOpenAI。SK用NuGet模块化，像传统库一样，你只装需要的部分，避免膨胀项目。这告诉我们，在企业项目中，按需加载，保持轻量。

配置AI服务是关键一步。SK支持多种模型，如Azure OpenAI、OpenAI或Hugging Face。拿Azure OpenAI为例，你需要Azure账号，创建OpenAI资源，获取Endpoint、API Key和Deployment Name。环境变量设置：AZURE_OPENAI_API_KEY=your-key，AZURE_OPENAI_ENDPOINT=your-endpoint，AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment。Hugging Face类似，用HF_API_KEY=your-key。

SK的连接器用HttpClient发请求到AI服务，底层是REST API调用。这与传统Web API消费一样，你可以用IHttpClientFactory注入，优化连接池。在生产环境中，这让SK易于监控，比如加Telemetry追踪请求延迟。

❝想想你的传统CRUD应用，加SK后，用户输入自然语言，就能查询数据库，而非填表单。这转变开发范式，从UI驱动到意图驱动。

如果用本地模型，如Hugging Face的开源LLM，确保安装相关包，并配置本地推理引擎。2025年，SK已优化对ONNX的支持，原理是模型量化减少内存占用，让低端机也能跑AI。

落地建议：在小团队项目中，从Azure起步，成本低（按token计费），后期迁移本地节省钱。

准备好后，验证环境：新建控制台项目，添加包，写个简单Kernel构建代码（下节详解）。如果报错，检查防火墙或代理——AI服务常需互联网。

2 第一个 Hello World 示例

入门示例是构建简单Kernel，调用文本生成模型。这就像传统“Hello World”控制台App，但注入AI智慧。让我们用C#一步步来。

先创建项目：dotnet new console -o SKHelloWorld，cd进去，加包如上。核心代码在Program.cs：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
    deploymentName: Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME"),
    endpoint: Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"),
    apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
);
var kernel = builder.Build();

var chatService = kernel.GetRequiredService<IChatCompletionService>();

var history = new ChatHistory();
history.AddUserMessage("Hello, Semantic Kernel! Tell me a joke about .NET developers.");

var response = await chatService.GetChatMessageContentAsync(history);
Console.WriteLine(response.Content);

运行dotnet run，输出一个笑话。这简单吧？深入原理：Kernel是SK的核心，像.NET的IServiceProvider，构建器用链式API注册服务。AddAzureOpenAIChatCompletion注入聊天完成服务，底层用Azure的API版本（2025年默认2024-10-01）。ChatHistory管理上下文，像传统会话状态，避免每次从零开始。

与传统开发结合：想象在ASP.NET Core中，把Kernel注入Startup.cs的ConfigureServices，然后在控制器用它处理POST请求。实际价值：快速原型聊天机器人，集成到现有Web App，增强用户交互。启发：这鼓励我们设计松耦合系统，Kernel作为中介，模型换了不影响代码。

如果用OpenAI而非Azure，换成builder.AddOpenAIChatCompletion(modelId: "gpt-4o", apiKey: "your-key")。gpt-4o支持多模态（文本+图像），让你扩展到视觉AI。在电商App中，用户上传图片，AI描述产品，减少手动输入。

示例扩展：加提示模板。改成

var prompt = "You are a helpful assistant. {{$input}}"; 
var result = await kernel.InvokePromptAsync(prompt, new() 
{ 
  ["input"] = "Tell me about Semantic Kernel." 
});

原理是Handlebars模板引擎，变量注入像Razor视图。这让提示可复用，像配置文件，易于A/B测试优化AI输出。

3 常见问题排查

安装入门总有坑，这里分享一些常见问题，基于社区反馈。排查像调试传统.NET App，用日志和异常栈。

• API密钥无效：报401 Unauthorized。检查环境变量拼写，或密钥过期。Azure密钥每月轮换，原因是安全最佳实践，像JWT token。可以使用dotnet user-secrets存储密钥来解决问题，避免硬编码。在CI/CD中，安全注入密钥，防泄露。
• 代理设置问题：企业网常需代理。SK用系统HttpClient，默认继承代理，但有时失败。加HttpClientHandler.UseProxy = true;自定义Handler。SK的连接器继承HttpClientFactory，原理是连接复用减少开销。这提醒我们，AI不是孤岛，要考虑网络环境，像传统微服务。
• 版本兼容性：用旧.NET 7可能报错，SK要求.NET 8+的特性如required成员。升级SDK，或检查NuGet版本冲突。2025年，SK 1.60.0兼容.NET 9的AOT编译，原理是提前编译提升启动速。在Serverless如Azure Functions，用AOT减少冷启动，优化成本。
• 模型部署名不对：Azure报404。确认Deployment Name匹配Azure门户。原理是部署是模型实例，像虚拟机规格。用gpt-3.5-turbo而非gpt-4o。测试多种模型，选性价比高的，比如小模型本地跑，大模型云端。
• 其他：令牌超限报错，加ExecutionSettings限制MaxTokens。日志用ILogger注入Kernel，追踪调用。在生产，集成AppInsights监控，预测问题。

4 集成开发工具

在Visual Studio扩展：搜“Semantic Kernel Tools”，安装后有模板创建SK项目。原理是VS插件API，添加项目向导。实际：一键生成Kernel配置，节省 boilerplate。用IntelliSense补全提示，像写LINQ，提升效率。

Jupyter Notebook：加Microsoft.SemanticKernel.Notebooks包，用dotnet-interactive。创建.ipynb，写C# cell加载Kernel。示例：

#r "nuget: Microsoft.SemanticKernel, 1.60.0"

using Microsoft.SemanticKernel;

var kernel = Kernel.CreateBuilder().Build();
// 后续代码

原理是Polyglot Notebook，支持交互式实验提示。在数据分析项目，用Notebook原型AI，然后迁到生产App。2025年，VS Code的Jupyter扩展更强，结合GitHub Copilot加速。

其他工具：Postman测试API密钥，Azure门户监控使用。工具链像DevOps，SK集成CI/CD，自动化测试AI输出。

5 实践练习

最后，构建基本聊天代理。创建控制台App，加包。完整代码：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using System;

var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(/* 配置 */);
var kernel = builder.Build();
var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory("You are a friendly .NET expert.");

while (true)
{
    Console.Write("User: ");
    var input = Console.ReadLine();
    if (input == "exit") break;
    history.AddUserMessage(input);
    var response = await chatService.GetChatMessageContentAsync(history);
    Console.WriteLine($"AI: {response.Content}");
    history.AddAssistantMessage(response.Content);
}

运行，聊天关于.NET。ChatHistory保持状态，像Session in ASP.NET。扩展到Blazor App，做实时聊天UI。

后续大家可以试试加插件调用天气API。从简单起步，迭代复杂代理。

总结，这篇让你从零上手SK，结合传统开发落地AI。下篇聊核心概念，敬请期待！