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

严格解析器对坏输入是零宽容的:只给你一条报错和一个行号,一个字节的数据都不给。修复器存在的意义,就是把「完全失败」变成「先跑起来再说」——但它补出来的东西永远只是对意图的最佳猜测。
一、坏 JSON 从哪来:三个来源,问题高度集中
修复不是全能的,先看输入是什么。工程里非标准 JSON 的来源集中在三处:
- LLM 输出。模型逐 token 生成文本,并不运行 JSON 序列化器。即使要求「只输出 JSON」,它也会包一层
```json围栏、加一句「好的,这是你要的数据」、落下尾逗号,或者命中 token 上限停在对象中间。 - 从别的语言复制。
console.log打出来的 JavaScript 对象带单引号和不带引号的键;Python 字典打出来是True/False/None;这些「长得像 JSON」的文本一喂给JSON.parse就炸。 - JSON5/JSONC 配置。tsconfig 这类文件允许注释和尾逗号,拷出来直接给严格解析器同样拒收。
三类来源的修法不同,但修复器都能覆盖——前提是错误落在它声明的可修清单里。
二、九类可修:修复器真正擅长什么
综合 jsonrepair 库文档与各家工具页的能力声明,可自动修复的错误可以归纳为九类:
| 类别 | 坏输入示例 | 修复结果 |
|---|---|---|
| 尾逗号 | [1, 2, 3,] |
[1, 2, 3] |
| 单引号 / 弯引号 | {'a': 'b'}、{"a": "b"} |
{"a": "b"} |
| 未加引号的键 | {name: 'Ada'} |
{"name": "Ada"} |
| 注释 | {"a": 1 /* 说明 */} |
{"a": 1} |
| Python 字面量 | {"ok": True, "v": None} |
{"ok": true, "v": null} |
| markdown 围栏 | ```json {...} ``` |
{...} |
| 缺失逗号 | [1 2] |
[1, 2] |
| 括号 / 引号未闭合 | {"a": [1, 2 |
{"a": [1, 2]} |
| JSONP / 字符串拼接 | cb({...})、"x" + "y" |
{...}、"xy" |
这九类的共同点是:数据都在,只是语法不对。修复器只需要调整标点和包装,不改任何值。有几条细节值得单独记住:
- 前导零数字会被转成字符串:
007修复成"007"而不是7,为的是不丢数字位。如果你的字段本来就是文本编号,这是正确行为;如果它真是数字,得自己决定。 - 裸词会被变成字符串:
NaN修不成数字,有的实现直接变"NaN",有的变null。不同库行为不同,接进管线前先试一遍。 - 输入已是合法 JSON 则原样返回:修复器都内置严格解析快路径,合法输入不经过修复逻辑,不存在「越修越坏」。
三、四类不能修:信任边界的另一侧
修复器的能力边界同样明确,下面四类别指望它:
- HTML 错误页或纯散文。输入里根本没有 JSON 结构,没有任何工具能凭空造出数据。
- 语法合法但数据错误。键拼错、值放错位、数字存成字符串——这些是语义问题,语法层面完全合法,任何修复器都会放行。
- 截断丢掉的数据。截断补全能把
{"items": [{"id": 1}, {"na修成合法 JSON,但name字段的值永远不会回来。修出来的是「合法但不完整」的对象,生产环境必须先查stopReason === "max_tokens"再决定是补全还是重试。 - 重复键与歧义结构。两个同名键哪个生效取决于解析器实现,负责任的修复器提供 strict 模式直接抛错而不是静默二选一。
一句话总结信任边界:修复是「最佳猜测」,不是「正确保证」。修完不校验就进下游,等于把语法风险换成了更隐蔽的数据风险。
四、实现两派:状态机与正则的差别,一个 URL 就能试出来
市面修复器有两种实现流派,能力差距在特定输入上会立刻显形。
正则替换派对坏模式做全局查找替换。考虑这个输入:
{"url": "http://example.com", 'note': 'fine'}
一条「把单引号换双引号」的正则会把 URL 里的内容一起处理;一条「删掉所有 //」的注释清理正则会把 http:// 腰斩。字符串内部和结构外部长得一模一样,正则区分不了。
逐字符状态机派维护一个解析状态:当前在双引号字符串内、单引号字符串内、行注释内、块注释内,还是在等值。看到 ' 时先判断自己在不在字符串里,再决定是转引号还是跳过。http://example.com 位于双引号字符串内,状态机知道里面的 // 是数据不是注释,原样保留。jsonrepair、json-healer 这类库都是这一派,社区教程里反复强调的「修复器不是查找替换」说的就是这件事。
修复管线的完整次序(以 devkits 披露的链路为例)也值得看一眼:剥围栏 → 弯引号规范化 → 提取首个配平块 → 去注释 → 补键引号 → 去尾逗号 → 字面量转换 → 最后用 JSON.stringify 重序列化。最后一步重序列化是关键:不管前面怎么修,输出都从解析结果重新生成,保证下游任何严格解析器都能吃。
五、代码里怎么接:一条顺序化的解析链
在代码里接修复,顺序比选库更重要。按 json2toon 与 aijsonmedic 给出的模式整理,顺序应该是:截断检查 → 提取 JSON 区间 → 严格 parse → repair 兜底 → schema 校验。
import { jsonrepair } from "jsonrepair";
export function parseModelJson(text, stopReason) {
if (stopReason === "max_tokens") {
// 截断的输出修复出来也是缺数据的,直接重试
throw new Error("Truncated output: retry with a higher max_tokens");
}
// 提取 JSON 区间:LLM 可能在前后加寒暄
const start = text.search(/[[{]/);
const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
try {
return JSON.parse(candidate); // 合法输入走快路径
} catch {
return JSON.parse(jsonrepair(candidate)); // 兜底修复
}
}
Python 侧对应 json-repair 包,4700+ star,loads() 直接返回对象:
from json_repair import repair_json
import json
broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}
两个工程细节:
- 双栈对齐。前后端都要修时,选同源语义的实现(Python json-repair 与它的 TS 移植
@yarmu/json-repair,或双端通过同一一致性语料的 jsonmend),否则同一段输出在前端修成 A、在后端修成 B,问题会更难查。 - 开启修复日志。
@yarmu/json-repair的logging: true返回每次修复操作的数组。线上修复率突然升高,通常意味着提示词或模型版本变了——这是比报错更早的信号。
修复之后还有一步不能省:schema 校验。语法修好不等于数据可用,缺字段、类型错、多出来的键都要靠 schema 抓。契约测试的思路完全适用于这里,参见《JSON Schema 契约测试怎么做》。
六、预防清单:能不修就不修
修复是兜底,源头少产出坏 JSON 才是上策。按优先级排:
- Structured Outputs(json_schema 模式):解码阶段就按 schema 约束,尾部逗号根本生成不出来。OpenAI 的 strict 模式失败率约 0.1%,代价是
additionalProperties: false等硬性要求。 - JSON mode(json_object):只保证语法合法,不保证形状,token 上限导致的截断依然存在。
- 显式指令:没有 JSON mode 的端点,写明「不要围栏、不要注释、不要尾逗号、只输出对象」能降 70-80% 的错误率。
- 降低 temperature、加大 token 上限:前者减少跑偏成散文的概率,后者减少截断。
- 带报错的重试:校验失败时,把坏输出和「JSON path + 报错」一起回传给模型再要一次,模型通常能据此自纠。
实践中「structured outputs + repair 兜底 + schema 校验」三层叠着用,几乎没有修不住的场景。
七、在线工具怎么分工:方言转换不等于修复
本站工具箱在这条链路里有两个落点,各管一段:
- **方言类问题(注释、单引号、尾逗号)**直接用 JSON5 转换:JSON5 与标准 JSON 互转正好覆盖这三类,转换语义明确、不猜测。如果输入整体就是一份 JSONC/JSON5 文件,这比「修复」更可控。方言本身的取舍见《JSON5 与 JSONC 指南》。
- 修完之后用 JSON 解析工具校验并格式化,错误定位到行列,确认修复结果真的能被严格解析器接受。
- **库类问题(Python 字面量、截断补全、JSONP 包装、markdown 围栏)**目前得靠代码侧的 jsonrepair / json-repair,浏览器端没有等价的一键修复——这两类修复涉及「推断意图」,交给本地库比塞进通用转换工具更稳。
如果拿到手的是一段报错而不是一段坏数据,先去《JSON 解析报错怎么修》把报错翻译成坐标,再决定是手改还是修复。
常见问题
JSON 修复会把我的数据改坏吗?
九类可修错误只动标点和包装,不动值;字符串内部的 //、逗号、花括号由状态机识别,原样保留。但截断补全得到的对象缺数据,前导零数字会变成字符串,NaN 的处理各库不同——修复后检查关键字段是必要动作。
修复和校验是什么关系?
校验只告诉你「哪里不合法」,修复直接给出「一份合法的」。可靠的做法是两个都做:先修复再校验,schema 校验抓类型与必填字段,语法校验确认解析器能吃。只修不校验,等于把语法错误换成更隐蔽的数据错误。
LLM 输出总是被 ```json 围栏包着,怎么办?
短期用提取:取首个 { 或 [ 到最后一个 } 或 ] 之间的内容再解析;带围栏剥离的修复器也能直接吃整段输出。长期靠 structured outputs 或显式指令「不要 markdown 围栏」,从生成阶段就避免。
jsonrepair 和 json-repair 选哪个?
JS 栈用 npm 的 jsonrepair(支持流式 transform),Python 栈用 PyPI 的 json-repair。前后端都要修就选语义同源的组合,比如 json-repair 加它的 TS 移植,保证同一输入两侧修复结果一致。
修复器能处理中文和弯引号吗?
能。中文输入法打出来的弯引号(“”)和全角空格、文件开头的 BOM 都在常见修复清单里,弯引号会被规范化成直引号。修复后用校验器过一遍即可确认。