Skip to main content
本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
生成类接口既可一次性返回完整响应，也可返回 Server-Sent Events（SSE）流，由每次请求的 response_mode 决定。通常选流式返回：回复边生成边呈现，长时间运行也不会中途被切断。

​
选择响应模式

blocking（阻塞式返回）在生成结束后一次性返回一个 JSON 响应体。对简短、非交互的调用来说，它集成起来更简单，但长时间生成有被中断的风险：代理会切断长请求，Dify Cloud 的边缘代理约 100 秒后就会终止请求。 streaming（流式返回）以 SSE 事件的形式传送回复。面向用户的场景、长时间运行的任务，以及所有会因 人工介入 暂停的流程，都应使用它。
Agent 和新 Agent 应用仅支持流式返回。

​
解析事件流

每个事件以一行 data: 的形式到达，携带一个 JSON 对象，并以一个空行结束。 根据 event 字段决定如何处理，并跳过所有不以 data: 开头的行：保活用的 ping 每 10 秒到达一次，形式是一行不带 data: 载荷的 event: ping。 
import json
import requests

body = {
    "query": "What are this month's top issues?",
    "inputs": {},
    "user": "customer-4821",
    "response_mode": "streaming",
}

with requests.post(url, headers=headers, json=body, stream=True) as r:
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue  # 跳过空行分隔符和 ping 行
        event = json.loads(line[len("data: "):])
        handle(event)
实际传输中，事件流如下所示： 
data: {"event": "workflow_started", "task_id": "c3800678-…", "workflow_run_id": "fb47b2e6-…", "data": {…}}

event: ping

data: {"event": "node_finished", "task_id": "c3800678-…", "workflow_run_id": "fb47b2e6-…", "data": {…}}

​
按事件类型分发

会收到哪些事件取决于应用类型。事件契约详见 发送对话消息、执行工作流 和 发送消息 页面中的事件表。 通常至少要做到：
  1. 按顺序拼接回复片段：
    • Chatbot 和 Chatflow 应用为 message 事件
    • Agent 和新 Agent 应用为 agent_message 事件
    新 Agent 应用在收尾时会额外返回一个重复完整回答的 message 事件，将其视为最终回答即可，不要再追加拼接。
  2. 在正确的终止事件上收尾：
    • Chatbot、Agent 和新 Agent 应用为 message_end
    • Chatflow 应用为 message_end 后跟 workflow_finished（两个事件都会到达，且按此顺序）
    • Workflow 应用为 workflow_finished
  3. 将 error 事件上报给调用方。

​
处理流中的错误

流打开之后再发生失败，HTTP 状态码不会改变：连接保持 200。失败以何种形式出现，取决于它发生在哪里：
  • 工作流节点失败时，会收到 status 为 "failed" 的 node_finished 和 workflow_finished 事件。
  • 其他失败会以一个携带 status、code 和 message 的 error 事件结束整个流。
两种情况都要处理，且都视为该请求的终点。

​
重连与恢复

有两个标识符很重要，且容易混淆： 两者都从流本身获得：除 error 外的每个事件都携带 task_id，工作流和节点事件还携带 workflow_run_id。收到 workflow_run_id 后立即保存：如果连接中途断开，它是重连或查询运行结果的唯一凭据。 对由工作流驱动的运行（Workflow 和 Chatflow 应用），连接断开并非致命问题。可用 流式获取工作流事件 重新打开事件流，传入 workflow_run_id 和发起运行时所用的同一个 user。user 不一致会返回 404。 加上 include_state_snapshot=true 可先重放已执行节点的状态；加上 continue_on_pause=true 可在多次人工介入暂停间保持同一个流不断开。 重连到仍在运行的工作流后，用 获取工作流执行情况 确认运行已完成，不要只依赖重连后事件流的最后一个事件。 其他类型的回复没有恢复接口：连接在回复中途断开时，重新发起请求即可。对话类应用可通过 获取会话历史消息 查看已保存到会话中的内容。

​
保持连接

将客户端的读取超时设置为明显大于 10 秒的 ping 间隔，事件之间的空闲期才不会导致连接被断开。ping 本身无需处理，跳过即可。
Last modified on July 9, 2026