流式上线后，「不好用」通常被描述成同一句话：卡。但卡有三种完全不同的成因，修法也完全不同——连接根本没建立、内容吐到一半停了、反向代理把整段攒完才给。用同一种办法（比如「把缓冲全关」）去治三种病，只会让其中一种好转，另外两种照旧。

这一节用时间戳把三类分开，再给一张「先查哪一层」的顺序表。

一、问题不是「流卡了」，而是「卡在哪一段」

要区分三类，只需要四个观测值：

• 首 token 时间：从发出请求到收到第一条增量。
• chunk 间隔分布：相邻增量之间的时间差。
• 是否见到 [DONE]：终止信号有没有到。
• chunk 总数：有没有任何增量。

四个值组合起来，三类故障的指纹很清楚：

故障	首 token	chunk 间隔	[DONE]
连接层卡住	极晚或没有	无	无
静默截断	正常	正常后突然停止	通常没有
代理缓冲	很晚	之后非常密集	有

所以定位的第一步不是改配置，是把时间戳记下来。

二、最小可运行示例：流健康诊断器

下面的脚本不联网、不需要真实密钥。它接收一段已经采集好的时间数据，判断属于哪一类中断。

"""流健康诊断：用首 token 时间、间隔分布与终止符区分三类中断。"""

from dataclasses import dataclass, field

@dataclass
class StreamTrace:
    first_token_s: float | None      # 首条增量的到达时间；None 表示没有
    chunk_gaps: list[float] = field(default_factory=list)
    total_s: float = 0.0
    chunks: int = 0
    saw_done: bool = False

def diagnose(t: StreamTrace) -> str:
    if t.chunks == 0:
        return "无任何增量：先查连接与超时，不怀疑模型"
    longest = max(t.chunk_gaps) if t.chunk_gaps else 0.0
    if t.first_token_s is not None and t.first_token_s > 10 and longest < 0.5:
        return "首 token 很晚但之后密集：像缓冲攒够才吐，优先查代理"
    if not t.saw_done:
        return "未收到 [DONE]：判定为截断，记录最后一条事件"
    if longest > 30:
        return "中途长间隔后恢复：像连接重试，核对是否重复计费"
    return "流完整"

def offline_check() -> None:
    cases = [
        ("正常", StreamTrace(0.8, [0.1, 0.1, 0.1], 1.1, 4, True)),
        ("缓冲", StreamTrace(12.0, [0.05, 0.05], 12.2, 3, True)),
        ("截断", StreamTrace(0.5, [0.1, 0.1], 0.7, 3, False)),
        ("无增量", StreamTrace(None, [], 30.0, 0, False)),
        ("长间隔恢复", StreamTrace(0.8, [0.1, 35.0, 0.1], 36.0, 3, True)),
    ]
    for name, t in cases:
        print(name + "：" + diagnose(t))

if __name__ == "__main__":
    offline_check()

真正上线时，把采集点放在消费循环里：收到第一条带 content 的事件记首 token 时间，每条事件记一次时间戳，循环结束时把 saw_done 与 chunks 一起带出来。诊断器只做判断，不做重试。上面三个阈值（10 秒、0.5 秒、30 秒）是判据形状，不是标准值；按你的网关、模型与网络实测调整。

三、三类故障的定位顺序

故障	典型现象	优先怀疑	第一步动作
连接层卡住	连接在，但一条增量都没有	超时、网络、鉴权	打印首 token 时间，核对客户端超时
静默截断	有内容，但停在半句、没有 [DONE]	上游断开、超时截断	记录最后一条事件与总时长
代理缓冲	很久不吐，之后一次给完	反向代理、CDN	看首 token 与间隔分布是否「晚而密」

三件要强调的事：

• 推理模型要显式覆盖超时。官方 Streaming 页专门提示：推理模型的流式输出可能很长，建议手动提高请求超时，避免连接被提前关闭。默认短超时会把「正常但慢」误判成「卡住」。
• 缓冲要逐层验证，不要一刀切。应用服务器、反向代理、CDN 都可能缓存响应；正确做法是逐层用同一段请求对比首 token 时间，找出是哪一层在攒。直接「关掉所有缓冲」既可能无效，也会影响其他接口。
• 截断与重试要分开处理。截断时已经收到的内容仍有价值，应该保留并标记「不完整」；如果直接用重试结果覆盖，用户会看到答案忽然变短或前后矛盾（重连策略见 6.4）。

四、预期输出与异常分支

运行诊断器，预期输出：

正常：流完整
缓冲：首 token 很晚但之后密集：像缓冲攒够才吐，优先查代理
截断：未收到 [DONE]：判定为截断，记录最后一条事件
无增量：无任何增量：先查连接与超时，不怀疑模型
长间隔恢复：中途长间隔后恢复：像连接重试，核对是否重复计费

换成真实流量时，若诊断结果与体感不符，按下面顺序复核：

现象	优先怀疑	第一步动作
判成「完整」但用户说卡	采集点位置不对	把时间戳打在收到事件处，不是打在上层回调
一会儿缓冲一会儿正常	多实例路由不一致	按实例聚合首 token 时间
截断频繁但日志无错	异常被吞	在消费循环末尾显式记录退出原因
长间隔后仍有内容	连接重试	对照请求数，确认是否重复计费

最后一行尤其重要：长间隔后「自己好了」，最容易被当成运气。它可能是底层重连成功，而重连意味着同一段内容可能被请求了两次——这直接连到 6.4 的重放问题。

五、判据卡

判断项	该这么做	不该这么做
定位顺序	先看时间戳分布，再怀疑模型	一上来换模型或调参数
超时设置	推理模型显式覆盖超时	用默认短超时
缓冲排查	逐层对比首 token 时间	直接关掉所有缓冲
截断处理	保留已收内容并标记不完整	用重试结果直接覆盖
结论依据	用采集数据说话	凭体感判断

这张卡的重点是先分层再修。四类现象里「判成完整但用户说卡」和「一会儿缓冲一会儿正常」常常同源：采集点或实例维度不对，表现一个是误判一个是波动，但修法都在观测上。

六、来源与核验

• 官方 Streaming 页：https://docs.x.ai/developers/model-capabilities/text/streaming（核验日期 2026-11-04）。SSE 事件结构、stream: true、推理模型建议手动覆盖请求超时的提示，均以该页为准。
• 三类故障的划分与诊断代码为本书原创的工程框架；第三方排障文章中的相似提法仅用于确认这是共性问题，本节不转述其段落、不引用其结论。
• 反向代理与 CDN 的具体缓冲参数因部署而异，请以你自己的网关文档为准；本节不给通用配置值。

七、动手试

1. 给 StreamTrace 加一个 first_event_s（第一条任意事件的时间）与 first_content_s（第一条正文增量的时间），比较两者差值。想一想：这个差值变大更可能说明缓冲，还是说明推理变长？
2. 用同一段请求分别直连与经过你的网关各跑一次，记录首 token 时间。若差异显著，说明缓冲在哪一层？
3. 设计一条「截断」的用户提示：在不谎称完整的前提下，告诉用户答案可能不全，并给出继续的方式。写出你会保留哪些已收内容、丢弃哪些。