LLM 返回的 JSON 有问题？试试 json-repair!

和 LLM 打交道时，如果你了解一些 Prompt Engineering 的技巧，应该知道我们很多时候需要让模型进行结构化输出，结构化输出相比纯文本有很多优势，我们可以通过程序自然地解析、使用其中的数据。而在众多结构化格式中，JSON 是一个非常理想的选择。它带来了诸多好处，比如：

• 格式统一：每次返回都是预期的结构，极大地方便了后续的数据处理和消费
• 减少幻觉：要求模型生成固定格式的数据，能在一定程度上约束模型，减少随意“编造”无关内容的可能性
• 关系清晰：JSON 的嵌套结构天然地体现了数据之间的层次和关联
• 类型明确：字段是字符串、数字还是布尔值一目了然，便于直接在应用程序中使用

笔者最近在用 Python 开发 AI 相关服务时，就深刻体会到了让 LLM 返回 JSON 的便利。然而，实践中也遇到了一个令人头疼的问题：LLM 本质上是概率模型，即使你在 Prompt 中反复强调、明确要求（比如叮嘱它生成的 JSON 必须能json.loads成功解析），它有时还是会输出格式错误的 JSON。常见的翻车情况为：

• 缺少闭合的大括号}或方括号]
• 字符串值中的双引号没有被正确转义 (\”)，导致解析中断
• 多了或少了必要的逗号

这些问题不仅影响程序解析，还经常导致整个流程中断。起初，我以为只能通过不断调整 Prompt、增加 Retry 机制来曲线救国。但后来读到 Google 出的《Prompt Engineering 白皮书》时，注意到里面提到了一个工具 ——json-repair，用于自动修复 LLM 输出的非法 JSON！它的出现，大大降低了处理这类 Bad Case 的心智负担和代码复杂度。

于是我对这个库进行了深入研究，并整理了这篇文章，希望能帮到遇到同样困扰的你。

什么是json-repair

json-repair是一个修复无效 JSON 的 Python 库。

值得一提的是，这是一个相对较新的库。作者在 Readme 中明确提到，开发它的初衷正是为了解决 LLM 返回 JSON 格式不规范的问题——这与我们的需求不谋而合。

库的功能如下：

1. 修复 JSON 中的语法错误

• 处理缺失的引号、错误放置的逗号、未转义字符、不完整的键值对等问题。
• 修正缺少引号、不规范的值（如 true、false、null），以及损坏的键值结构。
• 修复格式错误的 JSON 数组和对象
• 通过添加必要的元素（如逗号、括号）或默认值（如 null、空字符串 ""）来补全不完整或破损的数组/对象。
• 支持处理包含额外非 JSON 内容（如注释或错误字符）的 JSON，清理后保证结构有效。
• 自动补全缺失的 JSON 值
• 自动为缺失的字段补充合理的默认值（如空字符串 "" 或 null），确保最终生成合法的 JSON。

为了修复损坏的 JSON，json-repair 内部实现了一个基于 BNF的简单解析器。它按照以下语法规则来理解和修复 JSON：

<json> ::= <primitive> | <container>

<primitive> ::= <number> | <string> | <boolean>
; Where:
; <number> is a valid real number expressed in one of a number of given formats
; <string> is a string of valid characters enclosed in quotes
; <boolean> is one of the literal strings 'true', 'false', or 'null' (unquoted)

<container> ::= <object> | <array>
<array> ::= '[' [ <json> *(', ' <json>) ] ']' ; A sequence of JSON values separated by commas
<object> ::= '{' [ <member> *(', ' <member>) ] '}' ; A sequence of 'members'
<member> ::= <string> ': ' <json> ; A pair consisting of a name, and a JSON value

上手json-repair

使用非常简单，就是一个函数：repair_json，你可以通过官方提供的 Playground 实验一下 https://mangiucugna.github.io/json_repair/。

这里我们以未转义正确转义双引号的 JSON 为例（LLM 很容易返回这种 JSON 结构）：



可以看到，repair_json函数成功地将未转义的双引号修复为\"，使得后续的json.loads调用能够顺利进行。请注意：repair_json 返回的仍然是一个字符串，你需要再次使用json.loads或类似的库将其转换为 Python 对象。

注意，虽然json-repair非常强大，但也不是万能的，如果 JSON 字符串的损坏程度非常高，例如完全丢失了根对象的括号或是结构极其混乱以至于无法推断出原始意图，那就无法修复了，另外json-repair是一个后处理工具，用于抢救有问题的输出。它不能解决 LLM 产生格式错误JSON的根本原因。最佳实践仍然是结合优秀的 Prompt Engineering 和可能的模型微调，来尽量提高原始输出的质量。

json-repair的优势在于：它提供了一个通用、健壮且专注于修复的解决方案。它不依赖特定的 Prompt 或模型，而是直接处理输出字符串，尝试将其恢复为标准的、可被 json.loads 等标准库解析的格式。它作为现有流程（Prompt优化、模型选择）的一个补充，提供了一层可靠的保障。

Benchmark

为了验证json-repair 在实际应用中的效率，我进行了一个简单的 Benchmark 测试。 测试设置：输入 1000 条轻微损坏的 JSON 字符串，模拟常见的 LLM 输出错误，然后测量json-repair对于不同类型的 JSON 修复的耗时情况。



从测试结果来看，repair_json的性能表现非常出色：

• 总体性能极佳：每秒能处理近 20,000 条破损 JSON，平均每条处理时间只有 0.088 毫秒，说明这个库在大规模数据处理场景下非常高效。
• 稳定性良好：标准差为 0.16 毫秒，相对较小，表明处理时间的波动不大，性能稳定可预期。
• 扩展性强：
• 处理长度增加时（从短到长），处理时间从 0.049 毫秒增加到 0.259 毫秒
• 处理复杂度增加时（从简单到复杂），处理时间从 0.049 毫秒增加到 0.159 毫秒（虽然时间随复杂度增加而增长，但增长幅度是可控的，即使最复杂的情况下依然保持毫秒级处理速度）
• 错误类型处理均衡：不同类型的 JSON 错误（引号错误、括号不匹配、多余逗号、未转义引号等）处理时间相当，都在 0.08-0.09 毫秒左右，没有明显的性能瓶颈点。

repair_json经过了良好的优化，即使面对复杂的 JSON 破损情况，也能保持高性能。与许多需要正则表达式或复杂解析的解决方案相比，它的性能表现值得肯定。

总结与建议

在开发涉及 LLM 的应用时，强烈建议大家尽可能地让模型输出结构化数据，尤其是 JSON 格式。这不仅能有效降低模型产生幻觉的风险，还能显著提高返回数据的可靠性和下游程序的可操作性。

然而，由于 LLM 的内在机制，即使精心设计了 Prompt，输出的 JSON 仍有一定概率存在瑕疵。因此，在工程实践中，引入像repair_json这样的库，对 LLM 的输出进行自动化的健壮性处理，是一个非常务实且高效的做法。

从实际测试和使用来看，repair_json 具有修复成功率高、处理速度快的优点，非常值得在各类需要处理 LLM 输出 JSON 的系统中考虑集成，作为一道可靠的保险。