20260617:目前有914 页

concepts/structured-output.md

@@ -0,0 +1,46 @@
+---
+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|漂移检测]]