Structured Output 实战：JSON Schema 约束 LLM 输出格式完全指南

结论先行：为什么你需要一个「听话」的 LLM

作为在 AI 工程化领域摸爬滚打三年的开发者，我见过太多团队被 LLM「自由发挥」折磨得苦不堪言——让模型返回一个商品信息，它可能给你吐出一段自然语言描述；让它输出用户画像，结果里面混了个表情包。这些看似「智能」的随机性，在生产环境中就是噩梦。

Structured Output（结构化输出）就是来解决这个问题的。通过 JSON Schema 约束 LLM 的输出格式，你能让模型像受过训练的程序员一样，100% 按照你的数据模板返回结果。我实测用 HolySheep API 接入 GPT-4.1，延迟稳定在 120-180ms，价格比官方省 85%+，人民币直接充值不用操心外汇问题。

本文核心结论：

• 首选方案：使用支持 response_format 参数的 API（如 HolySheep 的 OpenAI 兼容接口），直接传入 JSON Schema
• 备选方案：Few-shot Prompting + 输出解析正则校验
• HolySheep 核心优势：¥1=$1 汇率 + 国内 <50ms 延迟 + 微信/支付宝充值 + 注册送免费额度

HolySheep API vs 官方 OpenAI vs Anthropic 横向对比

对比维度	HolySheep AI	OpenAI 官方	Anthropic 官方
汇率	¥1 = $1（无损）	¥7.3 = $1（1:1充值）	¥7.3 = $1
充值方式	微信/支付宝/银行卡	国际信用卡/虚拟卡	国际信用卡
国内延迟	<50ms	200-500ms+	300-600ms+
GPT-4.1 Output	$8/MTok	$8/MTok	不提供
Claude Sonnet 4.5 Output	$15/MTok	不提供	$15/MTok
Gemini 2.5 Flash Output	$2.50/MTok	不提供	不提供
DeepSeek V3.2 Output	$0.42/MTok	不提供	不提供
适合人群	国内开发者/企业	有海外支付能力者	有海外支付能力者

👉 立即注册 HolySheep AI，获取首月赠额度

一、Structured Output 的本质：为什么 JSON Schema 有效

很多人以为 Structured Output 就是「让模型输出 JSON」，这是一个致命误解。LLM 本质上是在做概率补全，直接要求它输出 JSON 时，它可能会：

• 在字符串中混入转义字符
• 输出截断导致格式不完整
• 对 Schema 的 enum 约束视而不见

Structured Output 的正确理解：通过 API 层面的约束机制，强制模型在生成阶段就按照指定 Schema 构建输出，而非事后用正则解析。HolySheep API 完全兼容 OpenAI 的 response_format 参数，这意味着你可以直接使用官方文档中描述的所有高级特性。

二、实战代码：从基础到高阶

2.1 基础场景：商品信息提取

import requests
import json

HolySheep API 配置
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"

定义 JSON Schema - 约束 LLM 输出格式
product_schema = {
    "type": "object",
    "properties": {
        "product_name": {"type": "string", "description": "商品全称"},
        "price": {"type": "number", "description": "价格，单位元"},
        "currency": {"type": "string", "enum": ["CNY", "USD", "JPY"]},
        "in_stock": {"type": "boolean"},
        "category": {"type": "string", "enum": ["电子产品", "服装", "食品", "家居", "其他"]},
        "tags": {"type": "array", "items": {"type": "string"}, "maxItems": 5}
    },
    "required": ["product_name", "price", "currency", "in_stock", "category"]
}

def extract_product_info(product_description: str) -> dict:
    """从商品描述中提取结构化信息"""
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "gpt-4.1",
            "messages": [
                {
                    "role": "system",
                    "content": "你是一个专业的商品信息提取助手。用户会给你商品描述，你需要严格按照 JSON Schema 提取信息。"
                },
                {
                    "role": "user", 
                    "content": f"请提取以下商品的信息：{product_description}"
                }
            ],
            "response_format": {
                "type": "json_schema",
                "json_schema": product_schema
            },
            "temperature": 0  # 设为0提高格式稳定性
        },
        timeout=30
    )
    
    result = response.json()
    
    # HolySheep 返回格式与 OpenAI 完全兼容
    return json.loads(result["choices"][0]["message"]["content"])

