Laravel ile AI Entegrasyonları: Yaygın Hatalar ve Çözüm Yöntemleri

AI altın madeni dönemi başladı ve her geliştirici bir “AI wrapper” inşa etmekle meşgul. Laravel uygulamanızı oluşturuyor, OpenAI PHP istemcisini ekliyor, bir kontrolcüyle entegre ediyorsunuz; işte ürün hazır. Uygulama yerel makinanızda mükemmel çalışıyor. İlk 10 kullanıcı için de sorun yok. Fakat Hacker News ana sayfasına ulaştığınızda işler tersine dönüyor.

Artık uygulamanız durma noktasına geliyor. Loglarınız 429 Too Many Requests hatalarını feryat ediyor. OpenAI API faturanız tavan yapıyor çünkü farklı kullanıcılar için aynı yanıtları yeniden üretiyorsunuz. PHP-FPM işçileriniz tükenmiş durumda, OpenAI sunucularından yanıt beklerken askıya alınıyorlar.

AI çağında, N+1 sorgu problemi bu şekilde karşınıza çıkıyor. Geleneksel web geliştirmede N+1 problemi, veritabanına bir döngü içinde sorgu gönderdiğinizde ortaya çıkar. AI döneminde ise bu problem, dış LLM API’lerini yerel, senkron bir veritabanı çağrısı gibi değerlendirdiğinizde ortaya çıkıyor.

Bu derin dalışta, Laravel’de naif AI entegrasyonlarının mimari tuzaklarını keşfedecek ve kümeleme, önbellekleme ile birlikte ölçeklenebilir bir AI pipeline’ı nasıl oluşturacağınızı göreceğiz.

Naif Yaklaşım: Senkron API Çağrıları

Aşağıda çoğu geliştiricinin OpenAI’yi Laravel kontrolcülerine entegre ettiği yöntemleri inceleyeceğiz.

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use OpenAI\Laravel\Facades\OpenAI;
use App\Models\Article;

class ArticleSummaryController extends Controller
{
    public function store(Request $request, Article $article)
    {
        // ❌ KÖTÜ: Senkron, bloke edici API çağrısı
        $response = OpenAI::chat()->create([
            'model' => 'gpt-4-turbo',
            'messages' => [
                ['role' => 'system', 'content' => 'Aşağıdaki makaleyi özetleyin.'],
                ['role' => 'user', 'content' => $article->content],
            ],
        ]);

        $summary = $response->choices[0]->message->content;

        $article->update(['summary' => $summary]);

        return response()->json(['summary' => $summary]);
    }
}

Bunun neden bir felaket olacağı:

• İşçiyi bloke etme: PHP senkron çalışır. OpenAI yanıt üretmek için 15 saniye beklerse, o PHP-FPM işçisi 15 saniye boyunca kilitlenmiş olur. Eğer 50 işçi ve aynı anda 50 kullanıcı SUMMARY talep ederse, tüm uygulamanız çöküyor ve kimse ana sayfayı yükleyemiyor.
• Tekrar Deneme Mekanizması Yok: Ağ istekleri başarısız olabilir. OpenAI hizmet dışı kalırsa ve API 500 veya 429 (Limit Aşımı) dönerse, kullanıcı genel bir hata alır ve veri kaybolur.
• Önbellekleme Yok: Eğer 100 kullanıcı aynı makalenin özetini talep ederse, OpenAI’ye 100 kez ödeme yaparsınız.

Adım 1: Kuyruğa Dayalı Mimariye Geçiş

AI entegrasyonlarının altın kuralı: HTTP isteği döngüsünde asla bir LLM API çağrısı yapmayın. Bunun yerine, bir işçi işlemi kuyruğa gönderip, kullanıcıya hemen bir yanıt döndürmeliyiz. Laravel’in yayınlama veya anketleme özelliklerini kullanarak, AI tamamlandığında ön uç tarafını bilgilendirebiliriz. Kontrolcümüzü iş gönderme işlemi ile yeniden düzenleyelim.

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Jobs\GenerateArticleSummary;
use App\Models\Article;

class ArticleSummaryController extends Controller
{
    public function store(Request $request, Article $article)
    {
        // ✅ İYİ: Kuyruğa gönder ve hemen yanıt ver
        GenerateArticleSummary::dispatch($article, $request->user());

        return response()->json([
            'message' => 'Özet oluşturma başladı.',
            'status_url' => route('articles.summary.status', $article)
        ], 202);
    }
}

Şimdi, bu işçiyi oluşturalım. Burada sihir gerçekleşiyor.

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use OpenAI\Laravel\Facades\OpenAI;
use App\Models\Article;
use App\Models\User;
use Illuminate\Support\Facades\Log;
use Throwable;

