Laravel için LLM Gözlemlenebilirliği – Langfuse ile her AI çağrısını takip et

Laravel ile AI özellikleri geliştiriyorsanız, bu özelliklerin performansını ve maliyetini kolayca değerlendiremiyor olabilirsiniz. Hangi belgelerin getirildiğini, üretim sürecinin ne kadar sürdüğünü veya sorgu başına maliyetin ne olduğunu tam olarak bildiğinizden değil.

Laravel AI için hazır. Observability eksikti.

Laravel AI SDK’sı Şubat 2026’da piyasaya sürüldü. Prism üzerine inşa edilen bu SDK, Laravel’de LLM çağrıları için tercih edilen paket haline geldi. Neuron AI, ajan iş akışları için popülerlik kazanıyor. Laravel 13 ile AI, framework içinde birinci sınıf bir konu haline geldi.

Laravel ile ajanlar, RAG boru hatları ve LLM özellikleri artık deneysel değil. Ancak bu özellikler üretimde çalıştığında, her şey gözden kaçıyor.

Hangi belgeler retrieval ediliyor? Üretim süresi ne kadar? Sorgu başına maliyet nedir? Çıktı gerçekten doğru mu? Python ve JavaScript geliştiricilerinin bu tür sorularla başa çıkabilmesi için yıllardır olgun araçları bulunuyor. Ancak Laravel için hiçbir şey yoktu.

Langfuse Nedir?

Langfuse, açık kaynaklı bir LLM observability platformudur. Bunu “LLM çağrılarınız için Sentry” olarak düşünebilirsiniz, ancak AI uygulamaları için özel olarak tasarlanmıştır.

Langfuse ile elde edeceğiniz özellikler:

• İzleme – her LLM çağrısı, retrieval adımı, araç çağrısı ve ajan eylemi için iç içe geçmiş bir zaman çizelgesi
• Maliyet takibi – model bazında, kullanıcı bazında token kullanımı ve maliyetler
• Prompt yönetimi – merkezi bir UI’den prompt’ları sürümleyin, dağıtın ve A/B test yapın
• Değerlendirme – izleme verilerine puan ekleyin, LLM-as-judge değerlendirmeleri yapın, kullanıcı geri bildirimlerini toplayın

Langfuse, kendi barındırabileceğiniz veya yönetilen bir bulut hizmeti olarak kullanılabilir. Açık kaynaklıdır, 24K+’dan fazla GitHub yıldızı vardır ve binlerce firma tarafından kullanılmaktadır. Ancak SDK’lar yalnızca Python ve JavaScript işlemektedir. PHP yok.

laravel-langfuse

Bu nedenle ben de laravel-langfuse adında, uygulamanızı Langfuse ile bağlayan temiz bir API sunan bir Laravel paketi geliştirdim.

Kurulum için:

composer require axyr/laravel-langfuse

Kimlik bilgilerinizi ekleyin:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...

LLM çağrısını izleyin:

use Axyr\Langfuse\LangfuseFacade as Langfuse;
use Axyr\Langfuse\Dto\TraceBody;
use Axyr\Langfuse\Dto\GenerationBody;
use Axyr\Langfuse\Dto\Usage;

$trace = Langfuse::trace(new TraceBody(name: 'chat-request'));

$generation = $trace->generation(new GenerationBody(
    name: 'chat-completion',
    model: 'gpt-4',
    input: [[=> , => ]],
));

// LLM yanıt verdikten sonra:
$generation->end(
    output: ,
    usage: new Usage(input: 24, output: 150, total: 174),
);

Yukarıdaki, manuel API’dir. Ancak gerçek güç, bir sonraki aşamadadır.

Zero-code otomatik izleme

En heyecan verici özellik bu.

Prism kullanıyorsanız, sadece bir satır eklemek yeterlidir:

LANGFUSE_PRISM_ENABLED=true

Her Prism::text(), Prism::structured(), ve Prism::stream() çağrısı artık Langfuse’de otomatik olarak bir izleme kaydı ve üretim oluşturur. Model adı, parametreler, token kullanımı, gecikme süreleri, hatalar — uygulama kodunuza dokunmadan hepsi kaydedilir.

