Python 调用大模型时如何用结构化输出校验 JSON：从解析失败到可重试

大模型接口返回的内容看起来像 JSON，并不等于它已经是可用数据。真正稳妥的做法是把返回值依次交给 json.loads、字段校验和有限重试；任何一步失败，都先停在边界上，不让半截结果继续污染业务状态。

把模型当成不稳定的外部输入：先解析，再校验，最后才进入业务；重试只解决暂时性格式问题，不能替代明确的失败返回。

为什么“能解析”仍然不代表结果合格

常见失败有两层。第一层是模型输出了 Markdown 代码围栏、前后解释文字或截断字符串，json.loads 直接抛出 JSONDecodeError。第二层是 JSON 语法没问题，但缺少 answer，或者 confidence 变成了字符串。

这两层要分开处理。解析失败说明文本不是 JSON；字段失败说明 JSON 结构不满足本次任务。混成一个“解析失败”提示，下一次请求就很难针对性修正。

先把返回值挡在解析层

下面的 call_model 只是模型调用边界，实际项目可以替换成自己的 SDK。示例故意不依赖厂商专属参数，重点放在返回值进入业务前的检查。

import json
from typing import Any

def call_model(prompt: str) -> str:
    # 这里替换成实际的大模型调用，返回文本
    raise NotImplementedError

def parse_json(text: str) -> dict[str, Any]:
    value = json.loads(text)
    if not isinstance(value, dict):
        raise ValueError("root must be object")
    return value

这一层只做两件事：把文本交给 json.loads，再确认根节点是对象。不要在这里偷偷截取第一个花括号；那样可能把解释文字中的示例对象误当成正式结果。

字段校验要写成业务规则

解析成功后，再把必填字段和类型说清楚。示例要求 answer 是非空字符串，confidence 是 0 到 1 之间的数字；规则不满足就返回明确原因。

def validate_result(value: dict[str, Any]) -> list[str]:
    errors: list[str] = []
    if not isinstance(value.get("answer"), str) or not value["answer"].strip():
        errors.append("answer must be non-empty string")
    confidence = value.get("confidence")
    if not isinstance(confidence, (int, float)) or not 0 

这里没有把未知字段一律判错，因为模型可能附带解释字段。若下游协议要求严格字段集，再增加白名单；关键是让校验规则和真正消费数据的代码保持一致。

校验失败时只重试一次

重试提示应该携带可操作的失败原因，例如“只返回 JSON 对象，不要 Markdown；answer 必须是非空字符串”。解析失败和字段失败都可以进入同一个重试入口，但必须保留 errors，否则排查时只剩一句“模型不稳定”。

def run_once(prompt: str) -> tuple[dict[str, Any] | None, list[str], str]:
    raw = call_model(prompt)
    try:
        value = parse_json(raw)
    except (json.JSONDecodeError, ValueError) as exc:
        return None, [str(exc)], raw
    errors = validate_result(value)
    return (value if not errors else None), errors, raw

def ask_with_retry(prompt: str) -> dict[str, Any]:
    value, errors, raw = run_once(prompt)
    if value is not None:
        return value
    repair_prompt = (prompt + "\n只返回 JSON 对象。修正这些问题：" + "; ".join(errors))
    value, retry_errors, retry_raw = run_once(repair_prompt)
    if value is not None:
        return value
    raise RuntimeError({"errors": retry_errors, "last_raw": retry_raw or raw})

示例设置一次重试上限，是因为格式修复和业务正确性不是一回事。若两次都失败，抛出包含 errors 和 last_raw 的异常，让上层记录请求 ID、模型名和失败原因，再决定是否人工处理。

三个容易被忽略的边界

不要用正则表达式代替 JSON 解析

正则适合检查非常局部的文本，不适合处理转义引号、嵌套对象和数组。先用 json.loads 建立语法边界，再做字段规则判断。

不要无限重试

无限重试会放大费用和延迟，也可能把同一个错误不断写进日志。把重试次数作为配置，但默认从一次开始，并区分格式错误、超时和服务端错误。

不要把置信度当成事实证明

confidence 只是模型输出的一个字段，不能替代检索、规则或人工复核。下游仍要根据业务风险决定是否接受结果。

把结果交给业务前的验收清单

• json.loads 失败时，记录原始文本和异常类型。
• 根节点、必填字段、字段类型和数值范围都有明确规则。
• 重试提示包含本次真实的 errors，且次数有上限。
• 最终失败不会写入订单、知识库或其他持久化状态。

相关问题

模型总是返回 Markdown 代码围栏怎么办？

先在提示中要求只输出 JSON，并在解析失败时把该次错误带入一次修复请求。不要默认剥离围栏后继续用，因为围栏外可能还有解释内容。

什么时候应该使用 JSON Schema？

当字段较多、嵌套较深，或多个服务需要共享同一份结构约束时，可以把规则集中成 JSON Schema；小型脚本用显式 Python 校验函数通常更容易读和调试。

结构化输出的核心不是让模型“保证正确”，而是把不确定性关在调用边界内。解析、校验、一次修复和最终失败四个状态都留痕，业务代码才能只接收经过验收的数据。