Kaip naudoti „Semantic Kernel“: praktinis vadovas su šablonais, raginimais ir įskiepiais
Ar kada bandėte prijungti LLM prie savo programos ir galiausiai gavote trapų raginimų, pagalbinių funkcijų ir būsenų raizginį? „Semantic Kernel“ (SK) egzistuoja būtent tam, kad tai ištaisytų. Tai lengvas, atvirojo kodo orkestravimo karkasas iš „Microsoft“, skirtas kurti pirmiausia dirbtinio intelekto programas, kurios sujungia natūralią kalbą, įrankius ir atmintį – nepaverčiant jūsų kodo bazės raginimų makaronų dubeniu.
Šiame vadove apžvelgsime praktinį, į sprendimus orientuotą „Semantic Kernel“ naudojimo būdą nuo nulio iki gamybos šablonų. Sužinosite, kaip struktūruoti raginimus, prijungti įrankius, pridėti atmintį, iškviesti kelis modelius ir įdiegti agentus, kurie veikia nuosekliai. Pateiksime pagrįstų pavyzdžių ir parodysime, kas svarbu.
Kas yra „Semantic Kernel“ ir kodėl jį naudoti?
„Semantic Kernel“ yra SDK, kuris padeda jums:
- Sukurti raginimus ir funkcijas („įgūdžius“ / įskiepius) į srautus.
- Iškviesti kelis modelius (OpenAI, Azure OpenAI, vietinius modelius) pakaitomis.
- Pridėti atmintį kontekstui ir ilgalaikiam prisiminimui per įterpimus.
- Planuoti ir orkestruoti daugiapakopius uždavinius su patikima būsena.
- Integruoti įrankius (API, duomenų bazes, failų įvestį / išvestį) saugiai ir deterministiškai.
Įsivaizduokite SK kaip valdiklį, kuris koordinuoja LLM, jūsų programos logiką ir vartotojo duomenis. Užuot sunkiai koduojant ilgus raginimus ir ad hoc įrankių iškvietimus, jūs apibrėžiate pakartotinai naudojamas semantines funkcijas ir vietines funkcijas su aiškiais įvesties / išvesties duomenimis.
Dažniausi naudojimo atvejai:
- Klientų aptarnavimo kopilotai su gavimu papildytu generavimu (RAG)
- Darbo eigos agentai (apibendrinti → klasifikuoti → imtis veiksmų)
- Dokumentų klausimai ir atsakymai su atmintimi ir citatomis
- Kūrybinio turinio ir kodo generavimo srautai
Greita pradžia: jūsų pirmoji „Semantic Kernel“ programa
Žemiau pateikiamas minimalus srautas, parodantis, kaip naudoti „Semantic Kernel“ su pokalbių modeliu ir paprastu raginimu. Aiškumo dėlei naudosime C#; tą patį galite padaryti su Python arba Java.
1) Įdiekite paketus
# .NET
dotnet add package Microsoft.SemanticKernel
# Pasirenkama: jungtys ir planuotojai skiriasi priklausomai nuo versijos
2) Konfigūruokite branduolį ir modelį
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// Pasirinkite savo tiekėją: OpenAI arba Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // arba jūsų pageidaujamas modelis
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;
3) Apibrėžkite semantinę funkciją (raginimą)
using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"Jūs esate glaustas aiškintojas.
Paaiškinkite sąvoką '{topic}' 3 punktais pradedančiajam.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vector embeddings" });
Console.WriteLine(result);
Tai yra esmė: branduolys, modelis ir raginimas, paverstas pakartotinai naudojama funkcija su įvesties duomenimis.
Semantinės funkcijos prieš vietines funkcijas
- Semantinės funkcijos: paremtos raginimais. Jūs kuriate jas iš šablonų, perduodate kintamuosius ir gaunate tekstą arba struktūrizuotus išvesties duomenis.
- Vietinės funkcijos: įprastos kodo funkcijos, kurias SK pateikia LLM įrankių naudojimui.
Vietinės funkcijos pavyzdys, kuris gauna orų duomenis iš jūsų API ir pateikia juos modeliui:
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");
Dabar jūsų raginimai gali iškviesti weather.GetWeatherAsync kaip įrankį, leidžiantį modeliui pagrįsti atsakymus realiais duomenimis.
Raginimų šablonai, kurie iš tikrųjų veikia
Mokantis naudoti „Semantic Kernel“, greičiausios pergalės ateina iš disciplinuotų raginimų šablonų:
- Pirmiausia sistema: naudokite stiprią sistemos žinutę, kad užrakintumėte toną, asmenybę, saugumą ir išvesties formatą.
- Kintamieji lizdai: aiškiai pavadinkite vietos rezervavimo ženklus (pvz.,
{topic}, {audience}) ir patvirtinkite įvestį.
- Išvesties sutartys: prašykite struktūrizuotų formatų, tokių kaip JSON; į raginimą įtraukite schemą.
- Keli kadrai: pateikite glaustus stiliaus ir formato pavyzdžius, o ne turinio išpūtimą.
- Apsaugos priemonės: įtraukite apribojimus („Jei trūksta duomenų, pirmiausia užduokite patikslinantį klausimą“).
Struktūrizuoto raginimo pavyzdys SK viduje:
var prompt = @"
Jūs esate klasifikavimo variklis.
Uždavinys: klasifikuokite `message` į vieną iš [Billing, Tech Support, Sales].
Grąžinkite griežtą 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}
Atminties pridėjimas: įterpimai, RAG ir konteksto langai
LLM pamiršta. Atmintis padaro juos naudingus.
- Trumpalaikis kontekstas: automatinis per pokalbio istoriją.
- Ilgalaikė atmintis: saugokite vartotojo pastabų, dokumentų ar įvykių įterpimus ir gaukite atitinkamas dalis kontekstui.
- RAG: prieš iškviesdami generavimo funkciją, užklauskite savo vektorių saugyklos ir įterpkite rezultatus į raginimą.
Pavyzdys: pridėkite tekstinę atmintį su įterpimais ir gaukite kontekstą.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // swap for a vector 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."
);
// Later: retrieve and stuff into prompt
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}");
}
Tada įveskite geriausius atitikmenis į savo semantinę funkciją kaip konteksto kintamuosius. Patarimas: laikykite dalis mažas (200–400 ženklų) ir pašalinkite dublikatus.
Įrankių naudojimas ir planavimas: daugiapakopės darbo eigos
„Semantic Kernel“ palaiko planuotojus, kurie gali suskaidyti vartotojo tikslą į veiksmus ir pasirinkti, kurias funkcijas iškviesti. Tai puikiai tinka, kai turite vietinių ir semantinių funkcijų rinkinį.
Šablonas:
- Surinkite tikslą ir apribojimus iš vartotojo.
- Parengkite planą (funkcijų iškvietimų seką su argumentais).
- Vykdykite žingsnis po žingsnio, patikrinkite išvesties duomenis ir atkurkite po klaidų.
Pseudokodo pavyzdys:
// 1) Apibrėžkite įskiepius (semantinius + vietinius) kaip anksčiau
// 2) Naudokite planuotoją (API paviršius gali skirtis priklausomai nuo versijos)
var goal = "Apibendrinkite pridėtą politiką, klasifikuokite riziką ir išsiųskite ataskaitą el. paštu";
// Assume we have plugins: files, summarize, classify, email
// Planner will assemble a plan: files.Load → summarize.Run → classify.Run → email.Send
// Execute plan sequentially, validate JSON outputs between steps
Geriausia praktika:
- Padarykite veiksmus idempotentinius ir patikrinamus.
- Nustatykite aiškias išvesties schemas tarp veiksmų.
- Naudokite pakartotinius bandymus / atsitraukimą tinkle esantiems įrankiams.
- Registruokite įvesties / išvesties duomenis stebėjimui (bet pašalinkite PII).
Kelių modelių strategija: pasirinkite tinkamą modelį darbui
Naudodami „Semantic Kernel“, galite nukreipti užduotis į skirtingus modelius:
- Greiti juodraščiai → maži, pigūs modeliai
- Sunkūs samprotavimo veiksmai → didesni modeliai
- Įterpimai → specializuotas įterpimo modelis
- Kodas → kodui optimizuoti modeliai
Praktiškai:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // speed-optimized
.Build;
// Route simpler prompts to fastKernel; complex tasks to kernel
Arba sukonfigūruokite kelias paslaugas tame pačiame branduolyje ir pasirinkite pagal funkciją.
Nuo prototipo iki gamybos: apsaugos priemonės ir testavimas
Mokantis naudoti „Semantic Kernel“ realiose programose, patikimumas yra svarbus:
- Pirmiausia schemos išvesties duomenys: naudokite JSON schemas ir
TryParse vartus.
- Deterministiškumas, kai reikia: nustatykite žemą temperatūrą ir apribokite išvesties duomenis.
- Saugos filtrai: pridėkite turinio filtrus ir raudonojo komandos raginimus.
- Kaupimas talpykloje: kaupkite RAG rezultatus ir stabilius generavimus.
- Stebėjimas: registruokite raginimų šablonus, kintamuosius, delsą, ženklų naudojimą.
- Vienetiniai testai: auksiniai testiniai raginimai su momentinių nuotraukų palyginimais.
Pavyzdys: patvirtinkite JSON išvesties duomenis.
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; }
}
Realaus pasaulio šablonai, kuriuos galite pakartotinai naudoti
- RAG pokalbių robotas:
gauti(context) → atsakyti(question, context) su citatomis.
- Patvirtinimo darbo eigos: klasifikuoti → generuoti juodraštį → žmogaus peržiūra → siųsti.
- Turinio operacijos: apibūdinti → parengti → patikrinti faktus → pakoreguoti toną → publikuoti.
- Agentas su įrankiais: calendar.lookup, docs.search, email.send; su planavimu ir atmintimi.
Patarimas: kiekvieną veiksmą apibūdinkite kaip funkciją (semantinę arba vietinę) ir sudėkite jas į srautus.
Pavyzdys: dokumentų klausimai ir atsakymai su citatomis
Sujunkime paprastą klausimų ir atsakymų srautą, kuris cituoja šaltinius naudodamas RAG.
// 1) Įkelkite dokumentus į atmintį
await memory.SaveInformationAsync("handbook", "vacation-policy",
"Employees accrue 1.5 days of PTO per month and can carry over 5 days.");
// 2) Retrieve context for a question
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) Ask with context and request citations
var qaPrompt = @"
You answer strictly from the provided context. If missing, say you don't know.
Include inline citations like [source i] using the index of context items starting at 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);
Dažniausios klaidos (ir kaip jų išvengti)
- Vienas didelis raginimas: suskaidykite į funkcijas; perduokite tik tą kontekstą, kurio jums reikia.
- Nėra išvesties sutarčių: visada apibrėžkite schemas, skirtas mašinoms skaitomiems veiksmams.
- RAG be higienos: gerai suskaidykite, pašalinkite dublikatus ir reitinguokite pagal aktualumą ir naujumą.
- Įrankių išplitimas: laikykite įskiepių sąsajas mažas ir dokumentuotas.
- Nėra žmogaus kilpoje: pridėkite patvirtinimus didelės rizikos veiksmams.
Kaip naudoti „Semantic Kernel“ su priekinėmis sąsajomis
- Žiniatinklio programos: prieglobkite savo SK orkestravimą API sluoksnyje; transliuokite ženklus į UI.
- Pokalbių UI: palaikykite pokalbio būseną serverio pusėje; apkarpykite ir apibendrinkite.
- Autentifikavimas: asmens tapatybės saugūs iškvietimai – niekada neleiskite modeliui kaldinti ženklų. Užrakinkite įrankių iškvietimus per savo galinę sistemą.
Diegimo kontrolinis sąrašas
- Aplinkos kintamieji, skirti raktams ir galiniams taškams
- Modelio / įrankių iškvietimų greičio ribojimas ir pakartotiniai bandymai
- Raginimų šablonų šaltinių valdymas
- Vektorių saugyklos atsarginės kopijos ir PII tvarkymas
- Stebėjimo informacijos suvestinės (delsa, kaina, klaidos)
- A / B testavimas raginimams ir maršrutizavimui
Trikčių šalinimas DUK stiliumi
- „Modelis haliucinuoja net ir su RAG.“ Sugriežtinkite instrukcijas: „Atsakykite tik iš konteksto“ ir įtraukite atsisakymo pavyzdį. Padidinkite gavimo specifiškumą ir sumažinkite temperatūrą.
- „JSON nuolat sugenda.“ Pridėkite mini galiojančio JSON pavyzdį ir uždrauskite komentarus. Patvirtinkite po patvirtinimo ir perfrazuokite, jei nepavyksta.
- „Delsa yra didelė.“ Gaukite mažiau, aktualesnių dalių; perkelkite paprastus veiksmus į mažesnius modelius; lygiagrečiai atlikite nepriklausomus veiksmus.
- „Išlaidos didėja.“ Kaupkite talpykloje, suspauskite kontekstą ir nukreipkite lengvas užduotis į pigesnius modelius.
Verta paminėti: kurkite greičiau naudodami Sider.AI
Jei kuriate raginimų prototipus, testuojate įrankių srautus arba lyginate atsakymus tarp modelių, toks kompanionas kaip Sider.ai gali pagreitinti iteraciją. Galite parengti raginimus, vykdyti A / B palyginimus ir užfiksuoti pakartotinai naudojamus fragmentus prieš perkeldami juos į „Semantic Kernel“ šablonus – puikiai tinka patikslinti instrukcijas ir išvesties schemas. Kiti veiksmai: paverskite tai veikiančiu agentu
- Pradėkite nuo vienos aiškios užduoties (pvz., klasifikuokite palaikymo el. laiškus).
- Apibrėžkite semantines / vietines funkcijas su griežtais įvesties / išvesties duomenimis.
- Pridėkite atmintį tik ten, kur ji pastebimai pagerina atsakymus.
- Instrumentuokite viską; testuokite su realaus pasaulio pavyzdžiais.
- Iteruokite raginimus naudodami smėlio dėžę, tada kodifikuokite SK.
Pagrindiniai dalykai:
- „Semantic Kernel“ padeda jums sudaryti raginimus, įrankius ir atmintį į patikimas darbo eigas.
- Naudokite išvesties schemas, planuotojus ir kelių modelių maršrutizavimą, kad užtikrintumėte patikimumą ir išlaidų kontrolę.
- RAG plius apsaugos priemonės kiekvieną kartą nugalės didžiulius raginimus.
Kai įvaldysite, kaip naudoti „Semantic Kernel“ su šiais šablonais, pristatysite dirbtinio intelekto funkcijas, kurios yra ne tik įspūdingos demonstracijos, bet ir patikimos sistemos.
DUK
Q1:Kam naudojamas „Semantic Kernel“ dirbtinio intelekto programose?
„Semantic Kernel“ yra orkestravimo SDK, skirtas kurti dirbtinio intelekto darbo eigas, kurios sujungia LLM raginimus, įrankius (vietines funkcijas) ir atmintį. Tai padeda jums struktūruoti užduotis, pridėti RAG ir patikimai iškviesti kelis modelius.
Q2:Kaip naudoti „Semantic Kernel“ RAG su mano dokumentais?
Įkelkite savo dokumentus į vektorių saugyklą per SK atminties API, tada gaukite aktualiausius fragmentus pagal užklausą ir įterpkite juos į savo raginimą. Tai pagerina tikslumą ir sumažina haliucinacijas.
Q3:Ar „Semantic Kernel“ gali iškviesti išorines API ir paslaugas?
Taip. Apvyniokite API kaip vietines funkcijas įskiepyje ir užregistruokite jas branduolyje, kad modelis galėtų jas naudoti kaip įrankius. Laikykite sąsajas mažas ir priverstinai patvirtinkite įvesties / išvesties duomenis.
Q4:Kurie modeliai veikia su „Semantic Kernel“?
„Semantic Kernel“ palaiko OpenAI, Azure OpenAI ir kitas jungtis. Galite nukreipti užduotis į skirtingus modelius – pavyzdžiui, mažesnius modelius juodraščiams ir didesnius modelius samprotavimo intensyviems veiksmams.
Q5:Kaip padaryti „Semantic Kernel“ išvesties duomenis nuoseklius (pvz., JSON)?
Naudokite struktūrizuotus raginimus, kurie reikalauja griežto JSON ir įtraukite minimalų pavyzdį arba schemą. Nustatykite žemą temperatūrą, patvirtinkite išvesties duomenis po iškvietimo ir bandykite iš naujo arba pataisykite, kai nepavyksta analizuoti.