• Strona główna
  • Blog
  • Narzędzia AI
  • Jak Korzystać z Semantic Kernel: Praktyczny Przewodnik z Wzorcami, Promptami i Wtyczkami

Jak Korzystać z Semantic Kernel: Praktyczny Przewodnik z Wzorcami, Promptami i Wtyczkami

Zaktualizowano 24 wrz 2025

9 min


Jak używać Semantic Kernel: Praktyczny przewodnik z wzorcami, podpowiedziami i wtyczkami

Próbowałeś kiedyś podłączyć LLM do swojej aplikacji i skończyło się to kruchą plątaniną podpowiedzi, funkcji pomocniczych i stanu? Semantic Kernel (SK) istnieje po to, aby to naprawić. Jest to lekka, otwarta platforma orkiestracyjna od Microsoftu do tworzenia aplikacji typu AI-first, które łączą język naturalny, narzędzia i pamięć — bez zamieniania bazy kodu w spaghetti z podpowiedzi.
W tym przewodniku odbędziemy praktyczną, zorientowaną na rozwiązania wycieczkę po tym, jak używać Semantic Kernel od zera do wzorców produkcyjnych. Dowiesz się, jak strukturyzować podpowiedzi, podłączać narzędzia, dodawać pamięć, wywoływać wiele modeli i wdrażać agentów, którzy działają konsekwentnie. Utrzymamy przykłady w uziemieniu i pokażemy ci, co się liczy.

Czym jest Semantic Kernel — i dlaczego go używać?

Semantic Kernel to zestaw SDK, który pomaga:
  • Tworzyć podpowiedzi i funkcje („umiejętności”/wtyczki) w potoki.
  • Wywoływać wiele modeli (OpenAI, Azure OpenAI, modele lokalne) zamiennie.
  • Dodawać pamięć dla kontekstu i długotrwałego przypominania za pomocą osadzeń.
  • Planować i orkiestrować wieloetapowe zadania z niezawodnym stanem.
  • Integrować narzędzia (API, bazy danych, we/wy plików) bezpiecznie i deterministycznie.
Pomyśl o SK jako o kontrolerze, który koordynuje LLM, logikę aplikacji i dane użytkownika. Zamiast zakodowywać na stałe długie podpowiedzi i doraźne wywołania narzędzi, definiujesz funkcje semantyczne wielokrotnego użytku i funkcje natywne z jasnymi wejściami/wyjściami.
Typowe przypadki użycia:
  • Piloci obsługi klienta z generowaniem rozszerzonym o pobieranie (RAG)
  • Agenci przepływu pracy (podsumuj → sklasyfikuj → podejmij działanie)
  • Pytania i odpowiedzi dotyczące dokumentów z pamięcią i cytatami
  • Potoki generowania treści kreatywnych i kodu

Szybki start: Twoja pierwsza aplikacja Semantic Kernel

Poniżej znajduje się minimalny przepływ, który pokazuje, jak używać Semantic Kernel z modelem czatu i prostą podpowiedzią. Użyjemy C#, aby było jasno; możesz zrobić to samo w Pythonie lub Javie.

1) Zainstaluj pakiety

# .NET
dotnet add package Microsoft.SemanticKernel
# Opcjonalnie: konektory i planiści różnią się w zależności od wersji

2) Skonfiguruj jądro i model

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// Wybierz swojego dostawcę: OpenAI lub Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // lub preferowany model
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;

3) Zdefiniuj funkcję semantyczną (podpowiedź)

using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"Jesteś zwięzłym tłumaczem.
Wyjaśnij koncepcję '{topic}' w 3 punktach dla początkującego.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vector embeddings" });
Console.WriteLine(result);
To jest rdzeń: jądro, model i podpowiedź przekształcona w funkcję wielokrotnego użytku z wejściami.

Funkcje semantyczne a funkcje natywne

  • Funkcje semantyczne: Oparte na podpowiedziach. Tworzysz je z szablonów, przekazujesz zmienne i otrzymujesz tekst lub ustrukturyzowane dane wyjściowe.
  • Funkcje natywne: Zwykłe funkcje kodu, które SK udostępnia LLM do użycia jako narzędzia.
