结构化输出

进阶

What you'll learn

解释为什么由 schema 强制的输出胜过提示要 JSON 再碰运气
提供一份 JSON Schema，并把响应解析为类型化的对象（Pydantic / Zod）
凭意图而非机制把结构化输出与工具使用区分开
应用四条建议，写出收得紧、可靠的 schema
用一个一问到底的经验法则挑出合适的工具

当 Claude 的输出要喂给其他软件时，你需要 可靠的结构——每一次都是符合已知形态的有效 JSON。不要靠"请用 JSON 回复"再寄希望；要用平台的结构化输出支持。

本课带你从为什么靠提示再碰运气会失败，走到如何强制套用一份 schema 并把它解析为类型化的对象——以及当结构化输出和工具使用看起来一模一样时，如何把它们区分开。请从上到下逐节读完，然后用接近文末的小测验来检验自己。

可靠的方式

为输出提供一份 JSON Schema，让 API/SDK 强制套用它，然后解析为类型化的对象（例如 Python 中的 Pydantic、TypeScript 中的 Zod）。SDK 的解析辅助方法会交给你一个类型化的结果，而不是一段你还得自己 JSON.parse 并校验的字符串。

Guided walkthrough1 of 3

把你需要的输出建模为一份 JSON Schema——在 Python 中用 Pydantic 的 BaseModel，在 TypeScript 中用 Zod schema。

# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

想要一个可以直接套用的具体请求吗？下面就是你交给模型的内容的形态——把其中的模型换成你自己的 schema 即可。

请求符合 schema 的输出

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

为什么不直接在提示词里要 JSON？

你可以在提示词里要 JSON，对于简单情形它也管用——但它可能漂移：多出的散文、一个尾随逗号、一个缺失的字段。由 schema 强制的输出消除了这类 bug，而一旦下游系统依赖它，这一点就至关重要。

Watch out

提示式 JSON 在演示里管用，到了生产环境就出问题：故障只有在下游系统去解析它时才会暴露。
需要警惕的三种经典漂移：JSON 周围多出的散文、一个尾随逗号、一个缺失的必填字段。