Laravel ile OpenAI Entegrasyonu Rehberi

OpenAI ve Claude entegrasyonları arasında önemli farklılıklar vardır. API’lerin ve model ailelerinin farklı olduğu durumlarda, üretim stabilitesi açısından mimari gereksinimler neredeyse aynıdır. Laravel, AI entegrasyonlarının oluşturduğu sorunları çözmesi nedeniyle burada iyi bir seçimdir: bağımlılık sınırları, ortam izolasyonu, arka plan işlemleri, hata yönetimi ve gözlemlenebilirlik gibi sorunlar bu framework ile kolaylıkla aşılabilir.

Model İsimleri Hakkında

Bu rehber gpt-4o ve gpt-4o-mini’yi örnek olarak kullanır. OpenAI’nın model kataloğu hızla değiştiğinden her zaman OpenAI’nın resmi modeller referansını kontrol etmeyi unutmayın. gpt-3.5-turbo artık kullanılmıyor; gpt-4o-mini onun maliyet etkin bir alternatifidir.

OpenAI API Yüzeyi Anlayışınız

Özellikle Laravel uygulamaları için üç ayrı yetenek üzerine düşünmek yararlı olacaktır: metin üretimi ve akıl yürütme için Chat Completions API, anlamsal arama ve veri alma için Embeddings API, ve transkripsiyon ile çok modal girdi için Audio/Vision API’leri. Laravel mimarisi, bu ayrımı baştan itibaren yansıtmalıdır. Doğrudan Completions ve Embeddings uç noktalarını çağıran kontrolörler hızla bakım dışı kalacaktır.

Temeller

Kimlik Doğrulama ve Ortam Yapılandırması

OpenAI, hesap veya proje seviyesinde verilen API anahtarlarını kullanmaktadır. Bu anahtarları, veritabanı kimlik bilgileri veya ödeme tokenları gibi üretim sırları olarak değerlendirin.

OPENAI_API_KEY=sk-...
OPENAI_ORG_ID=optional

Bu değerleri, yapılandırma dosyaları dışında env() ile okumamalısınız. Bu, Laravel AI kod tabanlarında gördüğümüz en yaygın yapısal hatalardan biridir. Onları, özel bir yapılandırma dosyası aracılığıyla açığa çıkarın:

// config/openai.php
return [
    'api_key'      => env('OPENAI_API_KEY'),
    'organization' => env('OPENAI_ORG_ID'),
    'base_url'     => env('OPENAI_BASE_URL', 'https://api.openai.com/v1'),
];

Neden OpenAI SDK’sını Doğrudan Kullanmamalısınız?

OpenAI, PHP topluluğu uygulamaları da dahil olmak üzere resmi SDK’lar sağlamaktadır. Bunları doğrudan kontrolörlerde veya işlerinizde entegre etmek bir hatadır. SDK’lar değişebilir. Model isimleri değişebilir. Yanıt formatları gelişebilir. Uygulamanız bu dalgalanmayı absorbe etmemelidir.

class OpenAiClient
{
    public function __construct(
        protected HttpClient $http
    ) {}
}

Ve şöyle:

class OpenAiService
{
    public function __construct(
        protected OpenAiClient $client
    ) {}
}

HTTP İstemcisi Yapılandırması ve Zaman Aşımı

AI istekleri uzun sürebilir, maliyetler içerir ve yeniden denemelere duyarlıdır. Varsayılan Http::post() yeterli değildir. Açık bir davranışla özel bir istemci yapılandırın:

Http::withHeaders([
    'Authorization' => 'Bearer ' . config('openai.api_key'),
    'Content-Type'  => 'application/json',
])
->timeout(60)
->retry(0, 0);

Hata Yönetimi

OpenAI’nin Chat Completions API’SI, standart REST API’lerin nadiren gerçekleştirdiği şekillerde başarısız olur: kısmi yanıtlar, oran kısıtlamaları, model aşırı yüklenmesi gibi durumlar. Servis katmanınız, OpenAI yanıtlarını güvenilmez bir girdi olarak değerlendirmelidir.

