使用 C# 和 Semantic Kernel 打造 AI 應用：第二章 - 深入 Plugins

前言

在上一章中，我們初探了 Semantic Kernel 的核心概念，並學習如何透過 Kernel 輕鬆地將 AI 服務整合到你的 C# 應用程式中。我們看到了 AI 基礎能力的強大，也理解到單靠 LLM 本身的知識庫仍有其限制。

這個限制，正是本章將要解決的核心問題。

想像一下，如果 AI 不僅能回答你提出的問題，還能執行更複雜的任務，例如：查詢即時的天氣、從資料庫中提取特定資訊，或是自動發送一封電子郵件。這將大大提升 AI 的應用潛力。

Semantic Kernel 提供了強大的 Plugins（插件） 機制，就像為你的 AI 助理裝備了一整個「工具箱」，讓它不再只是個知識淵博的大腦，更能動手執行任務，成為能解決現實問題的超能力者。
本章，我們將深入探索 Plugins 的世界，從最基礎的內建函數 (Native Functions) 開始，手把手帶你學習如何創建和使用自己的工具，並進一步了解如何透過檔案式提示 (File-based Prompts)，將 AI 的能力提升到一個全新的層次。

Using a Function with a Complex Type Parameter and Return Type

以下我們就來建立一個包含地點及日期的參數，做為查詢天氣預報的參數，試看看 LLM 是否能順利地從使用者的問題中，取出合適的參數來呼叫天氣預報的 Function ，如下:

using Microsoft.SemanticKernel;
using System.ComponentModel;


public class WeatherPlugin
{
    private static readonly string[] Conditions = { "晴天","多雲","下雨", "豪雨" };
    private static readonly Random Random = new Random();


    [KernelFunction]
    [Description("取得特定日期及特定地點的天氣預測")]
    public string GetWeatherForecastForLocationAndDate([Description("取得特定日期及特定地點的天氣預測的參數")] WeatherRequest weatherRequest)
    {
        var condition = Conditions[Random.Next(Conditions.Length)];
        var highTemp = Random.Next(0, 40);
        var lowTemp = Random.Next(10, 20);

        return $"在 {weatherRequest.Date.ToShortDateString()}，{weatherRequest.Location} 的天氣預測是 {condition}，氣溫方面最高 {highTemp}°F，最低 {lowTemp}°F。";
    }
}

public class WeatherRequest
{
    [Description("查詢天氣的地點")]
    public string Location { get; set; }

    [Description("查詢天氣的日期")]
    public DateTime Date { get; set; }
}

然後在 Kernel 中註冊這個 Plugin 後，詢問今2024/9/1 在台中的天氣如何?，如下:

using Microsoft.SemanticKernel;
using System.Text;

var apikey = "你的 openai api key";
var modelId = "gpt-4.1";
// 建立 KernelBuilder
var kernelBuilder = Kernel.CreateBuilder();
// 加入 OpenAI ChatCompletion 服務
var kernel = kernelBuilder
            .AddOpenAIChatCompletion(modelId, apikey)
            .Build();
// 註冊 plugin
kernel.ImportPluginFromType<WeatherPlugin>();
OpenAIPromptExecutionSettings settings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
Console.OutputEncoding = UTF8Encoding.UTF8;
Console.InputEncoding = UTF8Encoding.UTF8;
// 直接輸出結果
Console.WriteLine(await kernel.InvokePromptAsync("今2024/9/1 在台中的天氣如何?", new(settings)));

在 GetWeatherForecastForLocationAndDate Method 設定中斷點，可以看到 LLM 從使用者的問題中取出地點及日期組成WeatherRequest參數傳到 Method 之中，如下圖:

Built-in Plugins

Semantic kernel 核心的 Plugin 包含Time plugin、HTTP plugin、FileIO plugin、ConversationSummary plugin及Text plugin等等，
想知道更多，可以查看 Semantic kernel Plugins

1.加入 Microsoft.SemanticKernel.Plugins.Core Nuget 套件(preview)

2.使用ConversationSummary plugin， 整理一下對話內容，如下，

using Microsoft.SemanticKernel;
using System.Text;
using Microsoft.SemanticKernel.Plugins.Core;

