流式输出（Streaming）

​

使用场景

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

​

支持的模型

​

工作机制

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

​

关键参数

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

​

返回内容

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

​

调用示例

export API_KEY="YOUR_API_KEY"

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

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

​

限制说明

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