A Semantic Kernel használata: Gyakorlati útmutató mintákkal, promptokkal és bővítményekkel
Próbáltad már LLM-et ragasztani az alkalmazásodhoz, és végül egy törékeny, promptokból, segédfüggvényekből és állapotból álló kuszaság lett belőle? A Semantic Kernel (SK) pontosan ezt a problémát hivatott megoldani. Ez egy könnyűsúlyú, nyílt forráskódú orkesztrációs keretrendszer a Microsofttól, amely AI-központú alkalmazások építésére szolgál, amelyek ötvözik a természetes nyelvet, az eszközöket és a memóriát – anélkül, hogy a kódbázisodat prompt-spagettivé változtatnák.
Ebben az útmutatóban egy gyakorlati, megoldásorientált körutat teszünk a Semantic Kernel használatáról a nulláról a termelési mintákig. Megtanulod, hogyan kell strukturálni a promptokat, csatlakoztatni az eszközöket, memóriát hozzáadni, több modellt hívni, és konzisztensen működő ügynököket telepíteni. A példákat a valósághoz közel tartjuk, és megmutatjuk, mi számít.
Mi az a Semantic Kernel – és miért érdemes használni?
A Semantic Kernel egy SDK, amely segít:
- Promptok és függvények ("képességek"/bővítmények) összekapcsolása csővezetékekbe.
- Több modell hívása (OpenAI, Azure OpenAI, helyi modellek) felcserélhetően.
- Memória hozzáadása a kontextushoz és a hosszú távú felidézéshez beágyazásokon keresztül.
- Többlépcsős feladatok tervezése és összehangolása megbízható állapotkezeléssel.
- Eszközök integrálása (API-k, adatbázisok, fájl I/O) biztonságosan és determinisztikusan.
Tekints az SK-ra úgy, mint egy vezérlőre, amely koordinálja az LLM-eket, az alkalmazáslogikádat és a felhasználói adatokat. Ahelyett, hogy hosszú promptokat és ad hoc eszközhívásokat kódolnál keményen, újrafelhasználható szemantikai függvényeket és natív függvényeket definiálsz világos bemenetekkel/kimenetekkel.
Gyakori felhasználási esetek:
- Ügyfélszolgálati másodpilóták lekérdezés-kiegészített generálással (RAG)
- Munkafolyamat-ügynökök (összefoglalás → osztályozás → intézkedés)
- Dokumentum Q&A memóriával és hivatkozásokkal
- Kreatív tartalom és kódgenerálási csővezetékek
Gyors kezdés: Az első Semantic Kernel alkalmazásod
Az alábbiakban egy minimális folyamat látható, amely bemutatja, hogyan kell a Semantic Kernel-t csevegőmodellel és egy egyszerű prompttal használni. A világosság kedvéért C#-ot fogunk használni; ugyanezt megteheted Pythonban vagy Javában is.
1) Csomagok telepítése
# .NET
dotnet add package Microsoft.SemanticKernel
# Opcionális: a csatlakozók és a tervezők verziótól függően változnak
2) A kernel és a modell konfigurálása
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// Válaszd ki a szolgáltatódat: OpenAI vagy Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // vagy a preferált modell
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;
3) Szemantikai függvény (prompt) definiálása
using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"Te egy tömör magyarázó vagy.
Magyarázd el a '{topic}' fogalmát 3 pontban egy kezdő számára.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vektoros beágyazások" });
Console.WriteLine(result);
Ez a lényeg: egy kernel, egy modell és egy prompt, amely újrafelhasználható függvénnyé alakul bemenetekkel.
Szemantikai függvények vs. Natív függvények
- Szemantikai függvények: Prompt-vezéreltek. Sablonokból hozod létre őket, változókat adsz át, és szöveges vagy strukturált kimeneteket kapsz.
- Natív függvények: Szabályos kódfüggvények, amelyeket az SK elérhetővé tesz az LLM számára eszközhasználatra.
Példa egy natív függvényre, amely lekéri az időjárást az API-dból, és elérhetővé teszi a modell számára:
public class WeatherPlugin
{
[KernelFunction, Description("Időjárás lekérése egy városhoz")]
public async Task<string> GetWeatherAsync(
[Description("Város neve")] string city)
{
// Hívd meg itt az időjárás API-dat
var temp = 22; // helykitöltő
return $"Időjárás {city} városban: {temp}°C és derült";
}
}
// Bővítmény regisztrálása
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
Most a promptjaid meghívhatják a weather.GetWeatherAsync függvényt eszközként, lehetővé téve a modell számára, hogy a válaszokat valós adatokra alapozza.
Prompt minták, amelyek ténylegesen működnek
Amikor megtanulod, hogyan kell a Semantic Kernel-t használni, a leggyorsabb sikerek a fegyelmezett prompt mintákból származnak:
- Rendszer-első: Használj egy erős rendszerüzenetet a hangnem, a személyiség, a biztonság és a kimeneti formátum rögzítéséhez.
- Változóhelyek: Nevezd el a helykitöltőket egyértelműen (pl.
{topic}, {audience}) és ellenőrizd a bemenetet.
- Kimeneti szerződések: Kérj strukturált formátumokat, például JSON-t; adj meg egy sémát a promptban.
- Néhány példás: Adj tömör példákat a stílusra és a formátumra, ne a tartalom felfújására.
- Korlátok: Tartalmazz korlátozásokat ("Ha hiányoznak az adatok, először tegyél fel tisztázó kérdést").
Példa strukturált promptra az SK-n belül:
var prompt = @"
Te egy osztályozó motor vagy.
Feladat: Osztályozd a `message` üzenetet az alábbiak egyikébe: [Számlázás, Technikai támogatás, Értékesítés].
Adj vissza szigorú JSON-t: { \"label\": string, \"confidence\": number }
message: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "Nem tudok bejelentkezni a fiókomba." });
Console.WriteLine(output); // {"label":"Technikai támogatás","confidence":0.89}
Memória hozzáadása: Beágyazások, RAG és Kontextusablakok
Az LLM-ek elfelejtenek. A memória teszi őket hasznossá.
- Rövid távú kontextus: Automatikus a beszélgetési előzmények révén.
- Hosszú távú memória: Tárold a felhasználói jegyzetek, dokumentumok vagy események beágyazásait, és kérd le a releváns darabokat a kontextushoz.
- RAG: Mielőtt meghívnál egy generációs függvényt, kérdezd le a vektoros tárolódat, és illeszd be az eredményeket a promptba.
Példa: szöveges memória hozzáadása beágyazásokkal és kontextus lekérése.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // cseréld le egy vektoros adatbázisra (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: "Az ügyfelek a vásárlástól számított 30 napon belül kérhetnek visszatérítést a nyugta bemutatásával."
);
// Később: lekérés és beillesztés a promptba
var results = memory.SearchAsync("visszatérítési időszak", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"Releváns: {item.Metadata.Text}");
}
Ezután tápláld be a legjobb találatokat a szemantikai függvényedbe kontextusváltozókként. Tipp: tartsd a darabokat kicsinek (200–400 token) és deduplikáld őket.
Eszközhasználat és tervezés: Többlépcsős munkafolyamatok
A Semantic Kernel támogatja a tervezőket, amelyek lebontják a felhasználói célt lépésekre, és kiválasztják, mely függvényeket kell meghívni. Ez tökéletes, ha natív és szemantikai függvények eszköztárával rendelkezel.
Minta:
- Gyűjtsd össze a célt és a korlátokat a felhasználótól.
- Készíts tervet (függvényhívások sorozata argumentumokkal).
- Végezd el lépésről lépésre, ellenőrizd a kimeneteket, és állj helyre a hibákból.
Pszeudokód példa:
// 1) Definiálj bővítményeket (szemantikai + natív) a korábbiak szerint
// 2) Használj tervezőt (az API felülete verziótól függően változhat)
var goal = "Foglalja össze a mellékelt irányelvet, osztályozza a kockázatot, és küldjön egy jelentést e-mailben";
// Tegyük fel, hogy vannak bővítményeink: files, summarize, classify, email
// A tervező összeállít egy tervet: files.Load → summarize.Run → classify.Run → email.Send
// Végezd el a tervet szekvenciálisan, ellenőrizd a JSON kimeneteket a lépések között
Gyakorlati tanácsok:
- Tedd a lépéseket idempotenssé és tesztelhetővé.
- Állíts be explicit kimeneti sémákat a lépések között.
- Használj újrapróbálkozásokat/visszalépést a hálózati eszközökön.
- Naplózd a bemeneteket/kimeneteket a megfigyelhetőség érdekében (de tisztítsd meg a PII-t).
Többmodell-stratégia: Válaszd ki a megfelelő modellt a feladathoz
A Semantic Kernel használatával különböző modellekhez irányíthatod a feladatokat:
- Gyors vázlatok → kicsi, olcsó modellek
- Logikai nehézségekkel járó lépések → nagyobb modellek
- Beágyazások → speciális beágyazási modell
- Kód → kódoptimalizált modellek
A gyakorlatban:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // sebességre optimalizált
.Build;
// Egyszerűbb promptokat irányítsd a fastKernel-hez; összetett feladatokat a kernelhez
Vagy konfigurálj több szolgáltatást ugyanabban a kernelben, és válaszd ki a függvényenként.
Prototípustól a termelésig: Korlátok és tesztelés
Ahogy megtanulod, hogyan kell a Semantic Kernel-t valós alkalmazásokban használni, a megbízhatóság számít:
- Séma-első kimenetek: Használj JSON sémákat és
TryParse kapukat.
- Determinizmus, amikor szükséges: Állítsd alacsonyra a hőmérsékletet, és korlátozd a kimeneteket.
- Biztonsági szűrők: Adj hozzá tartalom szűrőket és red-team promptokat.
- Gyorsítótárazás: Gyorsítótárazd a RAG eredményeket és a stabil generációkat.
- Megfigyelhetőség: Naplózd a prompt sablonokat, a változókat, a késleltetést, a token használatot.
- Egységtesztek: Arany teszt promptok pillanatkép összehasonlításokkal.
Példa: JSON kimenet érvényesítése.
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; }
}
Valós minták, amelyeket újra felhasználhatsz
- RAG Chatbot:
retrieve(context) → answer(question, context) hivatkozásokkal.
- Jóváhagyási munkafolyamatok: osztályozás → vázlat generálása → emberi felülvizsgálat → küldés.
- Tartalmi műveletek: körvonal → vázlat → tényellenőrzés → hangnem beállítása → közzététel.
- Ügynök eszközökkel: calendar.lookup, docs.search, email.send; tervezéssel és memóriával.
Tipp: Kapszulázd be az egyes lépéseket függvényként (szemantikai vagy natív), és illeszd össze őket csővezetékekbe.
Példa: Dokumentum Q&A hivatkozásokkal
Vezessünk egy egyszerű Q&A csővezetéket, amely a RAG segítségével hivatkozik a forrásokra.
// 1) Dokumentumok betöltése a memóriába
await memory.SaveInformationAsync("handbook", "vacation-policy",
"A munkavállalók havonta 1,5 nap szabadságot gyűjtenek, és 5 napot vihetnek át.");
// 2) Kontextus lekérése egy kérdéshez
var top = memory.SearchAsync("szabadság átvitele", "handbook", limit: 3, minRelevanceScore: 0.75);
var contexts = new List<string>;
await foreach (var r in top) contexts.Add(r.Metadata.Text);
// 3) Kérdezz kontextussal és kérj hivatkozásokat
var qaPrompt = @"
Szigorúan a megadott kontextusból válaszolj. Ha hiányzik, mondd, hogy nem tudod.
Tartalmazz beágyazott hivatkozásokat, mint például [source i] a kontextuselemek indexének használatával, 1-től kezdve.
Kontextus:
1) {{ctx1}}
2) {{ctx2}}
Kérdés: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "Hány nap szabadságot vihetek át?"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);
Gyakori buktatók (és hogyan kerülheted el őket)
- Egyetlen óriási prompt: Törd fel függvényekre; csak a szükséges kontextust add át.
- Nincs kimeneti szerződés: Mindig definiálj sémákat a géppel olvasható lépésekhez.
- RAG higiénia nélkül: Jól darabold fel, deduplikáld és rangsorold a relevancia és a frissesség szerint.
- Eszközök burjánzása: Tartsd a bővítmény interfészeket kicsinek és dokumentáltnak.
- Nincs ember a hurokban: Adj hozzá jóváhagyásokat a magas kockázatú műveletekhez.
A Semantic Kernel használata frontendekkel
- Webalkalmazások: Helyezd el az SK orkesztrációdat egy API rétegben; streameld a tokeneket a felhasználói felületre.
- Csevegő felhasználói felületek: Tartsd fenn a beszélgetés állapotát a szerver oldalon; ritkítsd és foglald össze.
- Hitelesítés: Személyazonosság-váltás biztonságos hívások – soha ne engedd, hogy a modell tokeneket hozzon létre. Kapuzd be az eszközhívásokat a backendeden keresztül.
Telepítési ellenőrzőlista
- Környezeti változók a kulcsokhoz és a végpontokhoz
- Sebességkorlátozás és újrapróbálkozások a modell/eszközhívásokhoz
- Prompt sablon forráskód vezérlés
- Vektoros tároló biztonsági mentések és PII kezelés
- Megfigyelhetőségi irányítópultok (késleltetés, költség, hibák)
- A/B tesztelés a promptokhoz és az útválasztáshoz
GYIK-stílusú hibaelhárítás
- „A modell hallucinál még a RAG-gal is.” Szigorítsd az utasításokat: "Csak a kontextusból válaszolj", és adj meg egy elutasító példát. Növeld a lekérdezés specificitását és csökkentsd a hőmérsékletet.
- „A JSON folyamatosan elromlik.” Adj hozzá egy mini példát a valid JSON-ra, és tiltsd meg a kommentárt. Utólagosan érvényesítsd és fogalmazd át hiba esetén.
- „Magas a késleltetés.” Kevesebb, relevánsabb darabot kérj le; válts egyszerűbb lépéseket kisebb modellekre; párhuzamosítsd a független lépéseket.
- „A költségek az egekben vannak.” Gyorsítótárazd, tömörítsd a kontextust, és az egyszerű feladatokat olcsóbb modellekhez irányítsd.
Érdemes megjegyezni: Gyorsabban építhetsz a Sider.AI segítségével
Ha promptokat prototípuskészítesz, eszközfolyamatokat tesztelsz, vagy válaszokat hasonlítasz össze a modellek között, egy olyan társ, mint a Sider.ai, felgyorsíthatja az iterációt. Vázlatokat készíthetsz promptokról, futtathatsz A/B összehasonlításokat, és rögzíthetsz újrafelhasználható kódrészleteket, mielőtt áthelyeznéd őket a Semantic Kernel sablonokba – nagyszerű az utasítások és a kimeneti sémák élesítéséhez. Következő lépések: Alakítsd ezt egy működő ügynökké
- Kezdd egyértelmű feladattal (pl. támogatási e-mailek osztályozása).
- Definiálj szemantikai/natív függvényeket szigorú bemenetekkel/kimenetekkel.
- Csak ott adj hozzá memóriát, ahol az mérhetően javítja a válaszokat.
- Mindent mérj; tesztelj valós mintákkal.
- Iterálj a promptokon egy sandbox segítségével, majd kódold az SK-ban.
Főbb tudnivalók:
- A Semantic Kernel segít promptokat, eszközöket és memóriát megbízható munkafolyamatokba szervezni.
- Használj kimeneti sémákat, tervezőket és többmodell-útválasztást a robusztusság és a költségkontroll érdekében.
- A RAG plusz korlátok minden alkalommal legyőzik az óriási promptokat.
Ha elsajátítottad a Semantic Kernel használatát ezekkel a mintákkal, olyan AI funkciókat fogsz szállítani, amelyek nem csak lenyűgöző demók, hanem megbízható rendszerek is.
GYIK
Q1:Mire használják a Semantic Kernel-t az AI alkalmazásokban?
A Semantic Kernel egy orkesztrációs SDK az AI munkafolyamatok építéséhez, amelyek kombinálják az LLM promptokat, az eszközöket (natív függvényeket) és a memóriát. Segít a feladatok strukturálásában, a RAG hozzáadásában és a több modell megbízható hívásában.
Q2:Hogyan használhatom a Semantic Kernel-t a RAG-hoz a dokumentumaimmal?
Töltsd be a dokumentumaidat egy vektoros tárolóba az SK memória API-jain keresztül, majd kérd le a legrelevánsabb darabokat lekérdezésenként, és illeszd be őket a promptba. Ez javítja a pontosságot és csökkenti a hallucinációkat.
Q3:Hívhat a Semantic Kernel külső API-kat és szolgáltatásokat?
Igen. Csomagold be az API-kat natív függvényekként egy bővítménybe, és regisztráld őket a kernelben, hogy a modell eszközként használhassa őket. Tartsd az interfészeket kicsinek, és kényszerítsd ki a bemeneti/kimeneti érvényesítést.
Q4:Mely modellek működnek a Semantic Kernel-lel?
A Semantic Kernel támogatja az OpenAI-t, az Azure OpenAI-t és más csatlakozókat. A feladatokat különböző modellekhez irányíthatod – például kisebb modelleket a vázlatokhoz és nagyobb modelleket a logikai szempontból intenzív lépésekhez.
Q5:Hogyan tehetem a Semantic Kernel kimeneteit konzisztenssé (pl. JSON)?
Használj strukturált promptokat, amelyek szigorú JSON-t követelnek meg, és tartalmazzanak egy minimális példát vagy sémát. Állíts be alacsony hőmérsékletet, érvényesítsd a kimeneteket a hívás után, és próbáld újra vagy javítsd ki, ha az elemzés sikertelen.