Yazılım

Laravel AI SDK Eğitimi: 30 Dakikada Akıllı Asistan Oluşturma

Son güncelleme: 10 Şubat 2026 12:30

teknomers

Paylaş

Paylaş

Orijinal kaynak hafiz.dev

<hr/>

<p>Taylor Otwell ve Josh Cirre, Laravel AI SDK ile AI uygulamaları geliştirdikleri <a href="https://www.youtube.com/watch?v=8MJ7r6niTus" target="_blank" rel="noopener noreferrer">2 saatlik bir yayın</a> gerçekleştirdi. Bunu izledim. Kısaca diyebilirim ki, bu SDK, çoğu eğiticinin gösterdiğinden daha pratik.</p>

<p>Geçen hafta çıkışında, <a href="https://dev.to/blog/laravel-ai-sdk-what-it-changes-why-it-matters-and-should-you-use-it">AI SDK’nın neyi değiştirdiğini ve neden önemli olduğunu</a> ele aldım. Bu yazı "bunu kullanmalı mıyım?" sorusuna odaklanıyor. Burada pratik bir uygulama yapacağız.</p>

<p>Bir belge analizör ajanı inşa edeceğiz. Bu ajan, metni (veya bir dosyayı) alır, yapılandırılmış analiz ile geri döner; özet, ana konular, duygu puanı ve eylem maddeleri içerir ve yanıtı gerçek zamanlı olarak akıtır. Laravel uygulamanızda yaklaşık 30 dakikada çalışır bir AI özelliği elde edeceksiniz.</p>

<p>Şimdi başlayalım.</p>

<h2>
    <a name="what-youll-need" href="#what-youll-need"></a>
    İhtiyacınız Olanlar
</h2>

<p>Burada çılgın bir şey yok:</p>

<ul>
    <li>Laravel 12.x (temiz kurulum veya mevcut bir proje)</li>
    <li>PHP 8.2+</li>
    <li>Bir OpenAI API anahtarı (veya tercih ettiğiniz Anthropic, Gemini vb.)</li>
</ul>

<p>Örneklerde OpenAI kullanıyorum ama SDK’nın amacı işte bu. Sağlayıcıları tek bir satırlık değişiklikle değiştirebilirsiniz. Daha sonra bunun üzerinde duracağız.</p>

<h3>
    <a name="installation" href="#installation"></a>
    Kurulum
</h3>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>composer require laravel/ai

php artisan vendor:publish –provider=”Laravel\Ai\AiServiceProvider”
php artisan migrate

<p>Son komut önemlidir. SDK, konuşma belleği için <code>agent_conversations</code> ve <code>agent_conversation_messages</code> tablolarını oluşturur. Göçü atlayırsanız, ilk kez herhangi bir konuşma denemesi yaptığınızda kafa karıştırıcı bir tablo-bulunamadı hatası alırsınız.</p>

<p>Şimdi API anahtarınızı <code>.env</code> dosyasına ekleyin:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>OPENAI_API_KEY=sk-your-key-here

Ya da Anthropic tercih ediyorsanız:

ANTHROPIC_API_KEY=your-key-here

<p>Kısa bir ipucu: Deneme yaparken API çağrısı için ödeme yapmak istemiyorsanız, <a href="https://ollama.com" target="_blank" rel="noopener noreferrer">Ollama</a>'yı kurun ve yerel bir model indirin. SDK bunu sağlayıcı olarak destekliyor. Ücretsiz ve hızlı bir test imkanı sunuyor.</p>

<h2>
    <a name="step-1-create-your-first-agent" href="#step-1-create-your-first-agent"></a>
    1. Adım: İlk Ajanınızı Oluşturun
</h2>

<p>Artık eğlenceli kısma geldik. Tek bir artisan komutuyla:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>php artisan make:agent DocumentAnalyzer

<p>Bu, <code>app/Ai/Agents/DocumentAnalyzer.php</code> dosyasını oluşturur. Aşağıdaki gibi doldurulmuş sınıf olarak neye benzediği:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><?php 

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class DocumentAnalyzer implements Agent
{
use Promptable;

/ 
 * Get the instructions that the agent should follow.
 */
public function instructions(): string
{
    return 'You are a document analysis assistant. When given text or a document, '.
        'provide a concise summary, identify the key topics discussed, '.
        'rate the overall sentiment from 1 (very negative) to 10 (very positive), '.
        'and list any action items or next steps mentioned in the content. '.
        'Be specific and practical in your analysis.';
}

}

<p>Hepsi bu kadar. Ajan sınıfı her şeyi kapsar: sistem komutunuz, araç yapılandırması, çıktı şeması. <a href="https://studylab.app" target="_blank" rel="noopener noreferrer">StudyLab</a> uygulamasını geliştirirken tüm bunları manuel olarak birleştirmek zorunda kaldım. Özel servis sınıfları, yanıt ayrıştırma, hata yönetimi. Ajan deseni, hepsini tek temiz ve tekrar kullanılabilir bir sınıf halinde toplar.</p>

