Yapay Zekâ Entegrasyonu (Claude API)

Bu Proje Nedir?

Bir yapay zekâ API'sini projeye bağlamak, ilk bakışta tek bir curl çağrısıdır. Gerçekte dört soru hemen ardından gelir ve dördü de hafife alınırsa pahalıya patlar:

• Anahtar nerede duracak? JavaScript'e koyarsanız, sayfayı açan herkes onu görür ve sizin hesabınıza istek atabilir.
• Bu ay ne kadar harcadım? Fatura ayın sonunda gelir; o zamana kadar hiçbir fikriniz yoktur.
• Neden ikinci soru birinciden pahalı? Çünkü model durum tutmaz: her istekte sohbetin tamamı yeniden gönderilir ve yeniden ücretlendirilir.
• API hata verdiğinde ne olacak? 429 ve 529 geçicidir, tekrar denenmelidir; 401 kalıcıdır, denemenin anlamı yoktur. İkisini ayırt etmeyen kod ya boşuna uğraşır ya da erken pes eder.

Bu proje dördünü de ele alan bir entegrasyon katmanı kuruyor. Anahtar .env içinde durur ve yalnızca sunucuda kullanılır. Her yanıtın giriş/çıkış jetonu ve hesaplanmış maliyeti kaydedilir. Sohbet geçmişi veritabanındadır. Hata yönetimi geçici ile kalıcıyı ayırır ve geçici olanları üstel geri çekilmeyle yeniden dener.

Modelin "düşünme" özeti de saklanır ve arayüzde istenirse açılır — yanıtın nasıl kurulduğunu görmek, çıktıyı değerlendirmenin en pratik yoludur.

Sağlayıcı sınıfları hiçbir SDK kullanmaz; istek cURL ile atılır, yanıt elle ayrıştırılır.

Ve en önemlisi: denemek için para gerekmiyor. Varsayılan sağlayıcı Google Gemini'dir ve ücretsiz katmanı vardır — aistudio.google.com/apikey adresinden kredi kartı vermeden, birkaç saniyede anahtar alırsınız.

Kimler için uygun?

• Projesine yapay zekâ özelliği ekleyecek, ama maliyeti kontrol altında tutmak isteyenler
• API anahtarını nereye koyacağını soran herkes
• Jeton muhasebesinin nasıl yapıldığını öğrenmek isteyenler
• SDK kurmadan, saf PHP ile bir yapay zekâ API'sine bağlanmak isteyenler
• Sağlayıcıya kilitlenmeden, tek ayarla Gemini/Groq/Claude arasında geçiş yapmak isteyenler
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir panel kalıbı arayanlar

Bu proje, Çılgın Yazılım Kütüphanesi altında yayınlanan açıklamalı, üretime hazır örneklerden biridir.

---

Bir isteğin yolculuğu

 TARAYICI                          SUNUCU (PHP)                    SAĞLAYICI API
 ────────                          ────────────                    ─────────────
 Kullanıcı mesajı yazar
    │  POST /api/chat/send
    │  (CSRF jetonu ile)
    ▼
                          ai_messages'a "user" satırı
                                   │
                                   │  Ai::fromEnv()->send()
                                   │  (gemini · groq · claude …)
                                   │
                                   │  1) SOHBETİN TAMAMINI topla
                                   │     (model durum tutmaz)
                                   │
                                   │  2) x-goog-api-key: <ANAHTAR> ◄─ ANAHTAR
                                   │     (Claude'da x-api-key)        BURADA KALIR
                                   │                                  tarayıcıya
                                   │  3) POST …:generateContent ──────► GİTMEZ
                                   │                                     │
                                   │                                     ▼
                                   │  ◄────────────────────── 200 / 429 / 529 / 4xx
                                   │
                                   │  4) 429 · 529 · 5xx  → GEÇİCİ
                                   │     üstel geri çekilme + jitter
                                   │     en fazla 3 kez yeniden dene
                                   │
                                   │     401 · 400        → KALICI
                                   │     denemeden vazgeç, açıkla
                                   │
                                   │  5) Yanıtı ayrıştır:
                                   │     text · thinking · stop_reason
                                   │     refusal · usage
                                   │
                                   │  6) MALİYET HESAPLA
                                   │     giriş/1M×5$ + çıkış/1M×25$
                                   ▼
                          ai_messages'a "assistant" satırı
                          (metin · düşünme · jetonlar · maliyet)
                                   │
                          ai_conversations toplamları güncellenir
                                   │
    ◄──────────────────────── JSON yanıt
    ▼
 Balon çizilir, jeton satırı basılır

