Semantic Kernel Nedir? Microsoft'un Yapay Zeka Orkestrasyonu SDK'sı

Microsoft ekosisteminde yazılım geliştiriyor ve yapay zeka özellikleri eklemek için ayrı bir Python servisi yazmak istemiyorsanız, Semantic Kernel kullanışlı bir SDK seçeneğidir. Mevcut kodunuzu ve API'lerinizi büyük dil modellerine bağlayan açık kaynaklı bir kittir; C#, Python ve Java ile çalışır. Bu rehberde Semantic Kernel’in ne yaptığını, kernel/eklenti/fonksiyon yapısını ve OpenAPI belirtim desteğiyle REST API’lerinizi modelin çağırabileceği araçlara nasıl dönüştürebileceğinizi göreceksiniz.

Apidog'u bugün deneyin

Semantic Kernel aslında nedir

Semantic Kernel (SK), yapay zeka ajanları oluşturmak ve modelleri mevcut kod tabanınıza entegre etmek için Microsoft tarafından geliştirilen hafif, açık kaynaklı bir SDK’dır.

Pratikte SK’yi uygulamanız ile model arasında çalışan bir ara katman olarak düşünebilirsiniz:

1. Uygulamanız bir istek gönderir.
2. Model, hangi fonksiyonu çağırması gerektiğine karar verir.
3. Semantic Kernel bu isteği gerçek kodunuza veya API’nize yönlendirir.
4. Sonucu tekrar modele verir.
5. Model nihai yanıtı üretir.

Semantic Kernel’i öne çıkaran üç nokta vardır:

• Çok dilli destek: C#/.NET, Python ve Java için resmi SDK’lar sunar. Özellikle .NET ekipleri için Python tabanlı ajan framework’lerine göre daha doğal bir entegrasyon sağlar.
• Modelden bağımsız yapı: OpenAI, Azure OpenAI ve diğer sağlayıcılarla bağlayıcılar üzerinden çalışır. Model değiştirmek istediğinizde genellikle uygulama kodunu değil yapılandırmayı değiştirirsiniz.
• Kurumsal kullanım odağı: Telemetri, filtreler ve kancalar sayesinde modelin hangi aracı ne zaman çağırdığını loglayabilir, denetleyebilir ve gerektiğinde müdahale edebilirsiniz.

Kernel, eklentiler ve fonksiyonlar

Semantic Kernel’de ana nesne kernel’dir. Bunu yapay zeka orkestrasyonu için bir bağımlılık enjeksiyon kapsayıcısı gibi düşünebilirsiniz.

Kernel’e şunları kaydedersiniz:

• Kullanacağınız model bağlayıcısı
• Modele açacağınız eklentiler
• Modelin çağırabileceği fonksiyonlar

Bir eklenti, modele açılan adlandırılmış fonksiyon grubudur. Bir fonksiyon ise modelin çağırabileceği tek bir yetenektir.

Semantic Kernel’de iki temel fonksiyon tipi vardır:

• Yerel fonksiyonlar: Kendi kodunuzdaki normal metotlar veya fonksiyonlardır. Örneğin bir C# metodu ya da Python fonksiyonu.
• İstem fonksiyonları: Modelin kendisini çağıran şablonlanmış prompt’lardır. Özetleme, sınıflandırma veya yeniden yazma gibi işler için kullanılır.

Basit bir C# örneği:

var builder = Kernel.CreateBuilder();

builder.AddOpenAIChatCompletion("gpt-4o", apiKey);

builder.Plugins.AddFromType<LightsPlugin>("Lights");

Kernel kernel = builder.Build();

var result = await kernel.InvokePromptAsync("Turn the kitchen light blue");

Bu örnekte akış şu şekildedir:

1. Kernel oluşturulur.
2. Sohbet modeli kaydedilir.
3. LightsPlugin eklenti olarak eklenir.
4. Kullanıcı prompt’u çalıştırılır.
5. Model gerekirse LightsPlugin içindeki uygun fonksiyonu çağırır.

Örneğin model change_light_state fonksiyonunu çağırmak isterse, kernel ilgili metodu çalıştırır, sonucu alır ve modele geri iletir. Semantic Kernel’in temel döngüsü budur.

