Python AI结构化输出实战：让LLM稳定返回JSON的5个核心模式

AI结构化输出：为什么LLM的"自由文本"是生产环境的噩梦

LLM默认输出自由文本，你让它返回JSON，它给你夹带解释文字；你要求整数，它返回字符串"42"；你定义了Schema，它随机丢字段。结构化输出（Structured Output）就是让LLM严格按照预定义的Schema返回数据——这是AI从"聊天玩具"走向"生产系统"的关键一步。2026年，OpenAI已原生支持Structured Output、Instructor库实现自动重试、Outlines通过约束解码保证100%格式合规。

本文将从5个核心模式出发，带你完成Pydantic Schema定义→Function Calling→Instructor重试→约束解码→多模型适配的全链路实战。

---

核心概念

概念	说明
Structured Output	LLM按照预定义Schema输出结构化数据（如JSON）
Pydantic Model	Python数据验证库，用类型注解定义输出Schema
Function Calling	OpenAI API的函数调用机制，约束输出格式
Instructor	基于Pydantic的LLM结构化输出库，支持自动重试
Constrained Decoding	约束解码，在token级别限制输出必须符合Schema
JSON Schema	描述JSON数据结构的规范，是结构化输出的基础
Output Validation	对LLM输出进行验证，确保类型和字段完整
Multi-Model Adapter	跨不同LLM提供商统一结构化输出的适配层

---

问题分析：LLM非结构化输出的5类痛点

1. 格式不稳定：同一个Prompt，LLM有时返回JSON，有时返回Markdown包裹的JSON
2. 类型不可靠：要求返回integer，LLM可能返回字符串"42"或浮点数42.0
3. 字段缺失：Schema定义了10个字段，LLM随机省略2-3个
4. 幻觉内容：LLM在JSON值中夹带解释性文字，如"price": "约100元左右"
5. 解析崩溃：生产环境中JSON解析失败率高达5-15%，每次崩溃都需要人工介入

---

分步实操：5个AI结构化输出核心模式

模式1：Pydantic Schema定义 + 基础结构化输出

pip install pydantic==2.11 openai==1.82

from pydantic import BaseModel, Field
from openai import OpenAI
import json

class ProductInfo(BaseModel):
    name: str = Field(description="产品名称")
    price: float = Field(description="产品价格，单位：元")
    category: str = Field(description="产品分类")
    in_stock: bool = Field(description="是否有库存")
    tags: list[str] = Field(description="产品标签列表")

client = OpenAI()

# 方式1：使用response_format参数（OpenAI原生结构化输出）
response = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "你是产品信息提取助手，从用户描述中提取结构化产品信息。"},
        {"role": "user", "content": "这款MacBook Pro 14寸售价14999元，属于笔记本电脑分类，目前有库存，标签是苹果、高端、生产力工具"},
    ],
    response_format=ProductInfo,
)

product = response.choices[0].message.parsed
print(f"产品: {product.name}")
print(f"价格: {product.price}")
print(f"分类: {product.category}")
print(f"库存: {product.in_stock}")
print(f"标签: {product.tags}")
print(f"类型验证: price是{type(product.price).__name__}")

# 方式2：手动JSON Schema + 解析验证
class OrderItem(BaseModel):
    item_name: str = Field(description="商品名称")
    quantity: int = Field(gt=0, description="购买数量")
    unit_price: float = Field(ge=0, description="单价")

class CustomerOrder(BaseModel):
    order_id: str = Field(description="订单编号")
    customer_name: str = Field(description="客户姓名")
    items: list[OrderItem] = Field(description="订单商品列表")
    total_amount: float = Field(ge=0, description="订单总金额")

response2 = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "提取订单信息，严格返回JSON。"},
        {"role": "user", "content": "订单ORD-20260621，客户张三，买了2个键盘每个299元，1个显示器每个2999元，总计3597元"},
    ],
    response_format={"type": "json_object"},
)

raw_json = json.loads(response2.choices[0].message.content)
order = CustomerOrder.model_validate(raw_json)
print(f"\n订单: {order.order_id}, 客户: {order.customer_name}")
for item in order.items:
    print(f"  {item.item_name} x{item.quantity} @ {item.unit_price}")
print(f"总计: {order.total_amount}")

模式2：OpenAI Function Calling结构化输出

from pydantic import BaseModel, Field
from openai import OpenAI
import json

class WeatherQuery(BaseModel):
    city: str = Field(description="城市名称")
    temperature: float = Field(description="温度，摄氏度")
    condition: str = Field(description="天气状况：晴/多云/雨/雪")
    humidity: int = Field(ge=0, le=100, description="湿度百分比")
    wind_speed: float = Field(ge=0, description="风速，km/h")

