Response streaming

Bu modül için tahmini süre: 8 dakika

Genel bakış

Claude ile chat uygulamaları geliştirirken önemli bir kullanıcı deneyimi sorunuyla karşılaşırsınız: yanıtların üretilmesi 10-30 saniye sürebilir ve kullanıcılar loading spinner’ına bakmak zorunda kalır. Çözüm response streaming’dir: Claude metni ürettikçe kullanıcılar metni chunk chunk gelirken görebilir; bu çok daha hızlı ve canlı hissettiren bir deneyim sağlar.

Standart response’ların problemi

Tipik bir chat kurulumunda server’ınız bir user message’ı Claude’a gönderir ve client’a herhangi bir şey göndermeden önce tam response’u bekler. Bu, kullanıcıların hiçbir şey olmuyormuş gibi hissettiği rahatsız edici bir gecikme yaratır.

Streaming nasıl çalışır

Streaming etkinleştirildiğinde Claude, isteğinizi aldığını ve metin üretmeye başladığını belirten bir initial response hemen geri yollar. Sonra her biri genel response’un küçük bir parçasını içeren bir dizi event alırsınız.

Server’ınız bu text chunk’larını geldikçe client uygulamanıza iletebilir; böylece kullanıcılar yanıtın kelime kelime oluşmasını görebilir. Tüm bu event’ler Claude’a yapılan tek bir request’in parçasıdır.

Stream event’lerini anlamak

Streaming’i etkinleştirdiğinizde Claude birkaç tür event döner:

• MessageStart — yeni bir message gönderiliyor
• ContentBlockStart — text, tool use veya başka içerik içeren yeni bir block’un başı
• ContentBlockDelta — gerçek üretilen metnin chunk’ları
• ContentBlockStop — mevcut content block tamamlandı
• MessageDelta — mevcut message tamamlanıyor
• MessageStop — mevcut message hakkında bilginin sonu

ContentBlockDelta event’leri kullanıcılara göstermek isteyeceğiniz gerçek üretilen metni içerir.

Basit streaming uygulaması

Streaming’i etkinleştirmek için messages.create çağrınıza stream=True ekleyin:

messages = []
add_user_message(messages, "Write a 1 sentence description of a fake database")

stream = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    stream=True
)

for event in stream:
    print(event)

Basitleştirilmiş text streaming

Event’leri elle parse etmek yerine SDK’nın yalnızca metin içeriğini çıkaran basitleştirilmiş streaming arayüzünü kullanabilirsiniz:

with client.messages.stream(
    model=model,
    max_tokens=1000,
    messages=messages
) as stream:
    for text in stream.text_stream:
        print(text, end="")

Bu yaklaşım, gerçek text content dışındaki her şeyi otomatik olarak filtreler; bu da kullanıcılara yanıt göstermek için genelde ihtiyacınız olan tam şeydir.

Tam mesajı almak

Tek tek chunk’ları stream etmek kullanıcı deneyimi için harika olsa da çoğu zaman saklamak veya başka işlemler yapmak için tam message’a ihtiyacınız olur. Stream tamamlandıktan sonra bir araya getirilmiş final message’ı alabilirsiniz:

with client.messages.stream(
    model=model,
    max_tokens=1000,
    messages=messages
) as stream:
    for text in stream.text_stream:
        # Send each chunk to your client
        pass
    
    # Get the complete message for database storage
    final_message = stream.get_final_message()

Bu size iki dünyanın da iyisini sunar: kullanıcılar için real-time streaming ve uygulama mantığınız için tam bir message object.

Temel çıkarımlar

• Streaming, uzun yanıtlarda algılanan latency’i ciddi şekilde azaltır
• stream=True parametresi event-bazlı bir akış başlatır; her event farklı bir aşamayı temsil eder
• Gerçek metin parçaları ContentBlockDelta event’lerinde gelir
• SDK’nın client.messages.stream(...) context manager’ı, metin dışındaki event’leri otomatik filtreleyerek koda sadelik getirir
• Stream sona erdikten sonra stream.get_final_message() ile tam mesajı (storage veya logging için) alabilirsiniz