2026年流式输出大模型API 示例代码怎么写：首字返回与分片拼接处理

2026年流式输出大模型API 示例代码怎么写：首字返回与分片拼接处理

流式输出写不出来，通常不是接口不支持，而是分片边界没处理对，或者首字被中间层缓冲挡住了。

把“读取、解析、拼接、渲染”拆成四步分别处理，代码会清爽很多，出问题时也更容易定位到具体环节。

到大模型 API 里，stream 基本已经是标配参数。但真正动手写的时候，很多人会卡在两处：一是等了很久一个字都不出来，怀疑接口没生效；二是偶尔蹦出乱码或者半句话丢失，看起来像模型出了问题。这两类现象其实都指向同一件事——流式响应不是一个“完整 JSON”，而是一连串需要自己拼起来的文本片段。

一、流式输出的数据到底长什么样

打开 stream 之后，服务端返回的内容类型通常会从 application/json 变成 text/event-stream。它不是一次性给你一个完整对象，而是持续吐出一行行的文本块，每行以 data: 开头，块与块之间用空行分隔，最后发一条结束标记表示本次生成完毕。

data 行、空行与结束标记

理解三个符号就够了：data: 前缀说明这一行是有效载荷；空行表示一个事件结束；[DONE] 表示流已经关闭。真正需要额外注意的，是任意一行都可能只承载一部分内容——一个完整 JSON 对象可能被拆到两三个网络分片里传过来。所以正确的做法不是“收到一行就解析”，而是“先按行缓冲，凑够一行再解析”。这一条判断错了，就会看到大量 JSON 解析失败，或者内容凭空少一段。

二、示例代码怎么写

先从最小可用版本开始，跑通再考虑封装成 SDK。下面这段 Python 代码只做三件事：带 stream 参数发请求、按行读取、遇到结束标记就停。

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {"model": "omni-1.1", "stream": True,
           "messages": [{"role": "user", "content": "写一段产品说明"}]}

with requests.post(URL, headers=headers, json=payload,
                   stream=True, timeout=(10, 120)) as r:
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        data = line[5:].strip()
        if data == "[DONE]":
            break
        print(data, flush=True)

几个关键点值得单独说：stream=True 必须显式打开，否则请求会等到全部生成完才返回；timeout 写成元组形式，分别控制连接超时和读取超时，流式场景下读取超时要给得比普通请求更宽松；iter_lines 负责按行切分，避免自己处理纠结的换行边界。

分片拼接要处理的三个细节

• 按行缓冲，不要按固定字节长度切割，否则会把一条 data 行从中间劈开。
• 多字节字符可能与网络分片边界重合，务必使用增量解码方式，避免出现乱码或问号。
• 保留一个尾部缓冲：最后一段如果没有以换行结尾，要留到下一个分片再一起解析。
• 解析失败时不要直接抛出中断整个流，先记录原始片段再跳过，方便事后复盘。
• 结束时统一收尾，把缓冲区里剩余的内容处理完再关闭连接。

三、首字返回慢，先查这四件事

首字延迟是流式体验里最影响观感的一项。如果用户等三五秒还看不到任何变化，会直接认为系统卡死了。排查时可以按顺序检查：请求是否真的带了 stream 参数；响应是否被反向代理或网关整体缓冲；输入内容是否过长导致首 token 迟迟不出现；客户端是否在读取到第一段内容后没有立即刷新输出缓冲。

判断流式是否真的生效，最直接的方法是在收到第一段内容时立刻打印时间戳。如果首字距离发起请求超过数秒，问题多半在链路或输入长度上，而不是模型能力上。

四、把配置和日志统一起来

流式代码本身不复杂，真正麻烦的是多环境、多模型下的配置漂移：接口地址改了一处忘了另一处，模型名称在某套环境里写法不同，Key 权限不一致。通联AI中转站 提供 OpenAI 兼容方向的统一接入方式，可以把 Base URL、API Key 和模型选择收敛到同一套配置里，减少在不同平台之间来回切换的成本。实际可用的模型和接口写法，请以控制台中显示的实时信息为准。

在联调阶段，建议把每次请求的首字耗时、总耗时、结束原因都记进日志。等到线上出现异常时，这些字段能帮你快速区分是链路问题、参数问题还是内容问题。需要查看模型清单和接口说明时，可以到 通联AI中转站官网 的控制台里核对。

如果你正在给产品接入流式输出，可以先在通联注册账号，用控制台给出的接口地址和模型名称跑通一段最小示例代码，再逐步补上分片拼接、增量解码和超时处理。

注册通联AI中转站并测试流式调用