测试用例
product_desc = "iPhone 15 Pro Max 256GB 钛金属原色款，售价￥9999，有现货，属于高端智能手机品类，适合商务人士使用，标签：5G、A17芯片、钛金属"

result = extract_product_info(product_desc)
print(json.dumps(result, ensure_ascii=False, indent=2))

输出示例：

{
  "product_name": "iPhone 15 Pro Max 256GB 钛金属原色",
  "price": 9999,
  "currency": "CNY",
  "in_stock": true,
  "category": "电子产品",
  "tags": ["5G", "A17芯片", "钛金属"]
}

我第一次用 Structured Output 时，用的是 OpenAI 官方 API，每次请求要等 400-600ms，而且因为支付问题经常充值失败。换用 HolySheep 后，延迟直接降到 120ms 左右，微信扫码就能充值，效率提升肉眼可见。

2.2 高阶场景：多层级嵌套数据结构

import requests
import json
from typing import List, Optional

复杂的用户画像 Schema
user_profile_schema = {
    "type": "object",
    "properties": {
        "basic_info": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer", "minimum": 0, "maximum": 150},
                "gender": {"type": "string", "enum": ["男", "女", "未知"]},
                "location": {"type": "string"}
            },
            "required": ["name", "age", "gender"]
        },
        "preferences": {
            "type": "object",
            "properties": {
                "favorite_categories": {
                    "type": "array",
                    "items": {"type": "string"}
                },
                "price_range": {
                    "type": "object",
                    "properties": {
                        "min": {"type": "number"},
                        "max": {"type": "number"},
                        "currency": {"type": "string"}
                    }
                },
                "shopping_frequency": {
                    "type": "string",
                    "enum": ["每日", "每周", "每月", "偶尔", "很少"]
                }
            }
        },
        "behavior_summary": {"type": "string"},
        "risk_tags": {
            "type": "array",
            "items": {"type": "string"}
        }
    },
    "required": ["basic_info", "preferences", "behavior_summary"]
}

def analyze_user_profile(raw_data: str) -> dict:
    """分析用户数据生成画像"""
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "gpt-4.1",
            "messages": [
                {
                    "role": "system",
                    "content": "你是用户画像分析专家。根据用户行为数据生成精准画像，严格遵循 Schema 格式。"
                },
                {
                    "role": "user",
                    "content": f"分析以下用户数据：{raw_data}"
                }
            ],
            "response_format": {
                "type": "json_schema", 
                "json_schema": user_profile_schema
            },
            "max_tokens": 2048,
            "temperature": 0.1
        }
    )
    
    return json.loads(response.json()["choices"][0]["message"]["content"])

模拟用户行为数据
user_data = """
用户A，男性，28岁，北京朝阳区。周六在京东买了2件数码配件（蓝牙耳机199元、充电宝89元），
平时喜欢关注手机和电脑品类，每月购物3-4次，价格敏感度中等偏上。曾在平台购买过
虚假宣传商品，已被标记为维权用户。
"""

profile = analyze_user_profile(user_data)
print(json.dumps(profile, ensure_ascii=False, indent=2))

2.3 工程化封装：带重试和降级的生产级方案

import requests
import json
import time
from functools import wraps
from typing import Callable, Any, Optional

class StructuredOutputError(Exception):
    """结构化输出异常"""
    pass

def structured_output_retry(max_retries: int = 3, delay: float = 1.0):
    """重试装饰器 - 处理 LLM 格式不稳定问题"""
    def decorator(func: Callable) -> Callable:
        @wraps(func)
        def wrapper(*args, **kwargs) -> Any:
            last_error = None
            
            for attempt in range(max_retries):
                try:
                    result = func(*args, **kwargs)
                    
                    # 验证返回格式
                    if not isinstance(result, dict):
                        raise StructuredOutputError(f"期望 dict 类型，得到 {type(result)}")
                    
                    return result
                    
                except (requests.RequestException, json.JSONDecodeError, 
                        StructuredOutputError) as e:
                    last_error = e
                    if attempt < max_retries - 1:
                        time.sleep(delay * (attempt + 1))  # 指数退避
                        continue
                        
            raise StructuredOutputError(
                f"重试 {max_retries} 次后仍失败: {last_error}"
            )
        return wrapper
    return decorator