class TravelPlan(BaseModel):
    destination: str = Field(description="目的地")
    days: int = Field(gt=0, description="旅行天数")
    budget: float = Field(ge=0, description="预算，元")
    activities: list[str] = Field(description="推荐活动列表")
    weather_advice: str = Field(description="天气相关建议")

client = OpenAI()

# 使用Function Calling强制结构化输出
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_travel_plan",
            "description": "生成旅行计划",
            "parameters": TravelPlan.model_json_schema(),
        },
    },
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取天气信息",
            "parameters": WeatherQuery.model_json_schema(),
        },
    },
]

response = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "你是旅行规划助手，根据用户需求生成旅行计划和天气信息。"},
        {"role": "user", "content": "我计划去成都玩3天，预算5000元"},
    ],
    tools=tools,
    tool_choice="auto",
)

for tool_call in response.choices[0].message.tool_calls:
    func_name = tool_call.function.name
    func_args = json.loads(tool_call.function.arguments)

    if func_name == "get_travel_plan":
        plan = TravelPlan.model_validate(func_args)
        print(f"目的地: {plan.destination}")
        print(f"天数: {plan.days}")
        print(f"预算: {plan.budget}")
        print(f"活动: {', '.join(plan.activities)}")
        print(f"天气建议: {plan.weather_advice}")
    elif func_name == "get_weather":
        weather = WeatherQuery.model_validate(func_args)
        print(f"\n{weather.city}: {weather.temperature}°C, {weather.condition}, 湿度{weather.humidity}%, 风速{weather.wind_speed}km/h")

模式3：Instructor库实现自动重试结构化输出

pip install instructor==1.7 pydantic==2.11

import instructor
from pydantic import BaseModel, Field
from openai import OpenAI

class SentimentResult(BaseModel):
    text: str = Field(description="分析的文本")
    sentiment: str = Field(description="情感倾向：positive/negative/neutral")
    confidence: float = Field(ge=0, le=1, description="置信度0-1")
    keywords: list[str] = Field(description="关键词列表")

class ArticleSummary(BaseModel):
    title: str = Field(description="文章标题")
    summary: str = Field(min_length=50, max_length=200, description="50-200字摘要")
    key_points: list[str] = Field(min_length=2, max_length=5, description="2-5个要点")
    reading_time_minutes: int = Field(gt=0, description="预计阅读时间（分钟）")
    difficulty: str = Field(description="难度：beginner/intermediate/advanced")

# 使用instructor包装OpenAI客户端
client = instructor.from_openai(OpenAI())

# 自动重试：如果输出不符合Schema，instructor会自动重试
sentiment = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "你是情感分析专家。"},
        {"role": "user", "content": "这个产品真的太好用了，界面简洁，功能强大，强烈推荐！"},
    ],
    response_model=SentimentResult,
    max_retries=3,
)

print(f"情感: {sentiment.sentiment}")
print(f"置信度: {sentiment.confidence}")
print(f"关键词: {', '.join(sentiment.keywords)}")

# 嵌套模型 + 严格验证
summary = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "你是文章摘要生成器。"},
        {"role": "user", "content": "Python 3.13在2024年10月正式发布，带来了自由线程模式（PEP 703）、改进的交互式解释器、更佳的错误提示等重大更新。自由线程模式允许Python在不使用GIL的情况下运行，这对多线程性能提升显著。新的REPL支持多行编辑和语法高亮，大幅提升了开发体验。"},
    ],
    response_model=ArticleSummary,
    max_retries=3,
)

print(f"\n标题: {summary.title}")
print(f"摘要: {summary.summary}")
for i, point in enumerate(summary.key_points, 1):
    print(f"  要点{i}: {point}")
print(f"阅读时间: {summary.reading_time_minutes}分钟")
print(f"难度: {summary.difficulty}")

模式4：Outlines/结构化生成（约束解码）

pip install outlines==0.1 pydantic==2.11 transformers

import outlines
from pydantic import BaseModel, Field
import json

class EntityExtraction(BaseModel):
    person_names: list[str] = Field(description="人名列表")
    organizations: list[str] = Field(description="组织机构列表")
    locations: list[str] = Field(description="地点列表")
    dates: list[str] = Field(description="日期列表")

class CodeAnalysis(BaseModel):
    language: str = Field(description="编程语言")
    complexity: str = Field(description="复杂度：low/medium/high")
    functions: list[str] = Field(description="函数名列表")
    imports: list[str] = Field(description="导入模块列表")
    issues: list[str] = Field(description="潜在问题列表")

# 使用Outlines进行约束解码（本地模型）
# 注意：首次运行会下载模型，约1.5GB
model = outlines.models.transformers("microsoft/Phi-3-mini-4k-instruct")

# 方式1：基于JSON Schema的约束生成
generator = outlines.generate.json(model, EntityExtraction.model_json_schema())

