Python 中的 json_repair 使用教程：轻松修复大模型返回的非法 JSON

为什么大模型生成的 JSON 需要修复

在使用大语言模型（LLM，例如 GPT 系列）时，我们经常要求模型返回结构化的 JSON 数据，以便程序进一步解析和处理。然而，现实中模型输出的 JSON 往往"不够干净"------可能会在前后多出说明文字、注释、甚至中途缺少引号或逗号，从而导致 json.loads() 报错。

一个典型的错误场景如下。

大语言模型在生成 JSON 数据时，可能会出现多种格式问题：

括号不匹配：缺少闭合的括号或方括号

python 复制代码

# 模型可能返回
broken_json1 = '{"活动名称": "旋转木马", "游玩体验": "孩子们玩得非常开心!"'

缺失引号：键或字符串值缺少引号

python 复制代码

broken_json2 = '{活动名称: "旋转木马", "游玩体验": "孩子们玩得非常开心!"}'

缺少逗号：键值对之间缺少分隔符

python 复制代码

broken_json3 = '{"活动名称": "旋转木马" "游玩体验": "孩子们玩得非常开心!"}'

特殊字符未转义：包含未转义的特殊字符
python 复制代码
```
broken_json4 = '{"描述": "这是一个"包含引号"的字符串"}'
```

非 JSON 内容混杂：输出中包含解释性文本或其他非 JSON 内容

python 复制代码

broken_json5 = """
这里是返回的结果：
{
  "name": "Alice",
  "age": 25,
  "city": "New York", // 用户所在城市
}
"""

传统处理方式的局限性

当面对这些有问题的 JSON 时，开发者通常会考虑：

提示工程：优化提示词，明确要求模型输出标准 JSON
多次调用：当第一次返回无效 JSON 时，再次请求模型修正
正则表达式：编写复杂的正则表达式来提取 JSON 部分

然而，这些方法都存在明显缺点：提示工程效果不稳定，多次调用增加时间和 token 消耗，正则表达式编写维护困难且容易出错。

有没有更优雅、更自动化的方式？答案就是 ------ json_repair。

一、什么是 json_repair

json_repair 是一个 Python 库，用于自动修复无效的 JSON 字符串。

它会分析字符串中的结构、引号、括号、逗号等错误，尝试将其纠正为可被 json.loads() 正常解析的合法 JSON。

相比于正则修正或多次调用大模型，json_repair 的优势在于：

无需二次调用模型，执行速度快
可自动修复常见错误，例如：
- 缺少引号
- 结尾多余逗号
- 单引号替换为双引号
- 非法字符混入
- JSON 前后附带额外内容

二、安装方法

使用 pip 安装：

bash 复制代码

pip install json-repair

三、基本用法示例

来看一个实际例子。假设大模型返回了以下内容：

python 复制代码

from json_repair import repair_json
import json

response = """
模型输出：
{
  name: 'Alice',
  "age": 25,
  "city": "New York",
}
"""

# 使用 json_repair 修复
fixed = repair_json(response)

print(fixed)
# 输出:
# {"name": "Alice", "age": 25, "city": "New York"}

# 现在可以正常解析
data = json.loads(fixed)
print(data["name"])  # Alice

json_repair 自动完成了几个修复动作：

为 name 补上了引号
将 'Alice' 转换为 "Alice"
去掉了最后一个多余的逗号
忽略了前面的"模型输出："这段无关内容

四、更复杂的场景

有时，大模型可能在 JSON 前后附带了解释说明，例如：

python 复制代码

response = """
以下是结果：
{
  "status": "ok",
  "data": {
    "id": 123,
    "items": ["apple", "banana"]
  }
}
谢谢！
"""

这种情况下，json.loads() 同样无法直接解析。

而使用 json_repair：

python 复制代码

fixed = repair_json(response)
print(json.loads(fixed))

输出结果：

python 复制代码

{'status': 'ok', 'data': {'id': 123, 'items': ['apple', 'banana']}}

json_repair 能够智能识别出中间那段是完整的 JSON 块，并自动去除多余文字。

五、异常修复与边界情况

json_repair 并非万能。如果输入的内容严重破损，例如括号完全不匹配、结构不完整，它可能无法百分百恢复。

但它会尽力返回"最接近合法 JSON"的结果，而不会抛出异常。

示例：

python 复制代码

bad_json = "{ name: Alice, age: 30"

fixed = repair_json(bad_json)
print(fixed)
# 输出：{"name": "Alice", "age": 30}

六、实战建议

优先尝试 json.loads()，若失败再使用 json_repair。

这样可以避免对原本就合法的 JSON 进行不必要的处理。
python 复制代码
```
try:
    data = json.loads(response)
except json.JSONDecodeError:
    data = json.loads(repair_json(response))
```
结合日志输出，记录修复前后的差异，方便排查模型输出问题。
不建议用于安全敏感场景（例如：直接信任外部输入的 JSON），因为修复过程中会进行字符串推断。

七、总结

当我们依赖大模型生成 JSON 数据时，不可避免会遇到各种格式错误的问题。
json_repair 让我们不再需要反复提示模型"请返回合法 JSON"，也不必浪费 token 进行多轮修正。

一句 repair_json(response)，即可轻松将混乱的字符串变为可用的结构化数据。

它的出现，让 LLM 与后端程序之间的数据对接更稳定、更高效。