本文介绍 Claude API Streaming 流式输出的配置和解析方法。Claude API 的流式输出基于 SSE可以将模型生成过程中的内容分批返回常用于 AI 聊天机器人、AI 写作、代码生成、长文总结和 Agent 工具调用等场景。文章将重点说明如何开启 stream 参数如何使用 cURL、Node.js 和 Python 接收流式响应如何解析 message_start、content_block_delta、text_delta、message_delta 等事件以及如何在前端展示过程中处理拼接、渲染、中断和异常重试问题。先说结论Claude API 流式输出适合什么场景Claude API Streaming 并不会让模型本身“思考得更快”。它真正提升的是用户感知上的速度。更具体一点它主要优化这几个指标TTFTTime To First Token也就是首个有效文本返回时间首屏可读时间用户看到第一句话、第一段内容的时间用户感知等待时间从“空等转圈”变成“内容正在生成”可中断成本用户点停止后可以尽早取消后续输出避免继续消耗。一般来说下面这些场景很适合使用 Claude API 流式输出场景是否推荐 Streaming原因AI 聊天机器人推荐用户需要尽快看到反馈AI 写作、长文总结推荐输出内容较长流式体验提升明显代码生成、代码解释推荐用户可以边看边判断是否需要停止Agent / Tool Use推荐工具调用过程可以及时展示出来后台批处理不推荐不需要实时展示非流式更简单短文本分类、打标签不推荐输出太短Streaming 收益有限严格 JSON 结构化输出谨慎使用流式 JSON 需要额外拼接和校验所以核心结论其实很简单Streaming 提升的是感知性能不一定会明显缩短完整响应的总耗时。Claude API Streaming 的基本原理SSE 和事件流Claude API Streaming 基于 SSE也就是 Server-Sent Events。普通的非流式请求会等模型把结果全部生成完再一次性返回一个 JSON。流式请求则不同它会持续返回一系列事件例如message_start content_block_start content_block_delta content_block_stop message_delta message_stop常见事件大概可以这样理解事件作用message_start一条消息开始content_block_start一个内容块开始可能是文本也可能是工具调用content_block_delta内容增量最常见的是text_deltacontent_block_stop当前内容块结束message_delta消息级别的增量可能包含 usage 信息message_stop整条消息结束ping保活事件error流式过程中发生错误这里有个很重要的点开发时不要把整个返回当成普通 JSON 一口气解析而是要按事件类型分别处理。尤其是在 Tool Use 场景里input_json_delta返回的是partial_json也就是 JSON 的一部分。它还不是完整 JSON所以不能每收到一小段就直接JSON.parse否则很容易报错。Claude API Streaming 最小配置先用 cURL 跑通最小配置其实很简单请求体里加上stream: true就可以了。curl-Nhttps://api.anthropic.com/v1/messages\-Hx-api-key:$ANTHROPIC_API_KEY\-Hanthropic-version: 2023-06-01\-Hcontent-type: application/json\-d{ model: claude-3-5-sonnet-20241022, max_tokens: 800, stream: true, messages: [ { role: user, content: 用三段话解释 Claude API Streaming 的优势。 } ] }这里有几个地方很容易被忽略-N关闭 cURL 的输出缓冲。不加的话你可能会误以为没有流式返回stream: true开启 Claude API Streaminganthropic-version指定 API 版本max_tokens控制最大输出长度避免生成过长model模型名请以官方当前可用列表为准不要直接照抄旧示例。怎么判断是不是真的流式很简单如果终端里的内容是一段一段冒出来的而不是等很久后一次性打印出来说明流式链路基本没问题。Node.js 接入 Claude API 流式输出先安装 SDKnpminstallanthropic-ai/sdk一个基础示例如下importAnthropicfromanthropic-ai/sdk;constclientnewAnthropic({apiKey:process.env.ANTHROPIC_API_KEY,});conststreamawaitclient.messages.create({model:claude-3-5-sonnet-20241022,max_tokens:800,stream:true,messages:[{role:user,content:写一段关于 Claude API 流式输出的说明。}],});letfullText;forawait(consteventofstream){if(event.typecontent_block_deltaevent.delta?.typetext_delta){consttextevent.delta.text;fullTexttext;process.stdout.write(text);}if(event.typemessage_delta){// 部分 SDK / 事件中可能会在这里提供 usage 信息// 具体字段请以当前 SDK 返回为准}if(event.typemessage_stop){console.log(\n\n生成结束);}}在生产环境里建议加上AbortController。用户点击“停止生成”时可以立刻取消上游请求避免继续生成和计费。constcontrollernewAbortController();conststreamawaitclient.messages.create({model:claude-3-5-sonnet-20241022,max_tokens:1200,stream:true,messages:[{role:user,content:生成一篇长文。}],},{signal:controller.signal,});// 用户停止时调用// controller.abort();实际开发中比较推荐下面这些做法做法是否推荐只拼接text_delta推荐把所有事件都当文本拼接不推荐支持用户中断推荐只在前端做假打字机效果不推荐换句话说真正的流式应该来自模型输出本身而不是前端拿到完整内容后再模拟打字机效果。Python 接入 Claude API 流式输出先安装 SDKpipinstallanthropic如果只是想拿到文本流可以这样写importanthropic clientanthropic.Anthropic()withclient.messages.stream(modelclaude-3-5-sonnet-20241022,max_tokens800,messages[{role:user,content:解释 Claude API Streaming 配置的关键点。}],)asstream:fortextinstream.text_stream:print(text,end,flushTrue)如果你需要更细地处理事件比如区分文本、Tool Use、usage 等可以遍历完整事件流withclient.messages.stream(modelclaude-3-5-sonnet-20241022,max_tokens800,messages[{role:user,content:输出一段 Markdown 示例。}],)asstream:full_textforeventinstream:ifevent.typecontent_block_delta:deltaevent.deltaifgetattr(delta,type,None)text_delta:full_textdelta.textprint(delta.text,end,flushTrue)ifevent.typemessage_stop:print(\n生成完成)Python 服务端尤其要注意两点。第一控制台输出时记得加flushTrue。否则本地看起来可能不像流式而像攒了一段之后才输出。第二如果通过 Web 框架转发给浏览器要确认响应缓冲已经关闭。不然即使 Claude API 是流式返回浏览器也可能还是一次性收到内容。前端怎么展示 Claude 流式输出EventSource 和 Fetch Stream浏览器端不要直接请求 Claude API因为这样会暴露 API Key。比较安全、也更符合生产环境的架构是浏览器 → 业务后端 → Claude API也就是说前端只请求自己的业务后端。鉴权、调用 Claude、转发流、记录日志这些事情都交给后端处理。如果后端提供的是 SSE GET 接口前端可以用EventSourceconstesnewEventSource(/api/chat-stream?conversationId123);es.onmessage(event){appendText(event.data);};es.onerror(){es.close();};不过很多聊天接口需要 POST 请求还要携带复杂 body 或自定义鉴权。这种情况下更推荐使用fetch ReadableStreamconstcontrollernewAbortController();constresawaitfetch(/api/chat-stream,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify({message:你好介绍一下 Claude API 流式输出}),signal:controller.signal,});constreaderres.body.getReader();constdecodernewTextDecoder();while(true){const{done,value}awaitreader.read();if(done)break;constchunkdecoder.decode(value,{stream:true});appendText(chunk);}// 停止生成// controller.abort();前端渲染也别太激进。不要每来一个 token 就重新渲染整篇 Markdown这样很容易卡尤其是长文本和代码块。更稳妥的做法是每 30–100ms 批量刷新一次。代码块还没闭合时可以先按纯文本展示等生成结束后再做完整 Markdown 渲染和代码高亮。这样用户体验会稳定得多。服务端转发 SSE 的生产配置很多人本地测试时流式好好的一上线就变成一次性返回。原因通常不是代码错了而是代理、网关或 CDN 把响应缓冲了。后端转发 SSE 时建议设置这些响应头Content-Type: text/event-stream Cache-Control: no-cache, no-transform Connection: keep-alive X-Accel-Buffering: no一个 Node.js / Express 示例app.post(/api/chat-stream,async(req,res){res.setHeader(Content-Type,text/event-stream);res.setHeader(Cache-Control,no-cache, no-transform);res.setHeader(Connection,keep-alive);res.setHeader(X-Accel-Buffering,no);constcontrollernewAbortController();req.on(close,(){controller.abort();});try{conststreamawaitclient.messages.create({model:claude-3-5-sonnet-20241022,max_tokens:1000,stream:true,messages:[{role:user,content:req.body.message}],},{signal:controller.signal});forawait(consteventofstream){if(event.typecontent_block_deltaevent.delta?.typetext_delta){res.write(data:${JSON.stringify(event.delta.text)}\n\n);}}res.write(event: done\ndata: {}\n\n);res.end();}catch(err){res.write(event: error\ndata:${JSON.stringify({message:stream error})}\n\n);res.end();}});如果前面还有 Nginx需要关闭代理缓冲location /api/chat-stream { proxy_pass http://backend; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; }另外CDN、Serverless、API Gateway 这些中间层也可能缓冲响应。部署前一定要实际验证内容是不是逐段返回而不是最后一次性吐出来。Tool Use 场景下怎么解析流式事件Tool Use 的流式处理会比普通文本复杂一点因为工具参数可能会通过input_json_delta分段返回。比如你可能收到类似这样的内容content_block_start: tool_use content_block_delta: input_json_delta partial_json{\query\:\Claude content_block_delta: input_json_delta partial_json Streaming\} content_block_stop错误做法是每收到一段就立刻解析JSON.parse(partialJson);// 容易报错因为这时候的partial_json还不是完整 JSON。正确做法是按content_block的index缓存起来等content_block_stop到了之后再统一解析consttoolJsonBuffernewMap();functionhandleEvent(event){if(event.typecontent_block_deltaevent.delta?.typeinput_json_delta){constoldtoolJsonBuffer.get(event.index)||;toolJsonBuffer.set(event.index,oldevent.delta.partial_json);}if(event.typecontent_block_stop){constjsontoolJsonBuffer.get(event.index);if(json){constargsJSON.parse(json);// 执行工具调用}}}Tool Use 这里最关键的一点是文本、工具参数、thinking delta 不要粗暴拼成同一个字符串。不同类型的事件应该分开处理否则后面很容易出现解析失败、展示混乱或者状态不同步的问题。性能实测流式和非流式到底差在哪做 Claude API 性能优化时建议至少记录下面这些指标指标定义TTFT请求发出到首个有效文本 token 返回TTL请求发出到message_stop或完整响应结束Tokens/sec输出 token 数 / 生成耗时首屏可读时间前端出现可读句子或段落的时间中断节省用户停止后减少的后续输出 token测试时不要只测一种任务最好覆盖不同长度和不同前端渲染方式测试类型输出长度目的短文本100–300 tokens看短任务是否值得流式中等文本800–1500 tokens观察 TTFT 和总耗时长文本3000 tokens评估用户感知收益前端逐 token 渲染不限观察是否卡顿前端节流渲染不限对比渲染优化效果如果要发布正式测试数据建议表格里补充测试日期、模型、地区、SDK 版本、网络环境、重复次数和统计口径。一个可复现的测试表可以这样设计模式任务TTFTTTLTokens/sec结论非流式短文本无首字返回待实测待实测实现简单流式短文本待实测待实测待实测体验略好非流式长文本无首字返回待实测待实测等待感明显流式长文本待实测待实测待实测首屏反馈明显更好实际测下来通常会得到一个比较稳定的结论流式对 TTFT 和首屏可读时间帮助最大但 TTL 往往和非流式接近。因此不太建议把 Streaming 宣传成“总耗时一定更短”。更准确的说法应该是用户能更早看到内容也能更早决定是否中断。Claude API Streaming 性能优化清单Claude API 的性能优化可以从五个层面来做。1. 降低首字延迟想让第一个字更快出现可以从这些地方入手精简 system prompt减少无关上下文根据任务复杂度选择合适模型避免过长 prefill后端尽量复用连接减少冷启动影响。2. 控制输出长度输出越长总耗时和成本通常越高。所以要主动控制生成范围设置合理的max_tokens长文任务给出明确结构不要让模型无限扩写支持用户点击停止并立即 abort 上游请求。3. 优化前端渲染前端渲染做不好流式体验也会被拖垮。建议注意这些点不要每个 token 都重新渲染整篇 Markdown使用 30–100ms 的批量刷新代码块没闭合时先不要急着做高亮解析页面上展示“正在生成”而不是只有一个简单 loading。4. 提升稳定性线上环境更复杂要把异常情况提前考虑进去正确处理ping保活设置请求超时捕获断流错误避免无限重试使用 request id 做日志追踪。5. 做好成本监控Streaming 本身不等于省钱但它能帮助用户更早中断。成本监控可以这样做记录 input tokens 和 output tokens记录用户是否中断长任务优先使用流式后台任务可以使用非流式日志注意脱敏避免保存敏感内容。常见问题与排错为什么设置了stream: true还是一次性返回先检查三个地方cURL 是否加了-N后端是否缓冲响应Nginx / CDN 是否开启了 proxy buffering。为什么前端收不到 SSE确认响应头是不是text/event-stream再检查浏览器请求是否被网关压缩、缓存或合并了。为什么 Nginx 部署后不再逐字输出通常是proxy_buffering没关。需要在对应的 location 里设置proxy_buffering off;为什么 Markdown 代码块显示错乱流式输出时代码块可能还没生成完整。建议先按纯文本增量展示等结束后再做完整 Markdown 渲染。Tool Use 的 JSON 为什么解析失败因为partial_json只是 JSON 的一部分不是完整 JSON。必须缓存到content_block_stop之后再解析。Streaming 会不会更省钱不一定。Streaming 不会改变 token 单价也不会改变模型计费逻辑。它可能带来的成本优势主要来自用户提前停止生成从而减少后续输出。Streaming 和 WebSocket 应该选哪个如果只是模型单向输出优先选 SSE简单稳定。如果需要双向实时通信、多人协作或者复杂状态同步再考虑 WebSocket。最佳实践推荐架构和上线 Checklist推荐架构如下浏览器 ↓ 业务后端鉴权、限流、日志、调用 Claude API、转发 SSE ↓ Claude API / 兼容接入平台上线前建议逐项检查API Key 只放在后端不进入浏览器请求体设置了stream: true明确指定model、max_tokens、anthropic-version只拼接text_delta不要把所有事件混在一起Tool Use 的partial_json等 block 结束后再解析后端 SSE 响应头设置正确Nginx / CDN / Serverless 不缓冲响应支持 AbortController 停止生成记录完整回答、usage 和 request id前端 Markdown 渲染做节流长文本和聊天使用 Streaming后台批处理使用非流式。最后总结一句Claude API Streaming 的配置本身不复杂真正容易出问题的是事件解析、服务端转发、前端渲染和线上稳定性。如果只是本地跑一个 demostream: true基本就够了。但如果要放进真实业务里就不能只关注能不能输出还要把 SSE 响应头、代理缓冲、用户中断、Tool Use 拼接、usage 统计和性能指标一起设计好。