Przykład natywnej funkcji, która pobiera pogodę z twojego API i udostępnia ją modelowi:
public class WeatherPlugin
{
[KernelFunction, Description("Pobierz pogodę dla miasta")]
public async Task<string> GetWeatherAsync(
[Description("Nazwa miasta")] string city)
{
// Wywołaj swoje API pogodowe tutaj
var temp = 22; // symbol zastępczy
return $"Pogoda w {city}: {temp}°C i bezchmurnie";
}
}
// Zarejestruj wtyczkę
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
Teraz twoje podpowiedzi mogą wywoływać weather.GetWeatherAsync jako narzędzie, umożliwiając modelowi ugruntowanie odpowiedzi w rzeczywistych danych.

Wzorce podpowiedzi, które faktycznie działają

Ucząc się, jak używać Semantic Kernel, najszybsze wygrane pochodzą z zdyscyplinowanych wzorców podpowiedzi:
  • System-first: Użyj silnej wiadomości systemowej, aby zablokować ton, personę, bezpieczeństwo i format wyjściowy.
  • Gniazda zmiennych: Nazwij symbole zastępcze w sposób jasny (np. {topic}, {audience}) i zweryfikuj dane wejściowe.
  • Umowy wyjściowe: Proś o ustrukturyzowane formaty, takie jak JSON; dołącz schemat w podpowiedzi.
  • Few-shot: Podaj zwięzłe przykłady stylu i formatu, a nie nadmiar treści.
  • Szyny ochronne: Dołącz ograniczenia („Jeśli brakuje danych, najpierw zadaj pytanie wyjaśniające”).
Przykład ustrukturyzowanej podpowiedzi wewnątrz SK:
var prompt = @"
Jesteś silnikiem klasyfikacji.
Zadanie: Sklasyfikuj `message` do jednego z [Rozliczenia, Pomoc techniczna, Sprzedaż].
Zwróć ścisły JSON: { \"label\": string, \"confidence\": number }
message: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "Nie mogę się zalogować na moje konto." });
Console.WriteLine(output); // {"label":"Tech Support","confidence":0.89}

Dodawanie pamięci: Osadzanie, RAG i okna kontekstowe

LLM zapominają. Pamięć czyni je użytecznymi.
  • Krótkotrwały kontekst: Automatyczny za pośrednictwem historii konwersacji.
  • Pamięć długotrwała: Przechowuj osadzenia notatek użytkownika, dokumentów lub zdarzeń i pobieraj odpowiednie fragmenty dla kontekstu.
  • RAG: Przed wywołaniem funkcji generowania, zapytaj swój magazyn wektorowy i wstrzyknij wyniki do podpowiedzi.
Przykład: dodaj pamięć tekstową z osadzeniami i pobierz kontekst.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // zamień na wektorową bazę danych (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: "Klienci mogą poprosić o zwrot pieniędzy w ciągu 30 dni od zakupu z dowodem zakupu."
);
// Później: pobierz i umieść w podpowiedzi
var results = memory.SearchAsync("refund window", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"Odpowiednie: {item.Metadata.Text}");
}
Następnie wprowadź najlepsze dopasowania do swojej funkcji semantycznej jako zmienne kontekstowe. Wskazówka: utrzymuj małe fragmenty (200–400 tokenów) i usuwaj duplikaty.

Użycie narzędzi i planowanie: Wieloetapowe przepływy pracy

Semantic Kernel obsługuje planistów, którzy mogą podzielić cel użytkownika na kroki i wybrać, które funkcje wywołać. Jest to idealne rozwiązanie, gdy masz zestaw narzędzi funkcji natywnych i semantycznych.
Wzorzec:
  1. Zbierz cel i ograniczenia od użytkownika.
  1. Sporządź plan (sekwencję wywołań funkcji z argumentami).
  1. Wykonuj krok po kroku, weryfikuj dane wyjściowe i odzyskuj po błędach.
Przykład pseudokodu:
// 1) Zdefiniuj wtyczki (semantyczne + natywne) jak poprzednio
// 2) Użyj planisty (powierzchnia API może się różnić w zależności od wersji)
var goal = "Podsumuj załączoną politykę, sklasyfikuj ryzyko i wyślij raport e-mailem";
// Załóżmy, że mamy wtyczki: files, summarize, classify, email
// Planista złoży plan: files.Load → summarize.Run → classify.Run → email.Send
// Wykonaj plan sekwencyjnie, zweryfikuj wyjścia JSON między krokami
Najlepsze praktyki:
  • Uczyń kroki idempotentnymi i testowalnymi.
  • Ustaw jawne schematy wyjściowe między krokami.
  • Użyj ponownych prób/wycofywania na narzędziach sieciowych.
  • Rejestruj wejścia/wyjścia dla obserwowalności (ale oczyść PII).

