你的代码对模型回复调用 json.loads(),结果报出 JSONDecodeError: Expecting value: line 1 column 1。又或者解析通过了,但本该是数字的字段却是字符串。本文按“各自能安全做什么”给这些原因分类,提供一个经过测试、只修复无歧义情况的 Python 函数,并给出一个知道何时重试也无济于事的重试循环。
在 JSON 模式和 json_schema 之间怎么选,见 JSON 模式与 json_schema。本文讨论的是:拿到手的回复该怎么处理。
大模型为什么会返回不合法的 JSON?
模型一次写一个 token。除非服务器约束了解码,否则没有什么能阻止它多加一句客套话,或者写到一半没了空间。常见的失败情况:
| 你看到的 | 原因 | 能在代码里安全修复吗? |
|---|---|---|
```json … ``` 包住对象 |
聊天排版习惯 | 能:去掉围栏 |
| 前面有“Here is the JSON:”,后面有“Let me know…” | 同样的习惯 | 能:只读取第一个值 |
对象前面有 <think>...</think> |
某些服务器把思考文本放进了 content 字段 | 能:删除这段内容 |
| 在字符串中间结束,括号没闭合 | 触及 max_tokens |
不能:给足空间重新发送 |
| content 为空 | 思考用完了全部预算 | 不能:给足空间重新发送 |
{"a": 1,} |
尾随逗号;JavaScript 允许,RFC 8259 不允许 | 能:含义唯一 |
{'a': True, 'b': None} |
Python 语法 | 能:ast.literal_eval 可以安全读取 |
NaN、Infinity |
不是 JSON;Python 默认接受 | 不能:拒绝 |
| 合法 JSON,但类型错误或缺字段 | schema 未被强制执行 | 不能:带上错误重新请求 |
分界线在于有没有歧义。如果模型想表达的意思只有一种可能,就在代码里修复,并记录你修了什么。如果你得靠猜,就拒绝这个回复。
为什么不修复被截断的 JSON?
因为修复后的版本看起来没问题,实际上却是错的。我们用 json_repair 0.64.9(一个流行的 MIT 许可库)处理一个在单词中间被截断的回复:
'{"name": "Omar", "city": "Jed' -> {'name': 'Omar', 'city': 'Jed'}
它返回了合法的 JSON,城市是 “Jed”。它的 README 对此毫不隐瞒:它 “automatically completes missing values in JSON fields with reasonable defaults”(译文:会自动用合理的默认值补全 JSON 字段中缺失的值)。这对读日志很有用。但对于你要存储或据此行动的数据,它把一个显而易见的失败变成了悄无声息的失败。
解析之前先检查 finish_reason。"length" 表示回复触及了 max_tokens。用同样的上限重发同样的请求,会以同样的方式失败,所以要把上限翻倍,或者让每次调用少输出一些。思考模型让这种情况更常见:BroadNet 的 API 参考说明,DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考再回答,而思考计入 max_tokens。上限太小时,回答可能为空。请留出 1,000 个或更多 token,或者把 reasoning_effort 设为 low;具体数字见思考预算一文。
一个只修复安全情况的修复函数
它只用标准库。它返回解析后的值,以及它做过的修复列表,方便你统计。
import ast, json, re
class Truncated(Exception): pass
class NotJSON(Exception): pass
FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)
def _reject_constant(name): # NaN, Infinity: Python accepts them, JSON does not
raise NotJSON(f"non-standard constant {name}")
_decoder = json.JSONDecoder(parse_constant=_reject_constant)
def _first_value(s):
"""Decode the first JSON object or array in s, ignoring prose before and after it."""
for i, ch in enumerate(s):
if ch in "{[":
try:
return _decoder.raw_decode(s, i)[0]
except json.JSONDecodeError:
continue # a stray brace in prose; try the next one
raise NotJSON("no JSON object or array found")
def _scan(s):
"""Drop commas before } or ] outside strings; report brackets left open."""
out, stack, in_str, esc = [], [], False, False
for i, ch in enumerate(s):
if in_str:
if esc:
esc = False
elif ch == "\\":
esc = True
elif ch == '"':
in_str = False
elif ch == '"':
in_str = True
elif ch in "{[":
stack.append(ch)
elif ch in "}]" and stack:
stack.pop()
elif ch == ",":
rest = s[i + 1:].lstrip()
if rest[:1] in ("}", "]"):
continue # trailing comma: skip it
out.append(ch)
return "".join(out), len(stack) + (1 if in_str else 0)
def _python_literal(s):
"""Output in Python syntax: single quotes, True/False/None, trailing commas."""
start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
end = max(s.rfind("}"), s.rfind("]"))
if start < 0 or end <= start:
raise NotJSON("no braces")
value = ast.literal_eval(s[start:end + 1]) # literals only; never runs code
if not isinstance(value, (dict, list)):
raise NotJSON("not an object or array")
json.dumps(value, allow_nan=False) # must round-trip as strict JSON
return value
def parse_llm_json(content, finish_reason=None):
"""Return (value, repairs). Raises Truncated or NotJSON."""
if finish_reason == "length":
raise Truncated("hit max_tokens; raise the limit or shorten the output")
if not content or not content.strip():
raise NotJSON("empty content (reasoning may have used the whole budget)")
repairs = []
s = content.strip().lstrip("\ufeff")
if THINK.search(s):
s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
m = FENCE.search(s)
if m:
s = m.group(1).strip(); repairs.append("removed code fence")
try:
value = _decoder.decode(s)
return value, repairs
except json.JSONDecodeError:
pass
try:
value = _first_value(s); repairs.append("ignored text around JSON")
return value, repairs
except NotJSON:
pass
fixed, open_count = _scan(s)
if open_count:
raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
if fixed != s:
try:
value = _first_value(fixed); repairs.append("removed trailing commas")
return value, repairs
except NotJSON:
pass
try:
value = _python_literal(s); repairs.append("parsed Python-style literal")
return value, repairs
except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
raise NotJSON(f"unrepairable: {e}") from None
每一步的作用:
- 截断和空回复在任何解析之前就抛出异常,所以永远不会变成数据。
- 围栏和思考内容用两个正则表达式去掉。
raw_decode是关键工具。Python 文档说它从 “from a string that may have extraneous data at the end”(译文:末尾可能带有多余数据的字符串)中解码一个文档,并返回停止的位置。从第一个{或[开始,它跳过对象前面的文字,忽略后面的文字。如果文字里的某个括号解码失败,就尝试下一个。- 括号扫描逐字遍历文本,跟踪字符串和转义。括号没有闭合,说明回复被截断了,即使
finish_reason没这么说;此时抛出异常。字符串之外、紧挨在}或]前的逗号会被删除。 ast.literal_eval读取使用单引号、True和None的 Python 风格输出。它只求值字面量,绝不执行代码。结果还必须能序列化为严格的 JSON。NaN和Infinity通过parse_constant抛出异常。Python 的json默认接受它们;RFC 8259 说它们 “are not permitted”(译文:不被允许),JavaScript 的JSON.parse也会拒绝。
我们用 17 个测试字符串运行了它:干净的 JSON、带围栏的 JSON、围栏里带阿拉伯语键和值、前后带文字、对象前的文字里有 {name} 占位符、<think> 块、对象和数组中的尾随逗号、字符串里的逗号和括号、转义引号、以反斜杠结尾的 Windows 路径、Python 字面量、NaN、空回复、带和不带 finish_reason: "length" 的截断回复,以及连续两个对象。结果都与上表所述一致。其中一个测试抓到了一个真实的 bug:早期版本在检查结束引号之前就翻转了转义标志,导致 "he said \"hi,]\"" 丢了逗号。请用转义引号测试你自己的修复代码。
有两个限制需要知道。连续出现两个对象时,它返回第一个;如果你需要多个条目,请让模型输出一个 JSON 数组。另外,单引号的 Python 输出如果在字符串里含有双引号,可能被括号扫描误读而遭到拒绝。拒绝是安全的失败方式。
修复失败后应该怎么重试?
修复解决的是格式问题。校验解决的是内容问题:字段对不对、类型对不对、值是否合理。下面的循环用 jsonschema 包做校验,并根据原因选择重试方式:
import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON
client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
"required": ["name", "city", "amount"],
"properties": {"name": {"type": "string", "minLength": 1},
"city": {"type": ["string", "null"]},
"amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)
def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
"Schema: " + json.dumps(SCHEMA)},
{"role": "user", "content": text}]
for attempt in range(1, attempts + 1):
r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
reasoning_effort="low", temperature=0)
c = r.choices[0]
try:
value, repairs = parse_llm_json(c.message.content, c.finish_reason)
errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
if not errors:
log({"attempt": attempt, "repairs": repairs, "ok": True})
return value
problem = "The JSON does not match the schema: " + "; ".join(errors)
except Truncated:
log({"attempt": attempt, "ok": False, "why": "truncated"})
max_tokens *= 2 # same prompt, more room; a re-ask would be cut off too
continue
except NotJSON as e:
problem = f"That reply was not valid JSON ({e})."
log({"attempt": attempt, "ok": False, "why": problem})
messages += [{"role": "assistant", "content": c.message.content or ""},
{"role": "user", "content": problem + " Return the corrected JSON object only."}]
raise RuntimeError(f"no valid JSON after {attempts} attempts")
这个循环里的规则:
- **被截断:用加倍的上限重发相同的消息。**再加一条“请修正”的消息只会让提示词变长,输出却不会变短。
- 不是 JSON,或结构不对:把确切的错误发回去。“amount: ‘1200’ is not of type ‘number’”给了模型一个具体要改的地方。不带信息的重试往往会重复同样的错误。
- **最多尝试三次。**每次重试都会把整段对话作为输入 token 重新发送。三次之后,记录输入并转交其他流程处理。
- **记录修复列表。**改了提示词之后,“removed code fence”的次数不断上升,说明提示词变差了,即使并没有任何失败。
我们在一个回放预设回复的本地模拟服务器上运行了这个循环。一个带围栏、有尾随逗号、并且 "amount": "1200" 是字符串的回复被修复,校验失败,在把错误发回后的第二次调用中得到修正。一个带 finish_reason: "length" 的截断回复,在 max_tokens 从 1,500 提高到 3,000 后重发并成功。模拟服务器每次都记录了请求,确认了循环发送的消息数量和上限。真实模型的失败方式可能不同,所以在信任这些数字之前,先用你自己的 100 条输入跑一遍。
有了结构化输出,这些就不需要了吗?
大部分都不需要了。把解码约束在你的 schema 上的服务器,不可能输出围栏、尾随逗号或缺失字段。常用的开源模型服务器 vLLM 通过 xgrammar 或 guidance 后端实现这一点。但即便如此,仍有两种失败:在 max_tokens 处截断,以及拒绝回答。OpenAI 指出,JSON 模式的输出是合法的,“except for in some edge cases”(译文:某些边缘情况除外),而且你的应用 “must detect and handle”(译文:必须检测并处理)不是完整对象的输出。所以即使用 json_schema,也要保留 finish_reason 检查和校验器。
各方法能防止什么:
| 方法 | 围栏和多余文字 | 语法错误 | 结构不对 | 截断 |
|---|---|---|---|---|
| 只靠提示词(“用 JSON 回复”) | 减少 | 减少 | 减少 | 否 |
JSON 模式(json_object) |
是 | 是 | 否 | 否 |
结构化输出(json_schema,强制执行) |
是 | 是 | 是 | 否 |
对于 JSON 模式,OpenAI 还说你 “must always instruct the model to produce JSON”(译文:必须始终指示模型输出 JSON),要写在某条消息里;否则它可能一直输出空白字符,直到触及 token 上限。其他 OpenAI 兼容服务器的情况各不相同,所以要在你要上线的模型上测试这个模式。测试方法见结构化输出一文。
想手动检查某个回复,可以粘贴到大模型 JSON 输出校验器里,或者用 JSON schema 生成器从示例对象生成严格的 schema。
BroadNet Inference 适合什么场景
BroadRouter 是 BroadNet 的网站。BroadNet 的 API 参考只为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出,并且没有写明请求参数名,所以在依赖它之前,先在模型上测试 json_schema。在 DeepSeek V4.1 Flash 和 Gemma 4 VL 26B 上,请用只靠提示词的 JSON,再加上上面的修复函数和校验器。四个模型中有三个会先思考再回答,所以要为此预留 max_tokens。批量提取请看批处理运行器一文,其中演示了如何逐条记录 finish_reason。提示词和回复在每次请求后都不会被保留。
