Streaming API ile Gerçek Zamanlı Yapay Zeka Yanıtı Alma

Son güncelleme

Streaming API, model yanıtını tamamı bitmeden parça parça göstermeyi sağlar. Kullanıcı, sağlayıcı ilk parçayı ürettiği anda yanıtı okumaya başlayabilir; bu süre ağ, model ve istem uzunluğuna göre değişir. Akış tek başına toplam süreyi veya maliyeti düşürmez. Aynı istek aynı tokenları üretirse ücret genellikle aynı kalır; kullanıcı erken iptal ederse tüketim farklılaşabilir. Bu rehberde akışın sunucu ve tarayıcı tarafında nasıl kurulacağını, ters proxy ve PHP tamponlarının neden akışı bozduğunu, hata ve iptal senaryolarını ve canlıya çıkmadan önce neleri ölçmeniz gerektiğini adım adım ele alıyoruz.

Streaming ne zaman gerçekten işe yarar?

Akışın faydası, kullanıcının yanıtı okurken beklemesidir. Sohbet arayüzleri, uzun metin üreten yazma asistanları ve kod açıklaması gibi çıktının satır satır okunabildiği senaryolarda algılanan hız ciddi biçimde artar. Kullanıcı 8–10 saniyelik bir boş ekran yerine ilk saniyede yazının akmaya başladığını görür ve uygulamanın “takıldığını” düşünmez.

Buna karşılık bazı işlerde streaming ek karmaşıklıktan başka bir şey getirmez:

  • Yapılandırılmış çıktı bekleyen işlemler: Model JSON döndürüyorsa ve siz bu JSON’u ancak tamamlandığında doğrulayıp veritabanına yazacaksanız, parçaları ekranda göstermenin anlamı yoktur.
  • Arka plan görevleri: Kuyrukta çalışan özetleme, sınıflandırma veya toplu içerik işleme işlerinde ekranda bekleyen bir kullanıcı yoktur.
  • Kısa yanıtlar: Yanıt zaten bir iki saniyede geliyorsa akış altyapısının bakım maliyeti kazancı aşar.

Karar verirken iki metriği ayırın: ilk token süresi (time to first token, TTFT) ve toplam yanıt süresi. Streaming yalnızca ilkini kullanıcıya hissettirir; ikincisi model, prompt uzunluğu ve çıktı uzunluğuna bağlı kalır.

Akışın uçtan uca yolculuğu

Bir streaming isteğinde veri tek bir HTTP yanıtı içinde, bağlantı açık kalarak küçük olaylar halinde akar. Tipik bir web uygulamasında bu yolculuk dört halkadan oluşur: model sağlayıcısı, sizin sunucunuz, aradaki proxy/CDN katmanı ve tarayıcı. Halkalardan herhangi biri veriyi “biriktirip sonra gönderirse” kullanıcı akış yerine tek seferde gelen bir metin görür.

Streaming yanıt uçtan uca nasıl akar?
Herhangi bir halka tamponlarsa kullanıcı akış yerine tek parça metin görür.

Sağlayıcıların büyük kısmı akışı Server-Sent Events (SSE) biçiminde gönderir. SSE, text/event-stream içerik türüyle satır tabanlı bir protokoldür: her olay event: ve data: satırlarından oluşur, olaylar boş bir satırla ayrılır. Örneğin Anthropic Messages API’de metin parçaları content_block_delta olaylarıyla gelir; akışın başında message_start, sonunda kullanım bilgisini taşıyan message_delta ve message_stop olayları bulunur. OpenAI Responses API’de metin parçaları response.output_text.delta türündeki olaylarla, tamamlanma ise response.completed ile bildirilir. Gemini tarafında akış için ayrı bir streamGenerateContent yöntemi vardır ve alt=sse parametresiyle SSE biçiminde yanıt alınır.

Olay adları sağlayıcıya ve API sürümüne göre değiştiği için kodunuzu tek bir sağlayıcının olay listesine sıkı sıkıya bağlamak yerine, kendi uygulamanızda küçük bir ara katman (adaptör) tanımlamak uzun vadede işinizi kolaylaştırır: adaptör sağlayıcı olaylarını “metin parçası”, “tamamlandı”, “hata” ve “kullanım” gibi sizin belirlediğiniz birkaç olaya çevirir.

Sunucu tarafında akışı kurmak

