Как да използвате Semantic Kernel: Практическо ръководство с модели, подкани и добавки
Опитвали ли сте някога да свържете LLM към приложението си и да получите крехка плетеница от подкани, помощни функции и състояние? Semantic Kernel (SK) съществува, за да поправи точно това. Това е лека, платформа с отворен код от Microsoft за изграждане на AI-първи приложения, които съчетават естествен език, инструменти и памет – без да превръщате кодовата си база в купа спагети от подкани.
В това ръководство ще направим практическа, ориентирана към решения обиколка на това как да използвате Semantic Kernel от нулата до производствени модели. Ще научите как да структурирате подкани, да включвате инструменти, да добавяте памет, да извиквате множество модели и да разполагате агенти, които действат последователно. Ще запазим примерите заземени и ще ви покажем какво има значение.
Какво е Semantic Kernel – и защо да го използвате?
Semantic Kernel е SDK, който ви помага да:
- Съставяте подкани и функции („умения“/добавки) в конвейери.
- Извиквате множество модели (OpenAI, Azure OpenAI, локални модели) взаимозаменяемо.
- Добавяте памет за контекст и дългосрочно припомняне чрез вграждания.
- Планирате и организирате многостъпкови задачи с надеждно състояние.
- Интегрирате инструменти (API, бази данни, файлов I/O) безопасно и детерминистично.
Мислете за SK като за контролер, който координира LLM, логиката на вашето приложение и потребителските данни. Вместо да кодирате дълги подкани и ad hoc извиквания на инструменти, вие дефинирате многократно използваеми семантични функции и native функции с ясни входове/изходи.
Чести случаи на употреба:
- Копилоти за поддръжка на клиенти с генериране, подсилено от извличане (RAG)
- Агенти за работни потоци (обобщаване → класифициране → предприемане на действия)
- Документ Q&A с памет и цитати
- Творческо съдържание и конвейери за генериране на код
Бърз старт: Първото ви приложение Semantic Kernel
По-долу е минимален поток, който показва как да използвате Semantic Kernel с чат модел и проста подкана. Ще използваме C# за яснота; можете да направите същото в Python или Java.
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);
Това е ядрото: ядро, модел и подкана, превърнати в многократно използваема функция с входове.
Семантични функции vs. Native функции
- Семантични функции: Задвижвани от подкани. Създавате ги от шаблони, предавате променливи и получавате текст или структурирани изходи.
- Native функции: Обикновени кодови функции, които SK излага на LLM за използване на инструменти.
Пример за native функция, която извлича времето от вашия API и го излага на модела:
public class WeatherPlugin
{
[KernelFunction, Description("Get weather for a city")]
public async Task<string> GetWeatherAsync(
[Description("City name")] string city)
{
// Call your weather API here
var temp = 22; // placeholder
return $"Weather in {city}: {temp}°C and clear";
}
}
// Register plugin
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
Сега вашите подкани могат да извикват weather.GetWeatherAsync като инструмент, позволявайки на модела да обосновава отговорите си с реални данни.
Модели на подкани, които действително работят
Когато се учите как да използвате Semantic Kernel, най-бързите победи идват от дисциплинирани модели на подкани:
- System-first: Използвайте силно системно съобщение, за да заключите тон, персона, безопасност и формат на изхода.
- Променливи слотове: Наименувайте ясно контейнерите (напр.,
{topic}, {audience}) и валидирайте входа.
- Договори за изход: Поискайте структурирани формати като JSON; включете схема в подканата.
- Few-shot: Предоставете кратки примери за стил и формат, а не за раздут контент.
- Предпазни мерки: Включете ограничения („Ако липсват данни, първо задайте уточняващ въпрос“).
Пример за структурирана подкана в SK:
var prompt = @"
Вие сте двигател за класификация.
Задача: Класифицирайте `message` в един от [Billing, Tech Support, Sales].
Върнете строг JSON: { \"label\": string, \"confidence\": number }
message: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "I can’t log into my account." });
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: "Customers can request a refund within 30 days of purchase with proof of receipt."
);
// По-късно: извлечете и напълнете в подканата
var results = memory.SearchAsync("refund window", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"Relevant: {item.Metadata.Text}");
}
След това подайте най-добрите съвпадения във вашата семантична функция като контекстни променливи. Съвет: поддържайте частите малки (200–400 токена) и ги дедуплицирайте.
Използване на инструменти и планиране: Многостъпкови работни потоци
Semantic Kernel поддържа планери, които могат да разбият потребителска цел на стъпки и да изберат кои функции да извикат. Това е идеално, когато имате кутия с инструменти от native и семантични функции.
Модел:
- Съберете целта и ограниченията от потребителя.
- Създайте план (последователност от извиквания на функции с аргументи).
- Изпълнете стъпка по стъпка, проверете изходите и се възстановете от грешки.
Пример за псевдокод:
// 1) Дефинирайте добавки (семантични + native) както преди
// 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 резултати и стабилни поколения.
- Наблюдаемост: Регистрирайте шаблони на подкани, променливи, латентност, използване на токени.
- Unit тестове: Златни тестови подкани със сравнения на моментни снимки.
Пример: валидирайте 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 Chatbot:
retrieve(context) → answer(question, context) с цитати.
- Работни потоци за одобрение: classify → generate draft → human review → send.
- Съдържание ops: outline → draft → fact-check → tone adjust → publish.
- Агент с инструменти: calendar.lookup, docs.search, email.send; с планиране и памет.
Съвет: Капсулирайте всяка стъпка като функция (семантична или native) и ги съставете в конвейери.
Пример: Документ Q&A с цитати
Нека свържем прост Q&A конвейер, който цитира източници, използвайки RAG.
// 1) Въведете документи в паметта
await memory.SaveInformationAsync("handbook", "vacation-policy",
"Employees accrue 1.5 days of PTO per month and can carry over 5 days.");
// 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 = @"
Вие отговаряте стриктно от предоставения контекст. Ако липсва, кажете, че не знаете.
Включете вградени цитати като [source i], използвайки индекса на контекстните елементи, започващ от 1.
Context:
1) {{ctx1}}
2) {{ctx2}}
Question: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "How many PTO days can I carry over?"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);
Чести клопки (и как да ги избегнете)
- Единична гигантска подкана: Разделете на функции; предайте само контекста, от който се нуждаете.
- Няма договори за изход: Винаги дефинирайте схеми за машинно четими стъпки.
- RAG без хигиена: Разделете добре, дедуплицирайте и класирайте по уместност и актуалност.
- Разрастване на инструменти: Поддържайте интерфейсите на добавките малки и документирани.
- Няма човек в цикъла: Добавете одобрения за действия с висок риск.
Как да използвате Semantic Kernel с Frontends
- Уеб приложения: Хоствайте вашата SK оркестрация в API слой; предавайте токени към UI.
- Чат UIs: Поддържайте състоянието на разговора от страна на сървъра; подрязвайте и обобщавайте.
- Auth: Безопасни за представяне извиквания – никога не позволявайте на модела да създава токени. Ограничете извикванията на инструменти чрез вашия бекенд.
Контролен списък за разполагане
- Променливи на средата за ключове и крайни точки
- Ограничаване на скоростта и повторни опити за извиквания на модели/инструменти
- Контрол на изходния код на шаблона на подканата
- Архивиране на векторно хранилище и обработка на PII
- Табла за наблюдение (латентност, цена, грешки)
- A/B тестване за подкани и маршрутизиране
Отстраняване на неизправности в стил ЧЗВ
- „Моделът халюцинира дори с RAG.“ Затегнете инструкциите: „Отговаряйте само от контекста“ и включете пример за отказ. Увеличете спецификацията на извличане и намалете температурата.
- „JSON продължава да се чупи.“ Добавете мини пример за валиден JSON и забранете коментари. Потвърдете след това и префразирайте при неуспех.
- „Латентността е висока.“ Извлечете по-малко, по-подходящи части; превключете прости стъпки към по-малки модели; паралелизирайте независими стъпки.
- „Разходите растат бързо.“ Кеширайте, компресирайте контекста и насочвайте лесни задачи към по-евтини модели.
Заслужава си да се отбележи: Изградете по-бързо със Sider.AI
Ако прототипирате подкани, тествате потоци от инструменти или сравнявате отговори между модели, спътник като Sider.ai може да ускори итерацията. Можете да изготвяте подкани, да провеждате A/B сравнения и да заснемате многократно използваеми фрагменти, преди да ги преместите в шаблони на Semantic Kernel – чудесно за изостряне на инструкциите и изходните схеми. Следващи стъпки: Превърнете това в работещ агент
- Започнете с една ясна задача (напр., класифицирайте имейли за поддръжка).
- Дефинирайте семантични/native функции със строги входове/изходи.
- Добавете памет само там, където измеримо подобрява отговорите.
- Инструментирайте всичко; тествайте с реални проби.
- Итерирайте върху подкани, използвайки sandbox, след което кодифицирайте в SK.
Основни изводи:
- Semantic Kernel ви помага да съставяте подкани, инструменти и памет в надеждни работни потоци.
- Използвайте изходни схеми, планери и маршрутизиране на множество модели за устойчивост и контрол на разходите.
- RAG плюс предпазни мерки бие гигантските подкани всеки път.
След като усвоите как да използвате Semantic Kernel с тези модели, ще изпратите AI функции, които не са просто впечатляващи демонстрации – а надеждни системи.
ЧЗВ
Q1:За какво се използва Semantic Kernel в AI приложенията?
Semantic Kernel е SDK за оркестрация за изграждане на AI работни потоци, които комбинират LLM подкани, инструменти (native функции) и памет. Той ви помага да структурирате задачи, да добавяте RAG и да извиквате множество модели надеждно.
Q2:Как да използвам Semantic Kernel за RAG с моите документи?
Въведете вашите документи във векторно хранилище чрез SK memory API, след това извлечете най-подходящите части за всяка заявка и ги инжектирайте във вашата подкана. Това подобрява точността и намалява халюцинациите.
Q3:Може ли Semantic Kernel да извиква външни API и услуги?
Да. Опаковайте API като native функции в добавка и ги регистрирайте в ядрото, така че моделът да може да ги използва като инструменти. Поддържайте интерфейсите малки и прилагайте валидиране на входа/изхода.
Q4:Кои модели работят със Semantic Kernel?
Semantic Kernel поддържа OpenAI, Azure OpenAI и други конектори. Можете да насочвате задачи към различни модели – например по-малки модели за чернови и по-големи модели за стъпки, натоварени с разсъждения.
Q5:Как да направя изходите на Semantic Kernel последователни (напр. JSON)?
Използвайте структурирани подкани, които изискват строг JSON и включват минимален пример или схема. Задайте ниска температура, валидирайте изходите след извикване и повторете или поправете, когато анализирането не успее.