跳到文章正文
Claude 实用教程

Claude API怎么流式输出?text_stream、最终消息与断流检查

用官方SDK增量读取文本,再获取完整最终消息检查stop_reason;区分事件、内容块与文本片…

Claude API怎么流式输出?text_stream、最终消息与断流检查

流式输出让用户更早看到内容,但数据分片不等于完整消息。Claude Messages API通过SSE传输,SDK可简化文本消费。本文实现最小文本流与最终状态检查,不重复HTTP错误排查,也不把界面动画当作真实接口流。

第一步:明确显示与提交两种状态

显示层可以逐段追加文字,业务层应等消息完成后才保存最终结果或触发后续步骤。记录请求与响应身份,避免重连时把两个请求的片段拼成一个回答。

需要开发者API和兼容SDK,模型与平台支持按当前文档核对。输出预算仍受max_tokens约束,使用流式不会增加上下文窗口或绕过账号限制。

第二步:使用SDK文本流

下面是人工练习,不执行真实调用。text_stream便于处理纯文字,退出流前可获取最终Message,再核对停止原因。打印片段时不自行插入多余换行,以免破坏代码或JSON文本。

import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
    model="claude-opus-5-5", max_tokens=1024,
    messages=[{"role": "user", "content": "请用三句话解释练习项目的文件备份原则。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()
print("\nstop_reason:", final.stop_reason)

第三步:不要把所有事件当文本

底层流包含message_start、内容块开始结束、delta、message_delta、message_stop和可能的ping或error等事件。工具调用的JSON片段和thinking内容不能当普通文本直接展示或执行。

首次只实现文本流,复杂工具流程再按官方事件结构扩展。遇到未知事件应兼容记录,不让前端因为新类型崩溃,也不在解析失败时把未校验片段当成有效指令。

第四步:断线和截断分别处理

连接中断而没有完整结束,应标为部分结果。HTTP连接开始成功也可能在后续收到error事件,不能只检查最初200。max_tokens等停止原因则需要按完整响应语义处理,不全都叫网络失败。

重试可能产生另一份答案,不应把新答案继续接到旧半句后面。对已有部分文本保留清晰状态;若后续涉及写工具,先核对是否已执行,防止重复业务动作。

验收计划:短文本正常完成;低预算截断;中途断连;工具事件出现;未知事件类型。分别检查界面状态、最终消息、是否重复文本与是否误触发后续步骤。

第五步:最终消息再做内容验收

只有完整流和预期stop_reason通过,才进入JSON解析、文件生成或事实核对。格式正确不代表事实正确,text_stream里看起来结束也不代表底层协议结束。

保存必要用量与完成状态,日志脱敏,不将所有输入输出长期公开。完成标准是增量显示准确、结束状态可靠、失败可解释且不重复副作用。本教程仅提供示例与测试计划,不虚报已在读者账号亲测。

官方资料

资料核对日期:2026年11月18日。

本文地址:https://www.163264.com/21718