个人站点
Agent

主线 · 第 4 / 12 篇

· 约 9 分钟

让输出能被程序接住:结构化输出、schema 校验、拒答与截断

Agent 里模型的输出要交给程序处理,所以要按约定的结构生成,再一层层检查:为什么停下、语法、schema、业务规则。结构化输出能保证大多数情况下的格式,但拒答、截断和业务上的对错,仍然要应用自己处理。

本文目录 6 节
  1. 为什么要让程序接得住
  2. 三种约束:提示、JSON 模式、结构化输出
  3. 结构化输出也有例外
  4. 一条校验管线
  5. 容易误解的地方
  6. 参考资料

前面的早期演示用固定函数代替模型,直接给出程序要求的返回值。接上真实模型后,就需要解析和检查输出:程序要从里面读出调用哪个工具、传什么参数、什么时候停。给程序读的文本,要求比给人读的严格得多。这一篇讲怎样让输出能被程序接住,以及接住之前要检查什么。

几个词先说明。结构化输出指让模型按约定的结构生成内容,最常见的是 JSON。schema 是描述这个结构的规则;JSON Schema 是一种声明式的语言,用来定义 JSON 数据的结构和约束。校验是检查输出是否满足这些规则。停止原因(stop reason)是 API 返回的一个字段,说明这次生成为什么结束。

为什么要让程序接得住

上一篇说过,模型的输出是从分布里抽出来的,没有对错保证,也没有格式保证;提示只改变分布。Anthropic 的文档列了提示写得再仔细也会遇到的几种情况:JSON 语法错误、缺少必填字段、字段类型不一致、违反 schema,需要错误处理和重试。

对聊天来说,格式有点偏差,人读起来照样明白。对 Agent 来说,后面的代码要解析它、按它分支、甚至照着它执行。OWASP 的大模型应用十大风险里有一项叫“输出处理不当”:模型生成的内容在传给下游组件之前,没有经过足够的校验、清理和处理。理由是模型的输出能被提示里的输入左右,放任它直接进入下游,等于间接把系统的功能交给了提供输入的人。

所以本专题采用的原则是:模型的输出和用户的输入一样,是不可信的外部数据,检查过才能用。例如,把模型文本直接拼进 SQL 或 shell 命令,原本当作数据的内容就可能改变查询含义或触发额外命令,形成注入风险。

三种约束:提示、JSON 模式、结构化输出

约束输出格式,大致有三种强度。

第一种是写在提示里:说明要 JSON,给出字段和示例。成本最低,但只是让模型更可能照做。

第二种是 JSON 模式。OpenAI 的文档说明,JSON 模式能保证生成合法的 JSON,但不保证符合给定的 schema,字段缺了、类型错了,它都不管。

第三种是结构化输出:把 schema 交给 API,生成时直接受它约束。OpenAI 的示例里这样对比:和 JSON 模式不同,它约束的是 JSON 的形状,不只是语法合法。Anthropic 的文档也说,结构化输出通过约束解码保证输出符合 schema。

约束解码可以这样理解:每步只从符合格式规则的 token 中选择,而不是生成完再修格式。Willard 和 Louf 2023 年的论文用有限状态机实现这类限制。Anthropic 的文档提到,它会把 schema 转成生成时可用的规则,首次使用要多等编译的时间。同样的约束也能加在工具调用上,让工具参数符合 schema,这是下一篇的内容。

结构化输出也有例外

Anthropic 的文档写明,结构化输出在大多数情况下保证符合 schema,并单独列了不符合的情形。拒答时,停止原因是 refusal,状态码照样是 200,生成的 token 照样计费,拒答的内容优先于 schema,输出可能对不上格式。达到输出长度上限 max_tokens 时,输出被截断,可能不完整。枚举值的大小写也不保证,文档建议比较时不区分大小写。

另外,支持的 schema 只是 JSON Schema 的一个子集。按 Anthropic 当前的文档,数值范围、字符串长度这类约束都不在支持之列。哪些约束 API 能保证、哪些要自己检查,各家和各版本都不一样,用之前要对照当时的文档。

