BroadRouter

Penjelasan streaming LLM: chunk SSE, delta, usage, dan pembatalan

Oleh tim BroadNet Inference · 4 menit baca · Dipublikasikan · Diperbarui

API LLM melakukan streaming chat completion sebagai Server-Sent Events: setiap baris data berisi chunk JSON yang choices[0].delta-nya membawa potongan teks berikutnya. Gabungkan delta-delta itu, berhenti di data: [DONE], dan set stream_options include_usage untuk mendapat jumlah token di chunk terakhir dengan daftar choices kosong. Untuk membatalkan, tutup koneksinya.

Tanpa streaming, chat completion tidak mengembalikan apa pun sampai seluruh jawaban siap. Balasan 600 token pada kecepatan sekitar 100 token per detik berarti beberapa detik tanpa respons. Dengan streaming, kata-kata pertama muncul begitu model menuliskannya. Artikel ini membahas apa yang sebenarnya dikirim lewat jaringan, cara mem-parse-nya, cara mendapatkan usage token dari stream, dan cara menghentikannya dengan rapi. Untuk aturan khusus BroadNet dalam bentuk ringkas, lihat panduan referensi streaming.

Seperti apa wujud stream SSE di jaringan?

Server-Sent Events adalah respons HTTP biasa dengan Content-Type: text/event-stream. Server menjaga koneksi tetap terbuka dan menuliskan event. Setiap event terdiri dari satu atau lebih baris data: yang diikuti baris kosong. API yang kompatibel dengan OpenAI menaruh satu chunk JSON di setiap event dan diakhiri dengan [DONE] literal:

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]

Bentuk di atas hanya ilustrasi dan sudah dipangkas. Chunk sungguhan juga membawa model dan created, dan model penalaran bisa melaporkan token penalaran di usage.

Apa isi sebuah chunk?

Field Di mana Artinya
choices[0].delta.role Chunk pertama Biasanya assistant. Dikirim sekali.
choices[0].delta.content Sebagian besar chunk Potongan teks berikutnya. Bisa kosong.
choices[0].delta.tool_calls Tool call Potongan nama fungsi dan argumen JSON, digabung berdasarkan index.
choices[0].finish_reason Chunk konten terakhir stop, length, atau tool_calls. null sampai saat itu.
usage Chunk terakhir, jika diminta Total untuk seluruh permintaan. null di tempat lain.

Ide kuncinya adalah delta, bukan snapshot. Setiap chunk hanya berisi bagian yang baru. Anda menyusun ulang pesan dengan menggabungkan potongan-potongan itu secara berurutan. Tool call di-stream dengan cara yang sama: argumennya datang sebagai potongan string yang belum menjadi JSON valid sampai potongan terakhir tiba, jadi parse hanya setelah finish_reason bernilai tool_calls.

Bagaimana mendapatkan usage token dari stream?

Respons tanpa streaming selalu menyertakan usage. Stream tidak, kecuali Anda memintanya. Set stream_options: {"include_usage": true} dan server mengirim satu chunk tambahan sebelum [DONE]. Chunk itu berisi total dan array choices kosong. Di BroadNet Inference, usage juga bisa menyertakan prompt_tokens_details.cached_tokens dan completion_tokens_details.reasoning_tokens jika model melaporkannya, dan itulah yang Anda perlukan untuk pencatatan biaya.

Bug yang umum: kode yang membaca chunk.choices[0] di setiap chunk akan memunculkan index error pada chunk usage. Cek choices terlebih dahulu.

Python: stream, kumpulkan usage, batalkan

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)

break saja hanya berhenti membaca, tetapi socket tetap terbuka sampai dibersihkan garbage collector. Tutup secara eksplisit agar server melihat koneksinya terputus.

Node: stream dengan AbortController

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);
}

README openai-node mendokumentasikan opsi signal, dan opsi ini tetap berfungsi saat body masih dibaca. Di web server, hubungkan controller.abort() ke event close milik request client agar pengguna yang meninggalkan halaman juga menghentikan proses generasi. Setup lebih lengkap ada di panduan Node SDK.

curl: lihat event mentahnya

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 mematikan buffering output sehingga event tercetak begitu tiba. Tekan Ctrl+C untuk membatalkan; itu menutup koneksi. API request builder membuat permintaan ini, beserta versi Python dan Node-nya, untuk model dan Base URL apa pun.

