DeepSeek API Streaming: SSE on V4-Pro and V4-Flash

您点击“发送”，用户盯着旋转器长达十五秒，而一个1,500个token的回答在沉默中组装。这就是默认的`POST /chat/completions`体验——这也是团队在所有其他功能之前开启DeepSeek API流式传输的最大原因。使用`stream=true`，token在模型生成时即出现在浏览器中，感知延迟降低到第一个token的时间，思维模式痕迹可以实时读取，而不是作为一堵文本墙出现。

本指南涵盖了实际操作机制 DeepSeek V4 （发布日期：2026年4月24日）：SSE协议在`api.deepseek.com`上的工作方式，如何消费与最终`content`并行的`reasoning_content`增量，生产部署中需要注意的问题（代理超时、工具调用的V4往返规则），以及一个实际成本示例，以便您在发货前规划支出。

DeepSeek API流式传输实际上是什么

DeepSeek API流是聊天端点的服务器发送事件（SSE）模式。设置 stream: true 在您的JSON体中，服务器会回复 内容类型：text/event-stream，推送每个标记（或一小批标记）作为 数据： 行，直到发送最终的 数据： [完成] 监视器。如果设置，将发送部分消息增量。token将以仅数据的服务器发送事件（SSE）形式发送，一旦可用，通过数据： [完成]消息终止流。

线路格式是OpenAI兼容的Chat Completions模式。每个块都是一个小的JSON对象，其 选项[0].delta 带有新的标记文本而不是完整 message。这意味着您的客户端在收到delta时将其附加，而不是替换缓冲区。

两项事实构成了本文其余内容的基石：

• The current generation is DeepSeek V4以两个开放权重MoE模型的形式发布，遵循MIT许可— deepseek-v4-pro (1.6T total / 49B active) and deepseek-v4-flash （284B / 13B活动）。DeepSeek-V4-Pro具有1.6T参数（49B激活）和DeepSeek-V4-Flash具有284B参数（13B激活）——两者都支持一百万个token的上下文长度。
• The API is stateless. 流式传输改变了响应到达的方式，而不是状态管理的方式。你仍然需要在每个请求中重新发送完整的对话历史——与网页聊天不同，网页聊天将历史保存在服务器端以供用户会话使用。

如果您尚未配置访问权限，请首先完成 get a DeepSeek API key 的工作；本指南的其余部分假设在 $DEEPSEEK_API_KEY.

快速入门：使用curl和Python进行流式传输

Chat 请求 hit POST /chat/completions, the OpenAI-compatible endpoint at https://api.deepseek.com中有一个有效的密钥。

curl https://api.deepseek.com/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" 
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Stream a haiku about caching."}],
    在调用时在您的JSON体中设置
  }'

最基本的curl调用： 数据： {...} 您将看到一系列 {"choices":[{"delta":{"content":"a "}}]}行，每行包含一个类似 数据： [完成].

的片段，以 base_url 在DeepSeek：

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Stream a 200-word essay on MoE."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.选项[0].delta.content or ""
    print(delta, end="", flush=True)

关于认证、基础URL和SDK安装的完整指南，请参阅 DeepSeek API getting started and DeepSeek OpenAI SDK compatibility. 如果您的堆栈已经支持该模式，DeepSeek 还会针对相同的基URL暴露一个 Anthropic 兼容的界面。

使用思考模式（reasoning_content）进行流式传输

在V4中，思考模式是任一模型上的一个请求参数，而不是一个单独的模型ID。通过以下方式启用： reasoning_effort="high" plus extra_body={"thinking": {"type": "enabled"}}; the response then returns reasoning_content alongside the final content。仅用于思考模式。助手消息的推理内容，在最终答案之前。

在流式传输时，这些跟踪信息会出现在 delta 的一个单独字段中。流式聊天完成也支持推理模型。在聊天完成响应块中的 delta 字段中，可用 reasoning_content 字段。一个同时处理两个字段的模式：

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Plan a database migration."}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
    stream=True,
)

reasoning, content = "", ""
for chunk in stream:
    delta = chunk.选项[0].delta
    if getattr(delta, "reasoning_content", None):
        reasoning += delta.reasoning_content
        # render in a collapsible UI panel
    if delta.content:
        content += delta.content
        # render in the main answer panel

两个实用提示：

