大模型流式输出如何避免半截 JSON：增量缓冲、括号配对与最终校验

流式返回让界面更快看到模型输出，但它也带来一个很具体的坑：上一片刚好停在 {"items":[，调用方就急着解析，得到的不是“模型答错”，而是一个尚未传完的 JSON。稳妥的处理方式是先把分片按顺序放入增量缓冲器，用字符串状态和括号深度判断是否具备尝试条件，最后仍交给标准解析器和业务校验。

不要把“当前分片能否解析”当成流式 JSON 的成功条件；只有完整候选通过标准 JSON 解析，并且必填字段、类型和数量约束都通过，才可以交给业务层。

先把分片边界和 JSON 完整度分开

网络层可能把一个 UTF-8 字符串拆成多片，模型事件也可能把一个 JSON 字符串拆在任意位置。比如下面三片拼起来才是完整值：

{"items":[{"id":1,"title":"缓存"}]}
分片1: {"items":[{"id":1,
分片2: "title":"缓
分片3: 存"}]}

因此，接收循环只负责处理事件顺序和结束状态，不应该在每个分片上直接反序列化。若把解析错误当成模型错误，重试会制造重复请求；若把半截对象写入缓存，后续读者还可能拿到缺字段的结果。

用增量状态判断何时值得尝试解析

下面的最小状态机只关心四个真实状态：AppendChunk 把新文本追加到缓冲区，braceDepth 记录对象和数组嵌套，inString 记录当前是否位于 JSON 字符串中，candidateReady 表示括号已经归零且当前不在字符串内。

type JSONTracker struct {
    buf            strings.Builder
    braceDepth     int
    inString       bool
    escaped        bool
    candidateReady bool
}

func (t *JSONTracker) AppendChunk(chunk string) {
    t.buf.WriteString(chunk)
    for _, r := range chunk {
        if t.escaped {
            t.escaped = false
            continue
        }
        if t.inString && r == '\\' {
            t.escaped = true
            continue
        }
        if r == '"' {
            t.inString = !t.inString
            continue
        }
        if t.inString {
            continue
        }
        if r == '{' || r == '[' {
            t.braceDepth++
        } else if r == '}' || r == ']' {
            t.braceDepth--
        }
    }
    t.candidateReady = t.braceDepth == 0 && !t.inString && t.buf.Len() > 0
}

这里的 braceDepth 是“括号深度”，不是合法性证明。多一个右括号会让深度变成负数，非法转义也可能让字符串状态失真，所以生产代码还应限制最大深度、单次输出长度和累计缓冲区大小。

为什么括号出现在字符串里不能参与配对

字段值可能是 "说明：数组 [a] 暂不展开"。如果扫描器不区分 inString，这两个方括号会被误算成结构括号。反斜杠也不能简单跳过一个字节：\\" 中的引号是字符串内容，真正结束字符串的是未被转义的引号。

候选完整后仍要走标准解析器

当 candidateReady 变为 true，只说明可以尝试一次完整解析。RFC 8259 要求 JSON 生成结果符合 JSON 语法，而解析器必须接受符合语法的文本；括号扫描器无法覆盖数字格式、Unicode 转义、重复键策略和额外尾随内容这些细节。

type ModelResult struct {
    Items []struct {
        ID    int    `json:"id"`
        Title string `json:"title"`
    } `json:"items"`
}

func DecodeResult(t *JSONTracker) (ModelResult, error) {
    var result ModelResult
    if !t.candidateReady {
        return result, errors.New("candidate is incomplete")
    }
    if err := json.Unmarshal([]byte(t.buf.String()), &result); err != nil {
        return result, err
    }
    if err := ValidateResult(result); err != nil {
        return result, err
    }
    return result, nil
}

如果上游使用事件流，还要把正常结束、主动取消和传输失败区分开。传输失败时即使缓冲区看起来已经闭合，也不应绕过结束状态检查；否则“恰好收齐但连接报错”的边界会被误判为成功。只有这些检查都通过，结果才进入 accept，而不是停留在候选缓冲区。

业务验收要检查字段而不是只看 err

ValidateResult 应该是独立函数，方便单测覆盖空数组、未知字段、超长标题和重复 ID。别用“能反序列化”代替“可入库”：Go 会把缺失字段留成零值，这正是最容易漏掉的半成品。

生产发布前的四个检查点

1. 记录每次追加后的缓冲区长度、braceDepth 和结束状态，但不要在日志里直接输出包含隐私的完整模型结果。
2. 用括号出现在字符串、转义引号、数组嵌套和 Unicode 字符中的样例测试 AppendChunk。
3. 分别模拟正常结束、传输失败和主动取消，确认只有正常结束才进入 DecodeResult。
4. 让 ValidateResult 拒绝空标题、重复 ID 和超长数组，并确认失败不会污染成功缓存。

常见问题：流式 JSON 的边界怎么处理

括号深度归零后就能直接入库吗？

不能。它只代表候选文本值得交给标准解析器；解析、字段类型和业务规则都通过后才可以入库。

解析报错要不要立刻重试模型？

先判断是否仍在接收、连接是否正常以及是否已收到结束事件。半截分片不是模型质量问题，立刻重试可能造成重复请求；明确的完整 JSON 语法错误，才适合按幂等策略决定是否重试。

为什么不直接等最后一个分片再解析？

可以把最终解析放在结束事件之后，但增量状态仍有价值：它能提前发现深度异常、限制缓冲区增长，并为界面展示“正在等待完整对象”提供依据。

把半成品挡在业务边界之外

流式输出的速度和结构化结果的可靠性是两件事。接收层按顺序累计，增量状态只负责判断完整度，标准解析器负责语法，ValidateResult 负责业务可用性；这四层职责分开后，半截 JSON 就不会伪装成一次成功响应。真正需要优化时，再围绕缓冲区上限、取消回收和失败重试做压测，而不是牺牲最后一道校验。