var apikey = "你的 openai api key";
var modelId = "gpt-4.1";
// 建立 KernelBuilder
var kernelBuilder = Kernel.CreateBuilder();
// 加入 OpenAI ChatCompletion 服務
var kernel = kernelBuilder
            .AddOpenAIChatCompletion(modelId, apikey)
            .Build();
// 註冊 plugin
kernel.ImportPluginFromType<ConversationSummaryPlugin>();
OpenAIPromptExecutionSettings settings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
Console.OutputEncoding = UTF8Encoding.UTF8;
Console.InputEncoding = UTF8Encoding.UTF8;
var chatTranscript = """
George：Mary，我在想我們是不是應該跟銀行借點錢來擴大生意。

Mary：嗯，我也有這個想法。不過你打算借多少？

George：大概新台幣兩百萬，主要是要添購新的設備。

Mary：兩百萬不算小數目，你覺得我們的還款能力足夠嗎？

George：以目前的營收，加上新設備帶來的產能，應該能在五年內還清。

Mary：那利率部分你有查過嗎？現在銀行大概是年利率 2.5% 到 3%。

George：我看過一些資料，如果有公司財報跟資產擔保，應該可以談到 2.2% 左右。

Mary：聽起來不錯，但我們還需要準備好貸款計畫書，銀行才會比較容易審核。

George：對，我打算先整理最近三年的財務報表，還有未來三年的營運計畫。

Mary：好，那我來準備市場分析的部分，讓銀行看到我們成長的潛力。

George：太好了！等資料都準備好，我們就一起去銀行洽談吧。
""";
Console.WriteLine(await kernel.InvokePromptAsync($"請總結以下的對話內容，{chatTranscript}", new(settings)));

輸出結果如下:

File-based Prompt Functions(prompt plugin)

prompt plugin 包含 skprompt.txt 及 config.json
skprompt.txt: prompt 的內容(可包含變數)
config.json: prompt 的描述、執行的設定及變數的說明
以下使用人民陳情公文生成的例子來測試，找到相似的公文來生成來依使用者的陳情內容來生成新的公文，如下: 1.建立Prompts\ComposeGovDoc目錄

2.在目錄中新增skprompt.txt

你是台灣政府機關的公文撰擬專家，需根據人民陳情與過往相似公文，產出正式可用的「{{$doc_type}}」。

【輸入資料】
- 陳情內容：
{{$user_complaint}}

- 檢索到的相似公文片段（供參考，避免照抄，需改寫與去個資）：
{{$similar_examples}}

【寫作規範】
1. 採用台灣公文常用結構：「主旨／說明／辦法」。
2. 用語正式、精簡、條列清楚；避免口語與情緒性文字。
3. 優先參考相似公文的處理邏輯，但需以本案事實改寫；不可捏造未提供的事證。
4. 有缺資料時，以「請查明…」、「請會同…」等措辭引導，勿編造細節。
5. 保護個資：姓名、電話、住址等以「[個資已遮蔽]」表述。
6. 若涉及工務、照明、交通等，務必指明承辦單位（如：{{$target_agency}}）與回覆時程（例如：{{$deadline_days}}日內）。
7. 產出兩個部分：
   A) JSON（機器可讀結構）
   B) 正式正文（人工可讀）

【JSON 輸出格式】（請只輸出有效 JSON 物件，不要加註解）
{
  "doc_type": "{{$doc_type}}",
  "subject": "…（一句話說明主旨）",
  "facts": [
    "…（歸納已知事實1）",
    "…（歸納已知事實2）"
  ],
  "actions": [
    "…（應辦事項1）",
    "…（應辦事項2）"
  ],
  "target_agency": "{{$target_agency}}",
  "deadline_days": {{$deadline_days}},
  "legal_basis": ["…（如有法源依據，無則留空陣列）"]
}

【正文輸出格式】
主旨：……。
說明：
一、……。
二、……。
辦法：
一、請{{$target_agency}}……。
二、請於{{$deadline_days}}日內將辦理情形回復並副知本府。

【產出】
請先輸出 JSON，緊接著輸出「正文」。兩者中間空一行。

3.在目錄中新增config.json