text = "2026年3月15日，张三在北京参加了华为开发者大会，与李四讨论了AI技术在深圳的应用。"
result = generator(text)
print(f"人名: {result['person_names']}")
print(f"组织: {result['organizations']}")
print(f"地点: {result['locations']}")
print(f"日期: {result['dates']}")

# 方式2：基于正则表达式的约束生成
# 确保输出格式100%合规
phone_generator = outlines.generate.regex(model, r"\d{3}-\d{4}-\d{4}")
phone = phone_generator("我的电话号码是")
print(f"\n电话号码: {phone}")

# 方式3：基于Choice的约束生成（分类任务）
choice_generator = outlines.generate.choice(model, ["positive", "negative", "neutral"])
sentiment = choice_generator("这个产品非常好用，我非常满意！")
print(f"情感分类: {sentiment}")

# 方式4：基于Pydantic Model的约束生成
code_generator = outlines.generate.json(model, CodeAnalysis.model_json_schema())
code_text = """
import os
import sys
from typing import List

def process_data(items: List[str]) -> dict:
    result = {}
    for item in items:
        result[item] = len(item)
    return result

def main():
    data = process_data(["hello", "world"])
    print(data)
"""
code_result = code_generator(code_text)
print(f"\n语言: {code_result['language']}")
print(f"复杂度: {code_result['complexity']}")
print(f"函数: {code_result['functions']}")

模式5：多模型结构化输出适配器

from pydantic import BaseModel, Field
from openai import OpenAI
import anthropic
import google.generativeai as genai
import json
from abc import ABC, abstractmethod
from typing import TypeVar, Type

T = TypeVar("T", bound=BaseModel)

class BookRecommendation(BaseModel):
    title: str = Field(description="书名")
    author: str = Field(description="作者")
    genre: str = Field(description="类型")
    rating: float = Field(ge=0, le=5, description="评分0-5")
    reason: str = Field(description="推荐理由")

class StructuredOutputAdapter(ABC):
    """多模型结构化输出适配器基类"""

    @abstractmethod
    def generate(self, prompt: str, response_model: Type[T]) -> T:
        pass

class OpenAIAdapter(StructuredOutputAdapter):
    def __init__(self, api_key: str, model: str = "gpt-4o-2024-08-06"):
        self.client = OpenAI(api_key=api_key)
        self.model = model

    def generate(self, prompt: str, response_model: Type[T]) -> T:
        response = self.client.beta.chat.completions.parse(
            model=self.model,
            messages=[
                {"role": "system", "content": f"严格按照Schema返回数据。"},
                {"role": "user", "content": prompt},
            ],
            response_format=response_model,
        )
        return response.choices[0].message.parsed

class AnthropicAdapter(StructuredOutputAdapter):
    def __init__(self, api_key: str, model: str = "claude-sonnet-4-20250514"):
        self.client = anthropic.Anthropic(api_key=api_key)
        self.model = model

    def generate(self, prompt: str, response_model: Type[T]) -> T:
        schema = response_model.model_json_schema()
        response = self.client.messages.create(
            model=self.model,
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}],
            tools=[{
                "name": "structured_output",
                "description": "返回结构化数据",
                "input_schema": schema,
            }],
            tool_choice={"type": "tool", "name": "structured_output"},
        )
        for block in response.content:
            if block.type == "tool_use":
                return response_model.model_validate(block.input)
        raise ValueError("No tool use in response")

class GeminiAdapter(StructuredOutputAdapter):
    def __init__(self, api_key: str, model: str = "gemini-2.0-flash"):
        genai.configure(api_key=api_key)
        self.model_name = model

    def generate(self, prompt: str, response_model: Type[T]) -> T:
        model = genai.GenerativeModel(
            self.model_name,
            generation_config={"response_mime_type": "application/json"},
        )
        schema_instructions = f"返回严格符合以下JSON Schema的数据：\n{json.dumps(response_model.model_json_schema(), ensure_ascii=False)}"
        response = model.generate_content(f"{schema_instructions}\n\n{prompt}")
        raw = json.loads(response.text)
        return response_model.model_validate(raw)

# 统一调用接口
def get_recommendation(adapter: StructuredOutputAdapter, query: str) -> BookRecommendation:
    return adapter.generate(query, BookRecommendation)

# 使用示例（需要配置对应API Key）
# openai_adapter = OpenAIAdapter(api_key="sk-xxx")
# result = get_recommendation(openai_adapter, "推荐一本关于AI的入门书籍")
# print(f"推荐: 《{result.title}》 by {result.author}, 评分{result.rating}")

# 通用验证层：无论使用哪个模型，最终都经过Pydantic验证
def safe_parse(raw_json: dict, model: Type[T]) -> T:
    """通用安全解析：验证 + 默认值填充"""
    try:
        return model.model_validate(raw_json)
    except Exception as e:
        print(f"验证失败: {e}")
        defaults = {}
        for field_name, field_info in model.model_fields.items():
            if field_info.is_required():
                raise ValueError(f"必填字段 {field_name} 缺失")
            defaults[field_name] = field_info.default
        return model.model_validate(defaults)