class HolySheepStructuredOutput:
    """HolySheep 结构化输出封装类"""
    
    def __init__(self, api_key: str, base_url: str = "https://api.holysheep.ai/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.default_model = "gpt-4.1"
    
    def generate(
        self,
        prompt: str,
        schema: dict,
        model: Optional[str] = None,
        temperature: float = 0,
        max_tokens: int = 4096
    ) -> dict:
        """生成结构化输出"""
        
        response = requests.post(
            f"{self.base_url}/chat/completions",
            headers={
                "Authorization": f"Bearer {self.api_key}",
                "Content-Type": "application/json"
            },
            json={
                "model": model or self.default_model,
                "messages": [{"role": "user", "content": prompt}],
                "response_format": {
                    "type": "json_schema",
                    "json_schema": schema
                },
                "temperature": temperature,
                "max_tokens": max_tokens
            },
            timeout=30
        )
        
        response.raise_for_status()
        return json.loads(response.json()["choices"][0]["message"]["content"])

使用示例
client = HolySheepStructuredOutput("YOUR_HOLYSHEEP_API_KEY")

order_schema = {
    "type": "object",
    "properties": {
        "order_id": {"type": "string"},
        "status": {"type": "string", "enum": ["待支付", "已支付", "已发货", "已完成", "已取消"]},
        "total_amount": {"type": "number"},
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "product_id": {"type": "string"},
                    "quantity": {"type": "integer", "minimum": 1},
                    "subtotal": {"type": "number"}
                }
            }
        }
    },
    "required": ["order_id", "status", "total_amount", "items"]
}

生产环境调用
try:
    result = client.generate(
        prompt="从以下文本提取订单信息：订单号ORD20240115，用户购买了一件T恤（ID:P001，数量2件，小计199元）和一条牛仔裤（ID:P002，数量1件，小计299元），实付498元，状态已支付",
        schema=order_schema
    )
    print(json.dumps(result, ensure_ascii=False, indent=2))
except StructuredOutputError as e:
    print(f"结构化输出失败: {e}")

常见报错排查

错误 1：Invalid schema format - Schema 语法错误

# ❌ 错误写法 - 缺少外层 type 字段
invalid_schema = {
    "product_name": {"type": "string"},  # 直接定义了属性，缺少外层包装
    "price": {"type": "number"}
}

✅ 正确写法 - 完整的 JSON Schema 结构
correct_schema = {
    "type": "object",
    "properties": {
        "product_name": {"type": "string"},
        "price": {"type": "number"}
    },
    "required": ["product_name", "price"]
}

❌ 错误写法 - enum 使用数组而非数组形式
wrong_enum = {"type": "string", "enum": "男|女"}  # 字符串形式

✅ 正确写法 - enum 必须是数组
correct_enum = {"type": "string", "enum": ["男", "女"]}

排查步骤：使用 JSON Schema 在线验证工具（如 JSON Schema Validator）检查 Schema 语法，确保每个对象都有 type 字段。

错误 2：Response format not supported - 模型不支持该格式

# ❌ 错误 - 使用了不支持 Structured Output 的模型
response = requests.post(
    f"{BASE_URL}/chat/completions",
    json={
        "model": "gpt-3.5-turbo",  # GPT-3.5 不支持 response_format 参数
        "messages": [...],
        "response_format": {...}
    }
)
返回：{"error": {"message": "model does not support response_format"}}

✅ 解决方案 1 - 换用支持的模型
supported_models = ["gpt-4.1", "gpt-4o", "gpt-4o-mini", "claude-sonnet-4.5"]

