Laravel AI Entegrasyonu: Üretim İçin Hazır Mimarisi Rehberi (OpenAI, Gemini, Claude)

Laravel ile AI entegrasyonuna başlamak her zaman benzer şekilde gerçekleşir. Öncelikle bir paket kurarsınız, .env dosyasına bir API anahtarı ekler, bir kontrolcü metodu yazar ve isteği tetiklendiğinde çalışır. Ardından ürünü yayımlarsınız. Fakat ilk üretim hatasını aldığınızda, örneğin, 429 rate limit bir müşteri yüzlü özelliği 2AM’de suskun hale getirirse, bir Gemini modelinin kullanım dışı kalması, üç sprint önce bir iş akışını bozarsa veya bir token döngüsü ayda harcamanızın dört saat içinde yanmasına yol açarsa, gerçekler ortaya çıkar.

İşte o an Laravel AI entegrasyonunun bir API sorunu olmadığını anlarsınız. Bu, bir mimari sorunudur. API çağrısı kolay kısımdır. Zor olan, AI davranışını öngörülebilir, maliyet kontrol altında ve sağlayıcıdan bağımsız hale getiren katmanı inşa etmektir.

Bu rehber, herhangi bir sağlayıcının kimlik doğrulama akışını incelemez. Sistem düzeyindeki haritayı sunar: problem alanı, buna yönelik mimari kalıplar, OpenAI, Gemini ve Claude’in net bir karşılaştırması ve bir sonraki toplantınızdan önce ekibinizin önüne koyabileceğiniz bir karar çerçevesi sunar.

Laravel AI Entegrasyonu Problem Alanı

Bir sağlayıcı seçmeden veya bir hizmet diyagramı çizmeye başlamadan önce, gerçekte ne inşa ettiğinize dürüst olmalısınız. Üretimde AI’yi zorlaştıran problemler herhangi bir sağlayıcıya özgü değildir. Yapısaldır.

Sağlayıcı Abstraksiyonu

Ürün yaşam döngüsü boyunca sağlayıcıları neredeyse kesinlikle değiştirirsiniz veya birleştirirsiniz. Başlangıçta mantıklı olan model, genellikle ölçeklendikçe, fiyat değişikliklerinde veya kullanım senaryonuz değiştiğinde mantıklı gelmez. Uygulama kodunuz doğrudan OpenAI SDK’sına veya Anthropic istemcisine bağlıysa, bir sağlayıcı değişikliği yalnızca bir yapılandırma değerini değiştirmekle kalmaz, aynı zamanda özellik mantığını yeniden yazmayı gerektirir.

Doğru cevap, uygulamanızın bağımlı olduğu bir sağlayıcı arayüzüdür ve bunun arkasında somut adaptörler bulunur. Aşağıda arayüz sözleşmesi hakkında daha fazla bilgi vereceğiz.

Token Kullanımı ve Maliyet Kontrolü

Dil modelleri token başına ücretlendirir. Bu basit gözükse de, uygulamada, yanlış yapılandırılmış bir istem, kuyruk verimliliğinizle birleştiğinde, bir günde beş rakamlı bir fatura çıkarabilir. Bu duruma tanık olduk.

Token yönetimi üretimde isteğe bağlı değildir. API çağrısı öncesinde bütçe uygulaması, yanıt seviyesinde kullanım kaydı ve harcama eşiğinden geçildiğinde uyarı olmalıdır. Bu, hizmet katmanına aittir – bir kontrolörde değil, zararın gerçekleşmesinden sonra çalışan bir zamanlanmış işte değil.

Gecikme ve Akış

HTTP işleyicisinde senkron bir AI çağrısı neredeyse her zaman yanlıştır. Çıkarma gecikmeleri, hafif bir modelde 800ms’den uzun form mantık görevlerinde 30 saniyeye kadar değişir. PHP-FPM, bu pencere boyunca bağlantıyı açık tutar. Anlamlı trafik altında çalışan aracılarınızı çökertir.

Akış, kullanıcı deneyimi (UX) açısından yardımcı olur, ancak bağlantı baskısı sorununu çözmez. Arka plan işler bunun çözümüdür. Akış seçeneği farklı bir karar olup, aşağıda ayrı bir bölümde ele alınmıştır.

Hata Yönetimi ve Yeniden Deneme

AI API’leri başarısız olur. Trafik yüklenmelerinde 429 döner, model istikrarsızlığında 500 döner ve bazen hiç yanıt gövdesi olmadan zaman aşımı gerçekleşir. Bunların hiçbiri olağan dışı durum değildir. Bunlar sıradan durumlardır.

