JSON 工具箱

LLM 输出的 JSON 被截断了怎么办:先看停止原因,再谈修复

结论:模型返回的 JSON 少了结尾,解析器只给一个列号,补上括号就能跑——但缺口被藏进了数据里。本文按停止原因判定、输出额度定容、schema 字段排序与部分恢复的诚实披露,划清截断场景下能修与必须重试的边界。

实战约 5 分钟发布于 2026-11-14更新于 2026-11-14
截断 JSON 的栈式闭合示意:字符串感知扫描后按括号栈补全

截断不是语法错误,是数据不完整。语法坏可以修,截断只能恢复一部分——修复器把缺口闭合的那一刻,剩下的缺口就从「解析报错」变成了「没人知道」。

截断长什么样:一个列号救不了你

模型按你的 schema 返回 JSON,生成到一半撞上输出上限,文本戛然而止。用 Python 3.11 的 json 模块实测这样一段输入:

{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"

json.loads 报错是 Expecting ':' delimiter, col 94——列号指向 "qty" 后面缺值的位置,但真正的病因是整个文档没有结尾。同一份输入用贪心正则补一个 "} 闭合,解析直接失败;用字符串感知的栈式闭合(下文第六节)能解析成功,但 items 只剩 2 条,第三条残缺记录被丢弃。报错列号告诉你「哪里断了」,不告诉你「丢了多少」。

这就是截断和普通 JSON 报错的第一个区别:它没有明确的修复终点。尾逗号修完就完整了,截断修完仍然是残本。

截断和语法坏不是一回事:修复器的盲区

修复器(如 jsonrepair)的设计目标是把语法坏的 JSON 变成合法 JSON:剥 markdown 围栏、去尾逗号、单引号转双引号,这些场景里「意图」是完整的,修复只是去污。截断输入在修复器眼里也是「坏 JSON」,于是它同样闭合未完成的字符串、数组和对象,返回一个能通过解析的结果——83 份被截断的 Claude 报告里,修复器"修好"了 79 份,只有 4 份硬失败。错误监控看到的失败率被低估了 20 倍。

修完的结果长什么样?问题 6 的反馈字符串停在半句话,问题 7 到 9 整个消失,next_steps 数组不存在。Pydantic 校验照样通过,因为字段给了默认值 []、列表没有长度约束。每一层都在正常工作,产出是一份自信的错误报告。语法修复的逻辑放进截断场景,就从「去污」变成了「伪造」。

所以边界必须先划清:修复器只该处理完整回答上的格式污渍;被切断的输出不该进修复器。同类的格式污渍怎么修,见本站《JSON 修复指南》。

第一步永远是看停止原因

所有主流 API 都在响应元数据里告诉你为什么停止,这个字段存在且免费,却是最常被忽略的一行代码。Anthropic 是 stop_reason,OpenAI 旧版是 finish_reason,取值 max_tokens 即截断、end_turn/stop 才是自然结束:

resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
    raise TruncatedOutput(
        f"stop_reason={resp.stop_reason}, "
        f"output_tokens={resp.usage.output_tokens}"
    )
data = json.loads(resp.content[0].text)

把截断变成显式异常后,重试路径才有触发条件,监控才有告警源。上面的 83 份报告就是事后从日志里的 stop_reason 字段捞出来的——元数据一直在存,只是从来没人读。同理,length、incomplete 这类取值在 Google 与 OpenAI 的响应里含义相同,接新厂商时先核对这张对照,别靠猜。

max_tokens 不是预算:按最坏情况定额度

截断的直接原因通常是一个为早期产品定的输出上限:1500 token 的 cap 在长会话上线后,39% 的长报告被切断。加额度是免费的——计费只按实际生成的 token 算,4096 的上限对一份实际只用 1100 token 的报告,成本与 1500 的上限完全一样。上限的作用是防止失控输出,不是省钱阀门。

定容方法:上线后观察一周真实的输出分布,取 p99 再留余量。那份事故复盘里的选择是 4096,因为其后实测 p99 是 2350。另一个方向是压缩输出本身:同构数组的键名重复是 token 大头,喂模型前先换成表格化编码(本站《TOON 格式指南》),同样的信息量能省下可观额度,从源头降低撞顶概率。

schema 字段顺序就是截断顺序

模型自上而下写 JSON,输出耗尽时被切掉的永远是 schema 末尾的字段。一份把 scores 放在 per_question_feedback 之后的教学报告 schema,截断时最先丢的就是用户会截图对比的分数。改动只需把属性重新排序:关键且短的字段在前,长而可再生的明细在后,notes 类自由文本垫底。

厂商行为差异也决定了同样截断、不同后果:

厂商 结构化输出方式 截断时的表现
OpenAI response_format + strict: true 采样级保证,但方言最窄;通常直接拒绝生成
Anthropic tool use 的 input_schema 无解码期保证,可能交出未闭合的括号
Gemini responseSchema + JSON MIME 解码期只保证 enum 与类型,截断同样可能发生

所以「开了 structured output 就不用校验」是错觉:约束越松的厂商越要在你这边补一道 schema 校验与重试闭环,契约测试怎么搭见《JSON Schema 契约测试》。

真要部分恢复:字符串感知的栈式闭合

有些场景必须榨出残本——流式展示、降级响应、人工复核。此时修复梯子的最后一级才是闭合操作,且必须满足两个条件。第一,括号扫描必须字符串感知:逐字符维护引号与转义状态,否则值里的 { 会把栈弄乱。第二,残缺的键值对要先删再闭:"qty" 后面没有值时,直接闭合会产生 {"qty"} 这种非法结构,正确做法是整对丢弃。

def close_truncated(s: str) -> str:
    # 1) 字符串感知扫描,截断在字符串内则先补引号
    out, in_str, esc = [], False, False
    for ch in s:
        out.append(ch)
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str
    text = ''.join(out) + ('"' if in_str else '')
    # 2) 删除残缺键值对与悬空冒号/逗号
    text = re.sub(r',\s*"[^"]*"\s*$', '', text)
    text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
    text = re.sub(r':\s*$', '', text)
    text = re.sub(r',\s*$', '', text)
    # 3) 重扫栈,按后进先出补闭合符
    stack, in_str, esc = [], False, False
    for ch in text:
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str; continue
        if not in_str:
            if ch in '{[': stack.append(ch)
            elif ch in '}]' and stack: stack.pop()
    return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))

