课程大纲 第 138 课,共 250 课 · 结构化输出与函数/工具调用
结构化输出与函数/工具调用

受约束 / 由 schema 强制的输出

在前几课里,你亲手验证了模型的 JSON。现代的做法是再往前一步:从一开始就阻止模型输出坏的 JSON。这就是约束解码(也叫结构化输出)。你把一个 schema 交给 API,解码器只被允许采样那些能让输出始终对照它保持有效的词元。模型根本不可能产生缺失的字段或类型错误的值。

用 OpenAI 风格的 API,你传入一个带有 JSON Schema 和 strict: true 的 response_format(仅作示意,这里我们不调用任何模型):

resp = client.chat.completions.create(
    model="...",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
            },
        },
    },
)

本课程的其余部分调用的是 Anthropic,它通过用于保证 JSON 响应的 output_config 和用于完全符合 schema 的工具输入的 strict 工具调用,提供同样的保证:

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[...],
    output_config={"format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }},
)

无论哪种方式,约束都由提供商来做。但约束解码仍然无法检查你的业务规则(年龄合理吗?这种货币是你支持的吗?),而且并不是每个模型或网关都支持它。所以无论如何你都要在自己这边做验证。你现在要构建的就是那个验证器。

在 Python 这边,声明和验证这种形状的事实标准是 Pydantic。你写一个模型类,库就替你解析、转换和验证:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

record = Person.model_validate_json(text)   # raises if it does not fit

这个浏览器内的沙盒里没有 Pydantic,所以你要用标准库亲手构建同样的想法。这些库在底层做的正是这件事,而且这样一来,规则就不可能被糊弄过去。你要写的是 validate_against_schema(obj, schema)。

schema 是一个字典。每个值要么是一个类型名字符串("int"、"float"、"str"、"bool"、"list"、"dict"),要么是一个像 {"type": "int", "default": 0} 这样的小说明字典。你的函数返回一个结果字典 {"ok": bool, "value": dict, "errors": list}:

  • 如果 obj 不是 dict,就返回 ok=False,带一个根错误和一个空的 value。
  • 对每个字段:如果它缺失而说明里有 "default",就填入默认值(转换/默认值这一步)。如果它缺失又没有默认值,就记录一个错误。
  • 如果存在,就检查它的类型。不匹配时,记录一个点出该字段的错误。
  • 当需要 float 时,把一个普通的 int 转换成 float(这是无损而安全的),但不要转换其他任何东西。
  • 如果有任何错误,就返回 ok=False,带上收集到的 errors 和一个空的 value;否则返回 ok=True,带上验证过的 value。

bool 也是 int 的陷阱。在 Python 里 bool 是 int 的子类,所以 isinstance(True, int) 是 True,而 JSON 的 true 解码成 Python 的 True。一个朴素的类型检查会让 "age": true 顺利通过一个 int 字段。在任何要求 int 或 float 的地方都明确拒绝 bool:

if expected is int and isinstance(value, bool):
    errors.append(field + ": expected int, got bool")

把它构建成这样:两个不同的格式良好的数据都能通过,缺失的字段和错误的类型各自落进 errors,默认值能被填入,int 能转换成 float,而一个偷偷混进来的 bool 在要求数字的地方被拒绝。

轮到你了

写 validate_against_schema(obj, schema),返回 {"ok", "value", "errors"}。schema 把每个字段映射到一个类型名字符串("int"/"float"/"str"/"bool"/"list"/"dict")或一个说明字典 {"type": ..., "default": ...}。拒绝不是字典的 obj,为每个缺失(没有默认值)或类型错误的字段记录一个错误,给出默认值时就填入,把普通的 int 转换成 float,并在要求 int 或 float 的地方拒绝 bool(bool 也是 int 的陷阱)。只有没有错误时,才返回带有验证过的 value 的 ok=True。

发现这节课有问题?报告它 · 就这节课提问

这个练习即将开放

完成它前面的那一课,这一课就会解锁。整门课程免费,无需账号,而且你现在就可以阅读这节课。