Strategia wielu modeli: Wybierz odpowiedni model do zadania

Używając Semantic Kernel, możesz kierować zadania do różnych modeli:
  • Szybkie wersje robocze → małe, tanie modele
  • Kroki wymagające intensywnego rozumowania → większe modele
  • Osadzanie → specjalistyczny model osadzania
  • Kod → modele zoptymalizowane pod kątem kodu
W praktyce:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // zoptymalizowany pod kątem szybkości
.Build;
// Kieruj prostsze podpowiedzi do fastKernel; złożone zadania do kernel
Lub skonfiguruj wiele usług w tym samym jądrze i wybierz dla każdej funkcji.

Od prototypu do produkcji: Szyny ochronne i testowanie

Ucząc się, jak używać Semantic Kernel w prawdziwych aplikacjach, niezawodność ma znaczenie:
  • Wyjścia typu schema-first: Użyj schematów JSON i bramek TryParse.
  • Determinizm, gdy jest potrzebny: Ustaw niską temperaturę i ogranicz dane wyjściowe.
  • Filtry bezpieczeństwa: Dodaj filtry treści i podpowiedzi red-team.
  • Buforowanie: Buforuj wyniki RAG i stabilne generacje.
  • Obserwowalność: Rejestruj szablony podpowiedzi, zmienne, opóźnienia, użycie tokenów.
  • Testy jednostkowe: Złote podpowiedzi testowe z porównaniami migawek.
Przykład: zweryfikuj wyjście 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; }
}

Wzorce ze świata rzeczywistego, które możesz ponownie wykorzystać

  • RAG Chatbot: retrieve(context) → answer(question, context) z cytatami.
  • Przepływy pracy zatwierdzania: classify → generate draft → human review → send.
  • Operacje na treści: outline → draft → fact-check → tone adjust → publish.
  • Agent z narzędziami: calendar.lookup, docs.search, email.send; z planowaniem i pamięcią.
Wskazówka: Enkapsuluj każdy krok jako funkcję (semantyczną lub natywną) i komponuj je w potoki.

Przykład: Pytania i odpowiedzi dotyczące dokumentów z cytatami

Połączmy prosty potok pytań i odpowiedzi, który cytuje źródła przy użyciu RAG.
// 1) Wprowadź dokumenty do pamięci
await memory.SaveInformationAsync("handbook", "vacation-policy",
"Pracownicy gromadzą 1,5 dnia PTO miesięcznie i mogą przenieść 5 dni.");
// 2) Pobierz kontekst dla pytania
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) Zapytaj z kontekstem i poproś o cytaty
var qaPrompt = @"
Odpowiadasz ściśle z podanego kontekstu. Jeśli brakuje, powiedz, że nie wiesz.
Dołącz cytaty w tekście, takie jak [źródło i], używając indeksu elementów kontekstowych zaczynającego się od 1.
Kontekst:
1) {{ctx1}}
2) {{ctx2}}
Pytanie: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "Ile dni PTO mogę przenieść?"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);

Typowe pułapki (i jak ich unikać)

  • Pojedyncza gigantyczna podpowiedź: Podziel na funkcje; przekazuj tylko potrzebny kontekst.
  • Brak umów wyjściowych: Zawsze definiuj schematy dla kroków odczytywanych maszynowo.
  • RAG bez higieny: Dziel dobrze, usuwaj duplikaty i oceniaj według trafności i aktualności.
  • Rozrost narzędzi: Utrzymuj małe i udokumentowane interfejsy wtyczek.
  • Brak człowieka w pętli: Dodaj zatwierdzenia dla działań wysokiego ryzyka.

Jak używać Semantic Kernel z interfejsami użytkownika

  • Aplikacje internetowe: Hostuj swoją orkiestrację SK w warstwie API; przesyłaj tokeny do interfejsu użytkownika.
  • Interfejsy użytkownika czatu: Utrzymuj stan konwersacji po stronie serwera; przycinaj i podsumowuj.
  • Uwierzytelnianie: Wywołania bezpieczne dla personifikacji — nigdy nie pozwól modelowi tworzyć tokenów. Bramkuj wywołania narzędzi przez swój backend.

