Bu AI API entegrasyonu rehberi, sitedeki yapay zeka API yazılarının merkezi. Hedef kitlesi belli: kendi PHP, Laravel veya WordPress projesine bir dil modeli bağlamak isteyen geliştirici. Sıra, gerçek bir entegrasyonun ilerlediği sıra — önce ilk çağrı, sonra maliyet ve hata yönetimi, en sonda kendi verinizle çalışan sistemler.
Sıfırdan Başlıyorsanız: İlk Entegrasyon

İlk hedef karmaşık bir mimari değil, çalışan tek bir istek. Sağlayıcı seçimini erken kilitlemeyin; üç büyük API de benzer kavramlar üzerine kurulu ve aralarında geçiş yapmak, kodu ilk günden bir servis katmanının arkasına koyduysanız sağlayıcı farkları için yeniden uyarlama ve değerlendirme gerektirir.
- PHP projesine ilk yapay zeka çağrısı — kurulum, anahtar yönetimi ve ilk yanıt.
- Claude API PHP entegrasyonu, Gemini API PHP entegrasyonu — aynı işin diğer iki sağlayıcıdaki karşılığı.
- Claude, OpenAI ve Gemini karşılaştırması — hangi işe hangisi, fiyat ve bağlam penceresi farkları.
- Local LLM mi, bulut API mi? — veri gizliliği ve maliyet açısından kritik ilk karar.
- OpenAI Responses API — eski Chat Completions alışkanlıklarının nerede değiştiği.
Üretime Geçerken: Maliyet, Hata ve Limitler