{
  "schema": 1,
  "description": "依人民陳情內容與相似公文，擬出正式可用的台灣公文。",
  "execution_settings": {
    "default": {
      "max_tokens": 1024,
      "temperature": 0.3
    }
  },

  "input_variables": [
    {
      "name": "user_complaint",
      "description": "人民陳情的原始文字",
      "default": ""
    },
    {
      "name": "similar_examples",
      "description": "相似公文片段",
      "default": ""
    },
    {
      "name": "doc_type",
      "description": "公文文別",
      "default": "函"
    },
    {
      "name": "target_agency",
      "description": "承辦單位",
      "default": ""
    },
    {
      "name": "deadline_days",
      "description": "回覆期限天數",
      "default": "14"
    }
  ]
}

4.設定skprompt.txt及config.json Copy 到 Output 目錄

接下來，就來看看程式如何使用prompt plugin, 如下:

using Microsoft.SemanticKernel;
using System.Text;
using Microsoft.SemanticKernel.Plugins.Core;

var apikey = "你的 openai api key";
var modelId = "gpt-4.1";
// 建立 KernelBuilder
var kernelBuilder = Kernel.CreateBuilder();
// 加入 OpenAI ChatCompletion 服務
var kernel = kernelBuilder
            .AddOpenAIChatCompletion(modelId, apikey)
            .Build();
OpenAIPromptExecutionSettings settings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
Console.OutputEncoding = UTF8Encoding.UTF8;
Console.InputEncoding = UTF8Encoding.UTF8;

// 註冊 plugin
var prompts = kernel.CreatePluginFromPromptDirectory("Prompts");
var fun = prompts["ComposeGovDoc"];
// 民眾陳情內容
var userMessage = @"陳情人:陳芊城陳述，在114年7月1日，在台北市林森北路52號巷口路燈不亮";
// 透過 RAG 取出相似的公文內容
var ragResult = @"主旨：關於民眾反映里內路燈故障一案，請查照。
說明：
一、依據民眾於113年9月1日陳情台北市承德路三段199號巷口路燈不亮。
二、經查現場路燈編號A12、A13不亮。
辦法：請工務課儘速派員檢修，完成後回復。";
var arguments = new KernelArguments
{
    ["user_complaint"] = userMessage,
    ["similar_examples"] = ragResult,
    ["doc_type"] = "函",
    ["target_agency"] = "工務課",
    ["deadline_days"] = "14"
};
// 呼叫並傳入參數
var result = await kernel.InvokeAsync(fun,  arguments);
Console.WriteLine(result);

輸出結果如下:

Filters

Semantic Kernel Filters提供三種類型:
Function Invocation Filter: 每次呼叫 KernelFunction 時，都會執行此過濾器。
Prompt Render Filter: 在將 prompt 給 AI 前，會執行此過濾器。
Auto Function Invocation Filter: 與Function Invocation Filter類似，提供額外的上下文信息(包含聊天歷史記錄、所有待執行函數的列表以及迭代計數器)。它還允許終止自動函數呼叫過程(context.Terminate = true;)
接下來使用Function Invocation Filter的程式碼會模擬一個對話流程，當 AI 試圖呼叫 ChangePrice 函式時，我們的 ApprovalFilter 會被觸發，並詢問使用者是否同意執行。
修改價格的 Plugin 及 Filter 如下:

using Microsoft.SemanticKernel;
using System.ComponentModel;

public class BookManagementPlugin
{
    [KernelFunction]
    [Description("Change the price of a book in the database ")]
    public void ChangePrice([Description("The book id to update")] int bookId, [Description("The new price")] int newPrice)
    {
        //update the price of the book in the database
    }
}

public class ApprovalFilter() : IFunctionInvocationFilter
{
    public async Task OnFunctionInvocationAsync(FunctionInvocationContext context, Func<FunctionInvocationContext, Task> next)
    {
        if (context.Function.PluginName == "BookManagementPlugin" && context.Function.Name == "ChangePrice")
        {

            Console.WriteLine($"系統想要更新書本的價格，您要繼續嗎？ （Y/N）");
            string shouldProceed = Console.ReadLine()!;

            if (shouldProceed != "Y")
            {
                context.Result = new FunctionResult(context.Result, "價格變動未獲得批准");
                return;
            }
        }

        await next(context);
    }

}

Console 程式如下:

using Microsoft.SemanticKernel;
using System.Text;
using Microsoft.SemanticKernel.Plugins.Core;

