Structured Output (结构化输出) 教程

长期以来，让 LLM 稳定输出 JSON 是一门玄学。直到 OpenAI 推出了 response_format={"type": "json_object"} 和后来的 Structured Outputs (严格模式)，这才让 AI 从“聊天机器人”变成了可靠的“数据处理 API”。

---

1. 为什么需要结构化输出

当你希望 AI 把一篇简历提取成数据库能存的格式时：

• 不稳定 (Text):

  “姓名是张三，技能有 Python...” (你需要写复杂的正则去匹配)

• 稳定 (JSON):

  {"name": "张三", "skills": ["Python"]} (直接 json.loads 即可)

2. 三种实现方案

方案 A: 提示词工程 (Prompt Engineering)

最原始的方法，适用于任何模型。

Prompt: "请提取其中的信息，并严格以 JSON 格式输出，不要包含任何 markdown 标记。"

缺点：模型可能会啰嗦（比如开头加一句 "Here is the JSON:"），或者 JSON 语法错误（少个括号）。

方案 B: JSON Mode

OpenAI 提供的中间态方案。

设置 response_format={"type": "json_object"}，并在 Prompt 中显式提到 "JSON"。

优点：保证输出的是合法 JSON。 缺点：无法保证 JSON 里的字段是你想要的（比如把 phone 写成了 telephone）。

方案 C: Structured Outputs (推荐)

OpenAI 2024 年推出的终极方案。使用 JSON Schema 严格约束。 优点：100% 遵循 Schema，字段名、类型绝对正确。

3. 实战代码 (Pydantic / OpenAI)

最优雅的方式是结合 Python 的 Pydantic 库。

from pydantic import BaseModel
from openai import OpenAI

class Step(BaseModel):
    explanation: str
    output: str

class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str

client = OpenAI()

completion = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "You are a helpful math tutor."},
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    response_format=MathReasoning, # 直接传 Pydantic 类
)

result = completion.choices[0].message.parsed
print(result.final_answer)
# Output: -3.75

4. 自定义 Schema (非 Pydantic)

如果你不是用 Python，或者想手动控制 Schema：

{
  "type": "json_schema",
  "json_schema": {
    "name": "math_reasoning",
    "schema": {
      "type": "object",
      "properties": {
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "explanation": { "type": "string" },
              "output": { "type": "string" }
            },
            "required": ["explanation", "output"],
            "additionalProperties": false
          }
        },
        "final_answer": { "type": "string" }
      },
      "required": ["steps", "final_answer"],
      "additionalProperties": false
    },
    "strict": true
  }
}

5. 最佳实践

• Always use Strict: 如果模型支持（如 GPT-4o），尽量开启 strict=True，这样能彻底杜绝幻觉字段。
• Few-shot: 即便有了 Schema，如果任务很复杂（如情感分类的情绪定义），在 Prompt 中提供 1-2 个 JSON 示例依然能显著提升内容质量。
• 错误重试: 即使是结构化输出，对于推理型问题（如“提取所有地址”），模型也可能漏掉。可以配合 Validator 库（如 Guardrails, Instructor）进行校验和重试。

---

最后更新：2025-12