Laravel AI SDK: Ne Degistiriyor ve Neden Onemli?
Laravel ekosisteminde AI entegrasyonu uzun zamandir devam ediyor ama hep ucuncu parti paketlerle, hep farkli yaklasimlarla. Laravel AI SDK ile bu is artik framework seviyesinde, resmi ve standart. Bu yazida SDK'nin ne oldugunu, neden onemli oldugunu ve onceki cozumlerden ne farki oldugunu anlatacagim.
Evrimi Anlamak
Laravel'de AI kullanmak icin gectigimiz yillarda su asamalardan gectik:
Asama 1: openai-php/client (2023)
Her sey burada basladi. Serhii Potapenko ve Nuno Maduro'nun gelistirdigi bu paket PHP'den OpenAI API'sine istek atmayi kolaylastirdi:
// openai-php/client ile
$client = OpenAI::client('sk-...');
$response = $client->chat()->create([
'model' => 'gpt-3.5-turbo',
'messages' => [
['role' => 'user', 'content' => 'Merhaba!'],
],
]);
echo $response->choices[0]->message->content;
Temiz bir API istemcisiydi ama Laravel'e ozgu hicbir sey yoktu. Konfigurasyonu kendiniz yonetmeniz, test icin mock yazmaniz, hata yonetimini kendiniz yapmaniz gerekiyordu.
Asama 2: openai-php/laravel (2023)
Ayni ekip Laravel wrapper'i cikardi. Artik Service Provider, Facade ve config/services.php entegrasyonu vardi:
// openai-php/laravel ile
use OpenAI\Laravel\Facades\OpenAI;
$response = OpenAI::chat()->create([
'model' => 'gpt-4',
'messages' => [
['role' => 'system', 'content' => 'Sen bir asistansin.'],
['role' => 'user', 'content' => 'Laravel nedir?'],
],
]);
Daha iyiydi ama hala bazi sorunlar vardi:
- Sadece OpenAI destegi (Anthropic, Gemini icin ayri paket lazim)
- Structured output yok (JSON parse etmeniz gerekiyor)
- Conversation persistence yok
- Test desteği sinirli
Asama 3: Prism PHP (2024)
Toni Soriano'nun gelistirdigi Prism, provider-agnostik bir yaklasim getirdi. Artik tek bir API ile birden fazla AI servisi kullanabiliyordunuz:
// Prism PHP ile
use Prism\Prism\Prism;
use Prism\Prism\Enums\Provider;
$response = Prism::text()
->using(Provider::OpenAI, 'gpt-4')
->withSystemPrompt('Sen bir asistansin.')
->withPrompt('Laravel nedir?')
->asText();
echo $response->text;
Prism buyuk bir adimdi: provider soyutlamasi, structured output, tool calling. Ama hala Laravel'in resmi bir parcasi degildi ve bazi sinirlamalari vardi.
Asama 4: Laravel AI SDK (2026)
Ve sonunda geldik buraya. Taylor Otwell ve ekibinin gelistirdigi, Laravel'in resmi AI SDK'si. Agent mimarisi, conversation persistence, streaming, queuing, failover, test -- hepsi yerlesik:
// Laravel AI SDK ile
use App\AI\Agents\Assistant;
$response = app(Assistant::class)
->send('Laravel nedir?')
->result();
echo $response;
Ne Degisti?
1. Agent Class'lari
AI mantigi artik controller'larda degil, kendi class'larinda yasiyor. Bu SOLID prensiplerine uygun, test edilebilir ve yeniden kullanilabilir:
// app/AI/Agents/ContentModerator.php
<?php
namespace App\AI\Agents;
use Laravel\AI\Agent;
use Laravel\AI\Attributes\Description;
use Laravel\AI\Attributes\Provider;
use Laravel\AI\Attributes\Model;
#[Description('Kullanici iceriklerini kontrol eder')]
#[Provider('openai')]
#[Model('gpt-4o-mini')]
class ContentModerator extends Agent
{
protected function systemPrompt(): string
{
return 'Icerik moderasyonu yap. Uygunsuz icerik tespit et.';
}
}
Artisan komutuyla hizlica olusturabiliyorsunuz:
php artisan make:agent ContentModerator
php artisan make:agent DocumentAnalyzer
php artisan make:agent TranslationAssistant
2. Conversation Persistence
Onceki cozumlerde konusma gecmisini kendiniz yonetmeniz gerekiyordu. Session'da tutuyordunuz, veritabanina yaziyordunuz, her istekte tum gecmisi gonderiyordunuz. AI SDK bunu otomatik hallediyor:
// Konusma baslatma
$conversation = $agent->conversation()
->for($user) // Kullaniciya bagli
->send('Merhaba, ben Laravel hakkinda soru soracagim.')
->result();
// Ayni konusmaya devam etme
$response = $agent->conversation($conversation->id)
->send('Middleware nedir?')
->result();
// Tum gecmis otomatik dahil ediliyor
// AI "Laravel hakkinda soru soracagim" baglamini hatirliyora
3. Structured Output
String parse etmek yerine tipi belli PHP objeleri aliyorsunuz. Bu muazzam bir fark cunku json_decode ile ugrasip hata yakalama derdinden kurtuluyorsunuz:
// Schema tanimla
class ProductReview extends Schema
{
public function __construct(
public string $summary,
public int $rating, // 1-5 arasi
public Sentiment $tone, // enum
/** @var string[] */
public array $pros,
/** @var string[] */
public array $cons,
) {}
}
// Kullan
$review = $agent->structured(ProductReview::class)
->send("Bu yorumu analiz et: '$reviewText'")
->result();
// $review->rating int, $review->tone enum, $review->pros array
// Tip guvenligi var, IDE autocomplete calisiyor
4. Streaming
Buyuk cevaplarda kullaniciyi bekletmemek icin stream desteği var. SSE (Server-Sent Events) ile real-time cikti gosterebiliyorsunuz:
$stream = $agent->send('Bana Laravel\'in tarihini anlat.')
->stream();
foreach ($stream as $chunk) {
echo $chunk; // Her parca geldikce goster
}
5. Queue Entegrasyonu
AI islemleri genellikle yavas. Kullaniciyi bekletmek yerine queue'ya atabilirsiniz. Bu Laravel'in kendi queue sistemiyle calisiyor:
// Arka planda calistir
$agent->send('Bu 500 sayfalik PDF\'i ozetle.')
->onQueue('ai-tasks')
->dispatch();
6. Failover
Birden fazla provider tanimlayin, biri cokerse digeri devreye girsin:
// config/ai.php
'defaults' => [
'providers' => [
['provider' => 'openai', 'model' => 'gpt-4o'],
['provider' => 'anthropic', 'model' => 'claude-sonnet-4-20250514'],
],
'failover' => true,
'retry' => [
'times' => 2,
'sleep' => 1000, // ms
],
],
Bu ozellikle production icin kritik. OpenAI veya Anthropic'in downtime yasadigi durumlar oluyor ve kullanicilariniz bundan etkilenmesin istiyorsunuz.
7. Test Desteği
fake() ile AI cagrilarini taklit edebiliyorsunuz. Gercek API'ye istek atmadan, maliyetsiz test:
use Laravel\AI\Facades\AI;
// Test'te
AI::fake([
ContentModerator::class => 'Bu icerik uygundur.',
]);
// Controller cagrildiginda gercek API yerine fake cevap donecek
$response = $this->postJson('/api/moderate', ['content' => 'Test']);
$response->assertOk();
// Assertion'lar
AI::assertAgentUsed(ContentModerator::class);
AI::assertAgentUsedTimes(ContentModerator::class, 1);
AI::assertNothingUsed(); // Hicbir agent kullanilmadi
Gereksinimler
- PHP 8.4+ (readonly class'lar, enum'lar, intersection types)
- Laravel 12+
- En az bir AI provider API key'i (OpenAI, Anthropic veya Ollama)
Ne Zaman Kullanilmali?
AI SDK su durumlarda deger katiyor:
Evet, kullanin:
- Icerik moderasyonu
- Belge analizi ve siniflandirma
- Otomatik ozetleme
- Chatbot / asistan
- Veri cikarma (extraction)
- Ceviri
- Kod analizi
Hayir, gereksiz:
- Basit string isleme (regex yeterli)
- Statik siniflandirma (if/switch yeterli)
- Arama (Elasticsearch/Meilisearch daha iyi)
- Her istek icin AI cagirmak (maliyet, performans)
Sik Yapilan Hatalar
1. Her Seyi AI'ya Yaptirmak
AI gucu muazzam ama her is icin AI cagirmak gereksiz maliyet ve yavaslik demek. "Bu e-posta adresi gecerli mi?" sorusunu AI'ya sormak yerine basit bir regex kullanin.
2. Prompt'u Koda Gommek
System prompt'u hardcoded yazmak yerine konfigurasyondan veya veritabanindan cekin. Boylece yeniden deploy etmeden prompt'u optimize edebilirsiniz:
// YANLIS
protected function systemPrompt(): string
{
return 'Sen bir asistansin...';
}
// DOGRU
protected function systemPrompt(): string
{
return config('ai.prompts.assistant', 'Varsayilan prompt...');
}
3. Hata Yonetimini Atlama
AI servisleri her zaman calismaz. Rate limit, timeout, gecersiz cevap... Bunlari yonetmelisiniz:
use Laravel\AI\Exceptions\AgentException;
use Laravel\AI\Exceptions\ProviderException;
use Laravel\AI\Exceptions\RateLimitException;
try {
$result = $agent->send($prompt)->result();
} catch (RateLimitException $e) {
// Kullaniciyi bilgilendir, kuyruga at
return back()->with('warning', 'Sistem yogun, lutfen biraz bekleyin.');
} catch (ProviderException $e) {
// Provider hatasi, log'la
Log::error('AI provider hatasi', ['error' => $e->getMessage()]);
return back()->with('error', 'Islem sirasinda bir hata olustu.');
} catch (AgentException $e) {
// Genel agent hatasi
report($e);
return back()->with('error', 'Beklenmeyen bir hata olustu.');
}
4. Maliyeti Takip Etmemek
Her AI cagrisi para. GPT-4o ile gunluk 10.000 istek = ciddi fatura. Takip edin:
// Basit token takibi middleware'i
class TrackAiUsage
{
public function handle($request, Closure $next)
{
$response = $next($request);
// AI SDK usage bilgisi donuyorsa kaydet
if ($usage = AI::getLastUsage()) {
AiUsageLog::create([
'user_id' => auth()->id(),
'agent' => $usage->agent,
'input_tokens' => $usage->inputTokens,
'output_tokens' => $usage->outputTokens,
'cost' => $usage->estimatedCost,
'model' => $usage->model,
]);
}
return $response;
}
}
Prism PHP ile Karsilastirma
Prism PHP hala bagimsiz bir paket olarak gelistirilmeye devam ediyor ve gecerli bir alternatif. Iste farklari:
| Ozellik | Prism PHP | Laravel AI SDK |
|---|---|---|
| Provider desteği | OpenAI, Anthropic, Gemini, Ollama | Ayni + daha fazla |
| Agent mimarisi | Yok (fonksiyonel API) | Var (class-based) |
| Conversation persistence | Manuel | Otomatik |
| Queue entegrasyonu | Manuel | Yerlesik |
| Structured output | Var | Var (daha gelismis) |
| Streaming | Var | Var |
| Test (fake) | Sinirli | Tam destek |
| Failover | Manuel | Otomatik |
| Resmi destek | Topluluk | Laravel ekibi |
Prism PHP hafif ve fonksiyonel bir yaklasim sunuyor. Kucuk projelerde veya mevcut bir Prism kullaniminda gecis yapmak zorunda degilsiniz. Ama yeni projelerde AI SDK'yi kullanmanizi oneririm cunku Laravel ekibinin resmi destegi ve framework ile derin entegrasyon buyuk avantaj.
Veritabani: MySQL vs PostgreSQL
AI uygulamalarinda veritabani secimi onemli hale geliyor, ozellikle embedding'ler kullaniyorsaniz.
MySQL
Cogu Laravel projesinde MySQL var ve AI SDK temel ozellikleri icin MySQL yeterli:
- Conversation persistence
- Agent konfigurasyonu
- Usage logging
PostgreSQL + pgvector
Eger embedding tabanli arama (semantic search) yapacaksaniz PostgreSQL + pgvector sart:
-- pgvector extension'i
CREATE EXTENSION IF NOT EXISTS vector;
-- Embedding kolonu
ALTER TABLE documents ADD COLUMN embedding vector(1536);
-- Similarity search
SELECT *, 1 - (embedding <=> $1) as similarity
FROM documents
ORDER BY embedding <=> $1
LIMIT 10;
Ne zaman PostgreSQL'e gecmelisiniz:
- RAG (Retrieval Augmented Generation) yapiyorsaniz
- Belge arama / semantik arama istiyorsaniz
- Oneri sistemi kuruyorsaniz
- Buyuk olcekli embedding depolama gerekiyorsa
MySQL'de kalin:
- Sadece chat/asistan yapiyorsaniz
- Structured output kullaniyorsaniz (embedding gerekmiyor)
- Kucuk-orta olcekli proje
- Mevcut MySQL altyapiniz varsa
Lokal Gelistirme: Ollama
Gelistirme sirasinda surekli OpenAI API'sine istek atip para odemenize gerek yok. Ollama ile yerel olarak calisabilirsiniz:
# macOS
brew install ollama
ollama pull llama3.2
ollama pull nomic-embed-text # Embedding icin
ollama serve
# .env.local
AI_DEFAULT_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2
Sinirliliklari:
- Structured output kalitesi dusuk (kucuk modellerde)
- Hiz GPU'ya bagli
- Bazi gelismis ozellikler desteklenmiyor
Ama hizli iterasyon ve test icin mukemmel.
Sonuc
Laravel AI SDK, PHP/Laravel dunyasinda AI entegrasyonunu ciddi sekilde ileriye tasiyor. Ozellikle su uc sey beni etkiledi:
- Agent mimarisi: AI mantigini duzgun bir sekilde organize etmeyi sagliyor
- Test desteği:
fake()ile unit test yazabilmek muazzam - Failover: Production'da guvence
Eger Laravel 12 ve PHP 8.4 kullaniyorsaniz, yeni projelerinizde AI SDK'yi deneyin. Mevcut projeleriniz icin hemen gecis yapmaniz gerekmiyor ama yeni AI ozellikleri eklerken SDK'yi tercih edin.
Bu konuda daha fazla icerik gelecek. Agent pattern'leri, RAG uygulamasi ve production best practice'leri ayri yazilar olarak planliyorum.