第一个应用 #

概述 #

本节将带你创建第一个 Semantic Kernel 应用，通过一个简单的示例了解：

如何创建 Kernel
如何配置 AI 服务
如何执行提示词
如何处理返回结果

C# 版本 #

1. 创建基础应用 #

csharp

using Microsoft.SemanticKernel;

// 创建 Kernel 构建器
var builder = Kernel.CreateBuilder();

// 添加 OpenAI 聊天服务
builder.AddOpenAIChatCompletion(
    modelId: "gpt-4",
    apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!
);

// 构建 Kernel
var kernel = builder.Build();

// 执行简单提示词
var result = await kernel.InvokePromptAsync("你好，请用一句话介绍自己");

// 输出结果
Console.WriteLine(result);

2. 运行结果 #

text

你好！我是一个 AI 助手，致力于帮助用户解决问题、提供信息和支持。

3. 完整示例代码 #

csharp

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

var builder = Kernel.CreateBuilder();

// 方式一：使用 OpenAI
builder.AddOpenAIChatCompletion(
    modelId: "gpt-4o-mini",
    apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!
);

// 方式二：使用 Azure OpenAI
// builder.AddAzureOpenAIChatCompletion(
//     deploymentName: "gpt-4",
//     endpoint: Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!,
//     apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")!
// );

var kernel = builder.Build();

Console.WriteLine("=== Semantic Kernel 第一个应用 ===\n");

// 示例 1：简单提示词
Console.WriteLine("示例 1：简单提示词");
var result1 = await kernel.InvokePromptAsync("什么是 Semantic Kernel？用一句话回答");
Console.WriteLine($"结果：{result1}\n");

// 示例 2：带参数的提示词
Console.WriteLine("示例 2：带参数的提示词");
var arguments = new KernelArguments
{
    ["topic"] = "人工智能",
    ["language"] = "中文"
};
var result2 = await kernel.InvokePromptAsync(
    "请用{{$language}}写一段关于{{$topic}}的简短介绍",
    arguments
);
Console.WriteLine($"结果：{result2}\n");

// 示例 3：获取更多信息
Console.WriteLine("示例 3：获取更多信息");
var result3 = await kernel.InvokePromptAsync("列举三种编程语言的名称");
Console.WriteLine($"结果：{result3}");

// 获取 token 使用情况
var usage = result3.Metadata?["Usage"] as Dictionary<string, object>;
if (usage != null)
{
    Console.WriteLine($"Prompt Tokens: {usage["PromptTokens"]}");
    Console.WriteLine($"Completion Tokens: {usage["CompletionTokens"]}");
    Console.WriteLine($"Total Tokens: {usage["TotalTokens"]}");
}

Console.WriteLine("\n应用执行完成！");

Python 版本 #

1. 创建基础应用 #

python

import asyncio
import os
import semantic_kernel as sk
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

async def main():
    # 创建 Kernel
    kernel = sk.Kernel()
    
    # 添加 OpenAI 服务
    kernel.add_service(OpenAIChatCompletion(
        service_id="gpt-4",
        ai_model_id="gpt-4o-mini",
        api_key=os.getenv("OPENAI_API_KEY")
    ))
    
    # 执行简单提示词
    result = await kernel.invoke_prompt("你好，请用一句话介绍自己")
    
    # 输出结果
    print(result)

asyncio.run(main())

2. 运行结果 #

text

你好！我是一个 AI 助手，致力于帮助用户解决问题、提供信息和支持。

3. 完整示例代码 #

python

import asyncio
import os
import semantic_kernel as sk
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.contents.chat_history import ChatHistory

async def main():
    # 创建 Kernel
    kernel = sk.Kernel()
    
    # 添加 OpenAI 服务
    kernel.add_service(OpenAIChatCompletion(
        service_id="gpt-4",
        ai_model_id="gpt-4o-mini",
        api_key=os.getenv("OPENAI_API_KEY")
    ))
    
    print("=== Semantic Kernel 第一个应用 ===\n")
    
    # 示例 1：简单提示词
    print("示例 1：简单提示词")
    result1 = await kernel.invoke_prompt("什么是 Semantic Kernel？用一句话回答")
    print(f"结果：{result1}\n")
    
    # 示例 2：带参数的提示词
    print("示例 2：带参数的提示词")
    result2 = await kernel.invoke_prompt(
        "请用{{$language}}写一段关于{{$topic}}的简短介绍",
        language="中文",
        topic="人工智能"
    )
    print(f"结果：{result2}\n")
    
    # 示例 3：多轮对话
    print("示例 3：多轮对话")
    chat = ChatHistory()
    chat.add_user_message("你好，我叫小明")
    chat.add_user_message("你还记得我的名字吗？")
    
    result3 = await kernel.invoke_prompt("{{chat}}", chat=chat)
    print(f"结果：{result3}\n")
    
    print("应用执行完成！")

asyncio.run(main())

代码解析 #

核心流程 #

text