一条校验管线

所以应用这边要有自己的检查,并且分层,按顺序来。

第一层看停止原因。Anthropic 的文档把它和错误分开:停止原因属于成功的响应,说明生成为什么正常结束;错误是 4xx、5xx 这类请求失败。只有正常结束的输出,才值得往下解析。第二层看语法,能不能解析成 JSON。第三层看 schema:必填字段、类型、枚举。第四层看业务规则,也就是 schema 表达不了的东西:服务是否真的存在,引用的证据是否真在观察里出现过,严重级别和处置动作是否对得上。

写成代码,就是按顺序排下来,碰到第一个失败就返回。下面这段取自本篇的演示脚本:

def validate(resp):
    """Return (layer, verdict, detail). Layers run in order and stop at the first failure."""
    if resp["stop_reason"] == "refusal":
        return "stop", "human", "model declined; do not parse, do not retry"
    if resp["stop_reason"] == "max_tokens":
        return "stop", "retry", "truncated; raise the limit or shrink the task"
    try:
        obj = json.loads(resp["text"])
    except json.JSONDecodeError as e:
        return "syntax", "retry", e.msg
    err = check_schema(obj)
    if err:
        return "schema", "retry", err
    err = check_rules(obj)
    if err:
        return "rules", "retry", err
    return "all", "accept", f"{obj['severity']} {obj['action']}: {obj['cause']}"

每层失败的处理不一样。格式和 schema 错误,可以把错误信息原样反馈给模型重试,但要有次数上限。截断,就提高上限或者把任务拆小。拒答不要靠重试绕过去,交给人。

下面的演示不联网,也没有模型,六个“响应”是手写的,交给同一条管线检查。任务是给告警 A 写一份研判,字段有服务、严重级别(P1 到 P3)、原因、证据、处置动作(none、notify、page)。

case               layer   verdict  detail
clean              all     accept   P1 page: db pool full
wrapped in prose   syntax  retry    Expecting value
enum drift         schema  retry    severity must be one of P1, P2, P3
made-up evidence   rules   retry    evidence is not a quote from the observations
cut off            stop    retry    truncated; raise the limit or shrink the task
refusal            stop    human    model declined; do not parse, do not retry
retry loop, max 3 attempts
  attempt 1: retry  severity must be one of P1, P2, P3
  attempt 2: accept P1 page: db pool full

第二个响应内容是对的,只是在 JSON 外面包了一句说明和代码块标记,严格解析在第一个字符就失败了。第三个把严重级别写成了 high,schema 这一层拦住。第四个格式完全合规,可它引用的证据在日志里根本不存在,是编出来的,只有业务规则这一层能发现。第五个被 max_tokens 截断,不该当作完整输出去解析。第六个是拒答,直接交给人。

最后一段是重试:第一次的错误信息被放进下一次的输入,第二次通过。错误信息写得越具体,比如列出允许的取值,重试越有用。

容易误解的地方

“写了‘只返回 JSON’就够了。”提示只是让模型更可能照做,演示里第二个响应就是这种情况。

“通过 schema 就是对的。”schema 只管形状。第四个响应每个字段都填得规规矩矩,证据却是编的;如果证据是真的、结论是错的,任何一层校验都查不出来,那要靠后面讲的评估。

“校验失败就重试到成功。”重试要有上限,还要把错误告诉模型,不然很可能原样再错一次。拒答和截断不是格式错误,要分开处理。

“用了结构化输出就不用校验。”它省掉的是语法和一部分 schema 检查,停止原因和业务规则仍然要自己看。

日常用的编码 Agent 也是这个思路:改完代码,跑一遍编译器或测试,由程序判断结果能不能接受,而不是看它说得多肯定。

参考资料

本文涉及的知识点

7 个

名称打开知识图谱中的对应条目;「另见」只计已发布文章。