OpenAI Compatible SSE 流式输出接入与排错

流式响应改变了什么

非流式请求会等完整响应生成后再返回。流式请求则在模型生成内容时持续发送事件。OpenAI 的 HTTP 流式接口使用服务器发送事件（SSE）；Responses API 与 Chat Completions 的事件结构不同。

流式测试前先验证 Key 和模型

先请求 GET /v1/models，复制当前 Key 可见的准确模型 ID，再发送一个简短的非流式请求。这样可以先排除认证和模型路由问题，避免把它们误判为流解析错误。

curl -sS https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

2026 年 8 月 3 日，未携带 Key、且请求体包含 stream: true 的生产探测分别请求了 /v1/responses 和 /v1/chat/completions，两者均返回结构化的 401 API_KEY_REQUIRED。这只能证明请求到达认证层，不能证明每个模型都支持已认证流式输出。

用 Python SDK 接收流式事件

官方 Python SDK 支持 stream=True。下面的 Responses 示例只输出文本增量，并单独处理错误事件。

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://monkeytheme.com/v1",
)

stream = client.responses.create(
    model="MODEL_ID_FROM_LIST",
    input="Write one short sentence.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "error":
        print("\nstream error:", event)

如果使用 Chat Completions，应遍历 chunk 并读取 chunk.choices[0].delta.content。请勿用 Responses 事件解析器处理 Chat Completions。

用 Node.js SDK 接收流式事件

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://monkeytheme.com/v1",
});

const stream = client.responses.stream({
  model: "MODEL_ID_FROM_LIST",
  input: "Write one short sentence.",
});

stream.on("response.output_text.delta", (event) => {
  process.stdout.write(event.delta);
});

await stream.finalResponse();

官方 Node SDK 也提供 Chat Completions stream runner，但返回结构不同。迁移时应按接口文档改解析逻辑，不能只替换字段名。

用 curl 查看原始 SSE 边界

curl -N https://monkeytheme.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "MODEL_ID_FROM_LIST",
    "input": "Reply with OK",
    "stream": true
  }'

-N 会关闭 curl 的输出缓冲。如果 curl 能逐条显示事件，而应用只能一次性显示全部内容，应检查应用解析器以及应用和网关之间的代理。

流式响应卡住时检查代理

Nginx 官方文档说明，proxy_buffering off 会在收到上游响应时同步传给客户端；proxy_read_timeout 计算的是两次连续读取之间的等待时间，并非整个响应的总时长。

location /v1/ {
    proxy_pass http://your_upstream;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_read_timeout 300s;
}

按现象定位故障层

资料与相关教程

• OpenAI：流式 API 响应
• OpenAI 官方 Python SDK
• OpenAI 官方 Node.js SDK
• Nginx HTTP 代理模块
• Responses API 与 Chat Completions 对比
• 504 upstream timeout 排错

常见问题