​
使用场景

Structured Outputs 功能使得模型能够生成符合您提供的 JSON Schema 的响应，让生成结果更加可控，易于解析。这一功能既可以方便后续逻辑的解析和处理，也有利于将结果集成到业务系统中，适用于各种自动化和数据处理场景。

​
支持的模型

以下模型支持结构化输出：

  • deepseek/deepseek-r1-0528
  • deepseek/deepseek-r1-distill-qwen-32b
  • deepseek/deepseek-r1-distill-qwen-14b
  • qwen/qwen-2.5-72b-instruct
  • qwen/qwen2.5-32b-instruct
  • qwen/qwen2.5-7b-instruct
  • thudm/glm-4-32b-0414
  • minimaxai/minimax-m1-80k
  • baidu/ernie-4.5-300b-a47b-paddle

​
使用方法

在请求中添加以下信息：

  • 设置参数：通过response_format参数指定您定义的 JSON Schema。
  • 提示词指引：在提示词中指引模型进行结构化输出。

​
使用示例

下文提供了完整的 Python 代码示例，演示如何使用 Structured Outputs 功能生成符合您提供的 JSON Schema 的 JSON 响应。

​
1. 初始化客户端

您需要使用您的PPIO 派欧云 API 密钥初始化客户端。

from openai import OpenAI

client = OpenAI(
    base_url="https://api.ppinfra.com/v3/openai",
    api_key="<Your API Key>",
)

model = "qwen/qwen-2.5-72b-instruct"

​
2. 定义 JSON Schema

您需要定义 JSON Schema。以下示例创建了一个从用户输入中提取费用信息的 JSON Schema。

# 定义用于费用跟踪的系统提示。
system_prompt = """You are an expense tracking assistant. 
Extract expense information from the user's input and format it according to the provided schema."""

# 定义用于结构化响应的 JSON Schema。
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "expense_tracking_schema",
        "schema": {
            "type": "object",
            "properties": {
                "expenses": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {
                                "type": "string",
                                "description": "Description of the expense"
                            },
                            "amount": {
                                "type": "number",
                                "description": "Amount spent in dollars"
                            },
                            "date": {
                                "type": "string",
                                "description": "When the expense occurred"
                            },
                            "category": {
                                "type": "string",
                                "description": "Category of expense (e.g., food, office, travel)"
                            }
                        },
                        "required": [
                            "description",
                            "amount"
                        ]
                    }
                },
                "total": {
                    "type": "number",
                    "description": "Total amount of all expenses"
                }
            },
            "required": [
                "expenses",
                "total"
            ],
        },
    },
}

​
3. 发起 API 请求

创建 API 请求。此请求包括 response_format 参数，指定了上一步中定义的 JSON schema。

chat_completion = client.chat.completions.create(
    model=model,
    messages=[
        {
            "role": "system",
            "content": system_prompt,
        },
        {
            "role": "user",
            "content": """I spent $120 on dinner at an Italian restaurant last Friday with my colleagues.
Also bought office supplies for $45 on Monday.""",
        },
    ],
    max_tokens=1024,
    temperature=0.8,
    stream=False,
    response_format=response_format,
)

response_content = chat_completion.choices[0].message.content

# 解析并美化 JSON
try:
    json_response = json.loads(response_content)
    prettified_json = json.dumps(json_response, indent=2)
    print(prettified_json)
except json.JSONDecodeError:
    print("Could not parse response as JSON. Raw response:")
    print(response_content)

输出：

{
  "expenses": [
    {
      "date": "2023-03-17",
      "description": "Dinner at Italian restaurant",
      "amount": 120,
      "category": "Food & Dining"
    },
    {
      "date": "2023-03-13",
      "description": "Office supplies",
      "amount": 45,
      "category": "Office Supplies"
    }
  ],
  "total": 165
}

​
完整代码

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.ppinfra.com/v3/openai",
    api_key="<Your API Key>",
)

model = "qwen/qwen-2.5-72b-instruct"

# 使用 JSON Schema 进行结构化输出的示例
# 此示例创建了一个用于提取费用信息的 schema

# 定义用于费用跟踪的系统提示
system_prompt = """You are an expense tracking assistant. 
Extract expense information from the user's input and format it according to the provided schema."""

# 定义用于结构化响应的 JSON schema
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "expense_tracking_schema",
        "schema": {
            "type": "object",
            "properties": {
                "expenses": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {
                                "type": "string",
                                "description": "Description of the expense"
                            },
                            "amount": {
                                "type": "number",
                                "description": "Amount spent in dollars"
                            },
                            "date": {
                                "type": "string",
                                "description": "When the expense occurred"
                            },
                            "category": {
                                "type": "string",
                                "description": "Category of expense (e.g., food, office, travel)"
                            }
                        },
                        "required": [
                            "description",
                            "amount"
                        ]
                    }
                },
                "total": {
                    "type": "number",
                    "description": "Total amount of all expenses"
                }
            },
            "required": [
                "expenses",
                "total"
            ],
        },
    },
}

chat_completion = client.chat.completions.create(
    model=model,
    messages=[
        {
            "role": "system",
            "content": system_prompt,
        },
        {
            "role": "user",
            "content": """I spent $120 on dinner at an Italian restaurant last Friday with my colleagues.
Also bought office supplies for $45 on Monday.""",
        },
    ],
    max_tokens=1024,
    temperature=0.8,
    stream=False,
    response_format=response_format,
)

response_content = chat_completion.choices[0].message.content

# 解析并美化 JSON
try:
    json_response = json.loads(response_content)
    prettified_json = json.dumps(json_response, indent=2)
    print(prettified_json)
except json.JSONDecodeError:
    print("Could not parse response as JSON. Raw response:")
    print(response_content)