Demo ile üretim arasındaki fark neredeyse tamamen bu bölümde. Bir entegrasyon, mutlu senaryoda değil; limit dolduğunda, yanıt yarıda kesildiğinde ve fatura beklenenin üç katı geldiğinde sınanır.
- Token maliyetini azaltma — istem kısaltma, önbellekleme ve model seçimiyle gerçekçi tasarruf.
- Rate limit hatası ve üstel geri çekilme — kuyruk kullanmadan üretime çıkmanın riski.
- OpenAI API hataları — hangi hata kodunda yeniden denenir, hangisinde denenmez.
- Streaming ile gerçek zamanlı yanıt — algılanan hızın çoğu buradan gelir.
- Function calling ve adım adım entegrasyonu — modeli kendi fonksiyonlarınıza bağlamak.
- MCP: modeli araçlara bağlayan standart — function calling’in bir üst katmanı.
Kendi Verinizle Çalışan Sistemler: RAG ve Vektörler
Model, sizin verinizi bilmez. “Kendi dokümanlarım üzerinden cevap versin” isteğinin teknik karşılığı, modeli eğitmek değil; soruyla ilgili parçaları bulup istemin içine koymaktır. Bu üç yapı taşının sırası şu: metni vektöre çevir, bir yerde sakla, sorguda en yakınlarını getir.
- Embeddings nedir — metni sayısal vektöre çevirmenin mantığı ve maliyeti.
- Vector store seçimi — pgvector, Qdrant ve dosya tabanlı basit çözümler.
- RAG nedir, nasıl çalışır ve siteye RAG eklemek — kavramdan uygulamaya.
- Prompt engineering — RAG sonuçlarını işe yarar cevaba çeviren katman.
Metin Dışına Çıkmak: Ses, Görsel ve Moderasyon
- Speech to Text ile ses metne çevirme
- Vision API ile görsel analizi
- AI moderation sistemi — kullanıcı içeriği alan her projede erken kurulması gereken katman.
Uçtan Uca Örnek Projeler
Kavramlar oturduktan sonra en hızlı öğrenme yolu, küçük ama tamamlanmış bir proje. Aşağıdakiler siteye eklediğim, tek oturumda bitirilebilecek örnekler.
- PHP ile chatbot yapımı
- Müşteri destek botu
- Blog içerik asistanı ve SEO başlık/meta üretimi
- Laravel ile AI agent sistemi ve Laravel + OpenAI entegrasyonu
Entegrasyonu Bozan Dört Yaygın Hata
1. API anahtarını istemci tarafında tutmak. Anahtar tarayıcıya düşen her projede fatura er ya da geç başkasına yazılır. Çağrı her zaman sunucudan gider.
2. Zaman aşımını varsayılan bırakmak. Uzun yanıtlar PHP’nin varsayılan süresini aşar. Streaming kullanmıyorsanız zaman aşımını bilinçli olarak yükseltmek ve isteği kuyruğa almak gerekir.
3. Yanıtı doğrulamadan kullanmak. JSON isteseniz de model bazen serbest metin döndürür. Şema doğrulaması olmayan entegrasyon, üretimde ilk haftasında kırılır.
4. Maliyeti sonradan ölçmek. Her isteğin token sayısını ve tahmini bedelini günlüğe yazmayan proje, hangi özelliğin pahalı olduğunu asla öğrenemez.
Sağlayıcı Seçerken Neye Bakılır?
Model kalitesi tek başına karar verdirmez. Gerçek projelerde seçimi belirleyen dört değişken var ve bunların üçü modelin kendisiyle değil, çevresindeki altyapıyla ilgili.
| Değişken | Neden önemli | Nasıl ölçülür |
|---|---|---|
| Bağlam penceresi | Uzun dokümanla çalışacaksanız parçalama maliyetini belirler | Tipik girdinizin token sayısını ölçün, iki katını hedefleyin |
| Girdi/çıktı fiyat farkı | Çoğu sağlayıcıda çıktı, girdiden birkaç kat pahalıdır | Gerçek trafikten örnek alıp aylık tahmin çıkarın |
| Rate limit yapısı | Dakikadaki istek mi, token mı sınırlı — mimariyi bu belirler | Sağlayıcının katman tablosunu projenizin tepe yüküyle karşılaştırın |
| Yapılandırılmış çıktı desteği | Şemaya uygun JSON garantisi, doğrulama kodunu ciddi biçimde azaltır | Şema zorlaması var mı, yoksa yalnızca istemle mi sağlanıyor |
Maliyeti Baştan Hesaplamak
Bir özelliğin aylık bedeli, tek istekteki token sayısı × aylık istek sayısı × birim fiyat kadardır. Kaba bir örnek: ortalama 1.500 giriş ve 500 çıkış tokenı harcayan bir destek botu, günde 200 konuşma alıyorsa tek çağrı/konuşma ve 30 gün varsayımıyla ayda yaklaşık 9 milyon giriş ve 3 milyon çıkış tokenı üretir. Bu sayıyı sağlayıcının fiyat listesiyle çarpmak, projeye başlamadan önce yapılabilecek en faydalı beş dakikalık iştir.
Maliyeti düşürmenin sırası da bellidir ve model küçültmek listenin sonunda gelir: önce istemi kısaltın, sonra tekrar eden bağlamı önbelleğe alın, sonra kolay soruları küçük modele yönlendirin. Bu adımların kazancı kullanım örüntüsüne bağlıdır; sabit yüzde tasarruf yoktur; model değişikliği ise kalite kaybı riski taşır.
PHP ve Laravel İçin Güvenli Entegrasyon Mimarisi
İlk başarılı isteği gönderdikten sonra kodu doğrudan bir sayfa denetleyicisinde bırakmayın. Kullanıcı girdisini doğrulayan katman, sağlayıcıya istek gönderen hizmet, yanıtı uygulamanın anlayacağı biçime çeviren katman ve hataları kaydeden katman birbirinden ayrılmalıdır. Böyle bir yapı model veya sağlayıcı değiştiğinde bütün uygulamayı yeniden yazmayı önler. Başlangıç için her şeyi soyutlayan büyük bir çatı kurmak da gerekmez. Önce tek bir görevin girdi ve çıktı sözleşmesini yazın: örneğin gelen destek metninden konu etiketi ve kısa özet üretmek.
API anahtarını yalnızca sunucu tarafında saklayın. Laravel ortam değişkeni veya gizli anahtar yöneticisi kullanabilir; tarayıcı JavaScript dosyasına, mobil uygulama paketine ya da Git deposuna gömülen anahtar kullanıcıya açılır. Ayar okumasını yapılandırma dosyasından yapın ve üretimde yapılandırma önbelleğinin güncellendiğinden emin olun. Hata kaydına anahtarı, tam kullanıcı metnini veya hassas müşteri bilgisini yazmayın. Geliştirici için yeterli olan alanlar çoğu zaman istek kimliği, işlem türü, süre, durum kodu ve maliyet ölçüsüdür.
Formdan gelen girdiye bir üst sınır koymak önemlidir. Çok büyük metin hem gereksiz maliyet üretir hem yanıtı geciktirir. Bu sınırı yalnızca karakter sayısı olarak düşünmeyin; sağlayıcının kullandığı token ölçüsü ve modele ayrılan çıktı alanı da hesaba katılmalıdır. Kullanıcıya belirsiz bir “hata oluştu” mesajı yerine, sınır aşıldığında hangi dosyanın veya alanın küçültülmesi gerektiğini açıklayın. Çok uzun belgeleri körlemesine kesmeyin; parçalara ayırma veya ilgili bölümü seçme yöntemini kullanın.
Yanıtı Uygulama Verisi Olarak İşleme
Bir model yanıtı ekranda okunabilir olsa bile uygulama mantığı için her zaman geçerli veri değildir. “Durum: onaylandı” gibi serbest metni ayrıştırarak sipariş statüsü değiştirmek kırılgandır. Sağlayıcının desteklediği yapılandırılmış çıktı veya araç çağrısı şemasını kullanın; gelen veriyi ayrıca PHP tarafında doğrulayın. Zorunlu alan, tür ve izin verilen değer denetiminden geçmeyen yanıtı işlemeyin. Modelin ürettiği e-posta adresi, dosya yolu veya bağlantı da güvenilmeyen girdi sayılmalıdır.
Entegrasyonda kullanıcıya görünen metin ile sisteme komut olarak verilen metni ayrı düşünün. Kullanıcı, belge veya web sayfası içindeki “önceki kuralları yok say” gibi bir ifade uygulamanızın yetkisini artırmamalıdır. Dışarıdan gelen içeriği talimat hiyerarşisinde en düşük güven düzeyinde ele alın. Özellikle veri tabanında silme, ödeme, e-posta gönderme ve dış hizmete dosya yükleme gibi işlemler için uygulama tarafında yetki denetimi ve gerektiğinde insan onayı gerekir. Model tek başına iş kuralı uygulayan son karar mercii olmamalıdır.
Hata Kodlarına Göre Doğru Tepki
Ağ zaman aşımı, kimlik doğrulama hatası ve hız sınırı aynı şekilde ele alınmamalıdır. Kimlik doğrulama başarısızsa yapılandırma ve anahtar yetkisini denetleyin; aynı isteği arka arkaya göndermek çözüm olmaz. Geçici hız sınırında sağlayıcının Retry-After başlığı varsa buna uyun ve sınırlı sayıda yeniden deneme yapın. Kota veya faturalama kaynaklı sınır, geçici yoğunlukla karıştırılmamalıdır. Sunucu hatasında da yeniden deneme sayısı, artan bekleme süresi ve en yüksek toplam işlem süresi tanımlayın.
Laravel HTTP istemcisi timeout, connectTimeout ve retry seçenekleri sağlar. Varsayılan değerleri uygulamanın kullanıcı deneyimi için yeterli kabul etmeyin. Bir sayfa isteği üç kez uzun süre bekleyip sonunda başarısız olursa kullanıcı belirsizlik içinde kalır. Kısa işler için makul bir üst süre belirleyin; uzun işler için kuyruğa aktarın, işlem durumunu saklayın ve kullanıcıya durum ekranı gösterin. Ağ bağlantısı hiç kurulamadığında oluşan istisnayı HTTP yanıt hatasından ayrı yakalamak gerekir. Hata günlüklerinde istek kimliğini tutmak sağlayıcı desteğiyle incelemeyi kolaylaştırır.
Maliyet ve Hız Kontrolünü Ölçümle Kurun
Model maliyetini yalnızca istek başına fiyat üzerinden hesaplamayın. Girdi uzunluğu, çıktı uzunluğu, tekrar denemeler, arka planda yapılan ek sorgular ve araç kullanımı toplam maliyeti belirler. Önce gerçek kullanımdan örnek alın. Hangi görevlerde kısa yanıt yeterli, hangi görevlerde uzun bağlam gerekiyor, bunu kaydedin. Sabit uzun bir yönergeyi her isteğe eklemek gerekiyorsa sağlayıcının önbellekleme seçeneklerini araştırın. Bir küçük modelin aynı doğrulukla görevi bitirip bitirmediğini temsilî test kümesinde ölçün.
Kullanıcı başına hız ve harcama sınırı koyun. Tek bir kötüye kullanım veya sonsuz yeniden deneme döngüsü bütçeyi tüketebilir. Üretim ve test ortamı için ayrı anahtar ve bütçe ayırmak hata ayıklamayı kolaylaştırır. Maliyet alarmı yalnızca haber verir; kesin harcama sınırı hizmeti durdurabilir. Bu nedenle işin devam etmesi açısından hangi düzeyde uyarı, hangi düzeyde durdurma gerektiğini belirleyin. Fiyatların ve model limitlerinin değişebileceğini unutmayın; yazıya sabit tutar gömmek yerine sağlayıcının güncel panelini esas alın.
RAG Kullanırken Kaynak ve Yetki Sınırı
RAG, yani ilgili belgeleri bulup modelin isteğine bağlam olarak ekleme, veri tabanındaki bütün bilgiyi modele “öğretmek” anlamına gelmez. Önce belgelerin erişim düzeyini, güncelliğini ve kimin hangi belgeyi görebileceğini belirleyin. Arama sonucu yalnızca oturum açmış kişinin yetkili olduğu parçaları döndürmelidir. Yanıtın hangi belgeye dayandığını kullanıcıya göstermek, yanlış bilginin denetlenmesini kolaylaştırır. Bulunan parça yetersizse modelin tahmin yürütmesi yerine “eldeki belgede bulunamadı” diyebilmesi gerekir.
Dokümanı küçük parçalara bölmek için tek bir ideal uzunluk yoktur. Parça sınırını cümleyi ortadan kesmeyecek biçimde seçin; başlık, belge sürümü ve kaynak adresi gibi metadata tutun. Eski bir politika belgesi ile yeni sürümü aynı anda arama sonucuna getiriyorsanız hangisinin geçerli olduğunu açıklayın. Belgeler değiştiğinde dizini yenileme sürecini tanımlayın. Hassas veriler varsa sağlayıcının saklama ve işleme koşullarını ayrıca değerlendirin; erişim kontrolü yalnızca indeks sorgusunda değil, veri hazırlama aşamasında da uygulanmalıdır.
Yayına Almadan Önce Test Listesi
Tek bir mutlu yol testinden sonra üretime geçmeyin. Boş girdi, çok uzun girdi, hatalı anahtar, yetkisiz kullanıcı, sağlayıcı zaman aşımı, hız sınırı, eksik alanlı yanıt ve tekrar edilen istek için test oluşturun. Yanıtın dili veya biçimi değiştiğinde uygulamanın güvenli şekilde durduğunu doğrulayın. Ücretli veya geri alınması güç işlemleri canlandıran testlerde sahte HTTP yanıtları kullanın. Laravel’in HTTP test araçları bu izolasyona yardımcı olur; gerçek API çağrısını yalnızca gerekli uçtan uca denemelerde çalıştırın.
Son kontrol kullanıcı deneyimidir. İşlem sürüyorsa bunu açıkça gösterin. Başarısız olduğunda yeniden deneme düğmesi veya destek yönlendirmesi sunun. Üretilen içeriği otomatik doğru kabul ettirmeyin; özellikle yayınlanacak metin, kod veya karar önerisi için inceleme imkânı verin. İzleme panelinde başarı oranını, gecikmeyi, hata türlerini ve kullanım maliyetini birlikte okuyun. Sağlayıcı değişirse aynı temsilî görevleri tekrar çalıştırın. Böylece ilk demosu çalışan entegrasyon, işletilebilir bir ürün hâline gelir.
Örnek Proje: Destek Mesajını Sınıflandırma
Somut bir uygulamada kullanıcı bir destek mesajı gönderir. Sunucu mesaj uzunluğunu ve oturum yetkisini denetler. Ardından API isteğinde yalnızca görev için gerekli metni gönderir: kategori, kısa özet ve “insan incelemesi gerekli mi?” alanlarını üretmesini ister. Yanıt geldiğinde kategori değerinin önceden tanımlı listede olduğunu ve özet uzunluğunun sınırı aşmadığını denetler. Kullanıcıya öneriyi gösterir, fakat bileti otomatik olarak kapatmaz. Böylece model ekip için zaman kazandırır; yanlış sınıflandırma müşterinin sorununu görünmez kılmaz.
İşlem başarısız olursa destek mesajı yine de kaydedilmelidir. Model hizmetinin geçici kesintisi müşterinin talebinin kaybolmasına neden olmamalıdır. Kuyruğa alınan görev tekrar denenebilir; ancak aynı mesaj için iki ayrı bilet oluşturulmasını önleyecek benzersiz işlem anahtarı kullanılmalıdır. Tekrarlanan isteklerde yan etkiyi kontrol etmek özellikle faturalama, mesaj gönderme veya dosya yazma içeren işlerde önemlidir. Modelin yanıtı gecikirse arayüzde “işleniyor” durumu ve sonradan görüntülenebilen sonuç sunun.
Başarıyı yalnızca “yanıt döndü” diye ölçmeyin. Kategori doğruluğunu insan etiketli küçük bir örnek kümede kontrol edin; yanlış negatiflerin neye mal olduğunu değerlendirin. Özetlerde müşteri adının veya özel bilginin gereksiz yere tekrarlanıp tekrarlanmadığına bakın. Yeni model sürümü, yönerge veya veri kaynağı değiştiğinde aynı örnekleri yeniden çalıştırın. Düşük maliyetli bir model, belirli bir görevde yeterli olabilir; diğer görevde eksik kalabilir. Seçimi tahmin yerine ölçüm belirlesin.
Sık Sorulan Sorular
Modeli kendi verimle eğitmem gerekir mi?
Çoğu durumda hayır. “Kendi verimle çalışsın” isteğinin yanıtı ince ayar değil, RAG’dir: ilgili parçaları bulup isteme eklemek. İnce ayar, biçim ve üslup tutarlılığı gerektiğinde anlamlı hale gelir; bilgi eklemek için verimli bir yol değildir.
API anahtarını nerede saklamalıyım?
Sunucu tarafında, ortam değişkeninde. Anahtarın tarayıcıya inen hiçbir dosyada bulunmaması gerekir. Kullanıcı arayüzünden yapılan çağrılar da kendi sunucunuzdaki bir uç noktaya gitmeli, oradan API’ye iletilmelidir.
Yanıtlar bazen çok yavaş geliyor, ne yapabilirim?
Algılanan hızı en çok streaming değiştirir: yanıt tamamlanmadan yazılmaya başlar. Bunun dışında istemi kısaltmak, çıktı uzunluğunu sınırlamak ve uzun işleri kuyruğa alıp sonucu bildirimle iletmek işe yarar.
Hangi hatalarda yeniden denemeliyim?
Geçici rate limit ve 5xx hatalarında sınırlı tekrar, jitter ve Retry-After kullanın. 429 kota/bakiye yetersizliğiyse beklemek çözmez. Yan etki üreten işlemler tekrar edileceğinde idempotency ve işlem durumu kontrolü gerekir; 400/401’i nedeni değişmeden tekrarlamayın.
Resmî kaynak: OpenAI API geliştirici hızlı başlangıç dokümantasyonu
Kaynaklar ve İleri Okuma
Resmî dokümantasyon
Token hesabında giriş, çıkış, cache, araç çağrısı, ses/görsel ve kullanılan model ayrı kalemlerdir. Çok turlu konuşmada geçmiş yeniden gönderilirse örnek hesabın üstüne eklenir. Structured output şema uyumuna yardımcı olur ama bilgi doğruluğu, ret veya yarım kalmış yanıt kontrolünün yerini almaz. RAG için vektör veritabanı zorunlu değildir; BM25/SQL veya hibrit retrieval mümkündür. Tool çağrısını sunucu tarafında izin ve parametre doğrulamasıyla sınırlandırın; MCP otomatik yetkilendirme değildir.


