Laravel AI SDK 17 Mart’ta Stabil Hale Geliyor: Değişiklikler ve Göndermeden Önce Kontrol Edilmesi Gerekenler

Orijinal yayın hafiz.dev adresindedir.

Laravel AI SDK, 17 Mart itibariyle, Laravel 13 ile birlikte stabil hale geldi. Eğer bu paket için onay bekliyorsanız, beklemenin sonuna geldiniz.

Fakat burada bir nokta var: “stabil” olmak sadece bir etiket değil. Paketin kullanım şeklinizi, versiyon güncellemelerinden ne beklemeniz gerektiğini ve bunu üretim yapılarında kullanmanın güvenli olup olmadığını değiştiriyor. Eğer benim genel bakış yazımı ya da 1. Bölüm ve 2. Bölüm derslerini takip ettiyseniz, kodlarım hala çalışıyor mu? Gerçekten ne değişti?

Bu yazı, tam da bunları ele alıyor. Daha önce okuduğunuz özellik tekrarları değil, sadece ne değişti, “stabil” pratikte ne anlama geliyor ve üretime göndermeden önce kontrol etmeniz gereken bir liste sunmakta.

“Stabil” Burada Gerçekten Ne Anlama Geliyor

Laravel bir paketi stabil olarak işaretlediğinde, birkaç somut şey oluyor.

İlk olarak, anlamsal versiyonlama doğru bir şekilde devreye giriyor. Beta döneminde, v0.x sürümleri, küçük sürümler arasında kıran değişiklikler getirebiliyordu ve bunları yaptı. API değişti, namespace düzenlemeleri yapıldı, metod imzaları değişti. Paket 1.0’a ulaştığında, kırıcı değişiklikler yalnızca büyük sürüm artışları için saklıdır. Hata düzeltmeleri ve yeni özellikler alırken, kodunuzun aniden derlenmemesi durumuyla karşılaşmazsınız.

İkincisi, paket artık üretim composer.json dosyalarında kilitlenmek için güvenlidir. Beta sırasında doğru olan "laravel/ai": "dev-main" veya gevşek ^0.x kısıtlamasıydı. 17 Mart’tan sonra ^0.3 veya daha yüksek bir değer kullanmalısınız. Bu, sizi stabil sürüm kanalına bağlar ve composer update komutunun, ajanslarınızı bozacak bir şey çekmesini engeller.

Üçüncüsü, birinci taraf destek artık resmi. Güvenlik açıkları düzeltilecektir. Ekip, geriye dönük uyumluluğu korur. Ekosistemdeki diğer paketler (Filament, Prism ve diğerleri) bağımlılıklarını güvenle belirtebilir, zeminlerinin kaymasını endişe etmeden yapabilirler.

Yani, 17 Mart’ta özellikler dramatik bir değişim göstermedi. Güvenilirlik sözleşmesi artık resmi hale geldi.

Beta Döneminde Ne Değişti

SDK, 2026 yılının Şubat başında cesur bir ilk sürüm olarak kamuya açıldı. Temel fikir ilk günden itibaren sağlamdı: AI sağlayıcıları ile çalışmak için birleşik, Laravel-yerli bir API sunmak, Agent sınıfı desenine dayalı olarak inşa edildi.

Ancak beta dönemi gerçekten de işlerin nasıl çalıştığını parlatmak için kullanıldı. İlk sürüm ile v0.3.0 arasındaki değişikler şöyle:

Sağlayıcı araç yapılandırması daha temiz hale geldi. WebSearch, WebFetch ve FileSearch sağlayıcı araçları artık düzgün bir şekilde Laravel\Ai\Providers\Tools altında isimlendirilmiştir. İlk beta kodu bunları doğrudan referans alıyorsa güncellenmesi gerekiyor.