API anahtarını hiçbir zaman tarayıcıya göndermeyin. Doğru mimaride tarayıcı sizin sunucunuza bağlanır, sunucunuz sağlayıcıya bağlanır ve gelen olayları süzerek istemciye aktarır. Böylece yetki kontrolü, oran sınırı, kayıt tutma ve maliyet takibi sizin elinizde kalır.

PHP ile basit bir SSE köprüsü

Aşağıdaki örnek, cURL ile sağlayıcıya akış isteği gönderen ve gelen her parçayı tarayıcıya ileten minimal bir yapıyı gösterir. Örnek, Anthropic Messages API başlıklarını kullanır; AI_ENDPOINT ve AI_MODEL değerlerini güncel belgelerden alın. $soru değişkeni, kimliği doğrulanmış isteğin gövdesinden uzunluk sınırı uygulanarak okunmalıdır. Bu kısa örnek, üretim ortamına tek başına kopyalanacak eksiksiz bir uç nokta değildir.

<?php
// stream.php — oturum ve yetki kontrolünü bu satırdan önce yapın
header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');
header('X-Accel-Buffering: no'); // Nginx tamponlamasını bu yanıt için kapatır

while (ob_get_level() > 0) { ob_end_flush(); } // PHP çıktı tamponlarını boşalt
set_time_limit(120);

$payload = json_encode([
    'model'      => getenv('AI_MODEL'),
    'max_tokens' => 1024,
    'stream'     => true,
    'messages'   => [['role' => 'user', 'content' => $soru]],
]);

$ch = curl_init(getenv('AI_ENDPOINT'));
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'x-api-key: ' . getenv('AI_KEY'), 'anthropic-version: 2023-06-01'],
    CURLOPT_WRITEFUNCTION  => function ($ch, $chunk) {
        echo $chunk;           // olayları olduğu gibi ilet (veya burada süzün)
        flush();
        return connection_aborted() ? 0 : strlen($chunk); // istemci koptuysa isteği kes
    },
    CURLOPT_TIMEOUT        => 120,
]);
curl_exec($ch);
curl_close($ch);

Üretimde önce sağlayıcının HTTP durumunu ve içerik türünü kontrol edin: 401 veya 429 hata gövdesini başarılı bir SSE yanıtı gibi kullanıcıya aktarmayın. Ağ hatası ile tamamlanma olayını ayrı kaydedin. Bu örnekte üç kritik nokta var. Birincisi, X-Accel-Buffering: no başlığı Nginx’in bu yanıtı tamponlamasını engeller. İkincisi, PHP’nin kendi çıktı tamponları kapatılır ve her parçadan sonra flush() çağrılır. Üçüncüsü, connection_aborted() kontrolü kullanıcı sekmeyi kapattığında sağlayıcıya giden isteği keserek boşa token harcanmasını önler. Ancak connection_aborted() PHP’nin bağlantı kopmasını ancak bir şey yazmaya çalıştığında fark ettiğini unutmayın; uzun sessiz aralıklarda gecikmeli algılanabilir.

Olayları ham iletmek mi, dönüştürmek mi?

Sağlayıcı olaylarını olduğu gibi tarayıcıya iletmek hızlı bir başlangıçtır ama üç dezavantajı vardır: istemci kodu sağlayıcıya bağımlı olur, olayların içinde istemcinin görmemesi gereken meta veriler bulunabilir ve sağlayıcı değiştirdiğinizde ön yüzü de yeniden yazmanız gerekir. Canlı sistemlerde gelen parçayı sunucuda ayrıştırıp yalnızca {"tip":"metin","deger":"..."} gibi sade bir biçimde iletmek daha güvenlidir.

Ayrıştırırken en sık yapılan hata, her ağ parçasının tam bir olay olduğunu varsaymaktır. TCP üzerinden gelen bir parça bir olayın yarısını ya da birden fazla olayı içerebilir. Doğru yöntem, gelen veriyi bir tampona eklemek, satır sonlarını (CRLF dâhil) doğru ayırmak, boş satırla tamamlanan olayları işlemek ve kalan yarım parçayı sonraki okumaya bırakmaktır. Bir SSE olayında birden çok data: satırı bulunabilir; bunlar yeni satırla birleştirilir. : ping gibi yorum satırları veri olarak gösterilmez.

Laravel ve Node.js tarafında aynı mantık

