SGLang的JSON Mode并不是一种“保证每次输出都是合法JSON”的魔法，它通常是通过约束解码（例如基于Outlines的语法约束）限制每一步token生成，使其只能落入符合上下文无关文法的序列。也就是说，它能把输出限制在“近似JSON”的结构里，但并不能保证结果一定可以被json.loads解析。生产环境中更容易遇到非法JSON的原因是：输出在达到max_tokens时被截断、schema定义与生成内容不匹配、约束解码在部分后端版本下未完全生效，或用户传入的json_schema本身不合法。因此，正确的处理思路不是指望框架永远不犯错，而是把schema校验、解析失败捕获和重试/修复策略一起做成容错链路。

处理非法JSON的关键边界：先用schema校验拦截结构性问题，再用异常捕获兜住截断和解析错误。不要把约束解码当作无限保险，max_tokens截断和schema不匹配是主要风险。建议代码层同时处理“无法解析”和“解析成功但不符合schema”两种失败，并设置显式的重试或降级策略。

先判断：非法JSON是“结构非法”还是“语义非法”

JSON Mode的“非法”通常分两类：第一类是连JSON解析器都无法通过的，例如多出一个逗号、引号未闭合、键名缺少引号、输出截断成半个字符串。第二类是可以解析但不符合你预先定义的字段名或类型，比如要求completion字段是字符串，实际返回了数组。SGLang的约束解码能显著降低第一类错误，有时也会引起第二类错误——因为约束解码只保证词法结构，不保证语义上“每个字段都按你的schema来”。处理时必须区分：如果json.loads直接抛异常，走修复或重试；如果解析成功但schema校验失败，则要重新生成或调整提示词。

schema约束配置：确认参数并验证效果

不同版本的SGLang暴露JSON模式的方式有差异，常见的是在生成调用中传入类似json_schema或structured_outputs的参数。建议先在本地写一个最小验证脚本，确认你手头的版本是否真正启用约束解码。不要只看文档，要跑一次带冲突schema的测试。例如在schema中把一个字段定义成object，但在提示词中明确要求模型返回字符串，然后观察输出是否违反schema。如果约束生效，模型应该不会生成非法的object结构；如果仍然出现，则说明当前调用方式可能没有真正传入schema。

# 通用接入骨架，具体参数名以当前API为准
# 目标：验证约束是否生效
schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "count": {"type": "number"}
    },
    "required": ["title", "count"],
    "additionalProperties": False
}

resp = engine.generate(
    prompt="返回一个JSON，title是abc，count是5，再多给一个多余字段extra",
    json_schema=schema  # 如果版本不支持，换成structured_outputs试试
)
try:
    data = json.loads(resp)
    print("parse ok", data)
except json.JSONDecodeError as e:
    print("parse failed", e)

运行后观察：如果resp严格遵循schema，不会包含extra字段；如果包含extra字段，说明约束未生效或参数名不对。注意，即使first解析成功，也需要用jsonschema.validate再检查一次，因为json.loads只保证语法合法。

异常捕获与恢复：不要只靠一个裸try

当非法JSON出现时，最实际的策略是分成三个层次：解析失败、schema校验失败、业务层字段缺失。解析失败时，如果输出长度已超过预设的max_tokens，大概率是截断，此时直接增加max_tokens或让模型重新生成即可；如果长度未到限制仍然截断，则可能是约束解码与生成逻辑冲突，需要调整schema或提示词。对于解析失败，还可以尝试用json.JSONDecoder.raw_decode从尾部逐步裁剪修复，但这个方法只适合“输出后面多了一点解释文字”的场景，对真正截断的JSON不适用。

# 一个可试的解析兜底：先完整解析，再尝试提取首个JSON对象
def parse_partial_json(text: str):
    import json
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass
    decoder = json.JSONDecoder()
    i = 0
    while i < len(text):
        if text[i] in '{[':
            try:
                obj, end = decoder.raw_decode(text, i)
                return obj
            except json.JSONDecodeError:
                i += 1
        else:
            i += 1
    return None

这个函数的意义不是保证修复所有坏JSON，而是让你在失败后至少能拿回一个“部分对象”用于日志或人工接管。使用后必须自行判断返回值是否可信：如果输出只是一个截断的assistant消息，提取出来的内容很可能是残缺的，不能直接当作最终结果。更稳妥的做法是：捕获异常后，把错误文本和schema一起送回模型，要求它只输出修正后的JSON，并设置较低温度。

诊断清单：从环境到配置逐项排查

确认约束解码是否真正生效

测试用例里显式要求模型输出一个不在schema中的额外字段；如果输出里出现了，说明参数没生效，不是异常捕获的锅。

确认max_tokens没有设置得太小

先手动估算最坏情况下JSON的长度，再设置max_tokens至少比估算值大20-30%。截断是非法JSON最常见的成因。

确认schema本身是合法的JSON Schema

用本地jsonschema库对schema做一次校验，不要手写容易出错的复杂结构，尤其是additionalProperties和required组合。

确认生成参数没有破坏约束解码

某些参数如top_k、top_p、presence_penalty可能会干扰约束解码的停止规则，不同版本有差异。在开JSON Mode时优先使用默认生成参数，再逐步调整。

确认业务层能够容忍失败

把重试次数限制在1-2次，并在每次重试中显式附加错误信息，这样模型才知道要修正什么。不要无限重试，否则遇到系统性问题时会白白消耗算力。

最后，把这些逻辑封装成一个统一的post-processing函数：先解析，再校验schema，最后判断必填字段是否存在。如果任意一步失败，就抛出带有解码错误内容的自定义异常，这样上层调用方才能根据失败类型决定是重试还是返回稳健的默认值。把约束解码当作“降低错误率”，而不是“消除错误”，异常捕获和解耦补偿仍然要保留。