Yeniden deneme mantığınız, geçici hataları (geri çekilerek yeniden denemeye değer) ve yapısal hataları (yanlış API anahtarı, hatalı yük) ayırt etmelidir. Tüm hataları aynı şekilde ele almak, AI ile entegre edilmiş Laravel uygulamalarında en yaygın üretim hatalarından biridir.

Sağlayıcıya Bağlanma (Vendor Lock-in)

Her sağlayıcı, özel uzantılara sahiptir: işlev çağırma formatları, sistem istemi kuralları, akış olay şekilleri, görsel ek şemaları. Bu şekilleri uygulama mantığınıza katı bir şekilde entegre ettiğiniz anda, bir kez daha değiştirmeye çalıştığınızda bir göç projesi sahibi olursunuz.

Abstraksiyon, bunun hafifletilmesidir. Ancak abstraksiyonun maliyeti vardır. Bunu doğru katmanda inşa edin ve sağlayıcıya özgü davranışları adaptörde tutun, alan hizmetlerinizde değil.

Sağlayıcı Karşılaştırması: OpenAI vs Gemini vs Claude

Her sağlayıcı, her kullanım durumu için doğru yanıt değildir. İşte Laravel AI entegrasyonu için üç baskın seçenek hakkında dürüst bir karşılaştırma.

Her biri hakkında dürüst notlar:

OpenAI, en olgun Laravel ekosistemine sahiptir. Birinci taraf paketi stabildir, API yüzeyi iyi belgelenmiştir ve fonksiyon çağırma ölçekli olarak üretimde test edilmiştir. Genel amaçlı AI özellikleri geliştiren takımlar için sınırlı bir mimari bütçeyle doğru varsayılandır.

Gemininin bir milyon token bağlam penceresi bir pazarlama numarası değildir; belgelerin işlenmesi, uzun oturum hafızası ve RAG’siz alma kalıpları için gerçekten olanakları değiştirir. laravel/ai SDK’sı bunu temiz bir şekilde sarmaktadır. Dezavantajı ise, rate limitlerin tutarsız bir şekilde uygulanmasıdır ve bağlam penceresinin sınırındaki model davranışı, Anthropic’in veya OpenAI’nin davranışlarından daha az öngörülebilir olabilir.

Claude, mantıklı ağır görevler, yapılandırılmış çıktı çıkarımı, kod inceleme hatları ve karmaşık çok aşamalı talimatları güvenilir bir şekilde izleme gerektiren her şey için en tutarlı modeldir. Güvenlik sınırlamaları gerçek olup, bazen kenar durumları için sinir bozucu olabilir; ancak talimat takip etme kalitesi, yüksek riskli özellikler için biraz daha yüksek maliyeti haklı çıkarır.

Laravel AI Sistemleri için Tavsiye Edilen Mimarisi

Tüm sağlayıcılar, tüm ölçekler ve her kullanım durumu için geçerli olan model aynıdır: AI’yı bir tür sözleşmeye gizleyin, her sağlayıcı için somut adaptörler uygulayın ve aktif sağlayıcıyı Servis Konteyneri ile kaydedin.

namespace App\Contracts\AI;

interface AIProviderInterface
{
    public function generate(string $prompt, array $options = []): string;

    public function stream(string $prompt, array $options = []): \Generator;

    public function embed(string $text): array;
}

Her sağlayıcı – OpenAI, Gemini, Claude – bu arayüzü uygulayan kendi adaptör sınıfına sahip olmalıdır. Uygulama servisleriniz, kuyruklanmış işleriniz ve kontrolcüleriniz AIProviderInterface arayüzüne bağımlıdır. Hangi sağlayıcının arkasında durduğunu asla bilemezler.

// AppServiceProvider veya bootstrap/app.php
$this->app->bind(
    \App\Contracts\AI\AIProviderInterface::class,
    \App\AI\Adapters\ClaudeAdapter::class,
);

Sağlayıcılara geçiş artık tek satırlık bir yapılandırma değişikliği. Alan mantığı taşınmıyor.

Bu arayüzün üstünde yönetim katmanınız bulunmalıdır – bütçe kontrolü, telemetri, istem versiyonlama. Laravel’de üretim düzeyinde AI mimarisi üzerine rehberimiz bu katmanı tamamen ele alır, tiplenmiş AiResult veri nesneleri, dekoratör zincirleri ve denetim izi kalıplarını içerir. Adaptör katmanınızı oluşturmadan önce o kılavuzu okuyun; tanımladığı sözleşme, yukarıdaki arayüzü nasıl yapılandıracağınızı bilgilendirecektir.

