BroadRouter

Giải thích streaming LLM: chunk SSE, delta, usage và hủy

Đội ngũ BroadNet Inference · 4 phút đọc · Đăng ngày · Cập nhật

API LLM stream một chat completion dưới dạng Server-Sent Events: mỗi dòng data chứa một chunk JSON có choices[0].delta mang mẩu văn bản tiếp theo. Hãy nối các delta, dừng ở data: [DONE], và đặt include_usage trong stream_options để nhận số token ở chunk cuối có danh sách choices rỗng. Để hủy, hãy đóng kết nối.

Không có streaming, một chat completion không trả về gì cho tới khi toàn bộ câu trả lời sẵn sàng. Một phản hồi 600 token ở tốc độ khoảng 100 token mỗi giây nghĩa là vài giây im lặng. Có streaming, những chữ đầu tiên hiện ra ngay khi model viết chúng. Bài này trình bày những gì thực sự đi qua đường truyền, cách parse, cách lấy usage token từ một stream, và cách dừng stream gọn gàng. Để xem tóm tắt các quy tắc riêng của BroadNet, hãy xem hướng dẫn tham khảo về streaming.

Một stream SSE trên đường truyền trông thế nào?

Server-Sent Events là một phản hồi HTTP thông thường với Content-Type: text/event-stream. Server giữ kết nối mở và ghi các event. Mỗi event gồm một hoặc nhiều dòng data: theo sau là một dòng trống. Các API tương thích OpenAI đặt một chunk JSON vào mỗi event và kết thúc bằng chuỗi [DONE]:

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]

Cấu trúc trên chỉ để minh họa và đã được rút gọn. Chunk thật còn mang model và created, và model suy luận có thể báo token suy luận trong usage.

Một chunk chứa những gì?

Trường Ở đâu Ý nghĩa
choices[0].delta.role Chunk đầu tiên Thường là assistant. Chỉ gửi một lần.
choices[0].delta.content Phần lớn các chunk Mẩu văn bản tiếp theo. Có thể rỗng.
choices[0].delta.tool_calls Tool call Các mảnh của tên hàm và tham số JSON, nối lại theo index.
choices[0].finish_reason Chunk nội dung cuối stop, length hoặc tool_calls. Trước đó là null.
usage Chunk cuối, nếu được yêu cầu Tổng số cho toàn bộ request. Ở mọi chỗ khác là null.

Ý then chốt là delta, không phải snapshot. Mỗi chunk chỉ chứa phần mới. Bạn ghép lại tin nhắn bằng cách nối các mảnh theo thứ tự. Tool call được stream theo cùng cách: tham số đến dưới dạng các mảnh chuỗi, không phải JSON hợp lệ cho tới khi mảnh cuối tới, nên chỉ parse chúng sau khi finish_reason là tool_calls.

Lấy usage token từ một stream thế nào?

Phản hồi không streaming luôn có usage. Stream thì không, trừ khi bạn yêu cầu. Hãy đặt stream_options: {"include_usage": true} và server sẽ gửi thêm một chunk trước [DONE]. Chunk đó có tổng số và một mảng choices rỗng. Trên BroadNet Inference, usage còn có thể gồm prompt_tokens_details.cached_tokens và completion_tokens_details.reasoning_tokens khi model có báo, đó là những gì bạn cần cho việc ghi log chi phí.

Lỗi hay gặp: code đọc chunk.choices[0] ở mọi chunk sẽ gặp lỗi index ở chunk usage. Hãy kiểm tra choices trước.

Python: stream, thu usage, hủy

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)

Chỉ break thì dừng đọc, nhưng socket vẫn mở cho tới khi bị garbage collect. Hãy đóng nó một cách tường minh để server thấy kết nối đã ngắt.

Node: stream với 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 của openai-node mô tả tùy chọn signal, và nó hoạt động cả khi body vẫn đang được đọc. Trong một web server, hãy nối controller.abort() với event close của request phía client, để người dùng rời trang thì quá trình sinh cũng dừng. Thiết lập chi tiết có trong hướng dẫn Node SDK.

curl: xem event thô

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 tắt bộ đệm đầu ra để event được in ra ngay khi tới. Nhấn Ctrl+C để hủy; thao tác này đóng kết nối. Công cụ tạo request API sinh ra request này, cùng phiên bản Python và Node, cho bất kỳ model và base URL nào.

