大模型 API 接入怎么配置流式输出

文章导读
流式输出的配置重心不在请求参数上,而在链路上:请求里通常只要打开一个流式开关,真正决定你能不能逐字看到内容的,是客户端怎么读、中间的网关和反向代理有没有把返回数据攒起来、以及流结束时怎么收尾。任何一层做了整包缓冲,用户看到的效果都是“卡很久,然后一大段文字一次冒出来”。
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

流式输出的配置重心不在请求参数上,而在链路上:请求里通常只要打开一个流式开关,真正决定你能不能逐字看到内容的,是客户端怎么读、中间的网关和反向代理有没有把返回数据攒起来、以及流结束时怎么收尾。任何一层做了整包缓冲,用户看到的效果都是“卡很久,然后一大段文字一次冒出来”。

适用场景:对话类接入,回答较长,需要首字尽快出现。操作动作:先用 curl -N 直连服务端,确认接口确实分块返回;再在代码里打开流式字段,用支持增量读取的客户端逐帧解析;最后逐层检查网关、反向代理、CDN 是否关闭缓冲。验证方式:观察首个数据帧到达的时间、帧与帧之间是否连续、末尾是否有明确的结束标记。风险边界:流式下的用量统计、结构化输出、错误返回都和非流式不同,需要单独处理;链路不支持流式时建议回退整包返回,不要用前端假打字掩盖问题。

先确认当前场景和目标

先确认服务端接口本身支持流式。多数对话类接口用 stream: true 这类布尔字段开启,返回格式常见为 SSE(text/event-stream),但字段名、帧结构、结束标记三者各服务商差异很大。接入前需要从对方接口约定里拿到这三样信息:用什么字段开启流式、每个数据帧里的增量内容放在哪个路径、流用什么标记结束。只照抄别人示例里的字段名,很容易出现请求成功但没有增量返回的情况。

再确认客户端运行环境能否增量读取。浏览器里 EventSource 只支持 GET,带不上自定义鉴权头,需要 POST 的场景建议改用 fetch 读 response.body 的流;Node 侧要看能否拿到响应体的流对象;Python 用 requests 时必须显式写 stream=True,用 httpx 时走 client.stream,否则库默认把响应读完才返回,看起来就像没有流式。

最后一层判断是:当前任务是否真的需要流式。要求严格 JSON 输出、需要 schema 校验、或者是后台批处理任务,流式带来的收益有限,反而增加拼接与异常处理成本。如果只是前端想要逐字出现的观感,也可以先拿整包再逐字渲染,但要分清楚这是链路真流式还是视觉假流式,两者的超时设置和错误处理不一样。

按这个顺序处理

处理顺序建议从最靠近服务端的一层往外推,逐层验证,别一上手就改前端。

大模型 API 接入怎么配置流式输出

第一步,用命令行直连确认服务端行为。下面是一个通用请求骨架,地址、模型名、字段名按你的服务商约定替换:

curl -N -X POST "https://你的服务地址/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "你的模型名",
    "stream": true,
    "messages": [{"role": "user", "content": "用三句话解释什么是幂等"}]
  }'

-N 的作用是关掉 curl 自身的输出缓冲。如果终端里是分多次逐行冒出 data: 帧,说明服务端流式正常;如果一次性刷出全部内容,问题在服务端或更前置的一层,先别往下走。

第二步,在应用代码里解析数据帧。下面是一段可替换的解析骨架,重点在按行读取、遇到结束标记就跳出、增量字段按服务商结构取:

import json, requests

resp = requests.post(url, headers=headers, json=payload,
                     stream=True, timeout=(5, 120))
resp.raise_for_status()

for raw in resp.iter_lines(decode_unicode=True):
    if not raw:
        continue
    line = raw.strip()
    if not line.startswith("data:"):
        continue          # 忽略空行、注释行、event: 行
    data = line[5:].strip()
    if data == "[DONE]":
        break
    chunk = json.loads(data)
    delta = chunk["choices"][0]["delta"].get("content") or ""
    if delta:
        print(delta, end="", flush=True)

生产代码里这段解析要补两件事:json.loads 包在 try 里,单帧解析失败跳过而不是整条流崩掉;把外层函数做成可取消的,用户点停止时主动关闭连接,否则连接会挂到超时。

大模型 API 接入怎么配置流式输出

第三步,处理中间层缓冲。如果直连正常、经过自己的网关后变成一次性返回,基本可以定位到反向代理或 CDN。Nginx 一类代理需要显式关掉缓冲并放宽空闲超时:

location /v1/ {
    proxy_pass http://your_upstream;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 120s;
    chunked_transfer_encoding on;
}

另外要确认接口路径没有被缓存规则或 WAF 的响应聚合策略覆盖。云厂商网关、Serverless 函数入口、部分 CDN 默认会聚合小响应,需要按其配置项单独关闭。

第四步才是前端渲染。浏览器侧用 fetch 读流、按分隔符切帧,边收边追加到消息节点,并在流结束后统一触发一次 Markdown 渲染,避免每个增量都重排整个文档。

改完后怎么验证

验证要分层做,不要只看最终页面效果。

大模型 API 接入怎么配置流式输出
  • 命令行层:重跑前面的 curl -N,观察输出是否为多行陆续出现,最后一帧是否为约定的结束标记。这一步排除服务端和网络问题。
  • 应用层:在解析循环里打印每帧到达的时间戳和内容长度,确认帧间隔是连续分布,而不是先静默若干秒再来一大批。同时检查用量字段是否只在末尾帧出现,如果不是,统计逻辑要相应调整。
  • 链路层:绕过自己的网关直连一次,再走网关请求一次,对比两者首帧到达时间。差异明显说明缓冲还开着。
  • 异常层:在流进行到一半时主动断网或让上游返回错误,确认客户端能收到非正常结束并给出提示,不会一直转圈。

预期信号是:首个增量在可接受的等待后出现,后续增量持续推进,结束时收到明确终止信号且连接被正常关闭,日志里没有残留的长连接。若只有“内容最终正确”但过程是一次性到达,说明流式没有真正生效,仍需回到第二步和第三步排查。

容易忽略的边界

流式形态下几个地方和非流式不一样,接入时容易踩到。用量与计费字段通常只出现在最后一个数据帧或独立的收尾事件里,中途中断就拿不到完整统计,需要按已收到的内容自行估算并做好对账口径。错误不一定以 HTTP 4xx/5xx 返回,可能以流内的错误事件出现,客户端要同时处理状态码和流内错误两种路径。

结构化输出与工具调用在流式下是分片返回的,参数可能被拆在多个帧里,必须累积拼接后再解析,不能对单帧做校验。反向代理、负载均衡、客户端读超时各自的空闲超时阈值不一致时,长回答容易在中途被某一层掐断,需要按最短的那个阈值统一配置。

不适用或需要回退的情况也很明确:网关或函数计算入口不支持流式透传、客户端运行环境拿不到流式响应体、或者业务要求严格的完整 JSON 一次校验,这几种场景建议直接回到 stream: false 的整包返回,用较短的回答和合理的超时来保证体验,而不是在前面套一层假流式。另外,不要把流式响应写入共享缓存,缓存层会截断或重复返回增量内容。