Gömme istekleri için yapılandırılabilir zaman aşım süreleri v0.3.0’da geldi. Büyük gömme işleriniz varsa ve zaman aşımı sorunları yaşıyorsanız, bu düzeltmedir. Artık her sağlayıcı için zaman aşımı değerlerini config/ai.php içinde belirleyebilirsiniz.

RemembersConversations trait’i stabil hale geldi. İlk uygulamalarda agent_conversations ve agent_conversation_messages tablolarında bazı zayıf noktalar vardı. Göç şeması artık kesin.

JsonSchema aracılığıyla yapılandırılmış çıktı, akışkan API’sini temizlendi. İlk beta dönemde çalışan bazı metod zincirleri tutarsız bir arayüzü sağlamak için devre dışı bırakıldı. Eğer Şubat 2026’dan önce yapılandırılmış çıktı ajansları yazdıysanız, şema tanımlarınızı kontrol etmeyi unutmayın.

Test sahte nesneleri kapsamlı hale geldi. Ajansları, resimleri, sesleri, transkripsiyonları, gömme işlemlerini, yeniden sıralamayı ve dosya depolarını sahte haline getirme yeteneği şimdi birinci sınıf bir özellik. Bu, başlangıçta tamamlanmamıştı.

12 Mart’ta çıkan v0.3.0 sürümü (Taylor’ın tweet attığı) ayrıca araç istek işleme etrafında birkaç düzeltme ekledi. Mevcut kodu bozacak bir şey yok, ancak en yenisini çekmeniz faydalı olacaktır.

Tam Özellik Seti, Artık Kilitlendi

Stabil sürüm API’yi dondurduğundan, neyle çalıştığınızı tam olarak bilmek önemlidir. Artık resmi olarak desteklenen her şey:

flowchart TB
    A["Your Laravel app
agents · controllers · jobs"]
    A --> B["Laravel AI SDK unified interface"]
    B --> C[OpenAI]
    B --> D[Anthropic]
    B --> E[Gemini]
    B --> F["+ 8 more"]

Ajanslar, temel primitiflerdir. Onları php artisan make:agent ile oluşturursunuz ve sınıf içinde talimatları, araçları, belleği ve çıktı şemasını yapılandırırsınız. Ya da hızlı çevrimiçi ajanslar için agent() yardımcısını kullanabilirsiniz. Her ajansı bir uzman olarak düşünün: bir işi, bir dizi talimatı ve bir çıktı sözleşmesi vardır.

Çoklu sağlayıcı desteği, OpenAI, Anthropic, Gemini, ElevenLabs, Groq, Cohere, DeepSeek, xAI ve OpenRouter’ı kapsar. Bir dize değiştirmekle sağlayıcıları değiştirirsiniz. Müşteri kitaplığı değişiklikleri ve arayüz düzenlemeleri yok. Bu, SDK’yı sadece OpenAI PHP istemcisini sarmaktan gerçek anlamda farklı kılan kısım.

Sağlayıcı yedeklemesi yerleşik olarak gelir. Bir sağlayıcı dizisi geçin ve SDK, bir hız limiti veya kesinti durumunda otomatik olarak bir sonraki sağlayıcıyı dikkate alır:

$response = (new SalesCoach)->prompt(
    'Analyse this transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

flowchart TD
    A[Your Laravel app] --> B[SDK tries OpenAI]
    B -- success --> D[Response returned]
    B -- rate limit / outage --> C[SDK retries Anthropic]
    C --> D

Yapılandırılmış çıktı, yanıtı belirttiğiniz türlere dönüştürerek otomatik olarak şema tanımını üreten bir JsonSchema yapıcı kullanır. Artık AI yanıtlarından JSON dizelerini manuel olarak ayrıştırmanıza gerek yok. Ajan, üzerinde doğrudan çalışabileceğiniz bir tip dizisi döndürür.

Görüntü, ses ve gömme üretimi, aynı akışkan arayüz desenini kullanır. Görüntüler, herhangi bir dosya sistemi diskine kuyruklanabilir ve saklanabilir. Ses, hem sentez hem de transkripsiyonu destekler. Gömmeler, yapılandırdığınız her vektör mağazası ile çalışır.

RAG kullanım senaryoları için vektör mağazaları tam olarak desteklenir; SimilaritySearch ise anlamsal belge elde etme için mevcuttur. Eğer benim 2. bölümdeki destek botunu oluşturduysanız, bunu en çok kullandığınız özellik budur.

Kullanıcı başına hız limitleme config/ai.php içinde yapılandırılabilir. Bu, son kullanıcıların AI taleplerini doğrudan tetiklediği herhangi bir uygulama için önemlidir. Bunun olmaması durumunda, tek bir kullanıcı API kottan birkaç dakika içinde harcayabilir.

Ajanslar için Middleware, istekleri ve yanıtları yakalama ve değiştirme olanağı sağlar. Her bir sistem istemcisinde tekrar etmek istemediğiniz kullanıcı bağlamını otomatik olarak enjekte etmek, hassas içeriği modelden önce filtrelemek veya her istemcide yanıtları günlüğe kaydetmek için faydalıdır.

Üretim Hazırlık Kontrol Listesi

Stabil SDK kullanarak herhangi bir şey göndermeden önce bu listeyi gözden geçirin. Bazı maddeler bariz görünebilir. Ama gerçek projelerde her birinin birini zor durumda bıraktığını gördüm.

1. Composer kısıtlamanızı güncelleyin

composer require laravel/ai:^0.3

Üretimde dev-main veya ^0.x üzerinde kalmayın. Stabil etiket tam da bunu sıkılaştırmak içindir.

2. Konfigürasyon dosyasını yayınlayın ve gözden geçirin

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Beta sırasında bunu yayınladıysanız, yeni konfigürasyonunuzu kontrol edin. Zaman aşımı ayarları, hız sınırı yapılandırması ve sağlayıcı listesi, henüz kullanmadığınız yeni seçeneklere sahip olabilir.

3. Göçleri sıfırdan çalıştırın

php artisan migrate

SDK’yı beta sırasında yüklediyseniz, agent_conversations ve agent_conversation_messages tablolarınızın nihai göç şemasına uyduğundan emin olun. Konuşma depolama şeması v0.3.0’da stabil hale geldi ve mevcut tablolarınızın bu şemaya uyup uymadığını doğrulamaya değer.

4. Kullanıcı ile etkileşimli olan her şey için sağlayıcı yedeklemesi ayarlayın

Tek sağlayıcı ayarları iç araçlar için uygundur. Gerçek bir kullanıcının beklediği her şey için, bir geri dönüş yapılandırın:

// config/ai.php
'default_providers' => [
    Lab::OpenAI,
    Lab::Anthropic,
],

Veya bu ayarı provider argümanını kullanarak her ajans sınıfı için ayarlayın. Rate limitler ve kısa kesintiler normaldir. Kullanıcılarınız bunları görmemelidir.

5. Ağır AI işlemlerini kuyruklanmış işleri taşıyın

Görüntü oluşturma, gömme dizini, ses transkripsiyonu: bunların hiçbiri bir istek döngüsünde eş zamanlı olarak çalışmamalıdır. SDK doğal olarak kuyruklamayı destekler:

Image::of('A product banner for...')
    ->generate()
    ->store('products/banner.webp');

Bunu bir kuyruk işine sarın ve HTTP yanıt süreleriniz, AI sağlayıcısının ne yaptığından bağımsız olarak hızlı kalır. Dilerseniz, tam ayar için Laravel kuyruk desenleri hakkında derinlemesine yazıma göz atabilirsiniz.

6. Testleri sahte nesnelerle, gerçek API çağrıları olmadan yazın

Burası stabil SDK’nın gerçek anlamda sunduğu bir avantaj. Her AI işleminin bir sahte versiyonu var:

use Laravel\Ai\Testing\AgentFake;

AgentFake::fake([
    SupportAgent::class => 'Here is the answer to your question...',
]);

// Artık testinizi OpenAI'ye hitap etmeden çalıştırabilirsiniz
$response = (new SupportAgent)->prompt('How do I reset my password?');

$this->assertStringContainsString('answer', $response->text);

Gerçek AI API’lerini kullanan testler yavaş, pahalı ve kararsız. Sahte nesneleri kullanın. Kapsamlıdırlar ve görüntüler, sesler, gömmeler ve dosya depolarını da kapsar.

7. Yapılandırılmış çıktı şemalarını doğrulayın

Eğer JsonSchema kullanarak yapılandırılmış ajan yanıtları alıyorsanız, nihai stabil API’ye kısa bir sağlık kontrolü yapın. Bazı akışkan metotlar, erken beta ile v0.3.0 arasında değişti. Bu özellikle mid-Şubat’tan önce ajans yazdıysanız önemlidir. Yapılandırılmış çıktıları hata ayıkırken, bir JSON biçimleyici zaman kazandırabilir. Bu, hammadde API yanıt gövdeleriyle uğraşırken şema tutarsızlıklarını bulmaya çalıştığınızda faydalı olur.

Mevcut Eğitim Kodunuz Hala Çalışıyor Mu?

Eğer 1. bölüm veya 2. bölümden belge analizörü oluşturduysanız, cevap çoğunlukla evet; sadece bir şey kontrol etmelisiniz.

agent() yardımcı fonksiyonu, ajans sınıfı yapısı, Promptable trait’i, araç arayüzü ve SimilaritySearch kullanımı değişmedi. İş mantığınız güvenli.

Kontrol etmeniz gereken bir şey var: Eğer ajanslarınızda WebSearch veya WebFetch gibi sağlayıcı araçları doğrudan referans aldıysanız, Laravel\Ai\Providers\Tools\WebSearch ad alanını teyit edin. Bu, beta sırasında değişti.

Ayrıca, composer kısıtlamanızı ^0.3 veya daha yükseğe yükseltip composer update çalıştırdığınızdan emin olun; bu, stabil etiket gelmeden önce v0.3.0 sürümünden gelen düzeltmeleri almanızı sağlar.

Ne Zaman Acele Etmemelisiniz?

Stabil lansman, her yeni özellik için AI’nin doğru bir seçim olduğu anlamına gelmez. Bu konuda doğrudan olmalıyım.

SDK, belirli, sınırlı bir kullanım durumu aşamasında net giriş ve çıkışlarla kullanıldığında harika çalışıyor. Sınıflandırma, belge analizi, destek yönlendirmesi, önceden belirlenmiş şemalarla içerik oluşturma gibi yapılandırılmış çıktı ajansları: bunlar iyi çalışır ve gerçekten üretime hazırdır.

Belirleyici bir davranış gerektiğinde zordur. AI yanıtları, veritabanı sorguları gibi tutarlı değildir. Eğer özelliğiniz kesin, tekrar edilebilir çıktılar gerektiriyorsa, geleneksel kod ile devam etmelisiniz.

Ve maliyet de önemlidir. Her AI API çağrısının bir fiyatı vardır. Sık sık tetiklenen kullanıcı ile etkileşime giren özellikler için, göndermeden önce rakamları değerlendirin. SDK’nın hız sınırlayıcıları, bunu kontrol etmeye yardımcı olur, ancak sorunu çözmez.

4 Mart tarihli PHP Attributes yazısı aslında bu SDK ile birlikte stabil hale gelen iyi bir örnektir. Laravel 13 genel olarak yeni yeteneklere ölçülü ve pratik bir yaklaşım sergiliyor. AI SDK da bu felsefeye uyuyor; üretim kullanım senaryoları için hazır. Ancak, gereksiz olan yerde AI’yi uygulamak için bir bahane değildir.

Sıkça Sorulan Sorular

Stabil SDK’ya geçmek veri tabanı göç değişiklikleri gerektiriyor mu?

Eğer beta döneminde SDK’yı kullanıyorsanız, php artisan migrate komutunu çalıştırın ve agent_conversations tablonuzun nihai şemaya uygun olup olmadığını kontrol edin. Yeni kurulumlar için, ^0.3 veya daha yüksek sürüme yükseldikten sonra göçleri sıfırdan yayınlayın.

Stabil SDK’yı Laravel 12 üzerinde kullanabilir miyim yoksa Laravel 13’e geçmem gerekiyor?

SDK, şu anda Laravel 12.x belgelerinde bulunmaktadır ve Şubat 2026’dan beri Laravel 12’de mevcuttur. 17 Mart tarihli stabil etiket, Laravel 13 ile birlikte geldi, ancak stabil SDK’yı kullanmak için Laravel yükseltmeniz gerekmiyor. Laravel 12’de çalışır.

agent() yardımcı fonksiyonunu kullanmak ile özel bir Ajans sınıfı oluşturmak arasındaki fark nedir?

agent() yardımcı fonksiyonu, hızlı ve çevrimiçi ajanslar için harika bir seçenektir: yeniden kullanılabilirliğe ihtiyaç duymadığınız tek seferlik işlemler. Özel Ajans sınıfları, uygulamanızdaki birden fazla yerden yönlendireceğiniz ajanslar veya karmaşık araç yapılandırmaları ve middleware’leri olan ajanslar içindir. Öncelikle yardımcıyı kullanın, büyüdüğünde bir sınıfa aktarın.

AI API hız limitlerini üretimde, yedekleme özellikleri olmadan nasıl yönetebilirim?

Eğer tek bir sağlayıcıya sıkı bir bağlılığınız varsa, AI işlemlerinizi kuyruklayın ve Laravel’in yerleşik iş tekrar mekanizmaları aracılığıyla yeniden deneme mantığı ekleyin. İş sınıfınıza public $tries = 3 ve public $backoff = [30, 60, 120] ayarlarını ekleyin. Yedekleme özelliği daha iyidir, ancak kuyruklanan yeniden denemeler bir yedekleme olarak çalışır.

Laravel AI SDK, Prism’in yerini alıyor mu yoksa birlikte mi var olmalı?

Resmi SDK, en yaygın kullanım senaryolarını kapsar ve artık yeni Laravel projeleri için birinci taraf tercihtir. Prism, daha geniş bir sağlayıcı yüzeyine sahip ve henüz resmi SDK’da bulunmayan bazı özellikler içermektedir. Yeni projeler için resmi SDK ile başlayın. Mevcut Prism kodunuz çalışıyorsa, göç yapmanız için acil bir neden yoktur.

Şu Anda Ne Yapmalısınız

Bugün stabil SDK’yı kurun, composer kısıtlamanızı ^0.3 veya daha yukarı bir değerle güncelleyin ve yukarıdaki kontrol listesini gözden geçirin. SDK beta aşamasındayken AI özellikleri geliştirmeyi bekliyorsanız, beklemek sona erdi.

Bu, şuan Laravel uygulamanıza AI eklemek için gerçekten en temiz yol. Bunun sebebi tek seçenek olması değil, zaten bildiğiniz her Laravel kuralını (servis sağlayıcıları, facadeler, artisan komutları, kuyruk işleri ve konfigürasyon dosyaları) takip etmesidir. Zihinsel bir bağlam değişikliği gerektirmeden AI sağlayıcısını çağıran Laravel kodu yazıyorsunuz.

Tam Laravel AI SDK belgeleri zaten aktif ve her şeyi kod örnekleriyle kapsamaktadır. Stabil etiketin yerleşmesiyle birlikte yetkili referans şimdi onlardır.

AI destekli bir ürün oluşturup hızlı bir şekilde piyasaya sürmek mi istiyorsunuz? İdeyeden çalışır bir Laravel MVP’ye geçmelerine yardımcı oluyorum. Hadi konuşalım.