Hủy stream thế nào, và tốn bao nhiêu?

Hủy trong SSE chỉ đơn giản là đóng kết nối. Không có tin nhắn “dừng” nào. Chuyện gì xảy ra tiếp theo là tùy server: một server hoạt động đúng sẽ nhận ra socket đã đóng và ngừng sinh. Các token sinh ra trước thời điểm đó là công việc thật. Tài liệu API của BroadNet không mô tả cách tính phí cho stream bị hủy, nên hãy lập kế hoạch như thể các token sinh ra cho tới lúc ngắt kết nối đều bị tính phí khi trả theo mức dùng, và kiểm tra bản ghi usage. Trên gói giá cố định, stream bị hủy không tốn thêm gì, nhưng phiên chỉ được giải phóng khi server dừng.

Năm lỗi streaming cần kiểm tra

  1. Proxy có bộ đệm. Nginx và một số CDN đệm phản hồi, nên client nhận mọi thứ cùng lúc. Hãy tắt proxy buffering cho route streaming.
  2. Không kiểm tra [DONE]. Kết nối bị rớt trông giống một câu trả lời ngắn. Hãy coi việc thiếu [DONE] là chưa hoàn chỉnh và ghi lại X-Request-ID, như hướng dẫn về lỗi mô tả.
  3. Retry giữa stream. SDK không retry khi body đã bắt đầu tới. Một lần retry là một request mới và, khi trả theo mức dùng, là một hóa đơn mới.
  4. Bỏ qua finish_reason: length. Trên model suy luận như DeepSeek V4.1 Flash, phần thinking được tính vào max_tokens, nên giới hạn nhỏ có thể dừng stream trước khi có văn bản nào hiện ra. Xem token suy luận tốn bao nhiêu.
  5. Tách dòng sai. Nếu bạn tự parse SSE, hãy đệm byte cho tới khi gặp dòng trống. Một lần đọc TCP có thể kết thúc giữa một chunk JSON.

BroadNet Inference phù hợp ở đâu?

BroadNet Inference dùng định dạng streaming chuẩn tương thích OpenAI, nên Python và Node SDK parse được mà không cần sửa gì. Usage trong chunk cuối gồm token cache và token suy luận khi model có báo. Tài liệu cho biết vẫn nên kiểm tra streaming theo từng model trước khi dùng cho production, nên hãy chạy code ở trên với đúng model bạn triển khai. Nếu bạn quan tâm chủ yếu tới việc token đầu tiên đến nhanh thế nào, hãy đọc tiếp TTFT và throughput. Nếu bạn cần giọng nói thời gian thực qua WebSocket, API này không được xây dựng cho việc đó; nó cung cấp chat completions và chép lời file.

Câu hỏi thường gặp

SSE và WebSocket khác nhau thế nào khi streaming LLM?

SSE là một chiều, từ server tới client, trên một phản hồi HTTP bình thường. Chat completion chỉ cần vậy, nên các API tương thích OpenAI dùng SSE. WebSocket là hai chiều và cần nâng cấp giao thức; nó được dùng cho giọng nói thời gian thực, không phải chat completion.

Vì sao usage là null trong các chunk streaming của tôi?

Usage chỉ được gửi khi bạn yêu cầu. Hãy thêm stream_options với include_usage là true. Khi đó mọi chunk trừ chunk cuối có usage null, và chunk cuối mang tổng số kèm danh sách choices rỗng.

Hủy stream có bị tính phí không?

Mỗi nhà cung cấp một khác và nhiều nơi không ghi rõ. Hãy giả định các token sinh ra trước khi server nhận ra kết nối đã đóng sẽ bị tính phí. Hãy ghi log X-Request-ID và đối chiếu với bản ghi usage của bạn.

Làm sao biết stream kết thúc bình thường?

Bạn đã nhận data: [DONE] và chunk nội dung cuối có finish_reason như stop. finish_reason là length nghĩa là max_tokens đã cắt câu trả lời. Không có [DONE] nghĩa là kết nối bị rớt.

Streaming có làm model nhanh hơn không?

Không. Tổng thời gian sinh vẫn vậy. Streaming rút ngắn thời gian tới khi người dùng thấy những chữ đầu tiên, và đó là điều khiến giao diện chat có cảm giác nhanh.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity