摘要本文详细介绍了 Microsoft Semantic Kernel 框架中两种提示词使用方式基于文件的插件机制和基于代码的内联提示词。通过对比表格清晰展示了提示词推理与插件机制的核心差异并提供了完整的实战示例包括环境配置、插件定义、代码实现和运行效果。文章重点演示了如何创建笑话生成和赞美插件以及如何使用内联提示词进行文本总结帮助开发者快速掌握 Semantic Kernel 的核心功能。零、食用指南官方 notebook 中介绍了两个示例02-running-prompts-from-file.ipynb和03-semantic-function-inline.ipynb本质上都是提示词推理只是换了一种更结构化的写法把一句话包装成一个函数来调用但执行的仍然是把提示词发给 AI这个动作。特性提示词推理插件机制核心概念直接发送文本给模型将函数/方法注册为工具供模型调用代码结构调用InvokePromptAsync/InvokeAsync需要定义插件类 注册 调用注解使用无使用[KernelFunction], [Description]等模型角色仅作为文本生成器作为决策者决定何时调用哪个工具扩展性每次添加新功能需修改提示词添加新类即可无需改动调用代码确定性低模型可能编造高代码执行确定逻辑适用场景纯文本处理、内容生成需要执行代码、操作外部系统一、开发环境Ubuntu 24.04 LTS.NET 8Microsoft.SemanticKernel 1.76.0二、基于文件1、定义插件文件创建一个FunPlugin目录在该目录下创建Joke文件夹包含两个文件config.json模型参数配置文件skprompt.txt提示词文件在文件skprompt.txt中有特殊的{{$input}}和{{$style}}标记它们是在调用函数时自动传递的变量通常称为“函数参数”这里有两个参数需要在config.json文件中对它们进行定义{input_variables:[{name:input,description:Joke subject,default:},{name:style,description:Give a hint about the desired joke style,default:}]}除了函数参数config.json文件还可以配置模型推理参数{execution_settings:{default:{max_tokens:1000,temperature:0.9,top_p:0.0,presence_penalty:0.0,frequency_penalty:0.0}}}一个完整的配置文件是这样的{schema:1,description:Generate a funny joke,execution_settings:{default:{max_tokens:1000,temperature:0.9,top_p:0.0,presence_penalty:0.0,frequency_penalty:0.0}},input_variables:[{name:input,description:Joke subject,default:},{name:style,description:Give a hint about the desired joke style,default:}]}一个插件可以包含多个函数因此我们在Joke同级目录下可以再创建其他函数例如## 请根据用户输入的内容进行赞美 {{$input}} ## 赞美规则 请严格遵循以下步骤生成赞美 ### 第一步分析用户输入 - 提取用户提到的**具体行为**如跑步、工作、学习、**情绪状态**如疲惫、自豪、沮丧或**请求方式**。 - 如果用户未提供任何背景仅说“夸夸我”则赞美用户**主动寻求关怀**的勇气。 ### 第二步构建赞美内容 遵循 **S.P.E.C.I.A.L.** 原则 - **S**pecific具体针对细节避免“你很棒”这种空话。 → “你坚持跑完5公里每一步都是对承诺的践行。” - **P**ositive积极用阳光、有力的词汇着眼于潜力和努力。 → “你的毅力正在塑造更强的你。” - **E**ncouraging鼓励传递“你值得”和“你可以”的信息。 → “这份自律会带你到任何想去的地方。” - **C**reative创意使用比喻或生动描述。 → “你的好奇心像钥匙迟早打开所有向往的门。” - **I**mmediate即时用“你”直接对话使用现在时态。 → “你此刻寻求光亮的举动本身就是一种光芒。” - **A**uthentic真诚避免夸张或虚假比较基于真实人性价值。 → “承认需要鼓励是你内心强大的证明。” ### 第三步格式化输出 - 直接输出2-4句流畅的赞美。 - 以“你”开头使用第二人称。 - 不要添加任何前缀如“好的”、“这是给你的赞美”不要输出额外解释。 ## 输出示例 ### 示例1有具体成就 **用户**夸夸我我今天写了5000字报告。 **输出** 你能在一天内专注产出5000字这不仅展现了惊人的执行力更说明你对目标的承诺如此坚定。这种沉浸创造的心流状态是你才华最自然的流露。 ### 示例2无具体信息 **用户**赞美我。 **输出** 你主动开口要求被看见、被肯定这份坦荡的自我关怀能力比任何外在成就都更值得掌声。你允许自己需要光于是你就成了光本身。 ### 示例3情绪低落时 **用户**我今天什么也没做好鼓励鼓励我。 **输出** 在感到挫折时你没有逃避而是选择为自己寻求力量这本身就是最勇敢的修复行动。你的价值从不取决于单日的产出而在于你永远不放弃尝试的韧性。 ## 边缘情况处理 - **用户持续要求赞美**每次生成不同内容可切换角度努力、存在价值、特质。 - **用户否定赞美**不争辩输出“我尊重你现在的感受。同时请知道你愿意表达真实情绪这本身就非常值得欣赏。” - **用户给出负面自我评价**不要直接反驳而是重新框架“你可能觉得自己不够好但我看到的是你追求成长的敏锐标准。这份不满足恰恰是驱动你前进的火花。”2、创建语义核心// Populate values from your OpenAI deploymentvarmodelIdPro/zai-org/GLM-5.1;varendpointnewUri(https://api.siliconflow.cn/v1);varapiKeysk-xxx;varbuilderKernel.CreateBuilder().AddOpenAIChatCompletion(modelId:modelId,endpoint:endpoint,apiKey:apiKey,serviceId:SiliconFlow);//可选Add enterprise componentsbuilder.Services.AddLogging(servicesservices.AddConsole().SetMinimumLevel(LogLevel.Trace));// Build the kernelKernelkernelbuilder.Build();3、加载插件// FunPlugin directory pathvarfunPluginDirectoryPathPath.Combine(System.IO.Directory.GetCurrentDirectory(),FunPlugin);// Load the FunPlugin from the Plugins DirectoryvarfunPluginFunctionskernel.ImportPluginFromPromptDirectory(funPluginDirectoryPath);4、使用插件// Construct argumentsvararguments1newKernelArguments(){[input]番茄鸡蛋};// Run the Function called Jokevarresult1awaitkernel.InvokeAsync(funPluginFunctions[Joke],arguments1);// Print the resultConsole.WriteLine(result1);// Construct argumentsvararguments2newKernelArguments(){[input]我今天学习了 Microsoft Semantic Kernel 框架};// Run the Function called Praisevarresult2awaitkernel.InvokeAsync(funPluginFunctions[Praise],arguments2);// Print the resultConsole.WriteLine(result2);运行效果从日志中可以看到框架会自动扫描插件文件夹下的每个目录并且注册为函数5、完整代码// Import packagesusingMicrosoft.Extensions.DependencyInjection;usingMicrosoft.Extensions.Logging;usingMicrosoft.SemanticKernel;usingMicrosoft.SemanticKernel.ChatCompletion;// Populate values from your OpenAI deploymentvarmodelIdPro/zai-org/GLM-5.1;varendpointnewUri(https://api.siliconflow.cn/v1);varapiKeysk-xxx;// Create a kernel with Azure OpenAI chat completion// var builder Kernel.CreateBuilder().AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);varbuilderKernel.CreateBuilder().AddOpenAIChatCompletion(modelId:modelId,endpoint:endpoint,apiKey:apiKey,serviceId:SiliconFlow);// Add enterprise componentsbuilder.Services.AddLogging(servicesservices.AddConsole().SetMinimumLevel(LogLevel.Trace));// Build the kernelKernelkernelbuilder.Build();varchatCompletionServicekernel.GetRequiredServiceIChatCompletionService();// FunPlugin directory pathvarfunPluginDirectoryPathPath.Combine(System.IO.Directory.GetCurrentDirectory(),FunPlugin);// Load the FunPlugin from the Plugins DirectoryvarfunPluginFunctionskernel.ImportPluginFromPromptDirectory(funPluginDirectoryPath);// Construct argumentsvararguments1newKernelArguments(){[input]番茄鸡蛋};// Run the Function called Jokevarresult1awaitkernel.InvokeAsync(funPluginFunctions[Joke],arguments1);// Print the resultConsole.WriteLine(result1);// Construct argumentsvararguments2newKernelArguments(){[input]我今天学习了 Microsoft Semantic Kernel 框架};// Run the Function called Praisevarresult2awaitkernel.InvokeAsync(funPluginFunctions[Praise],arguments2);// Print the resultConsole.WriteLine(result2);三、基于代码1、定义提示词stringskPrompt{{$input}}请总结以上文本。;2、模型参数varexecutionSettingsnewOpenAIPromptExecutionSettings{MaxTokens2000,Temperature0.2,TopP0.5};3、提示词模板接下来创建模板的一个实例传入上述的提示词和配置以及其他几个参数我们可以在发送给 AI 之前查看提示词内容。varpromptTemplateConfignewPromptTemplateConfig(skPrompt);varpromptTemplateFactorynewKernelPromptTemplateFactory();varpromptTemplatepromptTemplateFactory.Create(promptTemplateConfig);varrenderedPromptawaitpromptTemplate.RenderAsync(kernel);Console.WriteLine(renderedPrompt);4、转换为函数将提示模板转换为内核可以执行的函数varsummaryFunctionkernel.CreateFunctionFromPrompt(skPrompt,executionSettings);5、运行测试varinput 近年来随着全球气候变化加剧极端天气事件的频率和强度显著上升。 根据世界气象组织WMO2023年发布的报告过去50年间由洪水、风暴、热浪等天气灾害造成的经济损失增长了近5倍但同期因预警系统改善死亡人数下降了约三分之二。 以2022年为例巴基斯坦遭遇创纪录季风降雨导致全国三分之一的土地被淹超过3300万人受灾直接经济损失逾300亿美元。 专家指出应对极端天气需结合“减缓”与“适应”策略一方面通过减少温室气体排放控制长期变暖趋势另一方面加强基础设施韧性、推广社区早期预警系统。 然而低收入国家受限于资金与技术防灾能力普遍薄弱形成“气候脆弱性陷阱”。 国际社会在《联合国气候变化框架公约》下已启动“损失与损害”基金但从承诺到落地仍面临拨款机制、责任界定等多重挑战。;varsummaryResultawaitkernel.InvokeAsync(summaryFunction,new(){[input]input});Console.WriteLine(summaryResult);运行效果上面的代码显示了所有步骤以便逐步理解函数是如何构成的。6、更简洁的实现然而内核还包括一些辅助工具以更简洁地实现相同的功能。上面的相同函数可以用更少的代码执行stringskPrompt{{$input}}请总结以上文本。;varresultawaitkernel.InvokePromptAsync(skPrompt,new(){[input]input});Console.WriteLine(result);另一个示例用五个单词总结内容stringskPrompt {{$input}} Give me the TLDR in 5 words. ;vartextToSummarize 1) A robot may not injure a human being or, through inaction, allow a human being to come to harm. 2) A robot must obey orders given it by human beings except where such orders would conflict with the First Law. 3) A robot must protect its own existence as long as such protection does not conflict with the First or Second Law. ;varresultawaitkernel.InvokePromptAsync(skPrompt,new(){[input]textToSummarize});Console.WriteLine(result);7、完整代码usingMicrosoft.SemanticKernel;usingMicrosoft.SemanticKernel.Connectors.OpenAI;usingMicrosoft.Extensions.DependencyInjection;usingMicrosoft.Extensions.Logging;// Populate values from your OpenAI deploymentvarmodelIdPro/zai-org/GLM-5.1;varendpointnewUri(https://api.siliconflow.cn/v1);varapiKeyEnvironment.GetEnvironmentVariable(SILICON_FLOW_KEY)??sk-xxx;varbuilderKernel.CreateBuilder().AddOpenAIChatCompletion(modelId:modelId,endpoint:endpoint,apiKey:apiKey,serviceId:SiliconFlow);//可选Add enterprise componentsbuilder.Services.AddLogging(servicesservices.AddConsole().SetMinimumLevel(LogLevel.Trace));// Build the kernelKernelkernelbuilder.Build();// // 定义提示词// string skPrompt // {{$input}}// 请总结以上文本。// ;// // 模型参数// var executionSettings new OpenAIPromptExecutionSettings// {// MaxTokens 2000,// Temperature 0.2,// TopP 0.5// };// var promptTemplateConfig new PromptTemplateConfig(skPrompt);// var promptTemplateFactory new KernelPromptTemplateFactory();// var promptTemplate promptTemplateFactory.Create(promptTemplateConfig);// var renderedPrompt await promptTemplate.RenderAsync(kernel);// Console.WriteLine(renderedPrompt);// // 转换为函数// var summaryFunction kernel.CreateFunctionFromPrompt(skPrompt, executionSettings);// // 文本总结测试// var input // 近年来随着全球气候变化加剧极端天气事件的频率和强度显著上升。// 根据世界气象组织WMO2023年发布的报告过去50年间由洪水、风暴、热浪等天气灾害造成的经济损失增长了近5倍但同期因预警系统改善死亡人数下降了约三分之二。// 以2022年为例巴基斯坦遭遇创纪录季风降雨导致全国三分之一的土地被淹超过3300万人受灾直接经济损失逾300亿美元。// 专家指出应对极端天气需结合“减缓”与“适应”策略一方面通过减少温室气体排放控制长期变暖趋势另一方面加强基础设施韧性、推广社区早期预警系统。// 然而低收入国家受限于资金与技术防灾能力普遍薄弱形成“气候脆弱性陷阱”。// 国际社会在《联合国气候变化框架公约》下已启动“损失与损害”基金但从承诺到落地仍面临拨款机制、责任界定等多重挑战。// ;// var summaryResult await kernel.InvokeAsync(summaryFunction, new() { [input] input });// Console.WriteLine(summaryResult);// ---------------------------------------// string skPrompt // {{$input}}// 请总结以上文本。// ;// var result await kernel.InvokePromptAsync(skPrompt, new() { [input] input });// Console.WriteLine(result);// ---------------------------------------stringskPrompt {{$input}} Give me the TLDR in 5 words. ;vartextToSummarize 1) A robot may not injure a human being or, through inaction, allow a human being to come to harm. 2) A robot must obey orders given it by human beings except where such orders would conflict with the First Law. 3) A robot must protect its own existence as long as such protection does not conflict with the First or Second Law. ;varresultawaitkernel.InvokePromptAsync(skPrompt,new(){[input]textToSummarize});Console.WriteLine(result);四、模型推理参数在 Semantic Kernel 中模型推理参数控制着 AI 模型生成文本的行为和风格。这些参数通常在execution_settings中配置以下是常见参数及其作用1、max_tokens最大词元数作用限制模型生成的最大词元数token。一个 token 大约相当于 0.75 个英文单词或 2-3 个中文字符。示例值1000影响值过小可能导致回答被截断无法完成完整思考值过大可能浪费 tokens增加成本建议根据任务复杂度设置简单问答 100-300长文生成 500-20002、temperature温度作用控制输出的随机性和创造性。值越高输出越随机、多样值越低输出越确定、保守。范围0.0 到 2.0通常 0.0-1.0示例值0.9应用场景低温度0.0-0.3代码生成、事实问答、技术文档中等温度0.4-0.7一般对话、内容创作高温度0.8-1.0创意写作、头脑风暴、诗歌生成3、top_p核采样作用使用核采样nucleus sampling控制输出的多样性。模型仅从累积概率达到 top_p 的令牌中采样。范围0.0 到 1.0示例值0.0表示禁用 top_p使用 temperature 控制与 temperature 的关系通常只使用其中一个top_p0.9 表示只考虑概率质量占前 90% 的令牌当 top_p0.0 时完全由 temperature 控制4、presence_penalty存在惩罚作用惩罚已经出现过的令牌降低重复内容的可能性。范围-2.0 到 2.0示例值0.0无惩罚应用场景正值减少重复适合长文生成负值增加重复适合需要强调的场景0.0保持中性5、frequency_penalty频率惩罚作用根据令牌在文本中出现的频率进行惩罚降低常见词的重复。范围-2.0 到 2.0示例值0.0无惩罚与 presence_penalty 的区别presence_penalty惩罚是否出现过二元frequency_penalty惩罚出现频率连续6、参数组合示例创意写作配置{max_tokens:800,temperature:0.9,top_p:0.95,presence_penalty:0.2,frequency_penalty:0.1}高温度 高 top_p鼓励多样性轻微惩罚避免过度重复技术文档配置{max_tokens:500,temperature:0.2,top_p:0.0,presence_penalty:0.0,frequency_penalty:0.0}低温度确保准确性禁用 top_p使用确定性更高的 temperature 控制对话助手配置{max_tokens:300,temperature:0.7,top_p:0.9,presence_penalty:0.1,frequency_penalty:0.1}中等温度平衡友好性和一致性轻微惩罚保持对话自然流畅7、实践建议从默认值开始大多数场景下默认参数temperature0.7, top_p0.95效果良好或者参考模型的官方推荐参数逐步调整一次只调整 1-2 个参数观察效果变化任务导向创意任务提高 temperature (0.8-1.0)精确任务降低 temperature (0.0-0.3)避免重复增加 presence_penalty (0.1-0.5)成本考虑max_tokens 直接影响 API 调用成本按需设置测试验证用相同输入测试不同参数组合选择最佳效果8、在 Semantic Kernel 中使用配置文件方式基于文件插件{execution_settings:{default:{max_tokens:1000,temperature:0.9,top_p:0.0,presence_penalty:0.0,frequency_penalty:0.0}}}代码方式基于代码提示词varexecutionSettingsnewOpenAIPromptExecutionSettings{MaxTokens2000,Temperature0.2,TopP0.5,PresencePenalty0.0,FrequencyPenalty0.0};通过合理配置这些参数可以精确控制 AI 模型的输出风格和质量满足不同应用场景的需求。