Structured Output

结构化输出是让模型输出符合预定义格式（通常是 JSON）的技术，目标是让输出可以被程序直接解析，而非只是给人看的自然语言。纯靠 Prompt 要求「输出 JSON」在实践中失败率约 8–15%——模型偶尔会输出 Markdown 代码块、多说一句废话、或字段名写错。更可靠的做法有两种：①Schema 约束（OpenAI 的 Structured Outputs 或 Gemini 的 response_schema，成功率可达 99.7%+）②工具调用（Anthropic 的方案：把目标 JSON 结构定义成一个「工具」的 input_schema，让模型以调用工具的形式输出结构化数据，成功率约 99.8%）。Anthropic 没有专门的 JSON mode，但 tool use 方案同样稳定。使用结构化输出时，Schema 设计要遵守：字段名清晰易懂（模型靠字段名猜语义）、必填字段列入 required、类型要具体（用 enum 而非 string，当取值有限时）。即使用了 Schema 约束，生产代码也应该加 try/except 做容错解析，不要假设 100% 成功。

就像餐厅订单系统：服务员（模型）听到客户需求后，不能随便用语言描述给厨房，而必须填一张标准订单表格（JSON）——「主菜：牛排，熟度：七分，忌口：无葱」。表格格式固定，厨房系统才能自动读取处理。如果服务员用自由文本描述「客人要一份不太熟的牛排，还有点不喜欢葱」，厨房系统就没办法直接解析了。

# Anthropic 结构化输出：用 tool use 方案稳定获取 JSON
import anthropic
import json

client = anthropic.Anthropic()

# 把目标结构定义为工具的 input_schema
extract_tool = {
    "name": "extract_product_info",
    "description": "从用户描述中提取产品信息",
    "input_schema": {
        "type": "object",
        "properties": {
            "product_name": {"type": "string", "description": "产品名称"},
            "price": {"type": "number", "description": "价格（元）"},
            "category": {
                "type": "string",
                "enum": ["电子产品", "服装", "食品", "其他"],
                "description": "产品类别"
            },
            "in_stock": {"type": "boolean", "description": "是否有货"}
        },
        "required": ["product_name", "price", "category"]
    }
}

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    tools=[extract_tool],
    tool_choice={"type": "tool", "name": "extract_product_info"},  # 强制调用工具
    messages=[{
        "role": "user",
        "content": "索尼 WH-1000XM5 耳机，售价 2499 元，目前有货。"
    }]
)

# 从 tool_use block 取出结构化数据
tool_result = next(b for b in resp.content if b.type == "tool_use")
data = tool_result.input  # 已经是 dict，可直接使用
print(json.dumps(data, ensure_ascii=False, indent=2))

• → Tool Schema· 工具定义
• → Function Calling· 函数调用