BroadRouter

大模型返回的 JSON 不合法怎么办:原因、修复与重试

BroadNet Inference 团队 · 阅读约 7 分钟 · 发布于 · 更新于

先检查 finish_reason:在 max_tokens 处被截断的回复无法安全修复,应提高上限后重发。否则就去掉代码块围栏和前后的文字,解码第一个 JSON 值,只修复尾随逗号这类没有歧义的错误。再按 schema 校验,失败就把确切的错误发回去,重试一到两次。在支持的服务商上,结构化输出能从源头避免大部分问题。

你的代码对模型回复调用 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

每一步的作用:

  1. 截断和空回复在任何解析之前就抛出异常,所以永远不会变成数据。
  2. 围栏和思考内容用两个正则表达式去掉。
  3. raw_decode 是关键工具。Python 文档说它从 “from a string that may have extraneous data at the end”(译文:末尾可能带有多余数据的字符串)中解码一个文档,并返回停止的位置。从第一个 { 或 [ 开始,它跳过对象前面的文字,忽略后面的文字。如果文字里的某个括号解码失败,就尝试下一个。
  4. 括号扫描逐字遍历文本,跟踪字符串和转义。括号没有闭合,说明回复被截断了,即使 finish_reason 没这么说;此时抛出异常。字符串之外、紧挨在 } 或 ] 前的逗号会被删除。
  5. ast.literal_eval 读取使用单引号、True 和 None 的 Python 风格输出。它只求值字面量,绝不执行代码。结果还必须能序列化为严格的 JSON。
  6. 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。提示词和回复在每次请求后都不会被保留。

常见问题

为什么大模型返回的 JSON 包在 markdown 代码块里?

对话模型习惯为人类读者排版代码,而代码块围栏正是聊天界面展示代码的方式。可以要求“只输出 JSON,不要代码块”,但代码里仍然要去掉围栏:这条指令只能降低出现的概率,不能杜绝。

大模型输出报 JSONDecodeError,怎么修?

先看 finish_reason。如果是 "length",说明回复被截断了:提高 max_tokens 后重发。如果不是,就去掉代码块围栏,用 raw_decode 解码第一个 JSON 值,它会忽略后面的文字。修掉尾随逗号,然后校验。仍然失败就带上错误信息重新请求。

应该用 JSON 修复库吗?

用于日志和调试,可以。用于你要据此行动的数据,要小心。json_repair 这类库会用默认值补全缺失值,于是被截断的城市名 "Jed" 会作为合法的 "Jed" 返回。应该拒绝被截断的输出并重新发送。

为什么大模型输出的 JSON 被截断了?

回复触及了 max_tokens。在 DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 这类思考模型上,思考过程计入这个上限,思考一长,留给回答的空间就不够了。可以提高上限、把 reasoning_effort 设为 low,或者让每次调用少输出一些。

JSON 模式能保证输出合法 JSON 吗?

基本可以。OpenAI 表示 JSON 模式的输出是合法 JSON,"except for in some edge cases"(译文:某些边缘情况除外),比如触及 token 上限;而且它不会强制执行你的 schema。使用 json_schema 的结构化输出在服务商强制执行时,还能保证遵循 schema。无论哪种都要校验。

BroadNet 的哪些模型支持结构化输出?

截至 2026 年 11 月 15 日查阅,BroadNet 的 API 参考为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出。DeepSeek V4.1 Flash 和 Gemma 4 VL 26B 没有列出,所以在这两个模型上请用只靠提示词的 JSON,再加修复和校验。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity