跳到主要内容

流式响应

AISIX AI 网关可以向期望 Server-Sent Events 的客户端流式返回代理响应。流式响应不会改变网关职责：AISIX 仍会认证调用方 API Key、解析模型别名、应用受支持策略，并将请求转发到选中的上游服务提供方。

流式端点会保留各路由面向客户端的流格式，但网关策略可能影响投递。

本指南将发送一次 OpenAI 兼容流式请求，并说明不同端点族中的流式行为差异。

准备工作​

请先准备以下内容：

  • 一个可以处理代理请求的 AISIX 网关。
  • 一个可以访问该模型别名的调用方 API Key。
  • 一个由支持流式响应的服务提供方和模型支撑的模型别名。

导出网关连接和请求值：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

发送流式请求​

请求会将 model 值保持为 AISIX 模型别名，并要求上游流式返回响应：

curl -sS -N -X POST "${AISIX_PROXY}/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Stream a short greeting."}
    ]
  }'

响应是 OpenAI 风格 SSE 流。直接 HTTP 客户端会看到类似下面的 data: 帧：

data: {"id":"***","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}

data: [DONE]

OpenAI 兼容 SDK 会通过其常规流式 API 读取同一个流。

选择流式响应路径​

请选择与客户端响应格式匹配的代理端点：

客户端格式代理路径行为
OpenAI 兼容聊天/v1/chat/completions为 OpenAI 兼容 SDK 和直接 SSE 消费者返回 OpenAI 风格 SSE 分片。
Anthropic Messages/v1/messages返回 Anthropic 风格 SSE 事件。提供该路由的上游原生流式返回，其余上游通过转换实现流式返回。
OpenAI Responses API/v1/responses返回 Responses SSE 事件。提供该路由的上游原生流式返回，其余上游通过 Responses 桥接实现流式返回。

哪些上游可以原生流式返回，按服务提供方密钥逐个决定，见声明 API 协议面。

请以客户端格式作为选择依据，不要只因为上游服务提供方变化就切换到 /v1/messages 或 /v1/responses。

Chat Completions 音频输出是一个例外。AISIX 会在完整的非流式响应中保留 message.audio，但目前不会保留流式 delta.audio 分片。请保持使用 Chat Completions 输入和输出音频的请求为非流式；如需增量双向音频，请使用 Realtime API。

查看流式行为​

AISIX 接受请求并选定目标后才会开始流式返回。如果客户端在响应中途断开流，网关仍会保持健康，并继续处理后续请求。

流式 Chat Completions 不会被缓存。即使存在缓存策略，每个流式请求也都会调度到上游。

对于多目标模型，在任何流式字节发送给客户端之前，AISIX 可以重试或故障转移。一旦字节已经到达客户端，选中的上游就继续负责该流，AISIX 不会再切换目标。

如果启用了输出安全护栏，AISIX 可能会根据端点和安全护栏策略暂存、扫描或终止流式输出。对于 Chat Completions 和 Messages 流，被阻断的输出可以通过终止 SSE 错误事件表示，而不是正常完成流。对于 Responses API 流式响应，AISIX 可以先缓冲流内容进行策略检查，再决定返回或阻断。

当上游在流式响应中途断开时，除非特定端点的客户端契约另有说明，否则应将部分流视为未完成。

如果没有收到分片，请确认请求包含示例中的流式标志，并确认客户端按 Server-Sent Events 方式读取。对于 Responses API 流式响应，请检查选中的服务提供方是否支持转换后的请求形态。

如果流提前结束，请检查上游服务提供方状态、网关日志以及已配置的流式超时。

当模型尚未生成任何内容时，网关每隔 downstream.sse_keepalive_interval_secs（默认 15 秒）发送一条 SSE 注释，避免客户端与网关之间的代理将首 Token 较慢的模型视为已放弃连接。符合规范的 SSE 客户端会忽略这些注释。参见调整下游连接层。

下一步​

你已经了解 AISIX 不同端点族之间的流式行为差异。主要 OpenAI 风格路径请参见 OpenAI 兼容 API。Anthropic 风格事件请参见 Anthropic 风格 Messages API。流式错误和响应头请参见响应头与错误码。