流式响应 — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# 流式响应

使用 **Server-Sent Events (SSE)** 流式返回 Chat Completions token。

## 启用流式

在请求体中设置 `"stream": true`：

```json
{
  "model": "deepseek/deepseek-chat",
  "messages": [{"role": "user", "content": "数到五。"}],
  "stream": true
}
```

**思考型 / 长推理模型请务必使用 `stream: true`。** 非流式请求在 CDN（如 Cloudflare）后可能受约 100s 首字节限制而中断。流式路径下网关会周期性发送 SSE 注释行（`: keepalive`），各语言 SDK 会忽略注释，不影响解析。

## 响应格式

- **Content-Type**：`text/event-stream`
- 每行：`data: <json chunk>`
- 结束：`data: [DONE]`

示例（`data:` 后 JSON 实际传输多为单行，此处换行便于阅读）：

```http
data: {
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "choices": [
    {
      "index": 0,
      "delta": { "content": "一" },
      "finish_reason": null
    }
  ]
}

data: {
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "choices": [
    {
      "index": 0,
      "delta": { "content": "、二" },
      "finish_reason": null
    }
  ]
}

data: [DONE]
```

## 流式 usage

流式响应末尾可能包含 `usage` 对象（取决于模型支持情况）。

## curl 示例

```bash
curl -N "${SNX_BASE_URL}/chat/completions" \
  -H "Authorization: Bearer ${SNX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "stream": true,
    "messages": [{"role": "user", "content": "打个招呼"}]
  }'
```

使用 `-N` 禁用 curl 缓冲。

## OpenAI SDK（Python）

```python
stream = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "打个招呼"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)
```

## 错误处理

| 阶段 | 行为 |
|------|------|
| **流开始前** | HTTP 4xx/5xx + JSON `error`（与非流式相同） |
| **流进行中** | 客户端应处理 SSE 截断 |

配额、余额、认证错误通常在**首字节之前**返回。

## 相关

- [Chat Completions](./chat-completions.md)
- [错误处理](./errors.md)