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
- 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.
- 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ạiX-Request-ID, như hướng dẫn về lỗi mô tả. - 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.
- 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. - 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.
