7个实战技巧！解决微软语义内核（Semantic Kernel）90%的常见问题

一、初识微软语义内核（Semantic Kernel）

微软语义内核（Semantic Kernel，简称SK）是一个与模型无关的SDK，能让开发者轻松构建、编排和部署AI智能体及多智能体系统。无论是简单的聊天机器人，还是复杂的多智能体工作流，SK都能提供企业级的可靠性和灵活性。

系统要求：

• Python: 3.10+
• .NET: .NET 8.0+
• Java: JDK 17+
• OS Support: Windows, macOS, Linux

核心功能包括模型灵活性、智能体框架、多智能体系统、插件生态系统、向量数据库支持等。更多详细信息可查看README.md。

二、安装与环境配置问题

2.1 安装命令

Python:

pip install semantic-kernel

.NET:

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

2.2 API密钥配置

Azure OpenAI:

export AZURE_OPENAI_API_KEY=AAA....

或OpenAI直接:

export OPENAI_API_KEY=sk-...

2.3 身份验证错误

如果遇到身份验证错误，请检查API密钥环境变量是否正确设置。确保密钥没有过期，并且具有适当的权限。

三、插件使用问题

插件（Plugins）是特定领域的功能集合，作为一组精细调整的函数提供给SK使用。有两种主要类型的函数：

• 原生函数（Native Function）：用传统计算语言（C#、Python、Typescript）表达，可轻松与SK集成
• 语义函数（Semantic Function）：在文本文件"skprompt.txt"中用自然语言表达，使用SK的Prompt Template language

3.1 自定义插件示例

Python:

class MenuPlugin:
    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

3.2 导入插件

kernel.Plugins.Add(KernelPluginFactory.CreateFromType<MenuPlugin>());

四、内存与嵌入问题

内存（Memory） 是语义知识的集合，基于事实、事件、文档，使用**嵌入（Embeddings）** 建立索引。

嵌入是人工智能和自然语言处理领域的强大工具，它允许计算机以更复杂的方式理解词语的含义，将词语表示为高维向量而非简单的字符字符串。

4.1 使用TextMemoryPlugin

var memory = new MemoryBuilder()
    .WithChromaMemoryStore("https://chroma-endpoint")
    .WithOpenAITextEmbeddingGeneration("text-embedding-ada-002", "api-key")
    .Build();

kernel.ImportPluginFromObject(new TextMemoryPlugin(memory));

var result = await kernel.InvokePromptAsync("{{recall 'Company budget by year'}} What is my budget for 2024?");

五、RAG模式实现问题

检索增强生成（RAG）是一种结合信息检索和生成式AI的技术。在SK中实现RAG有多种方式：

5.1 提示拼接法

var kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("model-id", "api-key")
    .Build();

// 用户负责以自己选择的方式搜索数据，这是一个示例
var data = await this._vectorDB.SearchAsync("Company budget by year");

var arguments = new KernelArguments { ["budgetByYear"] = data };

var result = await kernel.InvokePromptAsync("{{budgetByYear}} What is my budget for 2024?", arguments);

5.2 内存插件法

var kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("model-id", "api-key")
    .Build();

var memory = new MemoryBuilder()
    .WithChromaMemoryStore("https://chroma-endpoint")
    .WithOpenAITextEmbeddingGeneration("text-embedding-ada-002", "api-key")
    .Build();

kernel.ImportPluginFromObject(new TextMemoryPlugin(memory));

var result = await kernel.InvokePromptAsync("{{recall 'Company budget by year'}} What is my budget for 2024?");

更多RAG实现方法请参考0034-rag-in-sk.md。

六、智能体创建与使用

6.1 基本智能体 - Python

import asyncio
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

async def main():
    # 使用基本指令初始化聊天智能体
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="You are a helpful assistant.",
    )

    # 获取对用户消息的响应
    response = await agent.get_response(messages="Write a haiku about Semantic Kernel.")
    print(response.content)

asyncio.run(main()) 

6.2 带插件的智能体

class MenuPlugin:
    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"

七、获取夜间构建版本

夜间构建版本可通过以下步骤获取：

1. 您需要一个GitHub账户来完成这些步骤。
2. 创建具有read:packages作用域的GitHub个人访问令牌。
3. 如果您的账户属于Microsoft组织，则必须授权Microsoft组织作为单点登录组织。
4. 使用以下命令将Microsoft GitHub Packages源添加到您的NuGet配置：

dotnet nuget add source --username GITHUBUSERNAME --password GITHUBPERSONALACCESSTOKEN --store-password-in-clear-text --name GitHubMicrosoft "https://nuget.pkg.github.com/microsoft/index.json"

更多详细信息请参考FAQS.md。

八、获取帮助与资源

如果遇到其他问题，可以通过以下方式获取帮助：

• 查看我们的GitHub issues了解已知问题
• 在Discord社区搜索解决方案
• 提问时请包含您的SDK版本和完整错误消息

详细文档和API参考：

• 概念文档
• C# API参考
• Python API参考

希望本文能帮助您解决使用微软语义内核（Semantic Kernel）时遇到的常见问题。如有其他疑问，欢迎在社区中提问交流！