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
- OpenAI Ultrafast modu — gecikmeye duyarlı senaryolarda ne değişiyor.
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.
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.