Laravel kullanıyorsanız response()->stream() veya StreamedResponse ile aynı yapıyı kurabilirsiniz. Callback içinde sağlayıcıdan gelen parçayı yazdıktan sonra ob_flush() ve flush() çağırmanız, başlıkları ise yanıt nesnesine eklemeniz gerekir. Laravel’in HTTP istemcisinde akış okumak için isteği withOptions(['stream' => true]) ile gönderip dönen gövdeyi parça parça okuyabilirsiniz. Oturum kullanan rotalarda uzun akış süresince oturum dosyasının kilitli kalması aynı kullanıcının diğer isteklerini bekletebilir; akış başlamadan önce gerekli oturum verisini okuyup oturumu kapatmak bu sorunu önler.

Node.js tarafında resmi SDK’ların çoğu akışı async iterator olarak sunar; for await döngüsüyle gelen olayları okuyup Express yanıtına res.write() ile yazabilirsiniz. Node’un olay döngüsü uzun açık bağlantıları PHP-FPM’e göre daha verimli taşıdığı için yoğun sohbet trafiği olan projelerde akış katmanını ayrı bir Node servisine taşımak sık tercih edilen bir mimaridir. Hangi dili seçerseniz seçin, değişmeyen kural şudur: sağlayıcıdan gelen veriyi beklemeden ilet, istemci koptuğunda sağlayıcı isteğini kapat ve son durumu kaydet.

Tarayıcı tarafında akışı okumak

Tarayıcıda iki yaygın yöntem vardır. EventSource API’si SSE için tasarlanmıştır, bağlantı koptuğunda otomatik yeniden bağlanır; fakat yalnızca GET isteği gönderebilir ve özel başlık ekleyemezsiniz. Kullanıcının uzun bir mesajını POST gövdesiyle göndermeniz gerekiyorsa fetch ile dönen yanıtın body akışını okumak daha esnektir:

const yanit = await fetch('/stream.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ soru }),
  signal: iptalDenetleyici.signal, // kullanıcı "Durdur"a basarsa iptal
});
if (!yanit.ok || !yanit.body) throw new Error('Akış başlatılamadı');
const okuyucu = yanit.body.getReader();
const cozucu = new TextDecoder();
let tampon = '';
while (true) {
  const { value, done } = await okuyucu.read();
  if (done) break;
  tampon += cozucu.decode(value, { stream: true });
  const olaylar = tampon.split('\n\n');
  tampon = olaylar.pop(); // yarım kalan olayı sakla
  for (const olay of olaylar) isleOlay(olay);
}

Bu kod, temel parçalı okuma mantığını gösterir. Üretimde isleOlay işlevi olay adını, çok satırlı veriyi, hata olayını ve tamamlanma işaretini ayrı ele almalıdır; farklı satır sonu biçimlerini de desteklemelidir. TextDecoderın stream: true seçeneği, çok baytlı bir Türkçe karakterin iki ağ parçasına bölündüğü durumda karakterin bozulmasını önler.

AbortController ile oluşturduğunuz signal, kullanıcıya bir “Durdur” düğmesi sunmanızı sağlar. Bu düğme yalnızca ekrandaki akışı durdurmamalı; sunucuda sağlayıcıya giden isteğin de kesildiğinden emin olun, aksi halde kullanıcı görmediği tokenların ücretini ödersiniz.

Ekrana yazarken her parçada tüm metni yeniden işlemek (örneğin Markdown’ı baştan HTML’e çevirmek) uzun yanıtlarda arayüzü yavaşlatır. Parçaları biriktirip requestAnimationFrame ile kare başına bir kez güncellemek ve model çıktısını HTML olarak eklemeden önce mutlaka temizlemek (sanitize) gerekir.

Ters proxy, CDN ve hosting tamponlaması

“Yerelde akıyor ama canlıda tek seferde geliyor” şikâyetinin neredeyse her zaman sebebi aradaki bir tampondur. Kontrol etmeniz gereken katmanlar şunlardır:

  • Nginx: proxy_buffering varsayılan olarak açıktır. Yanıt başlığında X-Accel-Buffering: no göndermek ya da ilgili location bloğunda proxy_buffering off; tanımlamak gerekir. PHP-FPM kullanıyorsanız fastcgi_buffering ayarını da gözden geçirin.
  • PHP: output_buffering ve zlib.output_compression ayarları akışı biriktirebilir. Sıkıştırma açıksa sunucu parçaları sıkıştırma bloğu dolana kadar bekletebilir.
  • Apache: mod_deflate gibi sıkıştırma modülleri text/event-stream yanıtlarını da sıkıştırmaya çalışabilir; bu içerik türünü sıkıştırma dışında bırakın.
  • CDN / proxy servisleri: Çoğu CDN SSE yanıtlarını iletebilir ancak zaman aşımı ve tamponlama davranışları farklıdır. Uzun yanıtlarda bağlantının kesilmemesi için sunucunuz düzenli aralıklarla küçük bir yorum satırı (: ping) gönderebilir.
  • Paylaşımlı hosting: Bazı paylaşımlı hosting ortamlarında PHP süreleri ve tamponlama ayarları kullanıcı tarafından değiştirilemez. Bu durumda akış ya hiç çalışmaz ya da tutarsız çalışır; küçük bir VPS veya ayrı bir Node.js servisi daha öngörülebilir sonuç verir.

