WordPress AI Client API, WordPress 7.0 ile çekirdeğe giren, sağlayıcıdan bağımsız (provider-agnostic) bir PHP katmanıdır. Eklentiler tek bir wp_ai_client_prompt() çağrısıyla farklı model sağlayıcılarına bağlanır; yanıtlar normalize biçimde döner. Eklenti tarafı artık modeli değil, sözleşmeyi tanır.
Bu rehberde katmanın mimarisini, temel kullanım biçimini, sağlayıcı ve anahtar yönetimini, üretim ortamında maliyet ve hata yönetimini, güvenlik kontrollerini ve yayın öncesi kontrol listesini ele alıyoruz. Yazının sonunda sık sorulan sorular ve resmi kaynak bağlantıları yer alıyor.
WordPress 7.0’da yapay zeka katmanı: AI Client API’nin sözleşmesi
Temel giriş noktası wp_ai_client_prompt() fonksiyonudur ve akıcı (fluent) bir builder döndürür. Builder üzerinde isteği özelleştirir, ardından generate_text() gibi üretim metotlarıyla sonucu alırsınız. Eklenti geliştiricisinin görevi “ne istediğini” ve “nasıl istediğini” tanımlamaktır; hangi sağlayıcının çalışacağına ve anahtarın nerede saklanacağına WordPress karar verir.
Yapı iki bileşenden oluşur: alttaki PHP AI Client paketi sağlayıcı iletişimini yönetir, üstündeki WordPress sarmalayıcısı ise snake_case metot isimleri, WP_Error dönüşleri ve HTTP API entegrasyonu sağlar. Bu ayrım sayesinde eklenti geliştiricisi istisna yönetimiyle değil, alışılmış WordPress kod sözleşmesiyle çalışır.
Sözleşmenin pratikteki karşılığı
Sözleşme yaklaşımının en somut faydası taşınabilirliktir. Sağlayıcı değiştiğinde eklenti kodunu yeniden yazmanız gerekmez; yalnızca yönetim tarafındaki bağlantı ayarı değişir. Aynı mantığı harici servisler için kuran Connectors API ve yetenek tanımlarını standartlaştıran Abilities API yazıları, bu tasarımın çekirdekteki diğer örnekleridir.
Temel kullanım: metin üretimi ve yanıt yönetimi
En yalın kullanım, bir istem gönderip metin çıktısı almaktır. Dönen değerin her zaman hata kontrolünden geçirilmesi, eklentinin sağlayıcı kesintilerinde beyaz ekran üretmesini önler:
$result = wp_ai_client_prompt( $prompt )->generate_text();
if ( is_wp_error( $result ) ) {
error_log( '[eklentim] AI isteği başarısız: ' . $result->get_error_message() );
return $fallback_metin;
}
echo esc_html( $result );Üç kural üretim kodunda vazgeçilmezdir. Birincisi, model çıktısı her zaman kullanıcı girdisi gibi ele alınmalı ve çıktıdan önce kaçış (escape) uygulanmalıdır. İkincisi, uzun süren istekler ön yüz isteğini bloklamamalı; mümkünse zamanlanmış görevlere veya arka plan işine taşınmalıdır. Üçüncüsü, aynı istem için üretilen sonuç önbelleğe alınmalıdır.
İstem kalitesi çıktının kalitesini belirler
Katman ne kadar iyi tasarlanmış olursa olsun, sonucun kalitesi büyük ölçüde istemin netliğine bağlıdır. Rol, kısıt ve beklenen çıktı biçimini açıkça yazmak hataları belirgin biçimde azaltır; ilkeler için prompt engineering yazısına bakabilirsiniz.
Sağlayıcı yapılandırması ve anahtar yönetimi
Kimlik bilgileri eklenti kodunda değil, yönetim panelindeki bağlantı ekranında tutulur; her sağlayıcı kendi anahtarını yönetir ve registry üzerinden kullanılabilir hâle gelir. Bu model, anahtarın onlarca eklenti arasında kopyalanmasını önlediği için hem güvenlik hem bakım açısından avantajlıdır.
Eklenti tarafında yapılması gereken; anahtarın varlığını doğrulamak, yoksa kullanıcıya anlaşılır bir uyarı göstermek ve özelliği devre dışı bırakmaktır. Anahtarı asla istemciye (JavaScript tarafına) göndermeyin, günlük kayıtlarına yazmayın ve yedek dosyalarında düz metin olarak bırakmayın.
Üretimde maliyet, önbellek, hata ve güvenlik yönetimi
| Konu | Risk | Önerilen yaklaşım |
|---|---|---|
| Maliyet | Her sayfa görüntülemesinde yeni istek | Sonucu transient veya nesne önbelleğinde saklayın |
| Gecikme | Uzun yanıt süresi sayfayı bekletir | Arka plan işine taşıyın, kullanıcıya ilerleme gösterin |
| Limit aşımı | Yoğun kullanımda istekler reddedilir | Yeniden deneme ve kuyruk kurun; bkz. rate limit hatası çözümü |
| Hata yönetimi | WP_Error kontrol edilmezse ölümcül hata | Her çağrıda is_wp_error() kontrolü ve yedek içerik |
| Yetki | Yetkisiz kullanıcı pahalı istek tetikler | current_user_can() ve nonce doğrulaması |
| Prompt injection | Kullanıcı metni talimatı ezer | Kullanıcı girdisini veri olarak işaretleyin, çıktıyı doğrulayın |
| Gizlilik | Kişisel veri sağlayıcıya gider | İstek öncesi maskeleme ve aydınlatma metni |
Maliyeti düşürmenin en etkili yolu daha ucuz model seçmek değil, gönderilen bağlamı küçültmek ve tekrar eden istekleri önbelleğe almaktır; yöntemler için token maliyetini azaltma yazısına göz atın. Kendi içeriğinize dayalı yanıt üretmek istiyorsanız RAG sistemi kurulumunu birlikte planlayın.
Yayın öncesi kontrol listesi
- Her AI çağrısı
is_wp_error()kontrolünden geçiyor mu? - Model çıktısı ekrana basılmadan önce kaçış uygulanıyor mu?
- Yetki ve nonce doğrulaması yapılıyor mu?
- Aynı istem için önbellek katmanı kuruldu mu?
- Sağlayıcı anahtarı yalnızca sunucu tarafında mı tutuluyor?
- Sağlayıcı yanıt vermediğinde gösterilecek yedek içerik tanımlı mı?
- Kişisel veri içeren alanlar istek öncesi maskeleniyor mu?
- Aylık kullanım ve maliyet için izleme ve uyarı eşiği var mı?
Sıkça Sorulan Sorular
AI Client API kullanmak için ayrı bir eklenti gerekir mi?
Katmanın kendisi çekirdekle gelir; ancak model sağlayıcısına bağlanmak için ilgili bağlantı yapılandırmasının tamamlanmış olması gerekir. Anahtar tanımlanmamışsa istekler hata döner.
Sağlayıcı değiştirdiğimde eklentimi güncellemem gerekir mi?
Normal koşullarda hayır. Sözleşme aynı kaldığı için değişiklik yönetim tarafındaki bağlantı ayarında yapılır.
İstekleri ön yüzde gerçek zamanlı çalıştırmalı mıyım?
Mümkünse hayır. Ziyaretçi isteğini bekletmemek için üretimi arka plana taşımak, sonucu önbellekten sunmak daha güvenli bir yaklaşımdır.
Yanıtlar neden bazen tutarsız geliyor?
Model çıktıları olasılıksaldır. Tutarlılık isteyen senaryolarda istemde çıktı biçimini netleştirin, mümkünse yapılandırılmış çıktı isteyin ve sonucu doğrulayın.
Verilerim model eğitiminde kullanılır mı?
Bu, seçtiğiniz sağlayıcının koşullarına bağlıdır. Kişisel veri gönderilen senaryolarda sağlayıcı sözleşmesini ve saklama politikalarını incelemek zorunludur.
Kendi sunucumdaki bir modeli kullanabilir miyim?
Sağlayıcı katmanı bunu mümkün kılacak biçimde tasarlanmıştır. Maliyet ve bakım dengesi için Local LLM ve Cloud API karşılaştırması yazısı karar vermenizi kolaylaştırır.
Blok geliştirirken AI çıktısını nasıl bağlarım?
Üretilen değeri özel alanda saklayıp bloklara bağlamak en sürdürülebilir yoldur; yöntem için Block Bindings API yazısına, dinamik etkileşim için Interactivity API rehberine bakabilirsiniz.
Kaynaklar
- Make WordPress Core — sürüm ve geliştirme duyuruları
- WordPress Geliştirici Kaynakları
- WordPress PHP AI Client deposu
- WordPress Geliştirici Kaynakları — Güvenlik (nonce, yetki, kaçış)
Sonuç
WordPress AI Client API, eklentilerin sağlayıcıya kilitlenmeden yapay zeka özelliği geliştirmesini sağlayan ortak bir sözleşme sunar. Üretimde farkı yaratan ise API’nin kendisi değil; hata kontrolü, önbellek, yetki doğrulaması ve maliyet izleme gibi klasik mühendislik disiplinlerinin eksiksiz uygulanmasıdır.
İlgili rehberler:
