流式響應
流式傳輸會在生成過程中逐步返回部分結果，讓你的應用可以增量地顯示文本，而無需等待完整響應。这能带来更好的用户體驗，尤其是對於较長的響應。
流式傳輸的工作原理
当你設定 stream: true 時，API 會返回一個 Server-Sent Events（SSE） 流。每個事件都包含生成過程中的一小段響應。
使用 cURL
curl https://api.linkastra.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-pro",
"messages": [{"role": "user", "content": "Write a haiku about coding"}],
"stream": true
}'響應是一連串的 data: 行：
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1719000000,"model":"deepseek/deepseek-v4-pro","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1719000000,"model":"deepseek/deepseek-v4-pro","choices":[{"index":0,"delta":{"content":"Silent"},"finish_reason":null}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1719000000,"model":"deepseek/deepseek-v4-pro","choices":[{"index":0,"delta":{"content":" keys"},"finish_reason":null}]}
data: [DONE]使用 Python（OpenAI SDK）
from openai import OpenAI
client = OpenAI(
base_url="https://api.linkastra.ai/v1",
api_key="YOUR_API_KEY"
)
stream = client.chat.completions.create(
model="deepseek/deepseek-v4-pro",
messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end="", flush=True)使用 Node.js（OpenAI SDK）
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.linkastra.ai/v1',
apiKey: 'YOUR_API_KEY',
});
const stream = await client.chat.completions.create({
model: 'deepseek/deepseek-v4-pro',
messages: [{ role: 'user', content: 'Explain quantum computing in simple terms' }],
stream: true,
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || '';
process.stdout.write(content);
}流式分片格式
流中每個分片的結構如下：
{
"id": "chatcmpl-abc123",
"object": "chat.completion.chunk",
"created": 1719000000,
"model": "deepseek/deepseek-v4-pro",
"choices": [
{
"index": 0,
"delta": {
"content": "partial text"
},
"finish_reason": null
}
]
}Delta 與 Message
| 字段 | 非流式 | 流式 |
|---|---|---|
| 內容位置 | choices[].message.content | choices[].delta.content |
| 內容 | 完整響應 | 增量片段 |
finish_reason | 始終存在 | 在最後一個分片之前為 null |
第一個分片通常包含 delta.role: "assistant"。後續分片包含 delta.content 片段。最後一個分片的 finish_reason 為 "stop"，且 delta 為空。
何時使用流式傳輸
| 使用場景 | 是否流式？ |
|---|---|
| 聊天界面 | 是 —— 边生成边顯示文本 |
| 批量處理 | 否 —— 收集完整響應後再處理 |
| API 集成 | 視情況而定 —— 若延迟敏感則使用 |
| 函數調用 | 否 —— 需要完整的結構化輸出 |
最佳實踐
- 務必處理
[DONE]标记 —— 它标志着流的結束 - 設定超時 —— 網络問題可能导致流挂起
- 缓冲小分片 —— 出於顯示考虑，可缓冲後再渲染，避免過度重绘
- 處理斷連 —— 為斷開的連接實現重試邏輯