---
title: "结构化输出 (Structured Output)"
created: 2026-06-10
updated: 2026-06-10
type: concept
tags: [llm, structured-output, pydantic, json-schema]
sources: [raw/articles/pydantic-three-piece-suite-2026.md]
---

# 结构化输出 (Structured Output)

> 让 LLM 生成符合预定义 schema 的 JSON/对象，而非自由格式文本。是从"自然语言回复"到"可编程 API"的关键桥梁。

## 核心挑战

LLM 的输出是概率性的——同样的 prompt 跑 100 次，结构会**漂移**（字段名变化、多了字段、类型错误、None 值）。

## 解决方案层次

| 方案 | 适用场景 | 代表工具 |
|------|---------|---------|
| 单次校验 | 简单结构化输出 | Instructor, Pydantic `model_validate` |
| 可观测校验 | 需要监控漂移趋势 | [[logfire|Logfire]] + trace |
| 类型约束 Agent | 多步推理 + tool 调用 | [[pydantic-ai|Pydantic AI]] |

## 从"事后校验"到"事前约束"

传统：LLM 输出 → model_validate → 错了 → 重试

[[pydantic-ai|Pydantic AI]]：Agent 定义时类型已写入 tool schema → LLM 按 schema 输出 → 自动校验 → 出错框架层重试

## 三配置升级（零成本）

```python
model_config = {
    "strict": True,    # 空字符串不会变 0
    "extra": "forbid", # LLM 多塞字段立刻报
    "frozen": True,    # 模块间传递防篡改
}
```

## 参考

- [[pydantic-ai|Pydantic AI]]
- [[type-safety-in-agents|Agent 类型安全]]
- [[drift-detection|漂移检测]]