class GenerateArticleSummary implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3;
    public $backoff = [10, 30, 60]; // Üstel geri çekilme

    public function __construct(
        public Article $article,
        public User $user
    ) {}

    public function handle(): void
    {
        try {
            $response = OpenAI::chat()->create([
                'model' => 'gpt-4-turbo',
                'messages' => [
                    ['role' => 'system', 'content' => 'Aşağıdaki makaleyi özetleyin.'],
                    ['role' => 'user', 'content' => $this->article->content],
                ],
            ]);

            $summary = $response->choices[0]->message->content;

            $this->article->update(['summary' => $summary]);

            // Kullanıcıyı WebSocket ile bilgilendirin
            // Broadcast::event(new SummaryGenerated($this->article, $this->user));

        } catch (\OpenAI\Exceptions\ErrorException $e) {
            if ($e->getErrorCode() === 'rate_limit_exceeded') {
                Log::warning('OpenAI Limit Aşıldı. İşi serbest bırakılıyor.');
                $this->release(60); // Yeniden denemeden önce 60 saniye bekle
                return;
            }

            throw $e;
        }
    }

    public function failed(Throwable $exception): void
    {
        Log::error("Makale {$this->article->id} için özet oluşturma başarısız oldu: {$exception->getMessage()}");
        // Kullanıcıyı başarısızlık hakkında bilgilendirin
    }
}

Önemli İyileştirmeler:

• Üstel Geri Çekilme: İş başarısız olursa, 10 saniye, sonra 30 saniye, ardından 60 saniye bekleyip yeniden dener.
• Limit Aşımı Yönetimi: OpenAI limit aşıma hatasını özel olarak yakalar ve işi kuyruktan 60 saniye gecikme ile serbest bırakır; böylece denemelerinizi bir anda harcamamış olursunuz.
• Bloklama Yapmama: Kullanıcıya anında 202 Kabul yanıtı döndürülür. Yoğun iş yükü arka planda gerçekleştirilir.

Adım 2: Akıllı Önbellekleme ile Kota Tasarrufu

Eğer uygulamanız, kullanıcıların sorular sormasına veya statik girdilere göre içerik oluşturmasına izin veriyorsa, sonuçları önbelleğe almanız gerekir. LLM’ler yeterince deterministik olduğu için (sıcaklık 0’dayken), birbirinin aynısı olan istemleri benzer yanıtlar verecektir. Laravel’in Cache facade’ını kullanarak bir önbellek katmanı ekleyelim. İstemciden gelen isteğin benzersiz bir önbellek anahtarını oluşturmak için istemi hashleyelim.

namespace App\Services;

use Illuminate\Support\Facades\Cache;
use OpenAI\Laravel\Facades\OpenAI;

class OpenAIService
{
    public function generateCachedResponse(string $systemPrompt, string $userPrompt): string
    {
        // Bu tam isteğe özgü gelişmiş bir parmak izi oluşturun
        $cacheKey = 'openai_response_' . md5($systemPrompt . $userPrompt);

        return Cache::remember($cacheKey, now()->addDays(30), function () use ($systemPrompt, $userPrompt) {
            $response = OpenAI::chat()->create([
                'model' => 'gpt-4-turbo',
                'temperature' => 0.2, // Daha deterministik önbellekleme için daha düşük sıcaklık
                'messages' => [
                    ['role' => 'system', 'content' => $systemPrompt],
                    ['role' => 'user', 'content' => $userPrompt],
                ],
            ]);

            return $response->choices[0]->message->content;
        });
    }
}

Birleştirilmiş sistem ve kullanıcı istemlerini hashleyerek, herhangi bir kullanıcı aynı soruyu sorduğunda Redis’ten yanıtı 2 milisaniyede servis edebiliriz; bunun yerine OpenAI’ye ödeme yapıp 10 saniye beklemek zorunda kalmayız.

Adım 3: Vektör Veritabanları ile Anlamsal Önbellekleme

Tam dize eşleştirme (MD5 hashing) iyi bir çözümdür, fakat Kullanıcı A “Laravel’i nasıl ölçeklendiririm?” diye sorduğunda ve Kullanıcı B “Laravel uygulamasını ölçeklendirmenin en iyi yolu nedir?” diye sorulduğunda ne olur?

Bunlar anlamsal olarak benzer olsa da, MD5 hash’leri tamamen farklı olacaktır. İşte burada Anlamsal Önbellekleme devreye giriyor.

Kesin dize eşleştirmek yerine, kullanıcının sorgusunu bir vektörde gömüyoruz, geçmişteki benzer sorgular için vektör veritabanımızda arama yaparak, benzerlik puanı yeterince yüksekse (örneğin, > 0.95) önbellekten yanıtı döndürüyoruz. Laravel ve varsayımsal bir Vektör DB istemcisi kullanarak kavramsal bir uygulama yapalım:

namespace App\Services;

use OpenAI\Laravel\Facades\OpenAI;
use App\Services\VectorDatabase;

