Adım Adım .NET Uygulamalarına OpenAI API Entegrasyonu Rehberi

Yazılım projelerine yapay zeka özelliklerini dahil etmek artık bir lüks değil, temel bir gereksinim haline geldi. Özellikle B2B SaaS platformları, çok kiracılı (multi-tenant) mimariler veya ERP sistemleri geliştiriyorsanız, verileri anlamlandırmak veya arka planda otomasyonlar kurmak ciddi bir avantaj sağlıyor. Python bu alanda standart kabul edilse de, backend tarafında .NET kullanan projeler için LLM (Büyük Dil Modeli) entegrasyonu sanıldığından çok daha basittir. Dışarıdan hazır ve ağır kütüphanelere bağımlı kalmadan, doğrudan REST API üzerinden C# mimarisiyle bu süreci nasıl standart, güvenli ve performanslı bir şekilde kurgulayacağınızı adım adım özetlemek istedim.

1. OpenAI Platformunda Hesap ve API Anahtarı Oluşturmak Her şeyden önce istekleri yetkilendirebilmek için bir API anahtarına ihtiyacınız var.

• Kayıt ve Key Üretimi: platform.openai.com adresine gidip geliştirici hesabı oluşturun. Sol menüden "API keys" sekmesine geçip "Create new secret key" butonuna tıklayın.
• Önemli Not: Üretilen bu anahtarı (sk-... ile başlayan metin) sadece bir kez görebilirsiniz. Kapatmadan önce güvenli bir yere kopyaladığınızdan emin olun.
• Bakiye ve Limitler: API kullanımı token bazlı ve ücretlidir. "Billing" sekmesinden kredi kartı tanımlayıp minimum bir bakiye yüklemeniz gerekir. Aksi takdirde entegrasyon sırasında sürekli 429 Too Many Requests veya Insufficient Quota hataları alırsınız.

2. .NET Projesinde Gizli Anahtar (Secret) Yönetimi API anahtarını asla doğrudan kodun içine (hardcoded) yazmamalısınız. Kod deposuna yanlışlıkla commit'lenen anahtarlar saniyeler içinde iptal edilebilir.

• Local Development: Geliştirme ortamında anahtarı güvenli tutmak için .NET Secret Manager kullanın. Terminalden dotnet user-secrets set "OpenAI:ApiKey" "sk-..." komutunu çalıştırarak anahtarı projenize tanımlayın.
• Production: Uygulamayı canlı sunucuya aldığınızda (örneğin Docker container içinde koştururken), bu değeri Environment Variables (Çevre Değişkenleri) üzerinden okumanız gerekir. appsettings.json dosyasında sadece konfigürasyon ağacını belirtin, asıl değerleri sunucu ortamından verin.

3. HttpClient Yapılandırması (Dependency Injection) Her API isteğinde yeni bir HttpClient nesnesi oluşturmak, yüksek trafikli uygulamalarda soket tükenmesine (socket exhaustion) yol açar.

• Program.cs Ayarları: Program.cs (veya Startup.cs) dosyanıza gidip servisi şu şekilde kaydedin:

builder.Services.AddHttpClient("OpenAI", client => {
    client.BaseAddress = new Uri("https://api.openai.com/v1/");
    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {builder.Configuration["OpenAI:ApiKey"]}");
});

Bu yapılandırma, Base URL'i ve yetkilendirme başlığını (Bearer Token) merkezi bir yerde çözmenizi sağlar.

4. Request ve Response Modellerinin Hazırlanması OpenAI'nin chat/completions endpoint'i belirli bir JSON formatı bekler ve yapılandırılmış bir JSON döndürür.

• DTO'lar (Data Transfer Objects): İstek atmak için C# record veya class yapılarını oluşturun.

public record GptRequest(string Model, List<Message> Messages, double Temperature);
public record Message(string Role, string Content);

• Yanıt Modeli: Dönen yanıttaki choices array'ini ve içindeki content verisini yakalamak için bir GptResponse modeli tanımlamanız gerekir. Nesne property isimleri ile JSON anahtarları uyuşmuyorsa [JsonPropertyName] attribute'unu kullanmayı unutmayın.

5. İstek Atma ve Yanıtı İşleme Artık veriyi gönderip sonucu alma aşamasına geldik.

• Servis Sınıfı: Dependency Injection ile aldığınız IHttpClientFactory üzerinden "OpenAI" isimli client'ı çağırın (_httpClientFactory.CreateClient("OpenAI")).
• JSON Serileştirme: Hazırladığınız GptRequest nesnesini System.Text.Json.JsonSerializer ile JSON formatına çevirin ve StringContent olarak, UTF-8 kodlamasıyla ve application/json medya türüyle hazırlayın.
• Post İşlemi: await client.PostAsync("chat/completions", content) komutuyla isteği atın.
• İşte burası çok önemli: Dönen yanıtın IsSuccessStatusCode değerini mutlaka kontrol edin. Eğer true ise, dönen JSON içeriğini deserialize ederek asıl metni dışarı aktarın. Hata durumunda ise dönen mesajı log mekanizmanıza yazdırın.

6. Performans ve Maliyet Kontrolü AI entegrasyonlarında donanımsal kaynaklardan ziyade API maliyetleri ve işlem süreleri ön plandadır.

• Token Sınırları: İstek atarken modelin parametrelerine max_tokens değeri ekleyerek dönen yanıtın uzunluğunu kısıtlayın. Bu sayede sonsuz döngüye giren veya gereksiz uzayan yanıtların faturanızı şişirmesini engellersiniz.
• Timeout Ayarları: LLM'ler standart veritabanı sorgularına göre çok daha geç yanıt verebilir. Kapsamlı bir metin üretimi 10-15 saniye sürebilir. Bu nedenle HttpClient yapılandırmanızdaki Timeout süresini uygulamanızın akışına göre esnetmeniz gerekebilir.