Bagaimana membatalkan stream, dan berapa biayanya?

Pembatalan di SSE hanyalah menutup koneksi. Tidak ada pesan “stop”. Apa yang terjadi selanjutnya tergantung server: server yang berperilaku baik menyadari socket yang tertutup dan berhenti menghasilkan. Token yang dihasilkan sebelum saat itu adalah pekerjaan nyata. Referensi API BroadNet tidak mendokumentasikan penagihan untuk stream yang dibatalkan, jadi rencanakan dengan asumsi token yang dihasilkan sampai koneksi terputus tetap ditagih di bayar sesuai pemakaian, dan periksa catatan usage Anda. Di paket harga tetap, stream yang dibatalkan tidak menambah biaya, tetapi sesi hanya bebas kembali setelah server berhenti.

Lima bug streaming yang perlu dicek

  1. Proxy yang melakukan buffering. Nginx dan beberapa CDN mem-buffer respons, sehingga client menerima semuanya sekaligus. Matikan proxy buffering untuk route streaming.
  2. Tidak mengecek [DONE]. Koneksi yang terputus terlihat seperti jawaban pendek. Anggap [DONE] yang hilang sebagai tidak lengkap dan catat X-Request-ID, seperti dijelaskan di panduan error.
  3. Retry di tengah stream. SDK tidak melakukan retry setelah body mulai datang. Retry adalah permintaan baru dan, di bayar sesuai pemakaian, tagihan baru.
  4. Mengabaikan finish_reason: length. Pada model penalaran seperti DeepSeek V4.1 Flash, proses berpikir dihitung ke dalam max_tokens, jadi batas yang kecil bisa menghentikan stream sebelum ada teks yang terlihat. Berapa biaya token penalaran.
  5. Salah memecah baris. Jika Anda mem-parse SSE secara manual, buffer byte sampai Anda melihat baris kosong. Satu pembacaan TCP bisa berakhir di tengah chunk JSON.

Posisi BroadNet Inference

BroadNet Inference memakai bentuk streaming standar yang kompatibel dengan OpenAI, sehingga SDK Python dan Node mem-parse-nya tanpa perubahan. Usage di chunk terakhir menyertakan token cache dan token penalaran jika model melaporkannya. Dokumentasinya menyebut streaming tetap perlu diverifikasi per model sebelum dipakai di produksi, jadi jalankan kode di atas dengan model persis yang akan Anda rilis. Jika yang paling Anda pedulikan adalah seberapa cepat token pertama tiba, baca TTFT vs throughput berikutnya. Jika Anda butuh suara realtime lewat WebSocket, API ini tidak dibuat untuk itu; yang tersedia adalah chat completions dan transkripsi file.

Pertanyaan umum

Apa bedanya SSE dan WebSocket untuk streaming LLM?

SSE bersifat satu arah, dari server ke client, lewat respons HTTP biasa. Itu saja yang dibutuhkan chat completion, jadi API yang kompatibel dengan OpenAI memakai SSE. WebSocket bersifat dua arah dan butuh protocol upgrade; dipakai untuk suara realtime, bukan untuk chat completion.

Kenapa usage bernilai null di chunk streaming saya?

Usage hanya dikirim jika Anda memintanya. Tambahkan stream_options dengan include_usage bernilai true. Setelah itu, setiap chunk kecuali yang terakhir punya usage null, dan chunk terakhir membawa totalnya dengan daftar choices kosong.

Apakah saya tetap ditagih jika membatalkan stream?

Tiap penyedia berbeda dan banyak yang tidak mendokumentasikannya. Anggap token yang dihasilkan sebelum server menyadari koneksi ditutup tetap ditagih. Catat X-Request-ID di log dan bandingkan dengan catatan usage Anda.

Bagaimana saya tahu stream selesai dengan normal?

Anda menerima data: [DONE] dan chunk konten terakhir punya finish_reason seperti stop. finish_reason length berarti max_tokens memotong jawabannya. Tidak ada [DONE] berarti koneksinya terputus.

Apakah streaming membuat model lebih cepat?

Tidak. Total waktu generasinya sama. Streaming mempersingkat waktu sampai pengguna melihat kata-kata pertama, dan itulah yang membuat antarmuka chat terasa cepat.

Baca sebagai MarkdownTanya ChatGPTTanya ClaudeTanya Perplexity