---

Kritik Kararlar

1. API anahtarı asla tarayıcıya gitmez

İnternetteki örneklerin şaşırtıcı bir kısmı anahtarı JavaScript'e koyar ve fetch ile doğrudan API'ye gider. Bu, anahtarı sayfayı açan herkese vermektir: F12 → Sources yeterlidir. Anahtarınızla başkaları istek atar, faturayı siz ödersiniz.

Bu projede istek her zaman sunucudan atılır:

Tarayıcı → (kendi sunucunuz) → Sağlayıcı API

Anahtar .env dosyasındadır, .gitignore içindedir ve PHP dışına hiç çıkmaz. Tarayıcı yalnızca kendi sunucunuzla konuşur — CSRF korumalı, oturum gerektiren bir uç nokta üzerinden.

2. Her mesajın jetonu ve maliyeti kaydedilir

Fatura ayın sonunda gelir. O zamana kadar hangi özelliğin ne kadar harcadığını bilmiyorsanız, maliyeti yönetemezsiniz.

ai_messages: input_tokens · output_tokens · cost_usd
ai_conversations: total_tokens · total_cost

Sayılar API'nin usage alanından gelir — tahmin değil, ölçümdür. Maliyet ise fiyat tablosundan hesaplanır.

Sohbet satırındaki toplam, mesajların toplamına eşittir; iki yerde tutulan bir sayının tutarsız kalması, güvenilmez bir gösterge demektir.

3. Giriş jetonu neden her mesajda artıyor?

Çünkü model durum tutmaz. "Önceki mesajımı hatırla" diye bir şey yoktur; her istekte sohbetin tamamını yeniden gönderirsiniz ve tamamı yeniden ücretlendirilir.

Örnek sohbette bunu somut görürsünüz: 412 → 890 → 1.503. Üçüncü soru, birincinin dört katı giriş jetonu tüketir — soru aynı uzunlukta olsa bile.

Bu, uzun sohbetlerin neden pahalılaştığını açıklar. Pratik sonuç: geçmişi sınırsız göndermeyin. Uzun sohbetlerde eski mesajları özetleyip özeti göndermek yaygın ve etkili bir kalıptır.

4. Geçici hata ile kalıcı hata ayrılır

$retryable = $status === 429 || $status === 529 || $status >= 500;

Ayrım yapmayan kod iki yönden de kaybeder: 401 için üç kez deneyip zaman kaybeder, 429 için hiç denemeyip kullanıcıya gereksiz hata gösterir.

Yeniden denemeler üstel geri çekilme + jitter ile yapılır. Jitter (rastgele sapma) önemlidir: aynı anda sınıra çarpan yüz istemci aynı anda tekrar denerse sınıra yine birlikte çarparlar.

5. stop_reason ve refusal göz ardı edilmez

Bir yanıt "başarılı" dönebilir ama tamamlanmamış olabilir:

• stop_reason = "max_tokens" → yanıt cümlenin ortasında kesildi. Kullanıcıya eksik bir metni tam gibi göstermek yanlıştır.
• refusal dolu → model bilerek yanıtlamadı. Bu bir hata değildir ve "sunucu hatası" diye gösterilmemelidir.

İkisi de ayrı ele alınır ve arayüzde ayrı biçimde gösterilir.

AI_MAX_TOKENS varsayılanı bu yüzden 16.000'dir. Düşük tutmak tasarruf gibi görünür ama kesilen yanıtı baştan sormak zorunda kalırsınız — yani iki kez ödersiniz.

6. "Düşünme" özeti saklanır, ama gizlenerek gösterilir

Modelin muhakemesi, çıktıyı değerlendirmenin en pratik yoludur: yanıt yanlışsa nerede saptığını görürsünüz.

Ama her zaman ekranda durması gerekmez; <details> etiketiyle katlanır. JavaScript gerekmez, erişilebilirlik kendiliğinden doğrudur.

7. Metin pre-wrap ile basılır, nl2br() ile değil

Model yanıtları kod örneği içerir ve kodun girintisi anlamlıdır.

.cy-msg__bubble { white-space: pre-wrap; }

pre-wrap hem satır sonlarını hem girintileri korur, uzun satırları da kırar. Üstüne nl2br() eklemek her satır sonunu iki kez uygular ve paragraf araları iki katına çıkar — kod içeren yanıtlarda ekran dağılır.

Aynı sebeple balonun <div> etiketiyle içeriği arasında boşluk bırakılmaz: pre-wrap, şablonun kendi girintisini de metin sayar ve her balonun ilk satırı sağa kaymış görünürdü.

8. Sohbet silinince mesajlar da gider

CONSTRAINT fk_msg_conv FOREIGN KEY (conversation_id)
    REFERENCES ai_conversations (id) ON DELETE CASCADE

Uygulama kodunda "önce mesajları sil, sonra sohbeti sil" yazılsaydı, o iki adımın arasında bir hata oluştuğunda yetim mesajlar kalırdı. Kısıtı veritabanına koymak bunu imkânsız kılar.

---

Neler Var?

API katmanı

• Messages API'sine cURL ile istek — SDK yok
• Anahtar yalnızca sunucuda
• Üstel geri çekilme + jitter, en fazla 3 deneme
• Geçici (429/529/5xx) ve kalıcı hata ayrımı
• stop_reason ve refusal ayrı ele alınır
• Model ve efor seviyesi .env'den
• Yapılandırılabilir max_tokens

Muhasebe

• Mesaj başına giriş/çıkış jetonu
• Mesaj başına maliyet (fiyat tablosundan)
• Sohbet başına toplam jeton ve maliyet
• Panelde dört sayaç

Sohbet arayüzü

• Sohbet listesi, jeton ve maliyet sütunlu
• Kullanıcı/model balonları, kod girintisi korunur
• Katlanabilir "düşünme özeti" (<details>)
• Mesaj altında jeton ve maliyet satırı
• Sohbet silme (yalnızca kendi sohbeti)
• Anahtar yoksa açıklayıcı uyarı

Ortak altyapı

• Oturum girişi, "beni hatırla", hız sınırı, CSRF
• CSP (script-src 'self'), X-Frame-Options: DENY
• Açık / koyu tema, hesaba kayıtlı
• Mobilde alt navigasyon, yatay kaydırma yok
• Kullanıcılar sayfasında canlı filtre (JS kapalıysa da çalışır)

---

Maliyet nasıl hesaplanıyor?

Fiyatlar milyon jeton başınadır ve her sağlayıcının kendi PRICING tablosundadır. Ücretsiz katmanda gerçek maliyetiniz sıfırdır; rakam yine de gösterilir, çünkü asıl soru "bugün ne ödedim?" değil, "bu uygulama yayına çıkarsa ne öderim?" sorusudur.

GeminiProvider::PRICING — ücretli katman:

ClaudeProvider::PRICING:

public static function estimateCost(string $model, array $usage): float
{
    $rates = self::PRICING[$model] ?? null;
    if ($rates === null) { return 0.0; }

    return ($usage['input_tokens']  / 1000000) * $rates['input']
         + ($usage['output_tokens'] / 1000000) * $rates['output'];
}

Örnek: 412 giriş + 386 çıkış jetonu →

412 / 1.000.000 × 5  = 0,00206
386 / 1.000.000 × 25 = 0,00965
                       ─────────
                       0,01171 $

Demodaki sohbetlerde bu hesabı satır satır doğrulayabilirsiniz.

Bu bir tahmindir, fatura değildir. Fiyatlar koda gömülüdür ve değişebilir; ayrıca ön belleğe yazılan ve ön bellekten okunan jetonlar farklı oranlarla ücretlendirilir — burada yalnızca normal giriş ve çıkış hesaba katılır. Yine de büyüklük mertebesini görmek çok değerlidir: "bu sohbet 0,04 dolar" bilgisi, model veya efor seviyesi değiştirme kararını somut hâle getirir.

Tanımlı olmayan bir model adı için 0.0 döner — yanlış bir rakam göstermektense hiç göstermemek yeğdir.

---

Hata yönetimi

Sağlayıcının send() metodu her durumda anlaşılır bir sonuç döndürür; ham bir istisna arayüze sızmaz.

---

Güvenlik: Neyi, Nasıl Kapattık?

---

Yapılandırma

APP_DEBUG=true          # silerseniz: yerelde açık, canlıda kapalı
APP_URL=
APP_PRETTY_URLS=true

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=cy_ai
DB_USER=root
DB_PASS=

# --- YAPAY ZEKÂ SAĞLAYICISI ---
AI_PROVIDER=gemini
GEMINI_API_KEY=
••••••••
AI_MAX_TOKENS=••••••••

Sağlayıcı seçmek

Uygulama sağlayıcıyı bilmez. App\Core\Ai\Ai::fromEnv() ayara bakıp doğru
sınıfı üretir; denetleyici ve arayüz aynı kalır. Sağlayıcı değiştirmek üç satırdır:

AI_PROVIDER=gemini
GEMINI_API_KEY=…
AI_MODEL=gemini-2.5-flash | var | aistudio.google.com/apikey |
| Groq | AI_PROVIDER=groq
GROQ_API_KEY=…
AI_MODEL=llama-3.3-70b-versatile | var | console.groq.com/keys |
| xAI (Grok) · OpenRouter · Ollama | AI_PROVIDER=openai-compatible
AI_API_KEY=…
AI_BASE_URL=https://api.x.ai/v1 | sağlayıcıya göre | sağlayıcının paneli |
| Anthropic Claude | AI_PROVIDER=claude
ANTHROPIC_API_KEY=…
AI_MODEL=claude-sonnet-5 | yok (ücretli) | console.anthropic.com |

Neden varsayılan ücretsiz bir sağlayıcı? Bu bir öğrenme örneğidir ve önündeki en
pahalı engel kredi kartıydı: kodu okumak isteyen çoğu kişi çalışır hâlini hiç
görmeden ayrılıyordu.

Yeni bir sağlayıcı eklemek HttpProvider sınıfını genişletip dört soruyu
cevaplamaktır: nereye (endpoint), hangi başlıkla (headers), hangi gövdeyle
(payload), gelen yanıt ortak biçime nasıl çevrilir (normalize). Yeniden deneme,
geri çekilme ve cURL ayarları zaten ortak katmandadır.

---

Dosya Yapısı

ai-integration-system/
│
├── index.php                     Ön denetleyici — TEK giriş noktası
├── database.sql                  Şema + 51 kullanıcı + 3 sohbet + 14 mesaj
├── .env.example
│
├── app/
│   ├── Core/
│   │   ├── Ai/                   ★ SAĞLAYICI KATMANI
│   │   │   ├── Ai.php                Fabrika — AI_PROVIDER'a bakar
│   │   │   ├── Provider.php          Arayüz + ortak yanıt sözleşmesi
│   │   │   ├── HttpProvider.php      cURL · yeniden deneme · geri çekilme
│   │   │   ├── GeminiProvider.php    Varsayılan — ücretsiz katman
│   │   │   ├── OpenAiCompatibleProvider.php  Groq · xAI · OpenRouter · Ollama
│   │   │   └── ClaudeProvider.php    Anthropic Messages API
│   │   ├── Auth.php · Session.php · Csrf.php · RateLimiter.php
│   │   ├── Database.php          PDO (EMULATE_PREPARES = false)
│   │   ├── Env.php               .env okuyucu + isLocalHost()
│   │   └── ...
│   │
│   ├── Http/Controllers/
│   │   ├── ChatController.php    Sohbet listesi, detay, silme
│   │   ├── Api/ChatApiController.php   Mesaj gönderme (AJAX)
│   │   └── Auth · Dashboard · User
│   │
│   ├── Repositories/ConversationRepository.php
│   └── Support/helpers.php
│
├── views/
│   ├── chat/index.php            Sohbet listesi + sayaçlar
│   ├── chat/show.php             ★ Balonlar · düşünme özeti · jeton satırı
│   └── ...
│
├── assets/
│   ├── css/  cilginyazilim.css (marka) · admin.css · feature.css
│   └── js/   chat.js · app.js · login.js · users.js
│
├── config/config.php
├── routes/web.php
└── docs/screenshots/

---

Veritabanı Şeması

ai_conversations

ai_messages

---

SSS

API anahtarını JavaScript'e koysam ne olur?

Sayfayı açan herkes onu görür. F12 → Sources yeterlidir; ağ sekmesinde istek başlıklarında da durur.

Sonuç: anahtarınızla başkaları istek atar, faturayı siz ödersiniz. Anahtarı iptal edip yenisini üretmekten başka çareniz kalmaz.

Kural basit: API anahtarı sunucudan çıkmaz. Tarayıcı yalnızca kendi sunucunuzla konuşur.

Maliyeti nasıl düşürürüm?

Dört kaldıraç var, etkileri sırasıyla:

