Dil modeli API'sini kurumsal sistemlere bağlama: mimari, hata yönetimi ve güvenlik

Entegrasyonun zor kısmı model çağrısı değil, çevresidir

Bir dil modeli API'sine istek göndermek, HTTP üzerinden bir JSON gövdesi yollayıp yanıt almaktır. Bir saat içinde çalışan bir örnek çıkar. Kurumsal entegrasyonda asıl iş, bu çağrının etrafındaki her şeydir: isteğin hangi sistemden, hangi yetkiyle geldiği, içine hangi verinin girdiği, yanıtın hangi sisteme hangi biçimde döndüğü, hata anında iş akışının ne yaptığı ve harcamanın kimin bütçesine yazıldığı.

Bu yüzden entegrasyon projeleri genellikle bir yazılım mimarisi ve operasyon işidir. Modelin ne kadar iyi yazdığı kadar, çağrının kuyruğa alınıp alınmadığı, aynı siparişin tekrar işlenip işlenmediği ve bir sağlayıcı kesintisinde müşteri ekranının donup donmadığı da sonucu belirler.

Başlamadan önce şu soruları yazılı hale getirmek işi kısaltır: • Model hangi iş adımında devreye giriyor ve çıktısını kim tüketiyor (insan mı, başka bir servis mi)? • Girdiye kişisel veri ya da ticari sır giriyor mu? • Yanıt gecikirse iş akışı bekleyebilir mi, yoksa kullanıcı ekranda mı bekliyor? • Model yanlış yanıt verirse zarar nerede ortaya çıkar ve kim yakalar?

Doğrudan çağrı yerine ara servis katmanı kurma

ERP, CRM ya da bilet sistemi gibi uygulamaların sağlayıcı anahtarını kendi içinde taşıması sürdürülebilir değildir. Anahtar her uygulamaya dağılır, harcama izlenemez, model ya da sağlayıcı değiştirmek her sistemde ayrı kod değişikliği ister. Yaygın çözüm, tüm çağrıların geçtiği tek bir iç servis ya da ağ geçidi kurmaktır.

Bu katmanın üstlendiği işler şunlardır: • Sağlayıcı anahtarını tek yerde, gizli bilgi kasasında tutmak; çağıran sistemlere yalnızca kendi iç kimliklerini vermek. • Hangi uygulamanın hangi modele ve hangi bütçeye erişebildiğini kural olarak tanımlamak. • İstek ve yanıt günlüğünü, maskeleme uygulandıktan sonra, merkezi bir yerde toplamak. • Hız sınırı ve yeniden deneme mantığını bir kez yazmak. • Model adını yapılandırmadan okumak; böylece yeni bir model sürümüne geçiş uygulamaları değiştirmeden yapılabilir.

Küçük ekipler için bu katman hafif bir servis olabilir. Büyüdükçe önbellek, model yönlendirme ve yedek sağlayıcıya düşme eklenir. Önemli olan, iş uygulamasının "hangi sağlayıcı" sorusunu hiç bilmemesidir.

Bir isteğin anatomisi: kimlik, gövde, yanıt

Anthropic'in Messages API'sinde istek, kimlik doğrulama için x-api-key başlığı, sürüm için anthropic-version başlığı ve JSON gövdesinden oluşur. Gövdedeki zorunlu alanlar model adı, üretilecek en fazla token sayısını belirten max_tokens ve dönüşümlü kullanıcı/asistan mesajlarından oluşan messages dizisidir. Sistem talimatı ayrı bir system alanıyla verilir; mesaj dizisinde sistem rolü yoktur. Diğer sağlayıcıların alan adları farklıdır ama mantık aynıdır: kimlik, model, talimat, mesajlar, üst sınır.

Yanıtta üretilen içerik blokları, neden durduğunu söyleyen bir durma nedeni ve harcanan girdi/çıktı token sayısı gelir. Durma nedeni entegrasyonda önemlidir: yanıt üst sınıra çarpıp kesilmişse, aşağıdaki sistem eksik bir metni tam sanabilir. Bu yüzden kesilen yanıtlar başarı gibi işlenmemelidir. Kullanım bilgisi ise maliyet takibi için ham veridir; her çağrıyla birlikte uygulama, kullanıcı ve iş türü etiketiyle kaydedilmelidir.

Kurumsal bir sarmalayıcı, bu ayrıntıları iş koduna sızdırmadan şuna benzer bir arayüz sunar:

result = llm_service.complete(task="invoice_summary", input_text=invoice_text, user=requester)

Görev adı, arkada hangi sistem talimatının, hangi modelin ve hangi çıktı biçiminin kullanılacağını belirler. Prompt metinleri iş uygulamasının içinde dağınık durmaz, sürümlenmiş tek bir yerde yaşar.

Hata türleri ve yeniden deneme mantığı

Sağlayıcı çağrıları üretim ortamında düzenli olarak başarısız olur ve bu normaldir. Anthropic belgeleri hataları türleriyle ayırır: invalid_request_error istek biçimindeki sorunu, authentication_error anahtar sorununu, permission_error yetki sorununu, request_too_large aşırı büyük isteği, rate_limit_error hız sınırı aşımını, api_error sağlayıcı tarafındaki beklenmedik hatayı, timeout_error zaman aşımını ve overloaded_error geçici aşırı yükü anlatır. Belgeler, resmî SDK'nın geçici hataları (bağlantı sorunları, hız sınırı, sunucu hataları) üstel bekleme ile otomatik yeniden denediğini ve retry-after başlığına uyduğunu belirtir.

Buradan çıkan kural şudur: istek biçimi, kimlik ve yetki hataları yeniden denemeyle düzelmez; hemen yukarı bildirilmelidir. Hız sınırı, aşırı yük, zaman aşımı ve sunucu hataları ise sınırlı sayıda ve rastgele sapmalı beklemeyle yeniden denenebilir. Basit bir iskelet:

for deneme in range(MAKS_DENEME): try: return istemci.mesaj_olustur(model=MODEL_ADI, max_tokens=UST_SINIR, messages=mesajlar) except GeciciHata: bekle(TABAN_SURE * (ustel(ARTIS, deneme)) + rastgele_sapma()) raise KaliciHata

Her yanıtın request-id başlığını günlüğe yazın. Sağlayıcı desteğiyle konuşurken bu kimlik, olayın bulunmasını sağlayan tek şeydir. Yeniden deneme yapan her katman maliyeti de çarpar; bu yüzden hem uygulamada hem ağ geçidinde aynı anda yeniden deneme açmayın.

Uzun istekler, akış ve toplu işleme

Sağlayıcı belgeleri, büyük bir max_tokens değeriyle uzun üretim yapan isteklerde akışlı (streaming) çağrıyı ya da toplu işleme arayüzünü önerir; çünkü bazı ağlar uzun süre veri akmayan bağlantıları keser. Kullanıcının ekranda beklediği senaryolarda akış, ilk sözcüklerin hemen görünmesini sağlar. Gece raporu, toplu belge özetleme gibi acelesi olmayan işlerde toplu arayüz hem ağ kesintisi riskini azaltır hem de sonuçları sorgulayarak almanıza izin verir.

Akışta dikkat edilecek bir ayrıntı vardır: bağlantı başarıyla açıldıktan sonra da akışın ortasında hata olayı gelebilir. Bu durumda alışılmış HTTP hata yönetimi devreye girmez; istemci akış içindeki hata olaylarını ayrıca dinlemelidir.

Kurumsal sistemlerle bağlantıda şu ayrım işe yarar: • Kullanıcı etkileşimli akış: akışlı çağrı, kısa zaman aşımı, yedek mesaj. • Sistem arası arka plan işi: kuyruk, toplu çağrı, sonucu veritabanına yazma. • Olay tetiklemeli iş: webhook ya da mesaj kuyruğu ile gelen olayı işleyip sonucu geri bildirme.

