【Semantic Kernel核心组件】Plugin：连接AI与业务逻辑的桥梁

目录

一、Plugin是什么？为什么它是SK的核心？

一、Plugin的核心机制与Python实现

1. 插件类型：语义函数与本地函数

语义函数（Semantic Function）

本地函数（Native Function）

2. Plugin的注册与调用

二、高级应用：自动化编排（Planner）

智能任务分解示例

三、关键特性详解

1. 参数自动映射机制

2. 安全约束实践

四、调试技巧

1. 查看已注册插件

2. 参数验证日志

五、Python vs C#实现差异

附录代码

mathplugin.py

native_function.py

---

一、Plugin是什么？为什么它是SK的核心？

在Semantic Kernel（SK）框架中，Plugin（插件） 是连接大语言模型（LLM）与确定性代码的核心组件。它通过将自然语言语义与程序函数绑定，实现了从“不确定的AI推理”到“确定性的业务逻辑”的转化。例如，用户可以通过自然语言指令“购买3斤苹果”，触发SK调用后台的库存扣减和支付接口。

Plugin的设计哲学：

• 确定性增强：LLM生成的文本具有不确定性（如“购买水果”可能对应多种操作），而Plugin通过预定义的函数和参数约束，将模糊指令转化为精准动作。

• 模块化复用：每个Plugin可独立开发、测试和部署，支持跨项目复用。例如电商、客服、数据分析等场景可共享通用插件。

---

一、Plugin的核心机制与Python实现

1. 插件类型：语义函数与本地函数

语义函数（Semantic Function）

通过自然语言模板定义意图识别逻辑（需安装 semantic-kernel 包）：

from semantic_kernel.skill_definition import sk_function

class IntentPlugin:
    @sk_function(
        description="根据用户输入判断是否为购买请求",
        name="classify_intent"
    )
    def classify_intent(self, input: str) -> str:
        # 调用LLM进行意图分类
        return "购买请求" if "买" in input else "其他请求"

本地函数（Native Function）

直接操作业务系统（示例含库存管理）：

class InventoryPlugin:
    def __init__(self):
        self.stock = {"苹果": 100, "香蕉": 50}  # 模拟库存

    @sk_function(
        description="从库存中扣除商品数量",
        name="deduct_stock",
        input_description="商品名称和数量, 例如 item='苹果', quantity=2"
    )
    def deduct_stock(self, item: str, quantity: int) -> str:
        if item not in self.stock:
            raise ValueError(f"商品{item}不存在")
        self.stock[item] -= quantity
        return f"库存更新：{item}剩余{self.stock[item]}件"

---

2. Plugin的注册与调用

import semantic_kernel as sk
from semantic_kernel.planning import ActionPlanner

# 初始化Kernel
kernel = sk.Kernel()
kernel.import_skill(IntentPlugin(), "IntentPlugin")
kernel.import_skill(InventoryPlugin(), "InventoryPlugin")

# 自然语言触发插件
async def process_order():
    context = kernel.create_new_context()
    context["input"] = "我要买3斤苹果"
    
    # 步骤1：意图识别
    intent = await kernel.run_async(
        kernel.skills["IntentPlugin"]["classify_intent"],
        input_context=context
    )
    print(intent.result)  # 输出：购买请求
    
    # 步骤2：执行库存操作
    if "购买" in intent.result:
        result = await kernel.run_async(
            kernel.skills["InventoryPlugin"]["deduct_stock"],
            input_context=sk.ContextVariables({"item": "苹果", "quantity": "3"})
        )
        print(result.result)  # 输出：库存更新：苹果剩余97件

# 运行示例
import asyncio
asyncio.run(process_order())

---

二、高级应用：自动化编排（Planner）

智能任务分解示例

# 定义天气预报插件
class WeatherPlugin:
    @sk_function(
        description="获取城市天气",
        name="get_weather"
    )
    def get_weather(self, city: str) -> str:
        # 模拟API调用
        return f"{city}天气：25℃ 晴"

# 注册插件并创建Planner
kernel.import_skill(WeatherPlugin(), "WeatherPlugin")
planner = ActionPlanner(kernel)

# 自动生成执行计划
async def plan_demo():
    goal = "查询北京天气并告诉我库存里还有多少苹果"
    plan = await planner.create_plan_async(goal)
    
    print("生成计划步骤：")
    for step in plan._steps:
        print(f"- {step.description}")
    
    # 执行计划
    result = await plan.invoke_async()
    print("\n执行结果：", result.result)

输出示例：

生成计划步骤：
WeatherPlugin.get_weather
InventoryPlugin.deduct_stock
执行结果：北京天气：25℃ 晴，库存更新：苹果剩余97件

---

三、关键特性详解

1. 参数自动映射机制

# 输入自然语言时自动提取参数
context = sk.ContextVariables("用户说：请买5个香蕉")
result = await kernel.run_async(
    kernel.skills["InventoryPlugin"]["deduct_stock"],
    input_context=context
)
# 自动提取 item="香蕉", quantity=5

2. 安全约束实践

@sk_function(
    description="支付接口",
    name="process_payment",
    input_description="金额必须为1-10000之间的整数"
)
def process_payment(self, amount: int) -> str:
    if not 1 <= amount <= 10000:
        raise ValueError("金额超出允许范围")
    # 调用支付API...

---

四、调试技巧

1. 查看已注册插件

print("已注册插件：", [skill.name for skill in kernel.skills.values()])
# 输出：['IntentPlugin', 'InventoryPlugin', 'WeatherPlugin']

2. 参数验证日志

# 设置调试模式
export LOGLEVEL=DEBUG
# 错误示例：
# ValueError: 商品'橘子'不存在 (当库存无该商品时)

---

五、Python vs C#实现差异

特性	Python实现	C#实现
装饰器语法	@sk_function	[KernelFunction]属性
异步处理	async/await	async/await
类型提示	强制类型注解（如str, int）	强类型参数声明
异常处理	Python原生异常体系	C# Exception类

---

通过Python实现的SK Plugin，开发者可以快速构建以下场景：

• 电商机器人：30行代码实现"购买X个Y商品"的完整链路

• 智能客服：自动路由用户问题到对应处理模块

---

附录代码

mathplugin.py

import math
from semantic_kernel.skill_definition import sk_function

class Math:
        @sk_function(
                description="描述一个平方根",
                name="Sqrt",
                input_description="取平方根"
                )
        def square_root(self,number:str)->str:
                return str(math.sqrt(float(number)))

math_instance=Math()

result=math_instance.square_root("14")
print(f"14的平方根是{result}")

native_function.py

import os
import asyncio
import semantic_kernel as sk
from mathplugin import Math    #导入mathplugin.py中的Math类
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

async def main():
        #1/初始化内核
        kernel=sk.Kernel()

        #2/配置模型服务
        kernel.add_chat_service(
                "chat_completion",
                OpenAIChatCompletion(
                        model_id="qwen-max",
                        api_key=os.getenv("DASHSCOPE_API_KEY"),
                        endpoint="https://dashscope.aliyuncs.com/compatible-mode/v1"
                        )
                
        )

        #3/导入数学插件
        math_plugin=kernel.import_skill(Math(),skill_name="mathplugin")

        #4/调用插件函数
        result=await kernel.run_async(
                math_plugin["Sqrt"],
                input_str="800"
                )
        print(f"800的平方根是{result}")

asyncio.run(main())

运行结果

14的平方根是3.7416573867739413
800的平方根是28.284271247461902