BroadRouter
Başlayın

LLM akışı (streaming): SSE parçaları, delta, usage ve iptal

BroadNet Inference ekibi · 4 dk okuma · Yayımlandı · Güncellendi

Bir LLM API'si chat completion'ı Server-Sent Events olarak akıtır: her data satırı, choices[0].delta alanı metnin sonraki parçasını taşıyan bir JSON parçası içerir. Delta'ları birleştirin, data: [DONE] gelince durun ve token sayılarını boş choices listeli son bir parçada almak için stream_options include_usage ayarlayın. İptal etmek için bağlantıyı kapatın.

Akış (streaming) olmadan bir chat completion, yanıtın tamamı hazır olana kadar hiçbir şey döndürmez. saniyede yaklaşık 100 token hızında 600 token’lık bir yanıt, birkaç saniyelik bir sessizlik demektir. Akışla ise ilk kelimeler model onları yazar yazmaz görünür. Bu yazı kablo üzerinde gerçekte neyin taşındığını, nasıl ayrıştırılacağını, bir akıştan token kullanımının nasıl alınacağını ve bir akışın nasıl temiz şekilde durdurulacağını ele alıyor. BroadNet’e özgü kuralların kısa hali için akış referans rehberine bakın.

Bir SSE akışı kablo üzerinde nasıl görünür?

Server-Sent Events, Content-Type: text/event-stream başlıklı sıradan bir HTTP yanıtıdır. Sunucu bağlantıyı açık tutar ve olaylar yazar. Her olay bir veya daha fazla data: satırından ve ardından gelen boş bir satırdan oluşur. OpenAI uyumlu API’ler her olaya bir JSON parçası koyar ve akışı birebir [DONE] ile bitirir:

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One, "},"finish_reason":null}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"two, three."},"finish_reason":"stop"}],"usage":null}

data: {"id":"c1","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":6,"total_tokens":20}}

data: [DONE]

Yukarıdaki yapı açıklama amaçlıdır ve kısaltılmıştır. Gerçek parçalar model ve created alanlarını da taşır; akıl yürüten modeller usage içinde akıl yürütme token’larını da raporlayabilir.

Bir parçada neler var?

Alan Nerede Anlamı
choices[0].delta.role İlk parça Genellikle assistant. Bir kez gönderilir.
choices[0].delta.content Çoğu parça Metnin sonraki parçası. Boş olabilir.
choices[0].delta.tool_calls Araç çağrıları Fonksiyon adı ve JSON argümanlarının index’e göre birleştirilecek parçaları.
choices[0].finish_reason Son içerik parçası stop, length veya tool_calls. O zamana kadar null.
usage İstenmişse son parça Tüm isteğin toplamları. Diğer her yerde null.

Temel fikir anlık görüntü değil, delta’dır. Her parça yalnızca yeni olanı taşır. Mesajı parçaları sırayla birleştirerek yeniden kurarsınız. Araç çağrıları da aynı şekilde akar: argümanlar, sonuncusu gelene kadar geçerli JSON olmayan dize parçaları halinde gelir; bu yüzden onları ancak finish_reason değeri tool_calls olduktan sonra ayrıştırın.

Bir akıştan token kullanımı nasıl alınır?

Akışsız bir yanıt her zaman usage içerir. Akış ise siz istemedikçe içermez. stream_options: {"include_usage": true} ayarlayın; sunucu [DONE] öncesinde fazladan bir parça gönderir. Bu parça toplamları ve boş bir choices dizisini taşır. BroadNet Inference’ta model raporladığında usage, prompt_tokens_details.cached_tokens ve completion_tokens_details.reasoning_tokens alanlarını da içerebilir; maliyet loglama için ihtiyacınız olan da budur.

Yaygın hata: her parçada chunk.choices[0] okuyan kod, usage parçasında indeks hatası fırlatır. Önce choices alanını kontrol edin.

Python: akış, usage toplama, iptal

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",  # DeepSeek V4.1 Flash, a reasoning model
    messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
    stream=True,
    stream_options={"include_usage": True},
    max_tokens=2000,  # reasoning counts toward this limit
)

def user_pressed_stop():  # replace with your own condition
    return False

parts, usage, finish = [], None, None
try:
    for chunk in stream:
        if chunk.choices:
            choice = chunk.choices[0]
            if choice.delta.content:
                parts.append(choice.delta.content)
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason:
                finish = choice.finish_reason
        if chunk.usage:
            usage = chunk.usage
        if user_pressed_stop():  # your own condition
            break
finally:
    stream.close()  # closes the HTTP connection

text = "".join(parts)

Tek başına break okumayı durdurur, ama soket çöp toplayıcı onu temizleyene kadar açık kalır. Sunucunun bağlantı kopmasını görmesi için soketi açıkça kapatın.

Node: AbortController ile akış

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY });
const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // hard stop after 30 s

const stream = await client.chat.completions.create(
  {
    model: "broadnet/deepseek-v4.1-flash",
    messages: [{ role: "user", content: "Explain SSE in three sentences." }],
    stream: true,
    stream_options: { include_usage: true },
  },
  { signal: controller.signal },
);

let text = "";
for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) text += delta;
  if (chunk.usage) console.log(chunk.usage);
}