---

避坑指南

坑1：Pydantic字段缺少description

# ❌ 错误：没有description，LLM不知道该填什么
class BadModel(BaseModel):
    x1: str
    x2: float
    x3: list[str]

# ✅ 正确：每个字段都加description
class GoodModel(BaseModel):
    product_name: str = Field(description="产品全称")
    price: float = Field(description="价格，单位：人民币元")
    tags: list[str] = Field(description="产品标签，如'电子产品''促销'")

坑2：依赖LLM自动输出JSON而不设response_format

# ❌ 错误：只靠Prompt要求JSON，格式不稳定
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "请返回JSON格式的产品信息"}],
)

# ✅ 正确：显式设置response_format
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "请返回JSON格式的产品信息"}],
    response_format={"type": "json_object"},
)

坑3：忽略Pydantic验证错误

# ❌ 错误：直接json.loads不做验证
data = json.loads(response.choices[0].message.content)
price = data["price"]  # 可能是字符串"42.0"而非float

# ✅ 正确：使用Pydantic验证
from pydantic import ValidationError
try:
    product = ProductInfo.model_validate_json(response.choices[0].message.content)
    price = product.price  # 保证是float类型
except ValidationError as e:
    print(f"验证失败: {e}")

坑4：嵌套模型过深导致LLM输出混乱

# ❌ 错误：3层以上嵌套，LLM极易出错
class DeepNested(BaseModel):
    level1: "Level1Model"  # -> level2: Level2Model -> level3: Level3Model

# ✅ 正确：扁平化设计，最多2层嵌套
class OrderItem(BaseModel):
    name: str = Field(description="商品名")
    qty: int = Field(description="数量")

class Order(BaseModel):
    items: list[OrderItem] = Field(description="商品列表")  # 只嵌套1层
    total: float = Field(description="总价")

坑5：Function Calling中tool_choice设置不当

# ❌ 错误：tool_choice="auto"时LLM可能不调用函数
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    tools=tools,
    tool_choice="auto",  # LLM可能直接回复文本
)

# ✅ 正确：强制调用特定函数
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_travel_plan"}},
)

---

报错排查

序号	报错信息	原因	解决方法
1	ValidationError: missing field	LLM输出缺少必填字段	使用Field(default=...)或增加max_retries
2	json.decoder.JSONDecodeError	LLM输出不是合法JSON	设置response_format={"type": "json_object"}
3	ValidationError: value is not a valid float	LLM返回字符串而非数字	Pydantic自动转换或使用Field(coerce_numbers=True)
4	InstructorRetryError: max retries exceeded	重试N次仍不符合Schema	简化Schema或优化Prompt描述
5	TypeError: 'NoneType' object is not subscriptable	LLM返回空内容	检查API Key额度和模型可用性
6	ValidationError: list should have at least N items	列表字段元素不足	使用Field(min_length=N)并优化Prompt
7	StructuredOutputError: schema too complex	Schema过于复杂	扁平化模型，减少嵌套层级
8	RateLimitError	API调用频率超限	添加退避重试或降低并发
9	ValidationError: string too long/short	字符串长度不符合约束	调整max_length/min_length或优化Prompt
10	ToolCallNotFoundError	LLM未调用tool	设置tool_choice强制调用

---

进阶优化

1. 流式结构化输出：使用instructor的create_partial方法实现流式解析，边生成边验证
2. Schema缓存：对相同Schema的请求缓存JSON Schema，减少重复序列化开销
3. 多Schema路由：根据用户意图动态选择不同的Pydantic Model，实现灵活的结构化输出
4. 输出后处理Pipeline：Pydantic验证→业务规则校验→默认值填充→日志记录，形成完整的数据质量保障链
5. A/B测试Schema：对同一任务使用不同粒度的Schema，对比LLM输出质量和Token消耗

---

对比分析

维度	OpenAI Structured Output	Instructor	Outlines	LMQL	Guidance
格式保证	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
自动重试	❌	⭐⭐⭐⭐⭐	❌	⭐⭐⭐	⭐⭐⭐
本地模型支持	❌	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
多模型适配	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐
学习曲线	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐
类型安全	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐

---

总结：AI结构化输出是从"聊天式AI"到"生产级AI"的必经之路。Pydantic Schema→Function Calling→Instructor重试→约束解码→多模型适配五位一体，是2026年Python AI结构化输出的最佳实践。核心原则：Schema即契约、验证即保障、重试即容错。

---

在线工具推荐

• JSON格式化：/zh-CN/json/format
• Hash计算：/zh-CN/encode/hash
• cURL转代码：/zh-CN/dev/curl-to-code