JSON有效≠符合契约：五个免费模型迷思与通过率探测

凌晨两点，一名工人死亡。负载解析正常。起初没人相信这个警报。

这个差距——解析与符合契约——正是许多免费模型流水线悄悄断裂的地方。我在评审讨论中反复看到同样的五种说法。每一种都能在一小时内验证。

迷思一：json.loads 通过就是遵循了模式

不。你有两道门，大多数团队只装了第一道。

• 门A——解析：这段文本到底是不是一个JSON值？
• 门B——契约：这个值是否匹配你的模式：必需键、类型、枚举、模式匹配、无多余字段？

一个响应可以通过A却在B上以十几种方式失败。{"ticket_id": 4411} 解析得干干净净，但它违反了 ^TCK-\d{4,}$ 模式。多一个 "notes" 键也能解析，却违反了 additionalProperties: false。

JSON有效性是语法问题，契约符合性是合同问题。只有后者才是你真正要面对的麻烦。

JSON Schema 是描述和验证 JSON 文档结构的标准（IETF draft），其核心关键字包括 type、required、properties、additionalProperties、enum、pattern 等。文章中的门B本质上就是执行一次 JSON Schema 校验。需要区分的是：json.loads 只检查 RFC 8259 规定的语法，而模式校验检查语义约束。另外，additionalProperties: false 这类约束有一个常见陷阱——它默认 properties 中未列出的字段都算多余，如果模型返回了训练数据中常见的 "confidence" 或 "reason" 字段，就会被判失败，这类失败往往不是模型能力问题，而是契约设计过严，需要和模型输出习惯对齐。

迷思二：返回一个干净对象，模型就可靠

一个只跑一次就通过的测试套件，你会叫它演示，不是套件。

一次调用给出的是 n=1，那是带大括号的轶事。你需要的是通过率以及围绕它的置信区间。二十次试验能让你对符合性给出一个站得住脚的下界。一次试验只能让你在站会上讲个故事。

所以问那个不舒服的问题：下界是多少，不是平均值？

Wilson 得分区间是比例估计中常用的置信区间方法，相比正态近似（Wald 区间），它在小样本和极端比例（接近0或1）下表现更稳健，不会产生越界或宽度为零的区间。文章代码中的 wilson 函数即实现该方法。理解其含义很重要：当 20 次试验中 17 次通过时，点估计是 0.85，但 95% 下界约为 0.62——这意味着真实通过率可能低至 0.62。决策表按下界排序，正是因为下界是对“最坏合理情况”的保守估计，适合在评审中为发布决策辩护。若团队更关心贝叶斯后验，也可以用 Beta 分布给出类似结论，但 Wilson 区间无需选择先验，更适合快速探测。

迷思三：温度0就能得到两次相同的回答

在你构建于这个假设之前，先在自己的端点上测试一下。

即使温度设为0，输出在多次运行间也可能漂移。浮点求和顺序、请求批处理、以及静默的后端版本变更都会移动token。这些都不在你的提示词里。

不要在设计文档里争论。把同一个提示词发送两次，对比原始字符串，写下你看到的结果。“足够确定到能作为缓存键”是一个测量结果，不是一项设置。

温度（temperature） 是采样参数，用于缩放 logits 后再做 softmax，温度越低分布越尖锐。但温度 0 通常并不等于贪心解码的严格实现：许多推理栈在 temperature=0 时仍会加入极小的采样噪声，或者因为批处理中其他请求的 padding 改变了数值路径。更深层的原因是浮点运算的非结合性——相同的数学表达式在不同求和顺序下可能产生不同的舍入结果，进而翻转 top-1 token。此外，服务端可能在不通知的情况下切换量化版本、CUDA 内核或投机解码策略。因此“确定性”应被视为端到端属性，需要在目标端点上实测，而不是从参数推断。

迷思四：修复循环免费修复畸形输出

修复循环不是免费的。它需要第二次调用、额外延迟，以及第二次以不同方式失败的机会。

应该测量边际通过率。如果第一次尝试符合契约的概率是70%，第二次能增加多少？如果答案是几个百分点，你只是用延迟买了噪声。

在发布前设定停止规则：

1. 第一次尝试，严格模式。
2. 失败后，一次修复调用，原样包含验证错误。
3. 第二次失败，升级。不要循环——转交人工或队列。

三次尝试通常是一个伪装成重试策略的bug。

迷思五：免费访问意味着实验零成本

免费访问去掉了账单，但没有去掉墙上时钟时间、速率限制或你自己的注意力。

这就是陷阱。一个在限流调用上烧掉四十分钟的探测，免费与否都是昂贵的。像生产工作一样预算探测：

• 限制试验次数。二十次足够第一轮阅读。
• 调用之间休眠。礼貌比429便宜。
• 当端点发送速率限制头时读取它们。不要猜。

探测：两道门、二十次试验、一个区间

这里是测试工具。仅标准库，Python 3.10+（用于联合类型）。它针对任何你能调用的聊天端点运行。

我通过MonkeyCode的免费模型访问在免费服务器选项上运行它——该工具需要一台保持唤醒的机器进行二十次顺序调用。披露：本文是作为MonkeyCode产品推广的一部分准备的。

# conformance_probe.py — 测量符合性，而不是信任演示
import json
import math
import re
import time

TRIALS = 20
TICKET_RE = re.compile(r"^TCK-\d{4,}$")