OpenAPI’den eklentiye deseni

Semantic Kernel’in en pratik özelliklerinden biri, bir OpenAPI belirtimini doğrudan eklenti olarak içe aktarabilmesidir.

Bu desen sayesinde:

• REST API’niz için özel wrapper kodu yazmanız gerekmez.
• OpenAPI dosyanızdaki her endpoint, modelin çağırabileceği bir fonksiyona dönüşür.
• Parametre adları, açıklamalar, tipler ve şemalar modele araç açıklaması olarak verilir.

C# tarafında kullanılan metot ImportPluginFromOpenApiAsync’tir. Python tarafında karşılığı add_plugin_from_openapi’dir. Java SDK’sında da eşdeğer içe aktarma desteği bulunur.

C# ile bir OpenAPI belirtimini URL’den içe aktarma örneği:

await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "lights",
    uri: new Uri("https://example.com/v1/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        EnablePayloadNamespacing = true
    }
);

Bu kod çalıştığında Semantic Kernel şu işleri yapar:

1. OpenAPI belirtimini indirir.
2. Endpoint’leri ve operation bilgilerini ayrıştırır.
3. Her işlemi çağrılabilir bir fonksiyona dönüştürür.
4. Parametre açıklamalarını ve şemaları modele verir.
5. Model bir fonksiyon seçtiğinde HTTP isteğini oluşturur.
6. Kimlik doğrulama ve execution parametrelerini uygular.
7. API yanıtını modele geri iletir.

Semantic Kernel, OpenAPI 2.0 ve 3.0’ı destekler. OpenAPI 3.1 belirtimlerini ise mümkün olduğunca 3.0’a düşürerek işler.

Burada dikkat edilmesi gereken nokta şudur: İnsanlar için yeterince açık olan bir OpenAPI belirtimi, model için her zaman yeterince açık olmayabilir. Daha iyi araç çağrıları için belirtiminizi şu şekilde hazırlayın:

• Açıklayıcı operationId değerleri kullanın.
• Parametre açıklamalarını kısa ama net yazın.
• Gereksiz endpoint’leri modele açmayın.
• Serbest metin alanları yerine enum ve tipli parametreler kullanın.
• Yanıt şemalarını eksiksiz tanımlayın.
• Hata yanıtlarını da belirtime ekleyin.

OpenAPI kalitesi doğrudan ajan davranışını etkiler. Belirtim ne kadar temizse, modelin doğru endpoint’i doğru parametrelerle çağırma ihtimali o kadar artar.

Ajanlar ve planlama

Semantic Kernel ilk dönemlerinde hedefleri adımlara bölen açık planlayıcılarla öne çıkıyordu. Daha yeni yaklaşımda ise ağırlık fonksiyon çağırmaya kaydı. Modern modeller, hangi fonksiyonu hangi sırayla çağıracaklarına çoğu senaryoda kendileri karar verebiliyor.

Semantic Kernel ayrıca ajan ve çoklu ajan desenleri için bir Agent Framework katmanı da sağlar. Bu katmanda şunlar bulunur:

• Oturum tabanlı durum yönetimi
• Ajan döngüleri
• Harici araç bağlama
• Model Bağlam Protokolü (MCP) desteği

Diğer ajan SDK’larıyla karşılaştırıldığında genel konumlandırma şöyledir:

Çerçeve	Birincil diller	Orkestrasyon modeli	En uygun
Semantic Kernel	C#/.NET, Python, Java	Fonksiyon çağırma + ajanlar	.NET ve kurumsal ekipler
LangGraph	Python, JS	Açık durum grafiği	Karmaşık, dallanan ajan akışları
Google ADK	Python	Ajan + araç modeli	Google Cloud ve Gemini yığınları
OpenAI Agents SDK	Python, JS	Ajanlar + devirler	OpenAI merkezli uygulamalar

Burada tek bir “en iyi” seçenek yoktur. Seçim; kullandığınız dile, model sağlayıcınıza, mevcut API’lerinize ve yürütme akışı üzerinde ne kadar kontrol istediğinize bağlıdır.

Semantic Kernel, Microsoft Agent Framework ile nereye oturur

