Dify流式响应如何与OpenWebUI的SSE接口正确对接？

Question

常见问题：Dify 的流式响应（`text/event-stream`）与 OpenWebUI 的 SSE 接口对接时，常因事件格式不兼容导致前端卡顿或消息丢失。OpenWebUI 严格依赖标准 SSE 协议（如 `data: {...}\n\n`），而 Dify 默认返回的流式 chunk 可能混杂非标准字段（如 `event: message`、`id:` 或含空行/JSON嵌套结构），且部分版本未对 `data:` 行做 JSON 字符串转义，导致前端解析失败；此外，Dify 的 `/chat/chat` 接口在启用多工具调用时可能插入 `event: tool_thinking` 等非 `message` 类型事件，OpenWebUI 若未忽略则抛错。同时，若后端未设置 `Content-Type: text/event-stream` 和禁用缓冲（如 Nginx 需配 `proxy_buffering off; proxy_cache off;`），SSE 连接将无法实时推送。这些问题共同表现为“首字延迟高”“中途断连”或“仅收首条响应”。

Answer 1

```html

一、现象层：前端可见的异常表现

• OpenWebUI 页面首次响应延迟高达 3–8 秒（首字节 TTFB 异常）
• 流式输出中途卡顿，后续消息完全停止（onmessage 事件中断）
• 仅接收第一条完整 JSON 响应，后续 chunk 被静默丢弃
• 浏览器开发者工具 Network 面板中 SSE 连接状态为 pending 后突变为 cancelled
• 控制台报错：Failed to execute 'postMessage' on 'Window': Invalid event type 或 Unexpected token { in JSON at position 0

二、协议层：SSE 标准与 Dify 实现的偏差对照

SSE 规范要求	Dify 默认行为（v0.10.x–v1.0.1）	兼容性风险
Content-Type: text/event-stream + cache-control: no-cache	部分部署缺失 header，或被 Nginx/CDN 缓存覆盖	触发浏览器强制缓冲，阻断实时流
data: {"answer":"..."}\n\n（严格双换行）	混入 event: message、id: 123、空行、未转义双引号	OpenWebUI 的 EventSource 解析器崩溃
仅允许 data: 字段携带有效载荷	插入 event: tool_thinking、event: agent_step 等非 message 类型	OpenWebUI 未注册对应 event handler → 抛出 unhandledrejection

三、架构层：全链路缓冲与代理瓶颈定位

典型部署拓扑中，SSE 流需穿越多层中间件：

OpenWebUI (EventSource)
      ↓ HTTPS
[Nginx] → [Dify API Gateway] → [Dify Backend (FastAPI)]

关键缓冲点排查清单：

• Nginx：必须启用 proxy_buffering off;、proxy_cache off;、chunked_transfer_encoding on;
• Uvicorn/Gunicorn：需设置 --timeout-keep-alive 65 防止连接过早关闭
• 云 WAF（如 Cloudflare）：默认禁用 SSE，需开启 Streaming Response 特性并放行 text/event-stream

四、代码层：Dify 响应标准化改造方案

在 Dify 的 chat_router.py 中，对流式响应做协议净化：

def format_sse_chunk(data: dict) -> str:
    # 强制 JSON 序列化 + 双引号转义（规避 data: {"msg":"a\"b"} 解析失败）
    json_str = json.dumps(data, ensure_ascii=False).replace('"', '\\"')
    return f"data: {json_str}\n\n"

# 过滤非 message 事件（兼容 OpenWebUI 语义）
if event_type != "message":
    continue  # 跳过 tool_thinking / agent_step 等

五、验证层：端到端连通性诊断流程图

graph TD
  A[OpenWebUI 发起 /chat/chat SSE 请求] --> B{Nginx Header 检查}
  B -->|缺失 text/event-stream| C[添加 proxy_set_header Content-Type text/event-stream]
  B -->|存在 proxy_buffering| D[设置 proxy_buffering off]
  C --> E[捕获原始响应流 curl -N]
  D --> E
  E --> F{是否每 chunk 以 data: 开头？}
  F -->|否| G[定位 Dify 后端 event: xxx 输出位置]
  F -->|是| H[检查 data: 行是否含未转义 JSON]
  G --> I[重写 response_stream middleware]
  H --> I
  I --> J[OpenWebUI 控制台无 error & 消息连续]

```