PROMPT = (
    "Return one JSON object and nothing else. "
    'Keys: ticket_id (string, "TCK-" plus 4 or more digits), '
    "severity (one of: low, medium, high), "
    "summary (string, at least 10 characters). No extra keys."
)


def call_model(prompt: str) -> str:
    """Return raw assistant text. Wire this to your own client."""
    raise NotImplementedError("fill in your endpoint call")


def extract_json(text: str):
    fenced = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.S)
    candidate = fenced.group(1) if fenced else text
    start, end = candidate.find("{"), candidate.rfind("}")
    if start == -1 or end <= start:
        return None, "no_object"
    try:
        return json.loads(candidate[start:end + 1]), None
    except json.JSONDecodeError as exc:
        return None, f"json_error:{exc.msg}"


def check(obj) -> str | None:
    """Gate B. Return a reason string, or None when conformant."""
    if not isinstance(obj, dict):
        return "not_an_object"
    extra = set(obj) - {"ticket_id", "severity", "summary"}
    if extra:
        return "extra_key:" + ",".join(sorted(extra))
    for key in ("ticket_id", "severity", "summary"):
        if key not in obj:
            return f"missing:{key}"
    if not isinstance(obj["ticket_id"], str) or not TICKET_RE.match(obj["ticket_id"]):
        return "bad:ticket_id"
    if obj["severity"] not in ("low", "medium", "high"):
        return "bad:severity"
    if not isinstance(obj["summary"], str) or len(obj["summary"]) < 10:
        return "bad:summary"
    return None


def wilson(passes: int, n: int, z: float = 1.96):
    if n == 0:
        return 0.0, 1.0
    p = passes / n
    denom = 1 + z * z / n
    centre = (p + z * z / (2 * n)) / denom
    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denom
    return max(0.0, centre - half), min(1.0, centre + half)


def run(trials: int = TRIALS):
    parsed = conformant = 0
    reasons: dict[str, int] = {}

    for _ in range(trials):
        raw = call_model(PROMPT)
        obj, err = extract_json(raw)
        if obj is None:
            reasons[err] = reasons.get(err, 0) + 1
        else:
            parsed += 1
            err = check(obj)
            if err is None:
                conformant += 1
            else:
                reasons[err] = reasons.get(err, 0) + 1
        time.sleep(1)  # be a good citizen; free endpoints still have limits
    lo, hi = wilson(conformant, trials)
    return {
        "trials": trials,
        "parse_rate": round(parsed / trials, 3),
        "conformance_rate": round(conformant / trials, 3),
        "lower_95": round(lo, 3),
        "upper_95": round(hi, 3),
        "failures": dict(sorted(reasons.items(), key=lambda kv: -kv[1])),
    }


if __name__ == "__main__":
    print(json.dumps(run(), indent=2))

每部分到底给你什么

• extract_json 区分“包裹在散文中”和“根本不是JSON”。这是不同的bug，需要不同的修复。
• check 是门B。针对此模式手工编写；如果你更喜欢可以换成 jsonschema，但要固定版本。
• wilson 给你一个可以在评审中辩护的下界，无需在小样本上假设正态性。
• failures 直方图告诉你哪个迷思你实际遇到了。大多数团队得到一种失败形态，反复出现。

extract_json 中的正则 r"```(?:json)?\s*(\{.*?\})\s*```" 使用了非贪婪匹配 .*? 和 re.S（让 . 匹配换行），目的是从 Markdown 代码围栏中提取第一个完整对象。但非贪婪加 re.S 在对象内部嵌套花括号时可能提前截断——例如 {"a": {"b": 1}} 会被截到第一个 } 之前。文章随后用 find/rfind 兜底，但这同样无法正确处理字符串字面量中含花括号的情况。生产环境更稳妥的做法是使用能感知 JSON 结构的扫描器，或先要求模型不输出围栏。这里保留简单实现是为了让探测工具仅依赖标准库，读者应按自己的输出形态调整提取逻辑。

解读数字

按下界排序，而不是点估计。决策表：

下界（95%）	行动
≥ 0.95	严格模式，无修复循环，发布
0.80 – 0.95	一次修复尝试，记录每次升级
0.60 – 0.80	缩小模式。更少字段，更简单的类型
< 0.60	模型不适合此任务。重试救不了

最后一行最重要。符合性差通常是任务形态问题，不是提示词问题。给一个范围不当的模式加重试，只会为同样的失败花更多钱。

还有一个解读提示：如果 parse_rate 高但 conformance_rate 低，你的提示词没问题，是你的契约不讨喜。如果 parse_rate 低，别往下读了，先修复提取。

局限与谁应该跳过

这个探测测量一个模式、一个提示词、一个端点、一个下午。它会过期。当提供商改变任何东西，或你的模式增加字段时，重新运行它。

如果你需要跨运行字节完全相同的输出，或者输出要进入审计追踪，完全跳过它。免费层模型属于分类、标记和草稿路径——不属于你以后会被要求辩护的写入路径。

如果你的量是每天五次调用，也跳过。在那个规模下，自己读输出，把工具留到以后。

不要以为二十次试验就是保证。这是一次带有诚实误差棒的第一轮阅读，仅此而已。

我会保留什么

用“它在20次中符合了17次，下界0.62”替换“它工作了”。那一句话改变整个设计对话。

迷思存活是因为没人运行那二十行本可以杀死它们的代码。所以，运行它们。

如果你想在接入计费前试试这个工具，MonkeyCode的免费模型访问加上免费服务器选项是一个起点——带上你自己的模式和怀疑。