API ile Yapay Zekâ Uygulaması Geliştirme: Başlangıç Rehberi

İlk çağrı: İsteğin anatomisi

Her büyük sağlayıcının API'si benzer anatomidedir: model adı, mesaj listesi (sistem + kullanıcı + asistan rolleri), sıcaklık, max token. İlk çağrı: sağlayıcıdan anahtar alın, basit bir POST isteği gönderin (curl veya SDK), yanıttaki token kullanım alanını inceleyin — maliyet yönetimi buradan başlar.

İpucu: SDK kullanın (Python/JS resmî kütüphaneler); ham HTTP deneyimi isterseniz curl ile bir kez yapıp SDK'ya geçin. Anahtar güvenliği: anahtar asla istemci tarafına (tarayıcı/mobil) konmaz; mutlaka kendi backend'iniz üzerinden çağrı yapılır.

Sistem istemi tasarımı

Sistem istemi, uygulamanın kişiliğidir: rol, ton, format kuralları, kapsam sınırları ("bu ürünün dışına çıkma"), güvenlik kuralları. Uygulama istemini kodda sabit tutun; kullanıcı verisini ayrı mesaj olarak geçirin — bu ayırım, hem kalite hem güvenlik (istem enjeksiyonu savunması) için temeldir.

Uzun sistem istemleri için bağlam önbelleği kullanın: tekrar eden istem parçası önbelleğe girer, maliyet belirgin düşer. İsteminizi sürümleyin (v1, v2...) ve değişiklikleri değerlendirme setiyle test edin — istem, kod kadar hassas bir varlıktır.

Streaming ve kullanıcı deneyimi

Token-token yanıt akışı (streaming), sohbet hissini kökten değiştirir: kullanıcı ilk kelimeyi 1 saniyede görür, tamamını 8 saniyede. Uygulama tarafı: SSE/WebSocket ile aktarım, kesilen akışın yeniden bağlanması, "durdur" butonu.

UX kuralları: Uzun görevlerde ilerleme göstergesi (aşama adı: "belgeler taranıyor"), hata mesajlarını kullanıcı dilinde (teknik hata kodu değil "bir sorun oldu, tekrar deneyin"), kritik yanıtlarda kaynak gösterme (RAG cevaplarında parça kaynağı).

Maliyet yönetimi

Dört teknik: (1) Doğru model katmanı — rutin iş küçük modele, zor iş büyük modele; yönlendirme mantığı basit classifier bile olabilir. (2) Token disiplini — sistem istemini önbellekleyin, gereksiz geçmişi budayın, çıktı uzunluğunu sınırlayın. (3) Önbellekleme — aynı soruya aynı cevabı vermemek için anlamsal önbellek (benzer sorulara önbellekteki cevabı sunma). (4) İzleme — kullanım panosu, kullanıcı/başvuru bazında maliyet dağılımı, anormal artış alarmı.

İpucu: Ücretsiz katman sunuyorsanız IP bazlı limit + dakikalık istek limiti koyun; hesabınızın başkasının demosu tarafından tüketilmesi en klasik başlangıç kazasıdır.

Hata işleme

Beklenen hatalar: hız limiti (429 — exponential backoff ile yeniden dene), servis yoğunluğu (5xx — yeniden deneme + yedek model), token limiti aşımı (bağlamı budama), geçersiz içerik filtresi durumu (kullanıcıya kibar açıklama).

Yedek model stratejisi: Birincil model hata verirse ikincil sağlayıcıya düşme (fallback) — kurumsal uygulamalar için önemli dayanıklılık katmanı. Ve idempotency: Tekrar denemede aynı işin iki kez yapılmasın (ödeme, bildirim gibi yan etkili işlerde).

Güvenlik kontrol listesi

• Anahtar sadece backend'de, çevresel değişkende; depoda değil.
• Kullanıcı girdisi sistem istemine karışmaz; ayraçlı ve rol ayrımlı geçer.
• Kullanıcı başına hız limiti + toplam bütçe sınırı.
• Çıktı filtreleme: hassas içerik uyarıları ve içerik politikası uyumu.
• Log: hangi istek, hangi model, ne kadar token — maliyet denetimi için.
• Gizlilik: kullanıcının paylaştığı verinin saklama politikası açık ve uygulanır.