本机对第六节开头那段输入跑这段代码(Python 3.11、标准库),产出 {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]}——可解析,第三条记录残缺被丢弃。本地模型侧的同类实践用 partial-json-parser 这类专用库,思路相同:按栈补全、按完整性裁剪。

关键在披露:闭合函数必须返回「我是从哪一级修好的」的报告,truncation 级的产物只能标记为部分结果——继续追问缺失范围、提额度重试、或明示用户数据不完整。静默假装什么都没发生,等于用确定性代码制造幻觉。

什么该修、什么必须重试:一张边界表

输入形态 正确动作 原因
围栏包裹、尾逗号、单引号 修复器处理 意图完整,只是语法脏
截断在字符串中间 重试或部分恢复+披露 值本身缺了一截,补不回来
截断在结构中间 部分恢复+披露 能救回已完成字段,残缺对要删
解析通过但语义可疑 业务校验 与截断无关,但常与其并发

中文侧的财务发票案例把代价量化了:长发票被截断后补括号变成合法 JSON,total 字段缺失取默认值 0,格式合规率 98.2% 的系统每月错约 200 张发票;改为截断即降级、加合计恒等校验后,金额错误率从 0.8% 降到 0.02%。盯着「格式合规率」优化三个月,方向从一开始就是偏的——能通过解析器的东西不等于能通过业务的东西。

落地清单四条:解析前先查停止原因;额度按 p99 定容而不是按预算省;schema 关键字段前置;修复器只处理完整回答的格式污渍。四条都做到,截断才会从静默的数据腐蚀变回一个响亮的、可重试的失败。

截断的 JSON 闭合括号后能直接用吗

不能直接用。闭合只保证语法合法,数据仍是残本:被切断的字符串停在半句、末尾记录被丢弃、依赖默认值的字段拿到的不是真实值。正确做法是把闭合产物标记为部分结果,触发重试或降级,并记录恢复率。

怎么判断 JSON 是被截断而不是写错了

看响应元数据里的停止原因字段:max_tokens/length/incomplete 即截断,end_turn/stop 却解析失败才是语法问题。没有元数据的场景可以看文本结尾形态——断在引号或括号中间、最后一级结构未闭合,基本是截断。

为什么修复器会把截断的数据"修好"得更危险

修复器的目标函数是「让解析通过」,截断文档闭合后恰恰能通过,于是错误监控零告警、下游校验有默认值也会放行。83 份截断报告只报错 4 次就是这个机制。修复器没有意图概念,它不知道数据缺了多少,所以截断必须在上游拦截。

max_tokens 调大会不会多花钱

不会。计费按实际生成的 token 数结算,上限只是安全阀门。4096 的上限对实际 1100 token 的输出,账单与 1500 上限完全相同。真正要控制的是失控输出,按 p99 留余量定容即可。

参考资料

同系列工具

相关文章

JSON 修复指南:LLM 坏输出的救回与信任边界

LLM 输出被 markdown 围栏包裹、带着尾逗号和 Python 字面量,手改过的配置少了引号,这些 JSON 严格解析器一概拒收。本文按修复器真实能力划清九类可修与四类不能修的边界,讲状态机与正则两派实现的差别,给出 jsonrepair 与 json-repair 双栈接入顺序,以及修复结果如何用校验器兜底。

实战约 6 分钟更新于 2026-11-08

TOON 格式指南:给 LLM 喂数据前,先把 JSON 瘦下来

把同构数组喂给大模型时,JSON 里重复的键名与括号都在消耗 token。TOON 用缩进对象加表格数组把结构声明一次、数据逐行铺开,官方基准以少约 40% 的 token 换来更高解析准确率。本文讲清语法规则、省 token 的适用边界、何时不该转,以及 encode 与 decode 的接入方式。

入门约 6 分钟更新于 2026-11-10

JSON Schema 契约测试:把校验规则焊进 CI

schema 写完不改就是坏的起点:一个 typo 让校验器静默放行,一次重构让 fixture 全线误报。本文给出一套可落地的契约测试方案——正例、负例、快照三件套,schema 本身先进 lint,编译一次复用,再把四道闸门焊进 CI,让契约坏了构建先红。

实战约 8 分钟更新于 2026-11-05