Lista kontrolna wdrożenia

  • Zmienne środowiskowe dla kluczy i punktów końcowych
  • Ograniczanie szybkości i ponowne próby dla wywołań modelu/narzędzia
  • Kontrola źródła szablonu podpowiedzi
  • Kopie zapasowe magazynu wektorowego i obsługa PII
  • Panele obserwacyjne (opóźnienie, koszt, błędy)
  • Testy A/B dla podpowiedzi i routingu

Rozwiązywanie problemów w stylu FAQ

  • „Model halucynuje nawet z RAG.” Zaostrz instrukcje: „Odpowiadaj tylko z kontekstu” i dołącz przykład odmowy. Zwiększ specyfikę pobierania i zmniejsz temperaturę.
  • „JSON ciągle się psuje.” Dodaj mini przykład prawidłowego JSON i zabroń komentarzy. Dokonaj post-walidacji i przefrazuj w przypadku awarii.
  • „Opóźnienie jest wysokie.” Pobierz mniej, bardziej trafnych fragmentów; przełącz proste kroki na mniejsze modele; zrównoleglaj niezależne kroki.
  • „Koszty rosną.” Buforuj, kompresuj kontekst i kieruj łatwe zadania do tańszych modeli.

Warto zauważyć: Buduj szybciej z Sider.AI

Jeśli prototypujesz podpowiedzi, testujesz przepływy narzędzi lub porównujesz odpowiedzi między modelami, towarzysz taki jak Sider.ai może przyspieszyć iterację. Możesz tworzyć podpowiedzi, uruchamiać porównania A/B i przechwytywać fragmenty wielokrotnego użytku przed przeniesieniem ich do szablonów Semantic Kernel — idealne do wyostrzania instrukcji i schematów wyjściowych.

Następne kroki: Zamień to w działającego agenta

  • Zacznij od jednego jasnego zadania (np. klasyfikuj e-maile pomocy technicznej).
  • Zdefiniuj funkcje semantyczne/natywne ze ścisłymi wejściami/wyjściami.
  • Dodaj pamięć tylko tam, gdzie mierzalnie poprawia odpowiedzi.
  • Instrumentuj wszystko; testuj na próbkach ze świata rzeczywistego.
  • Iteruj na podpowiedziach za pomocą piaskownicy, a następnie skodyfikuj w SK.
Kluczowe wnioski:
  • Semantic Kernel pomaga komponować podpowiedzi, narzędzia i pamięć w niezawodne przepływy pracy.
  • Użyj schematów wyjściowych, planistów i routingu wielu modeli dla solidności i kontroli kosztów.
  • RAG plus szyny ochronne bije gigantyczne podpowiedzi za każdym razem.
Gdy opanujesz, jak używać Semantic Kernel z tymi wzorcami, dostarczysz funkcje AI, które są nie tylko imponującymi demonstracjami — ale niezawodnymi systemami.

FAQ

P1: Do czego służy Semantic Kernel w aplikacjach AI? Semantic Kernel to zestaw SDK do orkiestracji do budowania przepływów pracy AI, które łączą podpowiedzi LLM, narzędzia (funkcje natywne) i pamięć. Pomaga strukturyzować zadania, dodawać RAG i niezawodnie wywoływać wiele modeli.
P2: Jak używać Semantic Kernel do RAG z moimi dokumentami? Wprowadź swoje dokumenty do magazynu wektorowego za pośrednictwem interfejsów API pamięci SK, a następnie pobierz najbardziej trafne fragmenty na zapytanie i wstrzyknij je do swojej podpowiedzi. Poprawia to dokładność i zmniejsza halucynacje.
P3: Czy Semantic Kernel może wywoływać zewnętrzne API i usługi? Tak. Zapakuj API jako funkcje natywne w wtyczce i zarejestruj je w jądrze, aby model mógł ich używać jako narzędzi. Utrzymuj małe interfejsy i wymuszaj walidację wejścia/wyjścia.
P4: Które modele działają z Semantic Kernel? Semantic Kernel obsługuje OpenAI, Azure OpenAI i inne konektory. Możesz kierować zadania do różnych modeli — na przykład mniejsze modele do wersji roboczych i większe modele do kroków wymagających intensywnego rozumowania.
P5: Jak sprawić, by wyjścia Semantic Kernel były spójne (np. JSON)? Użyj ustrukturyzowanych podpowiedzi, które wymagają ścisłego JSON i dołącz minimalny przykład lub schemat. Ustaw niską temperaturę, zweryfikuj wyjścia po wywołaniu i ponów lub napraw, gdy analiza się nie powiedzie.