Bu aynı zamanda Laravel AI SDK’sı için de geçerlidir:

LANGFUSE_LARAVEL_AI_ENABLED=true

Her ajan istemi, her araç çağrısı, her akış yanıtı – otomatik olarak izlenir. Ajan çağrıları izleme oluşturan üretimlerle, araç çağrıları argümanlar ve sonuçlarla izleme oluşturur.

Uygulamada nasıl göründüğüne bir örnek

Burası, bir RAG boru hattından alınan gerçek bir izleme kaydıdır — bir retrieval span ile bir embedding üretimi ve vektör arama, ardından bir tamamlama üretimi. Tüm bunlar Laravel’den gönderilmiş olup, Langfuse kontrol panelinde görünmektedir.

İç içe geçmiş yapı, her üretim için token sayıları, toplam maliyet, gecikme analizi, gerçek giriş/çıkış ve hatta bir değerlendirme puanı (cevap uygunluğu: 0.92) görebilirsiniz.

Middleware ile isteğe bağlı izleme

Middleware’i rotalarınıza ekleyerek, her HTTP isteği kendi izleme kaydını alır. Bu istekteki tüm LLM çağrıları otomatik olarak bu kaydın altına yerleştirilir:

use Axyr\Langfuse\Http\Middleware\LangfuseMiddleware;

Route::middleware(LangfuseMiddleware::class)->group(function () {
    Route::post(, ChatController::class);
});

İzleme kaydı, rota adını, kimlik doğrulanmış kullanıcı ID’sini ve istek meta verilerini toplar. Bir istekte üç Prism çağrısı varsa? Bir izleme, üç iç içe geçmiş üretim. Manuel bağlama yok.

Prompt yönetimi

Langfuse’den prompt’ları alın, bunları değişkenlerle birleştirerek izlemelerinize bağlayın:

$prompt = Langfuse::prompt();
$compiled = $prompt->compile([=> ]);

$generation = $trace->generation(new GenerationBody(
    name: ,
    model: ,
    promptName: $prompt->getName(),
    promptVersion: $prompt->getVersion(),
));

Prompt’lar, stale-while-revalidate ile bellek içinde önbelleğe alınır. API kapalıysa, eski önbellek döndürülür. Hiç önbellek yoksa bir yedek sağlayabilirsiniz:

$prompt = Langfuse::prompt(, fallback: );

Test Etme

Paket, HTTP çağrısı yapmadan olayları kaydeden bir sahte ile birlikte gelir:

$fake = Langfuse::fake();

// Uygulama kodunu çalıştırın...
$trace = Langfuse::trace(new TraceBody(name: ));
$trace->generation(new GenerationBody(name: ));

// Ne olduğunu doğrulayın
$fake->assertTraceCreated()
    ->assertGenerationCreated()
    ->assertEventCount(2);

Bu, Http::fake() ve Queue::fake() ile aynı deseni takip eder. Eğer Laravel konusunda tecrübeniz varsa, bunun nasıl çalıştığını zaten biliyorsunuzdur.

Üretime Hazır

Gerçek ortamda çalıştığında önemli olan bazı hususlar:

• Octane uyumlu – bağlam bağlamaları, talebe göre sıfırlanır, durum sızıntısı olmaz
• İşlem sıralı batched – LANGFUSE_QUEUE=langfuse ayarlayın ve olaylar, senkron HTTP çağrıları yerine görevler olarak dağıtılır
• Nazik degradasyon – API hataları yakalanır ve kaydedilir, asla fırlatılmaz
• Şutaja otomatik boşaltma – sıralanmış olaylar, uygulama kapandığında boşaltılır
• Langfuse v2 ve v3 – her ikisiyle de çalışır, bulut ve kendi barındırdığınız versiyon ile

Denemek İster Misiniz?

Paket, Packagist’te mevcuttur:

composer require axyr/laravel-langfuse

Her entegrasyon için çalışır durumda örnek projeler oluşturdum:

Daha fazla bilgi ve kaynak için: github.com/axyr/laravel-langfuse

Geri bildirimler, problemler ve yıldızlar her zaman değerlidir. Laravel’in AI ekosisteminde ihtiyacımız olan gözlem katmanıdır. Bunu düzeltelim.