<p>Taylor, yayın sırasında ajanların SDK’nın en sevdiği kısmı olduğunu belirtti. Onları, uygulamanızda kullanabileceğiniz, kendi kendine yeterli birim gibi tasarladı. Aynı ajan, bir artisan komutunda, bir kontrolcüde veya bir kuyruklu işte kullanılabilir. Promtu değiştirmenin bir yeri var ve bu her yerde güncelleniyor.</p>

<p>Şimdi bunu test edelim. En hızlı yol bir rota oluşturmaktır:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>use App\Ai\Agents\DocumentAnalyzer;

Route::post(‘/analyze’, function (Request $request) {
$response = (new DocumentAnalyzer)->prompt($request->input(‘text’));

return [
    'analysis' => (string) $response,
];

});

<p>Bu uç noktaya biraz metin ile eriştiğinizde, bir AI tarafından üretilmiş bir analiz alacaksınız. Çalışıyor. Ancak yanıt sadece büyük bir string. Veritabanında belirli alanlar saklamak veya yapılandırılmış bir UI'de görüntülemek istiyorsanız çok kullanışlı değil.</p>

<p>Burada yapılandırılmış çıktı devreye giriyor.</p>

<h2>
    <a name="step-2-add-structured-output" href="#step-2-add-structured-output"></a>
    2. Adım: Yapılandırılmış Çıktı Ekleyin
</h2>

<p>Bu özellik, geçmiş projelerde bana en çok zaman kazandıracak özellik olabilirdi. <a href="https://replygenius.io" target="_blank" rel="noopener noreferrer">ReplyGenius</a>'te, AI'nın belirli bir formatta yanıt seçenekleri döndürmesini sağlamam gerekiyordu: ton, uzunluk, yanıt metni. Özel JSON ayrıştırma yazmak zorundaydım, modelin hatalı JSON döndürdüğü durumları yönetmeliydim (bu düşündüğünüzden daha sık gerçekleşiyor) ve her alanı manuel olarak doğrulamalıydım.</p>

<p>SDK bunların hepsini yönetir. İlk olarak, bir şema sınıfı oluşturun:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><?php 

namespace App\Ai\Schemas;

use Laravel\Ai\Schema;
use Laravel\Ai\SchemaProperty;

[Schema]

class AnalysisResult
{
public function __construct(

[SchemaProperty(description: ‘A 2-3 sentence summary of the document’)]

    public string $summary,

    #[SchemaProperty(description: 'Array of key topics discussed')]
    public array $topics,

    #[SchemaProperty(description: 'Sentiment score from 1 (negative) to 10 (positive)')]
    public int $sentiment,

    #[SchemaProperty(description: 'Action items or next steps found in the document')]
    public array $actionItems,
) {}

}

<p>Şimdi, ajanınızı bunu kullanacak şekilde güncelleyin:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><?php 

namespace App\Ai\Agents;

use App\Ai\Schemas\AnalysisResult;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class DocumentAnalyzer implements Agent
{
use Promptable;

public function instructions(): string
{
    return 'You are a document analysis assistant. Analyze the given content '.
           'and return a structured analysis with summary, topics, sentiment, '.
           'and action items. Be specific and practical.';
}

public function schema(): string
{
    return AnalysisResult::class;
}

}

<p>Artık ajanı çağırdığınızda, bir tür nesne dönecek:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>$result = (new DocumentAnalyzer)->prompt($text);

$result->summary; // “The document discusses quarterly sales performance…”
$result->topics; // [“Q4 revenue”, “customer churn”, “expansion plans”]
$result->sentiment; // 7
$result->actionItems; // [“Schedule follow-up with enterprise team”, “Review pricing model”]

<p>JSON ayrıştırma yok. Doğrulama yok. Model bazen yanıtlarını markdown kod bloklarına sarmaladığında meydana gelen baş ağrısı yok. Sadece yazılı PHP özelliklerini elde edersiniz.</p>

<p>Geliştirme sırasında, genellikle bir <a href="https://dev.to/tools/json-formatter">JSON biçimlendirici</a> ile ham yanıtı inceliyorum, böylece şemanın beklediğim şeyi ürettiğinden emin olabiliyorum. Bu, OpenAI yanıtlarını hata ayıklamak konusundaki eski bir alışkanlığım ama hala faydalı.</p>

<h2>
    <a name="step-3-accept-file-attachments" href="#step-3-accept-file-attachments"></a>
    3. Adım: Dosya Lampadını Kabul Edin
</h2>

<p>Şu ana kadar ham metni ajana ilettik. Ancak, gerçek kullanım durumlarının çoğu dosyaları içerir. Toplantı transkriptleri, PDF’ler, sözleşmeler, vb.</p>

<p>SDK, <code>attachments</code> parametresi ile bunu basit hale getirir:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>use App\Ai\Agents\DocumentAnalyzer;

