LLM结构化输出与Schema校验实战指南

大语言模型能生成答案、抽取信息、驱动自动化流程，但它吐出的内容并不天然等于可信的应用数据。字段可能缺失、取值可能越界，甚至输出合法JSON却违反业务规则——当这些结果直接写入数据库、调用API或驱动Agent时，问题会被放大。

一套可靠做法是把三件事组合起来：约束生成、应用侧校验、业务规则兜底。Structured Outputs把响应限制在受支持的JSON Schema内，Pydantic等库在下游处理前验证数据，应用层则显式处理拒答、生成中断和授权失败。

Structured Outputs究竟解决了什么

Structured Outputs指的是按照预定义数据契约生成的响应。应用不再要求模型返回一段自由文本，而是明确指定字段、类型和允许的取值。

以工单分类系统为例：它需要category、priority、summary、confidence、evidence等字段。没有结构约束时，模型可能换一套字段名，或者把分类结果埋在一段解释性文字里。

Structured Outputs与JSON模式的区别

JSON模式和Schema约束生成常被混为一谈，但两者并不等价。JSON模式只保证输出是合法JSON；Structured Outputs在模型和Schema受支持的前提下，还会强制满足指定结构。两者都不保证内容事实正确。

Prompt格式化只是“请求”某种格式，JSON模式瞄准合法JSON，Structured Outputs把响应限制在受支持Schema内，本地校验则独立检查数据是否满足应用要求，业务规则校验确保结果适合其用途。

对生产系统来说，这些手段配合使用效果最好：供应商侧约束减少结构性错误，本地校验提供应用边界，业务规则保证合法数据不会越权。

JSON Schema 是描述和校验JSON文档结构的IETF标准，用type、properties、required、enum、minimum/maximum等关键字表达字段类型、必填项、取值范围等约束。文中Pydantic模型正是被SDK翻译成JSON Schema后再传给模型端点。需要区分的是，不同供应商对JSON Schema子集的支持并不一致：OpenAI的Structured Outputs要求additionalProperties: false且所有字段必须列入required（用nullable表达可选），一些高级关键字如oneOf、patternProperties可能被拒绝或降级。因此把本地校验用的Schema直接交给模型端点前，务必确认它是供应商支持的“子集”，否则可能出现请求被拒或约束被静默忽略的情况。

Schema能校验什么

JSON Schema能描述必填字段、类型、枚举值、嵌套对象、数组以及部分取值约束。例如priority字段只接受low/medium/high，confidence限定在数值区间，evidence要求字符串数组。

但结构约束有边界。Schema能验证evidence字段里是字符串，却无法证明这些字符串真的出现在源文档中——那需要额外的应用逻辑或评估。

设计可靠的结构化输出架构

生产实现应把模型响应当作未经信任的输入，直到它通过应用的验收流程。典型流水线包含六个阶段：

• 输入准备：校验入站请求，建立可信上下文
• 约束生成：调用受支持的LLM端点并传入预期Schema
• 响应检查：检查完成状态、拒答和API错误
• 本地校验：解析为带类型的应用对象
• 业务校验：应用领域规则、权限与审批要求
• 下游处理：只持久化、展示或路由通过验收的数据

每个阶段目的不同。API超时不是Schema违规，拒答不是JSON格式错误，结构合法的响应也不等于已授权操作。把失败类别分开，调试更轻松，恢复策略也更好实现。

用Python实现Structured Outputs

下面以OpenAI Python SDK配合Pydantic对客服工单分类为例，演示chat.completions.parse()的用法。部署前应查证当前模型与SDK版本。

第一步：定义输出Schema

安装依赖：

python -m pip install openai pydantic

生产环境要固定兼容的依赖版本，并通过环境变量或密钥管理器配置API Key。

用Pydantic模型定义预期输出：字段包括category、priority、summary、confidence、evidence、needs_human_review。category和priority用Literal限定枚举值，confidence用Field做区间约束，再通过自定义validator拒绝空白summary和空evidence项。

第二步：请求Schema约束响应

SDK能从Pydantic模型推导兼容的响应Schema，并把响应解析为带类型的对象：

from openai import OpenAI

client = OpenAI()

def classify_ticket(ticket_text: str) -> TicketTriage:
    if not ticket_text.strip():
        raise ValueError("Ticket text cannot be empty")

    completion = client.chat.completions.parse(
        model="gpt-4o-2024-08-06",
        messages=[
            {"role": "system", "content": "Classify the support ticket using the provided response schema. Do not invent evidence. Flag ambiguous cases for review."},
            {"role": "user", "content": ticket_text},
        ],
        response_format=TicketTriage,
    )
    message = completion.choices[0].message
    if message.refusal:
        raise RuntimeError("The model refused the request")
    if message.parsed is None:
        raise RuntimeError("No parsed result was returned")
    return message.parsed

注意：模型标识符只是文档示例，不代表最新或最优选择。使用前需确认当前可用性、端点兼容性和Schema特性支持。

第三步：执行业务规则

Schema校验只建立结构正确性，业务逻辑需要单独检查。假设高优先级工单必须转人工审核：

def validate_triage(result: TicketTriage) -> TicketTriage:
    if result.priority == "high" and not result.needs_human_review:
        raise ValueError("High-priority tickets require human review")
    return result

即使模型忽略指令，业务规则依然可执行。真实系统中，应用可以把失败结果路由到审核队列，而不是终止流程。核心原则很简单：Prompt引导模型行为，应用代码落实关键要求。

校验来自外部来源的JSON

不是每个应用都能用供应商特定的解析助手。有些系统从其他LLM供应商、存储记录或内部服务接收JSON。这时本地校验提供统一执行层：

from pydantic import ValidationError

def parse_untrusted_json(raw_json: str) -> TicketTriage:
    try:
        result = TicketTriage.model_validate_json(raw_json)
    except ValidationError as exc:
        raise ValueError("The supplied JSON failed validation") from exc
    return validate_triage(result)

该函数拒绝无法解析或不满足模型校验规则的数据，随后套用主流程同样的业务校验。

生产环境中的校验失败处理

即使有Schema约束生成，应用也要考虑失败请求、拒答、不完整响应和业务规则违规。

需要处理哪些失败类型

• 网络超时：在有限策略内重试
• 速率限制：退避、抖动与并发控制
• 模型拒答：走专门的拒答处理路径
• 不完整响应：拒绝结果，可恢复时重试
• Schema校验失败：记录失败并选择性拒绝或重生成
• 业务规则违规：安全兜底或转人工
• 授权失败：拒绝请求的动作

应用不应把所有失败都压成通用解析异常，否则难以判断问题来自网络、模型行为、Schema设计还是应用策略。

非法输出该自动重试吗

重试适合临时故障，但不是每个非法结果都值得再调一次模型。合理的恢复策略应分类错误、限制重试次数，避免因永久性配置问题反复请求。反复要求模型修复模糊业务决策，只会增加延迟和成本。

如果重试可能触发外部动作，还必须考虑幂等性。重复模型调用不一定安全——工作流可能发出重复付款、重复记录或重复通知。

为什么盲目JSON修复有风险

有些实现会尝试自动修复畸形JSON。这在依赖非约束文本生成的遗留系统中可能有用，但引入了一个必须被验证的额外变换。修复过程可能删除意外字段、改动取值或掩盖缺失信息。如果必须修复，务必再次对完整Schema和业务规则进行校验。能解析不等于可信。

幂等性（Idempotency） 指同一操作执行一次或多次产生相同结果。在结构化输出重试场景下它尤为关键：若模型调用触发了写数据库、发付款或发通知等副作用，一次超时后重试可能导致动作被执行两次。工程上常见的做法是让下游操作携带幂等键（idempotency key），服务端据此识别重复请求并返回首次结果；对于不可逆动作，则把模型调用与副作用执行解耦，先落到可对账的草稿或待审批状态，确认只执行一次后再推进。这样即使模型调用或网络层重复，也不会造成重复付款或重复通知。

企业AI系统中的结构化输出安全

结构化输出提升接口可靠性，但不会自动让生成内容变安全。

合法JSON也可能触发不安全动作

设想一个AI Agent输出合法对象，包含客户标识、退款金额和审批标志。对象可能完全符合Schema，却提出一笔未授权退款。应用必须独立验证身份、权限、交易限额和审批状态。模型生成的"approved": true绝不能替代权威授权决策。

当结构化输出用于工具调用、企业工作流和自主Agent时，这种分离尤其重要。

防御Prompt注入

RAG应用和企业Agent经常处理文档、邮件和检索内容，这些都应视为不可信输入。Schema约束输出结构，但不保证模型遵循了预期指令或正确理解了来源。建议控制措施：

• 把检索文档和用户文本视为不可信数据
• 针对权威系统校验标识符和资源访问
• 用显式白名单限制可用工具和操作
• 把凭证和授权决策排除在模型可控内容之外
• 敏感或不可逆动作要求人工审批
• 把Prompt注入尝试纳入安全评估

Prompt注入 指攻击者把恶意指令嵌入模型会读取的内容（用户输入、检索文档、网页、邮件）中，诱导模型偏离既定任务，例如窃取上下文、调用不该调用的工具或输出攻击者期望的结构。结构化输出只能约束“形状”，不能阻止注入内容进入模型上下文。常见防御思路包括：用明确分隔符或结构化字段把不可信数据与指令区分开，采用最小权限的工具白名单，把敏感凭证和授权判断放在模型之外，对检索来源做信任分级，并对高风险动作加人工审批。核心原则是把模型视为可能被操纵的组件，安全边界由外部系统而非Prompt承担责任。

性能、监控与可扩展性

结构化输出处理会带来额外考量，但性能影响取决于模型、Schema复杂度、响应长度、网络条件和应用实现。应在代表性负载下测量，而非依赖假设。

保持Schema可维护

大型深层嵌套Schema更难维护，也可能碰到供应商特定限制。建议使用描述性属性名并记录含义，只包含下游消费者需要的字段，保持Schema聚焦单一任务，验证供应商对每个Schema特性的支持，对契约做版本管理并针对现有消费者测试变更。

监控完整请求生命周期

生产监控应覆盖端到端延迟与token用量、供应商错误/超时/限流、拒答与不完整响应率、本地校验失败与业务规则违规、重试频率与下游拒绝率、人工审核频率与任务级准确率。

计算比率时使用一致的分母。供应商失败和本地校验失败应分开跟踪，因为它们指示不同问题。同时也要评估语义质量：响应可能满足每条Schema约束，却分类错误或编造证据。结构合规不能替代任务准确率测量。

安全地做Schema版本管理

实用发布流程应把Schema与应用代码一起存储、标识版本、测试兼容性，并在部署前跑回归评估。破坏性变更要刻意引入、监控结果、保留回滚策略。使用多模型或多供应商的系统应独立测试每种受支持配置——相同Schema定义不保证跨实现行为一致。

部署前的测试

一个成功示例不足以证明生产就绪。测试应覆盖正常请求、边界条件、模糊输入和失败路径：

• 有效响应：确认预期字段和取值被接受
• 边界值：测试空字符串、数值极限、空数组、意外枚举值
• 业务规则失败：验证结构合法但不可接受的结果被拒绝
• 供应商失败：测试超时、限流、拒答和不完整响应
• 安全用例：测试Prompt注入、未授权资源标识符、不安全工具参数
• 回归用例：在更换模型、Prompt、Schema或SDK版本后重跑代表性样例

总结

结构化输出与Schema校验通过约束生成、类型化解析和业务规则执行，让LLM集成更可预测。可靠实现还需要显式失败处理、安全控制、监控和回归测试。部署前要确认供应商兼容性、测试边界情况，并确保没有任何未校验或未授权的模型输出进入有后果的下游操作。