$response = $this->client->post(...);
if (! $response->successful()) {
    throw new OpenAiRequestFailed(
        $response->status(),
        $response->body()
    );
}

Hizmet Mimarisi: Değişim için Tasarım

OpenAI servisinizi, düşük seviyeli API önermelerini açmamaya çalışın. Bunun yerine, iş niyetini ifade eden yöntemleri tercih edin:

$openai->generateText(...)
$openai->summarize(...)
$openai->extractStructuredData(...)

Bağımlılık Enjeksiyonu ve Test Edilebilirlik

OpenAI’ye bakan her sınıf enjekte edilebilir ve taklit edilebilir olmalıdır. Statik yardımcılar, HTTP çağrıları gizleyen yüzeyler veya çalışma anında env() okumaları olmamalıdır.

Çekirdek Entegrasyon Modelleri

Temel yapınız kurulduktan sonra, OpenAI uygulamanızın bir yeteneği haline gelir. Bu modeller, belirli yapısal kurallara ve Laravel standartlarına göre geliştirilmiştir.

1. Basit İstek-Cevap (Tek Seferlik Görevler)

class OpenAiService
{
    public function generateText(string $prompt): string
    {
        // implementation
    }
}

API çağrısını uygulamak için:

$response = $this->client->post('/chat/completions', [
    'model'    => 'gpt-4o',
    'messages' => [
        [
            'role'    => 'user',
            'content' => $prompt,
        ],
    ],
]);

2. Akış Yanıtları (Uzun Süreli Çıktılar)

Akış, kullanıcı deneyimini artırmak için kullanılır. Açık bir yanıt uzunluğuna sahip olduğunda ve zamanlama önemli olduğunda kullanılır. OpenAI, sunucu-tabanlı akışları Server-Sent Events (SSE) ile destekler.

return response()->stream(function () use ($prompt) {
    $this->openAi->streamText($prompt, function ($chunk) {
        echo "data: " . json_encode($chunk) . "\n\n";
        ob_flush();
        flush();
    });
}, 200, [
    'Content-Type'     => 'text/event-stream',
    'Cache-Control'    => 'no-cache',
    'X-Accel-Buffering' => 'no',
]);

3. Konuşma Hafızası (Çok Aşamalı Etkileşimler)

Çok adımlı akıl yürütme, yönlendirilmiş formlar ve içerik iyileştirme gibi durumlarda hafıza yönetimi önemlidir.

4. Arka Plan İşlemleri (Kuponlanmış AI Çalışmaları)

class GenerateSummaryJob implements ShouldQueue
{
    public function handle(OpenAiService $openAi): void
    {
        $summary = $openAi->summarize($this->document);
        $this->document->update(['summary' => $summary]);
    }
}

Gelişmiş Modeller ve Dağıtım Düşünceleri

OpenAI entegrasyonunu üretim ortamına getirdiğinizde, “Bu entegrasyon sorunsuz çalışıyor mu?” sorusu yerini “Ne sıklıkla başarısız oluyor?” ve “Zamanla maliyeti nedir?” gibi sorulara bırakır. Oran kısıtlamaları, sistem davranışı olarak ele alınmalıdır.

Sonuç

Artık Laravel ve OpenAI sisteminiz gerçek zamanlı arayüzleri, belge odaklı akıl yürütmeyi, çoklu model yönlendirmeyi ve ölçeklenmeye hazır bir yapıyı destekliyor. Servis sınırı, API değişikliklerinden, model kaymalarından ve sağlayıcı değişikliklerinden sizi korur.

Son Adımlar

Gerçek konuşma hafızası ve akış ile çalışmaya hazır mısınız? Laravel’da Claude API sohbet robotu inşa etmek, bu desenleri tamamen çalışan bir uygulamada gösterir.

Kaynak: Orijinal Makale