Ana içeriğe geç

LLM cevaplarını Server-Sent Events ile tarayıcıya stream etmek

· 7 dakikalık okuma

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. EventSource formatı parse ediyor ve event'leri isimlerine göre dağıtıyor.
  • Yeniden bağlanma otomatik. Bağlantı koparsa EventSource onu yeniden açıyor ve aldığı son event'in id'sini Last-Event-ID header'ı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.

  1. Ü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.
  2. Çı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.
  3. 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.
  4. 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.