Semantic Kernel Nasıl Kullanılır: Desenler, İstekler ve Eklentilerle Pratik Bir Kılavuz
Uygulamanıza bir LLM entegre etmeye çalıştınız ve sonunda kırılgan bir istekler, yardımcı fonksiyonlar ve durum karmaşasıyla mı karşılaştınız? Semantic Kernel (SK) tam olarak bunu düzeltmek için var. Doğal dili, araçları ve belleği harmanlayan, yapay zeka öncelikli uygulamalar oluşturmak için Microsoft'un hafif, açık kaynaklı bir düzenleme çerçevesidir—kod tabanınızı bir istek spagettisine dönüştürmeden.
Bu kılavuzda, Semantic Kernel'i sıfırdan üretim desenlerine kadar nasıl kullanacağınız konusunda pratik, çözüm odaklı bir tura çıkacağız. İstekleri nasıl yapılandıracağınızı, araçları nasıl takacağınızı, bellek ekleyeceğinizi, birden fazla modeli nasıl çağıracağınızı ve tutarlı bir şekilde hareket eden aracıları nasıl dağıtacağınızı öğreneceksiniz. Örnekleri gerçekçi tutacak ve önemli olanı göstereceğiz.
Semantic Kernel Nedir—ve Neden Kullanmalısınız?
Semantic Kernel, size yardımcı olan bir SDK'dır:
- birleştirin ("beceriler"/eklentiler) ardışık düzenler halinde birleştirin.
- Birden fazla modeli çağırın (OpenAI, Azure OpenAI, yerel modeller) birbirinin yerine.
- Bağlam ve uzun süreli hatırlama için bellek ekleyin.
- Güvenilir durum ile çok adımlı görevleri planlayın ve yönetin.
- Araçları entegre edin (API'ler, veri tabanları, dosya G/Ç) güvenli ve deterministik bir şekilde.
SK'yı LLM'leri, uygulama mantığınızı ve kullanıcı verilerinizi koordine eden denetleyici olarak düşünün. Uzun istekleri ve geçici araç çağrılarını sabit kodlamak yerine, yeniden kullanılabilir semantik fonksiyonları ve net giriş/çıkışlara sahip yerel fonksiyonları tanımlarsınız.
Yaygın kullanım durumları:
- Geri alma ile güçlendirilmiş üretim (RAG) ile müşteri destek yardımcı pilotları
- İş akışı aracıları (özetle → sınıflandır → eyleme geç)
- Bellek ve alıntılarla belge Soru-Cevap
- Yaratıcı içerik ve kod oluşturma ardışık düzenleri
Hızlı Başlangıç: İlk Semantic Kernel Uygulamanız
Aşağıda, bir sohbet modeli ve basit bir istek ile Semantic Kernel'in nasıl kullanılacağını gösteren minimal bir akış bulunmaktadır. Açıklık için C#'ı kullanacağız; aynısını Python veya Java'da da yapabilirsiniz.
1) Paketleri yükleyin
# .NET
dotnet add package Microsoft.SemanticKernel
# İsteğe bağlı: bağlayıcılar ve planlayıcılar sürüme göre değişir
2) Çekirdeği ve modeli yapılandırın
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
var builder = Kernel.CreateBuilder;
// Sağlayıcınızı seçin: OpenAI veya Azure OpenAI
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o-mini", // veya tercih ettiğiniz model
apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")
);
var kernel = builder.Build;
3) Bir semantik fonksiyon (istek) tanımlayın
using Microsoft.SemanticKernel.SemanticFunctions;
var prompt = @"Siz özlü bir açıklayıcısınız.
'{topic}' kavramını yeni başlayanlar için 3 madde işaretiyle açıklayın.";
var explainFunc = kernel.CreateFunctionFromPrompt(prompt);
var result = await explainFunc.InvokeAsync(kernel, new { ["topic"] = "vektör gömmeleri" });
Console.WriteLine(result);
İşte özü: bir çekirdek, bir model ve yeniden kullanılabilir bir fonksiyona dönüştürülmüş, girişleri olan bir istek.
Semantik Fonksiyonlar ve Yerel Fonksiyonlar
- Semantik fonksiyonlar: İstekle güçlendirilmiş. Bunları şablonlardan oluşturur, değişkenler geçirir ve metin veya yapılandırılmış çıktılar alırsınız.
- Yerel fonksiyonlar: SK'nın araç kullanımı için LLM'ye sunduğu düzenli kod fonksiyonları.
API'nizden hava durumu getiren ve modele sunan örnek yerel fonksiyon:
public class WeatherPlugin
{
[KernelFunction, Description("Bir şehir için hava durumunu alın")]
public async Task<string> GetWeatherAsync(
[Description("Şehir adı")] string city)
{
// Hava durumu API'nizi buraya çağırın
var temp = 22; // yer tutucu
return $"{city} şehrinde hava durumu: {temp}°C ve açık";
}
}
// Eklentiyi kaydedin
var weather = new WeatherPlugin;
kernel.Plugins.AddFromObject(weather, pluginName: "weather");
Artık istekleriniz bir araç olarak weather.GetWeatherAsync'i çağırabilir ve modelin yanıtları gerçek verilere dayandırmasına olanak tanır.
Gerçekten İşe Yarayan İstek Desenleri
Semantic Kernel'i nasıl kullanacağınızı öğrenirken, en hızlı kazanımlar disiplinli istek desenlerinden gelir:
- Sistem öncelikli: Tonu, kişiliği, güvenliği ve çıktı biçimini kilitlemek için güçlü bir sistem mesajı kullanın.
- Değişken yuvaları: Yer tutucuları açıkça adlandırın (örn.,
{topic}, {audience}) ve girişi doğrulayın.
- Çıktı sözleşmeleri: JSON gibi yapılandırılmış biçimler isteyin; isteğe bir şema ekleyin.
- Birkaç örnek: İçerik şişkinliği değil, stil ve biçim için özlü örnekler sağlayın.
- Koruyucu raylar: Kısıtlamalar ekleyin ("Veri eksikse, önce açıklayıcı bir soru sorun").
SK içinde örnek yapılandırılmış istek:
var prompt = @"
Siz bir sınıflandırma motorusunuz.
Görev: `message`'ı [Faturalandırma, Teknik Destek, Satış]'tan birine sınıflandırın.
Kesin JSON döndürün: { \"label\": string, \"confidence\": number }
message: {message}
";
var classify = kernel.CreateFunctionFromPrompt(prompt);
var output = await classify.InvokeAsync(kernel, new { ["message"] = "Hesabıma giriş yapamıyorum." });
Console.WriteLine(output); // {"label":"Teknik Destek","confidence":0.89}
Bellek Ekleme: Gömme, RAG ve Bağlam Pencereleri
LLM'ler unutur. Bellek onları kullanışlı yapar.
- Kısa vadeli bağlam: Konuşma geçmişi aracılığıyla otomatik.
- Uzun vadeli bellek: Kullanıcı notlarının, belgelerin veya olayların gömmelerini saklayın ve bağlam için ilgili parçaları alın.
- RAG: Bir oluşturma fonksiyonunu çağırmadan önce, vektör deponuzu sorgulayın ve sonuçları isteğe enjekte edin.
Örnek: gömmelerle metin belleği ekleyin ve bağlamı alın.
using Microsoft.SemanticKernel.Memory;
var memory = new MemoryBuilder
.WithMemoryStore(new VolatileMemoryStore) // bir vektör veritabanı için değiştirin (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: "Müşteriler, makbuz kanıtıyla satın alma tarihinden itibaren 30 gün içinde geri ödeme talep edebilir.");
);
// Daha sonra: alın ve isteğe doldurun
var results = memory.SearchAsync("geri ödeme penceresi", collection: "policies", limit: 3, minRelevanceScore: 0.7);
await foreach (var item in results)
{
Console.WriteLine($"İlgili: {item.Metadata.Text}");
}
Ardından, en iyi eşleşmeleri bağlam değişkenleri olarak semantik fonksiyonunuza besleyin. İpucu: parçaları küçük (200–400 jeton) tutun ve yinelenenleri kaldırın.
Araç Kullanımı ve Planlama: Çok Adımlı İş Akışları
Semantic Kernel, bir kullanıcı hedefini adımlara ayırabilen ve hangi fonksiyonların çağrılacağını seçebilen planlayıcıları destekler. Bu, yerel ve semantik fonksiyonlardan oluşan bir araç kutunuz olduğunda mükemmeldir.
Desen:
- Kullanıcıdan hedef ve kısıtlamaları toplayın.
- Bir plan taslağı hazırlayın (argümanlarla fonksiyon çağrıları dizisi).
- Adım adım yürütün, çıktıları doğrulayın ve hatalardan kurtarın.
Sözde kod örneği:
// 1) Eklentileri (semantik + yerel) daha önce olduğu gibi tanımlayın
// 2) Bir planlayıcı kullanın (API yüzeyi sürüme göre değişebilir)
var goal = "Ekli politikayı özetleyin, riski sınıflandırın ve bir rapor e-postayla gönderin";
// Eklentilerimiz olduğunu varsayalım: dosyalar, özetle, sınıflandır, e-posta
// Planlayıcı bir plan oluşturacaktır: files.Load → summarize.Run → classify.Run → email.Send
// Planı sırayla yürütün, adımlar arasında JSON çıktılarını doğrulayın
En iyi uygulamalar:
- Adımları idempotent ve test edilebilir hale getirin.
- Adımlar arasında açık çıktı şemaları ayarlayın.
- Ağ bağlantılı araçlarda yeniden denemeler/geri çekilmeler kullanın.
- Gözlemlenebilirlik için girişleri/çıktıları günlüğe kaydedin (ancak PII'yi temizleyin).
Çok Modelli Strateji: İş İçin Doğru Modeli Seçin
Semantic Kernel'i kullanarak, görevleri farklı modellere yönlendirebilirsiniz:
- Hızlı taslaklar → küçük, ucuz modeller
- Akıl yürütme ağırlıklı adımlar → daha büyük modeller
- Gömme → özel gömme modeli
- Kod → kod için optimize edilmiş modeller
Uygulamada:
var kernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey)
.Build;
var fastKernel = Kernel.CreateBuilder
.AddOpenAIChatCompletion("gpt-4o-mini", apiKey) // hız için optimize edilmiş
.Build;
// Daha basit istekleri fastKernel'e; karmaşık görevleri kernel'e yönlendirin
Veya, aynı çekirdekte birden fazla hizmet yapılandırın ve fonksiyon başına seçin.
Prototipden Üretime: Koruyucu Raylar ve Test
Gerçek uygulamalarda Semantic Kernel'i nasıl kullanacağınızı öğrenirken, güvenilirlik önemlidir:
- Şema öncelikli çıktılar: JSON şemaları ve
TryParse kapıları kullanın.
- Gerekli olduğunda determinizm: Sıcaklığı düşük ayarlayın ve çıktıları kısıtlayın.
- Güvenlik filtreleri: İçerik filtreleri ve kırmızı takım istekleri ekleyin.
- Önbelleğe alma: RAG sonuçlarını ve kararlı nesilleri önbelleğe alın.
- Gözlemlenebilirlik: İstek şablonlarını, değişkenleri, gecikmeyi, jeton kullanımını günlüğe kaydedin.
- Birim testleri: Anlık görüntü karşılaştırmalarıyla altın test istekleri.
Örnek: JSON çıktısını doğrulayın.
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; }
}
Yeniden Kullanabileceğiniz Gerçek Dünya Desenleri
- RAG Sohbet Robotu: Alıntılarla
retrieve(context) → answer(question, context).
- Onay iş akışları: sınıflandır → taslak oluştur → insan incelemesi → gönder.
- İçerik işlemleri: ana hat → taslak → gerçekleri kontrol et → ton ayarı → yayınla.
- Araçlara sahip aracı: calendar.lookup, docs.search, email.send; planlama ve bellek ile.
İpucu: Her adımı bir fonksiyon (semantik veya yerel) olarak kapsülleyin ve bunları ardışık düzenler halinde birleştirin.
Örnek: Alıntılarla Belge Soru-Cevap
RAG kullanarak kaynakları alıntılayan basit bir Soru-Cevap ardışık düzeni bağlayalım.
// 1) Belgeleri belleğe alın
await memory.SaveInformationAsync("handbook", "vacation-policy",
"Çalışanlar ayda 1,5 gün ücretli izin biriktirir ve 5 gün devredebilir.");
// 2) Bir soru için bağlamı alın
var top = memory.SearchAsync("ücretli izin devretme", "handbook", limit: 3, minRelevanceScore: 0.75);
var contexts = new List<string>;
await foreach (var r in top) contexts.Add(r.Metadata.Text);
// 3) Bağlamla sorun ve alıntı isteyin
var qaPrompt = @"
Sağlanan bağlamdan kesinlikle cevap veriyorsunuz. Eksikse, bilmediğinizi söyleyin.
1'den başlayarak bağlam öğelerinin dizinini kullanarak [kaynak i] gibi satır içi alıntılar ekleyin.
Bağlam:
1) {{ctx1}}
2) {{ctx2}}
Soru: {{q}}
";
var qa = kernel.CreateFunctionFromPrompt(qaPrompt);
var variables = new KernelArguments
{
["ctx1"] = contexts.ElementAtOrDefault(0) ?? "",
["ctx2"] = contexts.ElementAtOrDefault(1) ?? "",
["q"] = "Kaç gün ücretli izin devredebilirim?"
};
var answer = await qa.InvokeAsync(kernel, variables);
Console.WriteLine(answer);
Yaygın Tuzaklar (ve Bunlardan Nasıl Kaçınılır)
- Tek dev istek: Fonksiyonlara ayırın; yalnızca ihtiyacınız olan bağlamı geçirin.
- Çıktı sözleşmesi yok: Makine tarafından okunabilir adımlar için her zaman şemalar tanımlayın.
- Hijyen olmadan RAG: İyi parçalara ayırın, yinelenenleri kaldırın ve alaka ve güncelliğe göre sıralayın.
- Araç yayılımı: Eklenti arayüzlerini küçük ve belgelenmiş tutun.
- İnsan döngüsü yok: Yüksek riskli eylemler için onaylar ekleyin.
Semantic Kernel'i Ön Uçlarla Nasıl Kullanılır
- Web uygulamaları: SK düzenlemenizi bir API katmanında barındırın; jetonları kullanıcı arayüzüne aktarın.
- Sohbet kullanıcı arayüzleri: Sunucu tarafında konuşma durumunu koruyun; budayın ve özetleyin.
- Kimlik doğrulama: Kimliğe bürünme güvenli çağrıları—modelin asla jeton basmasına izin vermeyin. Araç çağrılarını arka ucunuz aracılığıyla geçirin.
Dağıtım Kontrol Listesi
- Anahtarlar ve uç noktalar için ortam değişkenleri
- Model/araç çağrıları için hız sınırlaması ve yeniden denemeler
- İstek şablonu kaynak kontrolü
- Vektör deposu yedeklemeleri ve PII işleme
- Gözlemlenebilirlik panoları (gecikme, maliyet, hatalar)
- İstekler ve yönlendirme için A/B testi
SSS Tarzı Sorun Giderme
- “Model, RAG ile bile halüsinasyon görüyor.” Talimatları sıkılaştırın: "Yalnızca bağlamdan cevap verin" ve bir ret örneği ekleyin. Geri alma özgüllüğünü artırın ve sıcaklığı azaltın.
- “JSON sürekli bozuluyor.” Geçerli JSON'un mini bir örneğini ekleyin ve yorumu yasaklayın. Başarısızlık durumunda çağrı sonrası doğrulayın ve yeniden ifade edin.
- “Gecikme yüksek.” Daha az, daha alakalı parça alın; basit adımları daha küçük modellere geçirin; bağımsız adımları paralelleştirin.
- “Maliyetler artıyor.” Önbelleğe alın, bağlamı sıkıştırın ve kolay görevleri daha ucuz modellere yönlendirin.
Kayda Değer: Sider.AI ile Daha Hızlı Oluşturun
İsteklerin prototipini oluşturuyorsanız, araç akışlarını test ediyorsanız veya modeller arasında yanıtları karşılaştırıyorsanız, Sider.ai gibi bir yardımcı yinelemeyi hızlandırabilir. İstekleri taslak haline getirebilir, A/B karşılaştırmaları yapabilir ve bunları Semantic Kernel şablonlarına taşımadan önce yeniden kullanılabilir snippet'ler yakalayabilirsiniz—talimatları ve çıktı şemalarını keskinleştirmek için harika. Sonraki Adımlar: Bunu Çalışan Bir Aracıya Dönüştürün
- Net bir görevle başlayın (örn., destek e-postalarını sınıflandırın).
- Katı giriş/çıkışlarla semantik/yerel fonksiyonlar tanımlayın.
- Yalnızca cevapları ölçülebilir şekilde iyileştirdiği yerlerde bellek ekleyin.
- Her şeyi ölçün; gerçek dünya örnekleriyle test edin.
- Bir sanal alan kullanarak istekleri yineleyin, ardından SK'da kodlayın.
Temel çıkarımlar:
- Semantic Kernel, istekleri, araçları ve belleği güvenilir iş akışları halinde birleştirmenize yardımcı olur.
- Sağlamlık ve maliyet kontrolü için çıktı şemalarını, planlayıcıları ve çok modelli yönlendirmeyi kullanın.
- Koruyucu raylarla RAG, her zaman dev istekleri yener.
Bu desenlerle Semantic Kernel'i nasıl kullanacağınızı öğrendikten sonra, yalnızca etkileyici demolar değil, aynı zamanda güvenilir sistemler olan yapay zeka özellikleri göndereceksiniz.
SSS
S1:Semantic Kernel, yapay zeka uygulamalarında ne için kullanılır?
Semantic Kernel, LLM isteklerini, araçları (yerel fonksiyonlar) ve belleği birleştiren yapay zeka iş akışları oluşturmak için bir düzenleme SDK'sıdır. Görevleri yapılandırmanıza, RAG eklemenize ve birden fazla modeli güvenilir bir şekilde çağırmanıza yardımcı olur.
S2:Belgelerimle RAG için Semantic Kernel'i nasıl kullanırım?
Belgelerinizi SK'nın bellek API'leri aracılığıyla bir vektör deposuna alın, ardından sorgu başına en alakalı parçaları alın ve bunları isteğinize enjekte edin. Bu, doğruluğu artırır ve halüsinasyonları azaltır.
S3:Semantic Kernel harici API'leri ve hizmetleri çağırabilir mi?
Evet. API'leri bir eklentide yerel fonksiyonlar olarak sarın ve modelin bunları araç olarak kullanabilmesi için bunları çekirdeğe kaydedin. Arayüzleri küçük tutun ve giriş/çıkış doğrulamasını zorunlu kılın.
S4:Semantic Kernel ile hangi modeller çalışır?
Semantic Kernel, OpenAI, Azure OpenAI ve diğer bağlayıcıları destekler. Görevleri farklı modellere yönlendirebilirsiniz—örneğin, taslaklar için daha küçük modeller ve akıl yürütme yoğun adımlar için daha büyük modeller.
S5:Semantic Kernel çıktılarının tutarlı (örn., JSON) olmasını nasıl sağlarım?
Katı JSON talep eden ve minimal bir örnek veya şema içeren yapılandırılmış istekler kullanın. Düşük sıcaklık ayarlayın, çağrı sonrası çıktıları doğrulayın ve ayrıştırma başarısız olduğunda yeniden deneyin veya onarın.