Pydantic 2.9 模型嵌套生成 $defs 接口报 400 怎么拍平 schema

工单抽取用 Pydantic 2.9 定义结构,模型里嵌了一个地址对象,导出 schema 后带着 $defs 和 $ref。调接口直接 400,原文是 Invalid schema for response_format,后面说 $ref 不被支持。同一个模式在本地校验没问题,卡在服务端。

第一反应是加 additionalProperties: False。报错换了,说定义里还有未解析的引用。把整段定义删掉,字段全丢,模型开始编地址。

试过用 model_json_schema 的 ref_template 参数改引用前缀,服务端照样不认。也试过把嵌套模型序列化成字符串字段,让模型输出 JSON 串再解析,多了一层转义,800 条里 60 多条引号错位。

能走通的是拍平。地址对象拆成 province、city、street 三个顶层字段,枚举全部内联,不留任何引用。写了个小函数递归展开引用,展开后校验没有残留定义才发出去。

def flat(schema):
    defs = schema.pop("$defs", {})

    def walk(node):
        if "$ref" in node:
            name = node["$ref"].split("/")[-1]
            return walk(defs[name])
        return {k: walk(v) if isinstance(v, dict)
                else [walk(i) for i in v]
                if isinstance(v, list) else v
                for k, v in node.items()}
    return walk(schema)

拍平后模式从 1.4KB 涨到 2.1KB,多出来的 token 一次调用贵万分之三,和重试比不算什么。800 条重跑,解析失败从 61 条降到 4 条,剩下的是地址里混了英文缩写。

字段顺序也会影响成功率,把 type 这类判别字段放在第一位,模型先定分支再填内容,缺字段少一半。评审时别只看 schema 能不能导出,拿真实请求打一次接口,报错信息比文档直接。

您可以还会对下面的文章感兴趣: