Kako uporabljati Semantic Kernel: Praktični vodnik z vzorci, pozivi in vtičniki
Ste že kdaj poskusili prilepiti LLM na svojo aplikacijo in končali s krhko zmešnjavo pozivov, pomožnih funkcij in stanja? Semantic Kernel (SK) obstaja, da to popravi. Je lahek, odprtokodni okvir za orkestracijo podjetja Microsoft za gradnjo aplikacij, ki temeljijo na umetni inteligenci in združujejo naravni jezik, orodja in spomin – ne da bi vašo izvorno kodo spremenili v špagete pozivov.
V tem vodniku si bomo praktično in rešitveno usmerjeno ogledali, kako uporabljati Semantic Kernel od začetka do produkcijskih vzorcev. Naučili se boste strukturirati pozive, priključiti orodja, dodati spomin, klicati več modelov in uvajati agente, ki delujejo dosledno. Primeri bodo praktični in pokazali vam bomo, kaj je pomembno.
Kaj je Semantic Kernel – in zakaj ga uporabljati?
Semantic Kernel je SDK, ki vam pomaga:
- Sestaviti pozive in funkcije (»veščine«/vtičniki) v cevovode.
- Klicati več modelov (OpenAI, Azure OpenAI, lokalni modeli) izmenično.
- Dodati spomin za kontekst in dolgoročni priklic prek vdelav.
- Načrtovati in orkestrirati večstopenjske naloge z zanesljivim stanjem.
- Integrirati orodja (API-ji, baze podatkov, datotečni I/O) varno in deterministično.
Predstavljajte si SK kot krmilnik, ki usklajuje LLM-je, logiko vaše aplikacije in uporabniške podatke. Namesto trdega kodiranja dolgih pozivov in priložnostnih klicev orodij, definirate ponovljivo uporabne semantične funkcije in izvorne funkcije z jasnimi vhodi/izhodi.
Pogosti primeri uporabe:
- Kopiloti za podporo strankam z generiranjem, obogatenim z iskanjem (RAG)
- Agenti za potek dela (povzemi → razvrsti → ukrepaj)
- Dokument Q&A s spominom in citati
- Cevovodi za ustvarjalno vsebino in generiranje kode
Hiter začetek: Vaša prva aplikacija Semantic Kernel
Spodaj je minimalni potek, ki prikazuje, kako uporabljati Semantic Kernel s klepetalnim modelom in preprostim pozivom. Za jasnost bomo uporabili C#; enako lahko storite v Pythonu ali Javi.
1) Namestite pakete
# .NET
dotnet add package Microsoft.SemanticKernel
# Izbirno: konektorji in načrtovalci se razlikujejo glede na različico
2) Konfigurirajte jedro in model
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// Izberite svojega ponudnika: OpenAI ali Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // ali vaš najljubši model
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;
3) Določite semantično funkcijo (poziv)
using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"Ste jedrnat razlagalec.
Razložite koncept '{topic}' v 3 točkah za začetnika.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vektorske vdelave" });
Console.WriteLine(result);
To je bistvo: jedro, model in poziv, spremenjen v ponovljivo uporabno funkcijo z vhodi.
Semantične funkcije proti izvornim funkcijam
- Semantične funkcije: Pogon poziva. Ustvarite jih iz predlog, posredujete spremenljivke in dobite besedilne ali strukturirane izhode.
- Izvorne funkcije: Običajne funkcije kode, ki jih SK izpostavi LLM za uporabo orodij.
Primer izvorne funkcije, ki pridobi vreme iz vašega API-ja in ga izpostavi modelu:
public class WeatherPlugin
{
[KernelFunction, Description("Pridobi vreme za mesto")]
public async Task<string> GetWeatherAsync(
[Description("Ime mesta")] string city)
{
// Tukaj pokličite svoj vremenski API
var temp = 22; // ohranjevalnik mesta
return $"Vreme v {city}: {temp}°C in jasno";
}
}
// Registriraj vtičnik
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
Zdaj lahko vaši pozivi kličejo weather.GetWeatherAsync kot orodje, kar modelu omogoča, da odgovore utemelji v resničnih podatkih.
Vzorci pozivov, ki dejansko delujejo
Ko se učite uporabljati Semantic Kernel, najhitrejše zmage prihajajo iz discipliniranih vzorcev pozivov:
- Sistem na prvem mestu: Uporabite močno sistemsko sporočilo za zaklepanje tona, persone, varnosti in oblike izhoda.
- Spremenljiva mesta: Jasno poimenujte ohranjevalnike mesta (npr.
{topic}, {audience}) in preverite veljavnost vnosa.
- Izhodne pogodbe: Zahtevajte strukturirane oblike, kot je JSON; vključite shemo v poziv.
- Malo posnetkov: Zagotovite jedrnate primere za slog in obliko, ne pa za napihovanje vsebine.
- Varovala: Vključite omejitve (»Če manjkajo podatki, najprej postavite pojasnilno vprašanje«).
Primer strukturiranega poziva znotraj SK:
var prompt = @"
Ste mehanizem za razvrščanje.
Naloga: Razvrstite `sporočilo` v eno od [Obračun, Tehnična podpora, Prodaja].
Vrniti strog JSON: { \"label\": string, \"confidence\": number }
sporočilo: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "Ne morem se prijaviti v svoj račun." });
Console.WriteLine(output); // {"label":"Tehnična podpora","confidence":0.89}
Dodajanje spomina: Vdelave, RAG in kontekstna okna
LLM-ji pozabljajo. Spomin jih naredi uporabne.
- Kratkoročni kontekst: Samodejno prek zgodovine pogovorov.
- Dolgoročni spomin: Shranite vdelave uporabniških zapiskov, dokumentov ali dogodkov in pridobite ustrezne kose za kontekst.
- RAG: Preden pokličete funkcijo generiranja, poizvedite v svoji vektorski shrambi in vstavite rezultate v poziv.
Primer: dodajte besedilni spomin z vdelavami in pridobite kontekst.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // zamenjajte z vektorsko bazo podatkov (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: "Stranke lahko zahtevajo vračilo kupnine v 30 dneh od nakupa z dokazilom o prejemu."
);
// Kasneje: pridobite in vstavite v poziv
var results = memory.SearchAsync("okno za vračilo kupnine", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"Relevantno: {item.Metadata.Text}");
}
Nato vnesite najboljša ujemanja v svojo semantično funkcijo kot kontekstne spremenljivke. Nasvet: naj bodo kosi majhni (200–400 žetonov) in jih odstranite podvojene.
Uporaba orodij in načrtovanje: Večstopenjski poteki dela
Semantic Kernel podpira načrtovalce, ki lahko razčlenijo uporabnikov cilj na korake in izberejo, katere funkcije naj pokličejo. To je popolno, ko imate orodjarno izvornih in semantičnih funkcij.
Vzorec:
- Zberite cilj in omejitve od uporabnika.
- Pripravite načrt (zaporedje klicev funkcij z argumenti).
- Izvajajte korak za korakom, preverite izhode in si opomozite po napakah.
Primer psevdokode:
// 1) Določite vtičnike (semantične + izvorne) kot prej
// 2) Uporabite načrtovalca (površina API se lahko razlikuje glede na različico)
var goal = "Povzemite priloženo politiko, razvrstite tveganje in pošljite poročilo po e-pošti";
// Predpostavimo, da imamo vtičnike: datoteke, povzemi, razvrsti, e-pošta
// Načrtovalec bo sestavil načrt: files.Load → summarize.Run → classify.Run → email.Send
// Izvedite načrt zaporedno, preverite veljavnost izhodov JSON med koraki
Najboljše prakse:
- Naredite korake idempotentne in preizkusljive.
- Nastavite eksplicitne izhodne sheme med koraki.
- Uporabite ponovne poskuse/izklop pri omrežnih orodjih.
- Beležite vhode/izhode za opazovanje (vendar očistite PII).
Strategija z več modeli: Izberite pravi model za delo
Z uporabo Semantic Kernel lahko usmerjate naloge na različne modele:
- Hitri osnutki → majhni, poceni modeli
- Koraki, ki zahtevajo veliko razmišljanja → večji modeli
- Vdelave → specializiran model za vdelavo
- Koda → modeli, optimizirani za kodo
V praksi:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // optimizirano za hitrost
.Build;
// Usmerite preprostejše pozive na fastKernel; kompleksne naloge na kernel
Ali pa konfigurirajte več storitev v istem jedru in izberite na funkcijo.
Od prototipa do produkcije: Varovala in testiranje
Ko se učite uporabljati Semantic Kernel v resničnih aplikacijah, je zanesljivost pomembna:
- Izhodi s shemo na prvem mestu: Uporabite sheme JSON in
TryParse vrata.
- Determinacija, ko je potrebna: Nastavite nizko temperaturo in omejite izhode.
- Varnostni filtri: Dodajte filtre vsebine in pozive rdeče ekipe.
- Predpomnjenje: Predpomnite rezultate RAG in stabilne generacije.
- Opazovanje: Beležite predloge pozivov, spremenljivke, latenco, uporabo žetonov.
- Enotski testi: Zlati preizkusni pozivi s primerjavami posnetkov.
Primer: preverite veljavnost izhoda 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; }
}
Resnični vzorci, ki jih lahko ponovno uporabite
- RAG Chatbot:
pridobi(kontekst) → odgovori(vprašanje, kontekst) s citati.
- Poteki dela odobritve: razvrsti → ustvari osnutek → človeški pregled → pošlji.
- Operacije vsebine: oris → osnutek → preverjanje dejstev → prilagoditev tona → objava.
- Agent z orodji: calendar.lookup, docs.search, email.send; z načrtovanjem in spominom.
Nasvet: Vsak korak zapakirajte kot funkcijo (semantično ali izvorno) in jih sestavite v cevovode.
Primer: Dokument Q&A s citati
Povežimo preprost cevovod Q&A, ki navaja vire z uporabo RAG.
// 1) Vnesite dokumente v spomin
await memory.SaveInformationAsync("priročnik", "politika-dopusta",
"Zaposleni si naberejo 1,5 dni PTO na mesec in lahko prenesejo 5 dni.");
// 2) Pridobite kontekst za vprašanje
var top = memory.SearchAsync("prenos PTO", "priročnik", limit: 3, minRelevanceScore: 0.75);
var contexts = new List<string>;
await foreach (var r in top) contexts.Add(r.Metadata.Text);
// 3) Vprašajte s kontekstom in zahtevajte citate
var qaPrompt = @"
Odgovorite izključno iz navedenega konteksta. Če manjka, recite, da ne veste.
Vključite inline citate, kot je [vir i], z uporabo indeksa kontekstnih elementov, ki se začnejo pri 1.
Kontekst:
1) {{ctx1}}
2) {{ctx2}}
Vprašanje: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "Koliko dni PTO lahko prenesem?"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);
Pogoste pasti (in kako se jim izogniti)
- En sam velik poziv: Razdelite na funkcije; posredujte samo kontekst, ki ga potrebujete.
- Brez izhodnih pogodb: Vedno definirajte sheme za strojno berljive korake.
- RAG brez higiene: Dobro razdelite, odstranite podvojene in razvrstite po pomembnosti in nedavnosti.
- Širjenje orodij: Naj bodo vmesniki vtičnikov majhni in dokumentirani.
- Brez človeka v zanki: Dodajte odobritve za dejanja z visokim tveganjem.
Kako uporabljati Semantic Kernel s sprednjimi konci
- Spletne aplikacije: Gostite svojo SK orkestracijo v plasti API; pretakajte žetone v uporabniški vmesnik.
- Klepetalni uporabniški vmesniki: Vzdržujte stanje pogovora na strani strežnika; obrezujte in povzemajte.
- Preverjanje pristnosti: Klici, varni za lažno predstavljanje – nikoli ne dovolite, da model kuje žetone. Nadzirajte klice orodij prek vaše zaledne strani.
Kontrolni seznam za uvajanje
- Spremenljivke okolja za ključe in končne točke
- Omejevanje hitrosti in ponovni poskusi za klice modelov/orodij
- Nadzor izvorne kode predloge poziva
- Varnostne kopije vektorske shrambe in obravnava PII
- Nadzorne plošče za opazovanje (latenca, stroški, napake)
- A/B testiranje za pozive in usmerjanje
Odpravljanje težav v slogu FAQ
- »Model halucinira tudi z RAG.« Poostrite navodila: »Odgovorite samo iz konteksta« in vključite primer zavrnitve. Povečajte specifičnost pridobivanja in zmanjšajte temperaturo.
- »JSON se nenehno kvari.« Dodajte mini primer veljavnega JSON in prepovejte komentarje. Po-preverite veljavnost in preformulirajte ob neuspehu.
- »Latenca je visoka.« Pridobite manj, bolj relevantnih kosov; preklopite preproste korake na manjše modele; vzporedite neodvisne korake.
- »Stroški naraščajo.« Predpomnite, stisnite kontekst in usmerite preproste naloge na cenejše modele.
Omeniti velja: Gradite hitreje s Sider.AI
Če prototipirate pozive, preizkušate poteke orodij ali primerjate odzive med modeli, lahko spremljevalec, kot je Sider.ai, pospeši iteracijo. Lahko pripravite pozive, izvajate primerjave A/B in zajamete ponovljivo uporabne izrezke, preden jih premaknete v predloge Semantic Kernel – odlično za izostritev navodil in izhodnih shem. Naslednji koraki: Spremenite to v delujočega agenta
- Začnite z eno jasno nalogo (npr. razvrščanje e-poštnih sporočil za podporo).
- Določite semantične/izvorne funkcije s strogimi vhodi/izhodi.
- Dodajte spomin samo tam, kjer merljivo izboljša odgovore.
- Instrumentirajte vse; preizkusite z resničnimi vzorci.
- Ponovite pozive z uporabo peskovnika, nato kodificirajte v SK.
Ključne ugotovitve:
- Semantic Kernel vam pomaga sestaviti pozive, orodja in spomin v zanesljive poteke dela.
- Uporabite izhodne sheme, načrtovalce in usmerjanje z več modeli za robustnost in nadzor stroškov.
- RAG plus varovala vsakič premagajo velikanske pozive.
Ko boste obvladali uporabo Semantic Kernel s temi vzorci, boste poslali funkcije umetne inteligence, ki niso samo impresivne predstavitve – ampak zanesljivi sistemi.
FAQ
V1: Za kaj se uporablja Semantic Kernel v aplikacijah umetne inteligence?
Semantic Kernel je SDK za orkestracijo za gradnjo potekov dela umetne inteligence, ki združujejo pozive LLM, orodja (izvorne funkcije) in spomin. Pomaga vam strukturirati naloge, dodati RAG in zanesljivo klicati več modelov.
V2: Kako uporabljam Semantic Kernel za RAG s svojimi dokumenti?
Vnesite svoje dokumente v vektorsko shrambo prek SK-jevih spominskih API-jev, nato pridobite najustreznejše kose na poizvedbo in jih vstavite v svoj poziv. To izboljša natančnost in zmanjšuje halucinacije.
V3: Ali lahko Semantic Kernel kliče zunanje API-je in storitve?
Da. Zavijte API-je kot izvorne funkcije v vtičniku in jih registrirajte pri jedru, da jih lahko model uporablja kot orodja. Naj bodo vmesniki majhni in uveljavljajte preverjanje veljavnosti vnosa/izhoda.
V4: Kateri modeli delujejo s Semantic Kernel?
Semantic Kernel podpira OpenAI, Azure OpenAI in druge konektorje. Naloge lahko usmerjate na različne modele – na primer manjše modele za osnutke in večje modele za korake, ki zahtevajo veliko razmišljanja.
V5: Kako naredim, da so izhodi Semantic Kernel dosledni (npr. JSON)?
Uporabite strukturirane pozive, ki zahtevajo strog JSON, in vključite minimalni primer ali shemo. Nastavite nizko temperaturo, po-klicno preverite veljavnost izhodov in ponovite ali popravite, ko razčlenjevanje ne uspe.