LLM cevaplarını Server-Sent Events ile tarayıcıya stream etmek
Bir model cevabını token token yazıyor. API'niz bir şey döndürmek için son token'ı bekliyorsa kullanıcı bütün üretim boyunca bir spinner'a bakıyor; oysa ilk cümle çok daha önce hazırdı.
Stream etmek bunu çözüyor ve ASP.NET Core'da artık birkaç satırlık bir iş. İlginç kısımlar o satırların etrafında: hangi transport'u kullanacağınız, kullanıcı sekmeyi kapattığında ne olduğu, proxy'lerin uzun bir response'a ne yaptığı ve "stream'e kaldığı yerden devam etmek"in sunucunuzdan aslında ne istediği.
Neden stream etmeli?
Stream etmek modeli hızlandırmıyor. Bir cevabı üretmenin toplam süresi iki durumda da aynı. Değişen şey ilk token'a kadar geçen süre, yani kullanıcının bir şeylerin olduğunu gördüğü an. Hemen görünmeye başlayan ve bitmesi biraz süren bir cevap hızlı hissettiriyor; aynı cevap sonunda tek parça gelirse yavaş hissettiriyor, uzun bir cevapta da bozuk.
Cevabın yanlış yöne gittiğini gören kullanıcı onu erkenden durdurabiliyor da; sunucu bunu fark ederse bu, token tasarrufu demek.
Neden WebSocket değil de SSE?
Bir LLM cevabı tek yönde akıyor: sunucu konuşuyor, tarayıcı dinliyor. Server-Sent Events tam olarak bu
şekil için yapılmış. Content-Type: text/event-stream olan normal bir HTTP response; sunucu onu açık tutuyor
ve içine küçük metin event'leri yazıyor.
Bu size birkaç şeyi bedavaya veriyor:
- Düz HTTP. Authentication, CORS, loglama, rate limiting ve mevcut middleware'leriniz olduğu gibi geçerli. Bir proxy'nin ya da kurumsal firewall'un reddedeceği bir protocol upgrade yok.
- Tarayıcıda hazır bir client var.
EventSourceformatı parse ediyor ve event'leri isimlerine göre dağıtıyor. - Yeniden bağlanma otomatik. Bağlantı koparsa
EventSourceonu yeniden açıyor ve aldığı son event'in id'siniLast-Event-IDheader'ında gönderiyor; sunucu oradan devam edebiliyor.
WebSocket'ler ek mekanizmalarını iki tarafın da sürekli mesaj gönderdiği durumlarda hak ediyor: collaborative editing ya da oyunlar gibi. Bir chat arayüzü tek bir soru gönderip tek bir uzun cevap alıyor; soru sıradan bir POST olabilir.
Bir pürüz var ve tasarımı o belirliyor. EventSource yalnızca GET isteği yapabiliyor; body yok, özel
header yok. Soruyu POST edip cevabı aynı response'tan okumak istiyorsanız onu fetch ile okuyup stream'i
kendiniz parse ediyorsunuz ve otomatik yeniden bağlanmadan vazgeçiyorsunuz. Buna devam etme bölümünde
döneceğim.
Endpoint
.NET 10'da SSE hazır geliyor. System.Net.ServerSentEvents, SseItem<T>'yi tanımlıyor: payload'u, event
type'ı, opsiyonel bir id'si ve opsiyonel bir reconnection interval'ı olan bir event. ASP.NET Core 10 da
bunların bir IAsyncEnumerable'ını alıp response'u yazan TypedResults.ServerSentEvents'i ekliyor. Hem
minimal API'lerde hem controller'larda çalışıyor. Öbür tarafta Microsoft.Extensions.AI'daki
IChatClient.GetStreamingResponseAsync bir IAsyncEnumerable<ChatResponseUpdate> döndürüyor. İkisi doğrudan
birbirine oturuyor:
using System.Net.ServerSentEvents;
using System.Runtime.CompilerServices;
using Microsoft.Extensions.AI;
app.MapPost("/chat", (ChatRequest request, IChatClient chat, HttpResponse response,
CancellationToken ct) =>
{
response.Headers["X-Accel-Buffering"] = "no"; // nginx'ten buffer'lamamasını iste
return TypedResults.ServerSentEvents(StreamAnswer(chat, request.Question, ct));
});
static async IAsyncEnumerable<SseItem<string>> StreamAnswer(
IChatClient chat, string question, [EnumeratorCancellation] CancellationToken ct)
{
int seq = 0;
await foreach (ChatResponseUpdate update in
chat.GetStreamingResponseAsync(question, cancellationToken: ct))
{
if (string.IsNullOrEmpty(update.Text))
continue; // usage, tool call'lar ve metin olmayan diğer update'ler
yield return new SseItem<string>(update.Text, "delta") { EventId = (seq++).ToString() };
}
yield return new SseItem<string>("", "done");
}
public sealed record ChatRequest(string Question);
Kablo üzerinde her update şuna benzer bir event'e dönüşüyor:
event: delta
data: world
id: 1
String'ler olduğu gibi yazılıyor; satır sonu içeren bir payload'u formatter birden fazla data: satırına
bölüyor, client da onları yeniden birleştiriyor. Diğer payload tipleri JSON olarak serialize ediliyor.
Result ayrıca Cache-Control: no-cache,no-store set ediyor, ASP.NET Core'daki response buffering'i
kapatıyor ve compression middleware'i ona dokunmasın diye Content-Encoding: identity set ediyor.
Açık bir done event'i göründüğünden daha önemli. EventSource bir response'un bitişini kopan bir bağlantı
gibi görüp yeniden bağlanıyor; client'ın close() çağırması için net bir sinyale ihtiyacı var.
Client gidince iptal et
Minimal API'de bir CancellationToken parametresi HttpContext.RequestAborted'a bağlanıyor; bu da client
bağlantıyı kopardığında tetikleniyor. Onu GetStreamingResponseAsync'e geçirmek, kapanan bir sekmenin model
sağlayıcısına giden isteği de iptal etmesi demek; sunucunuz kimsenin görmeyeceği bir cevabı okumaya devam
etmiyor. Sağlayıcının o anda üretmeyi ve ücretlendirmeyi bırakıp bırakmadığı sağlayıcıya kalmış, ama
iptal etmek gönderebileceğiniz tek sinyal. Result RequestAborted'ı kendi writer'ına da geçiriyor,
[EnumeratorCancellation] da o token'ın iterator'a ulaşmasını sağlıyor.
Hatalar ayrı bir karar istiyor. İlk event yazıldığında status code zaten 200 ve artık değişemez. Yarı yolda
gelen bir sağlayıcı hatası, client'ın gösterebileceği son bir error event'ine dönüşmeli; ağ kopmasından
ayırt edilemeyen yarım bir stream'e değil. C#, catch içeren bir try bloğunun içinde yield return'e
izin vermiyor; o yüzden o catch'in yield'in değil, MoveNextAsync çağrısının etrafında durması gerekiyor.
Heartbeat'ler ve proxy buffering
Sunucunuzla tarayıcı arasındaki iki şey bir stream'i sessizce bozabiliyor.
Birincisi buffering. Response'un tamamını toplayıp öyle ileten bir reverse proxy stream'inizi yeniden bir
spinner'a çeviriyor. nginx proxy'lediği response'ları varsayılan olarak buffer'lıyor; yukarıdaki
endpoint'teki X-Accel-Buffering: no header'ı bunu tek bir response için kapatıyor. Diğer proxy'lerin ve
gateway'lerin kendi ayarları var; event'lerin birer birer geldiğini yalnızca localhost'ta değil, gerçek yol
üzerinden izleyin.
İkincisi idle timeout'lar. Proxy'ler ve load balancer'lar bir süredir sessiz olan bağlantıları kapatıyor.
Token'lar genelde hızlı geliyor ama uzun boşluklar olabiliyor: yavaş bir modelde ilk token'dan önce ya da
bir agent bir tool call'u beklerken. Bilinen çözüm heartbeat: client'ın yok saydığı ama trafik sayılan bir
SSE comment satırı (iki nokta üst üste ile başlayan). TypedResults.ServerSentEvents heartbeat göndermiyor.
Boşluklarınız proxy'nizin timeout'una yaklaşabiliyorsa ya iterator'dan kendi küçük ping event'inizi
gönderin ya da stream'i bunu yapan bir şeyle yazın.
Devam etmek gerçekte ne istiyor?
Last-Event-ID çoğu zaman size devam ettirilebilir stream'ler veriyormuş gibi anlatılıyor. Size client
yarısını veriyor. Tarayıcı son id'yi hatırlayıp geri gönderiyor; gerisi sizin işiniz.
Bunun çalışması için dört şeyin doğru olması gerekiyor.
- Üretim bağlantıdan uzun yaşamalı. Yukarıdaki endpoint'te kopan bir bağlantı model çağrısını iptal ediyor; devam edilecek bir şey kalmıyor. Devam edebilmek için üretim, bir cevap id'siyle arka planda çalışıyor ve SSE endpoint'i yalnızca onun ürettiğini okuyor. Bu, bağlantı kopunca iptal etmekten vazgeçmek demek; terk edilmiş bir üretimin ne kadar süre çalışmaya devam edeceğine karar verin.
- Çıktı saklanmalı. Her token id'siyle birlikte bir log'a gidiyor; böylece yeniden bağlanan bir client'a
Last-Event-ID'sinden sonraki her şey verilebiliyor. Yeniden üretmek devam etmek değil: model farklı bir cevap yazar. - Herhangi bir instance onu sunabilmeli. Bir load balancer'ın arkasında yeniden bağlantı başka bir sunucuya düşebilir; log yalnızca cevabı başlatan sunucunun belleğinde yaşayamaz.
- Eski log'ların süresi dolmalı. Yoksa stream edilmiş her cevap bellekte ya da cache'inizde kalır.
Bu tasarım GET sorununu da çözüyor: soru bir POST ile gidiyor, stream ise EventSource'un kendi başına
açıp yeniden bağlanabildiği bir GET. Bir cevap bitip tamamen teslim edildiğinde, events endpoint'i sonraki
bir yeniden bağlanmaya 204 No Content ile cevap verebilir; bu EventSource'a denemeyi bırakmasını söylüyor.
Devam etmeye ihtiyacınız yoksa onu kurmayın. Başarısız bir cevabı bir retry butonuyla yeniden başlatan bir chat dürüst ve çok daha basit.
OrionStream
Yukarıdaki parçaların birkaçını karşılayan, ASP.NET Core için bir SSE kütüphanesi olan
OrionStream'i geliştiriyorum. Writer'ı X-Accel-Buffering: no dahil SSE header'larını
set ediyor, boşta kalan bir stream'de heartbeat comment'leri gönderiyor ve RequestAborted tetiklenince
duruyor. Hub'ı event'leri topic'lere, her subscriber için sınırlı bir buffer ile publish ediyor, kablo
üzerindeki id'leri atıyor ve topic başına bir replay buffer tutuyor; böylece Last-Event-ID ile yeniden
bağlanan bir client gördüğü son event'ten sonrasıyla devam ediyor. OrionStream.Redis paketi bu replay
backlog'unu Redis'e taşıyor; devam etme instance'lar arasında ve yeniden başlatmalardan sonra da çalışıyor.
Token stream'leri için iki ayar dikkat istiyor. Varsayılan olarak dolu bir subscriber buffer'ı en eski
event'ini atıyor; bu canlı bir dashboard için doğru, bir cümlenin kelimeleri için yanlış. SubscriberCapacity'yi
burst'lerinize göre boyutlandırın ya da başka bir FullBufferPolicy seçin. Bir de in-memory replay buffer'ı
bir topic'in backlog'unu process bitene kadar tutuyor; cevap başına bir topic kullanacaksanız backlog için
time-to-live alan Redis store'u kullanın.
Tek bir cevabı okuyan tek bir tarayıcı için hazır gelen TypedResults.ServerSentEvents yeterli. Aynı
event'ler birçok client'a gittiğinde ya da devam etmenin bir yeniden başlatmayı atlatması gerektiğinde bir
kütüphaneye uzanıyorum.
