> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 流式输出（Streaming）

> 了解算秩 Streaming 流式输出的工作机制、stream 参数、chunk 字段处理、客户端消费方式和长回复最佳实践。

流式输出（Streaming）用于让模型在生成过程中持续返回增量内容，而不是等完整回复生成后一次性返回。应用可以边接收边展示输出，从而降低长回复场景下的等待体感。

Streaming 常用于聊天界面、长文本生成、代码生成、Agent 执行过程展示等场景。它不一定缩短模型生成完整答案的总耗时，但可以让用户更早看到模型开始回复。

该能力通过兼容 OpenAI 的调用方式提供。您可以在请求中设置 `stream=True`，并在客户端逐块读取返回内容。

## 使用场景

* **聊天 UI**：边生成边展示模型回复，减少用户等待感。
* **长文本生成**：生成报告、总结、方案或代码时，逐步展示输出内容。
* **代码与推理任务**：让用户更早看到模型的输出进展，便于判断是否需要中止或调整请求。
* **Agent 交互**：在多步骤任务中展示模型的中间输出或执行进度。

## 支持的模型

不同模型对 Streaming 的支持情况可能不同。请通过 [模型广场](https://console.siflow.cn/model-inference/models) 的模型详情页查看最新支持情况。

## 工作机制

开启 Streaming 后，一次请求通常包含以下流程：

1. 客户端发送请求，并设置 `stream=True`。
2. 模型开始生成后，服务端持续返回增量内容。
3. 客户端按顺序读取每个 chunk，从中提取需要展示或保存的增量字段。
4. 客户端收到结束原因后，停止读取并完成本次响应。

<Note>
  如果中途断连或超时，客户端需要决定是否重试、提示用户，或保留已接收的部分输出。Streaming 只改变响应返回方式，不改变模型本身的生成逻辑。应用仍需要处理鉴权、超时、断连、用户取消、内容拼接和最终结果保存。
</Note>

## 关键参数

* `stream`：是否开启流式返回。设置为 `True` 时，客户端需要按流式方式消费响应。
* `max_completion_tokens`：控制最大生成长度。长回复仍需要设置合理的输出上限，避免输出过长导致成本或延迟不可控。

## 返回内容

流式响应由多个 chunk 组成。不同模型、不同能力组合下，chunk 中的字段可能不同，客户端应按字段是否存在进行兼容处理。

流式 chunk 的 `object` 通常为 `chat.completion.chunk`，`delta` 中可能出现以下字段：

* `role`：消息角色，通常出现在流式响应开始阶段。
* `content`：模型生成的文本增量，通常用于拼接最终展示给用户的回复。
* `reasoning_content`：模型生成过程中的推理内容或中间思考内容。是否返回、返回多少，取决于具体模型和请求结果。

<Note>
  不要假设每个 chunk 都包含 `content`。部分 chunk 可能只包含 `role`、`reasoning_content`、结束原因或用量信息。客户端应跳过不需要处理的空增量或非展示字段。
</Note>

`finish_reason` 表示本次生成结束的原因，通常出现在最后一个包含 `choices` 的 chunk 中。

`usage` 可能在流式响应末尾返回，用于查看本次请求的 token 用量。不同模型的返回情况和 `usage` 明细字段可能不同，请以实际返回结果为准。

## 调用示例

示例使用环境变量读取 API Key，避免将密钥写入代码。

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

以下示例演示如何开启 Streaming，并在收到增量内容时立即打印。

这段代码完成以下处理：

1. 设置 `stream=True` 开启流式返回。
2. 遍历响应中的每个 chunk。
3. 优先读取 `delta.content` 并拼接为最终展示文本。
4. 如需记录推理过程，可单独收集 `delta.reasoning_content`，不要默认混入最终回答。

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://api.siflow.cn/model-api",
)

stream = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {
            "role": "user",
            "content": "请用三段话介绍什么是流式输出。",
        }
    ],
    stream=True,
    max_completion_tokens=1024,
)

final_answer = []
reasoning_trace = []

for chunk in stream:
    if not chunk.choices:
        continue

    delta = chunk.choices[0].delta

    content = getattr(delta, "content", None)
    if content:
        final_answer.append(content)
        print(content, end="", flush=True)

    reasoning_content = getattr(delta, "reasoning_content", None)
    if reasoning_content:
        reasoning_trace.append(reasoning_content)

print()
```

示例默认只展示 `delta.content`。如果您的产品需要展示或保存推理过程，可以按业务需要处理 `reasoning_trace`；如果不需要，可以忽略 `reasoning_content`。

具体 chunk 字段结构可能随 API 版本、模型能力和请求参数变化，请以 API 指南和实际返回结果为准。

## 最佳实践

* **区分最终回答和推理内容**：优先使用 `delta.content` 拼接最终展示文本。如果返回 `reasoning_content`，请按业务需要单独处理，不要默认和最终回答混在一起。
* **边展示边保存完整结果**：前端可以逐步渲染文本，后端仍应保存完整响应，便于审计、重试和后续处理。
* **处理非内容 chunk**：部分 chunk 可能不包含文本内容。客户端应跳过不需要处理的字段，而不是将其当作错误。
* **处理用户取消**：在聊天或 Agent 场景中，用户可能中止生成。应用应停止读取流，并正确更新会话状态。
* **设置超时和重试策略**：Streaming 连接持续时间可能较长。请设置合理的客户端超时，并明确断连后的处理方式。
* **不要提前解析不完整结构**：如果结合 Structured Output 或 JSON 输出使用，请等到完整响应收齐后再解析 JSON。
* **控制输出长度**：长回复建议设置合理的 `max_completion_tokens`，避免输出过长导致成本增加或连接持续时间过长。

## 限制说明

* Streaming 需要客户端持续读取响应流。如果客户端、代理或网关不支持长连接，可能无法稳定接收完整输出。
* Streaming 不保证模型更快完成生成，只是让部分内容更早返回。
* 如果请求中途断开，已接收内容可能是不完整输出。应用需要处理部分结果、重试和用户提示。
* 与 Function Calling、Structured Output、reasoning content 等能力组合使用时，具体返回结构和处理方式可能不同，请以 API 指南、模型详情和实际返回结果为准。
* token 用量、结束原因和 chunk 字段结构可能因模型而异，不建议在业务逻辑中依赖未确认的内部字段。