[Mimari Not] Yukarıdaki üç yöntemli arayüz kasıtlı olarak minimaldir. Sağlayıcıya özgü yetenekleri – görsel girdi, alıntı formatları, araç şemaları – paylaşılan arayüze ekleme konusunda direnin. Bunlar genişletilmiş arayüzlerde veya açıkça tüketilen sağlayıcıya özgü servislerde yer almalıdır. Paylaşılan arayüz, 80% durumunu taşınabilir kılmak içindir. 20% durumu, hangi sağlayıcıyla konuştuğunu bilmeye izin verilir.

Yapılandırma Yönetimi

Sağlayıcı kimlik bilgileri config/ai.php dosyasında bulunmalı, servis sağlayıcı yapıcıları arasında dağılmamalıdır. Her adaptör config('ai.providers.claude.api_key') gibi bir yapıdan veri okur. Ortam değişkenleri yapılandırma katmanından net bir şekilde haritalandırılır ve her sağlayıcı için varsayılanlar tanımlanabilir – sıcaklık, maksimum token, yeniden deneme bütçesi – uygulama kodunuzu dokunmadan.

Token Yönetimi ve Maliyet Kontrolü

Bu, çoğu mimari kılavuzun atladığı bölümde. Ancak bu bölüm, AI özelliğinizin mali açıdan sürdürülebilir olup olmadığını belirleyen bölümdür.

Token maliyetleri katlanarak artar. Günde 500 kez çalışan ve her çağrıda 2,000 token tüketen bir özellik, günlük bir milyon token demektir. Modelin token başına ücretini 30 ile çarptığınızda, bütçe konuşmalarınıza başlangıçtan itibaren dahil edilmesi gereken aylık bir altyapı kalemi elde edersiniz.

Uygulama işlemi önünde bir uygulama noktası olmalıdır. Bu, API çağrısı yapılmadan önce tahmin edilen token sayısını yapılandırılmış bir bütçeye karşı kontrol etmeyi gerektirir; yanıt geldikten sonra değil. Bir kez tüketilen tokenleri geri kazanamazsınız.

Gerçekleştirme süreçleri içeren sistemler için token problemi daha karmaşık hale gelir. İlgili belgeleri bir isteme eklemek, doğruluk için doğru mimari harekettir, ancak her belge parçası girdi token sayısına katkıda bulunur. RAG sistemlerinin, yalnızca istemin bir araya getirilmesi zamanında değil, alım zamanında token’ı dikkate alan parçalara ihtiyaçları vardır. Laravel uygulamanıza alım oluşturuyorsanız, RAG ve vektör alım uygulama kılavuzu parçalama ve gömme stratejisini ayrıntılı olarak ele alır.

Telemetri, maliyet kontrolünün diğer yarısıdır. Her yanıt üzerinde istem token’larını, tamamlanma token’larını, modeli, gecikmeyi ve kullanıcı veya kiracı kimliğini kaydedin. Bu veriler olmadan maliyet atayamazsınız, pahalı çağrı kalıplarını tanımlayamazsınız veya model seçimi üzerine bilinçli kararlar veremezsiniz.

Akış vs Standart Yanıtlar

Akış ve senkron yanıtlar arasındaki seçim, bir kullanıcı deneyimi (UX) kararıdır ve altyapı üzerinde sonuçları olacaktır.

Senkron çağrılar, arka plan işleri, programlı görevler ve kullanıcının görmeden önce sonucun depolandığı her bağlam için uygundur. Uygulaması daha basittir, test etmesi daha kolaydır ve özel bir taşıma altyapısı gerektirmez. AI çağrınızın bir Eloquent’e yazan Kuyruk İşleyicisi beslemesi durumunda, senkron olanlar doğru varsayılandır.

Akış, bir insan bekliyorsa ve çıktının uzunluğu tam yanıt gecikmesinin deneyimin kalitesini düşürdüğünde uygundur. Pratikte, bu eşik yaklaşık 1.5–2 saniyedir. Bunun altında, akış karmaşıklığı artırır fakat gözle görülebilir bir kazanç sağlamaz.

Akış arka planındaki taşınma mekanizması, ayrı bir karar gerektirir. Sunucu-Tarafı Olayları, Laravel için doğru varsayılandır; ek bir altyapı gerektirmez, standart HTTP üzerinden çalışır ve Livewire ile temiz bir şekilde entegre olur. WebSocket’ler, çift yönlü iletişim veya çoklu istemci yayınına ihtiyaç olduğunda haklı görünür. Livewire anketleri, tüm akış altyapısını tamamen kaçınmayı isteyen takımlar için mantıklı bir yedekleme olarak kabul edilir, ancak algılanan yanıt verme hızını kaybetme pahasına.

Bu üç yaklaşım arasındaki ticaret dengeleri önemli derecede analiz edilmeyi gerektirir. Akış taşıma karar rehberimiz her üç senaryoyu üretim kodlarıyla birlikte kapsamaktadır.

Doğru Sağlayıcıyı Seçmek: Bir Karar Çerçevesi

Sağlayıcı seçimini bir tercih olarak ele almayı bırakın. Bunu, net girdi ile bir mühendislik kararı olarak ele alın.

OpenAI’yi Ne Zaman Kullanmalısınız?

• Yerel gömme ile birlikte üretim yapmaya ihtiyacınız varsa (text-embedding-3-small, çoğu alım kullanım durumu için yeterlidir)
• Ekibinizin en çok belgelenmiş entegrasyon yoluna ihtiyacı varsa
• Araç güvenilirliğinin mantık derinliğinden daha önemli olduğu işlev-calling süreçleri oluşturuyorsanız
• Daha sonra gelişebilecek bir MVP için en düşük yüke sahip Laravel AI entegrasyonu istiyorsanız

Tam OpenAI entegrasyon kılavuzu, taşıma, fonksiyon çağırma ve GPT-4o ve GPT-4o-mini uç noktalarındaki yeniden deneme kalıplarını kapsar.

Gemini’yi Ne Zaman Kullanmalısınız?

• Kullanım durumunuz 128K token’ı aşan belgeleri veya oturumları içeriyorsa
• Ölçeklenebilir biçimde çok modlu girdileri – belgeler, resimler, karma medya – işliyorsanız
• Gemini’nin uzun bağlamını alım aracı olarak kullanarak RAG’siz kalıplar deneyimlemek istiyorsanız
• Hacim başına maliyet birincil endişenizse (Gemini 2.0 Flash, yüksek çağrı oranlarında rekabetçi)

Gemini kurulumu için Laravel AI SDK aracılığıyla, GeminiManager failover kalıbı gibi tüm detayları içerir.

Claude’yu Ne Zaman Kullanmalısınız?

• Görev, çok aşamalı talimatları kesin ve güvenilir bir şekilde izlemeyi gerektiriyorsa
• Yapılandırılmamış metinden yapılandırılmış çıktı çıkarıyorsanız (JSON çıkarımı, veri normalleştirme)
• Güvenlik ve reddetme davranışı önemliyse – düzenlenmiş endüstriler, içerik denetimi hatları
• Kod üretimi veya incelemesi, yükün önemli bir parçasıysa

Laravel Claude API entegrasyon kılavuzu, tam Anthropic istemci kurulumu ve stream implementasyonu ile birlikte tüm ayrıntıları kapsar.

Karışık Sağlayıcı Mimarileri

Daha önce tanımlanan arayüz kalıbı, çok sağlayıcı kurulumlarını pratik hale getirir. Görev türüne göre yönlendirme yaparak, OpenAI gömme ihtiyaçları için, Claude yapılandırılmış çıkarım için, Gemini uzun belge özetleme için operasyonel bir mimari tasviridir, aşırı mühendislik değildir. Servis Konteyneri doğru adaptörü görev türüne göre çözümler ve alan kodunuz temiz kalır.

[Üretim Tuzağı] Karışık sağlayıcı kurulumları, zarif bir bütçe izleme sorunu getirir. Token maliyetlerini sağlayıcıya göre ayrı ayrı kaydederseniz, toplam görünümü kaybedersiniz. Telemetri tablonuzun her çağrı ile birlikte sağlayıcı adını kaydettiğinden emin olun ve maliyet panolarınızın, yalnızca sağlayıcı hesabını değil, özellik veya kiracı başına tümevarım yaparak toplandığından emin olun.

Sonuç

Bu kılavuzdan almanız gereken tek şey şu olsun: sağlayıcılar değiştirilebilir. Mimari değil.

OpenAI, Gemini ve Claude önümüzdeki on iki ay içinde tümü gelişecek, modellerin kullanımdan kaldırılmasına, fiyat değişikliklerine ve yeni yeteneklerin katılmasına tanık olacaktır. Bugün üçü de doğru seçim olabilir, fakat iki çeyrekte yanlış olabilir. Bu değişikliklere takılmadan dayanabilen ekipler, bu katmanı inşa edenlerdir; yalnızca uygulamalarını belirli bir SDK’ye sıkı bir şekilde bağlayıp, sağladıkları özellikleri değiştirmek durumunda kalanlar değildir.

Üretim Laravel AI entegrasyonu, bir sistem tasarım problemidir. Arayüz sözleşmesi, adaptör katmanı, token bütçesi uygulanması, akış taşıma kararı ve telemetri boru hattı — bunlar AI özelliğinizin operasyonel olarak sürdürülebilir olup olmayacağını belirleyen kararlardır veya sadece kötü ölçeklendirilmiş bir demo haline gelir.

Katmanı inşa edin. Ardından sağlayıcıyı seçin.