✅ 解决方案 2 - 如果必须用 GPT-3.5，使用传统方式
def gpt35_with_few_shot(prompt: str, schema: dict) -> dict:
    """GPT-3.5 通过 Few-shot 方式约束输出"""
    
    schema_str = json.dumps(schema, ensure_ascii=False)
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        json={
            "model": "gpt-3.5-turbo",
            "messages": [
                {
                    "role": "system",
                    "content": f"""你是一个 JSON 生成器。请严格按照以下 Schema 生成 JSON：

{schema_str}


要求：
1. 只输出 JSON，不要有任何解释或 markdown 格式
2. 确保所有 required 字段都存在
3. 类型必须完全匹配"""
                },
                {"role": "user", "content": prompt}
            ],
            "temperature": 0
        }
    )
    
    # 解析并验证输出
    raw_output = response.json()["choices"][0]["message"]["content"]
    return json.loads(raw_output.strip("`json").strip())

错误 3：JSON decode error - 输出解析失败

# ❌ 常见原因 1 - 输出包含 markdown 代码块
raw_output = """
{"product_name": "iPhone", "price": 9999}

"""
json.loads() 会失败

✅ 解决方案 - 清理 markdown 格式
import re

def clean_json_output(raw: str) -> dict:
    """清理 LLM 输出的各种格式问题"""
    cleaned = raw.strip()
    
    # 移除 markdown 代码块标记
    cleaned = re.sub(r'^```json\s*', '', cleaned, flags=re.MULTILINE)
    cleaned = re.sub(r'^```\s*$', '', cleaned, flags=re.MULTILINE)
    
    # 移除前后空白
    cleaned = cleaned.strip()
    
    return json.loads(cleaned)

❌ 常见原因 2 - 输出被截断（max_tokens 太小）
response = requests.post(
    f"{BASE_URL}/chat/completions",
    json={
        "model": "gpt-4.1",
        "messages": [...],
        "response_format": {"type": "json_schema", "json_schema": large_schema},
        "max_tokens": 512  # 对于复杂 Schema 可能不够
    }
)
返回的 JSON 可能被截断，导致语法错误

✅ 解决方案 - 根据 Schema 复杂度估算 max_tokens
def estimate_max_tokens(schema: dict) -> int:
    """估算所需 max_tokens"""
    schema_str = json.dumps(schema)
    base_tokens = len(schema_str) // 4  # 粗略估算
    response_tokens = 1500  # 预期响应长度
    return max(512, base_tokens + response_tokens)

错误 4：Rate limit exceeded - 请求频率超限

# ❌ 快速连续请求导致限流
for item in items:
    result = client.generate(prompt=item, schema=schema)
可能触发 429 错误

✅ 解决方案 - 实现请求限流
import time
from collections import deque

class RateLimiter:
    """简单的令牌桶限流器"""
    
    def __init__(self, max_requests: int, time_window: float):
        self.max_requests = max_requests
        self.time_window = time_window
        self.requests = deque()
    
    def wait_if_needed(self):
        now = time.time()
        
        # 清理过期记录
        while self.requests and self.requests[0] < now - self.time_window:
            self.requests.popleft()
        
        if len(self.requests) >= self.max_requests:
            sleep_time = self.time_window - (now - self.requests[0])
            if sleep_time > 0:
                time.sleep(sleep_time)
                self.wait_if_needed()
        
        self.requests.append(time.time())

使用限流器
limiter = RateLimiter(max_requests=50, time_window=60)  # 每分钟50次

for item in items:
    limiter.wait_if_needed()
    result = client.generate(prompt=item, schema=schema)

错误 5：API key authentication failed - 认证失败

# ❌ 常见错误 - Key 格式错误或拼写错误
headers = {
    "Authorization": f"Bearer {API_KEY}",  # Bearer 拼写错误：Bearer
    "Content-Type": "application/json"
}

❌ 常见错误 - 传递了错误的 Header 名称
headers = {
    "api-key": f"Bearer {API_KEY}",  # 应该是 Authorization
}

✅ 正确写法 - 确认 Key 格式和 Header 名称
API_KEY = "YOUR_HOLYSHEEP_API_KEY"  # 从
相关资源
📚 AI API 技术文章库
💰 查看价格
📖 开发者文档
🚀 免费注册
相关文章
OpenAI Responses API 完整指南：从 Chat Completions 无缝迁移实战
AI API 负载测试实战：Locust 与 k6 压测大模型服务完整指南
AI 图像编辑 API 接入教程：inpainting/outpainting 实战完全指南