Route::post(‘/analyze’, function (Request $request) {
$request->validate([
‘document’ => ‘required|file|max:10240’, // 10MB max
]);

$result = (new DocumentAnalyzer)->prompt(
    'Analyze this document thoroughly.',
    attachments: [
        $request->file('document'),
    ],
);

return [
    'summary' => $result->summary,
    'topics' => $result->topics,
    'sentiment' => $result->sentiment,
    'action_items' => $result->actionItems,
];

});

<p>Yüklenmiş dosyaları doğrudan geçebilirsiniz. SDK, bunları sağlayıcıya doğru formatta göndermeyi yönetir. Daha büyük dosyalarla uğraşıyorsanız, yüklemeleri yönetirken <a href="https://dev.to/blog/handling-large-file-uploads-in-laravel-without-crashing-your-server">büyük dosya yüklemeleri yönetme hakkındaki kılavuzuma</a> göz atabilirsiniz.</p>

<p>Ayrıca birden fazla dosya ekleyebilirsiniz:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>$result = (new DocumentAnalyzer)->prompt(
'Compare these two documents and highlight the differences.',
attachments: [
    $request->file('document_v1'),
    $request->file('document_v2'),
],

);

<p>Gerçekten bu kadar. Hiçbir base64 kodlama, AI sağlayıcı tarafında çok parçalı form yönetimi yok. Sadece dosyaları geçin.</p>

<h2>
    <a name="step-4-stream-the-response" href="#step-4-stream-the-response"></a>
    4. Adım: Yanıtı Akıtın
</h2>

<p>AI yanıtları hakkında bir gerçek var. Kullanıcılar 5-10 saniye boyunca yüklenme simgesine bakmaktan hoşlanmaz. ChatGPT tarzı bir deneyim beklerler; metin kademeli olarak görünür olmalıdır. Taylor, bu yayında özellikle buna vurgu yaptı. Akış, önceliklerden biri çünkü kullanıcılar artık bunu bekliyor.</p>

<p> <code>-&gt;prompt()</code> metodunu <code>-&gt;stream()</code> ile değiştirin:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>use App\Ai\Agents\DocumentAnalyzer;

Route::post(‘/analyze’, function (Request $request) {
return (new DocumentAnalyzer)->stream(
‘Analyze this document.’,
attachments: [$request->file(‘document’)],
)->then(function ($response) {
// Bu akış tamamlandığında çalışır
// Veritabanına kaydet, bildirim gönder, ne varsa
logger(‘Analysis complete’, [
‘summary’ => $response->summary,
]);
});
});

<p><code>-&gt;stream()</code> metodu bir SSE (sunucu-tarafından gönderilen olaylar) yanıtı döndürür. Ön uçta, stack’inize bağlı olarak bunu kullanabilirsiniz:</p>

<ul>
    <li><strong>Livewire</strong>: <code>wire:stream</code> direktifini kullanın</li>
    <li><strong>Vue/React ile Inertia</strong>: <code>useStream</code> kancasını kullanın</li>
    <li><strong>Vanilla JS</strong>: Standart <code>EventSource</code> API'si</li>
</ul>

<p><code>-&gt;then()</code> geri çağırması oldukça kullanışlıdır. Tüm parçalar akıtıldıktan sonra çalışır. Sonucu veritabanınıza kaydetmek veya bildirim göndermek için mükemmel bir yerdir. Şema kullanıyorsanız, yapılandırılmış çıktı özelliklerine de erişiminiz olur.</p>

<p>Şunu itiraf etmeliyim ki, ön uçta SSE’i ayarlamak geçmişte sinir bozucuydu. Yeniden bağlanma, parçaları ayrıştırma, tarayıcı uyumluluğu ile uğraşma. SDK, arka uç kısmını tamamen soyutlamaktadır. Ön uç hala kurulumunuza bağlı olarak biraz çalışmaya ihtiyaç duysa da, kendi akış uç noktanızı oluşturmak kadar acı verici değil.</p>

<h2>
    <a name="step-5-write-tests" href="#step-5-write-tests"></a>
    5. Adım: Test Yazın
</h2>

<p>Bu bölüm çoğu eğitimin atlattığı kısmı. Atlama.</p>

<p>AI özelliklerini test etmek gerçekten zordu. Yanıtlar deterministik değil. Modelin iki kez aynı metni döndüreceğini garanti edemezsiniz. Taylor, SDK için bunu öncelikli hale getirdi çünkü topluluğun AI entegrasyonları ile ilgili testleri genellikle göz ardı ettiğini hissetti.</p>

<p>Çözüm temiz:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><?php 

use App\Ai\Agents\DocumentAnalyzer;
use App\Ai\Schemas\AnalysisResult;

test(‘it analyzes a document and returns structured output’, function () {
DocumentAnalyzer::fake(new AnalysisResult(
summary: ‘The document covers Q4 sales performance.’,
topics: [‘revenue’, ‘growth’],
sentiment: 8,
actionItems: [‘Review pricing’],
));

$response = $this->postJson('/analyze', [
    'document' => UploadedFile::fake()->create('report.pdf', 100),
]);

$response->assertOk();
$response->assertJsonFragment([
    'summary' => 'The document covers Q4 sales performance.',
]);

});