在工单分类、信息抽取、智能表单和自动化工作流中，AI 模型的输出通常不是给人直接阅读，而是交给程序继续处理。此时，“看起来像 JSON”远远不够：字段缺失、类型漂移、枚举越界、额外文本或转义错误，都可能导致接口失败。可靠方案应同时覆盖生成约束、语法解析、Schema 校验、业务校验和异常恢复。
一、先区分三种结构化输出能力
1. 提示词约束
最基础的方式是在提示词中要求模型“只返回 JSON，不要添加解释”。它接入简单，适合原型验证，但本质上属于软约束。随着字段数量、嵌套层级和条件规则增加，模型仍可能输出代码块标记、自然语言前缀、错误字段名或不一致的数据类型。
2. JSON 模式
部分模型接口提供 JSON 模式，可将输出限制为合法 JSON。它主要解决括号、引号、逗号等语法问题，却不一定保证数据符合指定结构。例如程序要求 status 只能是 success 或 failed，模型仍可能返回 completed。因此，JSON 模式不能代替 Schema 校验。
3. 基于 JSON Schema 的严格输出
更可靠的方案是在请求中声明对象属性、必填字段、数据类型、枚举值及是否允许额外属性，由模型服务在生成阶段施加约束。与单纯提示词相比，它能显著减少格式漂移。不同平台支持的 JSON Schema 关键字和草案版本可能不同，接入前应查阅对应模型的来源链接，不要默认完整 Schema 功能都可使用。
二、为什么生成受约束后仍要校验
结构约束只能解决一部分问题。模型可能因内容安全策略拒绝回答，也可能出现请求超时、输出截断、SDK 解析异常或平台降级。即使 JSON 在结构上有效，业务含义也可能不合理，例如结束时间早于开始时间、金额为负数，或者订单状态与操作类型冲突。
因此，生产环境应采用分层校验：先限制响应大小并完成 JSON 解析，再执行 JSON Schema 校验，随后检查跨字段关系、权限和业务规则。Python 官方文档也提醒，解析不可信 JSON 时应关注 CPU 与内存消耗，并限制输入规模，详见Python JSON 文档。
三、Schema 应该如何设计
- 字段尽量少：只保留下游真正需要的数据，避免让模型填充无意义字段。
- 类型保持稳定：同一字段不要有时返回数字、有时返回带单位的字符串。
- 枚举优先：状态、类别和操作类型应使用受控枚举，减少自由文本。
- 明确必填项：对缺失值设计统一策略，可使用 null、空数组或专门的状态字段，但不要混用。
- 禁止未知属性：在平台支持时使用 additionalProperties 控制额外字段，防止模型自行扩展结构。
- 控制嵌套深度：过深结构会增加模型生成、日志排查和前后端维护成本。
- 保留版本号：在 Schema 或接口层记录版本，便于兼容旧数据和灰度升级。
Schema 不仅是校验规则，也是模型、接口和业务系统之间的数据契约。建议将其纳入代码仓库，通过变更评审、自动化测试和版本管理维护，而不是散落在提示词或业务代码中。
四、主流 JSON 校验工具如何选择
Ajv：适合 JavaScript 和 TypeScript 服务
Ajv 可将 Schema 编译为 JavaScript 校验函数，适合 Node.js API、前端表单和高频数据管道。它支持多个 JSON Schema 草案及 JSON Type Definition，功能包括严格模式、格式扩展和错误信息收集，具体兼容范围可查看Ajv 官方文档。选型时应固定 Schema 草案版本，并确认 strict、allErrors 和格式插件等配置，避免开发与生产环境行为不一致。
jsonschema：适合 Python 数据与 AI 服务
Python 项目可优先考虑 jsonschema。它支持多个 JSON Schema 草案，能够返回字段路径、失败规则及上下文信息，适合模型结果校验、离线数据清洗和接口测试。需要注意的是，format 关键字是否真正执行检查取决于校验器配置，不能仅因 Schema 中写了 email 或 date-time 就认定验证已经启用，详见jsonschema 文档。
Pydantic：适合类型模型与业务代码统一
如果 Python 服务已经使用类型注解和数据模型，Pydantic 可以把解析、类型约束、默认值和错误报告集中在模型层，并可生成 JSON Schema。它适合将模型输出直接转换为领域对象，但仍需谨慎使用自动类型转换，避免字符串数字或布尔值被静默接受。相关配置可参考来源链接 官方文档。
Zod：适合 TypeScript 全栈项目
Zod 以 TypeScript 为中心，可从运行时 Schema 推导静态类型，减少接口定义与类型声明重复。它适合前后端共享数据契约，也便于与支持 Zod 辅助函数的模型 SDK 集成。若团队需要严格遵循标准 JSON Schema，仍应确认 Zod Schema 转换后的关键字是否满足目标平台要求，参考来源链接 文档。
五、选型时重点比较哪些维度
- 语言栈：JavaScript 或 TypeScript 优先考虑 Ajv、Zod，Python 可考虑 jsonschema、Pydantic。
- 标准兼容：确认工具、模型平台和 API 网关采用的 JSON Schema 草案及支持子集。
- 性能模式：高频请求适合预编译并复用校验器，避免每次请求重复解析 Schema。
- 错误可读性：错误结果应包含字段路径、期望类型和失败规则，同时对外隐藏敏感内容。
- 类型集成：需要静态类型推导时，可优先选择 Pydantic 或 Zod；跨语言共享契约时，标准 JSON Schema 更合适。
- 安全能力：应评估响应大小限制、正则表达式风险、远程引用策略和未知格式处理方式。
六、推荐的生产级处理流程
- 为任务定义精简、带版本号的 Schema，并在上线前验证 Schema 本身是否合法。
- 优先使用模型平台提供的严格结构化输出能力，同时在提示词中说明字段语义。
- 接收响应后识别拒绝、超时、截断和空内容，不要直接假设一定存在结果对象。
- 执行 JSON 解析和 Schema 校验，再进行跨字段关系、权限及业务规则校验。
- 将错误按可重试与不可重试分类，重试时提供精简的校验反馈，并设置次数上限。
- 记录模型版本、Schema 版本、校验阶段和错误路径，但不要把隐私数据完整写入日志。
- 使用缺失字段、额外字段、错误类型、超长文本和非法枚举等样本建立回归测试。
结构化输出的目标不是让模型“尽量返回正确 JSON”，而是把不稳定的自然语言生成纳入可验证、可监控、可回退的软件工程流程。
总结
工具选型不应只比较校验速度或 API 是否简洁。更关键的是语言生态、Schema 草案兼容性、错误可观测性、类型系统集成和安全边界。JavaScript 高频校验可重点评估 Ajv，TypeScript 全栈项目可结合 Zod，Python 标准 Schema 场景适合 jsonschema，强调领域模型与类型转换时可使用 Pydantic。无论选择哪种工具，都应坚持“生成阶段约束、接收阶段校验、业务阶段复核、失败阶段可控恢复”的完整链路，才能让 AI 结构化输出真正具备生产可用性。