openai-node README dosyası signal seçeneğini belgeliyor ve bu seçenek gövde hâlâ okunurken de çalışıyor. Bir web sunucusunda controller.abort() çağrısını istemci isteğinin close olayına bağlayın; böylece sayfadan ayrılan bir kullanıcı üretimi de durdurur. Daha fazla kurulum bilgisi Node SDK rehberinde.

curl: ham olayları görün

curl -N https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Count to five."}]}'

-N, çıktı tamponlamayı kapatır; böylece olaylar geldikçe yazdırılır. İptal etmek için Ctrl+C’ye basın; bu, bağlantıyı kapatır. API istek oluşturucu bu isteği, Python ve Node sürümleriyle birlikte, herhangi bir model ve temel URL (base URL) için üretir.

Bir akış nasıl iptal edilir ve maliyeti ne olur?

SSE’de iptal, yalnızca bağlantıyı kapatmaktır. Bir “dur” mesajı yoktur. Sonrasında ne olacağı sunucuya bağlıdır: düzgün davranan bir sunucu kapanan soketi fark eder ve üretmeyi durdurur. O ana kadar üretilen token’lar gerçek bir işti. BroadNet’in API referansı iptal edilen akışların faturalandırılmasını belgelemiyor; bu yüzden kullandıkça öde modelinde bağlantı kopana kadar üretilen token’ların faturalandırıldığını varsayarak plan yapın ve kullanım kayıtlarınızı kontrol edin. Sabit fiyatlı bir planda iptal edilen bir akış ek maliyet getirmez, ama oturumu ancak sunucu durduğunda serbest bırakır.

Kontrol etmeniz gereken beş akış hatası

  1. Tamponlayan proxy’ler. Nginx ve bazı CDN’ler yanıtları tamponlar; bu yüzden istemci her şeyi bir kerede alır. Akış rotası için proxy tamponlamayı kapatın.
  2. [DONE] kontrolü yapmamak. Kopan bir bağlantı kısa bir yanıt gibi görünür. Hatalar rehberinde anlatıldığı gibi, eksik bir [DONE]’u tamamlanmamış sayın ve X-Request-ID değerini kaydedin.
  3. Akışın ortasında yeniden denemek. SDK’lar gövde gelmeye başladıktan sonra yeniden denemez. Yeniden deneme yeni bir istektir ve kullandıkça öde modelinde yeni bir faturadır.
  4. finish_reason: length değerini yok saymak. DeepSeek V4.1 Flash gibi akıl yürüten modellerde düşünme max_tokens’tan düşülür; bu yüzden küçük bir sınır, akışı görünür bir metin gelmeden durdurabilir. Akıl yürütme token’larının maliyeti.
  5. Satırları yanlış bölmek. SSE’yi elle ayrıştırıyorsanız boş bir satır görene kadar baytları tamponlayın. Bir TCP okuması bir JSON parçasının ortasında bitebilir.

BroadNet Inference’ın yeri

BroadNet Inference standart OpenAI uyumlu akış yapısını kullanır; bu yüzden Python ve Node SDK’ları onu değiştirmeden ayrıştırır. Son parçadaki usage, model raporladığında önbellekli ve akıl yürütme token’larını içerir. Belgeleri, üretimde kullanmadan önce akışın yine de her model için doğrulanması gerektiğini söylüyor; bu yüzden yukarıdaki kodu yayına alacağınız modelin kendisiyle çalıştırın. Asıl önemsediğiniz ilk token’ın ne kadar hızlı geldiğiyse, sırada TTFT ve işlem hacmi yazısı var. WebSocket üzerinden gerçek zamanlı sese ihtiyacınız varsa bu API bunun için tasarlanmadı; chat completions ve dosya transkripsiyonu sunuyor.

Sık sorulan sorular

LLM akışında SSE ile WebSocket arasındaki fark nedir?

SSE, normal bir HTTP yanıtı üzerinden sunucudan istemciye tek yönlüdür. Bir chat completion'ın ihtiyacı da yalnızca budur; bu yüzden OpenAI uyumlu API'ler SSE kullanır. WebSocket'ler çift yönlüdür ve protokol yükseltmesi gerektirir; chat completion için değil, gerçek zamanlı ses için kullanılır.

Akış parçalarımda usage neden null?

Usage yalnızca istediğinizde gönderilir. include_usage değeri true olan stream_options ekleyin. Bu durumda son parça hariç her parçada usage null olur; son parça ise toplamları boş bir choices listesiyle taşır.

Bir akışı iptal edersem ücret ödüyor muyum?

Sağlayıcılar farklıdır ve çoğu bunu belgelemez. Sunucu bağlantının kapandığını fark etmeden önce üretilen token'ların faturalandırıldığını varsayın. X-Request-ID değerini loglayın ve kullanım kayıtlarınızla karşılaştırın.

Bir akışın normal şekilde bittiğini nasıl anlarım?

data: [DONE] aldınız ve son içerik parçasında stop gibi bir finish_reason vardı. length değerindeki bir finish_reason, yanıtı max_tokens'ın kestiği anlamına gelir. [DONE] gelmemesi bağlantının koptuğu anlamına gelir.

Akış modeli hızlandırır mı?

Hayır. Toplam üretim süresi aynıdır. Akış, kullanıcının ilk kelimeleri görene kadar geçen süreyi kısaltır; bir sohbet arayüzünü hızlı hissettiren de budur.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor