L3 · 专题文章

结构化输出

结构化输出JSONSchema模型调用

本页只讲 4 条最关键判断，不写百科

4核心点

先记住Schema 决定成败

不掌握 Schema 设计原则就无法稳定获得合规输出

先看重点 ↓ 下一步

LIVE

CORE 结构化输出

01 WHAT

是什么

通过 Prompt 或 API 参数约束大模型输出符合预定义 JSON Schema 的文本。

02 WHY

为什么

下游系统（数据库、前端、业务逻辑）需要稳定格式，自由文本易导致解析失败与数据丢失。

03 HOW

怎么做

在请求中传入 JSON Schema 定义，模型会按字段类型、必填项生成合规 JSON。

04 WHEN

什么时候

需将模型输出直接接入自动化流程时使用；若只需人类阅读或格式不敏感，无需强制结构化。

FOCUS

先记住这些

只留最重要的判断，细节见下方实践

01 Schema 设计

不掌握就无法稳定输出

字段类型、必填项、枚举值必须明确，避免模型自由发挥导致格式错误

02 API 控制

与自由文本的本质差异

通过 response_format 参数强制模型遵循 Schema，而非依赖 Prompt 暗示

03 输出校验

最高频踩坑

模型可能返回部分合规 JSON 或附加解释文本，必须用 JSON Schema 校验器验证

04 降级策略

失败处理机制

解析失败时应重试或转人工，避免错误数据污染下游系统

PROBLEM / POSITION / INTERFACE

先弄清它为什么存在，以及谁在使用

不从历史开始，从真实工作关系开始。

01 解决的问题

下游系统需要固定字段与类型，但模型返回自由文本或格式不一致。

解析失败率高、需大量后处理、错误难以定位、数据质量不可控。

成功标准

模型稳定返回符合 Schema 的 JSON，无需额外清洗即可直接入库或调用。
02 AI 生态位

连接自然语言理解与结构化数据处理的桥梁，位于 Prompt 工程与下游系统之间。

上游

依赖 Prompt 设计、模型能力、JSON Schema 规范。

下游

为数据库、API、前端组件、自动化脚本提供可直接解析的数据。
03 人的生态位

定义业务字段、设计 Schema、验收输出质量与处理异常。

适合使用

下游系统强依赖固定字段、类型与结构，且需自动化处理。

不必使用

输出仅供人类阅读、格式不敏感、或可用简单模板/正则解决时。
04 独特价值

无需后处理即可获得机器可读数据，显著降低集成成本与错误率。

Schema 设计需平衡灵活性与约束力，模型偶有幻觉或字段遗漏。

复杂度判断

复杂度不是功能数量，而是控制与验证成本。

INTERFACE FLOW

谁在操作，信息怎样流动

WHO OPERATES

HUMAN定义字段、设计 Schema、验收输出、处理异常

MODEL按 Schema 生成合规 JSON

SYSTEM封装请求、传递 Schema、解析响应、处理错误
INPUT
自然语言任务描述 + 预定义 JSON Schema
CONTROL
Prompt 指令、response_format 参数、Schema 定义、温度参数、重试策略
OUTPUT
符合 Schema 的 JSON 对象，可直接被下游系统解析使用

CODE / PYTHON最小 Python 调用

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["API_KEY"])

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "role": {"type": "string", "enum": ["admin", "user"]}
    },
    "required": ["name", "age"]
}

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "提取用户信息"}],
    response_format={"type": "json_schema", "json_schema": {"name": "user_info", "schema": schema}}
)

result = json.loads(resp.choices[0].message.content)
print(result)

最短闭环：定义 Schema → 调用 API → 解析返回 JSON。真实密钥不要写进代码。

JSON / RESPONSE典型返回（示意）

{
  "id": "chatcmpl-xxx",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\": \"张三\", \"age\": 28, \"role\": \"user\"}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 22,
    "total_tokens": 67
  }
}

PRACTICE