结构化输出

结构化输出确保模型生成的响应符合你定义的 JSON schema。这对于需要以编程方式解析模型输出的可靠应用至关重要。

JSON 模式

最简单的方式是通过 response_format 请求 JSON 输出：

from openai import OpenAI

client = OpenAI(
    base_url="https://openapi.linkwo.ai/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that responds in JSON."},
        {"role": "user", "content": "List 3 programming languages with their use cases."}
    ],
    response_format={"type": "json_object"}
)

import json
data = json.loads(response.choices[0].message.content)
print(data)

重要： 使用 json_object 模式时，请在 system 或 user 消息中包含输出 JSON 的指令，否则模型可能返回空内容。

JSON Schema

如需更严格的控制，可指定模型必须遵循的 JSON schema：

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Extract the name, age, and skills from: John is a 30-year-old Python developer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "skills": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "age", "skills"],
                "additionalProperties": False
            }
        }
    }
)

响应将始终是符合该 schema 的有效 JSON：

{
  "name": "John",
  "age": 30,
  "skills": ["Python"]
}

使用 Pydantic（Python）

借助 OpenAI Python SDK，你可以直接使用 Pydantic 模型：

from pydantic import BaseModel

class PersonInfo(BaseModel):
    name: str
    age: int
    skills: list[str]

response = client.beta.chat.completions.parse(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Extract: John is a 30-year-old Python developer."}
    ],
    response_format=PersonInfo
)

person = response.choices[0].message.parsed
print(f"{person.name}, age {person.age}, skills: {person.skills}")

Schema 定义规则

定义严格 JSON schema 时：

所有字段都必须列入 required
对每个 object 设置 additionalProperties: false
使用受支持的类型：string、number、integer、boolean、array、object
按需嵌套 object 和 array
对受限的字符串取值使用 enum

常见使用场景

使用场景	schema 示例
数据抽取	从非结构化文本中抽取实体
分类	用标签和置信度对输入分类
代码生成	生成结构化的代码配置
API 输入	为下游 API 生成合法的 JSON

错误处理

当模型无法针对给定 schema 生成合法输出时，可能返回 refusal：

message = response.choices[0].message
if message.refusal:
    print(f"Model refused: {message.refusal}")
else:
    data = json.loads(message.content)

支持的模型

基于 JSON schema 的结构化输出在大多数模型上可用。兼容性详情请查阅模型概览中的各模型页面。