نحوه استفاده از Semantic Kernel: یک راهنمای عملی با الگوها، اعلانها و پلاگینها
آیا تا به حال سعی کردهاید یک LLM را به برنامه خود بچسبانید و در نهایت با یک درهمتنیدگی شکننده از اعلانها، توابع کمکی و وضعیت مواجه شوید؟ Semantic Kernel (SK) دقیقاً برای رفع این مشکل وجود دارد. این یک چارچوب ارکستراسیون سبک و متنباز از مایکروسافت برای ساخت برنامههای کاربردی هوش مصنوعی است که زبان طبیعی، ابزارها و حافظه را با هم ترکیب میکند—بدون اینکه کد شما را به یک کاسه اسپاگتی اعلانی تبدیل کند.
در این راهنما، یک تور عملی و راهحلمحور از نحوه استفاده از Semantic Kernel از صفر تا الگوهای تولیدی خواهیم داشت. شما یاد خواهید گرفت که چگونه اعلانها را ساختاربندی کنید، ابزارها را به آن متصل کنید، حافظه اضافه کنید، مدلهای متعددی را فراخوانی کنید و نمایندگانی را مستقر کنید که به طور مداوم عمل میکنند. ما مثالها را ملموس نگه میداریم و به شما نشان میدهیم که چه چیزی مهم است.
Semantic Kernel چیست—و چرا باید از آن استفاده کرد؟
Semantic Kernel یک SDK است که به شما کمک میکند:
- ترکیب کنید ("مهارتها"/پلاگینها) را در خطوط لوله ترکیب کنید.
- فراخوانی کنید (OpenAI، Azure OpenAI، مدلهای محلی) را به صورت تعویضی فراخوانی کنید.
- برای زمینه و یادآوری طولانیمدت از طریق تعبیهها، حافظه اضافه کنید.
- وظایف چند مرحلهای را با وضعیت قابل اعتماد برنامهریزی و ارکستراسیون کنید.
- ادغام کنید (APIها، پایگاههای داده، فایل ورودی/خروجی) را به طور ایمن و قطعی ادغام کنید.
به SK به عنوان کنترلکننده فکر کنید که LLMها، منطق برنامه شما و دادههای کاربر را هماهنگ میکند. به جای کدنویسی سخت اعلانهای طولانی و فراخوانیهای ابزار موقت، شما توابع معنایی و توابع بومی قابل استفاده مجدد را با ورودی/خروجیهای واضح تعریف میکنید.
موارد استفاده رایج:
- کمکخلبانهای پشتیبانی مشتری با تولید تقویتشده بازیابی (RAG)
- نمایندگان گردش کار (خلاصه → طبقهبندی → اقدام)
- پرسش و پاسخ اسناد با حافظه و استناد
- خطوط لوله تولید محتوای خلاقانه و کد
شروع سریع: اولین برنامه Semantic Kernel شما
در زیر یک جریان حداقلی برای نشان دادن نحوه استفاده از Semantic Kernel با یک مدل چت و یک اعلان ساده آورده شده است. ما برای وضوح از C# استفاده خواهیم کرد. شما میتوانید همین کار را در پایتون یا جاوا انجام دهید.
1) نصب بستهها
# .NET
dotnet add package Microsoft.SemanticKernel
# اختیاری: کانکتورها و برنامهریزها بر اساس نسخه متفاوت هستند
2) پیکربندی هسته و مدل
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// ارائهدهنده خود را انتخاب کنید: OpenAI یا Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // یا مدل دلخواه شما
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;
3) تعریف یک تابع معنایی (اعلان)
using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"شما یک توضیحدهنده مختصر هستید.
مفهوم '{topic}' را در 3 نکته برای یک مبتدی توضیح دهید.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vector embeddings" });
Console.WriteLine(result);
این هسته اصلی است: یک هسته، یک مدل و یک اعلان که به یک تابع قابل استفاده مجدد با ورودیها تبدیل شده است.
توابع معنایی در مقابل توابع بومی
- توابع معنایی: مبتنی بر اعلان. شما آنها را از الگوها ایجاد میکنید، متغیرها را ارسال میکنید و خروجیهای متنی یا ساختاریافته دریافت میکنید.
- توابع بومی: توابع کد معمولی که SK برای استفاده ابزار در اختیار LLM قرار میدهد.
مثال تابع بومی که آب و هوا را از API شما میگیرد و آن را در اختیار مدل قرار میدهد:
public class WeatherPlugin
{
[KernelFunction, Description("دریافت آب و هوا برای یک شهر")]
public async Task<string> GetWeatherAsync(
[Description("نام شهر")] string city)
{
// API آب و هوای خود را در اینجا فراخوانی کنید
var temp = 22; // نگهدارنده
return $"آب و هوا در {city}: {temp}°C و صاف";
}
}
// ثبت پلاگین
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
اکنون اعلانهای شما میتوانند weather.GetWeatherAsync را به عنوان یک ابزار فراخوانی کنند و به مدل اجازه دهند پاسخها را در دادههای واقعی قرار دهد.
الگوهای اعلانی که واقعاً کار میکنند
هنگام یادگیری نحوه استفاده از Semantic Kernel، سریعترین بردها از الگوهای اعلانی منظم به دست میآیند:
- سیستم-اول: از یک پیام سیستمی قوی برای قفل کردن لحن، شخصیت، ایمنی و فرمت خروجی استفاده کنید.
- اسلاتهای متغیر: نگهدارندهها را به وضوح نامگذاری کنید (به عنوان مثال،
{topic}، {audience}) و ورودی را اعتبارسنجی کنید.
- قراردادهای خروجی: فرمتهای ساختاریافته مانند JSON را درخواست کنید. یک طرحواره در اعلان قرار دهید.
- چند-شات: مثالهای مختصر برای سبک و فرمت ارائه دهید، نه تورم محتوا.
- حفاظتها: محدودیتها را شامل کنید ("اگر دادهای از دست رفته است، ابتدا یک سؤال روشنکننده بپرسید").
مثال اعلان ساختاریافته در داخل SK:
var prompt = @"
شما یک موتور طبقهبندی هستید.
وظیفه: `message` را در یکی از [صورتحساب، پشتیبانی فنی، فروش] طبقهبندی کنید.
JSON دقیق را برگردانید: { \"label\": string, \"confidence\": number }
message: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "من نمیتوانم وارد حساب کاربری خود شوم." });
Console.WriteLine(output); // {"label":"Tech Support","confidence":0.89}
اضافه کردن حافظه: تعبیهها، RAG و پنجرههای زمینه
LLMها فراموش میکنند. حافظه آنها را مفید میکند.
- زمینه کوتاهمدت: خودکار از طریق تاریخچه مکالمه.
- حافظه بلندمدت: تعبیههای یادداشتها، اسناد یا رویدادهای کاربر را ذخیره کنید و تکههای مربوطه را برای زمینه بازیابی کنید.
- RAG: قبل از فراخوانی یک تابع تولید، فروشگاه برداری خود را پرس و جو کنید و نتایج را در اعلان تزریق کنید.
مثال: اضافه کردن حافظه متنی با تعبیهها و بازیابی زمینه.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // تعویض برای یک DB برداری (Qdrant, Pinecone, Azure AI Search)
.WithTextEmbeddingGeneration(
new OpenAITextEmbeddingGeneration("text-embedding-3-small", Environment.GetEnvironmentVariable("OPENAI_API_KEY")))
.Build;
await memory.SaveInformationAsync(
collection: "policies", id: "refund-policy",
text: "مشتریان میتوانند ظرف 30 روز پس از خرید با ارائه مدرک رسید، درخواست بازپرداخت کنند."
);
// بعداً: بازیابی و قرار دادن در اعلان
var results = memory.SearchAsync("refund window", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"مرتبط: {item.Metadata.Text}");
}
سپس بهترین تطابقها را به عنوان متغیرهای زمینه به تابع معنایی خود وارد کنید. نکته: تکهها را کوچک (200-400 توکن) نگه دارید و تکراریها را حذف کنید.
استفاده از ابزار و برنامهریزی: گردشهای کاری چند مرحلهای
Semantic Kernel از برنامهریزان پشتیبانی میکند که میتوانند یک هدف کاربر را به مراحلی تقسیم کنند و انتخاب کنند که کدام توابع را فراخوانی کنند. این عالی است زمانی که شما جعبه ابزاری از توابع بومی و معنایی دارید.
الگو:
- هدف و محدودیتها را از کاربر جمعآوری کنید.
- یک طرح (دنبالهای از فراخوانیهای تابع با آرگومانها) پیشنویس کنید.
- گام به گام اجرا کنید، خروجیها را تأیید کنید و از خطاها بازیابی کنید.
مثال شبه کد:
// 1) تعریف پلاگینها (معنایی + بومی) مانند قبل
// 2) استفاده از یک برنامهریز (سطح API ممکن است بر اساس نسخه متفاوت باشد)
var goal = "سیاست پیوست شده را خلاصه کنید، ریسک را طبقهبندی کنید و یک گزارش ایمیل کنید";
// فرض کنید پلاگینهایی داریم: files, summarize, classify, email
// برنامهریز یک طرح را جمعآوری میکند: files.Load → summarize.Run → classify.Run → email.Send
// اجرای طرح به صورت متوالی، اعتبارسنجی خروجیهای JSON بین مراحل
بهترین روشها:
- مراحل را معادل و قابل آزمایش کنید.
- طرحوارههای خروجی صریح را بین مراحل تنظیم کنید.
- از تلاش مجدد/بازگشت در ابزارهای شبکهای استفاده کنید.
- ورودی/خروجیها را برای قابلیت مشاهده ثبت کنید (اما PII را پاک کنید).
استراتژی چند مدلی: مدل مناسب را برای کار انتخاب کنید
با استفاده از Semantic Kernel، میتوانید وظایف را به مدلهای مختلف هدایت کنید:
- پیشنویسهای سریع → مدلهای کوچک و ارزان
- مراحل سنگین استدلال → مدلهای بزرگتر
- تعبیهها → مدل تعبیه تخصصی
- کد → مدلهای بهینهسازی شده کد
در عمل:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // بهینهسازی شده برای سرعت
.Build;
// اعلانهای سادهتر را به fastKernel هدایت کنید. وظایف پیچیده را به kernel
یا، چندین سرویس را در همان هسته پیکربندی کنید و بر اساس هر تابع انتخاب کنید.
از نمونه اولیه تا تولید: حفاظتها و آزمایش
همانطور که یاد میگیرید چگونه از Semantic Kernel در برنامههای واقعی استفاده کنید، قابلیت اطمینان مهم است:
- خروجیهای طرحواره-اول: از طرحوارههای JSON و درگاههای
TryParse استفاده کنید.
- قطعیت در صورت نیاز: دما را پایین تنظیم کنید و خروجیها را محدود کنید.
- فیلترهای ایمنی: فیلترهای محتوا و اعلانهای تیم قرمز را اضافه کنید.
- ذخیرهسازی: نتایج RAG و نسلهای پایدار را ذخیره کنید.
- قابلیت مشاهده: الگوهای اعلان، متغیرها، تأخیر، استفاده از توکن را ثبت کنید.
- آزمونهای واحد: اعلانهای آزمایشی طلایی با مقایسههای فوری.
مثال: اعتبارسنجی خروجی JSON.
record Classification(string label, double confidence);
bool TryParseClassification(string text, out Classification cls)
{
try { cls = System.Text.Json.JsonSerializer.Deserialize<Classification>(text)!; return true; }
catch { cls = default!; return false; }
}
الگوهای دنیای واقعی که میتوانید دوباره استفاده کنید
- چتبات RAG:
بازیابی(زمینه) → پاسخ(سؤال، زمینه) با استناد.
- گردشهای کاری تأیید: طبقهبندی → تولید پیشنویس → بررسی انسانی → ارسال.
- عملیات محتوا: طرح کلی → پیشنویس → بررسی صحت → تنظیم لحن → انتشار.
- نماینده با ابزارها: calendar.lookup, docs.search, email.send; با برنامهریزی و حافظه.
نکته: هر مرحله را به عنوان یک تابع (معنایی یا بومی) کپسوله کنید و آنها را در خطوط لوله ترکیب کنید.
مثال: پرسش و پاسخ اسناد با استناد
بیایید یک خط لوله پرسش و پاسخ ساده را سیمکشی کنیم که با استفاده از RAG به منابع استناد میکند.
// 1) وارد کردن اسناد به حافظه
await memory.SaveInformationAsync("handbook", "vacation-policy",
"کارمندان به ازای هر ماه 1.5 روز PTO جمع میکنند و میتوانند 5 روز را منتقل کنند.");
// 2) بازیابی زمینه برای یک سؤال
var top = memory.SearchAsync("carry over PTO", "handbook", limit: 3, minRelevanceScore: 0.75);
var contexts = new List<string>;
await foreach (var r in top) contexts.Add(r.Metadata.Text);
// 3) پرسیدن با زمینه و درخواست استناد
var qaPrompt = @"
شما دقیقاً از زمینه ارائه شده پاسخ میدهید. اگر وجود نداشت، بگویید نمیدانید.
استنادهای درونخطی مانند [منبع i] را با استفاده از فهرست موارد زمینه که از 1 شروع میشود، درج کنید.
زمینه:
1) {{ctx1}}
2) {{ctx2}}
سؤال: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "چند روز PTO میتوانم منتقل کنم؟"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);
اشتباهات رایج (و نحوه اجتناب از آنها)
- اعلان غولپیکر تکی: به توابع تقسیم کنید. فقط زمینهای را که نیاز دارید منتقل کنید.
- بدون قرارداد خروجی: همیشه طرحوارهها را برای مراحل قابل خواندن توسط ماشین تعریف کنید.
- RAG بدون بهداشت: به خوبی تکه تکه کنید، تکراریها را حذف کنید و بر اساس ارتباط و تازگی رتبهبندی کنید.
- گسترش ابزار: رابطهای پلاگین را کوچک و مستند نگه دارید.
- بدون انسان در حلقه: برای اقدامات پرخطر، تأییدیهها را اضافه کنید.
نحوه استفاده از Semantic Kernel با فرانتاندها
- برنامههای وب: ارکستراسیون SK خود را در یک لایه API میزبانی کنید. توکنها را به UI پخش کنید.
- UIهای چت: وضعیت مکالمه را در سمت سرور حفظ کنید. هرس و خلاصه کنید.
- احراز هویت: فراخوانیهای ایمن جعل هویت—هرگز اجازه ندهید مدل توکنها را ضرب کند. فراخوانیهای ابزار را از طریق باطن خود دروازهبانی کنید.
لیست بررسی استقرار
- متغیرهای محیطی برای کلیدها و نقاط پایانی
- محدودیت نرخ و تلاش مجدد برای فراخوانیهای مدل/ابزار
- پشتیبانگیری از فروشگاه برداری و رسیدگی به PII
- داشبوردهای قابلیت مشاهده (تأخیر، هزینه، خطاها)
- آزمایش A/B برای اعلانها و مسیریابی
عیبیابی به سبک پرسشهای متداول
- «مدل حتی با RAG توهم میزند.» دستورالعملها را محکم کنید: «فقط از زمینه پاسخ دهید» و یک مثال رد را درج کنید. ویژگی بازیابی را افزایش دهید و دما را کاهش دهید.
- «JSON مدام خراب میشود.» یک مثال کوچک از JSON معتبر اضافه کنید و تفسیر را ممنوع کنید. پس از اعتبارسنجی و بازنویسی در صورت شکست.
- «تأخیر زیاد است.» تکههای کمتر و مرتبطتری را بازیابی کنید. مراحل ساده را به مدلهای کوچکتر تغییر دهید. مراحل مستقل را موازی کنید.
- «هزینهها در حال افزایش است.» زمینه را ذخیره کنید، فشرده کنید و وظایف آسان را به مدلهای ارزانتر هدایت کنید.
شایان ذکر است: سریعتر با Sider.AI بسازید
اگر در حال نمونهسازی اعلانها، آزمایش جریانهای ابزار یا مقایسه پاسخها در مدلها هستید، یک همراه مانند Sider.ai میتواند تکرار را سرعت بخشد. شما میتوانید پیشنویس اعلانها را تهیه کنید، مقایسههای A/B را اجرا کنید و قطعههای قابل استفاده مجدد را قبل از انتقال آنها به الگوهای Semantic Kernel ضبط کنید—عالی برای تیز کردن دستورالعملها و طرحوارههای خروجی. مراحل بعدی: این را به یک نماینده کارآمد تبدیل کنید
- با یک وظیفه واضح شروع کنید (به عنوان مثال، طبقهبندی ایمیلهای پشتیبانی).
- توابع معنایی/بومی را با ورودی/خروجیهای دقیق تعریف کنید.
- حافظه را فقط در جایی اضافه کنید که به طور قابل اندازهگیری پاسخها را بهبود میبخشد.
- همه چیز را ابزار دقیق کنید. با نمونههای دنیای واقعی آزمایش کنید.
- در اعلانها با استفاده از یک سندباکس تکرار کنید، سپس در SK مدون کنید.
نکات کلیدی:
- Semantic Kernel به شما کمک میکند اعلانها، ابزارها و حافظه را در گردشهای کاری قابل اعتماد ترکیب کنید.
- از طرحوارههای خروجی، برنامهریزان و مسیریابی چند مدلی برای استحکام و کنترل هزینه استفاده کنید.
- RAG به همراه حفاظتها هر بار اعلانهای غولپیکر را شکست میدهد.
هنگامی که بر نحوه استفاده از Semantic Kernel با این الگوها تسلط پیدا کردید، ویژگیهای هوش مصنوعی را ارسال خواهید کرد که فقط نمایشهای چشمگیر نیستند—بلکه سیستمهای قابل اعتمادی هستند.
پرسشهای متداول
Q1: Semantic Kernel در برنامههای هوش مصنوعی برای چه استفاده میشود؟
Semantic Kernel یک SDK ارکستراسیون برای ساخت گردشهای کاری هوش مصنوعی است که اعلانهای LLM، ابزارها (توابع بومی) و حافظه را ترکیب میکند. این به شما کمک میکند وظایف را ساختاربندی کنید، RAG را اضافه کنید و مدلهای متعددی را به طور قابل اعتماد فراخوانی کنید.
Q2: چگونه از Semantic Kernel برای RAG با اسناد خود استفاده کنم؟
اسناد خود را از طریق APIهای حافظه SK وارد یک فروشگاه برداری کنید، سپس مرتبطترین تکهها را به ازای هر پرس و جو بازیابی کنید و آنها را در اعلان خود تزریق کنید. این دقت را بهبود میبخشد و توهمات را کاهش میدهد.
Q3: آیا Semantic Kernel میتواند APIها و سرویسهای خارجی را فراخوانی کند؟
بله. APIها را به عنوان توابع بومی در یک پلاگین بپیچید و آنها را در هسته ثبت کنید تا مدل بتواند از آنها به عنوان ابزار استفاده کند. رابطها را کوچک نگه دارید و اعتبارسنجی ورودی/خروجی را اعمال کنید.
Q4: کدام مدلها با Semantic Kernel کار میکنند؟
Semantic Kernel از OpenAI، Azure OpenAI و سایر کانکتورها پشتیبانی میکند. شما میتوانید وظایف را به مدلهای مختلف هدایت کنید—به عنوان مثال، مدلهای کوچکتر برای پیشنویسها و مدلهای بزرگتر برای مراحل سنگین استدلال.
Q5: چگونه خروجیهای Semantic Kernel را سازگار کنم (به عنوان مثال، JSON)؟
از اعلانهای ساختاریافته استفاده کنید که JSON دقیق را میطلبند و یک مثال یا طرحواره حداقلی را درج کنید. دمای پایین را تنظیم کنید، خروجیها را پس از فراخوانی اعتبارسنجی کنید و در صورت عدم موفقیت در تجزیه، دوباره تلاش کنید یا تعمیر کنید.