class SemanticCacheService
{
    public function __construct(protected VectorDatabase $vectorDb) {}

    public function ask(string $question): string
    {
        // 1. Kullanıcının sorusu için bir gömme oluştur
        $embeddingResponse = OpenAI::embeddings()->create([
            'model' => 'text-embedding-3-small',
            'input' => $question,
        ]);

        $vector = $embeddingResponse->embeddings[0]->embedding;

        // 2. Vektör veritabanında benzer geçmiş sorular için arama yap
        $similarPastQuery = $this->vectorDb->search('cached_queries', $vector, limit: 1);

        // 3. Eğer %95'ten fazla benzerlik bulursak, önbellek yanıtını döndür
        if ($similarPastQuery && $similarPastQuery->score > 0.95) {
            return $similarPastQuery->metadata['answer'];
        }

        // 4. Aksi halde LLM'ye sor
        $llmResponse = OpenAI::chat()->create([
            'model' => 'gpt-4-turbo',
            'messages' => [['role' => 'user', 'content' => $question]],
        ]);

        $answer = $llmResponse->choices[0]->message->content;

        // 5. Yeni soruyu ve yanıtı, gelecekteki kullanıcılar için vektör veritabanına kaydet
        $this->vectorDb->insert('cached_queries', [
            'vector' => $vector,
            'metadata' => [
                'question' => $question,
                'answer' => $answer
            ]
        ]);

        return $answer;
    }
}

Bu yaklaşım, kullanıcıların sıkça benzer sorular sorduğu AI müşteri destek robotları veya dokümantasyon asistanları gibi uygulamalar için API maliyetlerini önemli ölçüde azaltır.

Adım 4: API Kesintileri için Devre Kesiciler

OpenAI hizmet dışı kaldığında (ve kalacağını bilirsiniz), kuyruklarınız hızla başarısız işlerle dolar. Eğer kuyrukta 10,000 iş varsa ve hepsi başarısız olup yeniden denemeye geçerse, işçi kaynaklarınızı tüketirsiniz ve API tekrar çalıştığında IP’nizin yasaklanmasıyla sonuçlanabilirsiniz.

Bir devre kesiciye ihtiyacınız var. Devre kesici, ardışık hataları izler. Hata oranı belirli bir eşiği geçerse, devre “açılır” ve sonraki talepler hemen reddedilir veya API’yi denemeden önce bekletilir. Bir soğuma döneminin ardından, “yarı açık” bir duruma izin verilir.

namespace App\Jobs\Middleware;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

class OpenAICircuitBreaker
{
    public function handle($job, $next)
    {
        if (Cache::has('openai_circuit_open')) {
            Log::warning('Devre kesici açık. İş serbest bırakılıyor.');
            $job->release(300); // 5 dakika beklet
            return;
        }

        try {
            $next($job);
            // Başarılı olursa, hata sayacını sıfırla
            Cache::forget('openai_consecutive_failures');
        } catch (\Exception $e) {
            $failures = Cache::increment('openai_consecutive_failures');

            if ($failures >= 10) {
                // Devreyi 5 dakika için aç
                Cache::put('openai_circuit_open', true, 300);
                Log::critical('OpenAI Devre Kesici AÇILDI!');
            }

            throw $e;
        }
    }
}

Daha sonra bu ara yazılımı işinize ekleyebilirsiniz:

public function middleware()
    {
        return [new \App\Jobs\Middleware\OpenAICircuitBreaker];
    }

Sonuç

Bir AI wrapper oluşturmak kolaydır. Ancak ölçeklendirmek zordur. LLM API’lerine yavaş, dış mikro hizmetler gibi mimari bir saygı göstererek, trafik zirvelerini ve API kesintilerini atlatan dayanıklı uygulamalar geliştirebilirsiniz.

Temel Noktalar:

• HTTP isteğini asla bloke etmeyin: LLM çağrıları için her zaman kuyrukları kullanın.
• Limit aşımını nazikçe yönetin: 429 hatalarını yakalayın ve üstel geri çekilme uygulayın.
• Agresif önbellekleme yapın: Statik istemler için kesin dize eşleştirmesi ve kullanıcı sorguları için anlamsal önbellekleme kullanın.
• İşçilerinizi koruyun: API kesintileri sırasında kuyruk stampede’lerini önlemek için devre kesiciler uygulayın.

Bu desenleri uygulayarak, Laravel uygulamanızın hızla çalışmasını, işçilerin sağlıklı kalmasını ve OpenAI faturanızı yönetilebilir düzeyde tutmasını sağlayabilirsiniz.

Tartışma Konusu

Uygulamalarınızda “AI N+1 problemi” ile karşılaştınız mı? LLM API maliyetlerini azaltmak için en etkili önbellekleme stratejileri neler?

Kaynak: Orijinal Makale