Microsoft, Microsoft Agent Framework’ü (MAF) tanıttı ve belgelerde bunu Semantic Kernel ile AutoGen’in doğrudan halefi olarak konumlandırdı. MAF, AutoGen’in ajan soyutlamalarını Semantic Kernel’in kurumsal özellikleriyle birleştirir ve çoklu ajan orkestrasyonu için grafik tabanlı iş akışları ekler.

Pratikte durum şu şekilde okunabilir:

• Semantic Kernel kararlı ve desteklenen bir seçenektir.
• Mevcut Semantic Kernel uygulamaları çalışmaya devam eder.
• 1.0+ sürüm kararlılık taahhüdü geçerlidir.
• Yeni ajan projeleri için Microsoft, Agent Framework’e yönlendirme yapar.
• SK’den MAF’a geçiş için rehberler sağlanır.
• OpenAPI’den eklentiye yaklaşımı iki tarafta da önemini korur.

Bu yüzden mevcut uygulamanız Semantic Kernel üzerindeyse acil bir taşıma ihtiyacı yoktur. Yeni bir ajan projesine başlıyorsanız ve Microsoft’un en güncel yönünü takip etmek istiyorsanız, karar vermeden önce MAF belgelerini incelemek mantıklıdır.

Semantic Kernel ne zaman kullanılır

Semantic Kernel şu durumlarda güçlü bir seçenektir:

• Backend’iniz .NET veya Java ise ve yapay zeka orkestrasyonunun mevcut yığınınıza yerel hissettirmesini istiyorsanız.
• Mevcut REST API’lerinizi OpenAPI belirtimleri üzerinden modele araç olarak açmak istiyorsanız.
• Telemetri, filtreler, kancalar ve denetlenebilirlik gibi kurumsal özelliklere ihtiyacınız varsa.
• Model sağlayıcısına bağımlı kalmadan OpenAI, Azure OpenAI veya başka sağlayıcılar arasında geçiş yapabilmek istiyorsanız.
• Kod tabanınızda zaten iyi tanımlanmış servisler ve API sözleşmeleri varsa.

Buna karşılık, ekibiniz tamamen Python odaklıysa ve en yeni çoklu ajan özelliklerini kullanmak istiyorsa, Microsoft Agent Framework veya grafik tabanlı bir ajan kütüphanesi daha uygun olabilir.

Semantic Kernel ajanınızın arkasındaki API’leri test etme

API araçlarının önemli olduğu nokta burasıdır ve Apidog bu akışa doğrudan uyar.

Semantic Kernel API’lerinizi oluşturmaz veya düzeltmez; onları çağırır. Bu yüzden ajanınızın bağlı olduğu uç noktaların doğru, tanımlı ve güvenilir olması gerekir.

Bir Semantic Kernel ajanı genellikle iki tür endpoint’e bağlıdır:

• Konuştuğu LLM endpoint’i
• OpenAPI eklentisi olarak içe aktardığınız REST API’ler

Ajan davranışını daha güvenilir hale getirmek için şu adımları uygulayın:

1. OpenAPI belirtimini içe aktarmadan önce doğrulayın

Semantic Kernel, belirtimdeki her işlemi fonksiyona dönüştürür. Bu yüzden eksik veya belirsiz açıklamalar doğrudan hatalı araç çağrılarına yol açabilir.

Kontrol edin:

• Her endpoint çalışıyor mu?
• Parametre tipleri doğru mu?
• Zorunlu alanlar net mi?
• Yanıt şemaları gerçek yanıtlarla eşleşiyor mu?
• operationId değerleri modelin anlayabileceği kadar açıklayıcı mı?

Temiz sözleşme, daha güvenilir ajan davranışı üretir.

2. Geliştirme sırasında bağımlılıkları mock edin

Henüz hazır olmayan endpoint’ler için sahte bir API kurabilirsiniz.

Bu özellikle şu durumlarda faydalıdır:

• Backend endpoint’i henüz geliştirilmediyse
• LLM çağrılarında token harcamak istemiyorsanız
• Rate limit’e takılmadan ajan orkestrasyonunu debug etmek istiyorsanız
• Farklı yanıt senaryolarını test etmek istiyorsanız

Desen için API çağrılarını nasıl taklit edeceğinizi inceleyebilirsiniz.