var apikey = "你的 openai api key";
var modelId = "gpt-4.1";
// 建立 KernelBuilder
var kernelBuilder = Kernel.CreateBuilder();
// 註冊 Plugin
kernelBuilder.Plugins.AddFromType<BookManagementPlugin>();
// 加入 ApprovalFilter
kernelBuilder.Services.AddSingleton<IFunctionInvocationFilter, ApprovalFilter>();

// 加入 OpenAI ChatCompletion 服務
var kernel = kernelBuilder
            .AddOpenAIChatCompletion(modelId, apikey)
            .Build();
OpenAIPromptExecutionSettings settings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
Console.OutputEncoding = UTF8Encoding.UTF8;
Console.InputEncoding = UTF8Encoding.UTF8;
var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
ChatHistory chatHistory = new();
string userMessage = string.Empty;
while (userMessage != "quit")
{
    Console.WriteLine("Enter your question:");
    userMessage = Console.ReadLine();
    chatHistory.AddUserMessage(userMessage);
    var assistantMessage = await chatCompletionService.GetChatMessageContentAsync(chatHistory, settings, kernel);
    Console.WriteLine(assistantMessage);
    chatHistory.Add(assistantMessage);
}

執行過程如下:

Using OpenAPI Plugins

企業可能有寫好的 API，只要有 OpenAPI 規格檔，用於描述其 API 的功能、參數、驗證方式等細節。Semantic Kernel 可以直接讀取這些規格檔，自動生成對應的函數，省下額外開發 AI Plugin 的時間。
以下以預設天氣 API 來測試， 1.加入 Microsoft.SemanticKernel.Plugins.OpenApi Nuget 套件 2.使用 kernel.ImportPluginFromOpenApiAsync 匯入 API 3.詢問 今天天氣的如何 就會呼叫 GetWeatherForecast

using Microsoft.SemanticKernel;
using System.Text;
using Microsoft.SemanticKernel.Plugins.Core;
using Microsoft.SemanticKernel.Plugins.OpenApi;
var apikey = "你的 openai api key";
var modelId = "gpt-4.1";
// 建立 KernelBuilder
var kernelBuilder = Kernel.CreateBuilder();
// 加入 OpenAI ChatCompletion 服務
var kernel = kernelBuilder
            .AddOpenAIChatCompletion(modelId, apikey)
            .Build();
// 註冊 OpenAPI Plugin
await kernel.ImportPluginFromOpenApiAsync(
     pluginName: "weatherforecast",
     uri: new Uri("http://localhost:5129/openapi/v1.json"),
               executionParameters: new OpenApiFunctionExecutionParameters()
               {
                   EnablePayloadNamespacing = true
               }
    );
OpenAIPromptExecutionSettings settings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
Console.OutputEncoding = UTF8Encoding.UTF8;
Console.InputEncoding = UTF8Encoding.UTF8;
Console.WriteLine(await kernel.InvokePromptAsync("今天天氣的如何", new(settings)));
Console.ReadLine();

結果會輸出類似的結果 根據今天的天氣預報，今天的氣溫約為23°C，天氣較冷。請注意保暖。

結論

在本章中，我們深入探索了 Semantic Kernel 的核心能力之一：Plugins。

我們從實例中見證了 Plugins 如何突破大型語言模型 (LLM) 的資訊限制，讓 AI 不僅能回答問題，更能與外部世界互動。無論是處理內建的複雜型別參數、利用現成的內建 Plugins，或是透過 File-based Prompts 來定義客製化的行為，Semantic Kernel 都提供了一套簡潔而強大的框架。此外，我們也了解了如何使用 Filters 來為 AI 流程加入額外的邏輯控制，以及如何將既有的 OpenAPI 規格快速轉化為可用的 Plugins，大幅提升開發效率。

透過這些功能，Semantic Kernel 賦予了我們為 LLM 打造專屬工具的能力，使 AI 應用程式變得更加智慧、靈活且具備處理現實世界任務的能力。
在下一章中，我們將深入探討 Semantic Kernel 如何讓你輕鬆地在不同的 LLM 服務提供者（例如 OpenAI、Azure OpenAI 等）之間切換，而無需修改核心程式碼。

參考資源

Semantic Kernel
Semantic Kernel Filters