┌─────────────────────────────────────────────────────────────┐
│                    应用执行流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 创建 Kernel                                             │
│     ┌─────────────────────────────────────────────────┐    │
│     │  var builder = Kernel.CreateBuilder();          │    │
│     │  builder.AddOpenAIChatCompletion(...);          │    │
│     │  var kernel = builder.Build();                  │    │
│     └─────────────────────────────────────────────────┘    │
│                            │                                │
│                            ▼                                │
│  2. 准备提示词                                              │
│     ┌─────────────────────────────────────────────────┐    │
│     │  var prompt = "你好，请介绍自己";                │    │
│     │  var arguments = new KernelArguments {...};     │    │
│     └─────────────────────────────────────────────────┘    │
│                            │                                │
│                            ▼                                │
│  3. 执行调用                                                │
│     ┌─────────────────────────────────────────────────┐    │
│     │  var result = await kernel.InvokePromptAsync(); │    │
│     └─────────────────────────────────────────────────┘    │
│                            │                                │
│                            ▼                                │
│  4. 处理结果                                                │
│     ┌─────────────────────────────────────────────────┐    │
│     │  Console.WriteLine(result);                     │    │
│     │  var metadata = result.Metadata;                │    │
│     └─────────────────────────────────────────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Kernel 创建详解 #

csharp

// Kernel 是 Semantic Kernel 的核心
// 它管理所有服务和插件的协调

var builder = Kernel.CreateBuilder();

// 添加 AI 服务（至少需要一个）
builder.AddOpenAIChatCompletion(
    modelId: "gpt-4",           // 模型 ID
    apiKey: "your-api-key",      // API 密钥
    orgId: "your-org-id"         // 组织 ID（可选）
);

// 可以添加多个服务
builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4",
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: "your-azure-key"
);

// 构建不可变的 Kernel 实例
var kernel = builder.Build();

提示词执行详解 #

csharp

// 方式 1：直接执行简单提示词
var result = await kernel.InvokePromptAsync("你的问题");

// 方式 2：带参数的提示词
var arguments = new KernelArguments
{
    ["name"] = "小明",
    ["age"] = 25
};
var result = await kernel.InvokePromptAsync(
    "你好，{{$name}}，你今年{{$age}}岁",
    arguments
);

// 方式 3：指定服务 ID（当有多个服务时）
var result = await kernel.InvokePromptAsync(
    "你的问题",
    arguments,
    serviceName: "gpt-4"
);

结果处理详解 #

csharp

// 获取字符串结果
string text = result.ToString();

// 获取完整结果对象
var functionResult = result;

// 获取元数据
var metadata = result.Metadata;
if (metadata != null)
{
    // Token 使用情况
    var usage = metadata["Usage"];
    
    // 模型 ID
    var modelId = metadata["ModelId"];
    
    // 完成原因
    var finishReason = metadata["FinishReason"];
}

// 获取原始响应
var rawResponse = result.GetValue<object>();

进阶示例 #

使用设置参数 #

csharp

using Microsoft.SemanticKernel.Connectors.OpenAI;

var executionSettings = new OpenAIPromptExecutionSettings
{
    MaxTokens = 500,
    Temperature = 0.7,
    TopP = 0.9,
    FrequencyPenalty = 0.5,
    PresencePenalty = 0.5
};

var arguments = new KernelArguments(executionSettings)
{
    ["topic"] = "机器学习"
};

var result = await kernel.InvokePromptAsync(
    "写一篇关于{{$topic}}的短文",
    arguments
);

错误处理 #

csharp

try
{
    var result = await kernel.InvokePromptAsync("你的问题");
    Console.WriteLine(result);
}
catch (HttpOperationException ex)
{
    Console.WriteLine($"HTTP 错误: {ex.StatusCode}");
    Console.WriteLine($"响应内容: {ex.ResponseContent}");
}
catch (KernelException ex)
{
    Console.WriteLine($"Kernel 错误: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"未知错误: {ex.Message}");
}

异步流式输出 #

csharp

await foreach (var chunk in kernel.InvokePromptStreamingAsync("写一首诗"))
{
    Console.Write(chunk);
}

运行应用 #

C# 运行 #

bash

# 设置环境变量
export OPENAI_API_KEY=your-api-key

# 运行应用
dotnet run

Python 运行 #

bash

# 设置环境变量
export OPENAI_API_KEY=your-api-key

# 运行应用
python main.py

常见问题 #

Q1: API Key 无效 #

text

错误信息：Invalid API Key
解决方案：
1. 检查 API Key 是否正确复制
2. 确认 API Key 未过期
3. 检查环境变量是否正确设置

Q2: 网络连接失败 #

text

错误信息：Connection refused
解决方案：
1. 检查网络连接
2. 配置代理（如需要）
3. 检查防火墙设置

Q3: 模型不存在 #

text

错误信息：Model not found
解决方案：
1. 确认模型 ID 正确
2. 检查账户是否有权限访问该模型
3. Azure OpenAI 需要确认部署名称

下一步 #

恭喜你完成了第一个 Semantic Kernel 应用！接下来学习核心概念，深入了解 Semantic Kernel 的架构设计。