1. Sağlayıcı. En büyük fark burada: Gemini ve Groq'un ücretsiz katmanları vardır. Bir yan projede fatura hiç başlamayabilir.
2. Model. Aynı ailede bile fark büyüktür: gemini-2.5-flash-lite çıkışta gemini-2.5-flash'in altıda biri, claude-haiku-4-5 ise claude-opus-5'in beşte biri fiyattadır. Sınıflandırma, özetleme, biçimlendirme gibi işlerde aradaki kalite farkı çoğu zaman fark edilmez.
3. Gönderdiğiniz geçmiş. Giriş jetonu her mesajda birikir. Uzun sohbetlerde eski mesajları özetleyip özeti gönderin.
4. Efor seviyesi. Claude'da AI_EFFORT düşürmek düşünme jetonlarını azaltır.

Hangisinin işe yaradığını görmek için paneldeki maliyet sayacına bakın — ölçmeden optimize etmeyin.

Yanıt cümlenin ortasında kesiliyor

stop_reason = "max_tokens" demektir: yanıt AI_MAX_TOKENS sınırına çarptı.

.env içindeki değeri yükseltin. Düşük tutmak tasarruf gibi görünür ama kesilen yanıtı baştan sormak zorunda kalırsınız — yani iki kez ödersiniz. Varsayılan 16.000 çoğu iş için yeterlidir.

Çok uzun yanıtlar için akış (streaming) gerekir; bu örnekte akışsız istek kullanılmıştır.

Neden resmi SDK'yı kullanmadınız?

Bu proje Messages API'sinin nasıl çalıştığını göstermek için yazıldı: hangi başlıklar gidiyor, yanıt nasıl ayrışıyor, hangi hata kodu geçici.

Sağlayıcı sınıfları her adımı yorumlarla açıklar; ortak HTTP ve yeniden deneme katmanı HttpProvider içinde bir kez yazılmıştır. Ayrıca Composer bağımlılığı olmaması, paylaşımlı hosting'e atıp çalıştırabilmeniz demektir.

Üretimde SDK kullanmak isterseniz, artık onun ne yaptığını biliyor olacaksınız.

429 alıyorum, ne yapmalıyım?

429 hız sınırıdır ve geçicidir. Uygulama zaten üstel geri çekilmeyle en fazla 3 kez yeniden dener.

Üç deneme de yetmiyorsa istek hızınız hesabınızın sınırının üstünde demektir. Seçenekler: istekleri kuyruğa alıp yavaşça göndermek, daha küçük bir model kullanmak veya hesap limitinizi yükseltmek.

Kuyruk örneği için İş Kuyruğu ve Worker Sistemi'ne bakın.

Sohbet geçmişini sınırsız göndermek zorunda mıyım?

Hayır ve göndermemelisiniz. Model durum tutmadığı için her istekte tüm geçmiş yeniden ücretlendirilir; 50 mesajlık bir sohbette 51. soru çok pahalıya gelir.

Yaygın kalıp: son N mesajı ham gönderin, daha eskileri tek bir özet mesajına indirin. Özeti üretmek de bir API çağrısıdır ama bir kez ödenir.

---

Canlı Ortama Alırken

• [ ] .env içinde APP_DEBUG=false (veya satırı tümüyle silin)
• [ ] API anahtarı yalnızca .env içinde; depoda değil
• [ ] .env dosyasının tarayıcıdan erişilemediğini doğrulayın (403 dönmeli)
• [ ] AI_MODEL ve AI_MAX_TOKENS bütçenize göre ayarlanmış mı?
• [ ] Kullanıcı başına günlük istek sınırı düşünün (bu örnekte yoktur)
• [ ] Maliyet sayaçlarını düzenli izleyin
• [ ] HTTPS zorunlu olsun
• [ ] Veritabanı için root olmayan bir kullanıcı açın
• [ ] Demo hesaplarının parolalarını değiştirin veya hesapları silin

---

Sorun Giderme

---

Yol Haritası

• [ ] Akış (streaming) desteği — yanıt yazılırken göstermek
• [ ] Kullanıcı başına günlük jeton/maliyet kotası
• [ ] Uzun sohbetlerde otomatik özetleme
• [ ] Sistem istemi (system prompt) yönetimi
• [ ] Araç kullanımı (tool use) örneği
• [ ] Ön bellek (prompt caching) jetonlarının ayrı sayılması

---

Katkı

Hata bildirimi ve öneriler için issue açabilirsiniz.

Lisans

MIT — ticari projelerinizde de özgürce kullanabilirsiniz.

---