• 首先推理流，其次内容。 模型在发出任何答案标记之前，先发出完整的推理跟踪。同时显示两者的UI应将其渲染 reasoning_content 在一个单独的、暗淡的、可折叠的面板中，以便用户看到 某些内容 在模型思考时的移动。
• V4修改了往返规则。 如果一个回合包含工具调用，你必须传递助手的 reasoning_content 在下一个请求中返回，或者 API 返回 400。 “在思考模式下，`reasoning_content` 必须返回给 API。”，“type”：“invalid_request_error” 旧版本 deepseek-reasoner ID遵循相反的规则（从历史记录中删除 reasoning_content ）；请确保您的客户端库正确处理V4。

对于高努力变体， reasoning_effort="max" 需要至少 384K 令牌的上下文窗口以避免截断。对于 Think Max 推理模式，我们建议将上下文窗口设置为至少 384K 令牌。参见 DeepSeek V4-Pro 对于完整的特性矩阵。

参考：块、增量以及[完成]哨兵

每个流式传输块都是一个 JSON 对象，它反映了非流式响应的形状，有两个关键区别：

1. choices[0].message 被替换为 选项[0].delta ——这个块增量字段。
2. 整个流以一个字面 数据： [完成] 行结束，该行是 not JSON。不要尝试解析它。

一个代表性的块：

数据： {"id":"...","object":"chat.completion.chunk","created":1761000000,
       "model":"deepseek-v4-flash",
       "choices":[{"index":0,"delta":{"content":" Hi"},"finish_reason":null}]}

完整的请求/响应模式位于 DeepSeek API documentation; 另请参阅 DeepSeek API code examples 以获取Node、Go和Rust中的可粘贴片段。

生产级流式传输：超时、代理和保活

流式传输中最常见的单一生产故障不在于客户端代码，而是在于网络路径。V4-Pro thinking-max上的长时间生成可能持续数分钟，而你服务前面的任何反向代理、CDN、无服务器网关或WAF都可能无声地杀死连接。

DeepSeek 本身通过两个你应该了解的安全阀来应对调度压力。DeepSeek 的速率限制文档指出，在调度压力下：非流式请求在等待时可能会返回空行。流式请求在等待时可能会返回：保留-alive 注释。如果推理在10分钟后仍未开始，服务器将关闭连接。因此，一个健壮的客户端必须：

• 将以 : （SSE注释语法）开头的行视为保持连接的信号——忽略它们，不要报错。
• 设置一个 读取超时，比您期望的token之间最长间隔更长，而不是总响应预算。对于思考模式流量，六十秒是一个合理的下限。，而不是您的总响应预算。六十秒是思考模式流量的合理下限。
• 配置你的反向代理（nginx、Cloudflare、ALB、API Gateway）以禁用响应缓冲并允许长时间空闲连接。在生产环境中使用显式的连接/读取超时，并确保你的反向代理、无服务器运行时或网关层不会过早地杀死长时间运行的流式响应。
• 将 429 作为可重试的信号处理——DeepSeek通过动态并发进行节流，而不是固定的RPM。请参阅 DeepSeek API rate limits 了解当前行为。

对于 Python 中的 SSE 解析，两种可接受的模式：OpenAI SDK（它为你处理帧）或 请求 手动行迭代。如果你更喜欢辅助工具，sseclient-py 可以使用，但在这里自己实现也可以，只要你能防止部分行和超时。在 Node 中，fetch + 可读流读取器工作；在浏览器中，原生的 Event来源 API不支持自定义 Authorization 使用头部，因此请使用fetch加上流式读取器。

在飞行中取消

关闭HTTP连接将取消服务器端生成。在Python中使用OpenAI SDK，请调用 stream.close()在Node中，请调用 controller.abort() 在您传入的AbortController上。您将停止为从未收到的输出令牌付费——当用户在您的UI中点击“停止”时非常有用。

成本示例：流式传输不会改变账单

流式传输纯粹是一个传输选择——DeepSeek无论您是否进行流式传输，都收取相同的令牌。不同层级的定价差异才是关键。截至2026年4月，V4-Flash的费率是 $0.0028 cache-hit / $0.14 cache-miss / $0.28 output 每100万个令牌，而V4-Pro是 $0.003625 / $0.435 / $0.87 在2026-05-31前的75%促销期间（列表价 $0.0145 / $1.74 / $3.48）。在报价前请始终在实时页面上进行验证。 DeepSeek API pricing 流式聊天产品的示例工作

Worked example for a streaming chat product on deepseek-v4-flash：每月1,000,000次调用，包含2,000令牌的系统提示（已缓存），200令牌的用户消息（未缓存），以及300令牌的流式响应。

The same workload on deepseek-v4-pro 通过至2026-05-31的75%促销（$0.003625 / $0.435 / $0.87）的价格为 $355.25 ——大约是Flash费用的3倍（列表价$0.0145 / $1.74 / $3.48 → $1,421.00，约14倍Flash）。只有当代理或编码提升能够自付其账时，才需要Pro。高峰时段折扣于2025年9月5日结束，并且V4版本中没有恢复。有关实时计算器，请参阅 DeepSeek cost estimator.

注意： usage.prompt_cache_hit_tokens and usage.prompt_cache_miss_tokens 在最终块上告诉你每个请求具体属于哪个桶。如何检查它：检查响应中的usage.prompt_cache_hit_tokens和usage.prompt_cache_miss_tokens。确保您已将 stream_options={"include_usage": true} 如果您需要从流式调用中获取那些数字。更多关于前缀重用的信息请参阅 DeepSeek context caching.

Error handling patterns

流式失败分为三个类别，每个类别有不同的解决方案：

最后一行值得强调。JSON模式是 designed 设置为返回有效的JSON，不保证；文档中明确警告：当使用JSON输出时，您还必须通过系统或用户消息指示模型自己生成JSON。如果没有这样做，模型可能会生成一个无限循环的空白流，直到生成达到令牌限制，导致长时间运行且看似“卡住”的请求。始终在提示中包含字面词“json”以及一个示例模式，设置 max_tokens 足够高的，以避免截断，并处理偶尔的空内容。完整模式在 DeepSeek API JSON mode; 对于状态码，参见 DeepSeek API error codes.

Legacy IDs and the migration window

如果您仍然在使用 deepseek-chat or deepseek-reasoner的集成，它们将继续工作——目前分别路由到 deepseek-v4-flash （非思考和思考模式）。退休日期是 2026-07-24 at 15:59 UTC; after that, 请求 with those IDs fail. Migration is a one-line model= swap; base_url does not change.

对于流式代码而言，唯一需要测试的行为变化是之前提到的V4 reasoning_content往返规则。旧版指南涵盖了重试、批处理和前缀设计。如果您需要将完成项推送到下游服务而不是将它们流回客户端，DeepSeek不自带该中继模式。完整的参考集位于（最终答案）。推理流先；内容随后。如果您的UI显示两者，请将它们缓冲到两个字符串中。DeepSeek按令牌计费，而不是按网络字节计费——具有相同输入和输出的流式和非流式请求费用相同。优势是感知到的延迟，而不是价格。要估算令牌桶间的花费，请使用 deepseek-reasoner 需要您 从历史记录中删除 reasoning_content ；V4要求您 保留 它，只要涉及工具调用。在切换之前审计您的客户端库。

对于迁移后的更广泛的API模式，请参阅 DeepSeek API best practices 指南涵盖了重试、批处理和前缀设计。如果您需要将完成项推送到下游服务而不是将它们流回客户端，DeepSeek不自带该中继模式。完整的参考集位于（最终答案）。推理流先；内容随后。如果您的UI显示两者，请将它们缓冲到两个字符串中。DeepSeek按令牌计费，而不是按网络字节计费——具有相同输入和输出的流式和非流式请求费用相同。优势是感知到的延迟，而不是价格。要估算令牌桶间的花费，请使用 异步事件传递教程 文档了中继模式。DeepSeek不自带该中继模式。完整的参考集位于（最终答案）。推理流先；内容随后。如果您的UI显示两者，请将它们缓冲到两个字符串中。DeepSeek按令牌计费，而不是按网络字节计费——具有相同输入和输出的流式和非流式请求费用相同。优势是感知到的延迟，而不是价格。要估算令牌桶间的花费，请使用 DeepSeek API docs and guides hub.

DeepSeek AI Guide is an independent resource and is not affiliated with DeepSeek or its parent company. Model IDs, pricing and API behaviour change; check the official DeepSeek documentation and pricing page before committing to a production decision.