Hangi katmanın tamponladığını bulmak için en hızlı yöntem, aynı isteği önce sunucunun içinden doğrudan (curl -N http://127.0.0.1/...), sonra alan adı üzerinden denemektir. -N parametresi cURL’ün kendi tamponlamasını kapatır; parçalar terminalde akıyorsa sorun daha dış katmandadır.

Hata, iptal ve yeniden deneme senaryoları

Normal bir istekte yanıt ya başarılıdır ya da hatalıdır. Streaming’de üçüncü bir durum vardır: yanıt yarıda kesilir. Sağlayıcı akış ortasında bir hata olayı gönderebilir, ağ kopabilir veya kullanıcı sekmeyi kapatabilir. Bu durumları tasarlamazsanız veritabanına yarım yanıtlar “tamamlanmış” olarak kaydedilir.

Akış hata senaryoları ve doğru tepki
Yarım kalan yanıtı asla 'tamamlandı' olarak kaydetmeyin.

Dikkat etmeniz gereken başlıca senaryolar:

  • Bağlantı hiç kurulamadı: 401, 429 veya 5xx gibi hatalar akış başlamadan döner. Bunları normal API hataları gibi ele alın; 429 durumunda kullanıcıya bekleme süresi gösterin ve geri çekilmeli (backoff) yeniden deneme uygulayın.
  • Akış ortasında hata: Bazı sağlayıcılar HTTP 200 ile başlayan bir akışın içinde hata olayı gönderebilir. Bu olayı yakalayıp arayüzde “yanıt tamamlanamadı” uyarısı gösterin ve kısmi metni ayrı bir durumla kaydedin.
  • Sonlandırma olayı gelmedi: Akış sessizce kapandıysa ama tamamlanma olayını (message_stop, response.completed vb.) almadıysanız yanıtı eksik kabul edin.
  • Kullanıcı iptali: İptali bir hata olarak değil, ayrı bir son durum olarak kaydedin. Raporlarda “iptal oranı” yüksekse yanıtlar gereğinden uzun olabilir.
  • Yeniden deneme: Akış yarıda kesildiğinde aynı isteği otomatik tekrarlamak kullanıcıya iki kez başlayan bir metin gösterebilir ve maliyeti ikiye katlar. Otomatik tekrar yerine kullanıcıya “Yeniden oluştur” seçeneği sunmak çoğu zaman daha iyidir.

Akışı test ederken örnek bir hata akışı

Deneme ortamında üç ayrı test yapın. İlkinde sağlayıcıdan normal bir yanıt alın ve ilk olayın, metin parçalarının ve tamamlanma olayının sırasını kaydedin. İkincisinde bağlantıyı yanıt ortasında kesin; ekranda kısmi metin kalabilir fakat kayıt durumu “tamamlandı” olmamalıdır. Üçüncüsünde sağlayıcıdan 429 veya 5xx döndürün ve kullanıcıya ham hata JSON’u yerine anlaşılır bir uyarı gösterin. Bu testler yalnızca geliştirme sunucusunda değil, CDN ve alan adı üzerinden de yapılmalıdır.

Aynı anda birden fazla sekmede uzun akış açarak kaynak tüketimini gözlemleyin. Klasik HTTP/1.1 bağlantılarında tarayıcının alan adı başına bağlantı sınırı, başka isteklerin beklemesine yol açabilir; HTTP/2 bu durumu farklı yönetir. Akış açıkken yeni sohbet mesajı gönderilmesi, sayfanın kapanması ve kullanıcının “Durdur” düğmesine tekrar basması için beklenen davranışı önceden tanımlayın. Bu senaryolar kayıtlarınızda farklı son durumlara karşılık gelmelidir.

Ölçüm ve maliyet takibi

Streaming’e geçtikten sonra ölçmeniz gereken metrikler değişir. Yalnızca toplam süreyi kaydederseniz akışın faydasını göremezsiniz. Her istek için en az şu alanları kaydetmek iyi bir başlangıçtır:

  • İstek başlangıç zamanı, ilk metin parçasının geldiği an ve son olayın geldiği an
  • Son durum: tamamlandı, iptal edildi, hata, zaman aşımı
  • Girdi ve çıktı token sayıları (sağlayıcının akış sonunda gönderdiği kullanım bilgisinden)
  • Kullanılan model ve istemci türü (web, mobil)

Token kullanım bilgisi çoğu sağlayıcıda akışın sonunda gelir. İstemci erken koptuğunda bu bilgiyi alamayabilirsiniz; bu yüzden maliyet raporlarınızı yalnızca kendi kayıtlarınıza değil, sağlayıcının kullanım panelindeki verilere karşı da düzenli olarak kontrol edin. Maliyet tarafını detaylı incelemek isterseniz AI API token maliyetini azaltma rehberimize göz atabilirsiniz.

Güvenlik ve gizlilik kontrolleri

Akış altyapısı, fark edilmeden hassas veri sızdıran bir kanala dönüşebilir. Hata ayıklama sırasında açılan ham olay günlükleri, kullanıcı mesajlarını ve model yanıtlarını düz metin olarak saklayabilir. Canlıda bu günlükleri ya kapatın ya da kişisel verileri maskeleyin.

Streaming uç noktanız da diğer API uç noktalarınız gibi kimlik doğrulama, oran sınırı ve istek boyutu sınırı gerektirir. Açık kalan uzun bağlantılar sunucu kaynaklarını tükettiği için kullanıcı başına eşzamanlı akış sayısını sınırlamak iyi bir uygulamadır. Model çıktısını ekrana basmadan önce HTML kaçışı yapın; aksi halde prompt injection yoluyla üretilen bir script etiketi arayüzünüzde çalışabilir. Bu riskin ayrıntıları için prompt injection rehberine bakabilirsiniz.

Canlıya çıkmadan önce kontrol listesi

  • Akış alan adı üzerinden, CDN ve proxy aktifken test edildi; parçalar gerçekten ayrı ayrı geliyor.
  • İstemci koptuğunda sağlayıcı isteği de kesiliyor.
  • Akış ortası hata, sonlandırma olayı gelmemesi ve kullanıcı iptali ayrı durumlar olarak kaydediliyor.
  • İlk token süresi ve toplam süre ayrı ölçülüyor.
  • API anahtarı yalnızca sunucuda; tarayıcıya hiçbir yanıt içinde dönmüyor.
  • Model çıktısı ekrana eklenmeden önce temizleniyor.
  • Kullanıcı başına eşzamanlı akış ve istek sayısı sınırlı.

Sıkça Sorulan Sorular

Streaming kullanmak API maliyetini düşürür mü?

Hayır. Ücretlendirme üretilen ve gönderilen token sayısına göre yapılır. Streaming yalnızca yanıtın kullanıcıya ulaşma biçimini değiştirir. Kullanıcı yanıtı erken durdurduğunda ve siz sağlayıcı isteğini de kestiğinizde kısmi bir tasarruf olabilir.

EventSource mu, fetch ile akış okuma mı kullanmalıyım?

İsteği GET ile gönderebiliyor ve özel başlığa ihtiyaç duymuyorsanız EventSource basit ve otomatik yeniden bağlanan bir çözümdür. Uzun mesajları POST gövdesiyle göndermeniz veya yetki başlığı eklemeniz gerekiyorsa fetch ile ReadableStream okumak daha uygundur.

Yerelde çalışan akış canlıda neden tek parça geliyor?

En sık neden Nginx proxy_buffering, PHP output_buffering veya sıkıştırma modülleridir. Yanıta X-Accel-Buffering: no başlığı ekleyip PHP tamponlarını boşaltarak ve text/event-stream türünü sıkıştırma dışında bırakarak test edin.

Yarım kalan yanıtı kaydetmeli miyim?

Kaydedebilirsiniz ama “tamamlandı” olarak değil. Ayrı bir durum alanı (ör. yarim, iptal) kullanırsanız hem kullanıcıya doğru bilgi verirsiniz hem de hata oranlarını raporlayabilirsiniz.

İlgili Rehberler

Kaynaklar ve İleri Okuma

İlgili Yazılar

Yorum yapın