ERP, CRM ve iç servislerle güvenli bağlama

Dil modeli çağrısını senkron bir ekran isteğinin içine gömmek en yaygın hatadır. Model yavaşladığında ekran donar, kullanıcı tekrar tıklar ve aynı iş yeniden tetiklenir. Daha sağlam düzen, işi kuyruğa bırakmak, bir iş kimliği döndürmek ve sonucu hazır olunca bildirmektir.

Tekrarlanan işlemlere karşı her isteğe eşsiz bir iş anahtarı verin; aynı anahtarla gelen tekrarlanan istek, yeniden model çağırmak yerine kayıtlı sonucu döndürsün. Bu aynı zamanda gereksiz harcamayı da önler.

Veri tarafında şu kontroller kurumsal ortamda pazarlık konusu değildir: • Modele gönderilecek alanları açıkça listeleyin; "tüm kaydı yolla" yaklaşımından kaçının. • Kişisel veri ve gizli alanları göndermeden önce maskeleyin, yanıt geldiğinde geri eşleyin. • Modelin ürettiği metin, başka bir sisteme yazma ya da e-posta gönderme gibi geri dönüşü zor bir işlem yapacaksa araya insan onayı koyun. • Modele verilen araçların yetkisi, isteği başlatan kullanıcının yetkisini aşmasın.

Modelin çağırabileceği işlevler (function calling) tanımlıyorsanız, her işlev için yetki ve parametre doğrulamasını model yanıtına güvenmeden kendi kodunuzda yapın.

Çıktı sözleşmesi, doğrulama ve izleme

Başka bir sistemin tüketeceği çıktı serbest metin olmamalıdır. Modelden belirli bir şemaya uyan JSON istemek, ardından bu şemayı kendi tarafınızda doğrulamak, entegrasyonu öngörülebilir kılar. Doğrulama başarısız olursa kontrollü bir yeniden deneme yapın; yine olmazsa işi insan kuyruğuna düşürün. Sağlayıcıların yapılandırılmış çıktı özellikleri varsa bunları kullanın, ama doğrulamayı kaldırmayın.

İzleme için her çağrıda şunları kaydedin: hangi uygulama ve görev, hangi model adı, kullanılan token miktarı, gecikme, durma nedeni, yeniden deneme sayısı, request-id ve doğrulama sonucu. Bu veriyle şu soruları yanıtlayabilirsiniz: hangi görev bütçeyi tüketiyor, hangi görevde yanıtlar sık kesiliyor, hangi sürüm değişikliği hata oranını artırdı.

Son olarak değişiklik yönetimi: model adı ve prompt metni değiştiğinde davranış değişir. Sabit bir örnek girdi kümesiyle her değişiklikten önce çıktıları karşılaştıran küçük bir regresyon testi, kurumsal entegrasyonda en ucuz güvencedir. Sağlayıcı bir model sürümünü kullanımdan kaldırdığında bu test, geçişin güvenli olup olmadığını gösterir.

Bu beceriyi Mindset programlarında nerede çalışırsınız

"API ile Kurumsal Sistemlere Dil Modeli Entegrasyonu" eğitimi, mevcut iş uygulamalarına dil modeli bağlamak zorunda olan yazılım ve entegrasyon ekipleri için kurgulanmıştır. Modül başlıkları, bu sayfadaki ara katman, ölçeklenebilir dağıtım ve hibrit/yerel model sorularını karşılar: Kurumsal Sistem Entegrasyon Mimarisi, Ölçeklenebilir ve Güvenilir Dağıtım ve Uçtan Uca Kurumsal Entegrasyon Projesi.

"OpenAI ve Anthropic API ile Geliştirme" ise farklı sağlayıcıların API'lerini yan yana kullanıp araç çağırma ve üretim güvenliği konularına giren geliştiriciler için uygundur. Kurumsal ekipler için bu eğitimler birlikte düşünülebilir: biri mimariyi, diğeri sağlayıcıya özgü geliştirmeyi ele alır.