3. Yanıt şekillerini assertion ile sabitleyin

Ajanınız bir API endpoint’ini çağırdığında model belirli bir yanıt yapısı bekler. Backend tarafındaki sessiz bir değişiklik, ajan davranışını bozabilir.

Bunu önlemek için API iddialarını kullanarak şunları doğrulayın:

• HTTP durum kodu
• Zorunlu alanlar
• Alan tipleri
• Enum değerleri
• Hata yanıtları
• Şema uyumluluğu

4. Anahtarları ortama göre yönetin

LLM ve API kimlik bilgilerini kod içine yazmayın. Bunun yerine ortam bazlı yapılandırma kullanın:

• Development
• Staging
• Production

Bu yaklaşım hem güvenliği artırır hem de ajan davranışını farklı ortamlar arasında daha kontrollü test etmenizi sağlar.

Daha kapsamlı bir test yaklaşımı için Apidog ile bir ajanın araç çağrılarını test etme rehberine bakabilirsiniz.

Sıkça Sorulan Sorular

Semantic Kernel ücretsiz ve açık kaynak mı?

Evet. Semantic Kernel açık kaynaklıdır ve Microsoft tarafından GitHub’da hoşgörülü bir lisans altında yayınlanır. C#/.NET, Python ve Java SDK’ları vardır. Semantic Kernel’in kendisi için ödeme yapmazsınız; OpenAI, Azure OpenAI veya başka bir model sağlayıcısı kullanıyorsanız model kullanımı için ödeme yaparsınız.

Semantic Kernel hangi dilleri destekler?

Semantic Kernel C#/.NET, Python ve Java’yı destekler. Üçü için de 1.0+ sürüm kararlılık taahhütleri bulunur. C# SDK’sı en olgun seçenektir, ancak Python ve Java SDK’ları da kernel, eklenti ve OpenAPI içe aktarma gibi temel özellikleri kapsar.

Semantic Kernel, OpenAPI belirtimlerini nasıl kullanır?

Bir OpenAPI belirtimini C# tarafında ImportPluginFromOpenApiAsync, Python tarafında ise add_plugin_from_openapi ile içe aktarırsınız. Semantic Kernel belirtimi ayrıştırır, her işlemi parametre meta verileriyle çağrılabilir bir fonksiyona dönüştürür ve modelin bu işlemleri çağırmasına izin verir.

Model açıklamalarınıza güvendiği için belirtimi içe aktarmadan önce doğrulamak önemlidir. Belirtimi ve canlı endpoint’leri Apidog ile test edebilirsiniz.

Semantic Kernel mi yoksa Microsoft Agent Framework mü kullanmalıyım?

Halihazırda Semantic Kernel kullanan bir uygulamanız varsa kullanmaya devam edebilirsiniz; SK desteklenir ve kararlıdır. Yeni projelerde Microsoft, Agent Framework’ü halef olarak konumlandırır. Bu yüzden yeni bir projeye başlamadan önce güncel MAF belgelerini kontrol etmek iyi bir fikirdir.

Her iki yaklaşımda da API’lerin doğru çalışması kritik olduğu için, araç çağrılarınızın bağlı olduğu endpoint’leri test etmeniz gerekir. Bunun için ChatGPT API’sini Apidog ile nasıl test edeceğinize bakabilirsiniz.

Özetle

Semantic Kernel, Microsoft ekosistemindeki ekipler için yapay zekayı mevcut uygulamalara bağlamanın pratik bir yoludur. Kernel modeli orkestre eder, eklentiler ve fonksiyonlar modele araç sağlar, OpenAPI içe aktarma desteği ise mevcut REST API’lerinizi ajanların çağırabileceği fonksiyonlara dönüştürür.

Semantic Kernel kararlı ve üretimde kullanıma uygundur. Microsoft’un en yeni ajan yatırımı ise Agent Framework tarafına kaymaktadır. Hangi yaklaşımı seçerseniz seçin, ajanın çağırdığı API’lerin sağlam olması gerekir.

Ajanınızın bağımlı olduğu belirtimleri ve endpoint’leri tasarlamak, mock etmek ve test etmek için Apidog’u indirin ve ajanınız çağırmadan önce API sözleşmesini doğrulayın.